Skip to main content

HexArth JSON Usage Tutorial

What is JSON?​

JSON (JavaScript Object Notation) is a lightweight data interchange format commonly used for transmitting and storing data between different systems. JSON originated from JavaScript but has become a language-independent data format, so it can be used and parsed in various programming languages. Below is an example of a JSON-formatted command for controlling the left and right wheel speeds of the robot:

{ "T": 1, "X": 0.02, "Y": 0.02, "Yaw": 0.3 }

Explanation of this command: T represents the type of this command. Command types are defined in the header file json_cmd.h of the lower-computer program. 1 indicates that this command is CMD_SPEED_CTRL (used to control the robot's X, Y speed and body rotation).

Why use JSON commands to interact with the robot?​

Because the robot driver board has many onboard resources, rich example functions, and is designed for easy expansion with a host computer, making the host computer's control over the robot more versatile and convenient, we use JSON command communication to interact with the robot. Similarly, you can perform secondary development on these functions based on the existing framework to better suit your needs.

Communication methods supporting JSON commands

The robot supports multiple methods for JSON command interaction. Wired methods include serial communication via the RX/TX pins or USB serial communication via the Type-C interface. Wireless methods include communication via HTTP requests or ESP-NOW. You can use the examples below to send corresponding JSON commands using different methods to control various robot functions. The robot has a built-in heartbeat function: if no new movement control command is received within 3 seconds, the robot will automatically stop. Therefore, when controlling the robot via an upper computer, you need to periodically repeat movement commands to keep it moving continuously.

1. Serial/USB Communication​

Features: Wired connection, default baud rate @115200, two-way communication, stable, low latency; Usage: Convenient for controlling the robot from a host computer such as a PC or Raspberry Pi; Connection methods:

  • Connect the robot's 40PIN UART interface to a Raspberry Pi.
  • Use a USB cable to connect the robot's lower-computer driver board USB interface to the host computer (this method requires disassembling the robot). Python example: serial_simple_ctrl.py. The example content is as follows:
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 running, you can send JSON format commands and receive robot feedback in this interface to communicate with the robot.

  1. HTTP Request Communication

HTTP (Hypertext Transfer Protocol) is a protocol used for data communication on the Web. Features: Wireless communication based on the Wi-Fi module, request-response model, flexible, simple. Python example: Download http_simple_ctrl.py HTTP request communication example. The example content is as follows:

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()
warning

Note: In either mode, the robot needs to be on the same local area network as the device running the script.

3. Sending JSON Commands via Web Application​

  • After powering on, connect your phone or computer to the robot's Wi-Fi: HexArth, password 12345678. After connecting to the Wi-Fi, open Google Chrome and enter 192.168.4.1 in the address bar to open the web interface.
  • In the FEEDBACK INFORMATION window, you can send JSON commands to the robot. Below the window are the specific JSON commands.