MainComs Packet (Bi-Direction, Firmware ↔︎ ROS driver)¶

This packet includes general commands for firmware control sent from the ROS driver,
the corresponding responses from the firmware, and periodic report packets transmitted from the firmware.

Detailed Packet Specifications¶

Sent From The ROS driver¶

This packet must be sent from the ROS driver to the firmware through UDP port number 49158.

MainComs Command Parameter¶

The COMS_COMMAND field is represented as a 32-bit integer value in the range 0x00000000 to 0x7FFFFFFF.
All arguments associated with this field are represented as 32-bit unsigned integer values.

Value (Hex)	Name	Description
0x00000000	COMS_COMMAND_NONE	Do not use this param for packet.
0x00000001	COMS_COMMAND_SHUTDOWN	Shutdown the robot.
0x00000002	COMS_COMMAND_SET_ESTOP	Trigger or release the emergency stop for the motor.
0x00000003	COMS_COMMAND_ENABLE_POWER_SWITCH	Turn on the power switches. See the Usage section for more information.
0x00000004	COMS_COMMAND_DISABLE_POWER_SWITCH	Turn off the power switches. See the Usage section for more information.
0x00000005 - 0x00000007	N/A	Currently not in use.
0x00000008	COMS_COMMAND_PING	This parameter is used to check the connection with the firmware.
0x00000009	COMS_COMMAND_GET_VERSION	Query the firmware version and hardware revision of the main controller.
0x0000000A	COMS_COMMAND_GET_LED_DRIVER_VERSION	Query the firmware version and hardware revision of the BaseLEDDriver
0x0000000B	COMS_COMMAND_GET_MOTOR_VERSION	Query the firmware version and hardware revision of the Motor driver
0x0000000C	N/A	Currently not in use.
0x0000000D	COMS_COMMAND_ENABLE_CAN_COMM	Enable or disable the CAN communication for the Top-Controller
0x0000000E	N/A	Currently not in use.
0x0000000F	COMS_COMMAND_REMOTE_RESET	Reset the robot.
0x00000010 - 0x00000012	N/A	Currently not in use.
0x00000013	COMS_COMMAND_DISABLE_CONTACT_CHARGING	Enable or disable the contact charging with timeout value.

Field Layout¶

Byte Offset	Field Name	Type	Size (Bytes)	Description
0 - 3	Header	Non-Timestamp Header	4	Refer to Non-Timestamp Header
4 - 7	Parameter	COMS_COMMAND	4	Refer to COMS_COMMAND
8 - 11	Argument	uint32	4	The type of the argument varies depending on the associated `COMS_COMMAND` Please refer to Usage for more detail

Usage¶

COMS_COMMAND_SHUTDOWN:
- Purpose
  This command is used to shut down the robot.
- Argument Usage
  Not used, set to 0.
- Robot shutdown behavior
  No response packet is generated by the firmware for this command.
  To shut down the robot, the ROS driver must stop transmitting COMS_COMMAND_PING packets after issuing this command.
  Step 1: If no COMS_COMMAND_PING packets are received by the firmware for more than 10 seconds, the firmware enters the shutdown monitoring state.
  Step 2: If, in addition, no ICMP ping is observed on the physical Ethernet line between the firmware and the PC for more than 20 seconds, the firmware determines that the PC system has been completely shut down.
  Step 3: At this point, the firmware turns off the power switch to shut down the robot.
  
  This mechanism ensures that the PC and all subsystems in the robot are safely shut down before the main power is disconnected.
COMS_COMMAND_SET_ESTOP
- Purpose
  This command is used to enable or disable the emergency stop.
- Argument Usage
  0: Disable the emergency stop
  1: Enable the emergency stop
- Emergency stop behavior
  No response packet is generated by the firmware for this command. When the firmware receives this command with an argument value of 1, it sends an emergency signal to the motor driver, which locks the wheels of the robot.
  The robot cannot be moved until the emergency stop is disabled by sending this command with an argument value of 0.
COMS_COMMAND_ENABLE_POWER_SWITCH / DISABLE_POWER_SWITCH
- Purpose These commands are used to enable or disable specific power switches in the robot system.
- Argument Usage
  Both commands use the same argument value to specify the target power switch:
  0: Power switch for 12V
  1: Power switch for the PC
  2: Power switch for 5V
  3: Power switch for the Lidar module
  4: Power switch for the Motor driver
  5: Power switch for the 5V USB
  6: Power switch for the External 24V
- Enable / Disable the power switch behavior
  Only one power switch ca be controlled per packet.
  When executed, the firmware applies the requested power switch operation.
  The firmware does not generate a direct response packet for these commands. Instead, the current state of the power switches is reported periodically in the GenericStatus packet.
COMS_COMMAND_PING
- Purpose
  This commands is used to verify that the ROS driver and the firmware are still connected.
