RoArm-M3-S JSON Command Meaning

What is JSON Command

JSON (JavaScript Object Notation) is a lightweight data exchange format, typically used for transmitting and storing data between different systems. JSON originally originated from JavaScript, but it has become an independent data format from programming languages and can therefore be used and parsed in various programming languages.

The following is a JSON example for controlling the robotic arm to rotate to certain coordinates.

{"T":1041,"x":235,"y":0,"z":234,"t":0,"r":0,"g":3.14}

Explanation of this command:

"T" represents the command type, which is defined in the header file "json_cmd.h" of the slave demo of RoArm-M3-S. "1041" represents this command as CMD_XYZT_DIRECT_CTRL (the command is for controlling the robotic arm directly to move to the designated XYZT position and not get stuck). X, Y, Z, T, R and G respectively represent the 3D coordinates of the EoAT (End of Arm Tooling) and the angle of "Gripper/Wrist".

We will introduce the specific usage and precautions for each command below. After learning the functions of each command, you can refer to the command table on this page for second development and usage.

Why Use JSON Commands for Communication?

Although we have introduced the basic Web-based tutorial for the robotic arm on the main tutorial page, we have designed various JSON format command interfaces to facilitate users in controlling the robotic arm's movements with other devices or programs. In fact, the underlying interface of the Web-based control also utilizes JSON commands for communication. The following are the advantages of using JSON formatted commands to control robots:

1. Good readability

JSON is a lightweight text data format that is easy for humans to read and write. It uses the form of key-value pairs, which makes the commands easy to understand and debug, especially during the development and testing phases.

2. Easy to parse

Many programming languages provide JSON parsers, making parsing JSON commands very easy. This makes it easy to convert commands into executable operations.

3. Cross platform compatibility

JSON is a universal format that can be used on almost any programming language and platform. This means that you can use different programming languages to send and receive JSON commands.

4. Structured data

JSON supports nested data structures and can contain objects and arrays. This allows you to organize commands in a clear manner, including parameters, options, and subcommands.

5. Scalability

You can easily add new fields and parameters to JSON commands to support more features and options without changing the overall structure of the command.

6. Easy to integrate

JSON is the standard input and output format for many APIs and Web services. This enables robots to seamlessly inherit from other systems and services, such as communicating through REST APIs.

7. Standardization

JSON is a standardized data format that is widely supported and adopted. This means that you can use various libraries and tools to process and manipulate JSON data.

8. Support for multiple languages

Due to the fact that JSON can be used in multiple programming languages, it is possible to implement robot control systems written in multiple languages without the need to rewrite command parsers.

Overall, JSON formatted commands provide a simple, flexible, readable, and easily parsed way to control robots, making robot control systems more powerful and maintainable.

Communication Mode of JSON Commands Support

RoArm-M3-S supports multiple methods for JSON command interaction. Among them, wired communication can be achieved through RX/TX for serial communication or by connecting via the Type-C interface for USB serial communication. Wireless communication can be established using HTTP requests or through ESP-NOW. The wireless communication methods in the demo are typically implemented based on WIFI modules.

UART/USB Communication

Features: Wired connection, default baud rate @115200, bidirectional communication, stable, low latency.

Usage: Convenient for users to control robotic arms using devices such as PC/Raspberry Pi/Jetson Orin Nano.

Connection method: 1. Connect it to other devices directly via RX/TX pin; 2. Or connect it to other devices through the Type-C interface to a USB cable.

Python demo: serial_simple_ctrl.py

import serial
import argparse
import threading

def read_serial():
    while True:
        data = ser.readline().decode('utf-8')
        if data:
            print(f"Received: {data}", end='')

def main():
    global ser
    parser = argparse.ArgumentParser(description='Serial JSON Communication')
    parser.add_argument('port', type=str, help='Serial port name (e.g., COM1 or /dev/ttyUSB0)')

    args = parser.parse_args()

    ser = serial.Serial(args.port, baudrate=115200, dsrdtr=None)
    ser.setRTS(False)
    ser.setDTR(False)

    serial_recv_thread = threading.Thread(target=read_serial)
    serial_recv_thread.daemon = True
    serial_recv_thread.start()

    try:
        while True:
            command = input("")
            ser.write(command.encode() + b'\n')
    except KeyboardInterrupt:
        pass
    finally:
        ser.close()


if __name__ == "__main__":
    main()

After connecting to the robotic arm and running this demo, you can send the JSON command to obtain the feedback information. For detailed demo downloading and usage, you can refer to RoArm-M3-S_Python UART Communication Control.

HTTP Request Communication

HTTP (Hypertext Transfer Protocol) is a protocol used for data communication on the Web.

Features: Wireless communication based on the WIFI module, using a request-response model, is flexible and simple.

python demo: http_simple_ctrl.py

import requests
import argparse


