08 Slave Device JSON Instruction Set

From Waveshare Wiki
Jump to: navigation, search

Sub-controller JSON instruction set

In the previous chapter, we introduced a simple demo, in which we send motion control commands to the sub-controller through the host controller, and the sub-controller can receive a lot of instructions, in this chapter we will introduce these instructions.

Composition of JSON instructions

In the previous section, we sent {"T":1,"L":0.2,"R":0.2} instruction as an example, the T value in this JSON data represents the type (Type) of the instruction, the L value represents the target linear velocity of the left (LEFT) wheel, the R value represents the target linear velocity of the right (RIGHT) wheel, and the unit of linear velocity is m/s by default. The parameters of the motion control are the target linear velocity of the left and right wheels, respectively.

All subsequent JSON directives will contain a T-value that defines the type of instruction, but the specific instruction parameters will vary depending on the instruction type.

JSON instruction set

You can view the definitions of these instructions in the json_cmd.h file of our open-source sub-controller demos, or add new sub-controller features to them yourself.

Motion Control Instructions

These instructions are the most basic instructions for mobile robots, which are used for motion-related function control.

Each of the following directives consists of three parts: a case, a short introduction, and a detailed introduction.

CMD_SPEED_CTRL

  • {"T":1,"L":0.5,"R":0.5}
  • Set the target linear velocity of the wheels on both sides (speed closed-loop control)
L and R represent the target linear velocity of the left and right wheels respectively, the unit is m/s, the negative value is the reverse rotation of the substitution, and 0 is the stop. The value range of the target linear speed depends on the diameter of the motor/reducer/wheel used in the product, and the relevant calculation formula can be found in the open source sub-controller demo. It should be noted here that for chassis using carbon brush DC motors, when the absolute value of a given target speed is very small (but not 0), the speed of the product may fluctuate greatly during movement due to the low speed performance of carbon brush DC motors is usually poor.

CMD_PWM_INPUT

  • {"T":11,"L":164,"R":164}
  • Set the PWM value of the driving wheels on both sides (speed open-loop control)
L and R represent the PWM values of the left and right wheels respectively, the range of the values is -255 ~ 255, the negative value represents the reverse, when the absolute value of the value is 255, it means that the PWM is 100%, which means to let the wheels on this side run at full power.

CMD_ROS_CTRL

  • {"T":13,"X":0.1,"Z":0.3}
  • ROS control (speed closed-loop control)
 This instruction is used for the ROS host computer to control the command of chassis movement, X represents the linear speed of movement, the unit is m/s can be negative; Z stands for angular velocity of steering in rad/s and can be negative.

CMD_SET_MOTOR_PID

  • {"T":2,"P":20,"I":2000,"D":0,"L":255}
  • PID controller settings
This command is used to tune the parameters of the PID controller, the PID parameter in the above JSON example is the default parameter of the product, where L stands for WINDUP_LIMITS, which is the reserved interface, This parameter is not currently used in the current product.

OLED Display Control Command

An OLED display is installed on the product, which communicates with the ESP32 module of the host computer of the sub-controller through I2C, and the host computer can change the content displayed on the display by sending JSON commands.

CMD_OLED_CTRL

  • {"T":3,"lineNum":0,"Text":"putYourTextHere"}
  • Control the display display to display custom content
lineNum is the number of lines, a JSON command can change the content of a line, after the sub-controller receives a new instruction, the default OLED interface will disappear when booted, and it will be replaced by your newly added content, For the 0.91-inch OLED display used in most products, the lineNum value can be 0, 1, 2, 3, a total of four lines; Text is the text you want to display on this line, and if you have too much content in this line, it will automatically wrap, but it will also squeeze out the last line.

CMD_OLED_DEFAULT

  • {"T":-3}
  • Control the display to display custom content
 Use this command to make the OLED display display display the default screen when powered on.

Module Type

Different types of modules will be installed on the mobile chassis (none/robotic arm/pan-tilt),Use this command to tell the sub-controller the type of module currently installed,This instruction is usually automatically sent to the sub-controller when the host controller is turned on,This part will be introduced in the following chapters。

CMD_MODULE_TYPE

  • {"T":4,"cmd":0}
  • Set the module type
cmd value represents the type of module, there are currently three types to choose from, 0: install nothing, 1: robotic arm, 2: pan-tilt

IMU related functions

