This project has been superseded by L3aP (see github.com/leap-protocol)

Packets are human interprettable/enterable:

S10C0:00:cf000000\n

The protocol is configured using a json file.

The RoBus protocol is designed to:

• Provide intuitive protocol configuration
• Speed up development/debugging on the comms layer

The json file has the following root schema:

• version: the current semver of the RoBus protocol
• category: a map of start characters used in packets
• separator: protocol separator character
• compound: protocol compound character
• end: protocol end character
• _data: the root of the applications data map

Version is a semvar version with major, minor and patch numbers. This version relates to the RoBus protocol itself. Its purpose is to determine compatability.

Category characters determine how the receiving application should interpret a packet.

The RoBus protocol defines six categories by default. However, an application may define more categories when needed.

These configuration items define the utf-8 characters used in encoded packets. They may be changed to suit a users application if they meet the following rules:

• Must be copyable (eg, a delete character is not allowed)
• Must not be hexadecimal [0-9a-f]
• Must not be a category character

The _data field is a heirachical structure of user defined data.

"_data" : [
  { "sensor" : { "_addr": "8000", "_data": [
    { "imu": { "_addr": "00A0", "_data": [
      { "accel": { "_data": [
        { "x": { "_type": "float" } }, 
        { "y": { "_type": "float" } }, 
        { "z": { "_type": "float" } }
      ]}},
      { "gyros": { "_data": [
        { "x": { "_type": "float" } },
        { "y": { "_type": "float" } },
        { "z": { "_type": "float" } }
      ]}},
    ]}},
    { "temperature": { "_addr": "00C0", "_type": "float" } },
    { "barometer": { "_type": "float" } }
  ]}},
  { "timestamp_ms": { "_addr": "9000", "_type": "u64" }}
] 

Results in the following address mapping:

Addresses:

• Addresses are always four character hexidecimal strings /[0-9a-f]{4}/i
• Items inherit the address of the parent object and then add thier own.
• If an item does not define an address, it increments from the last assigned address.
• Addresses must always increment (eg/ an address of 8000 following and address of C000 is invalid).
• Addresses never exceed 16-bits.

Items

• An item must have either a "_data" array or "_type" string
• Items are placed in arrays to guarantee order (its a JSON thing)
• Item names must start with a character and can only contain characters, numbers, dashes and underscores /^[a-z][\w\-_]*$/i

Valid types:

• unsigned integers: "u8", "u16", "u32", "u64"
• signed integers: "i8", "i16", "i32", "i64"
• float 32-bit: "float"
• float 64-bit: "double"
• string: "string"
• boolean: "bool"
• enumeration: [ "item1", "item2", ...]

For enumerations, the item names are user defined - these get encoded as integers. An enumeration can have no more than 256 entries.

A typical packet looks like:

S13e7:00:cf000000\n

Where:

• S is the packet's category
• 13e7 is a data address
• : are item separation characters
• 00:cf000000 is encoded payload data
• \n is the packet's end character

The first character of a packet is always a category character. This specifies how the packet should be interpretted.

RoBus defines the following catergories by default:

It is not necessary that an application implements all categories (eg. ack and nak can easily be omitted in many cases)

Addresses are encoded as a four character big-endian hexidecimal string.

Separator characters go between addresses and data values. The default separator character is :

Encoding of data depends on the data type. All data gets encoded into some big endian hexidecimal string. Data typing is inferred from the address and configuration, it is not carried in the packet itself.

Packets terminate with an end character. The default end character is \n.

Instead of an end charactor, packets can be combined using a compound character. The purpose of a compound character is to ensure sets of data are processed together. The default compound character is |.