Command Dictionary

Grabs control of an Astrobee.

The Astrobee control station implements the RAPID access control protocol, which includes the following steps:

1. Use Admin.requestCookie to get a unique cookie.
2. Use this Admin.grabControl command to grab control. Include the cookie received in step 1.

The RAPID access control protocol exists to prevent accidental contention between different operators. Each robot can be under the control of at most one control station at a time. The robot will reject most commands from other control stations, but a few exceptions are made for commands that might be urgently needed to safe the system: any control station can send the Mobility.stopAllMotion and Mobility.idlePropulsion commands. A single control station can grab control of multiple robots, for example, to manage multi-robot guest science. Note that guest science apps running onboard the robot do not need to grab control of the robot to send commands; there is no mechanism to prevent contention between a guest science app and a control station.

Requests a cookie that can be used to grab control of an Astrobee via the AccessControl.grabControl command.

For internal use only. Places the robot in a fault state. This command can only be sent by Astrobee's onboard executive or system monitor nodes. The executive will reject the command if it comes from any other source.

Calibrates the bias parameters of Astrobee's IMU.

Astrobee's IMU biases slowly drift over time. While Astrobee is actively running its localization system and maintaining a position fix, its EKF automatically corrects for bias drift under the assumption that the local environment is inertially fixed. If the localization system is turned off or loses its fix for an extended period, this command should be used to explicitly calibrate the biases prior to restarting motion. It works by integrating the robot's linear acceleration and angular velocity for about five seconds, and taking the resulting average values as the new zero. During the calibration period, the robot must remain stationary (e.g. docked or perched on a handrail, not held by an astronaut).

This command is intended to load a ROS nodelet in the Astrobee flight software. Please note, the underlying system monitor service can't load nodelets that run on the HLP.

Does nothing. Returns a 'success' response if you have control of the robot. This command may be useful for debugging communication or access control issues.

Switches Astrobee's localization to use the general-purpose pipeline.

This command is equivalent to calling Admin.switchLocalization with the "MappedLandmarks" pipeline and then calling Admin.resetEKF. It could be useful as a way to manually recover localization if Astrobee is lost because it is using the wrong localization pipeline (e.g., if docking or perching approach got interrupted, and targets are no longer in view).

Resets the EKF component of Astrobee's localization.

This command discards the EKF state and forces the localization system to acquire a new fix. It should not be needed unless the localization system has failure modes where it gets persistently stuck with invalid state information. (Unfortunately, as of 10/2020, that is a frequent occurrence.)

This rarely used command manually switches between localization pipelines. Normally, Astrobee switches its localization pipeline automatically based on what activity it is conducting (normal free flight, docking, perching, etc.).

Note that, although Astrobee could logically integrate information from multiple pipelines at the same time (e.g., NavCam sparse map features as well as DockCam AR targets), at present, it only uses data from one of these pipelines at a time. IMU information is always integrated, regardless of which pipeline is used. While switching pipelines from A to B, updates from A stop, then there may be a dropout period of a few seconds before B acquires a fix. During the dropout period, localization relies solely on the IMU.

This command is intended to unload a ROS nodelet in Astrobee's flight software. Its primary use is in the system monitor's fault response table, where it is the usual response if initialization of a nodelet fails. Please note, the internal service can't unload nodes running on the HLP.

Clears the terminate flag on the robot. This functionality is tied to Astrobee's physical terminate button and terminate indicator LED. The terminate life cycle is as follows:

• Nominal ops: When Astrobee is active, the amber terminate LED is turned on and the robot functions normally.
• Terminate: A crew member may press the terminate button as a way to quickly power down the propulsion modules and payloads, while leaving the main processors running and able to communicate with the ground operator. This is a gentler way to intervene than turning off the physical power switch. While terminated, the terminate LED is also turned off.
• Unterminate: The ground operator can send this command to clear the terminate flag and turn the terminate LED back on. This does not automatically restore power to the hardware.
• Configure power: Send Power.powerOnItem commands as needed to restore power to individual hardware components.

Wakes an Astrobee from a hibernating state (only EPS powered) by powering up the main processors. This command is intended to also automatically start the flight software stack such that Astrobee is ready to receive Astrobee API commands, but that feature is not implemented.

The Astrobee in question must be docked. Because each wake command is routed through a dock berth, which Astrobee to wake is specified using the berth number.