- Argument Usage
  Its value is incremented for each packet transmitted.(Range: 0 - 0xFFFFFFFF)
- Ping by the command behavior
  When the ROS driver transmits this command, the firmware responds by echoing the same argument value.
  The response from the firmware is sent in a MainComsPingEcho packet.
COMS_COMMAND_GET_VERSION / GET_LED_DRIVER_VERSION / GET_MOTOR_VERSION
- Purpose
  These commands are used to query the firmware version and hardware revision of each controller:
  COMS_COMMAND_GET_VERSION - Main Controller
  COMS_COMMAND_GET_LED_DRIVER_VERSION - Base Led Driver
  COMS_COMMAND_GET_MOTOR_VERSION - Motor Driver
- Argument Usage
  Not used, set to 0.
- Version query behavior by COMS_COMMAND
  When the firmware receives a version query command, it responds with the corresponding MainComsVersionResponse packet.
COMS_COMMAND_ENABLE_CAN_COMM
- Purpose
  The main controller firmware can communicate with sub-controller called TopController through a CAN interface.
  By enabling this communication, the PC can control or monitor the devices on the TopController using CANpackets.
  To establish this communication path, the ROS driver must send this command.
- Argument Usage
  0: disable the CAN communication function
  1: enable the CAN communication function
- Enable or disable the CAN communication behavior
  No response packet is generated by the firmware for this command.
  After CAN communication is enabled, the firmware begins transmitting CANpackets to the ROS driver.
COMS_COMMAND_REMOTE_RESET
- Purpose
  This command is used to reboot the robot
- Argument Usage
  0: Immediate reboot
  1: Safety reboot
- Reboot behavior
  The firmware reboots the robot immediately without waiting for the PC to shut down for immediate reboot.
  The firmware waits until the PC has been completely shut down, and then performs the reboot following the same procedure as the Robot Shutdown Behavior for safety reboot.
COMS_COMMAND_DISABLE_CONTACT_CHARGING
- Purpose
  This command is used to disable(pause) or enable the contact charging.
- Argument Usage
  When pause the contact charging, input the pause time in 0.1s.
  When enable the contact charging in pause state, input 0.
- Pause or resume the contact charging behavior
  No response packet is generated by the firmware for this command.
  If the robot is undocked from the contact charger, electrical sparks may occur due to residual charging current, potentially causing damage to both the robot and the charger.
  Therefore, the ROS driver shall issue this command prior to detaching from the contact charger.
In contrast, explicit enabling of contact charging is typically unnecessary. After the pause time elapses, the firmware automatically initiates contact charging upon docking with the charger.

However, if undocking is canceled before the disable period has elapsed and contact charging should be resumed, the ROS driver may send this command with argument = 0 to re-enable contact charging.

Sent From The Firmware¶

This packet must be sent from the firmware to the ROS driver through UDP port number 49157.
Packets transmitted from the firmware include response to COMS_COMMANDpackets received from the ROS driver and status reports about the firmware.

MainComs Packet Parameter¶

The COMS_PACKET field is represented as a 32-bit integer value in the range 0x00000000 to 0x7FFFFFFF.

Value (Hex)	Name	Description
0x00000000	COMS_PACKET_NONE	Do not use this param for packet.
0x00000001	COMS_PACKET_IVT	Report packet for current, voltage and temperature.
0x00000002	N/A	Currently not in use.
0x00000003	COMS_PACKET_PING_ECHO	Response for the `COMS_COMMAND_PING.`
0x00000004	N/A	Currently not in use.
0x00000005	COMS_PACKET_GENERIC_STATUS	Report packet for generic status of the firmware.
0x00000006 - 0x00000008	N/A	Currently not in use.
0x00000009	COMS_PACKET_MAIN_VERSION	Response for `COMS_COMMAND_GET_VERSION`.
0x0000000A	COMS_PACKET_LED_DRIVER_VERSION	Response for `COMS_COMMAND_GET_LED_DRIVER_VERSION`.
0x0000000B	COMS_PACKET_MOTOR_DRIVER_VERSION	Response for `COMS_COMMAND_GET_MOTOR_VERSION`.
0x0000000C	COMS_PACKET_MOTOR_COMS_ALERT	Report packet for communication alert count between main and motor driver.

Field Layout¶

Byte Offset	Field Name	Type	Size (Bytes)	Description
0 - 3	Header	Non-Timestamp Header	4	Refer to Non-Timestamp Header
4 - 7	Parameter	COMS_PACKET	4	Refer to COMS_PACKET_PARAMETER
8 - ..	Payload	Variable	Variable	Varies by `COMS_PACKET` See the Payload Layout & Usage section for details.

For example, GenericStatus packet look like below:

Byte Offset	Field Name	Type	Size (Bytes)
0 - 3	Header	Non-Timestamp Header	4
4 - 7	Parameter	COMS_PACKET	4
8 - 19	GenericStatus Payload	GenericStatus	12

