UR Client Interface Partner Guide

A compact partner-facing example for understanding and using the Universal Robots Client Interface family from both a desktop app and a class-based Python API.

This repository is not an official Universal Robots SDK or product. It is a practical reference project for partners who want to inspect Client Interface traffic, read live values from Python, explore robot messages, and enrich detected error codes with a local SQLite database.

📚 Documentation

👉 https://shh444.github.io/ur-clientinterface/

---

What this repository is for

This repository brings four things together in one place:

• a desktop monitor for live Client Interface exploration,
• a compact Python library for data acquisition and integration,
• a local SQLite knowledge base for error-code lookup, and
• bilingual Sphinx manuals for partner education and project handover.

It is meant to help partner teams:

• understand the difference between the available Client Interface profiles,
• discover which value paths are useful for their machine or product,
• call the library directly from Python with an IP address,
• inspect robot messages and detected error codes,
• present Error code / Description / Explanation / Suggestion in their own HMI or service tool.

Repository highlights

Area	Purpose
app.py	Desktop app for live exploration, field selection, message history, and error details
ur_client.py	Single-file Python library with parser, state model, and class-based API
ur_error_codes.sqlite3	Local error-code database used by the app and the API
example_api.py	Integration examples for ClientInterfaceAPI and URClient
docs/	English and Korean partner manuals built with Sphinx

Screenshots

Main application

Error detail panel

API and data flow

Quick start

Create and activate a virtual environment, then install the repository requirements.

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Run the desktop app:

python app.py

Python API quick example

Use the high-level class when you want to read values directly from your own code.

from ur_client import ClientInterfaceAPI

with ClientInterfaceAPI(
    host="192.168.163.128",
    interface_name="primary_ro",
    error_db_path="ur_error_codes.sqlite3",
) as api:
    api.wait_until_ready(timeout=5.0, minimum_packet_count=1)

    values = api.get_values(
        "robot.mode",
        "robot.safety_mode",
        "tcp.pose.x",
        "tcp.pose.y",
        "tcp.pose.z",
        "errors.latest.error_code",
        "errors.latest.description",
        "errors.latest.explanation",
        "errors.latest.suggestion",
    )
    print(values)

Lower-level access is also available through URClient when you want direct lifecycle control, message history, subscriptions, or debug export support.

What you can do with the API

1) Read selected live values

robot_mode = api.read("robot.mode")
pose_x = api.read("tcp.pose.x")
selected = api.read_many(
    "robot.mode",
    "robot.safety_mode",
    "tcp.pose.x",
    "tcp.pose.y",
    "tcp.pose.z",
)

2) Read a full snapshot

snapshot = api.snapshot()
print(snapshot["values"]["robot"])
print(snapshot["values"]["errors"])

3) Watch values over time

for item in api.watch(
    "robot.mode",
    "errors.latest.error_code",
    interval=0.5,
):
    print(item)

4) Resolve a live or historical error code

info = api.lookup_error("C154A")
print(info["error_code"])
print(info["description"])
print(info["explanation"])
print(info["suggestion"])

Build the documentation

The docs are set up for local HTML output and GitHub Pages.

python -m pip install -r requirements.txt
cd docs
.\make.bat html

Open the built documentation here:

docs\_build\html\index.html

Documentation structure

The manuals are split by language and audience flow.

• docs/index.rst — documentation landing page
• docs/en/ — English partner manual
• docs/ko/ — Korean partner manual

Each manual covers:

• project overview,
• Client Interface guide,
• desktop application manual,
• Python class API,
• error lookup model,
• integration examples,
• official-reference map.

Included screenshots

The manuals expect the following files in docs/_static/images/screenshots/:

• app-home.png
• interface-dropdown.png
• live-status.png
• value-selection.png
• message-history.png
• error-details.png
• api-flow.png

You can replace them with your own branded screenshots later without changing the page content.

Audience

This repository is a strong fit for:

• partner HMIs,
• service laptops and diagnostics tools,
• internal engineering demos,
• commissioning workflows,
• small gateway or collector utilities,
• training material for teams that are new to the Client Interface family.

Relationship to official Universal Robots material

This project is intended to complement the official Universal Robots documentation, not replace it.

Use this repository when you want a compact example that helps people understand and use the data in practice. Use the official Universal Robots documentation as the protocol reference and product truth.

Repository layout

ur_clientinterface_partner_guide_v11/
├─ app.py
├─ example_api.py
├─ requirements.txt
├─ ur_client.py
├─ ur_error_codes.sqlite3
└─ docs/
   ├─ conf.py
   ├─ make.bat
   ├─ index.rst
   ├─ en/
   ├─ ko/
   └─ _static/images/screenshots/

License and reuse

Review and set the appropriate license for your own distribution model before publishing this repository externally.