M17_spec/pages/02.part-1/05.application-layer/docs.md

title	taxonomy	media_order
Application Layer	category docs	LFSR_8.svg,LFSR_16.svg,LFSR_24.svg

M17 Amateur Radio Voice Application

This section defines the application layer parameters for an audio stream containing low bit rate speech encoded using the open source Codec 2 codec. It is intended to be used over the air by amateur radio operators worldwide. Implementation details for M17 clients, repeaters, and gateways ensure that an M17 Amateur Radio Voice Application is legal under all licensing regimes.

Definitions

• M17 Client - an end station that transmits and receives M17 voice
• M17 Repeater - a station that receives and retransmits (repeats) M17 voice
• M17 Gateway - a station that receives and transmits M17 voice, converting to and from different formats (e.g. D-Star, DMR, EchoLink, etc.)

Credit to Jonathan Naylor (G4KLX) for documenting and implementing the details included here.

Data Link Layer Stream Mode is used for this application.

A Stream Mode Transmission begins with an LSF.

LSF/LICH

Table 16 Link Setup Frame Contents Field | Length | Description ----- | ------ | ----------- DST | 48 bits | Destination address SRC | 48 bits | Source address TYPE | 16 bits | Information about the incoming data stream META | 112 bits | Metadata field

Address fields

Destination (DST) and source (SRC) addresses may be encoded amateur radio callsigns, or special identifiers. See the Address Encoding Appendix for details on how up to 9 characters of text can be encoded into the 6-byte address value.

The source address is always the callsign of the station transmitting, be it a client, repeater, or gateway. This is not a problem for a client, but for a repeater/gateway this raises issues about identifying the original source of a transmission. Having a repeater/gateway always use its own callsign for the source field does ensure that there are no issues with licensing authorities. To retain identification of the original source for a repeater/gateway, an extended callsign data field will be encoded in the LSF META field.

The destination address used by a client may simply be a callsign for a point to point contact, or may be one of the following special identifiers in the table below.

Table 17 Client destination address Identifier | Address Value | Description ---------------- | -------------- | ----------- (Callsign) | varies | Destination callsign for a point to point contact ALL | 0xFFFFFFFFFFFF | Broadcast and any transmission is relayed to any connected reflector ECHO | 0x0000000ED87D | Enable the local echo function in a repeater/gateway INFO | 0x0000000ECDB9 | Trigger a voice and text announcement of the current linked status of the repeater/gateway UNLINK | 0x0000454F7745 | Unlink from a reflector and trigger an INFO response (Reflector Name) | varies | Link to a reflector and trigger an INFO response (if valid and not already linked)

The destination address of locally repeated radio transmission retains its original destination address, and the originator's callsign is encoded in the extended callsign data. For other transmissions, one of the following special identifiers may be used.

Table 18 Repeater/gateway destination address Identifier | Address Value | Description ---------------- | -------------- | ----------- (Callsign) | varies | Destination callsign for a locally repeated radio transmission ALL | 0xFFFFFFFFFFFF | All transmitted reflector traffic, originator's callsign and the currently linked reflector are encoded in the extended callsign data ECHO | 0x0000000ED87D | Reply of the built-in echo function, originator's callsign is encoded in the extended callsign data INFO | 0x0000000ECDB9 | Voice and text announcement of the current linked status of the repeater/gateway

TYPE field

The TYPE field contains information about the frames to follow LSF.

Table 18 M17 Voice LSF TYPE definition Bits | Meaning ---- | ------- 0 | Packet/Stream indicator | 1 = Stream Mode 1..2 | Data type indicator | $00_2$ = Reserved | $01_2$ = Data | $10_2$ = Voice only (3200 bps) | $11_2$ = Voice (1600 bps) + Data 3..4 | Encryption type | $00_2$ = None | $01_2$ = Scrambling | $10_2$ = AES 5..6 | Encryption subtype 7..10 | Channel Access Number (CAN) 11..15 | Reserved (don’t care)

This application requires Stream Mode.

The Voice only data type indicator (10_2) specifies voice data encoded at 3200 bps using Codec 2.

The Voice and Data data type indicator (11_2) specifies voice data encoded at 1600 bps using Codec 2, the remaining 1600 bps can be used for arbitrary data.

Encryption Types

Encryption is optional. The use of it may be restricted within some radio services and countries, and should only be used if legally permissible.

Null Encryption

Encryption type = 00_2

When no encryption is used, the 14-byte (112-bit) META field of the LSF and corresponding LICH of the stream can be used for transmitting relatively small amounts of extended data without affecting the bandwidth available for the audio. The full 14 bytes of META extended data is potentially decodable every six stream frames, at a 240 ms update rate. The extended data is transmitted in a simple round robin manner, with the only exception being GPS data which should be transmitted as soon as possible after the GPS data is received from its source.

The "Encryption SubType" bits in the Stream Type field indicate what extended data is stored in the META field.

