SoftBank Robotics documentation What's new in NAOqi 2.5?

Network Binary Protocol

Glossary

  • Message: a qiMessaging frame.
  • Object: an endpoint exposing methods and events.
  • Service: an object registered to the Service Directory.
  • Service Directory: a directory of all registered services.
  • Client: anyone connecting to a Service.

Messages

Message header

Field Size (in bits) Description
magic 32 qiMessaging message magic number (0x42dead42)
id 32 id of the message
size 32 size of the payload
version 16 protocol version
type 16 type of the message
service 32 id of the service
object 32 id of the object
action 32 id of the function or event
payload ... ...

Magic

The magic (0x42dead42) is used to verifiy the received buffer is a qiMessaging message.

Id

Each message has an id. A reply or an error will have the same id as the corresponding call.

Size

This field contains the size of the payload.

Version

The version of the protocol.

Type

This is the type of the message, as defined in the table below.

Defined types
Type Id Description
Call 1 A function call
Reply 2 A reply to a call
Event 3 An event raised by a service
Error 4 An error
Invoke 5 Invoke an event slot

Service

The service id, as given by the Service Directory.

Defined services
Service Id Description
Server 0 Used for control frames
Service directory 1 Directory of all registered services

Object

This field refers to objects that are created internally to the module.

Defined services
Object Id Description
Default 0 Default object of the service

Action

Function that should be performed, or event that is raised.

Events

There are two different cases.

An event is emitted by the service itself, it is broadcast to all registered clients.

A slot can be triggered by the client, this is equivalent to a function call which return value we don’t wait for.

Serialization

Basic Types

Type Size Description
void 0 void
bool 1 boolean
int8_t 1 signed byte
int16_t 2 signed 16-bit integer
int32_t 4 signed 32-bit integer
int64_t 8 signed 64-bit integer
uint8_t 1 unsigned byte
uint16_t 2 unsigned 16-bit integer
uint32_t 4 unsigned 32-bit integer
uint64_t 8 unsigned 64-bit integer
float 4 32-bit floating point number
double 8 64-bit floating point number
const char * 4 + n
  • uint32_t - length
  • const char * - data (including 0)

STL Types

Type Size Description
std::string 4 + n
  • uint32_t - length
  • const char * - data
std::list<T> 4 + n * size(T)
  • uint32_t - length
  • [ T0 ] .. [ Tlength ]
std::vector<T> 4 + n * size(T)
  • uint32_t - length
  • [ T0 ] .. [ Tlength ]
std::map<K, V> 4 + n * (size(K) + size(V))
  • uint32_t - length
  • [ K0 ] [V0] .. [ Klength ] [ Vlength ]