Primary and Secondary Interfaces

The UR controller provides servers that send robot state data and receive URScript commands. The primary interface transmits robot state data and additional messages. The secondary interface transmits robot state data only. The data is mainly used for communication between the GUI and the controller. Both accept URScript commands with state data updates at a 10 Hz rate. This makes it possible to control the robot remotely with a dynamically generated robot program.

TCP ports used by interfaces

• Primary client: port 30001 (Robot state and messages)

• Secondary client: port 30002 (Only robot state and the Version messages)

• Primary client read only: port 30011 (Robot state and messages)

• Secondary client read only: port 30012 (Only robot state and the Version messages)

Messages

Data sizes

Data Type	Size
int16_t	2 bytes
int32_t	4 bytes
float	4 bytes
double	8 bytes
bool	1 byte
uint8_t	1 byte

Array notation is used where the same type is repeated several times.

Example of fixed-length array: double DHa[6] — 6 doubles, 48 bytes total.

Example of variable-length array: char buildData[] — either the length is given as one of the fields, or the data spans until the end of the package.

Commands sent to Primary and Secondary interfaces

The primary interface accepts script commands. Typically, commands are aggregated into a complete program.

If remote control is intended to dynamically control part of the trajectory, it is recommended to use Interpreter Mode instead. Refer to the Script Manual for more information.

NOTE: Commands not documented in the Script Manual are used internally by UR software and are not backwards compatible.

Status messages sent to clients

All messages and sub-packages contain a length field at the beginning, followed by a type field.

NOTE: Future Polyscope versions may add additional fields to existing messages or sub-message types. Client code should be able to interpret partial messages and ignore the remaining data. Deprecated and reserved fields should not be used, as they can change content in future software releases.

Robot State Message

This message is sent periodically and contains multiple sub-packages.

Field	Description	Introduced in version
uint32_t messageSize	Length of overall package: total length of package including this field
uint8_t messageType	MESSAGE_TYPE_ROBOT_STATE = 16
Sub packages	One or more sub packages. Each contains size, type, and package specific data

Robot Mode Data (Sub Package of Robot State Message)

Field	Description	Introduced in version
uint32_t packageSize	Total length of subpackage including this field
uint8_t packageType	ROBOT_STATE_PACKAGE_TYPE_ROBOT_MODE_DATA = 0
uint64_t timestamp	Microseconds since controller started
bool isRealRobotConnected
bool isRealRobotEnabled
bool isRobotPowerOn
bool isEmergencyStopped
bool isProtectiveStopped
bool isProgramRunning
bool isProgramPaused
uint8_t robotMode	Robot Modes
uint8_t controlMode	Control Modes
double targetSpeedFraction
double speedScaling
double targetSpeedFractionLimit
uint8_t reserved	Internal use only

Joint Data (Sub Package of Robot State Message)

Field	Description	Introduced in version
uint32_t packageSize	Total length of subpackage including this field
uint8_t packageType	ROBOT_STATE_PACKAGE_TYPE_JOINT_DATA = 1
Following 8 fields are repeated for each joint (6 times)
→ double q_actual
→ double q_target
→ double qd_actual
→ float I_actual
→ float V_actual
→ float T_motor
→ float reserved	Deprecated — ignore
→ uint8_t jointMode	Joint Modes

Tool Data (Sub Package of Robot State Message)

Field	Description	Introduced in version
uint32_t packageSize	Total length of subpackage including this field
uint8_t packageType	ROBOT_STATE_PACKAGE_TYPE_TOOL_DATA = 2
uint8_t analogInputRange0
uint8_t analogInputRange1
double analogInput0
double analogInput1
float toolVoltage48V
uint8_t toolOutputVoltage
float toolCurrent
float toolTemperature
uint8_t toolMode	Tool Modes

Masterboard Data (Sub Package of Robot State Message)