Table 19 Null encryption subtype bits Encryption subtype bits | LSF META data contents ----------------------- | ---------------------- $00_2$ | Text Data $01_2$ | GNSS Position Data $10_2$ | Extended Callsign Data $11_2$ | Reserved

Text Data

The first byte of the Text Data is a Control Byte. To maintain backward compatibility, a Control Byte of 0x00 indicates that no Text Data is included.

Up to four Text Data blocks compose a complete message with a maximum length of 52 bytes. Each block may contain up to 13 bytes of UTF-8 encoded text, and is padded with space characters to fill any unused space at the end of the last used Text Data block.

The Control Byte is split into two 4-bit fields. The most significant four bits are a bit map of the message length indicating how many Text Data blocks are required for a complete message. There is one bit per used Text Data block, with 0001_2 used for one block, 0011_2 for the two, 0111_2 for three, and 1111_2 for four.

The least significant four bits indicate which of the Text Data blocks this text corresponds to. It is 0001_2 for the first, 0010_2 for the second, 0100_2 for the third, and 1000_2 for the fourth. Any received Control Byte is OR-ed together by the receiving station, and once the most significant and least significant four bits are the same, a complete message has been received.

It is up to the receiver to decide how to display this message. It may choose to wait for all of the Text Data to be received, or display the parts as they are received. It is not expected that the data in the text field changes during the course of a transmission.

GNSS Data

Unlike Text and Extended Callsign Data, GNSS data is expected to be dynamic during the course of a transmission and to be transmitted quickly after the GNSS data becomes available. To stop the LSF/LICH data stream from being overrun with GNSS data relative to other data types, a throttle on the amount of GNSS data transmitted is needed. It is recommended that GNSS data be sent at an update rate no faster than once every five seconds.

The GNSS data fits within one 14-byte META field, which equates to six audio frames, and takes 240ms to transmit. This is a simple format of the GNSS data which does not require too much work to convert into, and provides enough flexibility for most cases. This has been tested on-air and successfully gated to APRS-IS, showing a location very close to the position reported by the GPS receiver.

GNSS Position Data stores the 112 bit META field as follows:

Table 20 GNSS Data encoding Size in bits | Format | Contents ------------ | ------ | -------- 8 | unsigned integer | Data Source | | Used to modify the message added to the APRS message sent to APRS-IS | | 0x00 : M17 Client | | 0x01 : OpenRTX | | 0x02..0xFE : reserved | | 0xFF : other data source 8 | unsigned integer | Station Type | | Translated into suitable APRS symbols when gated to APRS-IS | | 0x00 : Fixed Station | | 0x01 : Mobile Station | | 0x02 : Handheld 8 | unsigned integer | Whole number absolute value of degrees latitude 16 | unsigned integer | Decimal degrees of latitude multiplied by 65535, MSB first 8 | unsigned integer | Whole number absolute value of degrees longitude 16 | unsigned integer | Decimal degrees of longitude multiplied by 65535, MSB first 8 | unsigned integer | Latitude N/S, Longitude E/W, Altitude, Speed and Bearing bit fields | | $xxxxxxx0_2$ North Latitude | | $xxxxxxx1_2$ South Latitude | | $xxxxxx0x_2$ East Longitude | | $xxxxxx1x_2$ West Longitude | | $xxxxx0xx_2$ Altitude data invalid | | $xxxxx1xx_2$ Altitude data valid | | $xxxx0xxx_2$ Speed and Bearing data invalid | | $xxxx1xxx_2$ Speed and Bearing data valid 16 | unsigned integer | Altitude above sea level in feet + 1500 (if valid), MSB first 16 | unsigned integer | Whole number of bearing in degrees between 0 and 360 (if valid), MSB first 8 | unsigned integer | Whole number of speed in miles per hour (if valid)

Extended Callsign Data

This is only transmitted from repeaters/gateways and not from clients, who only receive and display this data. These fields should not appear over M17 Internet links as they should only be used over the air from a repeater/gateway.

The META field is split into two callsign fields. The first is always present, and the second is optional. The callsign data is encoded using the standard M17 callsign Address Encoding which takes six bytes to encode a nine character callsign. Any unused space in the META field contains 0x00 bytes. The first callsign field starts at offset zero in the META field, and the second callsign if present starts immediately after the first. There are two unused bytes at the end of the META field.

The use of these two callsign fields is as follows:

Table 21 Extended Callsign Data encoding Source | Callsign Field 1 | Callsign Field 2 ------------------- | ---------------- | ---------------- Locally Repeated RF | Originator | Unused ECHO Reply | Originator | Unused Reflector Traffic | Originator | Reflector Name

The extended callsign data is not used under any other circumstances than the above currently.

It is not expected that the data in the extra callsign fields change during the course of a transmission.

Scrambling

Encryption type = 01_2

