Roboception Generic Robot Interface

Robot Side Implementations

This repository contains the official robot-side implementations that demonstrate how to integrate various industrial robot platforms with Roboception's Generic Robot Interface (GRI). The GRI is an integration layer that bridges the REST-API v2 and provides a standardized way to communicate with software modules using simple TCP socket communication on port 7100.

Why is this important?
Integrating a REST-API directly into robot controllers poses significant challenges due to diverse programming environments and limited REST support on many platforms. To address this, the GRI consolidates all REST interactions within the Roboception firmware and employs a fixed-length binary protocol over TCP socket communication, ensuring that interfacing with the vision modules is both standardized and straightforward on any robot supporting TCP/IP.

Available Implementations

ABB Robots

Complete RAPID implementation for ABB robot controllers.
View ABB Documentation

• Supports IRC5 controllers
• Tested with RobotWare 6.0 and higher
• All Interface Actions are implemented callable with simple function calls

FANUC Robots

Complete KAREL/TP implementation for FANUC robot controllers.
View FANUC Documentation

• Supports R-30iA/R-30iB controllers
• Simple CALL interface for all vision functions
• Background processing with KAREL programs

Techman Robots

TMScript implementation for Techman robot controllers.

Python Reference Implementation

Complete Python reference implementation demonstrating the GRI protocol.
View Python Documentation

• Reference example for implementing GRI support on new robot platforms
• Runs on standard PC for testing and validation
• Uses only Python standard library (no external dependencies)

System Architecture Overview

The GRI consists of a TCP socket server integrated into the Roboception firmware that handles all REST-API interactions and communicates with robot controllers using a fixed-length binary protocol. Robot-side implementations connect to this server and exchange standardized messages to control vision workflows.

For detailed architecture information, refer to the official GRI documentation.

Adding New Robot Support

Developers can extend support for new robot platforms by:

• Implementing a TCP socket client following the GRI binary protocol.
• Using the provided code examples as a reference.

Requirements

• A Roboception rc_visard or rc_cube with Generic Robot Interface license enabled
• A robot controller with TCP/IP support and the ability to pack robot poses into a binary message and to parse binary messages into robot poses
• The appropriate development environment for your robot's programming language

---

Protocol System

The Generic Robot Interface uses Protocol V1 (currently the only version) with a fixed-length binary protocol (54-byte requests, 80-byte responses). The 8-byte header contains the magic number "GRI\0" (ASCII bytes 47 52 49 00), protocol version, message length, pose format, and action. All multi-byte integers use little-endian byte order. Pose data uses 32-bit signed integers scaled by 1,000,000 for precision, with positions in millimeters before scaling.

The protocol supports multiple pose formats (quaternions, Euler angles, axis-angle) and uses signed 16-bit error codes (negative = error, zero = success, positive = warning).

For complete technical specifications, field layouts, and implementation details, refer to the official documentation:

• Main GRI Documentation: https://doc.rc-cube.com/latest/en/gri.html
• Protocol Specification: https://doc.rc-cube.com/latest/en/gri.html#gri-binary-protocol-specification
• Message Header Details: https://doc.rc-cube.com/latest/en/gri.html#message-header-8-bytes
• Pose Format Reference: https://doc.rc-cube.com/latest/en/gri.html#pose-formats
• Action Definitions: https://doc.rc-cube.com/latest/en/gri.html#actions
• Job Status Codes: https://doc.rc-cube.com/latest/en/gri.html#job-status
• Message Body Layouts: https://doc.rc-cube.com/latest/en/gri.html#body-definitions
• Error Code Semantics: https://doc.rc-cube.com/latest/en/gri.html#error-codes-and-semantics
• Integration Guide: https://doc.rc-cube.com/latest/en/gri.html#integration-with-a-robot

Robot-Specific Implementation Notes

ABB RAPID Integration

• Uses QUAT_WXYZ pose format (format code 1)
• All pose components packed as [w, x, y, z] quaternion
• See ABB_RAPID/README_ABB.md for detailed usage instructions

FANUC KAREL/TP Integration

• Uses EULER_ZYX_B_DEG pose format (format code 26)
• Rotation components packed as [R, P, W] in degrees
• Job status retrieved from data_2 field
• See FANUC/README_FANUC.md for detailed usage instructions

Python Reference Implementation

• Reference implementation demonstrating all GRI protocol aspects
• Useful for understanding protocol structure and testing before robot deployment
• See Python/README_Python.md for detailed usage instructions

Implementation Guidelines

When implementing robot-side communication, connect to port 7100, use Protocol V1 with the fixed-length binary protocol, and implement proper timeout and error handling. Build the 8-byte header with magic number "GRI\0", protocol version 1, message length, pose format, and action. Pack pose data using the robot's assigned format, scale all pose components by 1,000,000 before transmission (positions in millimeters), and use little-endian byte order for all multi-byte values.

For new robot platform integrations, study the existing ABB, FANUC, and Python implementations as reference examples, and always validate your implementation against the official protocol documentation.