Number formats used in API

Many numbers do not fit into a single byte [0..255] range and for those there are conventions throughout our API on how to encode them.

An 8-bit unsigned or signed value representing a decimal range of [0..255] or [-128..127] respectively. Bits are ordered the “usual” way with the MSB on the left and LSB on the right.

A couple of examples (decimal = bits):

• 1 = 00000001 both signed and unsigned
• 253 = 11111101 (unsigned only)
• -3 = 11111101 (signed only)

This is a 16-bit value in which 8 MSB represent the unsigned integer part of the number and the 8 LSB represent the fractional part. The fractional value is the LSB x 256, i.e. the smallest “increment” for this format is 1/256 or 0.00390625.

Numbers in this format represent a decimal range of [0.0..256).

A few examples (decimal = MSB, LSB):

• 0.0 = 0x00, 0x00
• 1.0 = 0x01, 0x00
• 1.5 = 0x01, 0x80
• 127.3 = 0x7F, 0x4D - notice how the actual precise decimal number 127 + 77/256 is not exactly 127.3 but is an approximation of the precise decimal value of 127.30078125
• -1 - unrepresentable
• 256 = 0xFF, 0xFF - once again, the actual decimal number is “very close” and is in fact 255.99609375