The chassis is equipped with an IMU sensor, you can get the data of the IMU sensor through the following commands, it should be noted here that the chassis information continuous feedback function (which contains the IMU information) will be turned on by default after the product is turned on, and the IMU related functions here are only necessary to use when the chassis information continuous feedback function is turned off.

CMD_GET_IMU_DATA

  • {"T":126}
  • Get IMU data
 Send this command to get the data of the IMU.

CMD_CALI_IMU_STEP

  • {"T":127}
  • IMU Calibration (Reserved Interface)
Current product program does not need to perform calibration, this command is reserved interface.

CMD_GET_IMU_OFFSET

  • {"T":128}
  • Get the offset of the current IMU (reserved interface)
 Use this command to feedback the current offset of each axis of the IMU.

CMD_SET_IMU_OFFSET

  • {"T":129,"x":-12,"y":0,"z":0}
  • Set the offset of the IMU (reserved interface)
 Use this command to set the offset of each axis of the IMU, this command is a reserved interface, and the current product does not need to execute this command.

Chassis information feedback

CMD_BASE_FEEDBACK

  • {"T":130}
  • Chassis information feedback
The product usually turns on chassis information feedback by default after booting, which is automatic, if the chassis information continuous feedback function is turned off, you need to obtain the chassis information at a time, you can use this command to obtain the basic information of the chassis.

CMD_BASE_FEEDBACK_FLOW

  • {"T":131,"cmd":1}
  • Continuous chassis information feedback
The value of cmd is set to 1, and the function is turned on by default, and the chassis information will be continuously fed; When the value of cmd is set to 0, turn off the function, and after the function is turned off, the host computer can get the chassis information through CMD_BASE_FEEDBACK.

CMD_FEEDBACK_FLOW_INTERVAL

  • {"T":142,"cmd":0}
  • Set the extra interval time for continuous feedback
The value of cmd is the extra interval that needs to be set, the unit is ms, and the frequency of chassis feedback can be adjusted through this command.

CMD_UART_ECHO_MODE

  • {"T":143,"cmd":0}
  • Set the command echo mode
When the value of cmd is set to 0, turn off echo; When the value of cmd is set to 1, the echo is enabled, and when the command echo mode is enabled, the sub-controller will output the received command.

WIFI related settings

CMD_WIFI_ON_BOOT

  • {"T":401,"cmd":3}
  • Set the WIFI mode when powered on.
When cmd is 0, turn off the WIFI function. 1-ap； 2-sta； 3-ap+sta。

CMD_SET_AP

  • {"T":402,"ssid":"UGV","password":"12345678"}
  • Set the name and password of the AP mode. (ESP32 builds hotspot)

CMD_SET_STA

  • {"T":403,"ssid":"WIFI_NAME","password":"WIFI_PASSWORD"}
  • Set the name and password of the STA mode. (ESP32 goes to connect to known hotspots)

CMD_WIFI_APSTA

  • {"T":404,"ap_ssid":"UGV","ap_password":"12345678","sta_ssid":"WIFI_NAME","sta_password":"WIFI_PASSWORD"}
  • Set the name and password of the AP and STA modes. (AP+STA mode)

CMD_WIFI_INFO

  • {"T":405}
  • Get the information of the current WIFI.

CMD_WIFI_CONFIG_CREATE_BY_STATUS

  • {"T":406}
  • Create a new WIFI profile with the current settings.

CMD_WIFI_CONFIG_CREATE_BY_INPUT

  • {"T":407,"mode":3,"ap_ssid":"UGV","ap_password":"12345678","sta_ssid":"WIFI_NAME","sta_password":"WIFI_PASSWORD"}
  • Create a new WIFI profile with the settings you entered.

CMD_WIFI_STOP

  • {"T":408}
  • Disconnect WIFI.

12V switch and pan-tilt settings

CMD_LED_CTRL

  • {"T":132,"IO4":255,"IO5":255}
  • 12V switch output setting
The sub-controller of the product has two 12V switch interfaces, each with 2 interfaces for a total of four interfaces, you can set the output voltage of these interfaces through this command, when the value is 255, it is 3S battery voltage. 
By default, the product uses these interfaces to control the LED lights, and you can control the brightness of the LED lights through this command.

CMD_GIMBAL_CTRL_SIMPLE

  • {"T":133,"X":0,"Y":0,"SPD":0,"ACC":0}
  • Basic Pan-tilt Control Command
