Robotino3 IO protocol

Description of the data exchange protocol between LPC2378 and COM-Express module over USB

Most of the I/Os comming with Robotino 3 are still connected to a NXP LPC2378 microcontroller (MC). In contrast to previous versions of Robotino the interface between the MC and Robotino's internal industral PC is no longer RS232 but USB. This page describes the protocol used for communication between MC and PC over USB.

Package assembly

All data send from PC to MC and vice versa has the form

Field name	Bytes	Description
Head	1	Start of package
Length	2	Length of package payload
Payload		Payload data
Checksum	2	Calculated from length and payload bytes

Head

The package header is the unique byte 0xAA.

Length

The number of bytes of the (not escaped) payload data.

package[1] = length & 0xFF;
package[2] = 0xFF & ( length >> 8 );

Payload

The package payload data. The payload is composed of one or more commands. The payload send to the LPC2378 must not be larger than 128 bytes.

Checksum

Complement 2 of the sum of Length and Payload bytes before escaping.

uint16 calculate_checksum( const uint8* data, int dataSize )
{
  uint16 out = 0;
  for( int i=0; i<dataSize; ++i )
  {
    out += *p;
    ++data;
  }
  return 0xffff & ( (1<<16) - out );
}

Data escaping

The Head byte 0xAA must be unique through out all data send. By this the receiver knows that whenever it reads 0xAA that a new package begins. This is achieved by going through all the Length, Payload and Checksum bytes and whenever 0xAA or the escape byte 0x55 is found this byte is prefixed with 0x55 and the byte is xored with 0x20.

uint8* data; //the complete package data (Head, Length, Payload, Checksum)
uint8* escapedData; //buffer big enough to hold the escaped package data
for( int i=1; i<numBytesInData; ++i ) //not that we are starting at 1, we do not escape the Head
{
  if( 0xAA == *data || 0x55 == *data )
  {
    *(escapedData+++) = 0x55;
    *(escapedData++) = ( *data ^ 0x20 );
  }
  else
  {
    *(escapedData++) = *data;
  }
  ++data;
}

When reading an escaped package look for the escape byte 0x55. When you found 0x55 in the stream read the next byte and xor it with 0x20 to get the unescaped value.

QByteArray read( int length ) const
{
  QByteArray ba( length, 0 );
  int i=0;
  while( i<length )
  {
    char ch = 0;
    if( 1 != _serial->read( (unsigned char*)&ch, 1 ) )
    {
      throw ParserException( "Error reading 1 byte" );
    }
    if( 0x55 == ch )
    {
      if( 1 != _serial->read( (unsigned char*)&ch, 1 ) )
      {
        throw ParserException( "Error reading 1 byte" );
      }
      ba[i] = ( ch ^ 0x20 );
    }
    else if( 0xAA == ch )
    {
      throw ParserException( "Found HEAD" );
    }
    else
    {
      ba[i] = ch;
    }
    ++i;
  }
  return ba;
}

Commands

Field name	Bytes	Description
Tag	1	The command tag
Length	1	Number of bytes of command data
Data		The command data. If Length=0 there is no Data field at all.

GET_HW_VERSION

Name	Value	Command data	Description	Direction
GET_HW_VERSION	1	none	Requesting the hardware version	PC->MC

HW_VERSION

Name	Value	Command data	Description	Direction
HW_VERSION	2	String	Response to GET_HW_VERSION	MC->PC

GET_SW_VERSION

Name	Value	Command data	Description	Direction
GET_SW_VERSION	3	none	Requesting the software version	PC->MC

SW_VERSION

Name	Value	Command data	Description	Direction
SW_VERSION	4	String	Response to GET_SW_VERSION	MC->PC

GET_DISTANCE_SENSOR_READINGS

Name	Value	Command data	Description	Direction
GET_DISTANCE_SENSOR_READINGS	5	none	Requesting the readings of all infrared distance sensors	PC->MC

DISTANCE_SENSOR_READINGS

Name	Value	Command data	Description	Direction
DISTANCE_SENSOR_READINGS	6	Byte Type Description 0-3 float32 ADC reading in Volts of distance sensor 0 ... 32-35 float32 ADC reading in Volts of distance sensor 8	Response to GET_DISTANCE_SENSOR_READINGS.	MC->PC

