HexArth ESP-NOW Control

ESP-NOW SETTINGS

This tutorial mainly introduces how to configure ESP-NOW for the robot. After configuration, the robot can achieve one-to-one and one-to-many ESP-NOW communication control. Among these, JSON commands are used to implement this function.

ESP-NOW Communication Protocol

ESP-NOW is a fast and efficient wireless communication protocol developed by Espressif Systems, aimed at providing low-power, high-performance local area network (LAN) communication solutions. It was initially designed for Espressif's Wi-Fi chips such as ESP8266 and ESP32.

The features of ESP-NOW are as follows:

1. Quick Response: The ESP-NOW protocol does not require TCP/IP stack processing, therefore it has very low latency and is suitable for applications with high real-time requirements.

2. High Throughput: The ESP-NOW protocol uses frame broadcasting to transmit data with high transmission efficiency, enabling simultaneous transmission of the same information to multiple nodes.

3. Low-power: ESP-NOW protocol uses very low power in data transmission, and is suitable for battery power supply.

4. User-friendly: The configuration of ESP-NOW protocol is easy, only by defining the basic parameters such as the channels, encryption key, and data structure can it realize the wireless communication.

5. Multicast Support: ESP-NOW protocol supports one-to-many and one-to-all node communication, improving the network flexibility.

6. Expandability: ESP-NOW protocol supports the transmission of multiple data types, and more complex communication functions can be achieved by customizing the data structure.

ESP-NOW Functionalities

HexArth comes with ESP-NOW functionality, and by default, is in Follower mode upon factory boot. In this mode, the robot allows itself to be controlled by other devices and can also send ESP-NOW messages to other devices to control them.

ESP-NOW Communication Data Structure

Before introducing the meanings of the functional commands, let's first introduce HexArth's ESP-NOW communication data structure, as follows:

struct Vec3 {
    double x;
    double y;
    double z;
};
typedef struct struct_message {
  byte devCode;
  Vec3 ESPInBase[6];
  byte cmd;
  char message[50];
} struct_message;

In this part, the specific value for variables will be set in the JSON commands. Here, we introduce the meaning of variables:

devCode: this device code. We do not use this variable in the demo we use, so you can choose not to set this code (always set it as 0). You can set this variable to differentiate the devices controlled by JSON commands when there are many devices that should be controlled through broadcast rather than multicast. This interface is reserved for you to modify the OnDataRecv() function of esp_now_ctrl.h in the slave demo.

ESPInBase: This is an array of Vec3 structures containing the coordinate values for each leg, unit: mm.

cmd: ESP-NOW control message type. For specific valuing, you can refer to the following JSON command introductions.

message: A character string. When the ESP-NOW control message type (cmd) is 1, this string will be used as a JSON-formatted command, but the command content must not be a command that causes long-term blocking.

Next, let's explore the specific meaning of the related JSON command for ESP-NOW configuration.

Set Broadcast Follower Mode

{"T":300,"mode":1}

{"T":300,"mode":0,"mac":"00:00:00:00:00:00"}

3000: This command is CMD_BROADCAST_FOLLOWER for setting the broadcast follower mode of this device.

mode:
- 1 - [factory default] This device can be controlled by the broadcast signal from other devices.
- 0 - This device can not be controlled by the broadcast signal from other devices.

mac: the MAC address of the only Leader controlling the device when the mode =0.
- The device can be controlled only by the ESP-NOW messages sent by the devices with a given MAC address.
- If the device does not need to be controlled by other devices, you can randomly input a MAC address such as 00:00:00:00:00:00.

Set ESP-NOW Operation Mode

{"T":301,"mode":3}

301: This command is CMD_ESP_NOW_CONFIG for setting the operation mode of ESP-NOW for this device.

mode (byte): The code of the ESP-NOW operation mode.
- 0 - Off.
- 1 - Streaming Multicast Leader: continuously sends its own coordinate position information to devices in the peerList.
- 2 - Streaming Unicast/Streaming Broadcast Leader: continuously sends its own coordinate position information to a device at a specific MAC address. When the MAC address is set to FF:FF:FF:FF:FF:FF, it becomes streaming broadcast control.
- 3 - [Factory Default] Follower: When the robot is in this mode, it can receive ESP-NOW messages from other Leader devices and can also act as a Leader device to send ESP-NOW messages to other devices.

Note: Only in Streaming Multicast and Streaming Unicast/Broadcast modes does the main controlling device continuously send its own coordinate position information to the controlled device(s). Manually moving the main controlling device will cause the controlled device(s) to mimic the same motion.

