URCtrl Control Manual

URCtrl is not merely a standalone Python wrapper for Universal Robots. It is the UR implementation of a common robot interface intended to let researchers control multiple collaborative robots through the same API.

The objective is not to make the smallest possible port from COBOTTA to UR. It is to define a common API that treats COBOTTA and UR at a comparable level of abstraction, providing a system for instrument control, experiment automation, and SPring-8 BL774-style operations.

Accordingly, URCtrl takes COBOTTA compatibility into account without treating COBOTTA as the definitive standard. Sound design choices established in the UR implementation may instead be incorporated into cobotta_ctrl.

---

Contents:

• Design Philosophy
  • Primary Objective
  • Concept of a Common Robot Interface
  • Separation of the Common Interface and Implementations
  • COBOTTA Is an Existing Implementation, Not the Standard
  • BL774-Style and SPring-8 Compatibility
  • Unit Conventions
  • Success and Failure Conventions
  • Policy for Unsupported Features
• Common Interface and BL774-Style Systems
  • Not Merely a Standalone Robot API
  • Meaning of the BL774-Style Architecture
  • SPring-8 Compatibility
  • Scope of the Common API
  • Relationship to Device Servers
• Quick Start
  • Minimal connection
  • Current position and joint angles
  • Move Z +10 mm from the current position
  • Create taught point P1
  • Move to P1
  • Move to P1 using LINE
  • Set IO outputs
  • Inspect errors
• Units and Pose Representation
  • Public units
  • Internal UR units
  • P coordinates
  • Rotation vector
  • J coordinates
  • speed / accel
  • Default values
• Connection and Initialization
  • Constructor
  • config
  • Dashboard
  • connect()
  • disconnect()
  • Context Manager (with)
• Virtual Variables P/I/F/IO
  • Basics
  • Attribute access
  • get_var() / set_var()
  • P variables
  • teach()
  • I / F
  • IO
  • is_empty_position()
• Motion API
  • MotionMode
  • move()
  • Internal Mapping
  • move_path()
  • dev()
  • pose_trans()
  • p2j() / j2p()
  • drive()
  • stop()
• State Monitoring
  • current_position
  • current_angle
  • state()
  • Robot mode
  • Safety status bits
  • motion_complete()
  • wait_for_complete()
• I/O and TCP
  • set_IO()
  • get_IO()
  • get_digital_input()
  • set_tcp()
  • set_tool() / set_tool_define()
  • get_current_tool()
  • safety limit
• Error Handling and Recovery
  • Policy
  • error_code
  • error_description
  • get_current_error_info()
  • reset_error()
  • turn_on_motor()
  • turn_off_motor()
  • Caution
• API Reference
  • Connection
  • Variables
  • Settings
  • Status
  • Motion
  • IO / TCP
  • Errors
  • Unsupported
• Tutorials
  • 1. Basic structure of a research script
  • 2. Create taught points
  • 3. Move to a taught point
  • 4. Move linearly to a measurement position
  • 5. Retract
  • 6. Combine motion with IO
  • 7. Inspect the state and stop
  • 8. Integrate into an experimental sequence
• Implementation Differences and Porting Policy
  • Policy
  • Variable Management
  • Status Monitoring
  • Error Information
  • No-Ops Versus Unsupported Features
  • BL774 / SPring-8 Integration

---

Objectives

• Provide a common collaborative-robot API that is easy for researchers to use.

• Hide differences between COBOTTA, UR, and other robot models from higher-level experiment code.

• Make robot control a component of the overall experimental instrument-control system.

• Support integration with BL774-style, SPring-8-compatible experiment automation architectures.

• Define a research-oriented robot control API rather than an interface tied to a particular manufacturer.

Role of URCtrl

Experiment script
    ↓
Common robot interface
    ↓
URCtrl / CobottaCtrl / future robot implementations
    ↓
Robot-specific APIs
    ↓
Physical robot

URCtrl implements the UR side, while cobotta_ctrl implements the COBOTTA side. Neither is subordinate to the other; both are peer implementations of the same common interface.

Contents

• Design Philosophy

• Common Interface and BL774-Style Systems

• Quick Start

• Units and Pose Representation

• Connection and Initialization

• Virtual Variables P/I/F/IO

• Motion API

• Status Monitoring

• I/O and TCP

• Error Handling and Recovery

• API Reference

• Tutorials

• Implementation Differences and Porting Policy

Minimal Example

from ur.ur_ctrl import UrCtrl, MotionMode

ROBOT_IP = "10.170.10.56"

with UrCtrl(ROBOT_IP) as robot:
    current = robot.current_position

    if current is not False:
        target = list(current)
        target[2] += 10.0

        robot.move(
            target,
            motion_mode=MotionMode.LINE,
            speed=20,
            accel=20,
            is_async=False,
        )

The public interface represents P coordinates as [x, y, z, rx, ry, rz]: position in millimeters and orientation as a rotation vector expressed in degrees. J coordinates are in degrees. speed, accel, and decel are percentages satisfying 0 < value <= 100.

---

Author

• Kengo NAKADA