SET_MOTOR_SPEED

Name	Value	Command data	Description	Direction
SET_MOTOR_SPEED	9	Byte Type Description 0 uint8 motor number 1-2 int16 speed set-point in rpm (rounds per minute)	Set the speed set-point for one motor	PC->MC

GET_ALL_MOTOR_SPEEDS

Name	Value	Command data	Description	Direction
GET_ALL_MOTOR_SPEEDS	10	none	Requesting the speed of all motors	PC->MC

ALL_MOTOR_SPEEDS

Name	Value	Command data	Description	Direction
ALL_MOTOR_SPEEDS	11	Byte Type Description 0-1 int16 speed of motor 0 in rpm ... 6-7 int16 speed of motor 3 in rpm	Response to GET_ALL_MOTOR_SPEEDS.	MC->PC

SET_MOTOR_POSITION

Name	Value	Command data	Description	Direction
SET_MOTOR_POSITION	12	Byte Type Description 0 uint8 motor number 1-4 int32 motor position in encoder ticks	Set the position counter of one motor	PC->MC

GET_ALL_MOTOR_POSITIONS

Name	Value	Command data	Description	Direction
GET_ALL_MOTOR_POSITIONS	13	none	Requesting the position of all motors	PC->MC
ALL_MOTOR_POSITIONS	14	Byte Type Description 0-3 int32 position of motor 0 ... 12-15 int32 position of motor 4	Response to GET_ALL_MOTOR_POSITIONS.	MC->PC

SET_MOTOR_PID_PARAMETERS

Name	Value	Command data	Description	Direction
SET_MOTOR_PID_PARAMETERS	15	Byte Type Description 0 uint8 motor number 1-4 float kp (a value less than 0 sets kp to the build in default) 5-8 float ki (a value less than 0 sets ki to the build in default) 9-12 float kd (currently not used)	Set PID parameters of one motor.	PC->MC

GET_ALL_MOTOR_PID_PARAMETERS

Name	Value	Command data	Description	Direction
GET_ALL_MOTOR_PID_PARAMETERS	16	none	Requesting the PID controller parameters of all motors	PC->MC

ALL_MOTOR_PID_PARAMETERS

Name	Value	Command data	Description	Direction
ALL_MOTOR_PID_PARAMETERS	17	Byte Type Description 0-3 float kp of motor 0 4-7 float ki of motor 0 8-11 float kd of motor 0 ... 35-39 float kp of motor 3 40-43 float ki of motor 3 44-47 float kd of motor 3	Response to GET_ALL_MOTOR_PID_PARAMETERS.	MC->PC

SET_ALL_DIGITAL_OUTPUTS

Name	Value	Command data	Description	Direction
SET_ALL_DIGITAL_OUTPUTS	18	Byte Type Description 0 uint8 each bit reflects the setting of one digital outputs port at Robotino's IO connector	Set digital output ports at Robotino's IO connector.	PC->MC

SET_ALL_RELAYS

Name	Value	Command data	Description	Direction
SET_ALL_RELAYS	19	Byte Type Description 0 uint8 bit 0 is the set-state of relay 0 at Robotino's IO connector bit 1 is the set-state of relay 1 at Robotino's IO connector	Set the relays at Robotino's IO connector.	PC->MC

SET_ODOMETRY

Name	Value	Command data	Description	Direction
SET_ODOMETRY	20	Byte Type Description 0-3 float x-position in meters 4-7 float y-position in meters 8-11 float rotation in radians	Set the odometry to the given pose	PC->MC

SET_ODOMETRY_ROTATION

Name	Value	Command data	Description	Direction
SET_ODOMETRY_ROTATION	21	Byte Type Description 0-3 float rotation in radians	Set the odometry to the given rotation. Used when a gyroscope is connected to the PC to forward the gyroscope readings to the MC where the odometry is processed.	PC->MC

GET_ODOMETRY

Name	Value	Command data	Description	Direction
GET_ODOMETRY	22	none	Request odometry readings from the MC	PC->MC

ODOMETRY

Name	Value	Command data	Description	Direction
ODOMETRY	23	Byte Type Description 0-3 float x-position in meters 4-7 float y-position in meters 8-11 float rotation in radians	Response to GET_ODOMETRY	MC->PC