This command is used to control the orientation of the pan-tilt. 
X is the horizontal direction in angle, positive values to the right, negative values to the left, and the value range is -180 to 180. 
Y is the direction of the value in angle, positive values are up, negative values are down, and the values range from -30 to 90. 
SPD is the velocity, ACC is the acceleration, and when the value is 0, it is the fastest speed/acceleration.

CMD_GIMBAL_CTRL_MOVE

  • {"T":134,"X":45,"Y":45,"SX":300,"SY":300}
  • Pan-tilt Continuous Control Command
This command is used to continuously control the pan-tilt orientation. 
X is the horizontal direction in angle, positive values to the right, negative values to the left, and the value range is -180 to 180. 
Y is the direction of the value in angle, positive values are up, negative values are down, and the values range from -30 to 90. 
SX and SY are the speeds of the X and Y axes, respectively.

CMD_GIMBAL_CTRL_STOP

  • {"T":135}
  • Pan-tilt Stop Command
When using the above command to make the pan-tilt move, you can use this command to stop the pan-tilt at any time.

CMD_GIMBAL_STEADY

  • {"T":137,"s":0,"y":0}
  • Pan-tilt self-stabilization function
When s is 0, turn off this function when s is 1, after this function is enabled, the pan-tilt will automatically adjust the vertical angle of the pan-tilt through the IMU data, and y is the target angle between the pan-tilt and the ground (even if the pan-tilt self-stabilization function is turned on, the camera can also look up and down).

CMD_GIMBAL_USER_CTRL

  • {"T":141,"X":0,"Y":0,"SPD":300}
  • Pan-tilt UI Control
This command is used to control the pan-tilt in the UI interface, the X value can be -1, 0 and 1, -1 is to turn left, 0 is to stop, and 1 is to turn right. 
The Y value can be -1, 0 and 1, -1 for downward rotation, 0 for stopping, and 1 for upward rotation. 
SPD is velocity

Robotic Arm Control

CMD_MOVE_INIT

  • {"T":100}
  • The robotic arm moves to the initial attitude
 Under normal circumstances, the robotic arm will automatically rotate to the initial position when it is turned on. This directive causes process blocking.

CMD_SINGLE_JOINT_CTRL

  • {"T":101,"joint":0,"rad":0,"spd":0,"acc":10}
  • Single-axis motion control of the robotic arm
  • joint: joint serial number.
    • 1: BASE_JOINT the basal joint.
    • 2: SHOULDER_JOINT shoulder joint.
    • 3: ELBOW_JOINT elbow joint.
    • 4: EOAT_JOINT wrist/jaw joints.
  • rad: The angle to be rotated to (displayed in radians), based on the initial position of each joint, the default angle and direction of rotation of each joint are as follows:
    • The default angle of the initial position of the BASE_JOINT is 0, and the angle rotation range is between 3.14 and -3.14. As the angle increases, the basal joint rotates to the left; When the angle is reduced, the base joint is rotated to the right.
    • The default angle of the initial position of the SHOULDER_JOINT is 0, and the angle rotation range is between 1.57 and -1.57. When the angle increases, the shoulder joint rotates forward; When the angle is reduced, the shoulder joint rotates backwards.
    • The default angle of the ELBOW_JOINT's initial position is 1.570796, and the angle rotation range is between 3.14 and -1.11. When the angle increases, the elbow rotates downward; When the angle is reduced, the elbow rotates in the opposite direction.
    • The default angle of the initial position of the EOAT_JOINT is 3.141593. The default jaw joint is the jaw joint, which has an angle rotation range between 1.08 and 3.14, and when the angle is reduced, the jaw joint opens. If the wrist joint is replaced, the angle rotation range is between 1.08 and 5.20, and when the angle increases, the wrist joint rotates downward; When the angle is reduced, the wrist joint is turned upward.
  • SPD: The speed of rotation, the speed unit is steps per second, one revolution of the servo is 4096 steps, the higher the value, the faster the speed, when the speed value is 0, it rotates at the maximum speed.
  • ACC: Acceleration at the beginning and end of the rotation, the smaller the value, the smoother the start and stop, the value can be 0-254, the unit is 100 steps/second^2. If set to 10, the speed is varied at a square acceleration of 1000 steps per second. When the acceleration value is 0, the maximum acceleration is followed.

