Appendix : Protocol Specification

Overview

The kobuki driver communicates with the robot by using predefined protocol. In general, the driver sends the commands to the robot and the robot sends some feedback data or sensor readings. These commands and feedback data are converted into bytestreams for communication via serial interface. The protocol specifies that rules and forms of bytestreams.

Structure of Bytestream

A bytestream can be devided into 4 fields; Headers, Length, Payload and Checksum.

NameHeader 0Header 1LengthPayloadChecksum
Size1 Byte1 Byte1 ByteN Bytes1 Byte
Description0xAA
(Fixed)		0x55
(Fixed)		Size of payload in bytesDescribed belowXOR'ed value of every bytes of bytesream except headers


Header

Two bytes of headers, header 0 and hader 1, are fixed value for both bytestreams, commands and feedback data. This headers are used to detect the starting point of bytestream.


Length

Length indicated the length of following bytes that single bytestream hold. Default size of this field is 1 byte. Length can be used to distinguish each bytestreams. Minimum value of this field is 3.


Payload

Payload contains actual data of bytestream.


Structure Of Payload

Payload is a consist of several sub-payloads.
Payload
Sub-Payload 0Sub-Payload 1Sub-Payload 2...Sub-Payload N-1


Structure Of Sub-Payloads

Sub-payload can be devided into three parts, Header, Length and Data.
NameHeaderLengthData
Size1 Byte1 ByteN Byte(s)
DescriptionPredefined IdentifierSize of data in byte(s)Described below


Checksum

Checksum is XOR'ed value of entire bytestream except headers. Checksum process ensure the integrity of bytestreams.

Here is simple code snippet for it. 

unsigned int packet_size(buffer.size());
unsigned char cs(0);
for (unsigned int i = 2; i < packet_size; i++)
{
  cs ^= buffer[i];
}
return cs ? false : true;


Entire Bytestream

HeadersLengthPayloadChecksum
Header 0Header 1Sub-Payload 0Sub-Payload 1Sub-Payload 2...Sub-Payload N-1

Above table shows the structure of entire bytestream.

Minimum length of payload is 3; Payload with a sub-payload, that has only 1 byte data.

Theoretical minimum length of entire packet(bytestream) is 7.


Data Types

Data field in Sub-payload is a mixture of below three data types; byte, short and int.

NameDescriptionByte LengthBit LengthData RangeC/C++ Identifier
Unsigned Byte8-bit unsigned integer180~255unsigend charuint8_t
Unsigned Short16-bit unsigned integer2160~65,535unsigend shortuint16_t
Unsigned Int32-bit unsigned integer4320~4,294,967,295unsigend intuint32_t


Serialization-Deserialization

Serialization is the process of converting a data sturcture into a bytestream. Deserialization is reversal process. Each data types are serialized and deserialized by `LSB-First Order`. It means Least Significant Bytes will comes first on the bytestream. For example, The integer number 2,864,434,397(0xAABBCCDD) can be serialized into:

0xDD0xCC0xBB0xAA

So, 0xDD will arrive first in bytestream.

Here are template functions to handle it on kobuki_deriver, buildVariable() and buildBytes().


Command Packets

Command Identifier

IDNameDescription
1Base ControlControl wheel motors
2Reserved
3SoundPlay custom sounds
4Sound SequencePlay predefined sounds
5Reserved
6Reserved
7Reserved
8Set PowerControl external powers
9Request ExtraRequest extra informations
10Reserved
11Reserved
12General Purpose OutputControl general purpose outputs


Base Control

Control wheel motors to moving robot. Robot will follow the arc, which radius is <Radius> mm, with <Velocity> mm/s.

NameSizeValueValue in HexDescription
HeaderIdentifier110x01Fixed
LengthSize of data field140x04Fixed
DataSpeed2in mm/s
Radius2in mm


Sound

Play custom sounds with note and duration.

NameSizeValueValue in HexDescription
HeaderIdentifier130x03Fixed
LengthSize of data field130x03Fixed
DataNote2$\mbox{1/}(f \cdotp a)$, where $f$ is frequency of sound in Hz, and $a$ is 0.00000275
Duration1Duration of playing note in mili-seconds
Warning:
This command is implemented on the kobuki with firmware, but not implemented yet on driver software(kobuki_driver).


Sound Sequence

Play predefined sounds by its index.

NameSizeValueValue in HexDescription
HeaderIdentifier140x04Fixed
LengthSize of data field110x01Fixed
DataSequence number10 for ON sound
1 for OFF sound
2 for RECHARGE sound
3 for BUTTON sound
4 for ERROR sound
5 for CLEANINGSTART sound
6 for CLEANINGEND sound


Set Power

Control the external powers; 3.3V, 5V, 12V1A, 12V5A. It is identical role with external power part of General Purpose Output.