Scrambling is an encryption by bit inversion using a bitwise exclusive-or (XOR) operation between the bit sequence of data and a pseudorandom bit sequence.

Pseudorandom bit sequence is generated using a Fibonacci-topology Linear-Feedback Shift Register (LFSR). Three different LFSR sizes are available: 8, 16 and 24-bit. Each shift register has an associated polynomial. The polynomials are listed in Table 7. The LFSR is initialized with a seed value of the same length as the shift register. The seed value acts as an encryption key for the scrambler algorithm. Figures 16 to 18 show block diagrams of the algorithm.

Table 22 Scrambling Encryption subtype | LFSR polynomial | Seed length | Sequence period ------------------ | --------------- | ----------- | --------------- $00_2$ | $x^8 + x^6 + x^5 + x^4 + 1$ | 8 bits | 255 $01_2$ | $x^{16} + x^{15} + x^{13} + x^4 + 1$ | 16 bits | 65,535 $10_2$ | $x^{24} + x^{23} + x^{22} + x^{17} + 1$ | 24 bits | 16,777,215

---

Figure 16 8-bit LFSR taps  --- Figure 17 16-bit LFSR taps  --- Figure 18 24-bit LFSR taps 

Advanced Encryption Standard (AES)

Encryption type = 10_2

This method uses AES block cipher in counter (CTR) mode, with a 96-bit nonce that should never be used for more than one separate stream and a 32-bit CTR.

The 96-bit AES nonce value is extracted from the 96 most significant bits of the META field, and the remaining 16 bits of the META field form the highest 16 bits of the 32-bit counter. The FN (Frame Number) field value is then used to fill out the lower 16 bits of the counter, and always starts from 0 (zero) in a new voice stream.

The 16-bit frame number and 40 ms frames can provide for over 20 minutes of streaming without rolling over the counter.

The effective capacity of the counter is 15 bits, as the MSB is used for transmission end signalling. At 40ms per frame, or 25 frames per second, and 2^{15} frames, we get 2^{15} frames / 25 frames per second = 1310 seconds, or almost 22 minutes.

The random part of the nonce value should be generated with a hardware random number generator or any other method of generating non-repeating values.

To combat replay attacks, a 32-bit timestamp shall be embedded into the cryptographic nonce field. The field structure of the 96 bit nonce is shown in Table 9. Timestamp is 32 LSB portion of the number of seconds that elapsed since the beginning of 1970-01-01, 00:00:00 UTC, minus leap seconds (a.k.a. “unix time”).

96 bit nonce field structure

Table 23 Nonce field | Timestamp | Random Data | CTR_HIGH | | --------- | ----------- | -------- | | 32 | 64 | 16 |

CTR_HIGH field initializes the highest 16 bits of the CTR, with the rest of the counter being equal to the FN counter. Encryption subtypes are not applicable for this encryption scheme. All parties are assumed to know the key length used for each transmission.

!! In CTR mode, AES encryption is malleable. That is, an attacker can change the contents of the encrypted message without decrypting it. This means that recipients of AES-encrypted data must not trust that the data is authentic. Users who require that received messages are proven to be exactly as-sent by the sender should add application-layer authentication, such as HMAC. In the future, use of a different mode, such as Galois/Counter Mode, could alleviate this issue.

Channel Access Number (CAN)

The Channel Access Number (CAN) is a four bit code that may be used to filter received audio, text, and GNSS data. A receiver may optionally allow reception from sources only if their transmitted CAN value matches the receiver's own specified CAN value.

Stream Frames

Stream Frames will contain the appropriate LICH data (described above). The Stream Contents will include the incrementing 16-bit Frame Number, and 128 bits of Codec 2 data (unencrypted or encrypted).

References / Acknowledgements

• Jonathan Naylor (G4KLX) Source/Destination and META fields in the M17 Voice Application
• Jonathan Naylor (G4KLX) GPS Encoding in META field
• Jonathan Naylor (G4KLX) Multi-Mode Digital Voice Modem (MMVDM)

Packet Application

!!! Incomplete !!! This is work in progress.

A single packet of up to 798 bytes of data may be sent in one transmission.

Packets are sent using Packet Mode.

A Stream Mode Transmission begins with an LSF.

Packet superframes are composed of a 1..n byte data type specifier, 0..797 bytes of payload data. The data type specifier is encoded in the same way as UTF-8. It provides efficient coding of common data types. And it can be extended to include a very large number of distinct packet data type codes.

The data type specifier can also be used as a protocol specifier. For example, the following protocol identifiers are reserved in the M17 packet spec:

Reserved Protocols

Table 24 Packet protocol identifiers Identifier | Protocol ---------- | -------- 0x00 | RAW 0x01 | AX.25 0x02 | APRS 0x03 | 6LoWPAN 0x04 | IPv4 0x05 | SMS 0x06 | Winlink

The data type specifier is used to compute the CRC, along with the payload.