GET_ALL_MOTOR_CURRENT_READINGS

Name	Value	Command data	Description	Direction
GET_ALL_MOTOR_CURRENT_READINGS	26	none	Request current readings from all motors	PC->MC

ALL_MOTOR_CURRENT_READINGS

Name	Value	Command data	Description	Direction
ALL_MOTOR_CURRENT_READINGS	27	Byte Type Description 0-3 float32 Current in Ampere drawn from motor 0 ... 12-15 float32 Current in Ampere drawn from motor 3	Response to GET_ALL_MOTOR_CURRENT_READINGS.	MC->PC

GET_ALL_ANALOG_INPUTS

Name	Value	Command data	Description	Direction
GET_ALL_ANALOG_INPUTS	32	none	Request all analog input readings.	PC->MC

ALL_ANALOG_INPUTS

Name	Value	Command data	Description	Direction
ALL_ANALOG_INPUTS	33	Byte Type Description 0-3 float32 ADC readings in Volts from analog input port 1 ... 32-35 float32 ADC readings in Volts from analog input port 8	Response to GET_ALL_ANALOG_INPUTS. Readings of all analog input ports.	MC->PC

GET_ALL_DIGITAL_INPUTS

Name	Value	Command data	Description	Direction
GET_ALL_DIGITAL_INPUTS	34	none	Request all digital input readings.	PC->MC

ALL_DIGITAL_INPUTS

Name	Value	Command data	Description	Direction
ALL_DIGITAL_INPUTS	35	uint8	Response to GET_ALL_DIGITAL_INPUTS. Readings of all digital input ports.	MC->PC

GET_BUMPER

Name	Value	Command data	Description	Direction
GET_BUMPER	36	none	Request all digital input readings.	PC->MC

BUMPER

Name	Value	Command data	Description	Direction
BUMPER	37	uint8	Response to GET_BUMPER. The bumpers state.	MC->PC

GET_POWER_BUTTON

Name	Value	Command data	Description	Direction
GET_POWER_BUTTON	38	none	Request all digital input readings.	PC->MC

POWER_BUTTON

Name	Value	Command data	Description	Direction
POWER_BUTTON	39	uint8	Response to GET_POWER_BUTTON. The power button state.	MC->PC

SET_FPGA_POWER

Name	Value	Command data	Description	Direction
SET_FPGA_POWER	40	uint8	Set the FPGA to hold the power supply	PC->MC

GET_FPGA_POWER

Name	Value	Command data	Description	Direction
GET_FPGA_POWER	41	none	Get the FPGA power supply hold status	PC->MC

FPGA_POWER

Name	Value	Command data	Description	Direction
FPGA_POWER	42	uint8	Response to SET_FPGA_POWER and GET_FPGA_POWER. The FPGA power supply hold status.	MC->PC

GET_PWR_OK_STATE

Name	Value	Command data	Description	Direction
GET_PWR_OK_STATE	43	uint8	Request status of the PWR_OK line.	PC->MC

PWR_OK_STATE

Name	Value	Command data	Description	Direction
PWR_OK_STATE	44	uint8	Response to GET_PWR_OK_STATE. Power OK status signal generated by the ATX power supply to notify the module that the DC operating voltages are within the ranges required for proper operation.	MC->PC

SET_PWR_OK_STATE

Name	Value	Command data	Description	Direction
SET_PWR_OK_STATE	45	uint8	Set the PWR_OK line.	PC->MC

SET_PWM

Name	Value	Command data	Description	Direction
SET_PWM	46	Byte Type Description 0 uint8 PWM output of the LPC2378. Number in range [1-6]. 1 uint8 PWM ratio. 0 is signal constant low. 255 is signal constant high.	Set the PWM ratio of a single PWM output.	PC->MC

SET_MOTOR_ON

Name	Value	Command data	Description	Direction
SET_MOTOR_ON	47	Byte Type Description 0 uint8 Number of motor in range [0-3]. 1 uint8 0 switches off the high side of the motor's H-bridge. 1 switches the high side of the motor's H-bridge on.	Enable/Disable a single motor.	PC->MC

SET_PWRBTN

Name	Value	Command data	Description	Direction
SET_PWRBTN	48	uint8	Set PWRBTN# line. Power button low active signal used to wake up the system from S5 state (soft off). This signal is triggered on the falling edge.	PC->MC

