Messaging

This section provides information for communicating with the modular robot via UDP.

Message Format

  • Each message starts with a 3-Byte header. The structure of the header is described in section Header and is the same for all messages.
  • The header is directly followed by a payload of various lenght carrying the actual message content. The formatting of the payload for different message types is described in section Payload.
  • A valid message has a minimum lenght of 4 Bytes taking into account header and payload.
  • A valid message has a maximum length of 508 Bytes taking into account header and payload.

Value Encoding

Endianness

  • In the context of messaging, all transmitted values (including Position Values) are encoded in Network Byte Order.

Position Values

  • All position values are encoded as 32-Bit signed integers for transmission.

Angular Values

  • Angular position values are encoded in nano radians divided by pi for transmission. This applies to joint angles of revolving joints as well as orientation values of poses in Cartesian space.
  • Formula for conversion to SI units: q_{rad} = q_{transmitted} \cdot 1 \times 10^{-9} \cdot \pi ~ rad

Linear Values

  • Linear position values are encoded in micrometers (\mu m) for transmission. This applies to joint values of prismatic joints as well as position values in Cartesian space.
  • Formula for conversion to SI units: q_m = q_{transmitted} \cdot 1 \times 10^{-6} ~ m

Payload

  • The message payload is directly appended to the 3-Byte message header as indicated in section Header.
  • Messages whose type name starts with GET_ originate from the robot.
  • Messages whose type name starts with SET_ are intended to be sent to the robot.

SET_JOINT_ABS (ID: 0x01)

  • Message Type: 0x01
  • Use the message type SET_JOINT_ABS to command the robot to move to an absolute position in joint space.
Byte 0 1 2 3 4
Meaning Point Sequence Number Approach Mode Approach Velocity Approach Acceleration Number of Joints
Data Type Unsigned Int Unsigned Int Unsigned Int Unsigned Int Unsigned Int
5 6 7 8 … …
Value Joint 0 … Value Joint n
Signed Int Signed Int Signed Int
  • Point Sequence Number is an arbitrary sequence number for identifying the waypoint specified in this message.
  • Approach Mode specifes how to approach the waypoint specified in this message. Available values are 1 for a point-to-point motion and 2 for a linear motion.
  • Approach Velocity specifies the permitted velocit for approaching the waypoint specified in this message where 0 equals 0% of the maximum available velocity and 255 equals 100% of it.
  • Approach Acceleration specifies the permitted acceleration for approaching the waypoint specified in this message where 0 equals 0% of the maximum available acceleration and 255 equals 100% of it.
  • Number of Joints specifies how many joint values are transmitted in this message.
  • Value Joint x is the desired absolute joint value for robot joint x. Counting starts at the joint mounted closest to the robot base. The encoding of joint values follows the schemes given in sections Angular Values and Linear Values, respectively.

Note

The value in Number of Joints doesn’t necessarily have to equal the number of joints present in the actual robot. Excess joint values will be ignored. Joints above Number of Joints will keep their positions.

GET_JOINT_ABS (ID: 0x02)

  • Message Type: 0x02
  • Messages of type GET_JOINT_ABS provide information on the current absolute position of the robot in joint space.
Byte 0 1 2 3 4
Meaning Number of Joints Value Joint 0
Data Type Unsigned Int Signed Int
… …
… Value Joint n
Signed Int Signed Int
  • Number of Joints specifies how many joint values are transmitted in this message.
  • Value Joint x is the current actual absolute joint value of robot joint x. Counting starts at the joint mounted closest to the robot base. The encoding of joint values follows the schemes given in sections Angular Values and Linear Values, respectively.

SET_JOINT_OFFS (ID: 0x03)

  • Message Type: 0x03
  • Use the message type SET_JOINT_OFFS to command the robot to move relatively in joint space by a given offset.
Byte 0 1 2 3 4
Meaning Number of Joints Offset Joint 0
Data Type Unsigned Int Signed Int
… …
… Offset Joint n
Signed Int Signed Int
  • Number of Joints specifies how many joint value offsets are transmitted in this message.
  • Offset Joint x is the desired relative joint value offset for robot joint x. Counting starts at the joint mounted closest to the robot base. The encoding of joint value offsets follows the schemes given in sections Angular Values and Linear Values, respectively.

Warning