NameSizeValueValue in HexDescription
HeaderIdentifier180x08Fixed
LengthSize of data field120x02Fixed
DataPower control flags2Set the flags to turn on external powers
0x01 for external power 3.3V ch.
0x02 for external power 5V ch.
0x04 for external power 12V1A ch.
0x08 for external power 12V5A ch.
Warning:
This command is implemented on the kobuki with firmware, but not implemented yet on driver software(kobuki_driver).
See also:
General Purpose Output


Request Extra

Request extra data from robot. Especially version info of kobuki; Hardware Version, Firmware Version and Unique Deivce IDentifier(UDID)

UDID is unique to device. so can be used to identify on multiple robots.

NameSizeValueValue in HexDescription
HeaderIdentifier190x09Fixed
LengthSize of data field120x02Fixed
DataReqeust flags2Set the flags to request extra data
0x01 for Hardware Version
0x02 for Firmware Version
0x08 for Unique Device ID
See also:
Hardware Version Firmware Version, Unique Device IDentifier(UDID)


General Purpose Output

This command has multiple roles. It controls LEDs, digital outputs and external powers.

NameSizeValueValue in HexDescription
HeaderIdentifier1120x0CFixed
LengthSize of data field120x02Fixed
DataDigital output flags2Set the flags to set high on output pins of expansion port
0x0001 for digital output ch. 0
0x0002 for digital output ch. 1
0x0004 for digital output ch. 2
0x0008 for digital output ch. 3

Set the flags to turn on external powers
0x0010 for external power 3.3V ch.
0x0020 for external power 5V ch.
0x0040 for external power 12V1A ch.
0x0080 for external power 12V5A ch.

Set the flags to turn on LEDs
0x0100 for red colour of LED1
0x0200 for green colour of LED1
0x0400 for red colour of LED2
0x0800 for green colour of LED2
See also:
Set Power


Feedback Packets

Feedback Identifier

Kobuki sends below default feedbacks periodically in 50 Hz, when it powered on.

IDNameDescriptionAvailability
1Basic Sensor DataBasic core sensor dataBy default
2Reserved
3Docking IRSignals from docking stationBy default
4Inertial SensorGyro data both angle and angular velocityBy default
5CliffPSD data facing floorBy default
6CurrentCurrent of wheel motorsBy default
7Reserved
8Reserved
9Reserved
10Hardware VersionVersion number of kobuki hardwareOn request
11Firmware VersionVersion number of kobuki firmwareOn request
12Reserved
13Raw data of 3-axis gyroRaw ADC data of digital 3-axis gyroBy default
14Reserved
15Reserved
16General Purpose InputInputs from 25-pin expansion portBy default
17Reserved
18Reserved
19Unique Device IDentifier(UDID)Unique number to identify robotOn request
20Reserved


Basic Sensor Data

Basic core sensor data.

NameSizeValueValue in HexDescription
HeaderFeedback Identifier110x01Fixed
LengthSize of data field1150x0FFixed
DataTimestamp2Timestamp generated internally in milliseconds
It circulates from 0 to 65535
Bumper1Flag will be setted when bumper is pressed
0x01 for right bumper
0x02 for central bumper
0x04 for left bumper
Wheel drop1Flag will be setted when wheel is dropped
0x01 for right wheel
0x02 for left wheel
Cliff1Flag will be setted when cliff is detected
0x01 for right cliff sensor
0x02 for central cliff sensor
0x04 for left cliff sensor
Left encoder2Accumulated encoder data of left and right wheels in ticks
Increments of this value means forward direction
It circulates from 0 to 65535
Right encoder2
Left PWM1PWM value that applied to left and right wheel motor
This data should be converted signed type to represent correctly
Negative sign indicated backward direction
Right PWM1
Button1Flag will be setted when button is pressed
0x01 for Button 0
0x02 for Button 1
0x04 for Button 2
Charger10 for DISCHARGING state
2 for DOCKING_CHARGED state
6 for DOCKING_CHARGING state
18 for ADAPTER_CHARGED state
22 for ADAPTER_CHARGING state
Battery1Voltage of battery in 0.1 V
Typically 16.7 V when fully charged
Over current flags1Flag will be setted when over current is detected
0x01 for left wheel
0x02 for right wheel
Note:
This sub-payload will be sent by default.


Docking IR

Signals from the docking station.

NameSizeValueValue in HexDescription
HeaderIdentifier130x03Fixed
LengthSize of data field130x03Fixed
DataRight signal1Flag will be setted when signal is detected
0x01 for NEAR_LEFT state
0x02 for NEAR_CENTER state
0x04 for NEAR_RIGHT state
0x08 for FAR_CENTER state
ox10 for FAR_LEFT state
0x20 for FAR_RIGHT state
Central signal1
Left signal1