def main():
    parser = argparse.ArgumentParser(description='Http JSON Communication')
    parser.add_argument('ip', type=str, help='IP address: 192.168.10.104')

    args = parser.parse_args()

    ip_addr = args.ip

    try:
        while True:
            command = input("input your json cmd: ")
            url = "http://" + ip_addr + "/js?json=" + command
            response = requests.get(url)
            content = response.text
            print(content)
    except KeyboardInterrupt:
        pass


if __name__ == "__main__":
    main()

After running this demo, you can send a JSON command to the robotic arm and obtain its feedback information. For the specific demo downloading and usage, you can refer to RoArm-M3-S_Python HTTP Request Communication .

JSON Command Table

The specific control meanings will be explained following the sequence of JSON commands that appear in the Web interface.

WIFI SETTINGS - WIFI Configuration

This feature contains a lot of content, so for detailed WiFi configuration JSON commands and operations, please refer to the tutorial RoArm-M3-S_WIFI Configuration.

ESP-NOW SETTINGS - ESP-NOW Configuration

For detailed ESP-NOW configuration JSON commands and operations, please refer to the tutorial RoArm-M3-S_ESP-NOW Control.

TORQUE CTRL - Torque Lock Control

CMD_TORQUE_CTRL

{"T":210,"cmd":0}

210: This command is CMD_TORQUE_CTRL and controls the torque switch ON/OFF.

cmd: Torque lock switch mode.
- 0: This means "turn off the torque lock", allows you to manually move the joints of the robotic arm when the arm is powered on.
- 1: This means "turn on the torque lock" prevents manual movement of the joints when the robotic arm is powered on.

Note: After turning off the torque lock, if a certain joint or all joints of the robotic arm receive other rotation commands, the torque lock will be automatically turned on.

DYNAMIC ADAPTATION - Dynamic Force Self-Adaption

CMD_DYNAMIC_ADAPTATION

{"T":112,"mode":1,"b":60,"s":110,"e":50,"h":50,"t":50,"r":50,"h":50}

{"T":112,"mode":0,"b":1000,"s":1000,"e":1000,"t":1000,"r":1000,"h":1000}

112: Indicates that this command is CMD_DYNAMIC_ADAPTATION, used to control the on/off state of the dynamic external force adaptation function (since limiting the torque of the servo also limits the speed of the servo, it may cause the servo speed to be insufficient to support the servo rebound after applying external force to rotate the robotic arm at some positions).

mode: The code for the dynamic external force adaptive mode.
- 0: It means that the function is turned off. When turned off, you cannot manually move the joints when the robotic arm is powered on.
- 1: It means that the function is turned on. When turned on, using an external force to move the robotic arm will result in the arm returning to its previous position.

b: The maximum output torque limit for the BASE joint.

s: The maximum torque limit for the SHOULDER joint.

e: The maximum torque limit for the ELOBW joint.

t: The maximum torque limit for the WRIST joint (WRIST joint 1).

r: The maximum torque limit for the ROLL joint (WRIST joint 2).

g: The maximum torque limit for the GRIPPER joint.

You can set the maximum output torque limit values as per your requirements.

When the function is enabled and the applied force exceeds the set maximum output torque limit value, the robotic arm will move with the external force and then return to its previous position The larger the set maximum torque limit value, the greater the external force that needs to be used, and the arm will rebound to its original position more quickly. Conversely, the smaller maximum torque limit value requires less force but results in a slower rebound speed.

When the function is disabled, the default maximum output torque limit for all joints is 1000.

MOVING CTRL - Robotic Arm Motion Control

For detailed robotic arm motion control JSON commands and operations, please refer to the tutorial RoArm-M3-S_Robotic Arm Control

JOINTS PID CTRL - Joint PID Setting

CMD_SET_JOINT_PID

{"T":108,"joint":3,"p":16,"i":0}

108: This command is CMD_SET_JOINT_PID for setting the PID value for all joints of the robotic arm.

joint is the joint number:
- BASE_JOINT = 1
- SHOULDER_JOINT = 2
- ELBOW_JOINT = 3
- WRIST_JOINT= 4
- ROLL_JOINT= 5
- GRIPPER= 6

The p value is the proportional coefficient, with a default of 16. An excessively high P value can cause joint oscillations in the robotic arm.

The i value is the integral coefficient, with a default of 0. It can be set to a multiple of 8, which can be used to compensate for the position error caused by the load, and too high i value will cause jitter.

CMD_RESET_PID

{"T":109}

109: This command is CMD_RESET_PID for setting the PID value for all joints of the robotic arm as the default values.

MISSION & STEPS EDIT - Mission File Setting

For detailed mission file settings for JSON commands and operations, please refer to the tutorial RoArm-M3-S_Step Recording and Reproduction

FLIE SYSTEM CTRL - FLASH File Operation

For detailed FLASH file JSON commands and operations, please refer to the tutorial RoArm-M3-S_FLASH File System Operation

Navigation menu