This message type is intended to be used for jogging. Do not use messages of this type for approaching predefined absolute positions. Depending on the robot state, individual messages of this type may be ignored or discarded at any time.

Note

The robot follows requested offsets very directly. Requesting too large offsets in a single message may result in jerky movement of the robot or may trigger safety mechanisms due to exceeded limits. Send messages frequently with only small offsets in each message to acheive smooth movements of the robot. The ideal frequency is at 100 Hz.

Note

The value in Number of Joints doesn’t necessarily have to equal the number of joints present in the actual robot. Excess joint value offsets will be ignored. Joints above Number of Joints will keep their positions.

SET_POSE_ABS (ID: 0x05)

  • Message Type: 0x05
  • Use the message type SET_POSE_ABS to command the robot to move its endeffector to an absolute pose in Cartesian space.
Byte 0 1 2 3 4
Meaning Point Sequence Number Approach Mode Approach Velocity Approach Acceleration Number of Dimensions
Data Type Unsigned Int Unsigned Int Unsigned Int Unsigned Int Unsigned Int
5 6 7 8 9 10
Value Position x Value Position y …
Signed Int Signed Int …
11 12 13 14 15 16
… Value Position y Value Position z
… Signed Int Signed Int
17 18 19 20 21 22
Value Orientation z Value Orientation y …
Signed Int Signed Int …
23 24 25 26 27 28
… Value Orientation y Value Orientation x
… Signed Int Signed Int
  • Point Sequence Number is an arbitrary sequence number for identifying the waypoint specified in this message.
  • Approach Mode specifes how to approach the waypoint specified in this message. Available values are 1 for a point-to-point motion and 2 for a linear motion.
  • Approach Velocity specifies the permitted velocit for approaching the waypoint specified in this message where 0 equals 0% of the maximum available velocity and 255 equals 100% of it.
  • Approach Acceleration specifies the permitted acceleration for approaching the waypoint specified in this message where 0 equals 0% of the maximum available acceleration and 255 equals 100% of it.
  • Number of Dimensions specifies how many dimnesional values are transmitted in this message. Currently onyl fully specified cartesian waypoints with values given for all 6 dimensions are supported so set this to 6.
  • Value Position x is the x-component of the desired absolute Cartesian position. The encoding of position values follows the scheme given in section Linear Values.
  • Value Position y is the y-component of the desired absolute Cartesian position.
  • Value Position z is the z-component of the desired absolute Cartesian position.
  • Value Orientation z is the z-component of the desired absolute Cartesian orientation given in zyx Euler angles. The encoding of orientation values follows the scheme given in section Angular Values.
  • Value Orientation y is the y-component of the desired absolute Cartesian orientation given in zyx Euler angles.
  • Value Orientation x is the x-component of the desired absolute Cartesian orientation given in zyx Euler angles.

GET_POSE_ABS (ID: 0x06)

  • Message Type: 0x06
  • Messages of type GET_POSE_ABS provide information on the current absolute pose of the robot’s endeffector in Cartesian space.
Byte 0 1 2 3 4
Meaning Number of Dimensions Value Position x
Data Type Unsigned Int Signed Int
5 6 7 8 9 10
Value Position y Value Position z …
Signed Int Signed Int …
11 12 13 14 15 16
… Value Position z Value Orientation z
… Signed Int Signed Int
17 18 19 20 21 22
Value Orientation y Value Orientation x …
Signed Int Signed Int …
23 24
… Value Orientation x
… Signed Int
  • Number of Dimensions specifies how many dimnesional values are transmitted in this message. Currently onyl fully specified cartesian waypoints with values given for all 6 dimensions are supported so set this to 6.
  • Value Position x is the x-component of the current actual absolute Cartesian position. The encoding of position values follows the scheme given in section Linear Values.
  • Value Position y is the y-component of the current actual absolute Cartesian position.
  • Value Position z is the z-component of the current actual absolute Cartesian position.
  • Value Orientation z is the z-component of the current actual absolute Cartesian orientation given in zyx Euler angles. The encoding of orientation values follows the scheme given in section Angular Values.
  • Value Orientation y is the y-component of the current actual absolute Cartesian orientation given in zyx Euler angles.
  • Value Orientation x is the x-component of the current actual absolute Cartesian orientation given in zyx Euler angles.

SET_POSE_OFFS (ID: 0x03)

  • Message Type: 0x07
  • Use the message type SET_POSE_OFFS to command the robot to move relatively in Cartesian space by a given offset.
