Connecting a Universal Robots Cobot
How to read robot mode, safety status, joint angles, and TCP position from a Universal Robots cobot over the built-in Modbus/TCP server and map them into an ISA-95 style MQTT topic hierarchy.
This guide shows you how to read state data from a Universal Robots (UR) cobot with the Connectware Modbus/TCP connector and map it into an ISA-95 style MQTT topic hierarchy. Every UR control box ships with a built-in Modbus/TCP server, so you do not need to install anything on the robot. The values collected here (robot mode, safety status, joint angles, TCP position, and a program-defined cycle counter) are the typical input for cell dashboards, utilization monitoring, and condition monitoring. In more detail, the following topics are covered:
The built-in Modbus/TCP server of the UR control box
Identifying the Modbus registers for robot state, joint angles, and TCP position
Decoding signed values with the
int16BEdata typeConverting milli-radians to degrees with a transform rule
Creating the service commissioning file
Mapping the values into an ISA-95 style MQTT topic hierarchy
Verifying data in the Data Explorer
This guide focuses on the UR specifics. For a general introduction to the Modbus/TCP connector, including function codes and write operations, see Connecting & Integrating a Modbus/TCP Server.
A complete example file is available at the end of this guide.
Prerequisites
To follow this guide, you will need the following:
A running instance of Cybus Connectware.
A Universal Robots cobot that is reachable over Ethernet from Connectware. The register map in this guide applies to e-Series robots (for example, a UR10e) and CB-Series robots alike. The Modbus/TCP server is available on all CB3 and e-Series controllers, and on CB2 controllers from software 1.6 on.
Access to the Admin UI with sufficient user permissions.
Basic knowledge of MQTT and the Connectware services concept (for example, service commissioning files, connections, and endpoints).
The Built-In Modbus/TCP Server
The UR control box acts as a Modbus/TCP server on the standard port 502. Configure the network settings in PolyScope so that the robot has an IP address that Connectware can reach; the registers are then available without further configuration on the robot. The server supports the standard Modbus function codes for reading (1 to 4) and writing (5, 6, 15, and 16). This guide reads all values with function code 3.
UR controllers also offer the Real-Time Data Exchange (RTDE) interface, which streams the same robot state at higher rates in a proprietary format; Connectware does not support RTDE out of the box, so this guide uses the Modbus/TCP server.
Identifying the Modbus Registers
The register map of the server is fixed and identical across robot generations. It is documented in the Universal Robots support article Modbus server, which includes the complete register table as a download. Each value occupies exactly one 16-bit register. The following registers are used in this guide:
258
Robot mode
enum
260
isPowerOnRobot
0 or 1
261
isSecurityStopped
0 or 1
262
isEmergencyStopped
0 or 1
270
Base joint angle
mrad
271
Shoulder joint angle
mrad
272
Elbow joint angle
mrad
273
Wrist 1 joint angle
mrad
274
Wrist 2 joint angle
mrad
275
Wrist 3 joint angle
mrad
400
TCP x (base frame)
tenth of mm
401
TCP y (base frame)
tenth of mm
402
TCP z (base frame)
tenth of mm
128-255
General purpose
user-defined
On CB3 and e-Series controllers, the robot mode register reports the following values: 0 = Disconnected, 1 = Confirm safety, 2 = Booting, 3 = Power off, 4 = Power on, 5 = Idle, 6 = Backdrive, 7 = Running. CB2 controllers use a different value set for this register, which is listed in the same UR article. The isSecurityStopped register indicates a protective stop, isEmergencyStopped an emergency stop.
The register map provides more values that follow the same pattern as the endpoints in this guide: joint speeds (280 to 285, mrad/s), joint currents (290 to 295, mA), joint temperatures (300 to 305, °C), TCP orientation rx, ry, rz (403 to 405, mrad), and TCP speed (410 to 415). Register 266 reports the safety mode with the values documented in the UR Primary Interface manual, but is only available from PolyScope 5.14 on.
General Purpose Registers
Registers 128 to 255 are general purpose registers that the robot program can read and write with the URScript functions read_port_register() and write_port_register(). The fixed register map has no dedicated program state register, so use a general purpose register to expose program-level information, for example a cycle counter or the number of the active program step. A single line in the robot program, such as write_port_register(128, cycle_count), makes the value readable for Connectware. Because these registers are also writable over Modbus with function code 6, you can use them for data flowing towards the robot as well; see Connecting & Integrating a Modbus/TCP Server for write endpoints.
Handling Signed 16-Bit Values
UR documents all register values as unsigned 16-bit integers and leaves the signed interpretation to the client. Joint angles and TCP coordinates are signed quantities: a base joint moved to -90° reports -1571 mrad, which arrives on the wire as the unsigned value 63965. Set dataType: int16BE and Connectware decodes the register as a signed two's complement integer, so negative angles and coordinates arrive as negative JSON numbers without manual conversion. For registers that only report 0, 1, or small positive values, this guide uses uint16BE to make the intent explicit. For all available data types, see Modbus/TCP Endpoint Properties.
Writing the Service Commissioning File
The service commissioning file contains all connection and mapping details. Do not worry about copying the snippets together into one file, the complete example file is available at the end of this guide.
Description and Metadata
These sections contain general information about the service commissioning file. Only the metadata name is required.
Parameters and Definitions
We define the network address of the control box as parameters, so you can set them when you install the service. The default Modbus/TCP port is 502.
The MQTT topics in this guide follow an ISA-95 style equipment hierarchy with a cobot branch (<enterprise>/<site>/<area>/<line>/cobot). We define the prefix once in the definitions section and reuse it in every mapping with !sub.
Cybus::Connection
The connection resource establishes the Modbus/TCP connection to the control box. The connectionStrategy object controls how Connectware retries failed connection attempts with increasing delays. For all connection properties, see Modbus/TCP Connection Properties.
Robot State Endpoints
Each endpoint polls one register. The register address becomes address, and since every value occupies one register, length is always 1. The robot mode is decoded as int16BE because CB2 controllers report -1 for "No controller". The safety flags at addresses 260 to 262 only report 0 or 1 and use uint16BE; the following snippet shows one of them, the other two differ only in the address.
Joint Angle Endpoints with a Transform Rule
The joint angle registers report milli-radians, which is rarely the unit you want on a dashboard. A transform rule converts the value to degrees before Connectware publishes it: one milli-radian is 180 / (1000 × π) ≈ 0.0572957795 degrees. The JSONata expression keeps the message structure with timestamp and value intact and rounds the result to two decimal places.
The endpoints for the remaining five joints (addresses 271 to 275) are identical apart from the address and are included in the complete example file.
TCP Position Endpoints
The TCP position registers report tenths of millimeters in the base frame. The same transform rule pattern converts them to millimeters. The following snippet shows the x coordinate; y and z (addresses 401 and 402) follow the same pattern.
The joint angle registers 270 to 275 and the TCP position registers 400 to 402 are contiguous. If you poll many endpoints, enable batch read processing on the connection. Connectware then combines reads of neighboring registers into a single request.
Cycle Counter Endpoint
The last endpoint reads the general purpose register 128, which the robot program writes with write_port_register(128, cycle_count). General purpose registers hold whatever the robot program stores in them; for a plain counter, uint16BE is the appropriate data type.
Cybus::Mapping
The mapping publishes each endpoint on a topic of the ISA-95 hierarchy.
With this mapping, the base joint angle is published on the topic enterprise/hamburg/assembly/line-1/cobot/joint/base/angle, and every other value follows the same pattern.
Installing the Service Commissioning File
Install the service commissioning file. See Installing Services.
Enable the service. See Enabling Services.
Result: The service is enabled. Connectware establishes the Modbus/TCP connection to the control box and polls the configured registers.
Verifying the Data
Open the Data Explorer and subscribe to enterprise/hamburg/assembly/line-1/cobot/#. Each topic carries a JSON object with the keys timestamp and value, where the value is the decoded and converted measurement:
A few plausibility checks for the first readings:
The topic
state/robot-modereports 7 (Running) on an e-Series or CB3 robot that is powered on with the brakes released.The joint angles match the values on the Move screen of PolyScope.
The TCP position matches the TCP coordinates that PolyScope displays, in millimeters.
When you press the emergency stop button,
state/emergency-stopchanges to 1 and the robot mode leaves 7.
If the connection does not reach the Connected state, verify that the robot has finished booting and that port 502 is reachable from Connectware. If angles or coordinates that should be negative arrive as large positive numbers around 65000, the endpoint decodes the register as unsigned: set dataType to int16BE. If values are off by a constant factor, check the unit conversion in the transform rule against the register table.
Service Commissioning File Example
Last updated
Was this helpful?