This page details the msgpack based binary protocol. Habpack uses msgpack to encode the binary data, and defines how msgpack is used to encode telemetry, and defines IDs for telemetry fields

A single telemetry string is a msgpack map. Each telemetry field then consists of a key which defines what that field is, and a value field. For efficiency reasons, each key is usually a 7bit unsigned int, and the list of keys is defined in the section below. An example packet is as follows:

{ 0:”CALLSIGN”, 2:12:56:14, 3:[52.33, -0.3543, 12320], 20:8, … }

• { …. } means msgpack map array
• 0:123 means a map entry with key 0 and data 123
• […, …, …] means an array

It should be noted that the datatype (eg string, integer etc) is handled by msgpack. As a result, the decoder should see what datatype has been sent, and handle the data accordingly.

This lists the IDs that habpack uses. There are reserved IDs to send data which is not already in the list of fields

• 0: callsign (as a string, or an integer ID)
• 1: count
• 2: time (as a string, or integer seconds past midnight UTC)
• 3: position (use a 3 element array: [lat, long, alt]. 1e-7 of a degree; meters)
• 4: satellites
• 5: lock type
• 10: internal temperature
• 11: external temperature
• 40: battery voltage (mV)
• 50: total uplinked messages

As msgpack handles datatypes, arrays can be used to send multiple entries for one field. For example, if there are two external temperature sensors, this can be sent as 11:[-40.5,-39,1]

Encoders should pick the smallest type within the correct family. eg. '112' can be encoded as an unsigned int using the 'positive fixnum' type, for an encoded size of 1 byte. Unsigned integers are always assumed to be positive.

This means that using integers can scale the storage required to the value being transmitted, while floats maintain a constant size (5 bytes for 32b float). See the msgpack spec for more details: msgpack spec -> type system

A list of reserved Map IDs is suggested below to standardise parsing of commonly used telemetry fields without requirement of a payload-doc, eg. for embedded & offline receivers. This list is intended to be expanded over time as new requirements develop.

• 0: callsign (string or unsigned integer) (integer converted to string representation for habitat upload)
• 1: count (unsigned integer)
• 2: time (string or unsigned integer seconds past midnight UTC, or unsigned integer unix epoch seconds)
• 3: position (2 or 3 element array of signed integers: [lat, long, <alt>]. 1e-7 of a degree; meters)
• 4: number of satellites (unsigned integer)
• 5: lock type [0: none, 1: time, 2: 2D, 3: 3D, 4: 3D+SBAS] (unsigned integer)
• 6: voltage (float as Volts or signed integer as milli-volts)
• 10: Internal temperature (float as degrees C or signed integer as milli-degrees C)
• 11: External temperature (float as degrees C or signed integer as milli-degrees C)
• 12: pressure (float as bar, or unsigned integer as milli-bar)
• 13: relative humidity (unsigned integer or float, as relative humidity percentage)
• 14: absolute humidity (float as g/m^3, or unsigned integer as milligrams/m^3)
• 20: downlink frequency, for use in calling channel (unsigned integer as Hz)
• 30: total uplinked messages (unsigned integer)
• 40: predicted time (string or unsigned integer seconds past midnight UTC, or unsigned integer unix epoch seconds)
• 41: predicted position (2 or 3 element array of signed integers: [lat, long, <alt>]. 1e-7 degree; meters).

6,10,11,12,13,14,20 can be an array of legal values to represent more than one field.

For bodging habitat upload compatibility, values are re-encoded into a UKHAS-compatible RTTY string ($$…*<crc>), with fields ordered by map ID ascending, and array index ascending when multiple values exist.

eg. “$$<callsign>,<count>,<time>,<lat>,<lon>,<alt>,<satellites>,<temp 1>,<temp 2>,<battery voltage>*<crc>”