-## Collision avoidance
-The Arm has no proximity awareness of its own, so maintaining safe distance is essential. If obstacles or people are in the path of operation, the Arm has no collision avoidance capability to prevent contact. Safe Arm operation depends on the Operator and/or safety observers maintaining situational awareness and halting operations if the Arm is at risk of contacting objects or people.
+## Collision avoidance
+
+The Arm has no proximity awareness of its own, so maintaining safe distance is essential. If obstacles or people are in the path of operation, the Arm has no collision avoidance capability to prevent contact. Safe Arm operation depends on the Operator and/or safety observers maintaining situational awareness and halting operations if the Arm is at risk of contacting objects or people.
**WARNING**: The robot Arm does not have any obstacle avoidance capability.
-Even if the robot's onboard cameras can see an obstacle, the Arm cannot avoid it without the Operator's intervention. In tight spaces, it is possible for the gripper head to inadvertently collide with something in the world. When operating around sensitive, fragile, or other objects that should not be contacted, extra care should be taken to avoid collisions with the Arm.
+Even if the robot's onboard cameras can see an obstacle, the Arm cannot avoid it without the Operator's intervention. In tight spaces, it is possible for the gripper head to inadvertently collide with something in the world. When operating around sensitive, fragile, or other objects that should not be contacted, extra care should be taken to avoid collisions with the Arm.
+
+Note: The Arm does have the ability to avoid colliding with itself, the robot's body, and any properly configured payloads attached to the body.
-Note: The Arm does have the ability to avoid colliding with itself, the robot's body, and any properly configured payloads attached to the body.
## Body force limiter
+
In order to prevent large forces from being applied to the body when the Arm collides with something in the world, Arm torques are automatically limited to protect the body from being disturbed.
+
## Safety notes
-* Arm torque limitations will not prevent damage to the environment and should NOT be used as a safety feature. These limitations are designed to reduce the likelihood that the robot will fall over if the Arm collides with some obstacle.
-* If the robot walks into an object with the Arm outstretched that object can be damaged.
-* If attempting to lift and carry an object, the force limiter may prevent the arm from lifting the object if it is too heavy. The force limiter can be disabled in the Arm menu.
- * Care should be taken when disabling the force limiter. If the Arm contacts something in the world, it may apply high forces to the world and the robot body. This can potentially cause damage to the environment and/or the robot or the Arm, and make the robot inoperable.
\ No newline at end of file
+
+- Arm torque limitations will not prevent damage to the environment and should NOT be used as a safety feature. These limitations are designed to reduce the likelihood that the robot will fall over if the Arm collides with some obstacle.
+- If the robot walks into an object with the Arm outstretched that object can be damaged.
+- If attempting to lift and carry an object, the force limiter may prevent the arm from lifting the object if it is too heavy. The force limiter can be disabled in the Arm menu.
+ - Care should be taken when disabling the force limiter. If the Arm contacts something in the world, it may apply high forces to the world and the robot body. This can potentially cause damage to the environment and/or the robot or the Arm, and make the robot inoperable.
diff --git a/docs/concepts/arm/arm_services.md b/docs/concepts/arm/arm_services.md
index d0f0cd708..060bce531 100644
--- a/docs/concepts/arm/arm_services.md
+++ b/docs/concepts/arm/arm_services.md
@@ -9,13 +9,15 @@ Development Kit License (20191101-BDSDK-SL).
# Arm Services
## Manipulation Service
-This API provides high-level control for walking to and picking up items in the world. The service walks the robot up to the object, not on top of it. The idea being that you want to interact or manipulate the object. For specifying grasps, there are parameters available for
-* Specifying the depth of the grasp
- * Item pressed tightly against the palm of the gripper or squeezed with just the tip of the finger.
-* Constraints about the orientation of the grasp
- * "Only grasp from this direction" or "only do top down grasp"
-* How much the robot is allowed to move the grasp
-* Which camera source produced the image (for correcting calibration errors)
+
+This API provides high-level control for walking to and picking up items in the world. The service walks the robot up to the object, not on top of it. The idea being that you want to interact or manipulate the object. For specifying grasps, there are parameters available for
+
+- Specifying the depth of the grasp
+ - Item pressed tightly against the palm of the gripper or squeezed with just the tip of the finger.
+- Constraints about the orientation of the grasp
+ - "Only grasp from this direction" or "only do top down grasp"
+- How much the robot is allowed to move the grasp
+- Which camera source produced the image (for correcting calibration errors)
See the following examples for using this service:
@@ -26,7 +28,8 @@ Commands the robot to walk towards an object in preparation to grasp it. The exa
Shows how to autonomously grasp an object based on the object's image coordinates in pixel space. It opens an image view and lets a user select an object by clicking on the image.
## ArmSurfaceContact Service
-Control the end-effector while pushing on a surface. This mode is useful for drawing, wiping, and other similar behaviors where high accuracy position moves are required while pushing down with some force. This service is similar to the `ArmCartesianCommand` message available in the `RobotCommand` service, but is specialized for this type of task and has higher position accuracy.
+
+Control the end-effector while pushing on a surface. This mode is useful for drawing, wiping, and other similar behaviors where high accuracy position moves are required while pushing down with some force. This service is similar to the `ArmCartesianCommand` message available in the `RobotCommand` service, but is specialized for this type of task and has higher position accuracy.
See the following examples for using this service:
@@ -37,10 +40,12 @@ Requests an end effector trajectory move while applying some force to the ground
A [GCODE](https://en.wikipedia.org/wiki/G-code) interpreter that can be used to draw with sidewalk chalk.
## Door Service
-The door service is a framework for opening doors. We support three command types:
-* **AutoGrasp**: This message requires users to specify a location to search for a door handle along with and some door parameters. Spot autonomously grabs the handle, opens the door, and walks through.
-* **Warmstart**: In Warmstart, the assumption is the robot is already grasping the door handle. The robot will skip the grasp stage of auto, and immediately begin opening the door and then traverses through the doorway.
-* **AutoPush**: Used for doors that can be opened via a push without requiring a grasp. This includes pushbars, crashbars, and doors without a latching mechanism. The robot will point the hand down and push the door open with its wrist based on a push point supplied over the API.
+
+The door service is a framework for opening doors. We support three command types:
+
+- **AutoGrasp**: This message requires users to specify a location to search for a door handle along with and some door parameters. Spot autonomously grabs the handle, opens the door, and walks through.
+- **Warmstart**: In Warmstart, the assumption is the robot is already grasping the door handle. The robot will skip the grasp stage of auto, and immediately begin opening the door and then traverses through the doorway.
+- **AutoPush**: Used for doors that can be opened via a push without requiring a grasp. This includes pushbars, crashbars, and doors without a latching mechanism. The robot will point the hand down and push the door open with its wrist based on a push point supplied over the API.
See the following example for using this service:
@@ -49,10 +54,10 @@ This examples uses both the `ManipulationAPIService` and the `DoorService` to ha
## Inverse Kinematics Service
-The inverse kinmatics (IK) service allows users to request robot configurations that satisfy a given set of stance, tool, and task specifications:
+The inverse kinematics (IK) service allows users to request robot configurations that satisfy a given set of stance, tool, and task specifications:
- **Stance Specifications**
- - **Fixed Stance**: A valid solution must place the feet at the specfied positions, or at their current positions if unspecified.
+ - **Fixed Stance**: A valid solution must place the feet at the specified positions, or at their current positions if unspecified.
- **On Ground Plane Stance**: A valid solution must place the feet on the specified ground plane, or on the robots current estimated ground plane if unspecified.
- **Tool Specifications**
- **Wrist-Mounted Tool**: The tool frame is fixed at a specified pose relative to the final arm link. If that pose is unspecified, the tool frame defaults to the [hand frame](./arm_concepts.md#hand-frame).
@@ -66,9 +71,10 @@ The service responds with a robot configuration that meets those specifications
The IK service does not cause the robot to take any actions, but the information it returns can be used to populate [robot commands](../robot_services.md#robot-command). See the following [examples](../../../python/examples/inverse_kinematics/README.md) for more on how to use the service.
### Frames
+
Along with the [usual frames](../geometry_and_frames.md#frames-in-the-spot-robot-world), the IK service API refers to several additional frames:
+
- **root frame**: The frame relative to which the problem is defined. Must be either "odom" or "vision".
- **scene frame**: An optional frame at a user-specified pose relative to the root frame. Body and foot related quantities, as well as the task frame are expressed relative to this frame. Identity by default.
- **task frame**: An optional frame at a user-specified pose relative to the scene fame. Task specifications are expressed relative to this frame. Identity by default.
- **ground frame**: An optional frame at a user-specified pose relative to the scene frame. For an on-ground-plane stance, the feet must lie on the XY-plane of this frame. Defaults to the robot's current estimated ground plane.
-
diff --git a/docs/concepts/arm/arm_specification.md b/docs/concepts/arm/arm_specification.md
index 2f9aa7942..5a8aa3016 100644
--- a/docs/concepts/arm/arm_specification.md
+++ b/docs/concepts/arm/arm_specification.md
@@ -9,6 +9,7 @@ Development Kit License (20191101-BDSDK-SL).
# Arm and gripper specifications
## Joint ranges of motion and link lengths
+
@@ -16,34 +17,39 @@ Development Kit License (20191101-BDSDK-SL).
Link lengths are in mm.
## Arm specifications
-- **Degrees of freedom**: 6 + gripper
-- **Length at full extension**: 984 mm
-- **Max. reach height on robot**: 1800 mm
-- **Mass/weight, including gripper**: 8 kg
-- **Max. endpoint speed**: 10 m/s
-- **Lift capacity\***: Up to 11 kg
-- **Continuous lift capacity at 0.5 m extension\***: 5 kg
-- **Drag capacity\* (on carpet)**: Up to 25 kg
-- **Operating temp**: -20 C to 45 C
-- **Ingress protection**: Water and dust resistant
-
-\* At 22 C.
+
+- **Degrees of freedom**: 6 + gripper
+- **Length at full extension**: 984 mm
+- **Max. reach height on robot**: 1800 mm
+- **Mass/weight, including gripper**: 8 kg
+- **Max. endpoint speed**: 10 m/s
+- **Lift capacity\***: Up to 11 kg
+- **Continuous lift capacity at 0.5 m extension\***: 5 kg
+- **Drag capacity\* (on carpet)**: Up to 25 kg
+- **Operating temp**: -20 C to 45 C
+- **Ingress protection**: Water and dust resistant
+
+\* At 22 C.
## Gripper specifications
-- **Depth**: 90 mm
-- **Peak clamp force (at tip of opening)**: 130 N
-- **Integrated sensors**: ToF, IMU, 4K RGB
-- **Accessory port**: Gigabit Ethernet, 50W power, camera sync (PPS)
-- **Max Camera FOV**: RGB: 60.2° x 46.4°; Depth: 55.9° x 44°
+
+- **Depth**: 90 mm
+- **Peak clamp force (at tip of opening)**: 130 N
+- **Integrated sensors**: ToF, IMU, 4K RGB
+- **Accessory port**: Gigabit Ethernet, 50W power, camera sync (PPS)
+- **Max Camera FOV**: RGB: 60.2° x 46.4°; Depth: 55.9° x 44°
## How big an object can the gripper grasp
-The robot Arm is capable of holding any object it can fit the gripper jaws around. In general, this means that objects a person can pick up are also manageable by the robot.
-
+
+The robot Arm is capable of holding any object it can fit the gripper jaws around. In general, this means that objects a person can pick up are also manageable by the robot.
+
## Gripper safety
-Continue to observe the recommended safety distance of 3 meters from the robot. Do not touch the Arm or gripper (or the robot) while the robot is active.
-
+
+Continue to observe the recommended safety distance of 3 meters from the robot. Do not touch the Arm or gripper (or the robot) while the robot is active.
+
## Pinch points
-The gripper has a small clearance that offers some possibility to avoid complete pinching. However, pinching is always possible when grasping/holding objects. Limit human interaction with the gripper when in use.
-
-* Never introduce hands or fingers between an object to be grasped or being grasped and the gripper jaws. Keep hands away.
-* Never attempt to open the gripper while the robot is powered on. Never try to interfere with grasping and carrying. Stay away from an active robot.
+
+The gripper has a small clearance that offers some possibility to avoid complete pinching. However, pinching is always possible when grasping/holding objects. Limit human interaction with the gripper when in use.
+
+- Never introduce hands or fingers between an object to be grasped or being grasped and the gripper jaws. Keep hands away.
+- Never attempt to open the gripper while the robot is powered on. Never try to interfere with grasping and carrying. Stay away from an active robot.
diff --git a/docs/concepts/autonomy/README.md b/docs/concepts/autonomy/README.md
index c4c7360a1..ed953b640 100644
--- a/docs/concepts/autonomy/README.md
+++ b/docs/concepts/autonomy/README.md
@@ -16,21 +16,21 @@ The Autowalk feature is an implementation of the autonomous navigation API. Howe
## Contents
-* [Autonomy Technical Summary](graphnav_tech_summary.md)
-* [Autonomous navigation code examples](autonomous_navigation_code_examples.md)
-* [Components of autonomous navigation](components_of_autonomous_navigation.md)
-* [Docking](docking.md)
-* [Typical autonomous navigation use case](typical_autonomous_navigation_use_case.md)
-* [Autonomous navigation services](autonomous_navigation_services.md)
-* [GraphNav service](graphnav_service.md)
-* [GraphNav map structure](graphnav_map_structure.md)
-* [GraphNav area callbacks](graphnav_area_callbacks.md)
-* [Initialization](initialization.md)
-* [Localization](localization.md)
-* [GraphNav and robot locomotion](graphnav_and_robot_locomotion.md)
-* [Missions service](missions_service.md)
-* [Autowalk service](autowalk_service.md)
-* [Network compute bridge](../network_compute_bridge.md)
-* [AutoReturn service](auto_return.md)
-* [Directed Exploration](directed_exploration.md)
-* [GPS](gps.md)
\ No newline at end of file
+- [Autonomy Technical Summary](graphnav_tech_summary.md)
+- [Autonomous navigation code examples](autonomous_navigation_code_examples.md)
+- [Components of autonomous navigation](components_of_autonomous_navigation.md)
+- [Docking](docking.md)
+- [Typical autonomous navigation use case](typical_autonomous_navigation_use_case.md)
+- [Autonomous navigation services](autonomous_navigation_services.md)
+- [GraphNav service](graphnav_service.md)
+- [GraphNav map structure](graphnav_map_structure.md)
+- [GraphNav area callbacks](graphnav_area_callbacks.md)
+- [Initialization](initialization.md)
+- [Localization](localization.md)
+- [GraphNav and robot locomotion](graphnav_and_robot_locomotion.md)
+- [Missions service](missions_service.md)
+- [Autowalk service](autowalk_service.md)
+- [Network compute bridge](../network_compute_bridge.md)
+- [AutoReturn service](auto_return.md)
+- [Directed Exploration](directed_exploration.md)
+- [GPS](gps.md)
diff --git a/docs/concepts/autonomy/auto_return.md b/docs/concepts/autonomy/auto_return.md
index 93493c286..7e53203d9 100644
--- a/docs/concepts/autonomy/auto_return.md
+++ b/docs/concepts/autonomy/auto_return.md
@@ -9,12 +9,15 @@ Development Kit License (20191101-BDSDK-SL).
# AutoReturn Service
## What is AutoReturn?
+
AutoReturn is a service that will walk Spot back along a recently traversed path. It can be configured to happen automatically when Spot stops receiving commands from a user.
## Why would I want to use AutoReturn?
+
If you are piloting Spot through an area inaccessible to people and suddenly lose the communication link to Spot, the standard behavior is for Spot to sit down and power off. It may be valuable to instead tell Spot to automatically come back along the path it walked, hopefully putting Spot back into communication range.
## Why would I NOT want to use AutoReturn?
+
Depending on the environment Spot is in when AutoReturn activates, Spot may make things worse by trying to autonomously navigate. It’s very likely that AutoReturn will activate when there is poor or no communication to Spot, leaving it walking around unsupervised.
It's also important to note the following:
@@ -23,6 +26,7 @@ It's also important to note the following:
- **AutoReturn will behave better in certain environments than others.** For example, if Spot becomes trapped while executing AutoReturn, Spot will continue to try and return, possibly until the battery drops below the operation threshold, at which point Spot will sit down and power off. If the environment around Spot changes and blocks Spot's previous path, Spot may end up in a worse location than before.
## How do I use AutoReturn?
+
AutoReturn must be explicitly enabled, and will only work for the user that is driving Spot when AutoReturn is enabled. For example, if user A enables AutoReturn and then user B takes control of Spot, AutoReturn will not automatically run. If user B wants to enable AutoReturn, they must do it themselves.
### Configuring AutoReturn
@@ -50,12 +54,15 @@ but will only walk Spot up to or before the boundary in this example, omitting t
Tablet users will find AutoReturn settings under the “Comms” section of the main menu.
## What happens when AutoReturn finishes?
+
It depends on whether communication to a user has been restored. If Spot does not hear from a user by the time AutoReturn finishes, Spot’s normal comms loss behavior will begin.
## Using AutoReturn Safely
+
**AutoReturn can potentially cause the robot to operate autonomously for unexpected distances. This can be dangerous for anyone nearby.**
Tips for safe use of AutoReturn:
+
- Set the max displacement as low as possible to minimize the potential for the robot to venture any further than necessary.
- Keep the E-stop Service timeout as low as possible to limit the amount of time the robot is moving without Operator control. This setting can be found under "Autowalk Replay Supervision" in the tablet, alongside the AutoReturn settings.
diff --git a/docs/concepts/autonomy/autonomous_navigation_code_examples.md b/docs/concepts/autonomy/autonomous_navigation_code_examples.md
index 609715047..4c63ba842 100644
--- a/docs/concepts/autonomy/autonomous_navigation_code_examples.md
+++ b/docs/concepts/autonomy/autonomous_navigation_code_examples.md
@@ -12,16 +12,16 @@ GraphNav provides place-based localization and locomotion services. Developers c
The Spot SDK includes [python code examples](../../../python/examples/README.md) to help you get started with autonomous navigation. Refer to the following examples to learn about exercising the GraphNav API.
-| Code example | Description |
-| ------------ | --------------------------------------------- |
-| [recording_command_line](../../../python/examples/graph_nav_command_line/README.md) | Demonstrates graphnav recording service requests to record, create, and download a map from the robot. |
-| [graph_nav_command_line](../../../python/examples/graph_nav_command_line/README.md) | Demonstrates how to use GraphNav requests to: 
-1) **Application selection** - Enter Choreography drive mode from the upper left dropdown menu where it appears with Drive and Autowalk.
+1. **Application selection** - Enter Choreography drive mode from the upper left dropdown menu where it appears with Drive and Autowalk.
-2. **Exiting and entering Dance mode** - For Tablets without hardware joysticks, exiting and entering dance mode allows you to toggle between playing choreography sequences and using other robot modes. For tablets with hardware joysticks, selected choreography sequences will always appear on screen.
+2) **Exiting and entering Dance mode** - For Tablets without hardware joysticks, exiting and entering dance mode allows you to toggle between playing choreography sequences and using other robot modes. For tablets with hardware joysticks, selected choreography sequences will always appear on screen.
-3) **Select and View Choreography Sequences** - Lists of the choreography sequences that the robot can perform are viewable by pressing the tabs at the top of the screen. Opening these menus will allow you to add dance sequences to the Choreography screen as buttons which are used to play the sequences on the robot. These tabs are configurable, and you can choose which tabs will appear as options on screen by going to the **Choreography** option in the **Settings** menu.
+3. **Select and View Choreography Sequences** - Lists of the choreography sequences that the robot can perform are viewable by pressing the tabs at the top of the screen. Opening these menus will allow you to add dance sequences to the Choreography screen as buttons which are used to play the sequences on the robot. These tabs are configurable, and you can choose which tabs will appear as options on screen by going to the **Choreography** option in the **Settings** menu.
- *See below for information on configuring the Choreography drive screen.*
+ _See below for information on configuring the Choreography drive screen._
-4. **Adding moves to the screen** - You can choose to place any sequence to the left or right side of the tablet screen, where it will be added to a list of buttons which each trigger the playback of the selected choreography sequence. Swipe horizontally left and right across the dropdown menu to scroll through the known moves.
+4) **Adding moves to the screen** - You can choose to place any sequence to the left or right side of the tablet screen, where it will be added to a list of buttons which each trigger the playback of the selected choreography sequence. Swipe horizontally left and right across the dropdown menu to scroll through the known moves.
-5. **Play the Choreography sequence** - Once a sequence appears on screen as a white button you can press that button to play the choreography sequence. The name on the button indicates the choreography sequence that will play.
+5) **Play the Choreography sequence** - Once a sequence appears on screen as a white button you can press that button to play the choreography sequence. The name on the button indicates the choreography sequence that will play.
-6. **Removing buttons from the list** - Remove a button from on screen by pressing the minus symbol next to it. This does not remove the move from the dropdown menu it was selected from.
+6) **Removing buttons from the list** - Remove a button from on screen by pressing the minus symbol next to it. This does not remove the move from the dropdown menu it was selected from.
-7. **Cancel moves** - Stop a choreography sequence that is playing by pressing **CANCEL** in the center of the screen. If a move is canceled while it is playing, the robot will stop the move and come to a stand. A sequence can also be aborted by entering any other mode such as Sit, Stand, Walk, or Self Right.
+7) **Cancel moves** - Stop a choreography sequence that is playing by pressing **CANCEL** in the center of the screen. If a move is canceled while it is playing, the robot will stop the move and come to a stand. A sequence can also be aborted by entering any other mode such as Sit, Stand, Walk, or Self Right.
Take caution when stopping choreography sequences and playing choreography sequences when the robot is not in a neutral stance. Interrupting a dance in the middle of a dynamic movement, or starting a different dance before the previous dance finishes, may cause falls. For the best behavior avoid stopping a dance partway through unless necessary for safety reasons, and start dances from a stable stance or from seated. If a dance must be stopped partway through regardless of risk, try to pick a moment when Spot isn't moving too quickly, and has at least 3 feet on the ground. This will lower the risk of falls.
@@ -45,7 +55,7 @@ Take caution when stopping choreography sequences and playing choreography seque
Spot comes with a small library of sequences. Some of these are intended for performance. Some gestures can be used to communicate intent through body language. These sequences are always available in the **Select Moves** dropdown. The Tablet can also play custom sequences uploaded by users. The easiest way to author choreography sequences and upload them to the robot is through the Choreographer application.
-*Only users with a Spot choreography license can upload original sequences.*
+_Only users with a Spot choreography license can upload original sequences._
### Uploading choreography sequences with Choreographer
@@ -59,23 +69,26 @@ Spot comes with a small library of sequences. Some of these are intended for per
-5) Now connect to Spot through the Tablet, and navigate to the **Settings** section of the Hamburger menu. In **Settings** select **Choreography**. All the moves you uploaded with Choreographer should appear in a list near the bottom of the screen under **Unsaved Choreography Sequences**.
+5. Now connect to Spot through the Tablet, and navigate to the **Settings** section of the Hamburger menu. In **Settings** select **Choreography**. All the moves you uploaded with Choreographer should appear in a list near the bottom of the screen under **Unsaved Choreography Sequences**.
-6) To play these sequences through the tablet you will need to save them and give them a label. To save a sequence, select the edit symbol next to its name on the right side of the screen, choose a label from the dropdown, and press save. Complete this step for each sequence you wish to save and have accessible for execution through the tablet.
+6. To play these sequences through the tablet you will need to save them and give them a label. To save a sequence, select the edit symbol next to its name on the right side of the screen, choose a label from the dropdown, and press save. Complete this step for each sequence you wish to save and have accessible for execution through the tablet.
-*All animation moves (moves loaded from .cha files), included in a saved sequence will also be saved. Once a sequence is saved no further upload action will be required for it to be playable from the tablet or through an `ExecuteChoreography` RPC call using the sequence's name. If all sequences requiring an animation move are deleted, the stored animation move will also be removed on the next reboot. Make sure different animations have different names, or saved choreography sequences will attempt to replace the old version with the new version of the animation.*
+_All animation moves (moves loaded from .cha files), included in a saved sequence will also be saved. Once a sequence is saved no further upload action will be required for it to be playable from the tablet or through an `ExecuteChoreography` RPC call using the sequence's name. If all sequences requiring an animation move are deleted, the stored animation move will also be removed on the next reboot. Make sure different animations have different names, or saved choreography sequences will attempt to replace the old version with the new version of the animation._
-7) Locate the checkbox for the label(s) you saved your sequences to, and make sure they are checked. Checking the checkbox for a label will make it appear as an option when you enter the Choreography drive screen.
+7. Locate the checkbox for the label(s) you saved your sequences to, and make sure they are checked. Checking the checkbox for a label will make it appear as an option when you enter the Choreography drive screen.
-8) Enter the Choreography drive screen and locate the dropdown tabs with the labels you selected in the Choreography settings screen. You will now be able to add and play your custom choreography sequences in the same way you would play the sample choreography sequences included with your robot release.
+8. Enter the Choreography drive screen and locate the dropdown tabs with the labels you selected in the Choreography settings screen. You will now be able to add and play your custom choreography sequences in the same way you would play the sample choreography sequences included with your robot release.
+
## Managing your uploaded Choreography sequences
+
### **Deleting Saved Choreography Sequences**
The original choreography sequences you save to Spot will be retained indefinitely until you actively choose to delete them. To delete a sequence go to the Choreography settings screen and select the edit button next to sequence you wish to delete. In that screen, find the trash icon next to the sequence name and press it.
+
### **Adding and Removing Labels**
**Add a Label**@@ -94,12 +107,10 @@ Select the edit icon next to the label you want to delete. Find the trash icon n
-Select the edit icon next to the sequence you wish to modify. Find the label you wish to remove in the list under *sequence labels* on the right side of the screen, and remove it by pressing the **X** icon next to it.
+Select the edit icon next to the sequence you wish to modify. Find the label you wish to remove in the list under _sequence labels_ on the right side of the screen, and remove it by pressing the **X** icon next to it.
**Add a label to a Sequence**
-
Select the edit icon next to the sequence you wish to modify. Select the label you wish to add in the dropdown on the left hand side of the screen, and then press the **Add Label** button.
-
diff --git a/docs/concepts/choreography/choreography_service.md b/docs/concepts/choreography/choreography_service.md
index ae10abf89..7e9ac75c1 100644
--- a/docs/concepts/choreography/choreography_service.md
+++ b/docs/concepts/choreography/choreography_service.md
@@ -20,39 +20,38 @@ A choreography sequence consists of a series of moves. A wide variety of possibl
2. Altering move parameters to vary the behavior of the move
3. Adjusting the BPM of the choreography sequence to change the speed of the moves
-
### Note on reliability
-The choreography framework is less robust than other Spot behaviors. It should only be used on a flat floor with plenty of space and good traction. Some combinations of moves will be incompatible and can result in the robot falling. The same is true for some combinations of parameters for an individual move. The robot **will** fall down. Trial-and-error might be needed to produce a script that looks good and succeeds reliably.
+The choreography framework is less robust than other Spot behaviors. It should only be used on a flat floor with plenty of space and good traction. Some combinations of moves will be incompatible and can result in the robot falling. The same is true for some combinations of parameters for an individual move. The robot **will** fall down. Trial-and-error might be needed to produce a script that looks good and succeeds reliably.
-***Not recommended for use with payloads.***
+**_Not recommended for use with payloads._**
## Choreography terminology
### Slices
-In Choreographer, time is divided into slices. A slice is ¼ beat (also, a 1/16th note for 4/4 music). For example, a dance with a BPM of 100 beats/minute has 400 slices per minute. The duration of a slice can be adjusted but must remain constant throughout the entire script.
+In Choreographer, time is divided into slices. A slice is ¼ beat (also, a 1/16th note for 4/4 music). For example, a dance with a BPM of 100 beats/minute has 400 slices per minute. The duration of a slice can be adjusted but must remain constant throughout the entire script.
-Moves always run for an integer number of slices. Some moves require a fixed number of slices, and some are extendable. See the Config Files section for more details.
+Moves always run for an integer number of slices. Some moves require a fixed number of slices, and some are extendable. See the Config Files section for more details.
-Note that any number of slices per minute can be selected, however very fast or very slow slices will cause some moves to be unreliable. Many moves will be most reliable in the range of 250-450 slices per minute.
+Note that any number of slices per minute can be selected, however very fast or very slow slices will cause some moves to be unreliable. Many moves will be most reliable in the range of 250-450 slices per minute.
### Tracks and layering
The robot’s motion is divided into the following distinct tracks:
-* Legs
-* Body
-* Arm
-* Gripper
+- Legs
+- Body
+- Arm
+- Gripper
In addition to the base motion, there are also tracks for:
-* Lights: Control the robot's front two sets of LEDs.
-* Annotations: Enable dance annotations that are separate from any specific move.
-* Music (Choreographer only): Control the audio played from the Choreographer application when dancing.
+- Lights: Control the robot's front two sets of LEDs.
+- Annotations: Enable dance annotations that are separate from any specific move.
+- Music (Choreographer only): Control the audio played from the Choreographer application when dancing.
-Each dance move requires one or more of these tracks. Moves that use different tracks can be run simultaneously in any combination. In Choreographer, a track is represented as a horizontal section in the timeline view. Example: the following script combines moves in three of the four tracks:
+Each dance move requires one or more of these tracks. Moves that use different tracks can be run simultaneously in any combination. In Choreographer, a track is represented as a horizontal section in the timeline view. Example: the following script combines moves in three of the four tracks:
@@ -64,22 +63,20 @@ Some moves require multiple tracks, such as the "Jump" move which uses the body
-
### Entry and exit conditions
-
-All moves that use the legs track have logical entry and exit positions that the body must be in before or after the move. These entry and exit positions help to prevent nonsensical choreographies. Example: Completing a kneel-to-stand transition where the robot moves to a kneeling-clap move without an intervening stand-to-knee transition.
+All moves that use the legs track have logical entry and exit positions that the body must be in before or after the move. These entry and exit positions help to prevent nonsensical choreographies. Example: Completing a kneel-to-stand transition where the robot moves to a kneeling-clap move without an intervening stand-to-knee transition.
To represent and enforce these requirements, all moves that use the legs track must use one of the following exit and entry transition states:
-* Stand
-* Sit
-* Kneel
-* Sprawl
+- Stand
+- Sit
+- Kneel
+- Sprawl
-The first leg-track move can have any entry state. The robot automatically transitions to an acceptable entry state for that move before starting the choreography sequence. If the robot is not already in the correct starting pose, it may delay the start of the choreography sequence beyond the requested start time.
+The first leg-track move can have any entry state. The robot automatically transitions to an acceptable entry state for that move before starting the choreography sequence. If the robot is not already in the correct starting pose, it may delay the start of the choreography sequence beyond the requested start time.
-All subsequent legs-track moves must have an entry state that corresponds to the exit state of a previous legs-track move. Scripts that violate this requirement are rejected by the API and return warnings indicating which moves violate this rule. Routines made in Choreographer highlight moves red when the entry state does not match the previous exit state, as in this example:
+All subsequent legs-track moves must have an entry state that corresponds to the exit state of a previous legs-track move. Scripts that violate this requirement are rejected by the API and return warnings indicating which moves violate this rule. Routines made in Choreographer highlight moves red when the entry state does not match the previous exit state, as in this example:
@@ -87,27 +84,28 @@ All subsequent legs-track moves must have an entry state that corresponds to the
### Choreography API
-The Choreography API defines a choreography sequence by a unique name, the number of slices per minute, and a repeated list of moves. Each move consists of:
+The Choreography API defines a choreography sequence by a unique name, the number of slices per minute, and a repeated list of moves. Each move consists of:
-* Move type
-* Starting slice
-* Duration (in slices)
-* Actual parameters (`MoveParams` proto message).
+- Move type
+- Starting slice
+- Duration (in slices)
+- Actual parameters (`MoveParams` proto message).
The `MoveParams` message describes how the robot should behave during each move.
-Example: A move parameter could specify positions for the body. Each parameter may have specific limits/bounds that are described by the `MoveInfo` proto. This information can be found using the `ListAllMoves` RPC.
+Example: A move parameter could specify positions for the body. Each parameter may have specific limits/bounds that are described by the `MoveInfo` proto. This information can be found using the `ListAllMoves` RPC.
Once a choreography sequence is created, the `UploadChoreography` RPC sends the routine to the robot. The choreography service validates and checks the structure of the routine to ensure it is feasible and within bounds.
The service returns a list of warnings and failures related to the uploaded choreography sequence. A failure is something the choreography service could not automatically correct and must be fixed before the routine can be executed. Warnings are automatically corrected and do not block the execution of the routine in certain scenarios. If the boolean `non_strict_parsing` is set to true in the `UploadChoreography` RPC, the service fixes any correctable errors within the routine (for example, by limiting parameters to the acceptable range) and allows a choreography sequence with warnings to be completed.
-The `ExecuteChoreography` RPC runs the choreography sequence to completion on the robot. A choreography sequence is identified by the unique name of the sequence that was uploaded to the robot. Starting time (in robot’s time) and starting slice specifies when the robot when starts the choreography sequence and at which move. Named sequences can be returned using the `ListAllSequences` RPC.
+The `ExecuteChoreography` RPC runs the choreography sequence to completion on the robot. A choreography sequence is identified by the unique name of the sequence that was uploaded to the robot. Starting time (in robot’s time) and starting slice specifies when the robot when starts the choreography sequence and at which move. Named sequences can be returned using the `ListAllSequences` RPC.
### Interacting With a Sequence During Execution
-The `ChoreographyStatus` RPC returns information about whether the robot is currently executing a sequence or why it isn't. If it is executing a sequence, the response tells you where (what slice) within the sequence Spot currently is, as well as listing which moves are currently active and the sequence name.
-Some moves (e.g. [CustomGait](custom_gait.md)) can respond to commands through the `ChorographyCommand` RPC. When such moves are active, they will provide information about what commands they are currently able to accept in the `command_limits` field as part of the Status response. The `ChoreographyCommand` RPC sends `MoveCommand`s, which are targeted at specific moves. The `move_type` and `move_id` can (optionally) be used to restrict which moves will accept the command and ensure that only the intended recipient can respond to it.
+The `ChoreographyStatus` RPC returns information about whether the robot is currently executing a sequence or why it isn't. If it is executing a sequence, the response tells you where (what slice) within the sequence Spot currently is, as well as listing which moves are currently active and the sequence name.
+
+Some moves (e.g. [CustomGait](custom_gait.md)) can respond to commands through the `ChorographyCommand` RPC. When such moves are active, they will provide information about what commands they are currently able to accept in the `command_limits` field as part of the Status response. The `ChoreographyCommand` RPC sends `MoveCommand`s, which are targeted at specific moves. The `move_type` and `move_id` can (optionally) be used to restrict which moves will accept the command and ensure that only the intended recipient can respond to it.
### Saving Choreography Sequences to your Spot
@@ -117,29 +115,30 @@ The `SaveSequence` RPC will save a sequence and all information required to play
The Animation API defines an animated move (`Animation` proto message) by:
-* Its unique name
-* A repeated list of `AnimationKeyFrames` that describes the robot's motion at each timestamp
-* Additional parameters and options that describe how the move should be executed.
+- Its unique name
+- A repeated list of `AnimationKeyFrames` that describes the robot's motion at each timestamp
+- Additional parameters and options that describe how the move should be executed.
Unlike other dance moves, the information about the minimum and maximum parameters must be specified in the `Animation` protobuf.
The `Animation` can be uploaded to the robot using the `UploadAnimatedMove` RPC, which sends the animation to the robot. The choreography service validates and checks the structure of the animation to ensure it is fully specified and is feasible. If the animation does not pass this validation, the RPC responds with a failure status and a set of warning messages indicating which parts of the animation failed.
-If the animation uploads successfully, it can be used within choreography sequences. The animation appears as a move option in Choreographer along with any parameters specified in the initial `Animation` protobuf message. The move type associated with the uploaded animation is "animation::" + the animation's name. The animations persist on the robot until either the robot is powered off or an animation with exactly the same name is uploaded and overwrites the previous animation.
+If the animation uploads successfully, it can be used within choreography sequences. The animation appears as a move option in Choreographer along with any parameters specified in the initial `Animation` protobuf message. The move type associated with the uploaded animation is "animation::" + the animation's name. The animations persist on the robot until either the robot is powered off or an animation with exactly the same name is uploaded and overwrites the previous animation.
While animations can be written manually using protobuf in any application, we have also provided a way to create animations from human-readable text files.
-* Animation text file extension: *.cha
-* The animation file format is described in the [animation file specification document](animation_file_specification.md).
-The animation *.cha file can be converted into an `Animation` protobuf message using the `animation_file_to_proto.py` script provided in the choreography client library.
+- Animation text file extension: \*.cha
+- The animation file format is described in the [animation file specification document](animation_file_specification.md).
+
+The animation \*.cha file can be converted into an `Animation` protobuf message using the `animation_file_to_proto.py` script provided in the choreography client library.
### Choreography logs API
-The Choreography logs API defines a choreography log using the `ChoreographyStateLog` protobuf message. ChoreographyStateLog consists of a repeated series of timestamped key frames that contain:
+The Choreography logs API defines a choreography log using the `ChoreographyStateLog` protobuf message. ChoreographyStateLog consists of a repeated series of timestamped key frames that contain:
-* The joint state of the entire robot
-* The foot contacts
-* The SE3Pose for the robot body relative to the animation frame.
+- The joint state of the entire robot
+- The foot contacts
+- The SE3Pose for the robot body relative to the animation frame.
The animation frame is defined based on the feet position at the beginning of the animation. The position is the center of all four feet. The rotation is yaw-only as computed from the feet positions.
@@ -147,8 +146,8 @@ The animation frame is defined based on the feet position at the beginning of th
Choreography logs are divided into two types:
-* Automatic logs: The recording starts when the `ExecuteChoreography` RPC is first received and continues 3 seconds after the completion of the choreography.
-* Manual logs: The recording starts when the `StartRecordingState` RPC is first received and continues until the `StopRecordingState` RPC is received. Manual log recordings are limited to 5 minutes.
+- Automatic logs: The recording starts when the `ExecuteChoreography` RPC is first received and continues 3 seconds after the completion of the choreography.
+- Manual logs: The recording starts when the `StartRecordingState` RPC is first received and continues until the `StopRecordingState` RPC is received. Manual log recordings are limited to 5 minutes.
Choreography logs can be used to review how the robot actually executed a choreography or animated dance move. For example (specifically for animations): If the move is not completely feasible, the robot attempts to get as close to what was asked as possible, but may not succeed. The choreography log can be used to understand and update the animated move to make it more likely to succeed.
@@ -174,53 +173,52 @@ There are two config files that describe the individual moves that are used by t
## MoveInfoConfig.txt
-`MoveInfoConfig` can be parsed by a protobuf parser into each moves field of the `ListAllMovesResponse` proto. Each `MoveInfo` proto provides metadata about a particular move.
-
+`MoveInfoConfig` can be parsed by a protobuf parser into each moves field of the `ListAllMovesResponse` proto. Each `MoveInfo` proto provides metadata about a particular move.
The fields and their meanings are:
-* name: Name of this move.
-* move_length_slices: Default duration of this move in slices.
-* min_move_length_slices: Minimum number of slices this move can complete in.
-* is_extendable: Whether this move can be extended. If is_extendable is true, the desired duration can be specified in the requested_slices field in the MoveParams proto.
-* entrance_state: Which transition state the robot must be in prior to entering this move. Only applicable if controls_legs=true. Structure can support multiple allowed entry states, but all current moves only accept a single entry state.
-* exit_state: Which transition state the robot will be in after completing this move. Only applicable if controls_legs=true. The next legs-track move must have the same entrance_state.
-* min_time: Minimum move duration. When specified, moves may take more than the normal number of slices if the slice duration is very short (slices per minute is very high).
-* max_time: Maximum move duration. This applies to moves that are extendable but cannot be made arbitrarily long.
-* controls_arm: Move requires the arm track.
-* controls_legs: Move requires the legs track.
-* controls_body: Move requires the body track.
-* controls_gripper: Move requires the gripper track.
-* controls_lights: Move requires the front LED lights.
-* controls_annotations: Move updates the overall dance state.
-* display: How Choreographer should display the move.
- * color: Color of the box for the move in timeline tracks.
- * markers: Slices to draw the small grey vertical lines. These usually correspond to events such as touchdown and liftoff. Intended to help the user line those events up as desired (for example, on the beat). Negative values indicate slices before the end of the move.
- * description: Text description of the move.
- * image: Location of an image to display for the move.
- * category: Category name of the move as it appears in the move selector in Choreographer.
+- name: Name of this move.
+- move_length_slices: Default duration of this move in slices.
+- min_move_length_slices: Minimum number of slices this move can complete in.
+- is_extendable: Whether this move can be extended. If is_extendable is true, the desired duration can be specified in the requested_slices field in the MoveParams proto.
+- entrance_state: Which transition state the robot must be in prior to entering this move. Only applicable if controls_legs=true. Structure can support multiple allowed entry states, but all current moves only accept a single entry state.
+- exit_state: Which transition state the robot will be in after completing this move. Only applicable if controls_legs=true. The next legs-track move must have the same entrance_state.
+- min_time: Minimum move duration. When specified, moves may take more than the normal number of slices if the slice duration is very short (slices per minute is very high).
+- max_time: Maximum move duration. This applies to moves that are extendable but cannot be made arbitrarily long.
+- controls_arm: Move requires the arm track.
+- controls_legs: Move requires the legs track.
+- controls_body: Move requires the body track.
+- controls_gripper: Move requires the gripper track.
+- controls_lights: Move requires the front LED lights.
+- controls_annotations: Move updates the overall dance state.
+- display: How Choreographer should display the move.
+ - color: Color of the box for the move in timeline tracks.
+ - markers: Slices to draw the small grey vertical lines. These usually correspond to events such as touchdown and liftoff. Intended to help the user line those events up as desired (for example, on the beat). Negative values indicate slices before the end of the move.
+ - description: Text description of the move.
+ - image: Location of an image to display for the move.
+ - category: Category name of the move as it appears in the move selector in Choreographer.
### MoveParamsConfig.txt
-`MoveParamsConfig` provides the default value for each move parameter. For moves that contain numerical parameters (for example, double, int32) the config file will also specify the minimum and maximum values.
+`MoveParamsConfig` provides the default value for each move parameter. For moves that contain numerical parameters (for example, double, int32) the config file will also specify the minimum and maximum values.
The config file is formatted as a block of text separated by empty lines for each available move.
The first line of each block has two values:
1. The names of the moves.
-2. Which option in the oneof `params` field within the `MoveParams` proto this move uses to specify its parameters. For moves with no parameters, the second entry in the first line should say `NONE`. No further lines are used in that block of text
+2. Which option in the oneof `params` field within the `MoveParams` proto this move uses to specify its parameters. For moves with no parameters, the second entry in the first line should say `NONE`. No further lines are used in that block of text
-The remaining lines describe the default (and possibly min/max) values for one parameter per line.
+The remaining lines describe the default (and possibly min/max) values for one parameter per line.
-* The first field in each of these lines will be the name of the parameter.
-* Dots (“.”) indicate a level of hierarchy within the proto.
-* Parameters of type bool or Enum have two fields in the line. The second field is the default value.
-* Parameters of type double or int32 have 4 fields in the following order:
+- The first field in each of these lines will be the name of the parameter.
+- Dots (“.”) indicate a level of hierarchy within the proto.
+- Parameters of type bool or Enum have two fields in the line. The second field is the default value.
+- Parameters of type double or int32 have 4 fields in the following order:
1. Parameter name
1. Minimum value
1. Default value
1. Maximum value
-Default values are used if no value is specified within the proto. Scripts are rejected if the values are outside the allowable range. If `non_strict_parsing` is enabled, the value will be forced into the required range and a warning will be thrown.
+Default values are used if no value is specified within the proto. Scripts are rejected if the values are outside the allowable range. If `non_strict_parsing` is enabled, the value will be forced into the required range and a warning will be thrown.
diff --git a/docs/concepts/choreography/custom_gait.md b/docs/concepts/choreography/custom_gait.md
index 6e3ad3c2e..80d5fa630 100644
--- a/docs/concepts/choreography/custom_gait.md
+++ b/docs/concepts/choreography/custom_gait.md
@@ -8,30 +8,31 @@ Development Kit License (20191101-BDSDK-SL).
# Custom Gait
-Custom Gait is Choreography Move that behaves like a gait that can be greatly customized in its appearance and can be actively steered during operation (e.g. via a joystick). It can represent any gait pattern that has one or two steps per gait cycle for each leg.
+Custom Gait is Choreography Move that behaves like a gait that can be greatly customized in its appearance and can be actively steered during operation (e.g. via a joystick). It can represent any gait pattern that has one or two steps per gait cycle for each leg.
## Behavior Within a Sequence
-Custom Gait is integrated as a legs-track move within the Choreography API. It can therefore be combined with other moves that occupy the body, arm, gripper, and lights tracks. The Custom Gait move can be adjusted to occupy any number of slices within the timeline, however the sequence clock will not advance normally while Custom Gait is executing. Instead, the section of the sequence occupied by Custom Gait will represent one gait cycle (duration set by the `cycle_duration` parameter). This portion of the sequence, including moves in other tracks, will loop until Custom Gait is commanded to stop. This behavior is denoted by the black repeat symbols in the timeline view within Choreographer and will be reflected by the red cursor during execution.
+Custom Gait is integrated as a legs-track move within the Choreography API. It can therefore be combined with other moves that occupy the body, arm, gripper, and lights tracks. The Custom Gait move can be adjusted to occupy any number of slices within the timeline, however the sequence clock will not advance normally while Custom Gait is executing. Instead, the section of the sequence occupied by Custom Gait will represent one gait cycle (duration set by the `cycle_duration` parameter). This portion of the sequence, including moves in other tracks, will loop until Custom Gait is commanded to stop. This behavior is denoted by the black repeat symbols in the timeline view within Choreographer and will be reflected by the red cursor during execution.
-This means that Body and Arm-track moves will result in a cyclic motion phase-locked to Custom Gait, providing further options for customizing the appearance of the behavior. It is not possible for other moves to span the beginning or end of Custom Gait within the timeline.
+This means that Body and Arm-track moves will result in a cyclic motion phase-locked to Custom Gait, providing further options for customizing the appearance of the behavior. It is not possible for other moves to span the beginning or end of Custom Gait within the timeline.
## Driving Custom Gait
-CustomGait responds to the [ChoreographyCommand](choreography_service.md) RPC. When operating through Choreographer with an attached XBox controller, steering commands will be sent based on joystick position (left joystick for translation, right for turning), and the d-pad down button will command Custom Gait to stop, allowing the sequence to proceed. Steering commands will be scaled by the `CustomGaitCommandLimits` message returned as part of the [ChoreographyStatus](choreography_service.md) RPC. Those will generally be the values specified for `max_velocity` and `max_yaw_rate` in the parameters, but may be limited based on a determination of what that gait pattern is capable of.
+CustomGait responds to the [ChoreographyCommand](choreography_service.md) RPC. When operating through Choreographer with an attached XBox controller, steering commands will be sent based on joystick position (left joystick for translation, right for turning), and the d-pad down button will command Custom Gait to stop, allowing the sequence to proceed. Steering commands will be scaled by the `CustomGaitCommandLimits` message returned as part of the [ChoreographyStatus](choreography_service.md) RPC. Those will generally be the values specified for `max_velocity` and `max_yaw_rate` in the parameters, but may be limited based on a determination of what that gait pattern is capable of.
-The custom gait move can also be driven through the tablet's choreograpy drive screen using the tablet's joysticks. See [Tablet Choreography Mode](choreography_in_tablet.md) for further details on playing choreography sequences through the tablet.
+The custom gait move can also be driven through the tablet's choreography drive screen using the tablet's joysticks. See [Tablet Choreography Mode](choreography_in_tablet.md) for further details on playing choreography sequences through the tablet.
## Gait Diagram
-A Hildebrand-style gait diagram (see [wikipedia](https://en.wikipedia.org/wiki/Gait) is provided for Custom Gait as currently configured in the left panel of the Move Configuration tab in Choreographer. For each foot in the diagram (FL, FR, HL, HR), black regions of the diagram indicate periods of time when a foot is in contact with the ground, and white regions indicate periods of time when a foot is in the air. The phase sliders control the beginning and end of the white region. Some types of configuration errors will be indicated in red on the diagram.
+A Hildebrand-style gait diagram (see [wikipedia](https://en.wikipedia.org/wiki/Gait) is provided for Custom Gait as currently configured in the left panel of the Move Configuration tab in Choreographer. For each foot in the diagram (FL, FR, HL, HR), black regions of the diagram indicate periods of time when a foot is in contact with the ground, and white regions indicate periods of time when a foot is in the air. The phase sliders control the beginning and end of the white region. Some types of configuration errors will be indicated in red on the diagram.
## Presets
-Several preset gait patterns are provided in a pulldown menu where the "Reset to Default Parameters" button is for most moves. Select the desired preset, then click the "Apply" button. Note that presets only modify a subset of parameters. Presets with the prefix "gait" will only impact `cycle_duration` and phase parameters.
+Several preset gait patterns are provided in a pulldown menu where the "Reset to Default Parameters" button is for most moves. Select the desired preset, then click the "Apply" button. Note that presets only modify a subset of parameters. Presets with the prefix "gait" will only impact `cycle_duration` and phase parameters.
## Tips for Configuring Custom Gait
-- Fast stepping is often easier than slow stepping, especially when fewer feet are on the ground. Try starting with a faster `cycle_duration`, then gradually increasing that value to slow the cadence to your preferred speed. Exact value will depend on gait pattern, especially the duty factor, but `cycle_duration = 0.6 seconds` or even faster may be required from some patterns.
+
+- Fast stepping is often easier than slow stepping, especially when fewer feet are on the ground. Try starting with a faster `cycle_duration`, then gradually increasing that value to slow the cadence to your preferred speed. Exact value will depend on gait pattern, especially the duty factor, but `cycle_duration = 0.6 seconds` or even faster may be required from some patterns.
- Swing Duration is `(touchdown_phase - liftoff_phase * cycle_duration)`.
- Individual swings shorter than 250 ms will make it difficult to operate off of flat ground.
- Individual swings shorter than 150 ms will make it difficult to move quickly, even on flat ground.
@@ -40,47 +41,48 @@ Several preset gait patterns are provided in a pulldown menu where the "Reset to
- The maximum duration both left or both right feet can be off the ground simultaneously is about 500ms.
- The maximum duration a diagonal pair of feet can be off the ground simultaneously is about 800ms.
- The "duty factor" is the fraction of the time that a foot is on the ground.
-- The average duty factor of either the two front legs or the two hind legs should be at least 30%. Increasing duty factor will generally improve stability (with decreasing returns after 65%).
-- More challenging gaits may only work well at low speeds and/or low accelerations. Consider lowering the speed limits using the `max_velocity` and `max_yaw_rate` sliders and lowering the acceleration limit with the `acceleration_scaling` slider during initial testing.
+- The average duty factor of either the two front legs or the two hind legs should be at least 30%. Increasing duty factor will generally improve stability (with decreasing returns after 65%).
+- More challenging gaits may only work well at low speeds and/or low accelerations. Consider lowering the speed limits using the `max_velocity` and `max_yaw_rate` sliders and lowering the acceleration limit with the `acceleration_scaling` slider during initial testing.
## Parameter Reference
-Parameter | Effect
---|--
-cycle_duration | The duration (s) of a full gait cycle.
-liftoff_phase | When within the gait cycle a particular leg lifts off the ground.
-touchdown_phase | When within the gait cycle a particular leg steps onto the ground.
-two_LEG_swings | Determines whether that particular leg will have two steps within the gait cycle. If active, a second set of liftoff_phase and touchdown_phase must be specified.
-max_velocity | The maximum translational velocity (m/s) command that will be accepted.
-max_yaw_rate | The maximum turn rate (rad/s) command that will be accepted.
-acceleration_scaling | How much to limit steering acceleration. 1 is normal. Smaller is less acceleration.
-com_height | Height (m) of the Center-of-Mass above the ground.
-body_translation_offset | Horizontal offset (m) of the Center-of-Mass from a neutral posture. (x-forward, y-left). This is a constant offset that is additive with any phase-dependent offset specified in a Body-track move.
-body_rotation_offset | Orientation offset (rad) from a neutral posture. This is a constant offset that is additive with any phase-dependent offset specified in a Body-track move.
-low_speed_body_fraction | How much to scale down the body motion when navigating at low speeds.
-stance_shape | The relative position of the feet when they are on the ground.
-stance_shape.length | Distance (m) between front and hind feet.
-stance_shape.width | Distance (m) between left and right feet.
-stance_shape.front_wider_than_hind | Difference (m) between the FL<-->FR distance and the HL<-->HR distance. Positive means front feet are wider.
-stance_shape.left_longer_than_right | Difference (m) between the FL<-->HL distance and the FR<-->HR distance. Positive means the left feet are farther apart.
-stance_shape.left_forward_of_right | Distance (m) to shift the FL and HL feet forward relative to the FR and HR feet. Negative means shifted backwards.
-general_swing_params | Swing parameters that apply to all legs not configured to use leg-specific swing parameters.
-use_LEG_swing_params | Configures a particular leg to use leg-speciic swing parameters rather than the general set.
-LEG_swing_params | Swing parameters used by a particular leg if configured to use leg-specific swing parameters.
-SwingParams.height | How high (m) to lift the foot. Request may not be achievable due to configured vertical_speed, vertical_acceleration, and swing duration.
-SwingParams.liftoff_speed | How fast (m/s) to start lifting the foot at the moment of liftoff.
-SwingParams.vertical_speed | How fast (m/s) to lift and lower the foot.
-SwingParams.vertical_acceleration | How fast to accelerate (m/s/s) the foot vertically to achieve the configured vertical_speed.
-SwingParams.overlay_outside | How far (m) to swing the foot to the outside (negative for inside) relative to a straight-line step.
-SwingParams.overlay_forward | How far (m) to swing the foot forward (negative for backward) relative to a straight-line step.
-SwingParams.low_speed_fraction | How much to reduce the swing parameters when navigating at low speed.
-mu | Estimated coefficient of friction between the ground and the feet. Setting this accurately will improve reliability.
-timing_stiffness | How much the robot is allowed to deviate from the specified timing. 0 means no deviation. Otherwise, large values mean less deviation and small values mean more is acceptable.Too much timing adjustment (low, non-zero values) may make the gait unstable.
At least a little timing adjustment is recommended for gaits with flight phases (periods with 0 feet on the ground). -step_position_stiffness | How much the robot is allowed to deviate from the specified stance shape.
0 means no deviation.
Otherwise: large values mean less deviation and small values mean more is acceptable.
Too much position adjustment (low, non-zero values) may make the gait unstable. -enable_perception_obstacle_avoidance | If enabled, CustomGait will attempt to avoid obstacles.
More challenging gaits may require significant obstacle avoidance padding to reliably avoid collisions. -obstacle_avoidance_padding | How far (m) to stay away from obstacles.
More challenging gaits may require significant padding to reliably avoid collisions. -enable_perception_terrain_height | If enabled, will use perception to determine the shape of the terrain.
Can be disabled if operating on a flat floor. -enable_perception_step_placement | If enabled, will use perception to determine good vs bad locations to step.
Can be disabled if operating on a flat floor. -maximum_stumble_distance | If Spot stumbles more than this distance (m), it will give up and freeze. -stand_in_place | Stand rather than stepping in place when not moving. -standard_final_stance | Go back to a standard rectangular stance when ending the gait.
Otherwise maintains the customized stance shape. -trip_sensitivity | How sensitive we should be to trip detection.
On the range [0, 1], where 1 is normal sensitivity and 0 is ignoring all trips.
Useful for very aggressive gaits or when a costume is restricting leg motion. + +| Parameter | Effect | +| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| cycle_duration | The duration (s) of a full gait cycle. | +| liftoff_phase | When within the gait cycle a particular leg lifts off the ground. | +| touchdown_phase | When within the gait cycle a particular leg steps onto the ground. | +| two_LEG_swings | Determines whether that particular leg will have two steps within the gait cycle. If active, a second set of liftoff_phase and touchdown_phase must be specified. | +| max_velocity | The maximum translational velocity (m/s) command that will be accepted. | +| max_yaw_rate | The maximum turn rate (rad/s) command that will be accepted. | +| acceleration_scaling | How much to limit steering acceleration. 1 is normal. Smaller is less acceleration. | +| com_height | Height (m) of the Center-of-Mass above the ground. | +| body_translation_offset | Horizontal offset (m) of the Center-of-Mass from a neutral posture. (x-forward, y-left). This is a constant offset that is additive with any phase-dependent offset specified in a Body-track move. | +| body_rotation_offset | Orientation offset (rad) from a neutral posture. This is a constant offset that is additive with any phase-dependent offset specified in a Body-track move. | +| low_speed_body_fraction | How much to scale down the body motion when navigating at low speeds. | +| stance_shape | The relative position of the feet when they are on the ground. | +| stance_shape.length | Distance (m) between front and hind feet. | +| stance_shape.width | Distance (m) between left and right feet. | +| stance_shape.front_wider_than_hind | Difference (m) between the FL<-->FR distance and the HL<-->HR distance. Positive means front feet are wider. | +| stance_shape.left_longer_than_right | Difference (m) between the FL<-->HL distance and the FR<-->HR distance. Positive means the left feet are farther apart. | +| stance_shape.left_forward_of_right | Distance (m) to shift the FL and HL feet forward relative to the FR and HR feet. Negative means shifted backwards. | +| general_swing_params | Swing parameters that apply to all legs not configured to use leg-specific swing parameters. | +| use_LEG_swing_params | Configures a particular leg to use leg-specific swing parameters rather than the general set. | +| LEG_swing_params | Swing parameters used by a particular leg if configured to use leg-specific swing parameters. | +| SwingParams.height | How high (m) to lift the foot. Request may not be achievable due to configured vertical_speed, vertical_acceleration, and swing duration. | +| SwingParams.liftoff_speed | How fast (m/s) to start lifting the foot at the moment of liftoff. | +| SwingParams.vertical_speed | How fast (m/s) to lift and lower the foot. | +| SwingParams.vertical_acceleration | How fast to accelerate (m/s/s) the foot vertically to achieve the configured vertical_speed. | +| SwingParams.overlay_outside | How far (m) to swing the foot to the outside (negative for inside) relative to a straight-line step. | +| SwingParams.overlay_forward | How far (m) to swing the foot forward (negative for backward) relative to a straight-line step. | +| SwingParams.low_speed_fraction | How much to reduce the swing parameters when navigating at low speed. | +| mu | Estimated coefficient of friction between the ground and the feet. Setting this accurately will improve reliability. | +| timing_stiffness | How much the robot is allowed to deviate from the specified timing. 0 means no deviation. Otherwise, large values mean less deviation and small values mean more is acceptable.
Too much timing adjustment (low, non-zero values) may make the gait unstable.
At least a little timing adjustment is recommended for gaits with flight phases (periods with 0 feet on the ground). | +| step_position_stiffness | How much the robot is allowed to deviate from the specified stance shape.
0 means no deviation.
Otherwise: large values mean less deviation and small values mean more is acceptable.
Too much position adjustment (low, non-zero values) may make the gait unstable. | +| enable_perception_obstacle_avoidance | If enabled, CustomGait will attempt to avoid obstacles.
More challenging gaits may require significant obstacle avoidance padding to reliably avoid collisions. | +| obstacle_avoidance_padding | How far (m) to stay away from obstacles.
More challenging gaits may require significant padding to reliably avoid collisions. | +| enable_perception_terrain_height | If enabled, will use perception to determine the shape of the terrain.
Can be disabled if operating on a flat floor. | +| enable_perception_step_placement | If enabled, will use perception to determine good vs bad locations to step.
Can be disabled if operating on a flat floor. | +| maximum_stumble_distance | If Spot stumbles more than this distance (m), it will give up and freeze. | +| stand_in_place | Stand rather than stepping in place when not moving. | +| standard_final_stance | Go back to a standard rectangular stance when ending the gait.
Otherwise maintains the customized stance shape. | +| trip_sensitivity | How sensitive we should be to trip detection.
On the range [0, 1], where 1 is normal sensitivity and 0 is ignoring all trips.
Useful for very aggressive gaits or when a costume is restricting leg motion. | diff --git a/docs/concepts/choreography/move_reference.md b/docs/concepts/choreography/move_reference.md index 57507785c..9980971a5 100644 --- a/docs/concepts/choreography/move_reference.md +++ b/docs/concepts/choreography/move_reference.md @@ -10,8 +10,8 @@ Development Kit License (20191101-BDSDK-SL). This section describes each Choreographer move at a high level, including: -* Parameters used by the move -* Animated GIFs demonstrating the move with default parameters (for most moves) +- Parameters used by the move +- Animated GIFs demonstrating the move with default parameters (for most moves) More information about choreography moves can be found by looking at the choreography protos in the Spot [proto reference](../../../protos/bosdyn/api/README). @@ -21,12 +21,12 @@ More information about choreography moves can be found by looking at the choreog  -Rotates the body to a desired orientation. Nominally takes one beat (4 slices) but can be extended to go slower. +Rotates the body to a desired orientation. Nominally takes one beat (4 slices) but can be extended to go slower. -Parameter | Effect ---|-- -rotation | The desired body orientation. -return_to_start_pose | If true, returns to the previous body pose by the end of this move. If false, remains in the specified position. +| Parameter | Effect | +| -------------------- | ---------------------------------------------------------------------------------------------------------------- | +| rotation | The desired body orientation. | +| return_to_start_pose | If true, returns to the previous body pose by the end of this move. If false, remains in the specified position. | ### rotate_body_sharp @@ -34,7 +34,7 @@ return_to_start_pose | If true, returns to the previous body pose by the end of Identical to the rotate_body move, but moves to the desired position quickly and returns (unless configured not to return) more slowly. -***No Parameters*** +**_No Parameters_** ### body_hold @@ -42,90 +42,90 @@ Identical to the rotate_body move, but moves to the desired position quickly and Moves the body to a specified position/orientation and holds it steady for the specified duration then optionally returns to a neutral pose. -Parameter | Effect ---|-- -rotation/translation | The desired pose. -entry_slices | How long to spend transitioning to the desired pose. -exit_slices | How quickly to transition back to the original pose. If set to 0, remains at the specified pose. +| Parameter | Effect | +| -------------------- | ------------------------------------------------------------------------------------------------ | +| rotation/translation | The desired pose. | +| entry_slices | How long to spend transitioning to the desired pose. | +| exit_slices | How quickly to transition back to the original pose. If set to 0, remains at the specified pose. | ### body_const -Holds the body at the pose from the immediately preceding body-track move. Applies to both orientation and translation. Can be extended to any desired duration. +Holds the body at the pose from the immediately preceding body-track move. Applies to both orientation and translation. Can be extended to any desired duration. -***No Parameters*** +**_No Parameters_** ### sway  -Sway back and forth to the beat. A full back/forth cycle takes 2 beats. +Sway back and forth to the beat. A full back/forth cycle takes 2 beats. -Parameter | Effect ---|-- -vertical/horizontal/roll | How much motion in the respective directions. -pivot | Which portion of the body remains stationary. -style | Modifies the velocity profile of the motion. -pronounced | How exaggerated the style is. Smaller values will be closer to the SWAY_STYLE_STANDARD. -hold_zero_axes | If set to true, maintains the previous pose in whichever axes 0 motion is specified. If false, those axes return to nominal. +| Parameter | Effect | +| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | +| vertical/horizontal/roll | How much motion in the respective directions. | +| pivot | Which portion of the body remains stationary. | +| style | Modifies the velocity profile of the motion. | +| pronounced | How exaggerated the style is. Smaller values will be closer to the SWAY_STYLE_STANDARD. | +| hold_zero_axes | If set to true, maintains the previous pose in whichever axes 0 motion is specified. If false, those axes return to nominal. | ### random_rotate  -Rotate the body in a random, chaotic manner. Rotation in each axis is generated independently. Can be extended to any desired duration. +Rotate the body in a random, chaotic manner. Rotation in each axis is generated independently. Can be extended to any desired duration. -Parameter | Effect ---|-- -amplitude | How far from the nominal pose to rotate in each axis. -speed | How quickly to rotate in each axis. -speed_variation | How much to vary the speed. Controls the ratio between the slowest and fastest moves. When 0, no variation (all moves are the same speed). -num_speed_tiers | Can create multiple tiers of speed. -tier_variation | Difference between the speed of the slowest tier compared to the fastest_tier. +| Parameter | Effect | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| amplitude | How far from the nominal pose to rotate in each axis. | +| speed | How quickly to rotate in each axis. | +| speed_variation | How much to vary the speed. Controls the ratio between the slowest and fastest moves. When 0, no variation (all moves are the same speed). | +| num_speed_tiers | Can create multiple tiers of speed. | +| tier_variation | Difference between the speed of the slowest tier compared to the fastest_tier. | ### twerk  -Lowers the robutt down and back up once. Lasts for one beat (4 slices). +Lowers the robutt down and back up once. Lasts for one beat (4 slices). -Parameter | Effect ---|-- -height | How much to lower the robutt. +| Parameter | Effect | +| --------- | ----------------------------- | +| height | How much to lower the robutt. | ### butt_circle  -Move the robutt, head, or both head and robutt in a circle. Extendable to the desired duration. Rotates about the previous pose. +Move the robutt, head, or both head and robutt in a circle. Extendable to the desired duration. Rotates about the previous pose. -Parameter | Effect ---|-- -radius | Size of the rotation circle. -beats_per_circle | The duration of a circle in beats (4 slices each). Mutually exclusive with number_of_circles. Will be ignored unless number_of_circles = 0. -number_of_circles | The number of circles to perform. Mutually exclusive with beats_per_circle. If number_of_circles = 0, beats_per_circle will be used instead. -pivot | What part of the robot to pivot around. Pivoting around the front means the robutt moves in circles. -clockwise | Which direction to rotate. -starting_angle | Where in the circle to start rotation. Since it spirals outwards, it may not be obvious exactly where it starts. +| Parameter | Effect | +| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| radius | Size of the rotation circle. | +| beats_per_circle | The duration of a circle in beats (4 slices each). Mutually exclusive with number_of_circles. Will be ignored unless number_of_circles = 0. | +| number_of_circles | The number of circles to perform. Mutually exclusive with beats_per_circle. If number_of_circles = 0, beats_per_circle will be used instead. | +| pivot | What part of the robot to pivot around. Pivoting around the front means the robutt moves in circles. | +| clockwise | Which direction to rotate. | +| starting_angle | Where in the circle to start rotation. Since it spirals outwards, it may not be obvious exactly where it starts. | ### fidget_stand -A procedurally-generated idle animation. It looks around, breathes, shifts its weight, and stamps. Can use one of the preset configurations or customize the parameters. - -Parameter | Effect ---|-- -preset | Pre-designed parameter combinations that attempt to convey a specific emotion. NOTE: All other sliders are only active if this is set to "Custom". -min_gaze_pitch | How far down the robot looks. (Radians) -max_gaze_pitch | How far up the robot looks. (Radians) -gaze_mean_period | How frequently the robot looks somewhere else. (Seconds) -gaze_center_cfp | Where the gaze array originates in the center-of-footprint frame. (Meters) -shift_mean_period | How frequently the robot shifts its weight. (Seconds) -shift_max_transition_time | Maximum amount of time the robot spends shifting its weight. (Seconds) -breath_min_z | Minimum amplitude of the "breathing" (meters) -breath_max_z | Maximum amplitude of the "breathing" (meters) -leg_gesture_mean_period | How frequently the robot does a leg gesture. (Seconds) -gaze_slew_rate | How quickly the robot shifts its gaze. (Meters/Second) -gaze_position_generation_gain | How much Brownian motion is applied to the gaze point. -gaze_roll_generation_gain | How much Brownian motion is applied to the gaze roll. +A procedurally-generated idle animation. It looks around, breathes, shifts its weight, and stamps. Can use one of the preset configurations or customize the parameters. + +| Parameter | Effect | +| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| preset | Pre-designed parameter combinations that attempt to convey a specific emotion. NOTE: All other sliders are only active if this is set to "Custom". | +| min_gaze_pitch | How far down the robot looks. (Radians) | +| max_gaze_pitch | How far up the robot looks. (Radians) | +| gaze_mean_period | How frequently the robot looks somewhere else. (Seconds) | +| gaze_center_cfp | Where the gaze array originates in the center-of-footprint frame. (Meters) | +| shift_mean_period | How frequently the robot shifts its weight. (Seconds) | +| shift_max_transition_time | Maximum amount of time the robot spends shifting its weight. (Seconds) | +| breath_min_z | Minimum amplitude of the "breathing" (meters) | +| breath_max_z | Maximum amplitude of the "breathing" (meters) | +| leg_gesture_mean_period | How frequently the robot does a leg gesture. (Seconds) | +| gaze_slew_rate | How quickly the robot shifts its gaze. (Meters/Second) | +| gaze_position_generation_gain | How much Brownian motion is applied to the gaze point. | +| gaze_roll_generation_gain | How much Brownian motion is applied to the gaze roll. | ## Step moves @@ -133,34 +133,37 @@ gaze_roll_generation_gain | How much Brownian motion is applied to the gaze roll  -Take a single step with one or two feet. Nominally requires one beat (4 slices) but can be extended to step slower. If stepping with two feet, especially both front or both hind feet, longer steps will be unreliable. Lifts off one slice after the move begins and touches down one slice before it ends. - -Parameter | Effect ---|-- -foot/second_foot | Which feet to step with. If only a single foot is desired, second_foot should be set to LEG_NO_LEG. -offset | Where to step relative to a nominal stance for the first foot. -touch | If true, taps the foot near the ground midway through swing. -touch_offset | If touch is true, where the touch should occur relative to the nominal stance location. -mirror_x, mirror_y | Determines whether the second_foot (if there is one) has the same offset and touch_offset as the first foot (false) or the opposite offset (true). Specified independently for the x and y axis. -swing_waypoint | Defines a waypoint that the swing leg must go through between liftoff and touchdown. If left at {0,0,0}, no waypoint will be added and the system will take a normal swing. -waypoint_dwell | What fraction of the swing should be spent near the waypoint. -swing_height | How high to lift the foot/feet. Does nothing if a swing_waypoint is specified. -liftoff_velocity | How quickly to raise the foot/feet. Does nothing if a swing_waypoint is specified. -touchdown_velocity | How quickly to lower the foot/feet. Does nothing if a swing_waypoint is specified. +Take a single step with one or two feet. Nominally requires one beat (4 slices) but can be extended to step slower. If stepping with two feet, especially both front or both hind feet, longer steps will be unreliable. Lifts off one slice after the move begins and touches down one slice before it ends. + +| Parameter | Effect | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| foot/second_foot | Which feet to step with. If only a single foot is desired, second_foot should be set to LEG_NO_LEG. | +| offset | Where to step relative to a nominal stance for the first foot. | +| touch | If true, taps the foot near the ground midway through swing. | +| touch_offset | If touch is true, where the touch should occur relative to the nominal stance location. | +| mirror_x, mirror_y | Determines whether the second_foot (if there is one) has the same offset and touch_offset as the first foot (false) or the opposite offset (true). Specified independently for the x and y axis. | +| swing_waypoint | Defines a waypoint that the swing leg must go through between liftoff and touchdown. If left at {0,0,0}, no waypoint will be added and the system will take a normal swing. | +| waypoint_dwell | What fraction of the swing should be spent near the waypoint. | +| swing_height | How high to lift the foot/feet. Does nothing if a swing_waypoint is specified. | +| liftoff_velocity | How quickly to raise the foot/feet. Does nothing if a swing_waypoint is specified. | +| touchdown_velocity | How quickly to lower the foot/feet. Does nothing if a swing_waypoint is specified. | ### goto  -Trot to a specified position in the dance frame. Unless explicitly set, the dance frame is defined by where the dance begins. Takes 1 step per beat. Extend the duration to successfully move farther. +Trot to a specified position in the dance frame. Unless explicitly set, the dance frame is defined by where the dance begins. Takes 1 step per beat. Extend the duration to successfully move farther. -Parameter | Effect ---|-- -absolute_position | Position the robot moves to in the dance frame. -absolute_yaw | Yaw orientation the robot moves to in the dance frame. -step_position_stiffness | How precisely the robot steps in the nominal locations. -duty_cycle | What fraction of the time a foot is on the ground. 0.5 is a standard trot. -link_to_next | Should the robot smoothly transition from this move to a subsequent goto move. +| Parameter | Effect | +| ----------------------- | ------------------------------------------------------------------------------------------------------ | +| relative | Relative to starting pose if true. Target specified in dance frame if false. | +| absolute_position | Position the robot moves to in the dance frame. Ignored if absolute = false. | +| absolute_yaw | Yaw orientation the robot moves to in the dance frame. Ignored if absolute = false. | +| relative_position | Position the robot moves to relative to where it started this move. Ignored if absolute = true. | +| relative_yaw | Yaw orientation the robot moves to relative to where it started this move. Ignored if absolute = true. | +| step_position_stiffness | How precisely the robot steps in the nominal locations. | +| duty_cycle | What fraction of the time a foot is on the ground. 0.5 is a standard trot. | +| link_to_next | Should the robot smoothly transition from this move to a subsequent goto move. | ### trot @@ -168,10 +171,10 @@ link_to_next | Should the robot smoothly transition from this move to a subseque Runs the trot gait. Can be extended to run for an arbitrary duration. -Parameter | Effect ---|-- -velocity/yaw_rate | The steering command. -stand_time | Duration before the end of the nominal move to start going to a stand. If set too short, the robot may not finish transitioning and could fall. +| Parameter | Effect | +| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| velocity/yaw_rate | The steering command. | +| stand_time | Duration before the end of the nominal move to start going to a stand. If set too short, the robot may not finish transitioning and could fall. | ### pace @@ -179,56 +182,60 @@ stand_time | Duration before the end of the nominal move to start going to a sta Runs the pace gait. Can be extended to run for any desired duration. -Parameter | Effect ---|-- -velocity/yaw_rate | The steering command. -stand_time | Duration before the end of the nominal move to start going to a stand. If set too short, it may not finish transitioning and could fall. +| Parameter | Effect | +| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| velocity/yaw_rate | The steering command. | +| stand_time | Duration before the end of the nominal move to start going to a stand. If set too short, it may not finish transitioning and could fall. | ### turn_2step  -Take two steps to turn in place. Requires 2 beats (8 slices). +Take two steps to turn in place. Requires 2 beats (8 slices). -Parameter | Effect ---|-- -motion_is_absolute | Is motion in the dance frame (true) or relative to the current position (false). -motion | How far to move. (Meters) -absolute_motion | Where to move to in the dance frame. (Meters) -yaw_is_absolute | Is yaw in the dance frame (true) or relative to the current position (false). -yaw | How far to rotate. (Radians) -absolute_yaw | Where to rotate to in the dance frame. (Radians) -swing_height | How to pick up the feet. Zero indicates to use a default swing. -swing_velocity | How quickly to lift off and touch down the feet. Zero indicates to use a default swing. +| Parameter | Effect | +| ------------------ | --------------------------------------------------------------------------------------- | +| motion_is_absolute | Is motion in the dance frame (true) or relative to the current position (false). | +| motion | How far to move. (Meters) | +| absolute_motion | Where to move to in the dance frame. (Meters) | +| yaw_is_absolute | Is yaw in the dance frame (true) or relative to the current position (false). | +| yaw | How far to rotate. (Radians) | +| absolute_yaw | Where to rotate to in the dance frame. (Radians) | +| swing_height | How to pick up the feet. Zero indicates to use a default swing. | +| swing_velocity | How quickly to lift off and touch down the feet. Zero indicates to use a default swing. | ## pace_2step  -Take two steps to translate using a pace gait (legs on the same side of the robot move together). Requires 2 beats (8 slices). Caution: Large lateral steps require a high-traction floor. +Take two steps to translate using a pace gait (legs on the same side of the robot move together). Requires 2 beats (8 slices). Caution: Large lateral steps require a high-traction floor. -Parameter | Effect ---|-- -motion_is_absolute | Is motion in the dance frame (true) or relative to the current position (false). -motion | How far to move. (Meters) -absolute_motion | Where to move to in the dance frame. (Meters) -yaw_is_absolute | Is yaw in the dance frame (true) or relative to the current position (false). -yaw | How far to rotate. (Radians) -absolute_yaw | Where to rotate to in the dance frame. (Radians) -swing_height | How to pick up the feet. Zero indicates to use a default swing. -swing_velocity | How quickly to lift off and touch down the feet. Zero indicates to use a default swing. +| Parameter | Effect | +| ------------------ | --------------------------------------------------------------------------------------- | +| motion_is_absolute | Is motion in the dance frame (true) or relative to the current position (false). | +| motion | How far to move. (Meters) | +| absolute_motion | Where to move to in the dance frame. (Meters) | +| yaw_is_absolute | Is yaw in the dance frame (true) or relative to the current position (false). | +| yaw | How far to rotate. (Radians) | +| absolute_yaw | Where to rotate to in the dance frame. (Radians) | +| swing_height | How to pick up the feet. Zero indicates to use a default swing. | +| swing_velocity | How quickly to lift off and touch down the feet. Zero indicates to use a default swing. | ### crawl  -Locomotes, taking one step every beat. Can be extended to run for any desired duration. +Locomotes, taking one step every beat. Can be extended to run for any desired duration. -Parameter | Effect ---|-- -velocity | Desired velocity of the robot. -swing_slices | Duration of a swing in slices. An entire gait cycle takes 4 beats (16 slices). At the maximum value of 8 slices two of the robot's feet will always be on the ground, as in the Amble gait. With a value of 4, the robot will always have one foot on the ground, as in the Crawl gait. -stance_width, stance_length | The dimensions and shape of the rectangle the stance feet make. +| Parameter | Effect | +| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| velocity | Desired velocity of the robot. | +| swing_slices | Duration of a swing in slices. An entire gait cycle takes 4 beats (16 slices). At the maximum value of 8 slices two of the robot's feet will always be on the ground, as in the Amble gait. With a value of 4, the robot will always have one foot on the ground, as in the Crawl gait. | +| stance_width, stance_length | The dimensions and shape of the rectangle the stance feet make. | + +### custom_gait + +See [CustomGait](custom_gait.md) ## Dynamic moves @@ -236,18 +243,18 @@ stance_width, stance_length | The dimensions and shape of the rectangle the stan  -Spot’s version of the “running man” dance move. Can be extended to run for any desired duration. +Spot’s version of the “running man” dance move. Can be extended to run for any desired duration. -Parameter | Effect ---|-- -velocity | By default, the robot dances in place but can move around in the world. -pre_move_cycles | How many slices to dance in place before moving at the specified velocity. -swing_height | How high to pick up the feet. -spread | How far to slide the feet backward from where they’re initially placed. -reverse | If true, will step backwards and slide forward: The reverse of the normal motion. -speed_multiplier | Run the move at something other than the song's overall beats-per-minute. -duty_cycle | What fraction of the time legs are in stance. -com_height | Desired height of the center-of-mass. +| Parameter | Effect | +| ---------------- | --------------------------------------------------------------------------------- | +| velocity | By default, the robot dances in place but can move around in the world. | +| pre_move_cycles | How many slices to dance in place before moving at the specified velocity. | +| swing_height | How high to pick up the feet. | +| spread | How far to slide the feet backward from where they’re initially placed. | +| reverse | If true, will step backwards and slide forward: The reverse of the normal motion. | +| speed_multiplier | Run the move at something other than the song's overall beats-per-minute. | +| duty_cycle | What fraction of the time legs are in stance. | +| com_height | Desired height of the center-of-mass. | ### bourree @@ -255,22 +262,21 @@ com_height | Desired height of the center-of-mass. Cross-legged tippy-taps, like the ballet move. -Parameter | Effect ---|-- -velocity, yaw_rate | Steering command. -stance_length | Distance between front and hind legs. +| Parameter | Effect | +| ------------------ | ------------------------------------- | +| velocity, yaw_rate | Steering command. | +| stance_length | Distance between front and hind legs. | ### hop  - Runs the hop gait. Can be extended to run for any desired duration. -Parameter | Effect ---|-- -velocity/yaw_rate | The steering command. -stand_time | The duration before the end of the nominal move to start going to a stand. If set too short, the robot may not finish transitioning and could fall. +| Parameter | Effect | +| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| velocity/yaw_rate | The steering command. | +| stand_time | The duration before the end of the nominal move to start going to a stand. If set too short, the robot may not finish transitioning and could fall. | ### jog @@ -278,11 +284,10 @@ stand_time | The duration before the end of the nominal move to start going to a Runs the jog gait. Can be extended to run for any desired duration. -Parameter | Effect ---|-- -velocity/yaw_rate | The steering command. -stand_time | The duration before the end of the nominal move to start going to a stand. If set too short, the robot may not finish transitioning and could fall. - +| Parameter | Effect | +| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| velocity/yaw_rate | The steering command. | +| stand_time | The duration before the end of the nominal move to start going to a stand. If set too short, the robot may not finish transitioning and could fall. | ### skip @@ -290,40 +295,40 @@ stand_time | The duration before the end of the nominal move to start going to a Runs the skip gait. Is extendable to run for an arbitrary duration. -Parameter | Effect ---|-- -velocity/yaw_rate | The steering command. -stand_time | The duration before the end of the nominal move to start going to a stand. If set too short, the robot may not finish transitioning and could fall. +| Parameter | Effect | +| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| velocity/yaw_rate | The steering command. | +| stand_time | The duration before the end of the nominal move to start going to a stand. If set too short, the robot may not finish transitioning and could fall. | ### front_up  -Lifts the front feet then returns to a stand. Can be extended to adjust the duration of the hind-feet-only stance. Longer durations are unreliable. Lifts off 2 slices from the start of the move and touches down one slice from the end of the move. +Lifts the front feet then returns to a stand. Can be extended to adjust the duration of the hind-feet-only stance. Longer durations are unreliable. Lifts off 2 slices from the start of the move and touches down one slice from the end of the move. -Parameter | Effect ---|-- -mirror | If true, raises the hind legs instead of the front legs. +| Parameter | Effect | +| --------- | -------------------------------------------------------- | +| mirror | If true, raises the hind legs instead of the front legs. | ### jump  -Jumps in place. Nominally lasts one beat but may take more slices at faster tempos. - -Parameter | Effect ---|-- -translation_is_absolute | Is motion in the dance frame (true) or relative to the current position (false). -translation | How far to move. (Meters) -absolute_translation | Where to move to in the dance frame. (Meters) -yaw_is_absolute | Is yaw in the dance frame (true) or relative to the current position (false). -yaw | How far to rotate. (Radians) -absolute_yaw | Where to rotate to in the dance frame. (Radians) -flight_slices | How long the jump should last with all feet off the ground measured in slices. Depending on tempo, higher values will be unreliable. -stance_width/stance_length | The footprint the robot should land its jump in. -swing_height | How how to pick up the feet. -split_fraction | Splits the liftoff and touchdown into two pairs of two legs. In fraction of of swing with two legs in flight, so 0 means all legs fully synchronized. -lead_leg_pair | If split_fraction is not 0, indicates which legs lift off first. Default AUTO mode will select a pair based on the translation vector. +Jumps in place. Nominally lasts one beat but may take more slices at faster tempos. + +| Parameter | Effect | +| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| translation_is_absolute | Is motion in the dance frame (true) or relative to the current position (false). | +| translation | How far to move. (Meters) | +| absolute_translation | Where to move to in the dance frame. (Meters) | +| yaw_is_absolute | Is yaw in the dance frame (true) or relative to the current position (false). | +| yaw | How far to rotate. (Radians) | +| absolute_yaw | Where to rotate to in the dance frame. (Radians) | +| flight_slices | How long the jump should last with all feet off the ground measured in slices. Depending on tempo, higher values will be unreliable. | +| stance_width/stance_length | The footprint the robot should land its jump in. | +| swing_height | How how to pick up the feet. | +| split_fraction | Splits the liftoff and touchdown into two pairs of two legs. In fraction of of swing with two legs in flight, so 0 means all legs fully synchronized. | +| lead_leg_pair | If split_fraction is not 0, indicates which legs lift off first. Default AUTO mode will select a pair based on the translation vector. | ## Transition moves @@ -331,72 +336,71 @@ lead_leg_pair | If split_fraction is not 0, indicates which legs lift off first.  -Sit the robot down or remain seated. Requires at least 3 seconds. +Sit the robot down or remain seated. Requires at least 3 seconds. -***No Parameters*** +**_No Parameters_** ### stand_up -Stand the robot up from a seated position. Requires at least 2 seconds. +Stand the robot up from a seated position. Requires at least 2 seconds. -***No Parameters*** +**_No Parameters_** ### sit_to_sprawl  -Starting from a seated position, rolls the robot onto its side/back. Intended to prep the robot for a more dramatic self-right. - -Parameter | Effect ---|-- -side | Which side to roll to. +Starting from a seated position, rolls the robot onto its side/back. Intended to prep the robot for a more dramatic self-right. +| Parameter | Effect | +| --------- | ---------------------- | +| side | Which side to roll to. | ### random_stretch -Extends any extendable moves immediately prior to it by a random number of slices between 0 and the duration of the stretch move. The robot then immediately jumps to the end of this move. Note: This changes the duration of a choreography sequence. +Extends any extendable moves immediately prior to it by a random number of slices between 0 and the duration of the stretch move. The robot then immediately jumps to the end of this move. Note: This changes the duration of a choreography sequence. -***No Parameters*** +**_No Parameters_** ### stand_to_kneel  -Transitions from standing to kneeling on the hind legs. Requires 2 seconds. +Transitions from standing to kneeling on the hind legs. Requires 2 seconds. -***No Parameters*** +**_No Parameters_** ### kneel_to_stand  -Transitions from kneeling on the hind legs to a stand. Requires 2.4 seconds. +Transitions from kneeling on the hind legs to a stand. Requires 2.4 seconds. -***No Parameters*** +**_No Parameters_** ### kneel_to_stand_fast  -Transitions from kneeling on the hind legs to a stand. Faster and smoother than kneel_To_stand, but might be less reliable in some combinations. +Transitions from kneeling on the hind legs to a stand. Faster and smoother than kneel_To_stand, but might be less reliable in some combinations. -***No Parameters*** +**_No Parameters_** ### self_right  -Activate the self-right behavior. Primarily useful as the first move in a dance if you wish to start from a non-standard posture. Nominally requires 5 seconds, but can be extended to ensure that it completes. +Activate the self-right behavior. Primarily useful as the first move in a dance if you wish to start from a non-standard posture. Nominally requires 5 seconds, but can be extended to ensure that it completes. -***No Parameters*** +**_No Parameters_** ### leg_pose -Directly pose Spot's legs by specifying joint angles. Spot will make no attempt to balance. +Directly pose Spot's legs by specifying joint angles. Spot will make no attempt to balance. -Parameter | Effect ---|-- -angles | The specified joint angles. +| Parameter | Effect | +| --------- | --------------------------- | +| angles | The specified joint angles. | ## Kneel moves @@ -404,53 +408,54 @@ angles | The specified joint angles.  -While kneeling, move the front legs to a specified joint configuration. Nominally takes one beat (4 slices) but can be extended to go slower. +While kneeling, move the front legs to a specified joint configuration. Nominally takes one beat (4 slices) but can be extended to go slower. -Parameter | Effect ---|-- -hip_x, hip_y, knee | Joint angles for the front-left leg. -mirror | If true, move the legs in a mirrored manner. If false, front-right leg moves to the same joint configuration as the front-left. If true, the front-right hip_x angle has the opposite sign: The front-left leg and the other joint angles will be the same. -easing | Controls the velocity profile of the motion. +| Parameter | Effect | +| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| hip_x, hip_y, knee | Joint angles for the front-left leg. | +| mirror | If true, move the legs in a mirrored manner. If false, front-right leg moves to the same joint configuration as the front-left. If true, the front-right hip_x angle has the opposite sign: The front-left leg and the other joint angles will be the same. | +| easing | Controls the velocity profile of the motion. | ### kneel_leg_move2  -Similar to kneel_leg_move, but allows you to independently set the front-left and front-right leg joint angles. Additionally allows linking for smoother transitions between multiple consecutive moves. +Similar to kneel_leg_move, but allows you to independently set the front-left and front-right leg joint angles. Additionally allows linking for smoother transitions between multiple consecutive moves. + +| Parameter | Effect | +| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| left_hip_x, left_hip_y, left_knee | Joint angles for the front-left leg. | +| right_hip_x, right_hip_y, right_knee | Joint angles for the front-left leg. | +| easing | Controls the velocity profile of the motion. Does nothing for linked moves. | +| link_to_next | Links this move to a second kneel_leg_move2 that immediately follows it if there is one. Multiple moves can be linked in this way. Linked moves form a combined trajectory where the joints travel through each waypoint but not necessarily come to a zero-velocity stop at the end of each move. | -Parameter | Effect ---|-- -left_hip_x, left_hip_y, left_knee | Joint angles for the front-left leg. -right_hip_x, right_hip_y, right_knee | Joint angles for the front-left leg. -easing | Controls the velocity profile of the motion. Does nothing for linked moves. -link_to_next | Links this move to a second kneel_leg_move2 that immediately follows it if there is one. Multiple moves can be linked in this way. Linked moves form a combined trajectory where the joints travel through each waypoint but not necessarily come to a zero-velocity stop at the end of each move. ### kneel_clap  -While kneeling, clap the front feet together. Takes one beat (4 slices). +While kneeling, clap the front feet together. Takes one beat (4 slices). -Parameter | Effect ---|-- -direction | The movement direction of the clap in the flat_body frame (z is up, x is direction the robot faces). -location | The location of the clap in body frame. -speed | The speed of the clap. -clap_distance | How far apart the feet will be prior to clapping. +| Parameter | Effect | +| ------------- | ---------------------------------------------------------------------------------------------------- | +| direction | The movement direction of the clap in the flat_body frame (z is up, x is direction the robot faces). | +| location | The location of the clap in body frame. | +| speed | The speed of the clap. | +| clap_distance | How far apart the feet will be prior to clapping. | ### kneel_circles  -While kneeling, move the front feet in circles in the body-XZ (sagittal) plane. The two feet will be 180 degrees out of phase. Can be extended to run for any duration. +While kneeling, move the front feet in circles in the body-XZ (sagittal) plane. The two feet will be 180 degrees out of phase. Can be extended to run for any duration. -Parameter | Effect ---|-- -location | The location of the center of the circles in body frame. -beats_per_circle | The duration of a full circle in beats. Ignored unless number_of_circles = 0. -number_of_circles | Number of circles to perform. If 0, then use beats_per_circle. -offset | Distance between the circle plane and the body centerline. -radius | Size of the circles that the feet move in. -reverse | Reverses the circle direction. Nominal direction is away from the body on top. +| Parameter | Effect | +| ----------------- | ------------------------------------------------------------------------------ | +| location | The location of the center of the circles in body frame. | +| beats_per_circle | The duration of a full circle in beats. Ignored unless number_of_circles = 0. | +| number_of_circles | Number of circles to perform. If 0, then use beats_per_circle. | +| offset | Distance between the circle plane and the body centerline. | +| radius | Size of the circles that the feet move in. | +| reverse | Reverses the circle direction. Nominal direction is away from the body on top. | ## Arm moves @@ -458,17 +463,17 @@ reverse | Reverses the circle direction. Nominal direction is away from the bod  -Moves the WR0 joint up and back down for one beat (4 slices). If done from a stow pose, will raise the hand. +Moves the WR0 joint up and back down for one beat (4 slices). If done from a stow pose, will raise the hand. -***No Parameters*** +**_No Parameters_** ### stow  -Returns the arm to a stowed configuration. Nominally takes one beat (4 slices) but can be extended to go slower. +Returns the arm to a stowed configuration. Nominally takes one beat (4 slices) but can be extended to go slower. -***No Parameters*** +**_No Parameters_** ### unstow @@ -476,32 +481,32 @@ Returns the arm to a stowed configuration. Nominally takes one beat (4 slices) Moves the arm to a deployed configuration. Nominally takes one beat (4 slices) but can be extended to go slower. -***No Parameters*** +**_No Parameters_** ### shoulder_left  -Rotate the SH0 joint to move the gripper to the left. Nominally takes one beat (4 slices) but can be extended to go slower. +Rotate the SH0 joint to move the gripper to the left. Nominally takes one beat (4 slices) but can be extended to go slower. -***No Parameters*** +**_No Parameters_** ### shoulder_right  -Rotate the SH0 joint to move the gripper to the right. Nominally takes one beat (4 slices) but can be extended to go slower. +Rotate the SH0 joint to move the gripper to the right. Nominally takes one beat (4 slices) but can be extended to go slower. -***No Parameters*** +**_No Parameters_** ### arm_move -Moves the arm to the specified joint angles. Nominally takes one beat (4 slices) but can be adjusted to go faster or slower. +Moves the arm to the specified joint angles. Nominally takes one beat (4 slices) but can be adjusted to go faster or slower. -Parameter | Effect ---|-- -angles | The specified joint angles, including the gripper angle. -easing | Controls the velocity profile of the motion. +| Parameter | Effect | +| --------- | -------------------------------------------------------- | +| angles | The specified joint angles, including the gripper angle. | +| easing | Controls the velocity profile of the motion. | ### arm_move_no_gripper @@ -509,124 +514,170 @@ Identical to arm_move, but excluding the gripper track. ### arm_move_relative -Moves the arm incrementally, relative to the previous pose. Nominally takes one beat (4 slices) but can be adjusted to go faster or slower. +Moves the arm incrementally, relative to the previous pose. Nominally takes one beat (4 slices) but can be adjusted to go faster or slower. -Parameter | Effect ---|-- -angles | The specified joint angles, including the gripper angle. -easing | Controls the velocity profile of the motion. +| Parameter | Effect | +| --------- | -------------------------------------------------------- | +| angles | The specified joint angles, including the gripper angle. | +| easing | Controls the velocity profile of the motion. | ### workspace_arm_move Moves the gripper to a location specified in the world (not joint angles). -Parameter | Effect ---|-- -frame | Frame in which the motion is specified. -absolute | If true goes to a position/orientation relative to the origin of the given frame. If false, direction is defined by the specified frame, but motion is relative to previous pose. -rotation, translation | The pose to move to. -easing | Controls the velocity profile of the motion. +| Parameter | Effect | +| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| frame | Frame in which the motion is specified. | +| absolute | If true goes to a position/orientation relative to the origin of the given frame. If false, direction is defined by the specified frame, but motion is relative to previous pose. | +| rotation, translation | The pose to move to. | +| easing | Controls the velocity profile of the motion. | ### figure8_move  -Moves the gripper in a figure-8 pattern centered on the previous pose. Repeats for the specified duration. +Moves the gripper in a figure-8 pattern centered on the previous pose. Repeats for the specified duration. -Parameter | Effect ---|-- -height, width | The size and shape of the figure-8 pattern. -beats_per_cycle | How long to complete one cycle of the figure-8 pattern. +| Parameter | Effect | +| --------------- | ------------------------------------------------------- | +| height, width | The size and shape of the figure-8 pattern. | +| beats_per_cycle | How long to complete one cycle of the figure-8 pattern. | ### gripper  -Moves the gripper to the specified angle. Duration can be set to any number of slices but speed will be determined by parameter. Once the gripper reaches the specified angle it will stop. If the selected duration is too short to complete the move given the configured speed, the robot remains at whatever angle it reaches when move ends. +Moves the gripper to the specified angle. Duration can be set to any number of slices but speed will be determined by parameter. Once the gripper reaches the specified angle it will stop. If the selected duration is too short to complete the move given the configured speed, the robot remains at whatever angle it reaches when move ends. -Parameter | Effect ---|-- -angle | The desired gripper angle. -speed | The desired velocity of the gripper in rad/s. +| Parameter | Effect | +| --------- | --------------------------------------------- | +| angle | The desired gripper angle. | +| speed | The desired velocity of the gripper in rad/s. | ### frame_snapshot -This move sets the frame to be used by future moves that are in an absolute frame. Some moves will always be in the dance frame (frame_id = 0) and some allow you to explicitly select a frame_id. This move can set frames relative to either a fiducial or to the robot's footprint. +This move sets the frame to be used by future moves that are in an absolute frame. Some moves will always be in the dance frame (frame_id = 0) and some allow you to explicitly select a frame_id. This move can set frames relative to either a fiducial or to Spot's footprint. -Parameter | Effect ---|-- -frame_id | Which frame to set. The dance frame 0 is used by moves that do absolute motion but don't explicitly select a frame. -fiducial_number | Which fiducial to set the frame relative to. If set to -1 or if the fiducial has not been seen recently, the fiducial number is set according to the robot's footprint. -include_each_leg | Should each leg be included when determining the footprint. -compensated | If a foot is not included, should we offset the footprint as if that foot were in a nominal stance? Otherwise, we'll take the center of the included feet. +| Parameter | Effect | +| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| frame_id | Which frame to set. The dance frame 0 is used by moves that do absolute motion but don't explicitly select a frame. | +| fiducial_number | Which fiducial to set the frame relative to. If set to -1 or if the fiducial has not been seen recently, the fiducial number is set according Spot's footprint. | +| include_each_leg | Should each leg be included when determining the footprint. | +| compensated | If a foot is not included, should we offset the footprint as if that foot were in a nominal stance? Otherwise, we'll take the center of the included feet. | ### chicken_head  -Holds the arm stationary in the world while the body is moving. Can also be configured to move in a fixed oscillation in the world. +Holds the arm stationary in the world while the body is moving. Can also be configured to move in a fixed oscillation in the world. -Parameter | Effect ---|-- -bob_magnitude | A vector describing the amplitude and direction of a periodic motion of the gripper in the world. -beats_per_cycle | How long it takes to complete 1 cycle of the motion described by bob_magnitude -follow | If set to true, the gripper position will adjust if the robot steps to a new location. +| Parameter | Effect | +| --------------- | ------------------------------------------------------------------------------------------------- | +| bob_magnitude | A vector describing the amplitude and direction of a periodic motion of the gripper in the world. | +| beats_per_cycle | How long it takes to complete 1 cycle of the motion described by bob_magnitude | +| follow | If set to true, the gripper position will adjust if the robot steps to a new location. | -## Lights moves +## Face Lights moves All colors are specified as RGB on a 0-255 scale. ### set_color -Sets the color of the robot's face lights. Left and right lights can be independently set. Lights can be set to fade in and out. +Sets the color of Spot's face (status) lights. Left and right lights can be independently set. Lights can be set to fade in and out. -Parameter | Effect ---|-- -left_color | Color of the left lights. Color of all lights if right_same_as_left specified. -right_same_as_left | If true, all lights are left_color. If false, left and right are independently specified. -right_color | Color of the right lights. Does nothing if right_same_as_left specified. -fade_in_slices | How long to spend brightening at the beginning, measured in slices (1/4 beats). -fade_out_slices | How long to spend darkening at the end, measured in slices (1/4 beats). +| Parameter | Effect | +| ------------------ | ---------------------------------------------------------------------------------------------- | +| left_color | Color of the left face lights. Color of all face lights if right_same_as_left specified. | +| right_same_as_left | If true, all face lights are left_color. If false, left and right are independently specified. | +| right_color | Color of the right face lights. Does nothing if right_same_as_left specified. | +| fade_in_slices | How long to spend brightening at the beginning, measured in slices (1/4 beats). | +| fade_out_slices | How long to spend darkening at the end, measured in slices (1/4 beats). | ### fade_color -Sets the lights to show one color at the top fading towards another color at the bottom. +Sets the face (status) lights to show one color at the top fading towards another color at the bottom. -Parameter | Effect ---|-- -top_color | The color of the topmost lights. -bottom_color | The color of the bottommost lights. -fade_in_slices | How long to brighten, measured in slices (1/4 beats). -fade_out_slices | How long to dim at the end, measured in slices (1/4 beats). +| Parameter | Effect | +| --------------- | ----------------------------------------------------------- | +| top_color | The color of the topmost lights. | +| bottom_color | The color of the bottommost lights. | +| fade_in_slices | How long to brighten, measured in slices (1/4 beats). | +| fade_out_slices | How long to dim at the end, measured in slices (1/4 beats). | ### independent_color -Independently specifies the color of all 8 lights. - -Parameter | Effect ---|-- -top_left | Color of the top left light. -upper_mid_left | Color of the second from top left light. -lower_mid_left | Color of the second from bottom left light. -bottom_left | Color of the bottom left light. -top_right | Color of the top right light. -upper_mid_right | Color of the second from top right light. -lower_mid_right | CColor of the second from bottom right light. -bottom_right | Color of the bottom right light. -fade_in_slices | How long to brighten, measured in slices (1/4 beats). -fade_out_slices | How long to dim at the end, measured in slices (1/4 beats). +Independently specifies the color of all 8 face (status) lights. + +| Parameter | Effect | +| --------------- | ----------------------------------------------------------- | +| top_left | Color of the top left light. | +| upper_mid_left | Color of the second from top left light. | +| lower_mid_left | Color of the second from bottom left light. | +| bottom_left | Color of the bottom left light. | +| top_right | Color of the top right light. | +| upper_mid_right | Color of the second from top right light. | +| lower_mid_right | CColor of the second from bottom right light. | +| bottom_right | Color of the bottom right light. | +| fade_in_slices | How long to brighten, measured in slices (1/4 beats). | +| fade_out_slices | How long to dim at the end, measured in slices (1/4 beats). | ### ripple_color -Sets the lights in a variety of moving patterns. +Sets the face (status) lights in a variety of moving patterns. -Parameter | Effect ---|-- -main | Color to make the lights. -secondary | Second color to make the lights, used only by some patterns. -pattern | Select from a variety of light motion patterns. -light_side | Which side lights to use for the pattern. -increment_slices | How quickly to move the pattern in slices (1/4 beats) between updates to the pattern. +| Parameter | Effect | +| ---------------- | ------------------------------------------------------------------------------------- | +| main | Color to make the face lights. | +| secondary | Second color to make the face lights, used only by some patterns. | +| pattern | Select from a variety of light motion patterns. | +| light_side | Which side lights to use for the pattern. | +| increment_slices | How quickly to move the pattern in slices (1/4 beats) between updates to the pattern. | -### custom_gait -See [CustomGait](custom_gait.md) \ No newline at end of file +## Audio Visual Lights moves + +All colors are specified as RGB on a 0-255 scale. + +### set_audio_visual_color + +Sets the color of the audio visual system's lights. Lights can be independently set. Lights can be set to fade in and out. + +| Parameter | Effect | +| ------------------ | --------------------------------------------------------------------------------------------------------------- | +| front_center_color | Color of the front center audio visual light. Color of all audio visual lights if all_same_as_center specified. | +| all_same_as_center | If true, all lights are front_center_color. If false, lights are independently specified. | +| front_left_color | Color of the front left audio visual light. Does nothing if all_same_as_center specified. | +| front_right_color | Color of the front right audio visual light. Does nothing if all_same_as_center specified. | +| back_left_color | Color of the back left audio visual light. Does nothing if all_same_as_center specified. | +| back_right_color | Color of the back right audio visual light. Does nothing if all_same_as_center specified. | +| fade_in_slices | How long to brighten, measured in slices (1/4 beats). | +| fade_out_slices | How long to dim at the end, measured in slices (1/4 beats). | + +### set_all_color + +Sets the color of the audio visual system's lights and the face (status) lights. Lights can be independently set. Lights can be set to fade in and out. + +| Parameter | Effect | +| ------------------ | --------------------------------------------------------------------------------------------------------------- | +| front_center_color | Color of the front center audio visual light. Color of all audio visual lights if all_same_as_center specified. | +| all_same_as_center | If true, all lights are front_center_color. If false, lights are independently specified. | +| status_left_color | Color of the left face lights. Does nothing if all_same_as_center specified. | +| status_right_color | Color of the right face lights. Does nothing if all_same_as_center specified. | +| front_left_color | Color of the front left audio visual light. Does nothing if all_same_as_center specified. | +| front_right_color | Color of the front right audio visual light. Does nothing if all_same_as_center specified. | +| back_left_color | Color of the back left audio visual light. Does nothing if all_same_as_center specified. | +| back_right_color | Color of the back right audio visual light. Does nothing if all_same_as_center specified. | +| fade_in_slices | How long to brighten, measured in slices (1/4 beats). | +| fade_out_slices | How long to dim at the end, measured in slices (1/4 beats). | + +## Audio Visual Buzzer moves + +### buzzer_note + +Play a note from the Audio Visual System Buzzer for the duration of the move. + +| Parameter | Effect | +| --------- | ---------------------------------------------------------------------------------------------------------- | +| note | The musical note that will be played. | +| sharp | If true, raises the note by a half step, or semitone. If both sharp and flat are true, there is no effect. | +| flat | If true, lowers the note by a half step, or semitone. If both sharp and flat are true, there is no effect. | +| octave | The octave of the note. | diff --git a/docs/concepts/choreography/robot_controls_in_choreographer.md b/docs/concepts/choreography/robot_controls_in_choreographer.md index 0dd37c978..724080918 100644 --- a/docs/concepts/choreography/robot_controls_in_choreographer.md +++ b/docs/concepts/choreography/robot_controls_in_choreographer.md @@ -12,10 +12,8 @@ Robots can either be connected to Choreographer before starting the application To connect your robot to Choreographer, start Choreographer from the command line with arguments: - --hostname {IP/Hostname of your Spot} --user {Username you use to log in to your Spot} --password {Password for your Spot} - To connect multiple Spots at once include additional command line arguments, one set for each Spot. To connect your robot after the application has been started @@ -34,18 +32,18 @@ Choreographer supports connections to multiple robots. In the Robot Management T The **Robot Controls** bar is disabled if there are no robots connected to Choreographer. If a robot is connected to Choreographer, the buttons will have the following effects: -Button | Function -----|---- -Power Off| Powers off Spot’s motors. Always press Power off before approaching the robot. -Power On | Powers on your Spot’s motors. You must activate this before your Spot can stand or start choreography. -E-Stop | Enables or disables your Spot’s E-Stop. In an emergency, use this to stop the Spot immediately. -Self-Right | If your Spot has fallen, self-righting causes the robot to attempt to return to the sitting pose. -Sit | Sits the Spot in-place. Cancels all current choreography and music. E-Stop and Power Off can still be used in an emergency. -Stand | Brings Spot to a stand. Cancels all current choreography and music. E-Stop and Power Off can still be used in an emergency. -Enable Joystick | Activates joystick controls (see Joystick controls section) -Enable WASD Driving | Activates WASD keyboard driving (see WASD Controls section) -Return To Start | Spot walks from its current location to the last location it started a dance (either a full choreography or the move preview dance). -Start Choreography | Sends a choreography sequence to the robot, then starts a 3 second countdown before the robot begins dancing. Any loaded music will automatically start as soon as Spot begins to dance. +| Button | Function | +| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Power Off | Powers off Spot’s motors. Always press Power off before approaching the robot. | +| Power On | Powers on your Spot’s motors. You must activate this before your Spot can stand or start choreography. | +| E-Stop | Enables or disables your Spot’s E-Stop. In an emergency, use this to stop the Spot immediately. | +| Self-Right | If your Spot has fallen, self-righting causes the robot to attempt to return to the sitting pose. | +| Sit | Sits the Spot in-place. Cancels all current choreography and music. E-Stop and Power Off can still be used in an emergency. | +| Stand | Brings Spot to a stand. Cancels all current choreography and music. E-Stop and Power Off can still be used in an emergency. | +| Enable Joystick | Activates joystick controls (see Joystick controls section) | +| Enable WASD Driving | Activates WASD keyboard driving (see WASD Controls section) | +| Return To Start | Spot walks from its current location to the last location it started a dance (either a full choreography or the move preview dance). | +| Start Choreography | Sends a choreography sequence to the robot, then starts a 3 second countdown before the robot begins dancing. Any loaded music will automatically start as soon as Spot begins to dance. | Note: **Return to Start** brings all selected robots back to their starting position after completing a choreography. If multiple robots are being controlled, obstacle avoidance is enabled when they are navigating back to the starting position. To adjust this obstacle padding distance (in meters) the command line argument `--obs-padding DIST_IN_METERS` can be added to the Choreographer command line. @@ -53,18 +51,18 @@ Note: **Return to Start** brings all selected robots back to their starting posi  -An Xbox gamepad controller can be used with the GUI for moving and positioning the robot. The button layout is set up for Xbox 360 controllers. Xbox controllers are connected to a computer using a USB port. Many of the buttons in the GUI are linked to gamepad buttons, and the gamepad button will behave the same as the corresponding GUI button. As shown in the diagram above they are: +An Xbox gamepad controller can be used with the GUI for moving and positioning the robot. The button layout is set up for Xbox 360 controllers. Xbox controllers are connected to a computer using a USB port. Many of the buttons in the GUI are linked to gamepad buttons, and the gamepad button will behave the same as the corresponding GUI button. As shown in the diagram above they are: -Button | Function -----|----- -A | Stop -B | Enable joystick -X | Start choreography -Y | Stand -Left-Bumper | Self-right -Right-Bumper | Sit -Start | Power on -Back | Power off +| Button | Function | +| ------------ | ------------------ | +| A | Stop | +| B | Enable joystick | +| X | Start choreography | +| Y | Stand | +| Left-Bumper | Self-right | +| Right-Bumper | Sit | +| Start | Power on | +| Back | Power off | When the joystick is enabled by tapping the **B** button on the gamepad or using the GUI button, the robot walks and can be driven using the joysticks. As shown in the diagram above, the left joystick controls translation. The right joystick controls yaw. @@ -82,22 +80,21 @@ When enabled, the robot can be driven using the WASD keys. Joystick mode is disa When the robot is controlled through any of the other Robot Controls buttons, WASD driving is disabled. Other keypresses still work. - -Key | Function -----|----- -v | Enable WASD mode -b | Enable joystick mode -k | Power on -l | Power off -y | Stand -x | Start choreography -[ | Sit -] | Self-right -w | Walk forward -a | Strafe left -s | Walk backwards -d | Strafe right -q | Turn left -e | Turn right +| Key | Function | +| --- | -------------------- | +| v | Enable WASD mode | +| b | Enable joystick mode | +| k | Power on | +| l | Power off | +| y | Stand | +| x | Start choreography | +| [ | Sit | +| ] | Self-right | +| w | Walk forward | +| a | Strafe left | +| s | Walk backwards | +| d | Strafe right | +| q | Turn left | +| e | Turn right | Select **Hotkeys Documentation** from the Help menu to view a keystroke mapping table. diff --git a/docs/concepts/data.md b/docs/concepts/data.md index 3013b0f59..abb84faa3 100644 --- a/docs/concepts/data.md +++ b/docs/concepts/data.md @@ -6,14 +6,15 @@ is subject to the terms and conditions of the Boston Dynamics Software Development Kit License (20191101-BDSDK-SL). --> -# Spot Data +# Spot Data + This sections describes various concepts on how data is captured, stored and retrieved in Spot services. ## Contents -* [Data Acquisition Overview](data_acquisition_overview.md) -* [Data Acquisition Output](data_acquisition_output.md) -* [Integrate Payloads with the API](writing_services_for_data_acquisition.md) -* [Data Buffer Overview](data_buffer_overview.md) -* [BDDF File Format](bddf.md) -* [Thermal Raw Data Format](data_acquisition_thermal_raw.md) +- [Data Acquisition Overview](data_acquisition_overview.md) +- [Data Acquisition Output](data_acquisition_output.md) +- [Integrate Payloads with the API](writing_services_for_data_acquisition.md) +- [Data Buffer Overview](data_buffer_overview.md) +- [BDDF File Format](bddf.md) +- [Thermal Raw Data Format](data_acquisition_thermal_raw.md) diff --git a/docs/concepts/data_acquisition_output.md b/docs/concepts/data_acquisition_output.md index 71aa7cab4..2f671c21b 100644 --- a/docs/concepts/data_acquisition_output.md +++ b/docs/concepts/data_acquisition_output.md @@ -8,11 +8,12 @@ Development Kit License (20191101-BDSDK-SL). # Data Acquisition Output - The data stored from data acquisition captures can be downloaded over a REST endpoint from the robot. When downloading the data, the result will be returned in a zip file containing all data that matches the particular query parameters sent to the endpoint. +The data stored from data acquisition captures can be downloaded over a REST endpoint from the robot. When downloading the data, the result will be returned in a zip file containing all data that matches the particular query parameters sent to the endpoint. ## Zip file structure An example zip file with data from both a teleoperation session and a run of a mission named "Inspection": + ``` downloaded_file.zip └───teleop_2020-10-29T183020Z @@ -33,7 +34,6 @@ downloaded_file.zip ... ``` - Each separate group from the stored data will be in its own directory. The directory name will be the `group_name`, formatted as `
- 4.0.3
+ 4.1.0