Byte 0 1 2 3 4
Meaning Number of Dimensions Offset Position x
Data Type Unsigned Int Signed Int
5 6 7 8 9 10
Offset Position y Offset Position z …
Signed Int Signed Int …
11 12 13 14 15 16
… Offset Position z Offset Orientation z
… Signed Int Signed Int
17 18 19 20 21 22
Offset Orientation y Offset Orientation x …
Signed Int Signed Int …
23 24
… Offset Orientation x
… Signed Int
  • Number of Dimensions specifies how many dimensional values are transmitted in this message. Currently onyl fully specified cartesian waypoints with values given for all 6 dimensions are supported so set this to 6.
  • Offset Position x is the x-component of the desired Cartesian position offset. The encoding of position offsets follows the scheme given in section Linear Values.
  • Offset Position y is the y-component of the desired Cartesian position offset.
  • Offset Position z is the z-component of the desired Cartesian position offset.
  • Offset Orientation z is the z-component of the desired Cartesian orientation offset given in zyx Euler angles. The encoding of orientation offsets follows the scheme given in section Angular Values.
  • Offset Orientation y is the y-component of the desired Cartesian orientation offset given in zyx Euler angles.
  • Offset Orientation x is the x-component of the desired Cartesian orientation offset given in zyx Euler angles.

Warning

This message type is intended to be used for jogging. Do not use messages of this type for approaching predefined absolute positions. Depending on the robot state, individual messages of this type may be ignored or discarded at any time.

Note

The robot follows requested offsets very directly. Requesting too large offsets in a single message may result in jerky movement of the robot or may trigger safety mechanisms due to exceeded limits. Send messages frequently with only small offsets in each message to acheive smooth movements of the robot. The ideal frequency is at 100 Hz.

GET_MOTION_DONE (ID: 0x11)

  • Message Type: 0x11
  • A Messages of type GET_MOTION_DONE provides information that a waypoint the robot was previously commanded to move to has been reached.
Byte 0
Meaning Point Sequence Number
Data Type Unsigned Int
  • Point Sequence Number is the sequence number associated with the waypoint that has been reached.

SET_OUTPUT (ID: 0x20)

  • Message Type: 0x20
  • Use the message type SET_OUTPUT to command the robot to set an (analog or digital) output to a given value.
Byte 0 1 2 3 4 5 6 7
Meaning Address Value
Data Type Unsigned Int (Unsigned) Int
  • Address specifies the address of the output to be set.
  • Value is the value to be set for the addressed output signal.

Note

The value field may be interpreted as singed or unsigned depending on the type of the addressed output.

Note

For digital outputs the value 0 equals inactive whereas values of 1 and above are interpreted as active.

GET_INPUT (ID: 0x21)

  • Message Type: 0x21
  • A Messages of type GET_INPUT provides information on the values of all (analog and digital) inputs of the robot.
Byte 0 1 2 3 4
Meaning Number of Values Value Input 0
Data Type Unsigned Int (Unsigned) Int
… 5 6 7 8
… Value Input n
… (Unsigned) Int
  • Number of Values specifies how many input values are transmitted in this message.
  • Value Input x is the current value present at input x.

Note

Each value field may be interpreted as singed or unsigned depending on the type of the corresponding input.

Note

For digital inputs the value 0 equals inactive whereas values of 1 and above are interpreted as active.

GET_OUTPUT (ID: 0x23)

  • Message Type: 0x23
  • A Messages of type GET_OUTPUT provides information on the values of all (analog and digital) outputs of the robot.
Byte 0 1 2 3 4
Meaning Number of Values Value Output 0
Data Type Unsigned Int (Unsigned) Int
… 5 6 7 8
… Value Output n
… (Unsigned) Int
  • Number of Values specifies how many output values are transmitted in this message.
  • Value Output x is the current value present at output x.

Note

Each value field may be interpreted as singed or unsigned depending on the type of the corresponding output.

Note

For digital outputs the value 0 equals inactive whereas values of 1 and above are interpreted as active.

SET_G_COMPENSATION (ID: 0x41)

  • Message Type: 0x41
  • Use the message type SET_G_COMPENSATION to command the robot to temporarily enter gravity compensation mode where the robot can be moved by external force.