See also Admin.wakeSafe. The difference between Admin.wake and Admin.wakeSafe is that Admin.wake is intended to automatically start the flight software stack. Since that feature is not implemented, at present, the two commands are equivalent.

Note: For context about how to wake an Astrobee on the ISS, see the procedure IRG-FFTEST207a Astrobee Quick Wakeup and Checkout.

Wakes Astrobee from a hibernating state (only EPS powered) into a safe state (main processors powered, available to log in for debugging, but flight software stack not started).

The Astrobee in question must be docked. Because each wake command is routed through a dock berth, which Astrobee to wake is specified using the berth number. See also Admin.wake.

Moves Astrobee's arm.

The arm has two joints. The tilt joint is used to deploy/stow the arm and adjust the SciCam tilt angle while perched. The pitch joint is used to adjust the SciCam pan angle while perched.

The (pan, tilt) = (0, 0) reference position is defined to have the arm fully deployed and aligned with the robot's -X axis. If perched on a handrail on an ISS wall, this position should nominally make the SciCam camera axis point directly toward the opposite wall. Increasing the tilt angle tilts the SciCam up, and increasing the pan angle pans the SciCam to the right. The arm's stowed position is (pan, tilt) = (0, 180).

The arm joints will be moved sequentially:

1. Pan: If which is "Pan" or "Both", pan to the specified pan angle.
2. Tilt: If which is "Tilt" or "Both", tilt to the specified tilt angle.

Naturally, if you prefer to tilt first, you can issue a tilt-only move, followed by a pan-only move.

Some mistakes to avoid include:

• While the arm is partially within its payload bay (tilt > 90), the pan angle must be 0 to avoid the arm colliding with its payload bay.
• While the arm is close to its fully stowed state (tilt > 160), the gripper must be closed to avoid colliding with the arm's payload bay.
• While perched, the nominal tilt range of motion is restricted to -20 .. +90.
• While perched, the arm may not be able to realize its full nominal range of motion without causing Astrobee's body to collide with the wall. The actual range of motion depends on clutter and how far the handrail projects from the wall.

Deploys arm. The motion sequence is:

1. Pan to 0
2. Tilt to 0

See also Arm.armPanAndTilt for more discussion of the arm.

Opens or closes gripper.

Astrobee's arm has a passively under-actuated gripper with a single motor. Opening the gripper commands the motor to pull on a pair of tendons that open the fingers. Closing the gripper cuts power to the motor; the fingers are spring-loaded to close. The first time the gripper opens, it calibrates the motor encoder position by fully opening until the fingers contact a hard stop, then relaxes slightly to its nominal open position. On later open cycles, it opens directly to the nominal open position. Note that the motor consumes significant power holding the gripper open, so it should be closed when not actively in use. Holding it open for extended periods (minutes) runs the risk of triggering a motor overtemperature fault, which disables the motor.

Stops arm motion by commanding it to hold its current joint positions. Does not affect the gripper.

Stows arm. The motion sequence is:

1. Close gripper
2. Pan to 0
3. Tilt to 180

See also Arm.armPanAndTilt for more discussion of the arm.

Sets the data-to-disk configuration, which specifies how to log ROS telemetry topics to the robot's onboard storage.

The configuration is specified in a JSON-formatted file that contains a list of topic entries. For each logged topic, one specifies:

• frequency: Throttles the maximum rate at which to record messages on the topic. Specify -1 to disable throttling. Note: Currently, throttling is not implemented. You must specify -1.
• downlinkOption: Which log to store messages in, which must be "Immediate" or "Delayed". The intent is that the "Immediate" log is for high-priority data, which can then be prioritized for downlink after the activity. Note: Currently, you must specify "Delayed" ("Immediate" downlink is currently reserved for internal use by the flight software stack).

Sample data-to-disk configuration files can be found in astrobee_ops/gds/ControlStationConfig.

The Astrobee control station implements the protocol for managing onboard telemetry recording:

1. Uplink a new data-to-disk file using the RAPID compressed file protocol over DDS. (File uplink is not considered a command, so it does not appear in this command dictionary).
2. Send this Data.setDataToDisk command to load the uplinked file. Any errors in the file will be reported at this time.
3. Use the Data.startRecording / Data.stopRecording commands to start / stop onboard telemetry logging.

