The creation of the RobotOpen Protocol is an effort to design an open, standardized protocol for communication and control of hobbyist robots over an IP based network. It is designed for simple and lightweight two-way communication. This version of the RobotOpen protocol supersedes any prior documentation and is used in all current RobotOpen software.
By default, any robot controller implementing the RobotOpen protocol should be disabled and inactive upon powerup. At any point that no packets are received for a timeout period (typically 100-200 milliseconds), the robot should also disable itself. All RobotOpen protocol data is currently intended to traverse an IP based network, specifically utilizing UDP on the transport layer. The RobotOpen protocol is stateless. Every packet should be treated individually and does not rely on any specific ordering.
Parameters are semi-permanent values intended to be stored in non-volatile EEPROM memory onboard the Robot. These values can be read from the robot and updated from the Driver Station when the robot controller is disabled. Currently RobotOpen protocol supports the following types listed below. Each parameter has a unique address assigned to it (a number between 0 and 99). Parameters are always transmitted as 4 bytes, even if their size is less than 4. Additional bytes should be set to 0. For instance a boolean that is true would be transmitted as 0xFF000000 in a parameter packet. Values are transmitted in big endian format (most significant byte first).
Driver Station to Robot Packets¶
Currently the RobotOpen protocol supports up to four control devices (each having a fixed size of 24 bytes, totalling 96 bytes of control data) per packet. These 24 bytes have specified names but arbitrary data can be inserted and interpreted on the robot controller.
Control (Enable) Packet¶
A control packet must contain at least one controller’s worth of data. This means that a control packet can be 27, 51, 75, or 99 bytes long. Control packets with no joystick data will be dropped on the robot side. A CRC-16 of the packet is calculated and appended on the end. When a valid control packet is received on the robot side, the robot will enable itself.
Heartbeat (Disable) Packet¶
Heartbeat packets are used to disable the robot but keep communications active. All heartbeat packets are 3 fixed bytes, show below.
Set Parameter Packet¶
The robot must be disabled for the parameters to be successfully set. Multiple parameters may be transmitted in each set parameter packet. Each parameter will consume 5 bytes (address + 4 data bytes).
Get Parameters Packet¶
A get parameters packet requests the robot controller to transmit all current parameters and their values back to the Driver Station. All get parameters packets are 3 fixed bytes, shown below.
Robot to Driver Station Packets¶
Robot to Driver Station packets can be transmitted at any time. While a robot controller is disabled (heartbeat packets being sent), it should continue to receive debug and dashboard packets regularly. Parameter packets will be received any time requested.
Debug packets allow for arbitrary ASCII data to be sent to the Driver Station (a sort of remote serial console). Debug packets begin with the byte 0x70 followed by a variable number of ascii bytes.
A dashboard packet contains values that a user has published from their robot code so that they can monitor them remotely on their Driver Station. The supported types can be seen above. Unlike parameters, dashboard values are exactly their specified length in the packet. Every dashboard value in a dashboard packet begins with a length (the length of that dashboard value including the length byte). The type will be one of the type codes listed below. The appropriate number of bytes will follow based on the value’s type. The ID is a variable length ascii name for the value.
A parameters packet is sent back upon the reception of a get parameters packet. Each parameter in the parameters packet begins with a length (the length of the parameter including the length byte). This is followed by the unique parameter address (0-99). The type follows that (reference the parameter type codes below). 4 bytes will follow, however based on the type the non-used bytes will be zeroes. The ID is a variable length ascii name for the parameter.