Understanding RoCS Programming¶

Using the RoCS SDK involves complex interactions between the robot's hardware, backend system and network. It's crucial to follow the proper procedures to ensure effective operation and avoid damage. This section delves into the principles and internal mechanisms of the RoCS SDK, providing insight into its architecture and the critical steps needed for safe and effective usage.

Following topics are covered:

"Host IP" Configuration
Robot State is a Message
SDK Workflow

"Host IP" Configuration¶

Each time you want to create a SDK object , the IP address needs to be correctly configured according to the actual network environment and your network choice. For example, to use Human class methods, you need to firstly establish a WebSocket connection with the server:

human = Human(host='192.168.12.1')

The IP address is used to uniquely identify and locate the robot on a network, allowing other devices or applications to send data, commands, or requests to the GR robot and receive responses in return.

For more details about the networking of GR robot, please refer to Network Communication.

Run the following command in the terminal to determine the needed ipv4 address:

Windows Users:

ipconfig

Linux Users:

ifconfig

Here are the common network choice and corresponding IP configuration:

Local Network

It is feasible to run command in the local network, namely the torso computer.This provides a reliable, high-rate communications link without infrastructure requirements but limits the application's deployment location. Loop back address or Ethernet address can be used in this way, such as "127.0.0.1" and "192.168.137.252".
GR as a WiFi access point

When the torso computer is on, it will automatically open a wireless network for devices nearby. The ssid is in line with the SN number and password remains "66668888". The IP address is a static address which is "192.168.12.1".
GR as a WiFi client

Your device can also connect to the robot if they are under the same WiFi network. In this case, the IP address is allocated by DHCP and you have to check the address from the local computer or the router.

Robot State is a Message¶

The RoCS state message is a comprehensive JSON-formatted data package that encapsulates real-time information about the robot's status. This payload includes details about the robot's joint states, offering precise information about the positioning and configuration of its mechanical components. Additionally, the state message encompasses data related to the robot's base state, providing insights into its spatial orientation and location. Contact force information is also embedded, shedding light on the external forces acting on the robot. The RoCS state message serves as a rich source of information, empowering users to monitor and interact with the robot in real-time with a granular level of detail.

SDK Workflow¶

There are three different SDK objects, responsible for whole body control, end effector and single motor separately. It is crucial to follow its workflow when using the methods in each class.

Human Class¶

Please refer to Quick Start for detailed workflow.

EndEffector Class¶

To properly use SDK commands in EndEffector class, you need to follow the procedure below:

Complete all the preliminary work before running the code, including charing, inspection, calibration and powering on the robot. For detailed instructions, please refer to Quick Start.

Import RoCS SDK:

from rocs_client import EndEffector, EndEffectorScheme

Create an EndEffector object to connect to the server using WebSocket connection:
```
end_effector = EndEffector(host="192.168.12.1")
```
If you have problems with determining the proper IP address, please refer to Host IP Configuration.
Enable the endeffector control using enable method:
```
end_effector.enable()
time.sleep(5)
```
After successful execution, the robot will start endeffector control mode with an initial position, which takes a few seconds to complete.

Danger

Ensure that nothing is within the range of motion in case of unexpected damage.

Send other commands to control the arm, such as control_left or control_right for a movement in Cartesian coordinate system. You can also enable status sending with enable_state.
```
end_effector.control_right(EndEffectorScheme(x=0.3, y=-0.2, z=0))
time.sleep(5)
```

Note

The origin of the Cartesian coordinate system is located at the chest of the robot's torso, with the positive direction of the x-axis pointing forward, the positive direction of the y-axis pointing to the left, and the positive direction of the z-axis pointing upwards. The unit of measurement for axis movement is meters.Both the left and right hand control utilize this same coordinate system.

Close WebSocket connection using exit:
```
end_effector.exit()
```
Press emergency stop switch.

Motor Class¶

To properly use SDK commands in Motor class, you need to follow the procedure below:

Complete all the preliminary work before running the code, including charing, inspection, calibration and powering on the robot. For detailed instructions, please refer to Quick Start.
Import RoCS SDK:
```
from rocs_client import Motor
```
Create a Motor object to connect to the server using WebSocket connection:
```
motor = Motor(host="192.168.12.1")
```
If you have problems with determining the proper IP address, please refer to "Host IP" Configuration.
Set pd flag with set_pds_flag and restart the robot:
```
motor.set_motor_pd_flag('8', 'left')
```

Set motor pd with set_pds and restart the robot:

motor.set_motor_pd('8', 'left', 0.36, 0.042)

Tip

The PD parameters will be stored in the motor flash memory and retain its value upon power loss. Thus, it is not necessary to repeat set_pds_flag and set_pds each time using single motor control.

Enable the motor with enable_motor:
```
motor.enable_motor('8', 'left')
```
Send other commands to control the motor and receive status messages, such as move_motor and get_motor_pvc:
```
motor.move_motor('8', 'left', 40)
time.sleep(5)
```
Close WebSocket connection using exit:
```
motor.exit()
```
Press emergency stop switch.