什么是JSON？

JSON（JavaScript Object Notation）是一种轻量级的数据交换格式，通常用于在不同系统之间传输和存储数据。JSON 最初起源于 JavaScript，但已成为一种独立于编程语言的数据格式，因此可以在各种编程语言中使用和解析。

以下是命令机械臂运动到某一坐标位置的 JSON 格式的指令案例：

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

对于这条指令的解释：

“T”代表该指令的类型，指令类型在 RoArm-M2-S 下位机程序的头文件 json_cmd.h 中定义。1041代表这条指令为 CMD_XYZT_DIRECT_CTRL (用来控制机械臂直接运动到 XYZT 位置的指令，且该指令不会引发阻塞），X、Y、Z 和 T 分别对应机械臂末端点的三维坐标位置和“夹爪/手腕”关节的角度。

我们会在后续教程中具体介绍每条指令的具体用法和注意事项，当你对每个功能有一定了解后，可参考本文章的指令表来增加二次开发和使用效率。

为什么使用JSON格式的指令通信？

虽然在主教程界面中介绍了机械臂基础Web端的使用教程，但是我们仍然设计了多种JSON格式的指令接口来方便用户可以使用其它设备或程序来控制机械臂运动。实际上，Web端的底层接口同样也是使用JSON指令通信的。以下是使用JSON格式的指令来控制机器人的优点：

1.可读性好

JSON是一种轻量级的文本数据格式，易于人类阅读和编写。它使用键-值对的形式，这使得指令易于理解和调试，特别是在开发和测试阶段。

2.易于解析

许多编程语言都提供了JSON解析器，使得解析JSON指令变得非常容易。这使得将指令转化为可执行的操作变得简单。

3.跨平台兼容性

JSON是一种通用格式，几乎可以在任何编程语言和平台上使用。这意味着您可以使用不同的编程语言来发送和接收JSON指令。

4.结构化数据

JSON支持嵌套的数据结构，可以包含对象和数组。这使得您可以以清晰的方式组织指令，包括参数、选项和子命令等。

5.扩展性

您可以轻松地添加新的字段和参数到JSON指令中，以支持更多的功能和选项，而不必改变指令的整体结构。

6.易于集成

JSON是许多API和Web服务的标准输入和输出格式。这使得机器人可以与其他系统和服务进行无缝继承，例如通过REST API进行通信。

7.标准化

JSON是一个标准化的数据格式，受到广泛的支持和采用。这意味着您可以借助各种库和工具来处理和操作JSON数据。

8.支持多语言

由于JSON可以在多种编程语言中使用，因此可以实现多语言编写的机器人控制系统，而无需重新编写指令解析器。

总的来说，JSON格式的指令提供了一种简单、灵活、可读性好且易于解析的方式来控制机器人，使得机器人控制系统更加强大和可维护。

目前支持JSON指令的通信方式

RoArm-M2-S可使用多种方式来进行JSON格式的指令交互。其中，有线的通信方式可以使用RX\TX进行串口通信，或者通过Type-C接口接USB进行串口通信；无线的通信方式可以使用http请求进行通信，或者使用ESP-NOW进行通信。例程中的无线通信方式都是基于WIFI模块实现的。

串口/USB通信

特性：有线连接，默认波特率@115200，双向通信，稳定，低延时。

用途：方便使用PC/树莓派/Jeston Orin Nano等设备来控制机械臂。

连接方式：1.可以通过RX/TX引脚直接与其它设备连接；2.也可以通过Type-C接口接USB线与其它设备进行连接。

Python例程：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()

通过连接到机械臂运行该程序后，你可以发送JSON格式的指令，并获取机械臂的反馈信息，具体的例程下载和使用方法可参考教程RoArm-M2-S_Python串口通信控制。

HTTP请求通信

HTTP（Hypertext Transfer Protocol）是一种用于在Web上进行数据通信的协议。

特性：基于WIFI模块实现的无线通信，请求-响应模型，灵活、简单。

python例程：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()

通过运行该程序，你可以发送JSON指令到机械臂，并获取机械臂的反馈信息，具体的例程下载和使用方法可参考教程RoArm-M2-S_Python HTTP请求通信 。

JSON指令表

下面将会以Web端界面中出现的JSON指令顺序来介绍具体控制含义。

WIFI SETTINGS - WIFI配置

这一功能部分的内容较多，因此详细的WIFI配置JSON指令和操作请参考教程RoArm-M2-S_WIFI配置。

ESP-NOW SETTINGS - ESP-NOW配置

详细的ESP-NOW配置JSON指令和操作请参考教程RoArm-M2-S_ESP-NOW控制。

TORQUE CTRL - 扭矩锁控制

CMD_TORQUE_CTRL

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

• 210：表示这条指令为CMD_TORQUE_CTRL，可以控制扭矩锁开关状态。

• cmd：扭矩锁开关模式的代号。
  • 0：表示关闭扭矩锁，可以在机械臂接通电源的时候手动使关节转动；
  • 1：表示开启扭矩锁，开启后在机械臂接通电源时不可手动使关节转动。

注意：关闭扭矩锁后，若机械臂某一关节或所有接收到其它的转动指令，则会自动开启扭矩锁。

DYNAMIC ADAPTATION - 动态外力自适应

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：表示这条指令为CMD_DYNAMIC_ADAPTATION，用来控制动态外力自适应功能开关状态。

• mode：动态外力自适应开关模式的代号。
  • 0：表示关闭该功能，关闭后在机械臂接通电源时不可手动使关节转动。
  • 1：表示开启该功能，开启后使用外力转动机械臂会回弹至转动前的位置。

• b：BASE关节的最大输出扭矩限制。

• s：SHOULDER关节的最大扭矩限制。

• e：ELOBW关节的最大扭矩限制。

• h：GRIPPER/WRIST关节的最大扭矩限制。

最大输出扭矩限制给的值可以自己设置。

当该功能处于开启状态时，且使用的外力大于设置的最大输出扭矩限制值时，机械臂会随着外力而运动，且会回弹至转动前的位置。设置的最大输出扭矩限制值越大，需要使用的外力也就越大，机械臂回弹的速度越快；反之，设置的最大输出扭矩限制值越小，需要使用的外力也就越小，但机械臂回弹的速度会减慢。

当该功能处于关闭状态时，默认所有关节的最大输出扭矩限制都为1000。

MOVING CTRL - 机械臂运动控制

详细的机械臂运动控制JSON指令和操作请参考教程RoArm-M2-S_机械臂控制。

EOAT CTRL - 末端关节设置

详细的末端关节控制JSON指令和操作请参考教程 RoArm-M2-S_末端关节设置。

JOINTS PID CTRL - 关节PID设置

CMD_SET_JOINT_PID

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

• 108：这条指令为CMD_SET_JOINT_PID，可以设置机械臂各关节的PID值。

• joint为关节编号：
  • BASE_JOINT = 1
  • SHOULDER_JOINT = 2
  • ELBOW_JOINT = 3
  • EOAT_JOINT = 4

• p值为比例系数，默认为16，过高的P值会导致机械臂关节抖动。

• i值为积分系数，默认为0，可以设置为8的倍数，可用于补偿负载带来的位置误差，过高的i值会引发抖动。

CMD_RESET_PID

{"T":109}

• 109：这条指令为CMD_RESET_PID，用来将所有关节的PID设置为默认值。