Field	Description	Introduced in version
uint32_t packageSize	Total length of subpackage including this field
uint8_t packageType	ROBOT_STATE_PACKAGE_TYPE_MASTERBOARD_DATA = 3
uint32_t digitalInputBits
uint32_t digitalOutputBits
uint8_t analogInputRange0
uint8_t analogInputRange1
double analogInput0
double analogInput1
char analogOutputDomain0
char analogOutputDomain1
double analogOutput0
double analogOutput1
float masterBoardTemperature
float robotVoltage48V
float robotCurrent
float masterIOCurrent
uint8_t safetyMode	Safety Modes
bool inReducedMode
bool immiInterfaceInstalled	True if the IMMI interface is installed
Following 4 fields are present only if immiInterfaceInstalled is true
→ uint32_t immiInputBits
→ uint32_t immiOutputBits
→ float immiVoltage24V
→ float immiCurrent
uint32_t reserved	Used by Universal Robots software only
uint8_t operationalModeSelectorInput
bool threePositionEnablingDeviceInput
uint8_t reserved	Used by Universal Robots software only

Cartesian Info (Sub Package of Robot State Message)

Field	Description	Introduced in version
uint32_t packageSize	Total length of subpackage including this field
uint8_t packageType	ROBOT_STATE_PACKAGE_TYPE_CARTESIAN_INFO = 4
double X
double Y
double Z
double Rx
double Ry
double Rz
double TCPOffsetX
double TCPOffsetY
double TCPOffsetZ
double TCPOffsetRx
double TCPOffsetRy
double TCPOffsetRz

Kinematics Info (Sub Package of Robot State Message)

This information is sent upon leaving initialization mode and when the kinematics configuration has changed.

Field	Description	Introduced in version
uint32_t packageSize	Total length of subpackage including this field
uint8_t packageType	ROBOT_STATE_PACKAGE_TYPE_KINEMATICS_INFO = 5
uint32_t checksum[6]
double DHtheta[6]
double DHa[6]
double DHd[6]
double DHalpha[6]
uint32_t calibrationStatus

Configuration Data (Sub Package of Robot State Message)

This information is sent once after the client connection is established.

Field	Description	Introduced in version
uint32_t packageSize	Total length of subpackage including this field
uint8_t packageType	ROBOT_STATE_PACKAGE_TYPE_CONFIGURATION_DATA = 6
Following 2 fields are repeated for each joint (6 times)
→ double jointMinLimit
→ double jointMaxLimit
Following 2 fields are repeated for each joint (6 times)
→ double jointMaxSpeed
→ double jointMaxAcceleration
double vJointDefault
double aJointDefault
double vToolDefault
double aToolDefault
double eqRadius
double DHa[6]
double Dhd[6]
double DHalpha[6]
double DHtheta[6]
int32_t masterboardVersion
int32_t reserved	Deprecated
int32_t robotType	Robot Arm type
int32_t robotSubType

Force Mode Data (Sub Package of Robot State Message)

Field	Description	Introduced in version
uint32_t packageSize	Total length of subpackage including this field
uint8_t packageType	ROBOT_STATE_PACKAGE_TYPE_FORCE_MODE_DATA = 7
double Fx	Deprecated — always contains the value 0.0
double Fy	Deprecated — always contains the value 0.0
double Fz	Deprecated — always contains the value 0.0
double Frx	Deprecated — always contains the value 0.0
double Fry	Deprecated — always contains the value 0.0
double Frz	Deprecated — always contains the value 0.0
double robotDexterity

Additional Info (Sub Package of Robot State Message)

Field	Description	Introduced in version
uint32_t packageSize	Total length of subpackage including this field
uint8_t packageType	ROBOT_STATE_PACKAGE_TYPE_ADDITIONAL_INFO = 8
uint8_t tpButtonState
bool isManualFreedriveAllowed
bool isFreedriveIOPressed
uint8_t tpType	Teach Pendant Type

Calibration Data (Sub Package of Robot State Message, Internally Used Only)

This sub-package is used internally by UR software and should be ignored.

Field	Description	Introduced in version
uint32_t packageSize	Total length of subpackage including this field
uint8_t packageType	ROBOT_STATE_PACKAGE_TYPE_CALIBRATION_DATA = 9
uint32_t reserved	Used by Universal Robots software only

