Protocol Buffer Messages

Protocol Buffer Messages

Starting with the Brinsop release, communication between modules happens by means of Protocol Buffer messages.  Protocol Buffers is a mechanism developed by Google. The main advantages of Protocol Buffers over the previously used XML format are:

  • Smaller message size, reducing network traffic
  • Faster parsing, reducing CPU load

The biggest difference between Protocol Buffers and XML is that Protocol Buffers is a binary format while XML is a text-based format. The upside is that Protocol Buffer messages can be sent and parsed faster, the downside is that they are no longer human-readable.

Logfiles

Brinsop modules still contain the “x” logging option for logging message content, but instead of XML these log lines now contain the “Short Debug String” representation of ProtocolBuffer messages.

Short Debug String

The Short Debug String format is a textual representation of Protocol Buffer messages. The most important characteristics of this notation are:

  • Values are indicated as: Name:Value (equivalent to <Name>Value</Name> in XML)
  • Nesting of messages is indicated using curly braces : { and }
  • String values are enclosed in quotes: “Value”
  • Enums are indicated in uppercase without quotes: EXAMPLE_VALUE

Here is an example message (indentation and colors added for clarity):

PB-Example
Common Fields

By convention, all Protocol Buffer messages sent by Voxtron modules contain at least the following elements:

  • message_type: this is an enum indicating the type of message (e.g. CONNECTIONREQUEST)
  • build: version of the protocol used

The build number indicates the version of the protocol used by the components. Two modules using a different build of a protocol will still be able to communicate with each other, but the extra fields in the newest version of the protocol will be ignored by the module using the older version.

Links

More information about Protocol Buffers can be found here.

Leave a Reply