robot subpackage

Introduction

RoCS Client SDK - Robot subpackage

The robot subpackage in the RoCS (Robot Control System) Client SDK provides modules, classes and functionality for interacting with robots. It includes components for controlling robot movements, accessing sensory data, and managing robot actions.

Modules:

car: Module containing functionalities for car-like robots.
human: Module containing functionalities for humanoid robots.
robot_base: Module providing a base class and utilities for robot interaction.

Classes:

Human: Class representing a humanoid robot.
Car: Class representing a robot with car-like functionalities.
Mod: Class representing the modular features of a car robot.

Enums:

ArmAction: Enum defining actions related to robot arms.
HandAction: Enum defining actions related to robot hands.

Usage:

from rocs_client import Human, Car, Mod, ArmAction, HandAction

# Creating an instance of the Human class human_robot = Human()

# Creating an instance of the Car class car_robot = Car()

# Creating an instance of the Mod class modular_robot = Mod()

# Accessing Motor enum options motor_option = Motor.SOME_OPTION

# Accessing ArmAction enum options arm_action_option = ArmAction.SOME_ACTION

# Accessing HandAction enum options hand_action_option = HandAction.SOME_ACTION

car module

class rocs_client.robot.car.Car(ssl: bool = False, host: str = '127.0.0.1', port: int = 8001, on_connected: Callable = None, on_message: Callable = None, on_close: Callable = None, on_error: Callable = None)

Bases: RobotBase

The Car class implements the behavior of car robots and facilitates communication with its control system. It provides control functions and real-time status monitoring.

Parameters:

ssl (-) – Indicates whether SSL authentication is enabled. Defaults to False.
host (-) – Specifies the network IP address of the car. Defaults to ‘127.0.0.1’.
port (-) – Specifies the PORT of the car control service. Defaults to 8001.
on_connected (-) – A callback function triggered upon successful car connection. Defaults to None.
on_message (-) – A callback function triggered when the car sends system status. Defaults to None.
on_close (-) – A callback function triggered when the car connection is closed. Defaults to None.
on_error (-) – A callback function triggered when a car-related error occurs. Defaults to None.

move(angle: float, speed: float)

Control the car’s movement.

The request is sent by maintaining a long-lived connection.

Parameters:

angle (float) – Angle control for direction. The value ranges from -45 to +45 degrees, where left is positive and right is negative. Precision of 8 decimal places.
speed (float) – Speed control for forward and backward movement. The value can be between -500 and +500, with positive values indicating forward and negative values indicating backward. Precision of 8 decimal places.

set_mode(mod: Mod)

Set the car mode.

The car will move in the corresponding mode, which can be one of the following:

4-wheel mode
3-wheel mode
2-wheel mode

Parameters:

mod (Mod) – The mode object definition.

Returns:

A dictionary containing the following keys:

code (int): Status code, where 0 indicates normal and -1 indicates an anomaly.
msg (str): Result message.

Return type:

Dict