Safety Data (Sub Package of Robot State Message)

This sub-package is used internally by UR software and should be ignored.

Field	Description	Introduced in version
uint32_t packageSize	Total length of subpackage including this field
unsigned char packageType	ROBOT_STATE_PACKAGE_TYPE_SAFETY_DATA = 10
reserved	Used by Universal Robots software only

Tool Communication Info (Sub Package of Robot State Message)

Field	Description	Introduced in version
uint32_t packageSize	Total length of subpackage including this field
unsigned char packageType	ROBOT_STATE_PACKAGE_TYPE_TOOL_COMM_INFO = 11
bool toolCommunicationIsEnabled
int32_t baudRate
int32_t parity
int32_t stopBits
float RxIdleChars
float TxIdleChars

Tool Mode Info (Sub Package of Robot State Message)

Field	Description	Introduced in version
uint32_t packageSize	Total length of subpackage including this field
unsigned char packageType	ROBOT_STATE_PACKAGE_TYPE_TOOL_MODE_INFO = 12
uint8_t outputMode
uint8_t digitalOutputModePin0
uint8_t digitalOutputModePin1

Singularity Info (Sub Package of Robot State Message)

This sub-package is used internally by UR software and should be ignored. Package is sent only when robot is in freedrive mode with individual lockable axes.

Field	Description	Introduced in version
uint32_t packageSize	Total length of subpackage including this field
unsigned char packageType	ROBOT_STATE_PACKAGE_TYPE_SINGULARITY_INFO = 13
uint8_t singularitySeverity
uint8_t singularityType

Payload Info (Sub Package of Robot State Message)

This sub-package is used internally by UR software and should be ignored.

Field	Description	Introduced in version
uint32_t packageSize	Total length of subpackage including this field
unsigned char packageType	ROBOT_STATE_PACKAGE_TYPE_ACTIVE_PAYLOAD = 14
reserved	Used by Universal Robots software only

Internal Data (Sub Package of Robot State Message)

This sub-package is used internally by UR software and should be ignored.

Field	Description	Introduced in version
uint32_t packageSize	Total length of subpackage including this field
unsigned char packageType	ROBOT_STATE_PACKAGE_TYPE_INTERNAL_DATA = 15
reserved	Used by Universal Robots software only

Cumulative Runtime Data (Sub Package of Robot State Message)

Message is sent once per second.

Field	Description	Introduced in version
uint32_t packageSize	Total length of subpackage including this field	5.23.0 / 10.11.0
unsigned char packageType	ROBOT_STATE_PACKAGE_TYPE_CUMULATIVE_RUNTIME_DATA = 16	5.23.0 / 10.11.0
double robot_energy_consumed_Wh	Robot Arm energy consumption since controller startup [Wh].	5.23.0 / 10.11.0
double robot_braking_energy_dissipated_Wh	Robot Arm braking energy dissipated since controller startup [Wh]. This energy is flowing back into the Control Box and gets dissipated as heat.	5.23.0 / 10.11.0

Robot Message

There are several messages grouped under the “Robot Message” type. Note that sub-messages don’t contain their own size field; only the main message does. Each complete message contains exactly one sub-message.

Some messages are sent only to Primary Interface clients.

Version Message

This is the first package sent on both the primary and secondary client interfaces. Package is sent only once.

Field	Description	Introduced in version
uint32_t messageSize	Length of overall package: total length of package including this field
uint8_t messageType	MESSAGE_TYPE_ROBOT_MESSAGE = 20
uint64_t timestamp	Microseconds since controller started
int8_t source	Message Sources
char robotMessageType	ROBOT_MESSAGE_TYPE_VERSION = 3
char projectNameSize
char projectName[]
uint8_t majorVersion
uint8_t minorVersion
int32_t bugfixVersion
int32_t buildNumber
char buildDate[]

Safety Mode Message

The message is sent only to Primary Interface clients.

