The Control URL is a URL on each robot that allows app choosers to start and stop the robot with ease. The control URL is accessed over HTTP GET. We currently use CGI scripts to implement our control URL.

States

Robot can be in three states: STATE_VALID, STATE_OFF, and STATE_IN_USE. In STATE_VALID, the applications platform is running correctly and is ready to be accessed by the app chooser. In STATE_OFF, no ROS related processes are running on the robot, and the applications platform may be launched at any time. In STATE_IN_USE, the robot is running ROS but not the applications platform, which occurs when users run custom code on the robot.

Actions

Control URL has three actions. These are specified by appending "?action=..." to the control URL specified in the robot configuration. The three actions are: STOP_ROBOT, START_ROBOT and GET_STATE. All the commands return a page that is line-delimited. Certain lines must be present for each command, but additional lines may also be present that should be ignored by the app chooser. The additional lines may be useful for debugging. See the next sections for more details.

STOP_ROBOT

STOP_ROBOT stops all currently running ROS processes. We generally use ckill to achieve this. Be warned that there is no guarantee that the ROS processes share any given characteristic, so we recommend using white list approach instead of a black list approach. The STOP_ROBOT command does not need to print anything to the HTTP request on completion, however it needs to complete in a reasonable time.

START_ROBOT

START_ROBOT starts the robot and launches the applications platform. It generally consists of a roslaunch command. We recommend using nohup to launch the command in the background so that it won't be terminated when CGI script is done. The START_ROBOT command does not need to print anything to the HTTP request on completion, however it needs to complete while the robot is running

GET_STATE

GET_STATE prints the state of the robot. It must not modify the robot state in any way. The GET_STATE command has very specific requirements of what it must print out to the HTTP request. The GET_STATE command must interact with the ROS system to find out which state the robot is in. In a STATE_VALID state, the GET_STATE command must simply print a line with STATE_VALID. In a STATE_OFF state, the GET_STATE command must print a line with STATE_OFF. In a STATE_IN_USE state, the GET_STATE command must print a line with STATE_IN_USE, however, it must also print two other lines. It must print a line with "USER: <user-name>" where user name is the user of the robot. It optionally may print a line with "MESSAGE: <message>" where message is a message left by the current user of the robot. The lines must have no leading whitespace.

Example

For a demonstration please see the PR2 Control URL implementation.