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.

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)
• 3: position (3 element array of signed integers: [lat, long, alt]. 1e-7 of a degree; meters)
• 4: satellites (unsigned integer)
• 5: lock type (unsigned integer)
• 10: temperature (float as degrees C or signed integer as milli-degrees C)
• 11: pressure (unsigned integer or float, as milli-bar) (not sure about units? Pa instead?)
• 12: humidity (unsigned integer or float, as relative humidity percentage)
• 13: voltage (float as Volts or signed integer as milli-volts)
• 20: downlink frequency, for use in calling channel (unsigned integer as Hz)
• 30: total uplinked messages (unsigned integer)
• 40: landing prediction (2 element array of signed integers: [lat, long]. 1e-7 degree)

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

100+ would be reserved for temporary use, ie. if your type is not in the list above or you want to try something special/new/unique, use a Map id >= 100 to avoid conflict with any future standardisation.

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>”