Starts logging ROS telemetry to onboard storage. See Data.setDataToDisk.

Stops logging ROS telemetry to onboard storage, as initiated by Data.startRecording. See also Data.setDataToDisk.

Routes a custom command to a guest science app (APK) running on the Astrobee HLP.

For the convenience of the control station operator, each guest science app can define what custom commands it supports in a configuration file read by the control station. See astrobee_ops/gds/ControlStation/PlanEditorGuestScience.config.

See GuestScience.startGuestScience for more on the guest science life cycle.

This command is the equivalent to issuing the stop guest science command and then the start guest science command. Sometimes guest science APKs become unresponsive and this is a quick way to try to get it work again.

See GuestScience.startGuestScience for more on the guest science life cycle.

Starts a guest science app (APK) running on the Astrobee HLP. This command is part of the guest science app life cycle, implemented by the guest science manager node on the HLP. Steps of the life cycle include:

• startGuestScience: Starts a guest science app, making it available to receive commands.
• customGuestScience: Routes a command to a running guest science app.
• stopGuestScience: Terminates a running guest science app.

Terminates a guest science app (APK) running on the Astrobee HLP. See GuestScience.startGuestScience.

For expert use only. Returns Astrobee to its dock.

As originally envisioned, this operation could be commanded from anywhere on the ISS, and Astrobee would plan a collision-free path back to the dock. Auto-return could also be invoked as an automatic response to a low-battery fault. To avoid contention for dock berths when multiple Astrobees are in use, each Astrobee should return to the same berth it originally departed from.

However, using this command is not recommended at this time, because (1) it has not been sufficiently tested (including testing of the QP trajectory planner), (2) at present, the proper berth selection logic is not implemented; instead, Astrobee will always return to berth 1 (= left).

Docks Astrobee at the specified berth. Preconditions: Astrobee must be near the dock approach point for the specified berth, the berth approach path must not be blocked, and the dock AR tags must not be occluded.

The nominal docking sequence is as follows:

1. Switch to the "MappedLandmarks" localization pipeline (the default for general-purpose navigation).
2. Coarsely correct positioning at dock approach point, ensuring dock AR tags are in view.
3. Switch to "ARTags" localization pipeline (uses AR tags on dock for more accurate dock-relative localization).
4. Fine-tune positioning at dock approach point.
5. Complete the docking approach, which should end with Astrobee magnetically retained on the berth, with power and data pins in contact.
6. Check magnetic retention by attempting to fly away from the dock. Lack of motion indicates success.
7. Idle propulsion.
8. Disable localization system.

Idles the propulsion impeller motors.

Astrobee will lose control authority. If it is not grounded in some way (docked or perched), it will drift uncontrolled. Note that the impellers have significant inertia, and may take several seconds to spin down.

This command is usually invoked automatically (e.g., at the end of successful docking or perching). It can also be used as a fault response (e.g., responding to an overspeed fault).

Perches Astrobee on a handrail. The robot must already be near the appropriate perch approach point for the desired perch location, with the handrail in view of the PerchCam.

The nominal perching sequence is as follows:

1. Switch to the "Handrail" (handrail-relative) localization pipeline.
2. Fine-tune positioning at perch approach point.
3. Deploy arm.
4. Open gripper.
5. Move until handrail is in contact, within gripper capture box.
6. Close gripper.
7. Confirm grasp by attempting to fly away from the handrail. Lack of motion indicates success.
8. Idle propulsion.

Manually spins up the propulsion modules, so that a future motion command can execute without a spin-up delay. This command is rarely used. Normally, you would just command the desired motion and the spin-up would be triggered automatically if needed. This command is intended to help with synchronizing motion of multiple Astrobees, but that scenario hasn't really been tested.

Moves the robot to the specified pose.

Using the default trapezoidal planner, the move works as follows:
- If holonomic mode is disabled (usual case), the robot will sequentially (1) rotate to face the target position, (2) translate to the target position while facing forward, (3) rotate to the target attitude.
- If holonomic mode is enabled, the robot will simultaneously translate along a straight line to the target position while rotating to the target attitude.

Stops motion of the mobility system and the arm.

Stopping the mobility system means transitioning to active station keeping (the propulsion system is activated if needed). The arm is stopped as in Arm.stopArm (the joints are commanded to maintain their current position, and the gripper is not affected).