SET_SYS_RESET

Name	Value	Command data	Description	Direction
SET_SYS_RESET	49	uint8	Reset input signal. This signal may be driven to low by external circuitry such as a reset button to hold the system module in hardware reset.	PC->MC

GET_COM_EXPRESS_STATES

Name	Value	Command data	Description	Direction
GET_COM_EXPRESS_STATES	50	none	Request status of the COM Express status lines.	PC->MC

COM_EXPRESS_STATES

Name	Value	Command data	Description	Direction
COM_EXPRESS_STATES	51	Byte Type Description 0 uint8 SUS_S3#. S3 Sleep control signal indicating that the system resides in S3 state (Suspend to RAM). 1 uint8 SUS_S4#. S4 Sleep control signal indicating that the system resides in S4 state (Suspend to Disk). 2 uint8 SUS_S5#. S5 Sleep Control signal indicating that the system resides in S5 State (Soft Off). 3 uint8 THRM#. Thermal Alarm active low signal generated by the external hardware to indicate an over temperature situation. This signal can be used to initiate thermal throttling. 4 uint8 THRMTRIP#	Response to GET_COM_EXPRESS_STATES.	MC->PC

GET_ALL_MOTOR_READINGS

Name	Value	Command data	Description	Direction
GET_ALL_MOTOR_READINGS	52	none	Request speeds, positions, currents from all motors.	PC->MC

ALL_MOTOR_READINGS

Name	Value	Command data	Description	Direction
ALL_MOTOR_READINGS	53	Byte Type Description 0-1 int16 speed of motor 0 in rpm. ... 6-7 int16 speed of motor 4 in rpm. 8-11 int32 position of motor 0. ... 20-23 int32 position of motor 4. 24-27 float32 Current in Ampere drawn from motor 1. ... 36-39 float32 Current in Ampere drawn from motor 4.	Response to GET_ALL_MOTOR_READINGS.	MC->PC

GET_IP_ADDRESS

Name	Value	Command data	Description	Direction
GET_IP_ADDRESS	54	none	Request IP4 address.	PC->MC

IP_ADDRESS

Name	Value	Command data	Description	Direction
IP_ADDRESS	55	Byte Type Description 0-3 uint32 IP address 4-7 uint32 Netmask	Response to GET_IP_ADDRESS.	MC->PC

SET_IP_ADDRESS

Name	Value	Command data	Description	Direction
SET_IP_ADDRESS	56	Byte Type Description 0-3 uint32 IP address 4-7 uint32 Netmask	Set IP4 address.	PC->MC

SET_EMERGENCY_BUMPER

Name	Value	Command data	Description	Direction
SET_EMERGENCY_BUMPER	57	uint8	1 enables the emergency bumper feature. 0 disables it. If enabled all motors are stopped for 2s if the Robotino's bumper is hit.	PC->MC

SET_MOTOR_MODE

Name	Value	Command data	Description	Direction
SET_MOTOR_MODE	58	Byte Type Description 0 uint8 motor 1 uint8 mode 0: velocity control mode 1: position control mode 2: gripper mode (only accepted for motor 3)	Set the control mode of one motor.	PC->MC

RESET_LPC

Name	Value	Command data	Description	Direction
RESET_LPC	59	Byte Type Description 0 uint8 0: Simple reset 1: Enter USB bootloader	Reset the LPC2378 microcontroller.	PC->MC

POWER_OFF

Name	Value	Command data	Description	Direction
POWER_OFF	60	none	Power off the system.	PC->MC

SET_POWER_SOURCE

Name	Value	Command data	Description	Direction
SET_POWER_SOURCE	61	Byte Type Description 0 uint8 0: External power 1: Battery pack 1 2: Battery pack 2 3: Battery pack 3	Select the systems power source.	PC->MC

GET_POWER_SOURCES

Name	Value	Command data	Description	Direction
GET_POWER_SOURCES	62	none	Request the list of available power sources.	PC->MC

POWER_SOURCES

Name	Value	Command data	Description	Direction
POWER_SOURCES	63	Byte Type Description 0 uint8 Boolean indicating if external power supply is availabe 1 uint8 Boolean indicating if battery pack 1 is availabe 2 uint8 Boolean indicating if battery pack 2 is availabe 3 uint8 Boolean indicating if battery pack 3 is availabe	Response to GET_POWER_SOURCES.	MC->PC

