RoArm-M2-S JSON Command Meaning

What's JSON

JSON (JavaScript Object Notation) is a lightweight format for data transmission, which is generally used in different systems for data transmission and storage. JSON, which originated from JavaScript, has emerged as an independent data format from programming languages. Hence, it can be used and analyzed in different 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":3.14}

Explanation:
"T" represents the command type, which is defined in the header file "json_cmd.h" of the slave demo of RoArm-M2-S. "1041" represents this command as CMD_XYZT_DIRECT_CTRL (the command is for controlling the robotic arm directly to move to the designated position and not get stuck). X, Y, Z, and T respectively represent the 3D coordinates of the EoAT (End of Arm Tooling) and the angle of "Clamp/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 Command to Communicate?

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 advantages of using JSON format commands to control the robot are as follows:
1. Better Readability:
JSON is a lightweight text data format and is easy for humans to read and compile. With the Key-Value pair format, it is easy to understand and debug, especially for the development and test stage.
2. Easy to Analyze:
As many programming environments adopt JSON analyzer, JSON is easy to analyze making the process of turning the command to the executable operation easier.
3. Cross-platform Compatibility:

JSON is a universal format that can be used on nearly any programming language and platform. This means you can use different programming languages to send and receive JSON commands.
4. Structural Data:
JSON supports nested data structures, including objects and arrays. This allows you to organize commands in a clear manner, including parameters, options, and subcommands.
5. Extensibility:
You can easily add new segments and parameters to JSON commands to support more functions and options without changing the overall structure of the command.
6. Easy to Integrate:
JSON is the standard input and output format for many APP and Web services, which makes the robot seamlessly compatible with other systems and services, for example, communication through REST API.
7. Standard:
JSON is a standard data format with popular support, which means you can operate JSON data with various libraries and tools.
8. Support Multiple Languages:
As JSON can be used in various programming languages, the robot control system programmed in different languages does not need to re-program the command analyzer.
In short, JSON format commands provide a simple, flexible, highly readable, and easily parseable way to control the robot, making the robot control system more robust and maintainable.

Communication Mode of JSON Commands Support

RoArm-M2-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 examples are typically implemented based on WIFI modules.

UART/USB Communication

Feature: Wired connection, default baud rate @115200, bidirectional communication, stability and low-delay.
Usage: Easy to use devices such as PC/Raspberry Pi/Jetson Nano to control the robotic arm.
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 by 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-M2-S Python UART Communication.

HTTP Request to Communication

HTTP (Hypertext Transfer Protocol) is a protocol for data communication on the Web.
Feature: The wireless communication based on the WIFI module, Request-Response model, flexible & 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-M2-S Python UART 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

You can refer to RoArm-M2-S WIFI Configuration.

ESP-NOW SETTINGS - ESP-NOW Configuration

You can refer to RoArm-M2-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, the torque lock will automatically be on if any joints of the robotic arm receive other rotation commands.

DYNAMIC ADAPTATION - Dynamic Force Self-Adaption

CMD_DYNAMIC_ADAPTATION

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

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

112: This command is labeled as "CMD_DYNAMIC_ADAPTATION" and is used to control the status of the dynamic external force adaptive function. Here's an explanation of the parameters:
mode: The code for the dynamic external force adaptive mode.
- 0: Represents the function is turned off. When turned off, you cannot manually move the joints when the robotic arm is powered on.
- 1: Represents 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: Represents the maximum torque limit for the BASE joint.
s: Represents the maximum torque limit for the SHOULDER joint.
e: Represents the maximum torque limit for the ELBOW joint.
h: Represents the maximum torque limit for the GRIPPER/WRIST joint.

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

When this function is in the "on" state and the applied external force exceeds the set maximum torque limit value, the robotic arm will move in response to the external force and then return to its previous position. The larger the set maximum torque limit value, the more force is required to move the arm, and the arm will rebound to its original position more quickly. Conversely, a smaller set maximum torque limit value requires less force but results in a slower rebound speed.

When this function is in the "off" state, the default maximum torque limit for all joints is set to 1000.

MOVING CTRL - Control the Mechanical Movement of Robotic Arm

Please refer to RoArm-M2-S Robotic Arm Control.

EOAT CTRL - EoAT Control

Please refer to RoArm-M2-S EoAT Setting.

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
- EOAT_JOINT = 4
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 in multiples of 8 and is used to compensate for position errors caused by the load. However, a high I value can also cause shaking.

CMD_RESET_PID

{"T":109}

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

SETX-AXIS - X-axis Positive Direction Setting

CMD_SET_NEW_X

#Rotate the positive direction of the X-axis 90° to the right
{"T":110,"xAxisAngle":90}

#Rotate the positive direction of the X-axis 90° to the left 
{"T":110,"xAxisAngle":-90}

110 means this command is CMD_SET_NEW_X for setting the orientation of the positive X-axis.

Navigation menu