Note that there is special behavior when this command is issued by the system monitor as a fault response: in that case, idled propulsion will not be activated. The special behavior ensures that when responding to multiple faults with different responses configured (stopAllMotion vs. idlePropulsion), the idlePropulsion response takes priority.

Undocks Astrobee.

The nominal undocking sequence is as follows:

1. Switch to the "MappedLandmarks" localization pipeline (the default for general-purpose navigation).
2. Spin up impellers.
3. Command the dock berth retention magnets to retract, releasing Astrobee. (They will automatically re-extend after a fixed time delay.)
4. Move to the dock approach point. (Note: Astrobee attempts to move immediately, without waiting for the berth magnets to fully retract.)

Unperches Astrobee from a handrail.

The nominal unperching sequence is as follows:

1. Switch to "MappedLandmarks" localization pipeline (the default for general-purpose navigation).
2. Spin up impellers.
3. Open gripper, releasing the handrail.
4. Move to perch approach point.
5. Stow arm, as in Arm.stowArm.

Pauses the running plan. The currently executing command will be aborted (equivalent to Mobility.stopAllMotion), and execution of subsequent commands will be delayed until the plan is resumed with a Plan.runPlan command. See plan.setPlan.

Runs the currently loaded plan. If the plan was previously paused with Plan.pausePlan, this command will resume execution where it previously left off. See plan.setPlan.

Loads the most recently uplinked plan.

An Astrobee plan is specified as a JSON-formatted fplan file that contains a list of stations (locations to visit), segments (trajectories for flying between stations), and commands to execute at stations. Plans are generated using the control station plan editor. Sample fplan files can be found in the astrobee/astrobee/plans folder.

The Astrobee control station implements the protocol for managing plans:

1. Uplink a new fplan file using the RAPID compressed file protocol over DDS. (File uplink is not considered a command, so it does not appear in this command dictionary).
2. Send this Plan.setPlan command to load the uplinked fplan file. Any errors in the fplan will be reported at this time. Once the plan is loaded, it is initially in the 'paused' state.
3. Use the Plan.runPlan / Plan.pausePlan commands to start / stop plan execution. Note that after a plan is paused using Plan.pausePlan, Plan.runPlan will resume plan execution at the beginning of the first plan step that was not fully completed. In the case that a trajectory segment is paused partway through, resuming the plan will cause the robot to fly back to the beginning of the segment and execute the whole segment again. If this behavior is not desired, you can use Plan.skipNextStep.

Other related commands include:

• Plan.skipNextStep: Skips the next step of the currently loaded (and paused) plan.
• Plan.wait: Same as Plan.pausePlan, but execution will resume automatically after the specified wait duration.

Skips the next step of the currently loaded plan (the step could be a trajectory segment or a command at a station). The plan must be paused. See plan.setPlan.

Temporarily pauses the running plan. This command only affects plan execution, not individual teleoperated commands. Plan execution will resume automatically after the specified duration. See plan.setPlan.

Powers off a component within Astrobee. Note: to turn flashlights on or off, see Settings.setFlashlightBrightness.

Powers on a component within Astrobee. Note: to turn flashlights on or off, see Settings.setFlashlightBrightness.

Starts the Astrobee intercommunication software. This enables the robot to send and receive a subset of data to and from other Astrobees in the network. Please note, this command must be executed on each robot needed in the communication.

Sets camera parameters.

The Astrobee camera control life cycle is as follows:

• When the Astrobee flight software stack is started, recording and streaming are initially disabled for all cameras, and the default camera parameters are as specified in the astrobee/config/cameras.config file.
• For each camera, while recording and streaming are disabled, you may use this Settings.setCamera command to adjust its parameters.
• For each camera, you may enable/disable recording imagery to onboard storage using Settings.setCameraRecording.
• For each camera, you may enable/disable live imagery downlink using Settings.setCameraStreaming.

Sets camera video onboard recording on/off.

Note: For the SciCam, this command actually enables independent recording of H.264 compressed video. For other cameras, this command enables publishing image frames to a topic designated for onboard recording together with other telemetry, but you also need to double-check that the Settings.setDataToDisk configuration will actually log that telemetry topic.

See Settings.setCamera for context.

Sets camera streaming live video to the ground on/off.