Get MAC Address of Device

{"T":302}

302: This command is CMD_GET_MAC_ADDRESS for obtaining the MAC address of this device.

After inputting this command, the return value is shown below:

44:17:93:EE:FD:70

Each device has a unique MAC address. When using ESP-NOW features, except for broadcast control, you need to obtain the MAC address of the controlled device. By default, each robot displays its own MAC address on the OLED screen.

Add MAC Address of Controlled Device to PeerList

{"T":303,"mac":"44:17:93:EE:FD:70"}

303: This command is CMD_ESP_NOW_ADD_FOLLOWER for adding the MAC address of the controlled device to peerList, and peerList is for storing the MAC address.

mac: The MAC address of the controlled device to be added.

You can add dozens of MAC addresses to the peerList for multicast control. However, when using multicast control, the peerList should not include the MAC address for broadcast control: FF:FF:FF:FF:FF:FF.

Remove MAC Address of Controlled Device from PeerList

{"T":304,"mac":"44:17:93:EE:FD:70"}

304: This command is CMD_ESP_NOW_REMOVE_FOLLOWER for removing the MAC address of the controlled device from peerList.

mac: The MAC address of the controlled device to be removed.

Multicast Control

# Multicast control: Command devices in peerList to move leg endpoints to specified coordinates.
{"T":305,"dev":0,"x1":156.24,"y1":-109.69,"z1":-80.83,"x2":0.18,"y2":-197.19,"z2":-80.83,"x3":-156.06,"y3":-110,"z3":-80.83,"x4":156.06,"y4":110,"z4":-80.83,"x5":-0.18,"y5":197.19,"z5":-80.83,"x6":-156.24,"y6":109.69,"z6":-80.83,"cmd":0,"megs":"hello!"}

# Multi-cast control, sends the JSON command to turn on the LED to the devices in peerlist
{"T":305,"dev":0,"x1":156.24,"y1":-109.69,"z1":-80.83,"x2":0.18,"y2":-197.19,"z2":-80.83,"x3":-156.06,"y3":-110,"z3":-80.83,"x4":156.06,"y4":110,"z4":-80.83,"x5":-0.18,"y5":197.19,"z5":-80.83,"x6":-156.24,"y6":109.69,"z6":-80.83,"cmd":1,"megs":"{\"T\":114,\"led\":255}"}

305: This command is CMD_ESP_NOW_GROUP_CTRL, which is used to send information through ESP-NOW multicast to all devices in the peerList.

Please refer to ESP-NOW Communication Data Structure. The various keys in this JSON command correspond to the structure variables as follows, with additional supplementary parts:

dev: the corresponding variable is devCode.

x, y, z: Correspond to x, y, z in the ESPInBase array respectively.

cmd: ESP-NOW control message type.
- When cmd is 0, the controlled robot's legs will rotate to the given coordinate positions.
- When cmd is 1, x, y, z are ignored. Input a JSON command in megs that does not cause blocking, and the robot will execute the function corresponding to that JSON command.

megs: the corresponding variable is the message.

Unicast/Broadcast Control

# Unicast control: Send coordinate control command to a specific device.
{"T":306,"mac":"44:17:93:EE:FD:70","dev":0,"x1":156.24,"y1":-109.69,"z1":-80.83,"x2":0.18,"y2":-197.19,"z2":-80.83,"x3":-156.06,"y3":-110,"z3":-80.83,"x4":156.06,"y4":110,"z4":-80.83,"x5":-0.18,"y5":197.19,"z5":-80.83,"x6":-156.24,"y6":109.69,"z6":-80.83,"cmd":0,"megs":"hello!"}

# Broadcast control: Send coordinate control command to all devices.
{"T":306,"mac":"FF:FF:FF:FF:FF:FF","dev":0,"x1":156.24,"y1":-109.69,"z1":-80.83,"x2":0.18,"y2":-197.19,"z2":-80.83,"x3":-156.06,"y3":-110,"z3":-80.83,"x4":156.06,"y4":110,"z4":-80.83,"x5":-0.18,"y5":197.19,"z5":-80.83,"x6":-156.24,"y6":109.69,"z6":-80.83,"cmd":0,"megs":"hello!"}

306: This command is CMD_ESP_NOW_SINGLE for controlling the device of peerList in unicast or broadcast control

mac: The MAC address of the controlled device. When the MAC address is FF:FF:FF:FF:FF:FF, the command is a broadcast signal and will be sent to all devices.