Byte 0
Meaning Mode
Data Type Unsigned Int
  • Mode determines the desired mode of gravity compensation. As of now, the only valid value for this field is 0. In this mode the robot is freely moveable while repsecting joint limits.

Note

Gravity compensation mode is volatile by implementation. Send messages frequently to keep gravity compensation enabled. The ideal frequency is at 100 Hz. To disable gravity compensation mode again just stop sending messages of type 0x41.

GET_STATUS (ID: 0x50)

  • Message Type: 0x50
  • Messages of type GET_STATUS provide information on the current status and operating condition of the robot and carry additional user-mapped information.
Byte 0 1 2 3
Meaning Status Rx Sequcence No. Rx Result Last Reached Waypoint
Data Type Signed Int Unsigned Int Signed Int Unsigned Int
4 5 6
Last Error Status Sequence No. Last Error Status Mapped Data ID
Unsigned Int Signed Int Unsigned Int
7 8 …
Mapped Data Length Mapped Data
Unsigend Int …
  • Status provides information on the current status and operating conditions. Positive values indicate ordinary operation while negative values indicate error conditions. See section Status Codes for further details.
  • Rx Sequence No. is the sequence number associated with the last message that has been received.
  • Rx Result is the processing status of the message specified by Rx Sequence No.. Negative values indixate an error while positive values indicate success.
  • Last Reached Waypoint is the sequence number associated with the waypoint that has been reached.
  • Last Error Status Sequence No. is a sequence number that changes every time a new error status appears.
  • Last Error Status carries the last error status that appeared. Formatting is the same as for the field Status.
  • Mapped Data ID determines what information is transported in the Mapped Data field and how to interpret it. See Mapped Data for valid ID values and their meanings.
  • Mapped Data Length determines the length of the Mapped Data field following in this message.
  • Mapped Data contains the actual mapped data. The format of this field depends on the information mapped to this field in accordance to the contents of the field Mapped Data ID and is given in section Mapped Data.

SET_MAPPED_STATUS_DATA (ID: 0x55)

  • Message Type: 0x55
  • Use the message type SET_MAPPED_STATUS_DATA to modify which information is transported in the Mapped Data fields of messages of the type GET_STATUS.
Byte 0 1
Meaning Mapped Data Slot Mapped Data ID
Data Type Unsigned Int Unsigned Int
  • Mapped Data Slot specifies the data slot of the messagign cycle to be modified. There are currently 4 slots per messaging cycle. Counting of the slots starts from 0.
  • Mapped Data ID specifies which data are mapped to the data slot specified in the field Mapped Data Slot. Valid values are given in section Mapped Data.

Note

See section Messaging Procedure for more details on the messaging cycle.

SET_STOP (ID: 0xEE)

  • Message Type: 0xEE
  • Use the message type SET_STOP to command the robot to stop all current and pending actions.
Byte 0
Meaning RFU
Data Type Unsigned Int
  • RFU — reserved for future usage. Set to 0 for for consistent behavior with future versions.

Messaging Procedure

  • When ready and initialized, the robot controller starts to transmit position and status information.
  • The robot controller accepts commands approximately 1 second after it starts to transmit position and status messages.
  • See section Payload for the available message types and their payload formats.
  • When a motion to absolute coordinates is requested using a message of the type SET_JOINT_ABS or SET_POSE_ABS, the robot controller reports when a requested position is reached by sending a message of the type GET_MOTION_DONE containing the ID of the relevant waypoint.
  • Absolute motion requests (relevant message types: SET_JOINT_ABS, SET_POSE_ABS) are queued and executed in the order they are received by the robot contoller.
  • Relative motion requests (relevant message types: SET_JOINT_OFFS, SET_POSE_OFFS) are not queued by the robot controller. They are either directly executed or discarded.
  • The robot cylclically transmits position and status information using the following message type sequence with a temporal distance of 2 milliseconds between the start of two consecutive messages: GET_JOINT_ABS, GET_STATUS, GET_POSE_ABS, GET_STATUS, GET_INPUT, GET_STATUS, GET_OUTPUT, GET_STATUS. The data in each of the GET_STATUS slots of the messaging cycle can be modifyed by sending messages with the SET_MAPPED_STATUS_DATA (ID: 0x55) payload to the robot controller. The default mapping after startup is: UPTIME, JOINT_TORQUES, DETECTED_MODULES, JOINT_TORQUES
  • To avoid message loss, wait until the sequence number of the last transmitted message appears in a GET_STATUS (ID: 0x50) message sent by the robot controller before sending the next message to it.