The SciCam streams H.264 compressed video via RTSP. All other cameras publish independent image frames via DDS.

See Settings.setCamera for context.

Enables/disables obstacle checking

Enables/disables keepout zone checking. See Settings.setZones.

Not implemented. This commmand is intended to enable/disable auto-return to the dock, under the assumption that auto-return will eventually be configured in Astrobee's fault table as the automatic fault response for a low-battery fault. The flag is currently ignored because auto-return has not been sufficiently tested and is not used in the fault table. See Mobility.autoReturn.

For expert use only. Changes the semantics of how Astrobee executes fplan trajectory segments.

A segment specifies the motion trajectory between stations in the plan. Within the segment, desired pose and velocity are smoothly interpolated functions of time over a time interval [t0, t1]. Plans created by the Astrobee control station plan editor always specify each segment's time values relative to the start of that segment's execution (i.e. t0 = 0). These plans must be executed in immediate mode, so called because when execution reaches a new segment, the executive and choreographer immediately 'start the clock' on executing the timed trajectory. In principle, if you want to synchronize motion of multiple robots, it could be useful to have the interval [t0, t1] specified using absolute timestamps. That is the behavior when immediate mode is disabled. The timestamp t0 is interpreted as absolute time using ROS conventions (usually UNIX epoch when running on real hardware, but could be any arbitrary time scale when running in simulation), and the start of motion on the segment would be delayed until the current time t = t0.

At this time, we cannot recommend disabling immediate mode to achieve synchronization, due to the following concerns: (1) execution with absolute timestamps has never really been tested, and may be buggy, (2) the control station plan editor doesn't provide any way to generate segments with absolute timestamps, (3) since it is seldom possible to predict exactly when ISS conditions will be right to begin a multi-robot activity, it would be awkward in practice to have the exact absolute timing of segments hard-coded into the plans.

As an alternative way to synchronize motion, you can execute with immediate mode enabled as usual, but take special care to minimize any skew in start time. Upload the plans in advance, use the Mobility.prepare command to get the robots ready to move, and then run the plans simultaneously. Astrobee to Astrobee communication is in the works, and may eventually enable synchronizing Astrobees in a better way.

Allows Astrobee to re-plan if it detects an obstacle too close to its forward trajectory. Enabling replanning only makes sense when you are using a planner that is able to plan around obstacles. (See Setting.setPlanner. As of 5/2021, only the QP planner can plan around obstacles).

Set the exposure value for either the nav or dock camera.

Sets flashlight brightness.

Enables/disables holonomic mode.

Holonomic mode is sometimes called 'blind flying' because it relaxes the constraint to always point the HazCam in the direction of motion while translating in order to enable obstacle detection. When holonomic mode is enabled, the default trapezoidal planner will simultaneously translate to the target position and rotate to the target attitude.

Sets mass and inertia parameters for Astrobee control.

The default inertial parameters for each robot are stored in an onboard configuration file, and should not need to be changed as long as the Astrobee remains in its baseline configuration (four batteries and no payloads installed). However, the inertial parameters may vary when the robot configuration changes. Examples are when a payload is installed or reconfigured (like deploying the arm). When configuration changes for a planned activity are known in advance, the standard management approach is to specify them in the inertiaConfig field of the relevant fplan. This command provides the same parameter update capability, but with more flexibility as to when it is applied (for example, you can change in the middle of a plan, during teleoperation, or when commanded by a guest science app).

Sets the map used for localization.

Changes the value of Astrobee operating limits

Switches which trajectory planner is used when Astrobee needs to generate a trajectory to reach a target pose. Astrobee uses its trajectory planner when it receives a teleoperation motion command. However, when an fplan is generated by the Astrobee control station plan editor, it normally contains pre-computed trajectories for its motion segments; when Astrobee executes these fplans, the onboard trajectory planner is not used.

Changes the frequency at which one DDS telemetry topic is published.

Loads the most recently uplinked keepout zones file.

The Astrobee control station implements the protocol for managing keepout zones:

1. Uplink a new keepout zone file using the RAPID compressed file protocol over DDS. (File uplink is not considered a command, so it does not appear in this command dictionary).
2. Send this Settings.setZones command to load the uplinked zones file. Any errors in the file will be reported at this time.
3. Use the Settings.setCheckZones command to enable/disable keepout zone checking.