Kobuki's docking station has 3 IR emitters. The emitted IR lights cover three regions in front of the docking station: left, central and right, each divided in two sub-fields: near and far. Each beam encodes this information, so the robot knows at any moment in which region and sub-field he is. Also, as regions and fields are independently identified, they can be overlap on its borders.

dock_ir_fields.png
Docking IR Fields


Inertial Sensor Data

Inertial sensor data. Only 1 axis gyro data only available.

NameSizeValueValue in HexDescription
HeaderIdentifier140x04Fixed
LengthSize of data field170x07Fixed
DataAngle2Factory calibrated
Angle rate2Factory calibrated
Unused1
Unused1
Unused1
Note:
This sub-payload will be sent by default.


Cliff Sensor Data

This sub-payload provides ADC data of PSD, which is facing the floor.

This value is related with distance between sensor and floor surface. See the datasheet for more detailed information.

This data also available in the Cliff field of Basic Sensor Data , as a boolean type, processed on the kobuki.

NameSizeValueValue in HexDescription
HeaderIdentifier150x05Fixed
LengthSize of data field160x06Fixed
DataRight cliff sensor2ADC output of each PSD
Data range: 0 ~ 4095
Distance range: 2 ~ 15 cm
Distance is non-linear
Central cliff sensor2
Left cliff sensor2
Note:
This sub-payload will be sent by default.
See also:
Basic Sensor Data


Current

Current sensor readings of wheel motors.

NameSizeValueValue in HexDescription
HeaderIdentifier160x06Fixed
LengthSize of data field120x02Fixed
DataLeft motor2in 10mA
Right motor2in 10mA
Note:
This sub-payload will be sent by default.


Hardware Version

Hardware version info in triplet form; <major>.<minor>.<patch>

NameSizeValueValue in HexDescription
HeaderIdentifier1100x0AFixed
LengthSize of data field140x04Fixed
DataPatch1
Minor1
Major1
Unused100x00Fixed
Note:
This sub-payload will be sent on request.
See also:
Request Extra


Firmware Version

Firmware version info in triplet form; <major>.<minor>.<patch>

NameSizeValueValue in HexDescription
HeaderIdentifier1110x0BFixed
LengthSize of data field140x04Fixed
DataPatch1
Minor1
Major1
Unused100x00Fixed
Note:
This sub-payload will be sent on request.
See also:
Request Extra


Raw Data Of 3D Gyro

Raw ADC data of digital 3D gyro; L3G4200D

Due to difference of acquisition rate and update rate, 2-3 data will be arrived at once.

Digit to deg/s ratio is 0.00875, it comes from datasheet of 3d gyro.

NameSizeValueValue in HexDescription
HeaderIdentifier1130x0DFixed
LengthSize of data field12+6N
DataFrame id1Frame id of 'Raw gyro data 0'
Every sensor readings can identified by frame id
, It circulate from 0 to 255
Followed data length13N
Raw gyro data 0x-axis2ADC output of each-axis in 0.00875 deg/s
y-axis2
z-axis2
:
:
Raw gyro data N-1x-axis2
y-axis2
z-axis2
Note:
This sub-payload will be sent by default.


Warning:
Sensing axis of 3d gyro is not match with robot. It is rotated 90 degree counterclockwise about z-axis. So, below conversion will needed. 
const double digit_to_dps = 0.00875;
angular_velocity.x =  -digit_to_dps * (short)raw_gyro_data.y;
angular_velocity.y =   digit_to_dps * (short)raw_gyro_data.x;
angular_velocity.z =   digit_to_dps * (short)raw_gyro_data.z;


General Purpose Input

NameSizeValueValue in HexDescription
HeaderIdentifier1160x10Fixed
LengthSize of data field1160x10Fixed
DataDigital input2Flag will be setted, when high voltage is applied
0x01 for digital input ch. 0
0x02 for digital input ch. 1
0x04 for digital input ch. 2
0x08 for input output ch. 3
Analog input ch.0212-bit ADC output of each channel
Data range: 0 ~ 4095(2^12-1)
Conversion voltage range: 0 ~ 3.3 V
Analog input ch.12
Analog input ch.22
Analog input ch.32
Unused2
Unused2
Unused2
Note:
This sub-payload will be sent by default.


Unique Device IDentifier(UDID)

Contains Unique Device IDentifier of robot. This value is unique for all robot in the world. It can be represented by triplet form: <UDID0>-<UDID1>-<UDID2>

NameSizeValueValue in HexDescription
HeaderIdentifier1190x13Fixed
LengthSize of data field1120x0CFixed
DataUDID04
UDID14
UDID24
Note:
This sub-payload will be sent on request.
See also:
Request Extra



kobuki_driver
Author(s): Daniel Stonier , Younghun Ju , Jorge Santos Simon
autogenerated on Mon Oct 6 2014 01:31:10