API Reference

Revision as of 23:04, 4 January 2017 by Swang (talk | contribs) (Inputs and Outputs)
Jump to: navigation , search

This page serves as a lookup reference for all the hardware and functionality for the SDK. The main interface of the SDK is via ROS Topics and Services, which you will find listed and described below along with other core information needed to interface with the robot.


Enable Robot

Be sure that you 'Enable' the robot before attempting to control any of the motors. The easiest method for controlling the robot is to use the enable_robot.py ROS executable found in the following example.

Robot Description (URDF)

Sawyer automatically builds an appropriate URDF (Unified Robot Description Format) on boot and loads it onto the ROS Parameter Server, under the ROS parameter name /robot_description. From here, it is accessible by rviz, tf and other ROS utilities that use the URDF. If you want to grab a copy of the actual URDF xml file yourself, see the How To's.



Sawyer has 7 joints (DoF) in arm and one more joint in its head (side-to-side panning). The control for the head is done separately from the arm; however, you can read the current joint states (position, velocity, and effort) for all the joints on arm and head by subscribing to one topic: /robot/joint_states (sensor_msgs-JointState) where the units for the position of a joint are in (rad), the units of velocity are in (rad/s) and the units of effort in each joint is in (Nm).

The following sections cover the individual joint sensing and control in more detail:

Cartesian Endpoint

Published at 100 Hz, the endpoint state topic provides the current Cartesian Position, Velocity and Effort at the endpoint for either limb.

The following sections covered the endpoint state and IK Solver in more detail:

Gripper (End-Effector)

Before using an End-Effector, or Gripper, you must first send the calibration command. You can check whether the gripper has been calibrated yet by echoing on the gripper state topic for that hand. Once calibrated, gripper can be controlled using the simplified command_grip and command_release topics, or using the more direct command_set topic. For more information on using the gripper, see the Gripper Example Program.

The following sections cover the gripper configuration, gripper state and simple gripper control in more detail:



Multiple sensors are included inside of the Sawyer Robot.


You can access Sawyer's hand camera and the head camera using the standard ROS image types and image_transport mechanism. You can use the ROS Services to open, close, and configure each of the cameras. See the link below for more info:

Head Display Screen

Images can be displayed on Sawyer's LCD screen by publishing the image data. For detailed info regarding the head display, please see:

Inputs and Outputs


There are two Navigators on Sawyer's body: one on side of the body and one on the arm. Each Navigator is comprised of three push buttons, one of which is also an indexing scroll wheel, and one set of white LED light.

Component IDs:
head_navigator, right_navigator

Shoulder Buttons

There are two shoulder buttons on the back of the torso, one on each side. The state of each button is published in a DigitalIOState message under its own topic (DigitalIOState constants: PRESSED==1, UNPRESSED==0).

Component IDs:
left_shoulder_button, right_shoulder_button

Read Button Pressed
/robot/digital_io/<side>_shoulder_button/state (baxter_core_msgs-DigitalIOState)

  • The integer field state will read PRESSED (1) when the button is pressed down, and UNPRESSED (0) otherwise.

Cuff Buttons

There are two buttons and one touch sensor in the cuff of each hand. The state of each button is published in a DigitalIOState message under its own topic (DigitalIOState constants: PRESSED==1, UNPRESSED==0).

Cuff (Squeeze) Sensor

Component IDs:
left_lower_cuff, right_lower_cuff

Read Cuff Squeezed
/robot/digital_io/<side>_lower_cuff/state (baxter_core_msgs-DigitalIOState)

  • Integer state will read PRESSED (1) when the cuff sensor is squeezed, and UNPRESSED (0) otherwise.

Cuff OK Button

This is the circular button on the cuff.
Component IDs:
left_lower_button, right_lower_button

Read OK Button Pressed
/robot/digital_io/<side>_lower_button/state (baxter_core_msgs-DigitalIOState)

  • Integer state will read PRESSED (1) when the button is pressed, and UNPRESSED (0) otherwise.

Cuff Grasp Button

This is the long, thin button on the cuff. Component IDs:
left_upper_button, right_upper_button

Read Grasp Button Pressed
/robot/digital_io/<side>_upper_button/state (baxter_core_msgs-DigitalIOState)

  • Integer state will read PRESSED (1) when the button is pressed, and UNPRESSED (0) otherwise.


(Head) Halo LEDs

The 'Halo' light is the red/green light at the top of Baxter's head. The Halo is actually two separate lights - one for the red, one for the green - whose intensity levels can be independently controlled and mixed to produce a range of colors.

Control Light Brightness
/robot/sonar/lights/set_red_level (std_msgs-Float32)
/robot/sonar/lights/set_green_level (std_msgs-Float32)

  • Set the brightness level of the red or green light using a value between 0.0 (full off) and 100.0 (full on).

Read Current Light Levels
/robot/sonar/head_sonar/lights/red_level (std_msgs-Float32)
/robot/sonar/head_sonar/lights/green_level (std_msgs-Float32)

  • Brightness ranges from 0.0 (full off) to 100.0 (full on).

Sonar LED Indicators

The yellow LEDs surrounding each sonar sensor on the head default to automatically being turned on or off when something enters/leaves the respective sensor's range. This behavior can be overridden by publishing on the control topic below. The published value should be the bit-wise OR of the desired mode and state for the 12 individual LEDs. The two modes are Normal (sensor-based) operation, and Manual Override. See the definitions below. Note: Make sure you constantly publish the values at rate of at least 100Hz or the LEDs will timeout and revert to Normal operation.