CMD_JOINTS_RAD_CTRL

  • {"T":102,"base":0,"shoulder":0,"elbow":1.57,"hand":1.57,"spd":0,"acc":10}
  • Control the rotation of all joints of the robotic arm in the form of radian system
  • base: the angle of the basic joint, the angle rotation range is shown above CMD_SINGLE_ JOINT_CTRL" command.
  • shoulder: The angle of the shoulder joint.
  • elbow: The angle of the elbow joint.
  • Hand: The angle of the gripper/wrist joint.
  • SPD: The speed of rotation, the speed unit is steps/second, the rotation of the servo is 4096 steps, the higher the value, the faster the speed, when the speed value is 0, it rotates at the maximum speed.
  • ACC: Acceleration at the beginning and end of rotation, the smaller the value, the smoother the start and stop, the value can be 0-254, the unit is 100 steps/sec^2. If it is set to 10, the speed will be changed according to the square acceleration and deceleration of 1000 steps per second. When the acceleration value is 0, the maximum acceleration is followed.

CMD_SINGLE_AXIS_CTRL

  • {"T":103,"axis":2,"pos":0,"spd":0.25}
  • Single-axis coordinate control
  • axis,1-x,2-y,3-z,4-t. Except for the T-axis, the pos parameter of the other axes is mm, and the unit of the T-axis is rad. SPD is the velocity coefficient, and the higher the value, the faster the speed.

CMD_XYZT_GOAL_CTRL

  • {"T":104,"x":235,"y":0,"z":234,"t":3.14,"spd":0.25}
  • Robotic arm coordinate motion control (inverse kinematics control)
 This function will cause a block

CMD_XYZT_DIRECT_CTRL

  • {"T":1041,"x":235,"y":0,"z":234,"t":3.14}
  • Robotic Arm Coordinate Motion Control (Inverse Kinematics Control)
 This function does not cause blocking

CMD_SERVO_RAD_FEEDBACK

  • {"T":105}
  • Feedback the coordinate information of the robotic arm

CMD_EOAT_HAND_CTRL

  • {"T":106,"cmd":1.57,"spd":0,"acc":0}
  • End joint control (radian)
  • cmd: The angle to be rotated (displayed in radians). The default angle of the initial position of the EOAT_JOINT is 3.141593.
    • The default of the product is the jaw joint, the angle rotation range is between 1.08 and 3.14, when the angle is reduced, the jaw joint will be opened.
    • If the wrist joint is replaced, the angle rotation range is between 1.08 and 5.20, and the wrist joint rotates downward when the angle increases, and the wrist joint turns upward when the angle decreases.
  • SPD: The speed of rotation, the speed unit is steps/second, the rotation of the servo is 4096 steps, the higher the value, the faster the speed, when the speed value is 0, it rotates at the maximum speed.
  • ACC: Acceleration at the beginning and end of rotation, the smaller the value, the smoother the start and stop, the value can be 0-254, the unit is 100 steps/sec^2. If it is set to 10, the speed will be changed according to the square acceleration and deceleration of 1000 steps per second. When the acceleration value is 0, the maximum acceleration is followed

CMD_EOAT_GRAB_TORQUE

*{"T":107,"tor":200}
  • Jaw Force Control
tor's value can be up to 1000, representing 100% strength.

CMD_SET_JOINT_PID

  • {"T":108,"joint":3,"p":16,"i":0}
  • Joint PID settings

CMD_RESET_PID

  • {"T":109}
  • Reset the joint PID

CMD_SET_NEW_X

  • {"T":110,"xAxisAngle":0}
  • Set the new X-axis direction

CMD_DYNAMIC_ADAPTATION

  • {"T":112,"mode":0,"b":1000,"s":1000,"e":1000,"h":1000}
  • Adaptive control of dynamic external forces

Other settings

CMD_HEART_BEAT_SET

  • {"T":136,"cmd":3000}
  • Set the heartbeat function time
cmudd unit is ms, you can use this command to set the heartbeat function time, if the sub-controller does not receive a new exercise command within the time, it will automatically stop moving, It is used to avoid the host controller crashing during use, causing the sub-controller to move all the time. During the process, the host controller crashed, causing the sub-controller to keep moving.

CMD_SET_SPD_RATE

  • {"T":138,"L":1,"R":1}
  • Set the left and right speed ratio
