API Reference

Revision as of 19:35, 6 January 2017 by Swang (talk | contribs) (Sensors+)
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

Cuff Buttons

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


The head LEDs and navigator LED

(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).

Navigator LEDs

(See: Navigator Lights)

/lights/cuff_command /lights/cuff_state /lights/halo