Note

For simple test usage with no checking of received GET_STATUS (ID: 0x50) message payloads, keep a minimum temporal distance of 3 milliseconds between two consecutive messages sent to the robot controller to avoid unexpected beahvior. This is only permissible for supervised test operation and not for productive usage as individual commands may be dropped without further notice due to the characteristics of UDP this way.

Status Codes

The robot status is encoded in one byte. The status byte can be divided into the 3 sections Error Flag, Status Group, and Status Sub-Group.

Bit 7 6 5 4 3 2 1 0
Meaning Error Flag Status Group Status Sub-Group
  • Error Flag provides information about the general status of the robot where a value of 1 or true means Error and a value of 0 or false means OK.
  • Status Group encodes the current state of opertion of the robot as a 4 bit number. See section Status Groups and Sub-Groups for details.
  • Status Sub-Group provides detailed status information encoded as a 3 bit value. The meaning of the value in this field depends on the value in the field Status Group and may additionally depend on the value in the Field Error Flag. See section Status Groups and Sub-Groups for details.

Status Groups and Sub-Groups

For each status group there is a range of status sub-groups associated with the group. The status sub-group GENERIC (Value: 0x0) is special in that it is defined for all status groups and does not carry any more specific information.

STATUS_GROUP_GENERIC (Value: 0x0)

  • Value: 0x0
  • This status group does not carry any more specific status information.
  • Available sub-groups:
    • GENERIC (Value 0x0): No specific information.

STATUS_GROUP_IDLE (Value: 0x1)

  • Value: 0x1
  • The robot is in idle state.
  • Available sub-groups:
    • GENERIC (Value 0x0): No specific information.

STATUS_GROUP_RUN (Value: 0x2)

  • Value: 0x2
  • The robot is currently executing requested movements or other issued commands.
  • Available sub-groups:
    • GENERIC (Value 0x0): No specific information.
    • RUN_PTP (Value 0x1): The robot is currently executing a point-to-point movement.
    • RUN_LINEAR (Value 0x2): The robot is currently executing a linear movement.

STATUS_GROUP_JOG (Value: 0x3)

  • Value: 0x3
  • The robot is currently moving in jog mode.
    • GENERIC (Value 0x0): No specific information.
    • JOG_RECOVER (Value 0x1): The robot is outside the joint limits permitted for jogging. Only jog requests that do not move it further away from the permitted joint limits are executed.

STATUS_GROUP_G_COMPENSATED (Value: 0x4)

  • Value: 0x04
  • The robot is currently running in gravity compensation mode and can be moved by external force.
    • GENERIC (Value 0x0): No specific information.

Mapped Data

  • The following data can be mapped to the appropriete field in messages of the type GET_STATUS (ID: 0x50)

UPTIME (ID: 0x01)

  • Mapped Data ID: 0x01
  • The UPTIME data-field carries information on the runtime of the robot since the last reset.
Byte 0 1 2 3
Meaning Uptime
Data Type Unsigned Int
  • Uptime is the time elapsed since the last reset given in milliseconds.

Note

The value in Uptime will wrap every 49.71 days.

DETECTED_MODULES (ID: 0x02)

  • Mapped Data ID: 0x02
  • The DETECTED_MODULES data-field carries information on the detected robot modules making up the current robot.
Byte 0 1 2 3 4
Meaning Number of Modules ID Module 0
Data Type Unsigned Int Unsigned Int
… …
… ID Module n
Unsigned Int Unsigned Int
  • Number of Modules specifies how many robot module IDs are transmitted in this message.
  • ID Module x is the ID uniqely identifying the type of robot module x. Counting starts at the robot base.

JOINT_TORQUES (ID: 0x03)

  • Mapped Data ID: 0x03
  • The JOINT_TORQUES data-field provides information on the current torques exerted by the individual joints of the robot.
Byte 0 1 2 3 4 … …
Meaning Number of Joints Torque Joint 0 … Torque Joint n
Data Type Unsigned Int Signed Int Signed Int Signed Int
  • Number of Joints specifies how many joint torques are transmitted in this message.
  • Torque Joint x is the current actual output torque of robot joint x given in millinewton meters. Counting starts at the joint mounted closest to the robot base.