Byte Translator (aka. Byte Whisperer)

This is an OpenChirp service that translates raw byte streams from devices
into meaningful values.

Do note that this service uses a simple and non-optimized approach for sending values
across a channel. To use a more optimized serializer, please use
Easybits.

Device’s Service Config

Note that all config parameters are optional and will be inferred or fall back
on defaults when omitted. To use ByteTranslator without configuration, please
see the Missing Config Incoming/Outgoing Behavior sections.

• Incoming Field Names - The names to assign to data fields received from the device
• Incoming Field Types - The types used to encode the data fields from the device
• Outgoing Field Names - The names of the transducers to send as fields to the device
• Outgoing Field Types - The types used to encode the data fields sent to the device
• Endianness - Indicates the order of bytes comprising an integer. (little or big)
• Aggregation Delay - The duration of time to wait, while aggregating
  outgoing data fields, before sending.
  This is a sequence of decimal numbers, each with optional fraction and a
  unit suffix, such as “300ms”, “1.5h” or “2h45m”.
  Valid time units are “ns”, “us” (or “µs”), “ms”, “s”, “m”, “h”.

Design Decisions

The overarching design principle is to be resilient to user configuration
errors and infer as much missing configuration as possible. For this reason,
the bytetranslator uses a default data type(configurable) and endianess, which
allow it to be used without any configuration.
The exception to this rule is finding invalid field data types. The parser will
halt and propagate an error if it encounters an invalid field data type. This is
because the user clearly expressed intent to use a data type other than the
default, but may have made a typo. The user should be made aware of this issue.

Missing Config Incoming Behavior

Any incoming fields that were not mentioned in the incoming field names are
assigned the name UnnamedValueIn#, where the # is the field position in the
array. Any missing incoming field types are assumed to be the default type.

Missing Config Outgoing Behavior

Any outgoing message published to a topic of the format UnnamedValueOut#,
where the # is a number, is sent as a field of the specified index #.
It will try to use a specified field data type, but will use the default if
one was not provided.
If an unnamed outgoing value refers to an index less than the number of field
names specified, then the message emitted will include blank elements for all
other specified fields. If the unnamed field refers to an index larger than
the number of specified fields, the message emitted will have all previous
indices’ value blanked out, with the last value being the unnamed value’s index.

Service Level Configuration

ByteTranslator will fetch the following two parameters from the Service’s
“Custom Properties” on startup:

• Default Type - This allows you to specify a service-wide default data type
  to use in unmarshalling payloads without a specified data type.
  If this parameter is omitted or “”, the default int16 is used.
• Outgoing Queue Length Topic - The topic on which the service will publish
  the running size of a device’s outgoing message queue. When using an
  Aggregation Delay larger than 0, this topic will increment as more outgoing
  values are aggregated. Setting this parameters to “”, disables
  the functionality. If this parameter is omitted, the default topic
  outgoingqueue is used.