Client Interface guide#

English 한국어

The Universal Robots Client Interface family gives external software a direct TCP/IP view into controller communication. In this project, that family is wrapped into a small parser and a path-based state model that partners can use from a GUI or from Python code.

Interface profiles in this project#

Interface presets#

Name

Port

Typical role

Why you might choose it

primary

30001

Full primary profile

Useful when you want robot state plus robot messages and you are comfortable using the writable primary channel.

secondary

30002

Secondary state profile

Useful when you want a lighter state-oriented profile and do not depend on the extra message categories expected on primary.

primary_ro

30011

Read-only primary profile

A strong default for monitoring tools that need robot state and robot messages while keeping the connection read-only.

secondary_ro

30012

Read-only secondary profile

Useful for observation-oriented integrations that mainly care about state values.

custom

user-defined

Manual profile

Useful when your environment exposes a different endpoint or when you want to enter the port yourself.

How the packet model is simplified#

At the wire level, the interface is binary. A packet typically starts with a size field, followed by a message type and a payload. The project keeps the low-level parser internal and exposes a more convenient model:

  • Robot State becomes stable state fields such as robot.mode or tcp.pose.x.

  • Robot Message becomes history entries and “latest” records under the messages namespace.

  • Program State Message becomes structured program variable updates and global variable information.

This means partner code can usually stay at the value-path level instead of working directly with raw bytes.

Namespaces used by the API#

A few namespaces are especially important.

robot.*

High-level robot state such as mode and safety mode.

tcp.*

Cartesian position and orientation fields.

joints.*

Per-joint values keyed by joint name.

globals.* or program.*

Program-state and global variable related data when present.

messages.*

Latest robot messages, message history, KeyMessage details, and detected error text.

errors.*

Resolved error information from the local database.

Choosing the right profile#

Choose primary_ro when:

  • you want a read-only connection,

  • you want a good chance of seeing message traffic in addition to robot state,

  • you are building monitoring, service, or diagnostics tools.

Choose primary when:

  • your environment already uses the writable primary channel,

  • you need the same message-oriented view but your toolchain or deployment model expects that port.

Choose secondary_ro when:

  • you mainly want state values,

  • you prefer a read-only channel,

  • your product does not depend on message-oriented monitoring.

Choose secondary when:

  • you are aligning with an existing secondary-based integration,

  • the project is mainly state-focused.

Handling message variety safely#

Not every robot message category carries the same fields. Some categories carry explicit numeric codes. Others are primarily textual or structural. This project therefore keeps multiple representations at once:

  • the parsed message record,

  • the flattened state fields,

  • raw packet diagnostics for messages that need deeper inspection,

  • error-code lookup results when a recognizable code string is present.

That design helps partner applications build user-facing diagnostics without pretending that every message type is identical.