Payload Layout & Usage¶

This section provides the payload structure and usage details corresponding to each COMS_PACKET_PARAMETER.

COMS_PACKET_IVT

This packet is report packet from the firmware.

IVT type

Byte Offset	Field Name	Type	Size (Bytes)	Description
0 - 3	Current	32-bit float	4	Measured current [A] of the specified electric line
4 - 7	Voltage	32-bit float	4	Measured voltage [V] of the specified electric line
8 - 11	Power	32-bit float	4	Measured power [W] of the specified electric line

IVT Packet Payload

Byte Offset	Field Name	Type	Size (Bytes)	Description
0 - 15	Temperature[4]	32-bit float array	4 x 4	Measured temperature [°C] of the specified parts. Index: 0 - Reserved, set to 0 1 - Reserved, set to 0 2 - CPU temperature of the Main Controller 3 - Board temperature of the Main Controller
16 - 111	IVT[8]	IVP array	12 x 8	Array of IVP structures, each representing current, voltage, and power measurements of an electric line. Index: 0 - 12V power line 1 - 5V power line 2 - 12V for PC power line 3 - Motor power line 4 - Charger line 5 - Battery line 6 - Main 24V power line 7 - Reserved, set to 0

Usage

The firmware periodically transmits IVT (electrical and temperature) information to the ROS driver at an interval of 500 ms.

COMS_PACKET_PING_ECHO

This packet is the response for the COMS_COMMAND_PING.
PingEcho Packet Payload

Byte Offset	Field Name	Type	Size (Bytes)	Description
0 - 3	Echo	uint32	4	The `Echo` field stores the argument value received in the corresponding `COMS_COMMAND_PING` command.

Usage
This packet is generated by the firmware as a response to the COMS_COMMAND_PING command from the ROS driver. The firmware echoes the argument value of the received COMS_COMMAND_PING in the payload of this packet.

COMS_PACKET_GENERIC_STATUS

This packet is report packet from the firmware.

GenericStatus Packet Payload

Byte Offset	Field Name	Type	Size (Bytes)	Description
0	PWR button	unsigned char	1	State of main power button 0 - Released 1 - Pressed
1	Reserved1	unsigned char	1	Reserved, set to 0
2	Reserved2	unsigned char	1	Reserved, set to 0
3 - 9	Power switch state[7]	unsigned char array	7	State if the power switch 0 - Turned off 1 - Turned on Index: 0 -12V power switch 1- 12V PC power switch 2 - 5V power switch 3 - Lidar power switch 4 - Motor power switch 5 - 5V USB power switch 6 - External 24V power switch
10	E-stop state switch	unsigned char	1	State of the emergency stop switch 0 - Released 1 - Pressed
11	Reserved3	unsigned char	1	Reserved, set to 0

Usage

The firmware periodically transmits the COMS_PACKET_GENERIC_STATUS packet to the ROS driver at a fixed interval of 500 ms.
This packet provides the current status of the main power button, the emergency stop switch, and the state of all power switches.
Since the commands COMS_COMMAND_ENABLE_POWER_SWITCH and COMS_COMMAND_DISABLE_POWER_SWITCH do not generate response packets from the firmware, the Power switch state field in this packet serves as the indicator for verifying the actual status of each power switch.

COMS_PACKET_XXX_VERSIONs:
COMS_PACKET_MAIN_VERSION
COMS_PACKET_LED_DRIVER_VERSION
COMS_PACKET_MOTOR_DRIVER_VERSION

These packets are the response for the COMS_COMMAND_GET_XXX_VERSIONs.

Version Packet Payload

Byte Offset	Field Name	Type	Size (Bytes)	Description
0 - 3	Hardware Revision	uint32	4	Hardware revision number of the target controller
4 - 7	Major	uint32	4	Major version number
8 - 11	Minor	uint32	4	Minor version number
12 - 15	Revision	uint32	4	Revision version number
16 - 19	Build	uint32	4	Build version number

Usage
This packet is transmitted by the firmware as a response to the COMS_COMMAND_GET_XXX_VERSIONS commands.
It provides both the hardware revision and firmware version information of the specified controller (Main Controller, LED Driver, or Motor Driver).

COMS_PACKET_MOTOR_COMS_ALERT

This packet is report packet from the firmware.

ComsAlert Packet Payload

Byte Offset	Field Name	Type	Size (Bytes)	Description
0 - 3	Alert Count	uint32	4	This field indicates the number of communication alert events detected between the Main Controller and the Motor Driver.

Usage
The firmware periodically transmits the COMS_PACKET_MOTOR_COMS_ALERT packet to the ROS driver at a fixed interval of 500 ms.
The Alert Countis incremented whenever a communication timeout is detected between the Main Controller and Motor Driver.