From 2e0fa23202911f08b6056cec6ee1499292ed6618 Mon Sep 17 00:00:00 2001 From: Steve Miller <43918257+kc1awv@users.noreply.github.com> Date: Tue, 21 Jun 2022 14:51:41 -0400 Subject: [PATCH 1/4] Update docs.md Spelling error --- pages/02.part-1/04.data-link-layer/docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/02.part-1/04.data-link-layer/docs.md b/pages/02.part-1/04.data-link-layer/docs.md index 8cab77f..4186780 100644 --- a/pages/02.part-1/04.data-link-layer/docs.md +++ b/pages/02.part-1/04.data-link-layer/docs.md @@ -25,7 +25,7 @@ There are four frame types each with their own specific Sync Burst: [Link Setup #### Forward Error Correction (FEC) The Data Link Layer Contents of a specific frame are modified using various Error Correction Code (ECC) methods. Applying these codes at the transmitter allows the receiver to correct some amount of induced errors in a Forward Error Correction (FEC) process. It is this ECC/FEC data that is inserted into the Payload portion of the Frame. The exact ECC/FEC techniques used vary by frame type. -Applying ECC/FEC may be a multi-step process. To distinquish data bits at the various stages of the process, Bit Types are defined as shown in the following table. It is important to note that not all ECC/FEC processes utilize both Type 2 and Type 3 bits. Prior to decoding Data Link Layer contents, a receiver would need to convert incoming bits from Type 4 back to Type 1 bits, which may also include conversion through Type 3 and/or Type 2 bits. The exact ECC/FEC methods and Bit Types utilized will be indicated for each frame type. +Applying ECC/FEC may be a multi-step process. To distinguish data bits at the various stages of the process, Bit Types are defined as shown in the following table. It is important to note that not all ECC/FEC processes utilize both Type 2 and Type 3 bits. Prior to decoding Data Link Layer contents, a receiver would need to convert incoming bits from Type 4 back to Type 1 bits, which may also include conversion through Type 3 and/or Type 2 bits. The exact ECC/FEC methods and Bit Types utilized will be indicated for each frame type.
Table 1 Bit Types
Type | Description From b97f8af07243d8197bd7619822e07336544a862e Mon Sep 17 00:00:00 2001 From: Jay Francis Date: Wed, 22 Jun 2022 10:32:38 -0400 Subject: [PATCH 2/4] Corrected table and figure numbers --- pages/02.part-1/04.data-link-layer/docs.md | 42 ++++++++++--------- pages/04.appendix/01.address-encoding/docs.md | 4 ++ .../02.randomizer-sequence/docs.md | 1 + .../03.convolutional-encoder/docs.md | 1 + pages/04.appendix/04.golay-encoder/docs.md | 3 +- pages/04.appendix/06.interleaving/docs.md | 2 +- pages/04.appendix/07.bert-details/docs.md | 10 ++--- pages/04.appendix/08.kiss-protocol/docs.md | 4 +- pages/04.appendix/09.file-formats/docs.md | 1 + 9 files changed, 41 insertions(+), 27 deletions(-) diff --git a/pages/02.part-1/04.data-link-layer/docs.md b/pages/02.part-1/04.data-link-layer/docs.md index 4186780..1d4380c 100644 --- a/pages/02.part-1/04.data-link-layer/docs.md +++ b/pages/02.part-1/04.data-link-layer/docs.md @@ -27,7 +27,7 @@ The Data Link Layer Contents of a specific frame are modified using various Erro Applying ECC/FEC may be a multi-step process. To distinguish data bits at the various stages of the process, Bit Types are defined as shown in the following table. It is important to note that not all ECC/FEC processes utilize both Type 2 and Type 3 bits. Prior to decoding Data Link Layer contents, a receiver would need to convert incoming bits from Type 4 back to Type 1 bits, which may also include conversion through Type 3 and/or Type 2 bits. The exact ECC/FEC methods and Bit Types utilized will be indicated for each frame type. -
Table 1 Bit Types
+
Table 2 Bit Types
Type | Description ---- | ----------- Type 1 | Data link layer content bits @@ -35,7 +35,7 @@ Type 2 | Bits after appropriate encoding Type 3 | Bits after puncturing Type 4 | Interleaved (re-ordered) bits -
Figure 1 Transmit Contents to Payload
+
Figure 6 Transmit Contents to Payload
[mermaid] graph LR contents[Data Link Layer Contents] -- Type 1 bits --> fec[ECC/FEC Encode] -- Type 4 bits--> payload[Payload] @@ -44,7 +44,7 @@ graph LR style payload fill:#ffffffff,stroke:#ffffffff,stroke-width:0px [/mermaid] -
Figure 2 Receive Payload to Contents
+
Figure 7 Receive Payload to Contents
[mermaid] graph LR payload[Payoad] -- Type 4 bits --> fec[ECC/FEC Decode] -- Type 1 bits--> contents[Data Link Layer Contents] @@ -83,7 +83,7 @@ BERT Sync Bursts, if present, may only follow the Preamble or other BERT frames. Multiple Stream or Packet Sync Bursts may be present during a Transmission, depending on the mode. -
Table 2 Frame Specific Sync Bursts
+
Table 3 Frame Specific Sync Bursts
Frame Type | Preamble | Sync Burst Bytes | Sync Burst Symbols ---------- | -------- | ---------------- | ------------------ LSF | +3, -3 | 0x55 0xF7 | +3, +3, +3, +3, -3, -3, +3, -3 @@ -95,7 +95,7 @@ Packet | None | 0x75 0xFF | +3, -3, +3, +3, -3, -3, -3, -3 The LSF is the intial frame for both Stream and Packet Modes and contains information needed to establish a link. -
Table 3 Link Setup Frame Contents
+
Table 4 Link Setup Frame Contents
Field | Length | Description ----- | ------ | ----------- DST | 48 bits | Destination address - Encoded callsign or a special number (eg. a group) @@ -114,7 +114,7 @@ Destination and source addresses may be encoded amateur radio callsigns, or spec The TYPE field contains information about the frames to follow LSF. The Packet/Stream indicator bit determines which mode (Packet or Stream) will be used during the transmission. The remaining field meanings are defined by the specific mode and application. -
Table 4 LSF TYPE definition
+
Table 5 LSF TYPE definition
Bits | Meaning ---- | ------- 0 | Packet/Stream indicator, 0=Packet Mode, 1=Stream Mode @@ -138,7 +138,7 @@ The input to the CRC algorithm consists of DST, SRC (each 48 bits), 16 bits of T The test vectors in the following table are calculated by feeding the given message and then 16 zero bits to the CRC algorithm. -
Table 5 CRC Test Vectors
+
Table 6 CRC Test Vectors
Message | CRC Output ------- | ---------- (empty string) | 0xFFFF @@ -156,6 +156,7 @@ Type 3 bits are computed by [\(P_1\) puncturing](../../04.appendix/05.code-punct Within the Physical Layer, the 368 Type 4 bits are randomized and combined with the 16-bit LSF Sync Burst, which results in a complete frame of 384 bits (384 bits / 9600bps = 40 ms). +
Figure 8 LSF Construction
[mermaid] graph TD @@ -188,7 +189,7 @@ In Stream Mode, an *indefinite* amount of data is sent continuously without brea Following the LSF, one or more Stream Frames may be sent. - + @@ -241,7 +242,7 @@ The 48-bit LICH Contents is partitioned into 4 12-bit parts and encoded using [G ##### Stream Contents -
Table 6 Stream Contents
+
Table 9 Stream Contents
Field | Length | Description ----- | ------ | ----------- FN | 16 bits | Frame Number @@ -262,7 +263,7 @@ These bits are [\(P_2\) punctured](../../04.appendix/05.code-puncturing) to gene The 96 Type 2 bits of the ECC/FEC LICH Contents are concatenated with 272 Type 3 bits of the ECC/FEC Stream Contents resuting in 368 of combined Type 2/3 bits. -
Table N LICH and Stream Combined
+
Table 10 LICH and Stream Combined
Field | Length | Description ------ | ------ | ----------- LICH | 96 bits | ECC/FEC LICH Contents Type 2 bits @@ -273,6 +274,7 @@ Total: 368 Type 2/3 bits Within the Physical Layer, the 368 Type 4 bits are randomized and combined with the 16-bit Stream Sync Burst, which results in a complete frame of 384 bits (384 bits / 9600bps = 40 ms). +
Figure 10 Stream Frame Construction
[mermaid] graph TD @@ -317,14 +319,14 @@ end Stream Frames are grouped into Stream Superframes, which is the group of 6 frames that contain everything needed to rebuild the original LSF packet, so that the user who starts listening in the middle of a stream (late-joiner) is eventually able to reconstruct the LSF message and understand how to receive the in-progress stream. -
Figure 6 Stream Superframes
+
Figure 11 Stream Superframes
![M17_stream](M17_stream.png?classes=caption "Stream consisting of one superframe") ### Packet Mode In Packet Mode, a Single Packet with up to 798 bytes of Application Packet Data along with an appended two byte CRC may be sent over the physical layer during one Transmission. -
Table 9 Single Packet
+
Table 11 Single Packet
Bytes | Meaning ----- | ------- 1..798 | Application Packet Data @@ -338,7 +340,7 @@ Packet Mode shall always start with an LSF that has the LSF TYPE Packet/Stream i Packet Mode acheives a base throughput of 5 kbps, a net throughput of approximately 4.7 kbps for the largest data payload, and over 3 kbps for 100-byte payloads. Net throughput takes into account preamble and link setup overhead.
Figure 3 Stream ModeFigure 9 Stream Mode
PREAMBLE
- + @@ -360,7 +362,7 @@ Packet Frames contain Packet Contents after ECC/FEC is applied. #### Packet Contents -
Table 10 Packet Contents
+
Table 12 Packet Contents
Bits | Meaning ---- | ------- 0..199 | 200-bit chunk of Single Packet @@ -378,7 +380,7 @@ When there are no bytes remaining in the Single Packet after removing a 25-byte
-
Table 11 Metadata Field with EOF = 0
+
Table 13 Metadata Field with EOF = 0
Bits | Meaning ---- | ------- 0 | Set to 0, Not end of frame @@ -386,7 +388,7 @@ Bits | Meaning
-
Table 12 Metadata Field with EOF = 1
+
Table 14 Metadata Field with EOF = 1
Bits | Meaning ---- | ------- 0 | Set to 1, End of frame @@ -402,6 +404,7 @@ These bits are [\(P_3\) punctured](../../04.appendix/05.code-puncturing) to gene Within the Physical Layer, the 368 Type 4 bits are randomized and combined with the 16-bit Packet Sync Burst, which results in a complete frame of 384 bits (384 bits / 9600bps = 40 ms). +
Figure 13 Packet Frame Construction
[mermaid] graph TD @@ -447,7 +450,7 @@ interoperability testing across M17 hardware and software implementations, and t configuration and tuning of ad hoc communications equipment common in amateur radio.
Figure 3 Packet ModeFigure 12 Packet Mode
PREAMBLE
- + @@ -475,7 +478,7 @@ frames even with a PRBS generator with a relatively short period. See the Appendix for [BERT generation and reception details](../../04.appendix/07.bert-details). -
Table X BERT Contents
+
Table 15 BERT Contents
Bits | Meaning ---- | ------- 0-196 | BERT PRBS9 Payload @@ -493,6 +496,7 @@ This provides the same error ECC/FEC used for Stream Frames. Within the Physical Layer, the 368 Type 4 bits are randomized and combined with the 16-bit BERT Sync Burst, which results in a complete frame of 384 bits (384 bits / 9600bps = 40 ms). +
Figure 15 BERT Frame Construction
[mermaid] graph TD @@ -522,5 +526,5 @@ end ### Issues to address... * Stream FN rollover - allowed or not? -* + diff --git a/pages/04.appendix/01.address-encoding/docs.md b/pages/04.appendix/01.address-encoding/docs.md index 0f63122..870b584 100644 --- a/pages/04.appendix/01.address-encoding/docs.md +++ b/pages/04.appendix/01.address-encoding/docs.md @@ -14,6 +14,7 @@ M17 uses 48-bit (6-byte) addresses. Callsigns and special purpose addresses are ### Address Scheme +
Table 1 M17 Addresses
Address Range (base-16) | Category | Number of Addresses | Remarks ------------- | -------- | ------------------- | ------- 0x000000000000 | RESERVED | 1 | For future use @@ -25,6 +26,7 @@ Address Range (base-16) | Category | Number of Addresses | Remarks 9 characters from an alphabet of 40 possible characters can be encoded into 48 bits (6 bytes). The base-40 alphabet is: +
Table 2 M17 Callsign Alphabet
Value (base-10) | Character | Note --------------- | --------- | ---- 0 | ' ' | A space, ASCII 32 (0x20). Invalid characters will be replaced with this. @@ -124,6 +126,7 @@ Secondary operating suffixes are often added to callsign to indicate temporary c The minimum number of allowed callsign characters in the callsign alphabet is 37 ('A' through 'Z', '0' through '9', and '/'). The following table shows how many bytes are required to encoded a callsign using an alphabet size of 37. +
Table 3 Storage required for number of callsign characters
Callsign Characters | Bits | Bytes ------------------- | ---- | ----- 7 | $log_2(37^7)=36.47$ | 5 @@ -140,6 +143,7 @@ Of these, 9 characters into 6 bytes, or 12 charcters into 8 bytes are the most e The following table shows how many bytes are required to encode a 9 character callsign using callsign alphabet sizes of 37 through 41. +
Table 4 Storage required for alphabet size
Alphabet Size | Bits | Bytes ------------- | ---- | ----- 37 | $log_2(37^9)=46.89$ | 6 diff --git a/pages/04.appendix/02.randomizer-sequence/docs.md b/pages/04.appendix/02.randomizer-sequence/docs.md index 054e8ce..39b0deb 100644 --- a/pages/04.appendix/02.randomizer-sequence/docs.md +++ b/pages/04.appendix/02.randomizer-sequence/docs.md @@ -5,6 +5,7 @@ taxonomy: - docs --- +
Table 1 Randomizer values
Seq. number | Value | Seq. number | Value ----------- | ----- | ----------- | ----- 00 | 0xD6 | 23 | 0x6E diff --git a/pages/04.appendix/03.convolutional-encoder/docs.md b/pages/04.appendix/03.convolutional-encoder/docs.md index 5936da5..0f67905 100644 --- a/pages/04.appendix/03.convolutional-encoder/docs.md +++ b/pages/04.appendix/03.convolutional-encoder/docs.md @@ -16,6 +16,7 @@ The convolutional code shall encode the input bit sequence after appending 4 tai The output from the encoder must be read alternately. +
Figure 1 Convolutional encoder
![convolutional](convolutional.svg?classes=caption "Convolutional coder diagram") ### Issues to address... diff --git a/pages/04.appendix/04.golay-encoder/docs.md b/pages/04.appendix/04.golay-encoder/docs.md index b4e8710..6d52ecd 100644 --- a/pages/04.appendix/04.golay-encoder/docs.md +++ b/pages/04.appendix/04.golay-encoder/docs.md @@ -48,7 +48,8 @@ This is equivalent to 0xC75 in hexadecimal notation. Both the generating matrix \) The output of the Golay encoder is shown in the table below. - + +
Table 1 Golay encoder details
Field | Data | Check bits | Parity ----- | ---- | ---------- | ------ Position | 23..12 | 11..1 | 0 (LSB) diff --git a/pages/04.appendix/06.interleaving/docs.md b/pages/04.appendix/06.interleaving/docs.md index 7c2204a..70eb2c7 100644 --- a/pages/04.appendix/06.interleaving/docs.md +++ b/pages/04.appendix/06.interleaving/docs.md @@ -7,7 +7,7 @@ taxonomy: For interleaving a Quadratic Permutation Polynomial (QPP) is used. The polynomial \(\pi(x)=(45x+92x^2)\mod 368\) is used for a 368 bit interleaving pattern QPP. - +
Table 1 Interleaver mapping
input index | output index | input index | output index | input index | output index | input index | output index ----------- | ------------ | ----------- | ------------ | ----------- | ------------ | ----------- | ------------ 0 | 0 | 92 | 92 | 184 | 184 | 276 | 276 diff --git a/pages/04.appendix/07.bert-details/docs.md b/pages/04.appendix/07.bert-details/docs.md index d16dcfd..bc25e5e 100644 --- a/pages/04.appendix/07.bert-details/docs.md +++ b/pages/04.appendix/07.bert-details/docs.md @@ -12,13 +12,13 @@ The PRBS uses the ITU standard PRBS9 polynomial : \(x^{9}+x^{5}+1\) This is the traditional form for a linear feedback shift register (LFSR) used to generate a psuedorandom binary sequence. -
Figure X Traditional form LFSR
+
Figure 1 Traditional form LFSR
![Traditional_LFSR](m17-traditional-lfsr.png?classes=caption "Traditional LFSR") However, the M17 LFSR is a slightly different. The M17 PRBS9 uses the generated bit as the output bit rather than the high-bit before the shift. -
Figure X M17 LFSR
+
Figure 2 M17 LFSR
![M17_LFSR](m17-prbs9.png?classes=caption "M17 LFSR") This will result in the same sequence, just shifted by nine bits. @@ -29,7 +29,7 @@ The reason for this is that it allows for easier synchronization. This is equivalent to a multiplicative scrambler (a self-synchronizing scrambler) fed with a stream of 0s. -
Figure X M17 PRBS9 Generator
+
Figure 3 M17 PRBS9 Generator
![M17_PRBS9_Generator](m17-equivalent-scrambler.png?classes=caption "M17 PRBS9 Generator") ``` @@ -69,7 +69,7 @@ reset. The received bit is then also shifted into the LFSR state register. Once a sequence of eighteen (18) consecutive good bits are recovered (twice the length of the LFSR), the stream is considered syncronized. -
Figure X M17 PRBS9 Synchronization
+
Figure 4 M17 PRBS9 Synchronization
![M17_PRBS9_Sync](m17-prbs9-sync.png?classes=caption "M17 PRBS9 Sync") During synchronization, bits received and bit errors are not counted towards @@ -107,7 +107,7 @@ After synchronization, BERT mode switches to error-counting mode, where the received bits are compared to a free-running PRBS9 generator. Each bit that does not match the output of the free-running LFSR is counted as a bit error. -
Figure X M17 PRBS9 Validation
+
Figure 5 M17 PRBS9 Validation
![M17_PRBS9_Validation](m17-prbs9-validation.png?classes=caption "M17 PRBS9 Validation") ``` diff --git a/pages/04.appendix/08.kiss-protocol/docs.md b/pages/04.appendix/08.kiss-protocol/docs.md index 3f375d3..ab35d55 100644 --- a/pages/04.appendix/08.kiss-protocol/docs.md +++ b/pages/04.appendix/08.kiss-protocol/docs.md @@ -131,8 +131,9 @@ The streaming protocol is fairly trivial to describe. It is used by sending firs #### Stream Format -##### M17 Kiss Stream Protocol +##### M17 KISS Stream Protocol +
Table 1 KISS Stream
Frame Size | Contents ---------- | -------- 30 | Link Setup Frame @@ -153,6 +154,7 @@ The data frames contain a 6-byte (48-bit) LICH segment followed by a 20 byte pay ##### KISS Stream Data Frame +
Table 2 KISS Stream Data
Frame Size | Contents ---------- | -------- 6 | LICH (48 bits) diff --git a/pages/04.appendix/09.file-formats/docs.md b/pages/04.appendix/09.file-formats/docs.md index 3cc039f..a981a44 100644 --- a/pages/04.appendix/09.file-formats/docs.md +++ b/pages/04.appendix/09.file-formats/docs.md @@ -43,6 +43,7 @@ The rate at which new symbols are generated. For M17, this is 4800 symbols per ### File Extensions Multiple files are used when testing the different elements of the M17 protocol. File extensions (the three characters after a period in a complete file name) are defined to standardize formats and usage. +
Table 1 File extensions
Extension | Description | Data Format | Data Rate --------- | ----------- | ----------- | --------- aud | Mono audio | Signed 16-bit LE | 8000 samples per second From 1a1fa9b3a58030024387dd5b1a55b1ee98d24f40 Mon Sep 17 00:00:00 2001 From: Jay Francis Date: Wed, 22 Jun 2022 15:24:15 -0400 Subject: [PATCH 3/4] Extensive application layer work --- pages/02.part-1/05.application-layer/docs.md | 177 ++++++++++++++----- 1 file changed, 135 insertions(+), 42 deletions(-) diff --git a/pages/02.part-1/05.application-layer/docs.md b/pages/02.part-1/05.application-layer/docs.md index dfaba67..903805d 100644 --- a/pages/02.part-1/05.application-layer/docs.md +++ b/pages/02.part-1/05.application-layer/docs.md @@ -5,30 +5,64 @@ taxonomy: - docs media_order: 'LFSR_8.svg,LFSR_16.svg,LFSR_24.svg' --- +### M17 Amateur Radio Voice Application -### M17 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](http://rowetel.com/codec2.html) 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 licencing regimes. -This section defines the application layer parameters for an audio stream containing low bit rate speech encoded using the open source [Codec 2](http://rowetel.com/codec2.html) codec. +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](#references-acknowledgements) the details included here. [Data Link Layer Stream Mode](../04.data-link-layer/#stream-mode) is used for this application. -#### M17 Voice Application LSF Parameters - A Stream Mode Transmission begins with an [LSF](../04.data-link-layer/#link-setup-frame-lsf). -
Table 3 Link Setup Frame Contents
+#### M17 Amateur Radio Voice Application LSF/LICH + +
Table 16 Link Setup Frame Contents
Field | Length | Description ----- | ------ | ----------- -DST | 48 bits | Destination address - Encoded callsign or a special number (eg. a group) -SRC | 48 bits | Source address - Encoded callsign of the originator or a special number (eg. a group) +DST | 48 bits | Destination address +SRC | 48 bits | Source address TYPE | 16 bits | Information about the incoming data stream -META | 112 bits | Metadata field, suitable for cryptographic metadata like IVs or single-use numbers, or non-crypto metadata like the sender’s GNSS position. +META | 112 bits | Metadata field -Destination (DST) and source (SRC) addresses may be encoded amateur radio callsigns, or special numbers. See the [Address Encoding Appendix](../../appendix/address-encoding) for details. +##### Address fields + +Destination (DST) and source (SRC) addresses may be encoded amateur radio callsigns, or special identifiers. See the [Address Encoding Appendix](../../appendix/address-encoding) 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 4 LSF TYPE definition
+
Table 18 M17 Voice LSF TYPE definition
Bits | Meaning ---- | ------- 0 | Packet/Stream indicator @@ -40,9 +74,7 @@ Bits | Meaning | $01_2$ = Scrambling | $10_2$ = AES 5..6 | Encryption subtype - | foo 7..10 | Channel Access Number (CAN) - | foo 11..15 | Reserved (don’t care) This application requires Stream Mode. @@ -57,29 +89,85 @@ Encryption is **optional**. The use of it may be restricted within some radio se Encryption type = $00_2$ -The “Encryption SubType” bits in the Stream Type field then indicate what data is stored in the 112 bits of the LSF META field. +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 ammounts 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. -Encryption SubType bits | LSF META data contents +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$ | UTF-8 Text +$00_2$ | Text Data $01_2$ | GNSS Position Data -$10_2$ | Reserved +$10_2$ | Extended Callsign Data $11_2$ | Reserved -All LSF META data must be stored in big endian byte order. +##### Text Data + +The first byte of the Text Data is a Control Byte. To maintain backward compatability, 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: -Size in bits | Format | Contents ------------- | ------ | -------- -8 | 8-bit signed integer | Latitude - degrees, integer part (-90..+90, positive values for northern hemisphere) -16 | 16-bit unsigned integer | Latitude - degrees, fractional part (eg. 0.5 -> 32,768) -16 | 16-bit unsigned integer | Longitude - degrees, integer part (-180..+180, positive values for eastern hemisphere) -16 | 16-bit unsigned integer | Longitude Longitude - degrees, fractional part (eg. 0.5 -> 32,768) -16 | unsigned integer | Altitude, in feet MSL. Stored +1500, so a stored value of 0 represents -1500 MSL. Subtract 1500 feet when parsing. -10 | unsigned integer | Course in degrees true North -10 | unsigned integer | Speed in miles per hour -20 | reserved values | Transmitter/Object description field +
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 : Open RTX +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](../../appendix/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 @@ -87,38 +175,36 @@ 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 initialised 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 5 to 8 show block diagrams of the algorithm +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 initialised 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 LSFR taps
![LSFR_8](LFSR_8.svg?classes=caption "8-bit LSFR taps") - --- - +
Figure 17 16-bit LSFR taps
![LSFR_16](LFSR_16.svg?classes=caption "16-bit LSFR taps") - --- - +
Figure 18 24-bit LSFR taps
![LSFR_24](LFSR_24.svg?classes=caption "24-bit LSFR taps") ---- - -#### Advanced Encryption Standard (AES) +##### 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. +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 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 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 21 minutes and some change. +> 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. @@ -126,6 +212,7 @@ To combat replay attacks, a 32-bit timestamp shall be embedded into the cryptogr ##### 96 bit nonce field structure +
Table 23 Nonce field
| Timestamp | Random Data | CTR_HIGH | | --------- | ----------- | -------- | | 32 | 64 | 16 | @@ -134,10 +221,16 @@ To combat replay attacks, a 32-bit timestamp shall be embedded into the cryptogr !! 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) -##### LSF META +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. + +#### References / Acknowledgements + + - [Jonathan Naylor (G4KLX) Source/Destination and META fields in the M17 Voice Application](https://discourse.m17project.org/t/callsigns-and-extended-use-of-the-meta-field-in-m17/103) + - [Jonathan Naylor (G4KLX) GPS Encoding in META field](https://discourse.m17project.org/t/the-format-of-the-m17-gps-data/107/3) + - [Jonathan Naylor (G4KLX) Multi-Mode Digital Voice Modem (MMVDM)](https://github.com/g4klx/MMDVM) -The LSF META field is defined by the specific application. ### Packet Application From c9d3efdccd8647a49de1c81be2d8586d759c800e Mon Sep 17 00:00:00 2001 From: Jay Francis Date: Thu, 23 Jun 2022 10:34:54 -0400 Subject: [PATCH 4/4] Fixed typo, add table number and !!! Incomplete !!! warning in Packet Application, corrected Welcome links to Application Layer --- pages/01.welcome/default.md | 4 ++-- pages/02.part-1/05.application-layer/docs.md | 17 +++++++++++++++-- 2 files changed, 17 insertions(+), 4 deletions(-) diff --git a/pages/01.welcome/default.md b/pages/01.welcome/default.md index eb80a2b..3b750c3 100644 --- a/pages/01.welcome/default.md +++ b/pages/01.welcome/default.md @@ -15,8 +15,8 @@ title: Welcome * [Packet Mode](/part-1/data-link-layer#packet-mode) * [BERT Mode](/part-1/data-link-layer#bert-mode) * [Application Layer](/part-1/application-layer) - * [Packet Superframes](/part-1/application-layer#packet-superframes) - * [Encryption Types](/part-1/application-layer#encryption-types) + * [Amateur Radio Voice Application](/part-1/application-layer#m17-amateur-radio-voice-application) + * [Packet Application](/part-1/application-layer#packet-application) ## Part II - Internet Interface * [M17 Internet Protocol (IP) Networking](/part-2/ip-networking) diff --git a/pages/02.part-1/05.application-layer/docs.md b/pages/02.part-1/05.application-layer/docs.md index 903805d..39bfc65 100644 --- a/pages/02.part-1/05.application-layer/docs.md +++ b/pages/02.part-1/05.application-layer/docs.md @@ -20,7 +20,7 @@ Credit to Jonathan Naylor (G4KLX) for [documenting and implementing](#references A Stream Mode Transmission begins with an [LSF](../04.data-link-layer/#link-setup-frame-lsf). -#### M17 Amateur Radio Voice Application LSF/LICH +#### LSF/LICH
Table 16 Link Setup Frame Contents
Field | Length | Description @@ -89,7 +89,7 @@ Encryption is **optional**. The use of it may be restricted within some radio se 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 ammounts 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. +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. @@ -225,6 +225,10 @@ To combat replay attacks, a 32-bit timestamp shall be embedded into the cryptogr 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](../data-link-layer#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](https://discourse.m17project.org/t/callsigns-and-extended-use-of-the-meta-field-in-m17/103) @@ -234,12 +238,21 @@ The Channel Access Number (CAN) is a four bit code that may be used to filter re ### 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](../data-link-layer#packet-mode). + +A Stream Mode Transmission begins with an [LSF](../04.data-link-layer/#link-setup-frame-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 identifers are reserved in the M17 packet spec: ##### Reserved Protocols +
Table 24 Packet protocol identifiers
Identifier | Protocol ---------- | -------- 0x00 | RAW
Figure X BERT ModeFigure 14 BERT Mode
PREAMBLE