class rocs_client.robot.car.Mod(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enumeration of Modes for the set_mode Function.

MOD_2_WHEEL = 'WHEEL_2'

MOD_3_WHEEL = 'WHEEL_3'

MOD_4_WHEEL = 'WHEEL_4'

human module

class rocs_client.robot.human.ArmAction(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

ArmAction Enum

Enumerates different arm actions that can be performed with a robot’s arms.

Actions:

RESET (str): Reset the arm to its default position.
LEFT_ARM_WAVE (str): Wave the left arm.
ARMS_SWING (str): Swing both arms.
HELLO (str): Wave hello with the arm.

Example

# Using the ArmAction enumeration

arm_reset = ArmAction.RESET

arm_wave_left = ArmAction.LEFT_ARM_WAVE

ARMS_SWING = 'ARMS_SWING'

HELLO = 'HELLO'

LEFT_ARM_WAVE = 'LEFT_ARM_WAVE'

RESET = 'RESET'

class rocs_client.robot.human.HandAction(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

HandAction Enum

Enumerates different hand actions that can be performed with a robot’s hand.

Actions:

HALF_HANDSHAKE (str): Perform a half handshake.
THUMB_UP (str): Show a thumbs-up gesture.
OPEN (str): Open the hands.
SLIGHTLY_BENT (str): Slightly bend the hands.
GRASP (str): Perform a grasping motion.
TREMBLE (str): Tremble the hands.
HANDSHAKE (str): Perform a handshake.

Example

# Using the HandAction enumeration

half_handshake = HandAction.HALF_HANDSHAKE

thumbs_up = HandAction.THUMB_UP

GRASP = 'GRASP'

HALF_HANDSHAKE = 'HALF_HANDSHAKE'

HANDSHAKE = 'HANDSHAKE'

OPEN = 'OPEN'

SLIGHTLY_BENT = 'SLIGHTLY_BENT'

THUMB_UP = 'THUMB_UP'

TREMBLE = 'TREMBLE'

class rocs_client.robot.human.Human(ssl: bool = False, host: str = '127.0.0.1', port: int = 8001, on_connected: Callable = None, on_message: Callable = None, on_close: Callable = None, on_error: Callable = None)

Bases: RobotBase

Human Class

The Human class implements the behavior of the GR-1 robot. It establishes a connection to the robot and offers control functions along with status monitoring.

Parameters:

ssl (bool) – Indicates whether SSL authentication is enabled. Default is False.
host (str) – Specifies the network IP address of the robot. Default is ‘127.0.0.1’.
port (int) – Specifies the PORT of the robot. Default is 8001.
on_connected (Callable) – Listener triggered when the connection to the robot is successful.
on_message (Callable) – Listener triggered when the robot sends messages.
on_close (Callable) – Listener triggered when the connection to the robot is closed.
on_error (Callable) – Listener triggered when an error occurs in the robot.

Example

# Creating an instance of the Human class

human_robot = Human()

Note

The Human class inherits from RobotBase and extends its functionality to control the GR-1 robot. Ensure that you have the necessary dependencies installed and a valid connection to your robot before using the SDK.

disable_debug_state() → Dict[str, Any]

Disable debug state mode.

Returns:

code (int): Return code. 0 indicates success, -1 indicates failure.
msg (str): Return message. “ok” indicates normal, failure returns an error message.

Return type:

dict

enable_debug_state(frequence: int = 1)

Enable debug mode

Triggering this function activates the robot to proactively send status values in the background.: Listen to the on_message function to process the received data.

Parameters:

frequence (int) – Frequency of status updates.

Returns:

log (dict): Log information.

logBuffer (list): Log buffers.

log (str): Log content.

states (dict): Joint data content

basestate (dict): Robot status data

a (float): Hip roll.

b (float): Hip Pitch.

c (float): Hip Yaw.

va (float): Not used.

vb (float): Not used.

vc (float): Not used.

vx (float): Forward-backward direction velocity, unit: m/s.

vy (float): Left-right direction velocity, unit: m/s.

vz (float): Not used.

x (float): Base X position when standing.

y (float): Base y position when standing.

z (float): Base z position when standing.

fsmstatename (dict): Data related to the state machine status.

currentstatus (str): Current status (Unknown, Start, Zero, Stand, Walk, Stop).

jointStates (list): Joint state list.

name (str): Joint name.

qa (float): Actual joint angle, unit: rad.

qdota (float): Actual (measured) joint velocity, unit: rad/s.

taua (float): Actual joint torque, unit: N.m.

qc (float): Commanded (desired) joint angle, unit: rad.

qdotc (float): Commanded (desired) joint velocity, unit: rad/s。

tauc (float): Commanded (desired) joint torques, unit: N.m.

stanceindex (dict): Pose index (not used).

contactforce (dict): Contact force data (not used).

fxL (float): Force along the X-axis for the left foot.

fyL (float): Force along the Y-axis for the left foot.

fzL (float): Force along the Z-axis for the left foot.

mxL (float): Moment (torque) around the X-axis for left foot.

myL (float): Moment (torque) around the Y-axis for left foot.

mzL (float): Moment (torque) around the Z-axis for left foot.

fxR (float): Force along the X-axis for the right foot.

fyR (float): Force along the Y-axis for the right foot.

fzR (float): Force along the Z-axis for the right foot.

mxR (float): Moment (torque) around the X-axis for right foot.

myR (float): Moment (torque) around the Y-axis for right foot.

mzR (float): Moment (torque) around the Z-axis for right foot.

timestamp (dict): Timestamp.

nanos (int):

seconds (str):

function (str): interface name / function name

Return type:

Dict

Example:

{
    "data": {
        "states": {
            "basestate": {
                "a": -0.00008816774229518624,
                // ... additional parameters omitted ...
                "z": 0
            },
            "contactforce": {
                "fxL": 0,
                "fxR": 6,
                // ... additional parameters omitted ...
                "mzR": 11
            },
            "fsmstatename": {
                "currentstatus": "Start"
            },
            "jointStates": [
                {
                    "name": "left_hip_roll",
                    "qa": -0.000002967348844382189,
                    // ... additional parameters omitted ...
                    "tauc": 0.00000421397498061693
                },
                // ... additional parameters omitted ...
            ],
            "stanceindex": {}
        },
        "timestamp": {
            "nanos": 2,
            "seconds": "1"
        }
    },
    "function": "SonnieGetStates"
}

get_joint_limit() → Dict[str, Any]

Get Joint Limit Information

Obtain the robot’s joint limit information.

Returns:

code (int): Status code. 0 for Normal, -1 for Anomaly.
msg (str): Result message.
data (dict): Results.
- function (str): Function name.
- data (dict):
  jointlimit (list): List of dictionaries, each representing the limits of a joint. Each dictionary contains the following information for a joint:
  
  name (str): The name of the joint.
  
  qaMax (float): Maximum joint angle, unit: radians.
  
  qaMin (float): Minimum joint angle, unit: radians.
  
  qdotaMax (float): Maximum joint speed, unit: rad/s.
  
  tauaMax (float): Maximum joint torque, unit: N.M.

Return type:

Dict

Example

{
    "code": 0,
    "msg": "ok",
    "data": {
        "function": "SonnieGetStatesLimit",
        "data": {
            "jointlimit": [
                {
                    "name": "left_hip_roll",
                    "qaMax": 0.523598775598299,
                    "qaMin": -0.087266462599716,
                    "qdotaMax": 12.56637061435917,
                    "tauaMax": 82.5
                },
                {
                    "name": "left_hip_yaw",
                    "qaMax": 0.392699081698724,
                    "qaMin": -0.392699081698724,
                    "qdotaMax": 12.56637061435917,
                    "tauaMax": 82.5
                },
                {
                    "name": "left_hip_pitch",
                    "qaMax": 0.698131700797732,
                    "qaMin": -1.221730476396031,
                    "qdotaMax": 22.441443522143093,
                    "tauaMax": 200
                },
                {
                    "name": "left_knee_pitch",
                    "qaMax": 2.094395102393195,
                    "qaMin": -0.087266462599716,
                    "qdotaMax": 22.441443522143093,
                    "tauaMax": 200
                }
            ]
        }
    }
}

get_joint_states() → Dict[str, Any]

Retrieve the current joint states of the robot.This data is essential for monitoring and controlling the robot’s articulation in real-time, enabling precise adjustments and ensuring the robot’s overall operational status.

Returns:

Response data with the following fields:

code (int): Status code. 0 indicates normal, -1 indicates an anomaly.
msg (str): Status message. “ok” indicates normal.
data (dict): Response data with the following fields:
- data (dict): Status data with the following fields:
  bodyandlegstate (dict): Body and leg status with the following fields:
  
  currentstatus (str): Current status. “StartComplete” indicates startup completion.
  
  log (dict): Log information with the following fields:
  
  logBuffer (list): Log buffer with the following fields:
  
  log (str): Log content. “gRPC system state response init complete” indicates
  gRPC system state response initialization completion.
  
  leftarmstate (dict): Left arm status with the following fields:
  
  armstatus (str): Arm status. “Swing” indicates swing arm mode.
  
  rightarmstate (dict): Right arm state with the following fields:
  
  armstatus (str): Arm status. “Swing” indicates swing arm mode.
- function (str): name of the Function that invoked this interface.

Return type:

Dict

Example:

{
    "code": 0,
    "msg": "ok",
    "data": {
        "data": {
            "bodyandlegstate": {
                "currentstatus": "StartComplete",
                "log": {
                    "logBuffer": [
                        {
                            "log": "gRPC system state response initialization completed"
                        }
                    ]
                }
            },
            "leftarmstate": {
                "armstatus": "Swing"
            },
            "rightarmstate": {
                "armstatus": "Swing"
            }
        },
        "function": "SonnieGetSystemStates"
    }
}

head(roll: float, pitch: float, yaw: float)

Control the movement of the robot’s head via a long-lived connection.

Parameters:

roll (float) – Rotation around the x-axis. Negative values turn the head to the left, and positive values turn it to the right. Range: -17.1887 to 17.1887.
pitch (float) – Rotation around the y-axis. Positive values tilt the head forward, and negative values tilt it backward. Range: -17.1887 to 17.1887.
yaw (float) – Rotation around the z-axis. Negative values twist the head to the left, and positive values twist it to the right. Range: -17.1887 to 17.1887.

Returns:

None

Raises:

Any exceptions raised during the execution. –

Notes

The request is sent via a long-lived connection.
The roll, pitch, and yaw values are automatically adjusted to fit within the specified valid ranges if they go beyond the given thresholds.

Example

To turn the robot’s head to the right (roll), tilt it backward (pitch), and twist it to the left (yaw):

>>> Human.head(roll=10.0, pitch=-5.0, yaw=-7.0)

reset()

Reset Method

Initiates the process to reset, zero, or calibrate the robot, bringing it to its initial state.

Returns:

code (int): Status code. 0 for Normal and -1 for Anomaly.
msg (str): Result message.

Return type:

Dict

stand() → Dict[str, Any]

Stand Method

Make the robot stand up from a resting position or other positions.

Once you’ve called start() and waited for stabilization, go ahead and use stand() to get the robot into a standing position. Only after making the stand() call can you then give further control commands or motion instructions. If the robot is walking or in the middle of other movements, you can also use this function to bring it to a stop.

Returns:

code (int): Status code. 0 for Normal and -1 for Anomaly.
msg (str): Result message.

Return type:

Dict

upper_body(arm: ArmAction = None, hand: HandAction = None)

Execute predefined upper body actions by setting arm and hand movements.

Parameters:

arm (ArmAction) – Arm action. Options: RESET, LEFT_ARM_WAVE, TWO_ARMS_WAVE, ARMS_SWING, HELLO.
hand (HandAction) – Hand action. Options: HALF_HANDSHAKE, THUMBS_UP, OPEN, SLIGHTLY_BENT, GRASP, TREMBLE, HANDSHAKE.

Returns:

code (int): Return code. 0 indicates success, -1 indicates failure.
msg (str): Return message. “ok” indicates normal, failure returns an error message.
data (dict): Data object containing specific details.

Return type:

Dict

walk(angle: float, speed: float)

Control the walking behavior of the robot via a long-lived connection.

Parameters:

angle (float) – Angle to control the direction, ranging from -45 to 45 degrees. Positive values turn left, negative values turn right. Precision of 8 decimal places.
speed (float) – Speed to control forward/backward, ranging from -0.8 to 0.8 meters per second. Positive values move forward, negative values move backward. Precision of 8 decimal places.

Returns:

None

Raises:

Any exceptions raised during the execution. –

Notes

The request is sent via a long-lived connection.
The provided angle and speed values are automatically adjusted to fit within the specified valid ranges if they go beyond the given thresholds.

Example

To make the robot turn left at a speed of 0.5 m/s:

>>> Human.walk(angle=30.0, speed=0.5)

base module

RobotBase

The RobotBase is the base class for interacting with robots in the RoCS (Robot Control System) Client SDK.

Attribute:

_baseurl (str): The base URL for HTTP requests.
_ws_url (str): The WebSocket URL for connecting to the robot.
_ws (WebSocket): WebSocket connection object.
_on_connected (Callable): Callback function for the connection event.
_on_message (Callable): Callback function for incoming messages.
_on_close (Callable): Callback function for the connection close event.
_on_error (Callable): Callback function for connection errors.
camera (Camera): Instance of the Camera class for camera-related functionalities.
system (System): Instance of the System class for system-related functionalities.

Method:

__init__(ssl: bool = False, host: str = ‘127.0.0.1’, port: int = 8001,
on_connected: Callable = None, on_message: Callable = None,

on_close: Callable = None, on_error: Callable = None):
Constructor method for the RobotBase class.
_event():

Private method handling events from the WebSocket connection.
_send_websocket_msg(message: json):

Private method for sending WebSocket messages.
_send_request(url: str, method: str = ‘GET’, params=None, json=None):

Private method for sending HTTP requests.
_send_request_stream(url: str, method: str = ‘GET’, params=None, json=None):

Private method for sending HTTP requests with streaming support.
_cover_param(value: float, name: str, min_threshold: float, max_threshold: float) -> float:

Class method for handling numerical parameters within defined thresholds.
start() -> dict:

Method for initiating the process to reset, zero, or calibrate the robot.
stop() -> dict:

Method for initiating the process to safely power down the robot.
exit():

Method for disconnecting from the robot.

Usage:

from rocs_client.robot.robot_base import RobotBase

Example

# Creating an instance of the RobotBase class

robot = RobotBase()

# Initiating the process to reset, zero, or calibrate the robot

result = robot.start()

print(result)

# Safely powering down the robot

result = robot.stop()

print(result)

# Disconnecting from the robot

robot.exit()

Note

Ensure that you have the necessary dependencies installed and a valid connection to your robot before using the SDK.

class rocs_client.robot.robot_base.RobotBase(ssl: bool = False, host: str = '127.0.0.1', port: int = 8001, on_connected: Callable = None, on_message: Callable = None, on_close: Callable = None, on_error: Callable = None)

Bases: object

Base class for Robot.

When instantiated, it connects to the corresponding robot’s port via WebSocket.

Param:

ssl (bool): Indicates whether to use a secure WebSocket connection (default is False).
host (str): The IP address or hostname of the robot (default is ‘127.0.0.1’).
port (int): The port number for the WebSocket connection (default is 8001).
on_connected (Callable): Callback function executed when the WebSocket connection is established.
on_message (Callable): Callback function executed when a message is received.
on_close (Callable): Callback function executed when the WebSocket connection is closed.
on_error (Callable): Callback function executed in case of a WebSocket error.

Attribute:

camera: Instance of the Camera class for interacting with the robot’s camera.
system: Instance of the System class for system-related operations.

Method:

start(): Initiates the process to reset, zero, or calibrate the robot, bringing it to its initial state.
stop(): Initiates the process to safely power down the robot, ensuring an orderly shutdown.
exit(): Disconnects from the robot by closing the WebSocket connection.

exit(): Disconnect from the robot by closing the WebSocket connection.

start()

Used to initiate the process to reset, zero, or calibrate the robot, bringing it to its initial state. This command is crucial when you intend to take control of the robot, ensuring it starts from a known and calibrated position.

Ensure that the robot has sufficient clearance and is ready for the calibration process before issuing this command.

stop()

Used to initiate the process to safely power down the robot. This command takes precedence over other commands, ensuring an orderly shutdown. It is recommended to trigger this command in emergency situations or when an immediate stop is necessary.

Use this command with caution, as it results in a powered-down state of the robot. Ensure that there are no critical tasks or movements in progress before invoking this command to prevent unexpected behavior.

Returns:: Response indicating the success or failure of the command.
Return type:: dict