Field	Description	Introduced in version
uint32_t messageSize	Length of overall package: total length of package including this field
uint8_t messageType	MESSAGE_TYPE_ROBOT_MESSAGE = 20
uint64_t timestamp	Microseconds since controller started
int8_t source	Message Sources
uint8_t robotMessageType	ROBOT_MESSAGE_TYPE_SAFETY_MODE = 5
int32_t robotMessageCode
int32_t robotMessageArgument
uint8_t safetyModeType	Safety Mode Types
uint32_t reportDataType	Following data type depends on this value
	0,1:uint32_t 2:int32_t 3:float 4:uint32_t that should be displayed as HEX
→ type32 reportData

Robot Comm Message

The message is sent only to Primary Interface clients.

Field	Description	Introduced in version
uint32_t messageSize	Length of overall package: total length of package including this field
uint8_t messageType	MESSAGE_TYPE_ROBOT_MESSAGE = 20
uint64_t timestamp	Microseconds since controller started
int8_t source	Message Sources
uint8_t robotMessageType	ROBOT_MESSAGE_TYPE_ERROR_CODE = 6
uint32_t robotMessageCode
uint32_t robotMessageArgument
int32_t robotMessageReportLevel	Report Levels
uint32_t dataType	Following data type depends on this value
	0,1:uint32_t 2:int32_t 3:float 4:uint32_t that should be displayed as HEX
→ type32 reportData
	5:String
→ uint16_t textLength
→ char textMessage[]

Last field is 32-bit number for dataType (0-4) or variable length string for dataType 5.

Key Message

The message is sent only to Primary Interface clients.

Field	Description	Introduced in version
uint32_t messageSize	Length of overall package: total length of package including this field
uint8_t messageType	MESSAGE_TYPE_ROBOT_MESSAGE = 20
uint64_t timestamp	Microseconds since controller started
int8_t source	Message Sources
uint8_t robotMessageType	ROBOT_MESSAGE_TYPE_KEY = 7
uint32_t robotMessageCode
uint32_t robotMessageArgument
uint8_t robotMessageTitleLength
char robotMessageTitle[]
uint16_t keyTextMessageLength
char keyTextMessage[]

Program Threads Message

The message is sent only to Primary Interface clients.

Information about all running threads might be spread into multiple messages if threads have long names. Only threads that contain labeled lines are reported. Refer to script program generated by Polyscope UI for label examples.

Field	Description	Introduced in version
uint32_t messageSize	Length of overall package: total length of package including this field
uint8_t messageType	MESSAGE_TYPE_ROBOT_MESSAGE = 20
uint64_t timestamp	Microseconds since controller started
int8_t source	Message Sources
uint8_t robotMessageType	ROBOT_MESSAGE_TYPE_PROGRAM_LABEL_THREADS = 14
Following structure repeats for each running program thread
→ int32_t labelId	Last executed line label id
→ uint8_t labelNameLength
→ char labelName[]
→ uint16_t threadNameLength
→ char threadName[]

Request Value Message

The message is sent only to Primary Interface clients.

Field	Description	Introduced in version
uint32_t messageSize	Length of overall package: total length of package including this field
uint8_t messageType	MESSAGE_TYPE_ROBOT_MESSAGE = 20
uint64_t timestamp	Microseconds since controller started
int8_t source	Message Sources
uint8_t robotMessageType	ROBOT_MESSAGE_TYPE_REQUEST_VALUE = 9
uint32_t requestId
uint32_t requestedType	Requested Types
char requestTextMessage[]

Text Message

The message is sent only to Primary Interface clients.

Field	Description	Introduced in version
uint32_t messageSize	Length of overall package: total length of package including this field
uint8_t messageType	MESSAGE_TYPE_ROBOT_MESSAGE = 20
uint64_t timestamp	Microseconds since controller started
int8_t source	Message Sources
uint8_t robotMessageType	ROBOT_MESSAGE_TYPE_TEXT = 0
char textMessage[]

Runtime Exception Message

The message is sent only to Primary Interface clients.