GET_POWER_SOURCE_READINGS

Name	Value	Command data	Description	Direction
GET_POWER_SOURCE_READING	64	Byte Type Description 0 uint8 Power source number. See SET_POWER_SOURCE.	Request readings of the power source.	PC->MC

POWER_SOURCE_READINGS

Name	Value	Command data	Description	Direction
POWER_SOURCE_READINGS	65	Byte Type Description 0 uint8 Power source number. 1-4 float32 Power source voltage 5-8 float32 Power source current 9-12 float32 Power source remaining capacity 13-16 float32 Power source temperature 17 uint8 Battery type 0: Lead acid battery 1: NiMH battery 18 uint8 State of charge 19 uint8 Error 20-23 float32 Charging voltage 24-27 float32 Charging current	Response to POWER_SOURCE_READINGS.	MC->PC

SET_MOTOR_ACCEL_LIMITS

Name	Value	Command data	Description	Direction
SET_MOTOR_ACCEL_LIMITS	66	Byte Type Description 0 uint8 motor number 1-4 float minimum acceleration in rpm/s 5-8 float maximum acceleration in rpm/s	Set the motor's minimum and maximum acceleration	PC->MC

MOTOR_ACCEL_LIMITS

Name	Value	Command data	Description	Direction
MOTOR_ACCEL_LIMITS	67	Byte Type Description 0 uint8 motor number 1-4 float minimum acceleration in rpm/s 5-8 float maximum acceleration in rpm/s	Response to GET_MOTOR_ACCEL_LIMITS	MC->PC

GET_MOTOR_ACCEL_LIMITS

Name	Value	Command data	Description	Direction
GET_MOTOR_ACCEL_LIMITS	68	Byte Type Description 0 uint8 Motor number.	Request motor's acceleration limits.	PC->MC

INFO

Name	Value	Command data	Description	Direction
INFO	250	String	Transmitted to inform about some event.	MC->PC

WARNING

Name	Value	Command data	Description	Direction
WARNING	251	String	Transmitted in case of a warning.	MC->PC

ERROR

Name	Value	Command data	Description	Direction
ERROR	252	String	Transmitted in case of a communication error.	MC->PC

Data types

Name	Number of bytes	Description
String	Depends of the TAGs data length	Seqeunce of characters. The string is not terminated by 0.
uint8	1	Unsigned character
int8	1	Signed character
uint16	2	Unsigned short. Serialization is little endian.
int16	2	Signed short. Serialization is little endian.
uint32	4	Unsigned int. Serialization is little endian.
int32	4	Signed int. Serialization is little endian.
float32	4	Floating point number single precision. Serialization is little endian. //encoding char* data; float f = 1.23f; char* p = (char*)&f; encodingData[0] = *(p++); encodingData[1] = *(p++); encodingData[2] = *(p++); encodingData[3] = *(p++); //decoding float f2; p = (char*)&f2; *(p++) = encodingData[0]; *(p++) = encodingData[1]; *(p++) = encodingData[2]; *(p++) = encodingData[3];

Communication example

Communication between PC and MC is driven from the PC. Initially the PC will ask for the hardware and software version of the MC.

Byte number	Value	Description
0	0xAA	HEAD
1	0x04	Package length low byte
2	0x00	Package length high byte
3	0x01	GET_HW_VERSION
4	0x00	Data length of GET_HW_VERSION
5	0x03	GET_SW_VERSION
6	0x00	Data length of GET_SW_VERSION
7	?	Checksum low byte
8	?	Checksum high byte

Answer from MC

Byte number	Value	Description
0	0xAA	HEAD
1	0x0E	Package length low byte
2	0x00	Package length high byte
3	0x02	HW_VERSION
4	0x05	Data length of HW_VERSION
5	0x33	"3"
6	0x2E	"."
7	0x30	"0"
8	0x2E	"."
9	0x30	"0"
10	0x04	SW_VERSION
11	0x05	Data length of SW_VERSION
12	0x33	"3"
13	0x2E	"."
14	0x30	"0"
15	0x2E	"."
16	0x30	"0"
17	?	Checksum low byte
18	?	Checksum high byte