Encap and TLV

The Sparrow Encap protocol and TLV format are the basis for the application layer protocol used for Sparrow devices. The protocol is used to access all the functional objects (called instances) in Sparrow devices (including all Yanzi's IoT devices and the example devices in this repository). Read more about the object model on the (Sparrow Object Model) page.

Encapsulation Protocol

The Encap Protocol is intended to be used over UDP and encapsulates payload with or without encryption state.

The header format of the Encap protocol is:

 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |Version| Res.  | Payload Type  | Error & Status|FP Mode| IVM   |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |                         Fingerprint                           |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |                         InitVector                            |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |                         SequenceNumber                        |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |                         Payload                               |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

• Version: This is a version field indicating encapsulation format version. All versions where bit 3 is ’0’ means that the length of the encapsulation header is the same. Current version is 1 (0001b).

• Reserved: This must be zeros in transmit and must be ignored when received. A receiver may not assume these bits are set to zero.

• Error & Status: The field contain error or status. Currently status can queue control message. Error is reported when the encapsulation protocol was not able parse correctly. The list below shows the defined errors and status. Note that a request can never include error. Error can only be returned as a reply to a request.

  • 0x00 - No Error
  • 0x01 - Version Error
  • 0x02 - Payload Error
  • 0x03 - Fingerprint length error
  • 0x04 - Fingerprint not recognised

• Payload Type: This is a description of the encapsulated data format. - Relevant types are:

  • 0x01 - TLV format
  • 0x08 - Serial Link Data
  • 0x09 - Debug Information
  • 0x0A - Serial data with 32-bit sequence number. The sequence number is located directly before payload after encryption sequence number, if present.

• Finger Print Mode: ...

• Init Vector Mode: ...

• Finger Print: ...

• Payload Unencrypted payload must be n * 4 bytes. Encrypted payload must be n * 16 bytes. Padding must be made with zeros.

TLV Format

The standard TLV payload format is shown below:

 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |Version|         Length        |            Variable           |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 | Instance      |  OP Code      | ElementSize   |     Error     |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |                          [ D A T A ]                          |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

If the data is on a vector format the TLV format is slightly different and include some more parameters:

 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |Version|         Length        |            Variable           |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 | Instance      |  OP Code      | ElementSize   |     Error     |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |                         Element Offset                        |  
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |                         Element Count                         |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |                          [ D A T A ]                          |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Here the element offset is the starting element of the vector and the element count is the number of affected elements for this TLV and operation (Read/write).