Field	Description	Introduced in version
uint32_t messageSize	Length of overall package: total length of package including this field
uint8_t messageType	MESSAGE_TYPE_ROBOT_MESSAGE = 20
uint64_t timestamp	Microseconds since controller started
int8_t source	Message Sources
uint8_t robotMessageType	ROBOT_MESSAGE_TYPE_RUNTIME_EXCEPTION = 10
uint32_t scriptLineNumber
uint32_t scriptColumnNumber
char runtimeExceptionTextMessage[]

Global Variable Messages

Global Variables Setup Message

The message is sent only to Primary Interface clients.

List of global variables is sent once when program starts. Afterwards update messages are sent every 100ms. If there are more variable names than can fit into one message, multiple messages will be sent with incrementing startIndex.

Field	Description	Introduced in version
uint32_t messageSize	Length of overall package: total length of package including this field
uint8_t messageType	MESSAGE_TYPE_PROGRAM_STATE_MESSAGE = 25
uint64_t timestamp	Microseconds since controller started
uint8_t robotMessageType	PROGRAM_STATE_MESSAGE_TYPE_GLOBAL_VARIABLES_SETUP = 0
uint16_t startIndex
char variableNames[]	List of names separated by new line character (‘\n’ character).

Example with 2 global variables: “var_1\nvar_2\n”

Global Variables Update Message

The message is sent only to Primary Interface clients.

If values can not fit into one message, multiple messages will be sent with incrementing startIndex. Order of values is matching order of variable names sent in Global Variables Setup Message.

Field	Description	Introduced in version
uint32_t messageSize	Length of overall package: total length of package including this field
uint8_t messageType	MESSAGE_TYPE_PROGRAM_STATE_MESSAGE = 25
uint64_t timestamp	Microseconds since controller started
uint8_t robotMessageType	PROGRAM_STATE_MESSAGE_TYPE_GLOBAL_VARIABLES_UPDATE = 1
uint16_t startIndex
uint8_t variableValues[]

Each variable value contains type byte, data, and terminating new line character (‘\n’ character).

Example - two variables of type BOOL=True , and STRING=”aaaa”: 0c 01 0a 03 00 04 61 61 61 61 0a

0c	01	0a	03	00	04	61	61	61	61	0a
BOOL	1=True	Separator	STRING	Length LSB	Length MSB	‘a’	‘a’	‘a’	‘a’	Separator

Data types:

Name	Value	Description
NONE	0	No content
CONST_STRING	3	uint16_t length char string[]
VAR_STRING	4	uint16_t length char string[]
POSE	12	float x float y float z float rx float ry float rz
BOOL	13	uint8_t value
NUM	14	float value
INT	15	int32_t value
FLOAT	16	float value
LIST	17	uint16_t listLength Repeated for each list element → uint8_t type → value
MATRIX	18	uint16_t nRows uint16_t nCols Repeated for each matrix element → uint8_t type → value

Constants

Constants used in the protocol messages.

NOTE: Unlisted values are reserved for internal use.

Control Modes

Name	Value	Description
POSITION	0
TEACH	1
FORCE	2
TORQUE	3

Robot Modes

Name	Value	Description
DISCONNECTED	0	Connection with the safety control board is not established.
CONFIRM_SAFETY	1	Robot is validating and updating the safety settings.
BOOTING	2	Safety control board is booting up and its communication with the other components is being verified.
POWER_OFF	3	Robot is ready to boot up the joints.
POWER_ON	4	Robot’s joints are booting up.
IDLE	5	Robot’s joints are ready (to go to RUNNING or BACKDRIVE modes).
BACKDRIVE	6	Robot is in back-drive mode. It is possible to move the robot in a restricted way. Brakes are being released when needed.
RUNNING	7	Brakes are fully released. Robot is ready for running a program. In Polyscope, the current safety mode is shown.
UPDATING	8	Firmware is being updated
POWERING_OFF	9	Robot arm is powering off
ARM_BOOTING	10	Robot arm is booting
ARM_UPDATING	11	Robot arm is being firmware updated