To set the LEDs, pick one of the 'Mode's and OR it with any of the individual LED States desired:

   # Mode 
   OVERRIDE_ENABLE  = 0x8000;
   # States 
   ALL_LIGHTS_OFF   = 0x8000;
   ALL_LIGHTS_ON    = 0x0fff;
   LED_0_ON     0x0001
   LED_1_ON     0x0002
   LED_2_ON     0x0004
   LED_3_ON     0x0008
   LED_4_ON     0x0010
   LED_5_ON     0x0020
   LED_6_ON     0x0040
   LED_7_ON     0x0080
   LED_8_ON     0x0100
   LED_9_ON     0x0200
   LED_10_ON    0x0400
   LED_11_ON    0x0800
   LED_ALL_ON   0x8FFF
   LED_ALL_OFF  0x8000

Control Lights /robot/sonar/head_sonar/lights/set_lights (std_msgs-UInt16)

  • If bit 15 is zero, LEDs are controlled locally by Sonar.
  • Set bit 15 to enable overrides, bits 0-11 to control individual channel LEDs.
  • To use these flags, OR the OVERRIDE_ENABLE flag with the desired x_ON flags.

State of Lights /robot/sonar/head_sonar/lights/state (std_msgs-UInt16)

Navigator LEDs

(See: Navigator Lights)

Digital IO

Read Digital Input State
/robot/digital_io/<component_id>/state (baxter_core_msgs-DigitalIOState)

  • state: field will be 0 (for True, Pressed, On) or 1 (for False, Released, Off). If the component is an output, then the state field will be the current setting of the output.
  • isInputOnly: field tells you if the component is an input (sensor) only, and cannot output (not a light, actuator, nor indicator).

Control Digital Output /robot/digital_io/command (baxter_core_msgs-DigitalOutputCommand)

  • name: <component_id>
  • value: {True, False}
  • Publish a DigitalOutputCommand message with the component id of the Output as the name and a value of True or False to turn the Output On or Off, respectively.

All Digital Component IDs:
Nav Inner Lights: left_itb_light_inner, right_itb_light_inner, torso_left_itb_light_inner, torso_right_itb_light_inner
Nav Outer Lights left_itb_light_outer, right_itb_light_outer, torso_left_itb_light_outer, torso_right_itb_light_outer
Configure Valves: left_blow, right_blow, left_suck, right_suck
Actuate Pneumatics: left_pneumatic, right_pneumatic
Camera Power: left_hand_camera_power, right_hand_camera_power, torso_camera_power
(Analog) Raw IR Range Values: left_hand_range, right_hand_range
Back Shoulder Buttons: left_shoulder_button, right_shoulder_button
Cuff (Squeeze) Sensor: left_lower_cuff, right_lower_cuff
Cuff OK Button: left_lower_button, right_lower_button
Cuff Grasp Button: left_upper_button, right_upper_button
Safety Mat 'is attached': torso_process_sense0
Safety Mat 'is NOT actuated': torso_safety_stop


Baxter is equipped with a pneumatic valve system that can be controlled independently on the left and right sides and fed to proper grippers for suction-based picking.   

Configure Valves

Blow Component IDs: left_blow, right_blow /robot/digital_io/<side>_blow/state (baxter_core_msgs-DigitalIOState)

  • Use to switch on/off the suck valve -- (does not activate suction).
  • Use this setting to grip objects in most cases.

Suck Component IDs: left_suck, right_suck /robot/digital_io/<side>_suck/state (baxter_core_msgs-DigitalIOState)

  • Use to switch off the blow valve -- (does not activate suction).
  • Use this setting to release objects in most cases.

Actuate Pneumatics

Turn On/Off Pneumatic Pressure/Airflow Component IDs: left_pneumatic, right_pneumatic /robot/digital_io/<side>_pneumatic/state (baxter_core_msgs-DigitalIOState)

  • This is how to use the pneumatic message.

Camera Power

Component IDs: left_hand_camera_power, right_hand_camera_power, torso_camera_power /robot/digital_io/<location>_camera_power/state (baxter_core_msgs-DigitalIOState)

Analog IO

(Analog) Input State /robot/analog_io/<component_id>/state (baxter_core_msgs-AnalogIOState)

  • value: is an integer often either rounded up from the hundreds decimal place or going from [0-100]

(Analog) Output Control /robot/analog_io/command ([1])

  • name: <component_id>
  • value: [0-65535] - (uint16)
  • Publish a AnalogOutputCommand message with the component id of the Output as the name and a uint16 value from [0-65535].

All Analog Component IDs
Workspace Lights: torso_lighting
Torso Fan: torso_fan
(Analog) Raw IR Range Values: left_hand_range, right_hand_range
Vacuum Sensor: left_vacuum_sensor_analog, right_vacuum_sensor_analog

Torso Fan

Component IDs: torso_fan Control Fan Speed /robot/analog_io/command (baxter_core_msgs-AnalogOutputCommand)

  • value: [0-100] power to the fan:
  • (0 = Auto, 1 = Off, 100 = Full-on)
  • Auto: Automatic control by hardware, based on torso board heatsink.

Fan State /robot/analog_io/torso_fan/state (baxter_core_msgs-AnalogIOState)

  • value: Current fan setting [0.0-100.0]

(Analog) Raw IR Range Values

Values are shifted by 3 decimal points (essentially in mm). Component IDs: left_hand_range, right_hand_range

Standard Integer Value /robot/analog_io/<side>_hand_range/value_uint32 (std_msgs-UInt32)
Analog Stamped State /robot/analog_io/<side>_hand_range/state (baxter_core_msgs-AnalogIOState)

Vacuum Sensor

Component IDs: left_vacuum_sensor_analog, right_vacuum_sensor_analog
Standard Integer Value /robot/analog_io/<side>_vacuum_sensor_analog/value_uint32 (std_msgs-UInt32)
Analog Stamped State /robot/analog_io/<side>_vacuum_sensor_analog/state (baxter_core_msgs-AnalogIOState)