The product uses the principle of differential steering, when the left and right wheels of the product give the same target speed, the product may not go straight due to encoder error or tire grip error, you can use this command to fine-tune the speed of the left and right wheels, for example, the left wheel needs to rotate slower, you can change the value of L to 0.98. Try not to set values greater than one for L and R values.

CMD_GET_SPD_RATE

  • {"T":139}
  • Get the current velocity ratio
Use this command to get the current velocity ratio

ESP-NOW related settings

CMD_BROADCAST_FOLLOWER

  • {"T":300,"mode":1}
  • {"T":300,"mode":0,"mac":"CC:DB:A7:5B:E4:1C"}
  • Set the mode in which ESP-NOW is controlled by broadcast
    • When mode is set to 1, other devices can be controlled by broadcast commands; When the mode is 0, it can only be controlled by the device with the MAC address.

CMD_GET_MAC_ADDRESS

  • {"T":302}
  • Get the MAC address of the current device

CMD_ESP_NOW_ADD_FOLLOWER

  • {"T":303,"mac":"FF:FF:FF:FF"}
  • Add MAC address to the controlled device (PEER)

CMD_ESP_NOW_REMOVE_FOLLOWER

  • {"T":304,"mac":"FF:FF:FF:FF:FF:FF:FF"}
  • Remove MAC address from PEER

CMD_ESP_NOW_GROUP_CTRL

  • {"T":305,"dev":0,"b":0,"s":0,"e":1.57,"h":1.57,"cmd":0,"megs":"hello!"}
  • ESP-NOW multicast control

CMD_ESP_NOW_SINGLE

  • {"T":306,"mac":"FF:FF:FF","dev":0,"b":0,"s":0,"e":1.57,"h":1.57,"cmd":0,"megs":"hello!"}
  • ESP-NOW unicast/multicast control

Task file related functions

This function belongs to the high-level functions of the sub-controller, and the following operations are usually not required when used with the host controller.

CMD_SCAN_FILES

  • {"T":200}
  • Scan the current task file

CMD_CREATE_FILE

  • {"T":201,"name":"file.txt","content":"inputContentHere."}
  • Create a task file

CMD_READ_FILE

  • {"T":202,"name":"file.txt"}
  • Read the task file

CMD_DELETE_FILE

  • {"T":203,"name":"file.txt"}
  • Delete the task file

CMD_APPEND_LINE

  • {"T":204,"name":"file.txt","content":"inputContentHere."}
  • Add a new command at the end of the task file

CMD_INSERT_LINE

  • {"T":205,"name":"file.txt","lineNum":3,"content":"content"}
  • Inserts a new command in the middle of the task file

CMD_REPLACE_LINE

  • {"T":206,"name":"file.txt","lineNum":3,"content":"Content"}
  • Replace a command in the task file

Bus Servo Settings

CMD_SET_SERVO_ID

  • {"T":501,"raw":1,"new":11}
  • Change the servo ID
raw is the original ID of the servo (the new servos are all 1), new is the ID to be changed, the maximum is not more than 254, it cannot be negative, and 255 is the broadcast ID.

CMD_SET_MIDDLE

  • {"T":502,"id":11}
  • Set the current position of the servo to the servo center (only ST series servos are valid).

CMD_SET_SERVO_PID

  • {"T":503,"id":14,"p":16}
  • Set the P value of the servo PID.

ESP32 Related Functions

CMD_REBOOT

  • {"T":600}
  • Restart.

CMD_FREE_FLASH_SPACE

  • {"T":601}
  • GET THE AMOUNT OF SPACE LEFT FOR FLASH.

CMD_BOOT_MISSION_INFO

  • {"T":602}
  • Outputs the current boot task file.

CMD_RESET_BOOT_MISSION

  • {"T":603}
  • Reset the boot task file.

CMD_NVS_CLEAR

  • {"T":604}
  • Clean up the NVS area of ESP32, if the WIFI connection cannot be successful, you can try to call this command and then restart.

CMD_INFO_PRINT

  • {"T":605,"cmd":1}
  • Set the feedback mode.
  • When cmd is set to 1, the debugging information is printed. 2. Continuous chassis information feedback; 0, nothing feedback.
Retrieved from "https://www.waveshare.com/w/index.php?title=08_Slave_Device_JSON_Instruction_Set&oldid=93367"