Joint Modes

Same constants are used for Tool Mode.

Name	Value	Description
RESET	235
SHUTTING_DOWN	236
BACKDRIVE	238
POWER_OFF	239
READY_FOR_POWER_OFF	240
NOT_RESPONDING	245
MOTOR_INITIALISATION	246
BOOTING	247
VIOLATION	251
FAULT	252
RUNNING	253
IDLE	255

Message Sources

Name	Value	Description
JOINT_0_FPGA	100
JOINT_0_A	110
JOINT_0_B	120
JOINT_1_FPGA	101
JOINT_1_A	111
JOINT_1_B	121
JOINT_2_FPGA	102
JOINT_2_A	112
JOINT_2_B	122
JOINT_3_FPGA	103
JOINT_3_A	113
JOINT_3_B	123
JOINT_4_FPGA	104
JOINT_4_A	114
JOINT_4_B	124
JOINT_5_FPGA	105
JOINT_5_A	115
JOINT_5_B	125
TOOL_FPGA	106
TOOL_A	116
TOOL_B	126
IMMI_FPGA	107
IMMI_A	117
IMMI_B	127
TEACH_PENDANT_A	108
TEACH_PENDANT_B	118
BFB_FPGA	109
BFB_A	119
BFB_B	129
ExtenderNear_FPGA	70
ExtenderNear_MCU	71
ExtenderFar_FPGA	72
ExtenderFar_MCU	73
SCB_FPGA	40
UA	20
UB	30
ROBOTINTERFACE	-2
RTMACHINE	-3
SIMULATED_ROBOT	-4
GUI	-5
CONTROLLER	7
RTDE	8

Message Types

Name	Value	Description
ROBOT_STATE	16
ROBOT_MESSAGE	20
MODBUS_INFO_MESSAGE	5
PROGRAM_STATE_MESSAGE	25

Safety Statuses

Name	Value	Description
NORMAL	1
REDUCED	2
PROTECTIVE_STOP	3
RECOVERY	4
SAFEGUARD_STOP	5
SYSTEM_EMERGENCY_STOP	6
ROBOT_EMERGENCY_STOP	7
VIOLATION	8
FAULT	9
VALIDATE_JOINT_ID	10
UNDEFINED_SAFETY_MODE	11
AUTOMATIC_MODE_SAFEGUARD_STOP	12
SYSTEM_THREE_POSITION_ENABLING_STOP	13
TP_THREE_POSITION_ENABLING_STOP	14
IMMI_EMERGENCY_STOP	15
IMMI_SAFEGUARD_STOP	16
PROFISAFE_WAITING_FOR_PARAMETERS	17
PROFISAFE_AUTOMATIC_MODE_SAFEGUARD_STOP	18
PROFISAFE_SAFEGUARD_STOP	19
PROFISAFE_EMERGENCY_STOP	20
SAFETY_API_SAFEGUARD_STOP	22

Report Levels

Name	Value	Description
DEBUG	0
INFO	1
WARNING	2
VIOLATION	3
FAULT	4
CRITICAL_FAULT	5
DEVL_DEBUG	128
DEVL_INFO	129
DEVL_WARNING	130
DEVL_VIOLATION	131
DEVL_FAULT	132
DEVL_CRITICAL_FAULT	133

Requested Types

Name	Value	Description
BOOLEAN	0	Simple yes/no */
INTEGER	1	Integer
FLOAT	2	A script float (a double in c++/java) */
STRING	3	Text string
NONE	8	Popup

Robot Types

Name	Value	Description
UNDEFINED	0
UR5	1	Also UR7e
UR10	2	Also UR12e
UR3	3	UR3e
UR16	4	UR16e
UR18	5	UR18
UR8_LONG	6	UR8 Long
UR20	7	UR20
UR30	8	UR30
UR15	9	UR15

TP Types

Name	Value	Description
NONE	0
STANDARD	1
THREE_POSITION_ENABLING	2

Additional Resources

Product page for IMMI Module