diff --git a/.github/workflows/pull_request.yml b/.github/workflows/pull_request.yml deleted file mode 100644 index 1164f0c..0000000 --- a/.github/workflows/pull_request.yml +++ /dev/null @@ -1,18 +0,0 @@ -name: "Pull Request Docs Check" -on: -- pull_request - -jobs: - docs: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v1 - - uses: ammaraskar/sphinx-action@master - with: - docs-folder: "docs/" - build-command: "make html" - # Create an artifact of the html output. - - uses: actions/upload-artifact@v1 - with: - name: DocumentationHTML - path: docs/_build/html/ diff --git a/.github/workflows/push.yml b/.github/workflows/push.yml deleted file mode 100644 index 1b13d8a..0000000 --- a/.github/workflows/push.yml +++ /dev/null @@ -1,40 +0,0 @@ -name: "Push Generate Docs" -on: - push: - branches: - - master -jobs: - docs: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v1 - - uses: ammaraskar/sphinx-action@master - with: - docs-folder: "docs/" - build-command: "make html" - # Create an artifact of the html output. - - uses: actions/upload-artifact@v1 - with: - name: DocumentationHTML - path: docs/_build/html/ - # Publish built docs to gh-pages branch. - # =============================== - - name: Commit documentation changes - run: | - git clone https://github.com/M17-Project/M17_spec.git --branch gh-pages --single-branch gh-pages - cp -r docs/_build/html/* gh-pages/ - cd gh-pages - touch .nojekyll - git config --local user.email "smiller@kc1awv.net" - git config --local user.name "kc1awv" - git add . - git commit -m "Update live documentation" -a || true - # The above command will fail if no changes were present, so we ignore - # that. - - name: Push changes - uses: ad-m/github-push-action@master - with: - branch: gh-pages - directory: gh-pages - github_token: ${{ secrets.GH_TOKEN }} - # =============================== diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..800905b --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,15 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +mkdocs: + configuration: mkdocs.yml + +# Optionally set the version of Python and requirements required to build your docs +python: + version: "3.7" + install: + - requirements: docs/requirements.txt \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 298ea9e..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,19 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -SOURCEDIR = . -BUILDDIR = _build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/address_encoding.md b/docs/address_encoding.md new file mode 100644 index 0000000..08f4aba --- /dev/null +++ b/docs/address_encoding.md @@ -0,0 +1,137 @@ +# Address Encoding + +M17 uses 48 bits (6 bytes) long addresses. Callsigns (and other addresses) are encoded into these 6 bytes in the following ways: + +* An address of 0 is invalid. +* Address values between 1 and 262143999999999 (which is 409−1), up to 9 characters of text are encoded using base40, described below. +* Address values between 262144000000000 (409) and 281474976710654 (248−2) are invalid +* An address of 0xFFFFFFFFFFFF is a broadcast. All stations should receive and listen to this message. + +##### Address Scheme + +Address Range | Category | Number of Addresses | Remarks +------------- | -------- | ------------------- | ------- +0x000000000000 | RESERVED | 1 | For future use +0x000000000001 - 0xee6b27ffffff | Unit ID | 262143999999999 | +0xee6b28000000 - 0xfffffffffffe | RESERVED | 19330976710655 | For future use +0xffffffffffff | Broadcast | 1 | Valid only for destination + +## Callsign Encoding: base40 + +9 characters from an alphabet of 40 possible characters can be encoded into 48 bits, 6 bytes. The base40 alphabet is: + +* 0: A space. Invalid characters will be replaced with this. +* 1-26: “A” through “Z” +* 27-36: “0” through “9” +* 37: “-” (hyphen) +* 38: “/” (slash) +* 39: “.” (dot) + +Encoding is little endian. That is, the right most characters in the encoded string are the most significant bits in the resulting encoding. + +#### Example code: encode_base40() + +```c +uint64_t encode_callsign_base40(const char *callsign) { + uint64_t encoded = 0; + for (const char *p = (callsign + strlen(callsign) - 1); p >= callsign; p-- ) { + encoded *= 40; + // If speed is more important than code space, + // you can replace this with a lookup into a 256 byte array. + if (*p >= 'A' && *p <= 'Z') // 1-26 + encoded += *p - 'A' + 1; + else if (*p >= '0' && *p <= '9') // 27-36 + encoded += *p - '0' + 27; + else if (*p == '-') // 37 + encoded += 37; + // These are just place holders. If other characters make more sense, + // change these. Be sure to change them in the decode array below too. + else if (*p == '/') // 38 + encoded += 38; + else if (*p == '.') // 39 + encoded += 39; + else + // Invalid character or space, represented by 0, decoded as a space. + //encoded += 0; + } + return encoded; +} +``` + +#### Example code: decode_base40() + +```c +char *decode_callsign_base40(uint64_t encoded, char *callsign) { + if (encoded >= 262144000000000) { // 40^9 + *callsign = 0; + return callsign; + } + char *p = callsign; + for (; encoded > 0; p++) { + *p = " ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-/."[encoded % 40]; + encoded /= 40; + } + *p = 0; + + return callsign; +} +``` + +#### Why base40? + +The longest commonly assigned callsign from the FCC is 6 characters. The minimum alphabet of A-Z, 0-9, and a “done” character mean the most compact encoding of an American callsign could be: $log2(37^6)=31.26$ bits, or 4 bytes. + +Some countries use longer callsigns, and the US sometimes issues longer special event callsigns. Also, we want to extend our callsigns (see below). So we want more than 6 characters. How many bits do we need to represent more characters: + +##### Bits per Characters + +Characters | Bits | Bytes +---------- | ---- | ----- +7 | $log2(37^7)=36.47$ | 5 +8 | $log2(37^8)=41.67$ | 6 +9 | $log2(37^9)=46.89$ | 6 +10 | $log2(37^{10})=52.09$ | 7 + +Of these, 9 characters into 6 bytes seems the sweet spot. Given 9 characters, how large can we make the alphabet without using more than 6 bytes? + +##### Alphabet Size vs. Bytes + +Alphabet Size | Bits | Bytes +------------- | ---- | ----- +37 | $log2(37^9)=46.89$ | 6 +38 | $log2(38^9)=47.23$ | 6 +39 | $log2(39^9)=47.57$ | 6 +40 | $log2(40^9)=47.90$ | 6 +41 | $log2(41^9)=48.22$ | 7 + +Given this, 9 characters from an alphabet of 40 possible characters, makes maximal use of 6 bytes. + +## Callsign Formats + +Government issued callsigns should be able to encode directly with no changes. + +#### Multiple Stations + +To allow for multiple stations by the same operator, we borrow the use of the ‘-’ character from AX.25 and the SSID field. A callsign such as “AB1CD-1” is considered a different station than “AB1CD-2” or even “AB1CD”, but it is understood that these all belong to the same operator, “AB1CD” + +#### Temporary Modifiers + +Similarly, suffixes are often added to callsign to indicate temporary changes of status, such as “AB1CD/M” for a mobile station, or “AB1CD/AE” to signify that I have Amateur Extra operating privileges even though the FCC database may not yet be updated. So the ‘/’ is included in the base40 alphabet. The difference between ‘-’ and ‘/’ is that ‘-’ are considered different stations, but ‘/’ are NOT. They are considered to be a temporary modification to the same station. + +#### Interoperability + +It may be desirable to bridge information between M17 and other networks. The 9 character base40 encoding allows for this: + +##### DMR + +DMR unfortunately doesn’t have a guaranteed single name space. Individual IDs are reasonably well recognized to be managed by [RadioID.net](https://www.radioid.net/database/search#!) but Talk Groups are much less well managed. Talk Group XYZ on Brandmeister may be (and often is) different than Talk Group XYZ on a private cBridge system. + +* DMR IDs are encoded as: D eg: D3106728 for KR6ZY +* DMR Talk Groups are encoded by their network. Currently, the following networks are defined: + * Brandmeister: BM eg: BM31075 + * DMRPlus: DP eg: DP262 + * More networks to be defined here. + +##### D-Star + +D-Star reflectors have well defined names: REFxxxY which are encoded directly into base40. diff --git a/docs/address_encoding.rst b/docs/address_encoding.rst deleted file mode 100644 index 7255d9a..0000000 --- a/docs/address_encoding.rst +++ /dev/null @@ -1,215 +0,0 @@ -Address Encoding -================ - -M17 uses 48 bits (6 bytes) long addresses. Callsigns (and other -addresses) are encoded into these 6 bytes in the following ways: - -* An address of 0 is invalid. - -* Address values between 1 and 262143999999999 (which is - :math:`40^9-1`), up to 9 characters of text are encoded using - base40, described below. -* Address values between 262144000000000 (:math:`40^9`) and - 281474976710654 (:math:`2^{48}-2`) are invalid - -.. todo:: Can we think of something to do with these 19330976710655 addresses? - -* An address of 0xFFFFFFFFFFFF is a broadcast. All stations should - receive and listen to this message. - -.. table:: Address scheme - - +------------------------------+---------------+-------------------+-------------------+ - |Address Range |Category |Number of addresses|Remarks | - +==============================+===============+===================+===================+ - |0x000000000000 |RESERVED |1 |For future use | - +------------------------------+---------------+-------------------+-------------------+ - |0x000000000001-0xee6b27ffffff |Unit ID |262143999999999 | | - +------------------------------+---------------+-------------------+-------------------+ - |0xee6b28000000-0xfffffffffffe |RESERVED |19330976710655 |For future use | - +------------------------------+---------------+-------------------+-------------------+ - |0xffffffffffff |Broadcast |1 |Valid only for | - | | | |destination field | - +------------------------------+---------------+-------------------+-------------------+ - - -Callsign Encoding: base40 -------------------------- - -9 characters from an alphabet of 40 possible characters can be encoded into 48 bits, 6 bytes. The -base40 alphabet is: - -* 0: A space. Invalid characters will be replaced with this. -* 1-26: "A" through "Z" -* 27-36: "0" through "9" -* 37: "-" (hyphen) -* 38: "/" (slash) -* 39: "." (dot) - -Encoding is little endian. That is, the right most characters in the -encoded string are the most significant bits in the resulting -encoding. - -Example code: encode_base40() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: c - - uint64_t encode_callsign_base40(const char *callsign) { - uint64_t encoded = 0; - for (const char *p = (callsign + strlen(callsign) - 1); p >= callsign; p-- ) { - encoded *= 40; - // If speed is more important than code space, - // you can replace this with a lookup into a 256 byte array. - if (*p >= 'A' && *p <= 'Z') // 1-26 - encoded += *p - 'A' + 1; - else if (*p >= '0' && *p <= '9') // 27-36 - encoded += *p - '0' + 27; - else if (*p == '-') // 37 - encoded += 37; - // These are just place holders. If other characters make more sense, - // change these. Be sure to change them in the decode array below too. - else if (*p == '/') // 38 - encoded += 38; - else if (*p == '.') // 39 - encoded += 39; - else - // Invalid character or space, represented by 0, decoded as a space. - //encoded += 0; - } - return encoded; - } - -Example code: decode_base40() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: c - - char *decode_callsign_base40(uint64_t encoded, char *callsign) { - if (encoded >= 262144000000000) { // 40^9 - *callsign = 0; - return callsign; - } - char *p = callsign; - for (; encoded > 0; p++) { - *p = " ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-/."[encoded % 40]; - encoded /= 40; - } - *p = 0; - - return callsign; - } - -Why base40? -~~~~~~~~~~~ - -The longest commonly assigned callsign from the FCC is 6 characters. The minimum alphabet of A-Z, -0-9, and a "done" character mean the most compact encoding of an American callsign could be: -:math:`log2(37^6)=31.26` bits, or 4 bytes. - -Some countries use longer callsigns, and the US sometimes issues -longer special event callsigns. Also, we want to extend our callsigns -(see below). So we want more than 6 characters. How many bits do we -need to represent more characters: - -.. list-table:: bits per characters - :header-rows: 1 - - * - characters - - bits - - bytes - * - 7 - - :math:`log2(37^7)=36.47` - - 5 - * - 8 - - :math:`log2(37^8)=41.67` - - 6 - * - 9 - - :math:`log2(37^9)=46.89` - - 6 - * - 10 - - :math:`log2(37^{10})=52.09` - - 7 - -Of these, 9 characters into 6 bytes seems the sweet spot. Given 9 -characters, how large can we make the alphabet without using more than -6 bytes? - -.. list-table:: alphabet size vs bytes - :header-rows: 1 - - * - alphabet size - - bits - - bytes - * - 37 - - :math:`log2(37^9)=46.89` - - 6 - * - 38 - - :math:`log2(38^9)=47.23` - - 6 - * - 39 - - :math:`log2(39^9)=47.57` - - 6 - * - 40 - - :math:`log2(40^9)=47.90` - - 6 - * - 41 - - :math:`log2(41^9)=48.22` - - 7 - -Given this, 9 characters from an alphabet of 40 possible characters, -makes maximal use of 6 bytes. - -Callsign Formats ----------------- - -Government issued callsigns should be able to encode directly with no -changes. - -Multiple Stations -~~~~~~~~~~~~~~~~~ - -To allow for multiple stations by the same operator, we borrow the use -of the '-' character from AX.25 and the SSID field. A callsign such as -"AB1CD-1" is considered a different station than "AB1CD-2" or even -"AB1CD", but it is understood that these all belong to the same -operator, "AB1CD" - -Temporary Modifiers -~~~~~~~~~~~~~~~~~~~ - -Similarly, suffixes are often added to callsign to indicate temporary -changes of status, such as "AB1CD/M" for a mobile station, or -"AB1CD/AE" to signify that I have Amateur Extra operating privileges -even though the FCC database may not yet be updated. So the '/' is -included in the base40 alphabet. The difference between '-' and '/' -is that '-' are considered different stations, but '/' are NOT. They -are considered to be a temporary modification to the same -station. - -Interoperability -~~~~~~~~~~~~~~~~ - -It may be desirable to bridge information between M17 and other -networks. The 9 character base40 encoding allows for this: - -DMR -+++ - -DMR unfortunately doesn't have a guaranteed single name -space. Individual IDs are reasonably well recognized to be managed by -https://www.radioid.net/database/search#! but Talk Groups are much -less well managed. Talk Group XYZ on Brandmeister may be (and often -is) different than Talk Group XYZ on a private cBridge system. - -* DMR IDs are encoded as: D eg: D3106728 for KR6ZY -* DMR Talk Groups are encoded by their network. Currently, the - following networks are defined: -* Brandmeister: BM eg: BM31075 -* DMRPlus: DP eg: DP262 -* More networks to be defined here. - -D-Star -++++++ - -D-Star reflectors have well defined names: REFxxxY which are encoded directly into base40. diff --git a/docs/appendix.md b/docs/appendix.md new file mode 100644 index 0000000..2eab0a7 --- /dev/null +++ b/docs/appendix.md @@ -0,0 +1,18 @@ +## Appendix +* [Address Encoding](address_encoding.md) + * [Callsign Encoding: base40](address_encoding.md#callsign-encoding-base40) + * [Callsign Formats](address_encoding.md#callsign-formats) +* [Decorrelator sequence](decorrelator.md) +* [Interleaving](interleaving.md) +* [M17 Internet Protocol (IP) Networking](ip_networking.md) + * [Standard IP Framing](ip_networking.md#standard-ip-framing) + * [Control Packets](ip_networking.md#control-packets) +* [KISS Protocol](kiss_protocol.md) + * [References](kiss_protocol.md#references) + * [Glossary](kiss_protocol.md#glossary) + * [M17 Protocols](kiss_protocol.md#m17-protocols) + * [KISS Basics](kiss_protocol.md#kiss-basics) + * [Packet Protocols](kiss_protocol.md#packet-protocols) + * [Stream Protocol](kiss_protocol.md#stream-protocol) + * [Mixing Modes](kiss_protocol.md#mixing-modes) + * [Implementation Details](kiss_protocol.md#implementation-details) diff --git a/docs/application_layer.md b/docs/application_layer.md new file mode 100644 index 0000000..58366c7 --- /dev/null +++ b/docs/application_layer.md @@ -0,0 +1,95 @@ +# Application Layer + +PARTS 1 AND 2 REMOVED – will add this later. + +### Packet Superframes + +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 + +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. + +### 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$ + +The “Encryption SubType” bits in the Stream Type field then indicate what data is stored in the 112 bits of the LSF META field. + +Encryption SubType bits | LSF META data contents +----------------------- | ---------------------- +$00_2$ | UTF-8 Text +$01_2$ | GNSS Position Data +$10_2$ | Reserved +$11_2$ | Reserved + +All LSF META data must be stored in big endian byte order, as throughout the rest of this specification. + +GNSS Position Data stores the 112 bit META field as follows: + +Size in bits | Format | Contents +------------ | ------ | -------- +32 | 32-bit fixed point degrees and decimal minutes (TBD) | Latitude +32 | 32-bit fixed point degrees and decimal minutes (TBD) | Longitude +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 +12 | reserved values | Transmitter/Object description field + +#### Scrambler + +Encryption type = $01_2$ + +Scrambling is an encryption by bit inversion using a bitwise exclusive-or (XOR) operation between bit sequence of data and pseudorandom bit sequence. + +Encrypting bitstream 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. Seed value acts as an encryption key for the scrambler algorithm. Figures 5 to 8 show block diagrams of the algorithm + +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 + +##### 8-bit LSFR Taps +![LSFR_8](img/LFSR_8.svg) + +##### 16-bit LSFR Taps +![LSFR_16](img/LFSR_16.svg) + +##### 24-bit LSFR Taps +![LSFR_24](img/LFSR_24.svg) + +#### 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. + +##### 96 bit nonce field structure + +Timestamp | Random Data | CTR_HIGH +--------- | ----------- | -------- +32 | 64 | 16 + +!!! warning + In CTR mode, AES encryption is malleable [CTR] [CRYPTO]. 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 [CRYPTO]. diff --git a/docs/application_layer.rst b/docs/application_layer.rst deleted file mode 100644 index 006a60e..0000000 --- a/docs/application_layer.rst +++ /dev/null @@ -1,214 +0,0 @@ -Application Layer -================= - -PARTS 1 AND 2 REMOVED – will add this later. - -.. _packet-superframes: - -Packet Superframes ------------------- - -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: - -.. list-table:: Reserved Protocols - :header-rows: 1 - - * - Identifer - - 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. - -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 = :math:`00_2` - -No encryption is performed, payload is sent in clear text. - -The "Encryption SubType" bits in the Stream Type field then indicate -what data is stored in the 112 bits of the LSF META field. - -.. list-table:: - :header-rows: 1 - - * - Encryption SubType bits - - LSF META data contents - * - :math:`00_2` - - UTF-8 Text - * - :math:`01_2` - - GNSS Position Data - * - :math:`10_2` - - Reserved - * - :math:`11_2` - - Reserved - -All LSF META data must be stored in big endian byte order, as throughout -the rest of this specification. - -GNSS Position Data stores the 112 bit META field as follows: - -.. list-table:: - :header-rows: 1 - - * - Size, in bits - - Format - - Contents - * - 32 - - 32-bit fixed point degrees and decimal minutes (TBD) - - Latitude - * - 32 - - 32-bit fixed point degrees and decimal minutes (TBD) - - Longitude - * - 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. - * - 12 - - Reserved values - - Transmitter/Object description field - - -Scrambler -~~~~~~~~~ - -Encryption type = :math:`01_2` - -Scrambling is an encryption by bit inversion using a bitwise -exclusive-or (XOR) operation between bit sequence of data and -pseudorandom bit sequence. - -Encrypting bitstream 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. Seed value acts as an encryption key for the scrambler -algorithm. Figures 5 to 8 show block diagrams of the algorithm - -.. list-table:: LFSR scrambler polynomials - :header-rows: 1 - - * - Encryption subtype - - LFSR polynomial - - Seed length - - Sequence period - * - :math:`00_2` - - :math:`x^8 + x^6 + x^5 + x^4 + 1` - - 8 bits - - 255 - * - :math:`01_2` - - :math:`x^{16} + x^{15} + x^{13} + x^4 + 1` - - 16 bits - - 65,535 - * - :math:`10_2` - - :math:`x^{24} + x^{23} + x^{22} + x^{17} + 1` - - 24 bits - - 16,777,215 - -.. figure:: ../images/LFSR_8.* - :scale: 22% - - 8-bit LFSR taps - -.. figure:: ../images/LFSR_16.* - :scale: 22% - - 16-bit LFSR taps - -.. figure:: ../images/LFSR_24.* - :scale: 22% - - 24-bit LFSR taps - - -Advanced Encryption Standard (AES) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Encryption type = :math:`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 [#fn_roll]_. - -.. [#fn_roll] 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 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”). - -.. list-table:: 96 bit nonce field structure - :header-rows: 1 - - * - 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. - -.. warning:: - In CTR mode, AES encryption is malleable [CTR]_ [CRYPTO]_. - 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 [CRYPTO]_. - -.. [CTR] McGrew, David A. "Counter mode security: Analysis and recommendations." Cisco Systems, November 2, no. 4 (2002). - -.. [CRYPTO] Rogaway, Phillip. "Evaluation of some blockcipher modes of operation." Cryptography Research and Evaluation Committees (CRYPTREC) for the Government of Japan (2011). diff --git a/docs/codeplug.md b/docs/codeplug.md new file mode 100644 index 0000000..7915607 --- /dev/null +++ b/docs/codeplug.md @@ -0,0 +1,94 @@ +# Codeplug + +## Recommendation for the codeplug structure + +### Introduction + +Codeplugs are ordinary text files with .m17 extension. They provide an information on: + +* channel banks +* channel frequencies +* destination IDs +* transmission mode +* payload type +* encryption mode + +Codeplugs should be human-readable and easily editable with common text editors. + +### Codeplug file structure + +We recommend using YAML for the codeplug files. + +#### Keywords + +``` +codeplug: + author: + String - Codeplug author, max 16 characters + version: + Date and time in YYYY-MM-DDTHH:MM:SS format +bank: + name: + String - Channel bank name, 16 characters maximum +channel: + name: + String - Channel name, 16 characters maximum + descr: + String - Channel Description, 16 characters maximum + freq_rx: + Integer - Channel RX Frequency in Hz + freq_tx: + Integer - Channel TX Frequency in Hz + mode: + Integer - Channel mode. Valid modes are: 0 - Analog, + 1 - Digital Voice, 2 - Digital Data, 3 - Digital Voice and Data + encr: + Integer - Is encryption enabled? 0 for no encryption, + 1 - AES256, 2 - scrambler etc. (refer to M17_spec for details) + nonce: + String - 14-byte hex value without leading 0x. nonce for + ciphers or initial LFSR value for scrambler + gps: + Boolean - If true, and mode value enables digital data, + gps data will be transferred along with payload +``` + +### Example Codeplug + +```yaml +codeplug: + author: SP5WWP + version: 2020-28-09T13:20:49 + - bank: + name: M17 + - channel: + name: M17_DMO + descr: + freq_rx: 439575000 + freq_tx: 439575000 + mode: 2 + encr: 0 + nonce: 0 + gps: false + - channel: + name: M17_DMO_2 + descr: + freq_rx: 439975000 + freq_tx: 439975000 + mode: 2 + encr: 0 + nonce: 0 + gps: false + - bank: + name: Repeaters + - channel: + name: SR5MS + descr: + freq_rx: 439425000 + freq_tx: 431825000 + mode: 2 + encr: 0 + nonce: 0 + gps: false +#codeplug end +``` diff --git a/docs/codeplug.rst b/docs/codeplug.rst deleted file mode 100644 index e85f7dc..0000000 --- a/docs/codeplug.rst +++ /dev/null @@ -1,93 +0,0 @@ -Recommendation for the codeplug structure -***************************************** - -Introduction -############ - -Codeplugs are ordinary text files with *.m17* extension. They provide an information on: - - * channel banks - * channel frequencies - * destination IDs - * transmission mode - * payload type - * encryption mode - -Codeplugs should be human-readable and easily editable with common text editors. - -Codeplug file structure -####################### - -We recommend using YAML for the codeplug files. - -Keywords --------- - -**codeplug:** - **author:** - String - Codeplug author, max 16 characters - **version:** - Date and time in YYYY-MM-DDTHH:MM:SS format - -**bank:** - **name:** - String - Channel bank name, 16 characters maximum - -**channel:** - **name:** - String - Channel name, 16 characters maximum - **descr:** - String - Channel Description, 16 characters maximum - **freq_rx:** - Integer - Channel RX Frequency in Hz - **freq_tx:** - Integer - Channel TX Frequency in Hz - **mode:** - Integer - Channel mode. Valid modes are: 0 - Analog, 1 - Digital Voice, 2 - Digital Data, 3 - Digital Voice and Data - **encr:** - Integer - Is encryption enabled? 0 for no encryption, 1 - AES256, 2 - scrambler etc. (refer to M17_spec for details) - **nonce:** - String - 14-byte hex value without leading 0x. nonce for ciphers or initial LFSR value for scrambler - **gps:** - Boolean - If true, and mode value enables digital data, gps data will be transferred along with payload - -Example Codeplug -################ - -:: - - codeplug: - author: SP5WWP - version: 2020-28-09T13:20:49 - - bank: - name: M17 - - channel: - name: M17_DMO - descr: - freq_rx: 439575000 - freq_tx: 439575000 - mode: 2 - encr: 0 - nonce: 0 - gps: false - - channel: - name: M17_DMO_2 - descr: - freq_rx: 439975000 - freq_tx: 439975000 - mode: 2 - encr: 0 - nonce: 0 - gps: false - - bank: - name: Repeaters - - channel: - name: SR5MS - descr: - freq_rx: 439425000 - freq_tx: 431825000 - mode: 2 - encr: 0 - nonce: 0 - gps: false - #codeplug end diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 271ab4c..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,218 +0,0 @@ -# -*- coding: utf-8 -*- -# -# Configuration file for the Sphinx documentation builder. -# -# This file does only contain a selection of the most common options. For a -# full list see the documentation: -# http://www.sphinx-doc.org/en/master/config - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) -import sphinx_rtd_theme - -# -- Project information ----------------------------------------------------- - -project = 'M17 Protocol Specification' -copyright = '2021, Project M17' -author = 'M17 Working Group: Wojciech SP5WWP, Juhani OH1CAU, Elms KM6VMZ, Nikoloz SO3ALG, Mark KR6ZY, Steve KC1AWV, Rob WX9O, Tom N7TAE, Mike W2FBI ' - -# The short X.Y version -version = '' -# The full version, including alpha/beta/rc tags -#release = 'DRAFT' - - -# -- General configuration --------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - 'sphinx_rtd_theme', - 'sphinx.ext.graphviz', - 'sphinxcontrib.rsvgconverter', - 'sphinx.ext.mathjax', - 'sphinx.ext.todo', -] - -numfig = True - -# Add any paths that contain templates here, relative to this directory. -#templates_path = ['_templates'] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = '.rst' - -# The master toctree document. -master_doc = 'index' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = None - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = None - - -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = "sphinx_rtd_theme" - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -# html_theme_options = {} - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -#html_static_path = ['_static'] - -# Custom sidebar templates, must be a dictionary that maps document names -# to template names. -# -# The default sidebars (for documents that don't match any pattern) are -# defined by theme itself. Builtin themes are using these templates by -# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', -# 'searchbox.html']``. -# -# html_sidebars = {} - - -# -- Options for HTMLHelp output --------------------------------------------- - -# Output file base name for HTML help builder. -htmlhelp_basename = 'M17ProtocolSpecificationdoc' - - -# -- Options for LaTeX output ------------------------------------------------ - -latex_engine = 'latex' - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_author = '{}: \\\\ \\hline \\\\\n'.format(author.split(':')[0]) + '\\\\\n'.join(['{} \\hfill {}'.format(*auth.split()) for auth in author.split(':')[1].split(',')]) -latex_documents = [ - ('indexPartI', 'M17ProtocolSpecification.tex', 'M17 Protocol Specification', - latex_author, 'manual'), - ('indexPartII', 'M17ProtocolCodeplug.tex', 'M17 Protocol Codeplug', - latex_author, 'manual') -] -latex_elements = { - 'fncychap': '\\usepackage[Sonny]{fncychap}', - 'figure_align': 'H', - 'preamble': r''' -\usepackage[toc,page]{appendix} - -\newcommand{\sphinxbackoftitlepage}{Published \today - -Copyright © 2019-2021 M17 Working Group - -Permission is granted to make and distribute verbatim copies of this -document provided the copyright notice and this permission notice are -preserved on all copies. - -Permission is granted to copy and distribute modified versions of this -document under the conditions for verbatim copying, provided that the -entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - -Permission is granted to copy and distribute translations of this -document into another language, under the above conditions for -modified versions, except that this permission notice may be included -in translations approved by the Free Software Foundation instead of in -the original English. - -See the GNU General Public License version 2 for more details. -} -''', - 'releasename': 'DRAFT', - } -latex_logo = '../images/m17_logo_shadow_400.png' - -# -- Options for manual page output ------------------------------------------ - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'm17protocolspecification', 'M17 Protocol Specification', - [author], 1) -] - - -# -- Options for Texinfo output ---------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - (master_doc, 'M17ProtocolSpecification', 'M17 Protocol Specification', - author, 'M17ProtocolSpecification', 'One line description of project.', - 'Miscellaneous'), -] - - -# -- Options for Epub output ------------------------------------------------- - -# Bibliographic Dublin Core info. -epub_title = project - -# The unique identifier of the text. This can be a ISBN number -# or the project homepage. -# -# epub_identifier = '' - -# A unique identification for the text. -# -# epub_uid = '' - -# A list of files that should not be packed into the epub file. -epub_exclude_files = ['search.html'] - - -# -- Extension configuration ------------------------------------------------- diff --git a/docs/data_link_layer.md b/docs/data_link_layer.md new file mode 100644 index 0000000..66c2eea --- /dev/null +++ b/docs/data_link_layer.md @@ -0,0 +1,241 @@ +# Data Link Layer + +The Data Link layer is split into two modes: + +* Packet Mode + > Data are sent in small bursts, on the order of 100s to 1000s of bytes at a time, after which the physical layer stops sending data. e.g. messages, beacons, etc. +* Stream Mode + > Data are sent in a continuous stream for an indefinite amount of time, with no break in physical layer output, until the stream ends. e.g. voice data, bulk data transfers, etc. + +When the physical layer is idle (no RF being transmitted or received), the data link defaults to packet mode. + +As is the convention with other networking protocols, all values are encoded in big endian byte order. + +### Stream Mode + +In Stream Mode, an indefinite amount of payload data is sent continuously without breaks in the physical layer. The stream is broken up into parts, called frames to not confuse them with packets sent in packet mode. Frames contain payload data interleaved with frame signalling (similar to packets). Frame signalling is contained within the **Link Information Channel (LICH)**. + +#### Sync Burst + +All frames are preceded by a 16-bit synchronization burst. + +* Link setup frames shall be preceded with 0x55F7. +* Stream frames shall be preceeded with 0xFF5D. +* Packet frames shall be preceeded with 0x75FF. + +All syncwords are type 4 bits. + +These sync words are based on Barker codes. The sequence 0xDF55 (symbols -3 +3 -3 -3 +3 +3 +3 +3) is reserved. + +#### Link Setup Frame + +First frame of the transmission contains full LSF data. It’s called the Link Setup Frame (LSF), and is not part of any superframes. + +##### LSF Fields + +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) +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. +CRC | 16 bits | CRC for the link setup data +TAIL | 4 bits | Flushing bits for the convolutional encoder that do not carry any information. Only included for RF frames, not included for IP purposes. + +##### Bitfields of Type Field + +Bits | Meaning +---- | ------- +0 | Packet/stream indicator, 0=packet, 1=stream +1..2 | Data type indicator, $01_2$ =data (D), $10_2$ =voice (V), $11_2$ =V+D, $00_2$ =reserved +3..4 | Encryption type, $00_2$ =none, $01_2$ =AES, $10_2$ =scrambling, $11_2$ =other/reserved +5..6 | Encryption subtype (meaning of values depends on encryption type) +7..10 | Channel Access Number (CAN) +11..15 | Reserved (don’t care) + +The fields in Table 3 (except TAIL) form initial LSF. It contains all information needed to establish M17 link. Later in the transmission, the initial LSF is divided into 6 “chunks” and transmitted beside the payload data. This allows late-joiners to reconstruct the LICH after collecting all the pieces, and start decoding the stream even though they missed the beginning of the transmission. The process of collecting full LSF takes 6 frames or 6*40 ms = 240 ms. Four TAIL bits are needed for the convolutional coder to go back to state 0, so the ending trellis position is also known. + +Voice coder rate is inferred from TYPE field, bits 1 and 2. + +##### Voice Coder Rates + +Data Type Indicator | Voice Coder Rate +------------------- | ---------------- +$00_2$ | none / reserved +$01_2$ | no voice +$10_2$ | 3200 bps +$11_2$ | 1600 bps + +#### Subsequent Frames + +##### Fields for Frames other than LSF + +Field | Length | Description +----- | ------ | ----------- +LICH | 48 bits | LSF chunk, one of 6 +FN | 16 bits | Frame number, starts from 0 and increments every frame to a max of 0x7fff where it will then wrap back to 0. High bit set indicates this frame is the last of the stream +PAYLOAD | 128 bits | Payload/data, can contain arbitrary data +TAIL | 4 bits | Flushing bits for the convolutional encoder that don’t carry any information + +The most significant bit in the FN counter is used for transmission end signalling. When transmitting the last frame, it shall be set to 1 (one), and 0 (zero) in all other frames. + +The payload is used so that earlier data in the voice stream is sent first. For mixed voice and data payloads, the voice data is stored first, then the data. + +##### LSF Chunk Structure + +Bits | Content +---- | ------- +0..39 | 40 bits of full LSF +40..42 | A modulo 6 counter (LICH_CNT) for LSF re-assembly +43..47 | Reserved + +##### Payload Example 1 + +Codec2 encoded frame t + 0 | Codec2 encoded frame t + 1 + +##### Payload Example 2 + +Codec2 encoded frame t + 0 | Mixed data t + 0 + +#### Superframes + +Each frame contains a chunk of the LSF frame that was used to establish the stream. Frames are grouped into 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. + +![One Superframe](img/M17_stream.png) + +```mermaid +graph TD +c0["conv. coder"] +p0["P_1 puncturer"] +i0["interleaver"] +w0["decorrelator"] +s0["prepend LSF_SYNC"] +l0["LICH combiner"] +chunker_40["chunk 40 bits"] +golay_24_12["Golay (24, 12)"] +c1["conv. coder"] +p1["P_2 puncturer"] +i1["interleaver"] +w1["decorrelator"] +s1["prepend FRAME_SYNC"] +fn["add FN"] +chunker_128["chunk 128 bits"] +framecomb["Frame Combiner"] +supercomb["Superframe Combiner"] + +counter --> l0 +LSF --> c0 --> p0 --> i0 --> w0 --> s0 --> supercomb +LSF --> chunker_40 --> l0 --> golay_24_12 --> framecomb +data --> chunker_128 --> fn --> c1 --> p1 --> framecomb +framecomb --> i1 --> w1 --> s1 --> supercomb +preamble --> supercomb +``` + +#### CRC + +M17 uses a non-standard version of 16-bit CRC with polynomial $x^{16} + x^{14} + x^{12} + x^{11} + x^8 + x^5 + x^4 + x^2 + 1$ or 0x5935 and initial value of 0xFFFF. This polynomial allows for detecting all errors up to hamming distance of 5 with payloads up to 241 bits, which is less than the amount of data in each frame. + +As M17’s native bit order is most significant bit first, neither the input nor the output of the CRC algorithm gets reflected. + +The input to the CRC algorithm consists of DST, SRC (each 48 bits), 16 bits of TYPE field and 112 bits META, and then depending on whether the CRC is being computed or verified either 16 zero bits or the received CRC. + +The test vectors in the following table are calculated by feeding the given message and then 16 zero bits to the CRC algorithm. + +Message | CRC Output +------- | ---------- +(empty string) | 0xFFFF +ASCII string "A" | 0x206E +ASCII string "123456789" | 0x772B +Bytes 0x00 to 0xFF | 0x1c31 + +### Packet Mode + +In *packet mode*, a finite amount of payload data (for example – text messages or application layer data) is wrapped with a packet, sent over the physical layer, and is completed when done. ~~Any acknowledgement or retransmission is done at the application layer.~~ + +#### Link Setup Frame + +Packet mode uses the same link setup frame that has been defined for stream mode above. The packet/stream indicator is set to 0 in the type field. + +##### Bitfields of Type Field + +Bits | Meaning +---- | ------- +0 | Packet/stream indicator, 0=packet, 1=stream +1..2 | Data type indicator, $01_2$ =data (D), $10_2$ =voice (V), $11_2$ =V+D, $00_2$ =reserved +3..4 | Encryption type, $00_2$ =none, $01_2$ =AES, $10_2$ =scrambling, $11_2$ =other/reserved +5..6 | Encryption subtype (meaning of values depends on encryption type) +7..10 | Channel Access Number (CAN) +11..15 | Reserved (don’t care) + +Raw packet frames have no packet type metadata associated with them. Encapsulated packet format is discussed in Packet Superframes in the Application Layer section. This provides data type information and is the preferred format for use on M17. + +When encryption type is $00_2$, meaning no encryption, the encryption subtype bits are used to indicate the contents of the META field in the LSF. Since that space would otherwise go be unused, we can store small bits of data in that field such as free text or the sender’s GNSS position. + +Encryption type and subtype bits, including the plaintext data formats when not using encryption, are described in more detail in the Application Layer section of this document. + +Currently the contents of the source and destination fields are arbitrary as no behavior is defined which depends on the content of these fields. The only requirement is that the content is base-40 encoded. + +#### Packet Format + +M17 packet mode can transmit up to 798 bytes of payload data. It acheives a base throughput of 5kbps, and a net throughput of about 4.7kbps for the largest data payload, and over 3kbps for 100-byte payloads. (Net throughput takes into account preamble and link setup overhead.) + +The packet superframe consists of 798 payload data bytes and a 2-byte CCITT CRC-16 checksum. + +##### Byte Fields of Packet Superframe + +Bytes | Meaning +----- | ------- +1..798 | Packet payload +2 | CCITT CRC-16 + +Packet data is split into frames of 368 type 4 bits preceded by a packet-specific 16-bit sync word (0xFF5D). This is the same size frame used by stream mode. + +The packet frame starts with a 210 bit frame of type 1 data. It is noteworthy that it does not terminate on a byte boundary. + +The frame has 200 bits (25 bytes) of payload data, 6 bits of frame metadata, and 4 bits to flush the convolutional coder. + +##### Bit Fields of Packet Frame + +Bits | Meaning +---- | ------- +0..199 | Packet payload +1 | EOF indicator +5 | Frame / Byte count +4 | Flush bits for convolutional coder + +The metadata field contains a 1 bit **end of frame (EOF)** indicator, and a 5-bit frame/byte counter. + +The **EOF** bit is 1 only on the last frame. The **counter** field is used to indicate the frame number when **EOF** is 0, and the number of bytes in the last frame when **EOF** is 1. This encodes the exact packet size, up to 800 bytes, in a 6-bit field. + +##### Metadata Field with EOF = 0 + +Bits | Meaning +---- | ------- +0 | Set to 0, Not end of frame +1..5 | Frame number, 0..31 + +##### Metadata Field with EOF = 1 + +Bits | Meaning +---- | ------- +0 | Set to 1, End of frame +1..5 | Number of bytes in frame, 1..25 + +Note that it is non-conforming to send a last frame with a length of 0 bytes. + +#### Convolutional Coding + +The entire frame is convolutionally coded, giving 420 bits of type 2 data. It is then punctured using a 7/8 puncture matrix (1,1,1,1,1,1,1,0) to give 368 type 3 bits. These are then interleaved and decorrelated to give 368 type 4 bits. + +##### Packet Frame + +Bits | Meaning +---- | ------- +16 bits | Sync word 0xFF5D +368 bits | Payload + +#### Carrier-sense Multiple Access + +When sending packets, the sender is reponsible for ensuring the channel is clear before transmitting. CSMA is used to minimize collisions on a shared network. Specifically, P-persistent access is used. Each time slot is 40ms (one packet length) and the probability SHOULD default to 25%. In terms of the values used by the KISS protocol, these equate to a slot time of 4 and a P-persistence value of 63. + +The benefit of this method is that it imposes no penalty on uncontested networks. diff --git a/docs/data_link_layer.rst b/docs/data_link_layer.rst deleted file mode 100644 index 54b299d..0000000 --- a/docs/data_link_layer.rst +++ /dev/null @@ -1,417 +0,0 @@ -Data Link Layer -=============== -The Data Link layer is split into two modes: - -* Packet mode - Data are sent in small bursts, on the order of 100s to 1000s of bytes - at a time, after which the physical layer stops sending data. e.g. messages, beacons, etc. - -* Stream mode - Data are sent in a continuous stream for an indefinite amount of time, - with no break in physical layer output, until the stream ends. e.g. voice data, - bulk data transfers, etc. - -When the physical layer is idle (no RF being transmitted or received), -the data link defaults to packet mode. - -.. ~~To switch to stream mode, a -.. start stream packet (detailed later) is sent, immediately followed by -.. the switch to stream mode; the Stream of data immediately follows the -.. Start Stream packet without disabling the Physical layer. To switch -.. out of Stream mode, the stream simply ends and returns the Physical -.. layer to the idle state, and the Data Link defaults back to Packet -.. mode.~~ - -As is the convention with other networking protocols, all values are -encoded in big endian byte order. - -Stream Mode ------------ - -In Stream Mode, an *indefinite* amount of payload data is sent continuously without breaks in the -physical layer. The *stream* is broken up into parts, called *frames* to not confuse them with *packets* sent -in packet mode. Frames contain payload data interleaved with frame signalling (similar to packets). -Frame signalling is contained within the **Link Information Channel (LICH)**. - -Sync Burst -~~~~~~~~~~ - -All frames are preceded by a 16-bit *synchronization burst*. - - * Link setup frames shall be preceded with 0x55F7. - * Stream frames shall be preceeded with 0xFF5D. - * Packet frames shall be preceeded with 0x75FF. - -All syncwords are type 4 bits. - -These sync words are based on `Barker codes`_. The sequence 0xDF55 (symbols -3 +3 -3 -3 +3 +3 +3 +3) is reserved. - -.. _`Barker codes`: https://en.wikipedia.org/wiki/Barker_code - - -Link setup frame -~~~~~~~~~~~~~~~~ - -First frame of the transmission contains full LSF data. It’s called -the **Link Setup Frame (LSF)**, and is not part of any superframes. - -.. list-table:: Link setup frame fields - - * - 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) - * - 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. - * - CRC - - 16 bits - - CRC for the link setup data - * - TAIL - - 4 bits - - Flushing bits for the convolutional encoder that do not carry any information. Only included for RF frames, not included for IP purposes. - - -.. list-table:: Bitfields of type field - :header-rows: 1 - - * - Bits - - Meaning - * - 0 - - Packet/stream indicator, 0=packet, 1=stream - * - 1..2 - - Data type indicator, :math:`01_2` =data (D), :math:`10_2` =voice - (V), :math:`11_2` =V+D, :math:`00_2` =reserved - * - 3..4 - - Encryption type, :math:`00_2` =none, :math:`01_2` =AES, - :math:`10_2` =scrambling, :math:`11_2` =other/reserved - * - 5..6 - - Encryption subtype (meaning of values depends on encryption type) - * - 7..10 - - Channel Access Number (CAN) - * - 11..15 - - Reserved (don't care) - -The fields in Table 3 (except TAIL) form initial LSF. It contains all -information needed to establish M17 link. Later in the transmission, -the initial LSF is divided into 6 "chunks" and transmitted -beside the payload data. This allows late-joiners to -reconstruct the LICH after collecting all the pieces, and start decoding -the stream even though they missed the beginning of the transmission. -The process of collecting full LSF takes 6 frames or 6*40 ms = 240 -ms. Four TAIL bits are needed for the convolutional coder to go back to -state 0, so the ending trellis position is also known. - -Voice coder rate is inferred from TYPE field, bits 1 and 2. - -.. list-table:: Voice coder rates for different data type indicators - :header-rows: 1 - - * - Data type indicator - - Voice coder rate - * - :math:`00_2` - - none/reserved - * - :math:`01_2` - - no voice - * - :math:`10_2` - - 3200 bps - * - :math:`11_2` - - 1600 bps - -Subsequent frames -~~~~~~~~~~~~~~~~~ - -.. list-table:: Fields for frames other than the link setup frame - - * - LICH - - 48 bits - - LSF chunk, one of 6 - * - FN - - 16 bits - - Frame number, starts from 0 and increments every frame to a max of 0x7fff where it will then wrap back to 0. High bit set indicates this frame is the last of the stream. - * - PAYLOAD - - 128 bits - - Payload/data, can contain arbitrary data - * - TAIL - - 4 bits - - Flushing bits for the convolutional encoder that don't carry any information - -The most significant bit in the FN counter is used for transmission -end signalling. When transmitting the last frame, it shall be set to 1 -(one), and 0 (zero) in all other frames. - -The payload is used so that earlier data in the voice stream is sent first. -For mixed voice and data payloads, the voice data is stored first, then the data. - -.. list-table:: LSF chunk structure - :header-rows: 1 - - * - Bits - - Content - * - 0..39 - - 40 bits of full LSF - * - 40..42 - - A modulo 6 counter (LICH_CNT) for LSF re-assembly - * - 43..47 - - Reserved - -.. table:: Payload example 1 - - +-------------------------------+---------------+---------------+ - | Codec2 encoded frame t + 0 | Codec2 encoded frame t + 1 | - +---------------+---------------+---------------+---------------+ - -.. table:: Payload Example 2 - - +-------------------------------+---------------+---------------+ - | Codec2 encoded frame t + 0 | Mixed data t + 0 | - +---------------+---------------+---------------+---------------+ - -Superframes -~~~~~~~~~~~ - -Each frame contains a chunk of the LSF frame that was used to -establish the stream. Frames are grouped into 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:: ../images/M17_stream.png - - Stream consisting of one superframe - -.. graphviz:: - :caption: An overview of the forward dataflow - - digraph D{ - size="4,6"; - node [shape=record]; - {rank=same c0 c1 golay_24_12} - {rank=same p0 p1} - {rank=same i0 i1} - - c0[label="conv. coder"] - p0[label="P_1 puncturer"] - i0[label="interleaver"] - w0[label="decorrelator"] - s0[label="prepend LSF_SYNC"] - l0[label="LICH combiner"] - chunker_40[label="chunk 40 bits"] - golay_24_12[label="Golay (24, 12)"] - - c1[label="conv. coder"] - p1[label="P_2 puncturer"] - i1[label="interleaver"] - w1[label="decorrelator"] - s1[label="prepend FRAME_SYNC"] - fn[label="add FN"] - chunker_128[label="chunk 128 bits"] - - framecomb[label="Frame Combiner"] - supercomb[label="Superframe Combiner"] - - counter -> l0 - LSF -> c0 -> p0 -> i0 -> w0 -> s0 -> supercomb - LSF -> chunker_40 -> l0 -> golay_24_12 -> framecomb - data -> chunker_128 -> fn -> c1 -> p1 -> framecomb - framecomb -> i1 -> w1 -> s1 -> supercomb - preamble -> supercomb - } - -CRC -~~~ - -M17 uses a non-standard version of 16-bit CRC with polynomial -:math:`x^{16} + x^{14} + x^{12} + x^{11} + x^8 + x^5 + x^4 + x^2 + 1` or -0x5935 and initial value of 0xFFFF. This polynomial allows for -detecting all errors up to hamming distance of 5 with payloads up to -241 bits [#koopman]_, which is less than the amount of data in each frame. - -.. [#koopman] https://users.ece.cmu.edu/~koopman/crc/ has this listed - as 0xAC9A, which is the reversed reciprocal notation - -As M17’s native bit order is most significant bit first, neither the -input nor the output of the CRC algorithm gets reflected. - -The input to the CRC algorithm consists of DST, SRC (each 48 bits), 16 bits of TYPE field and 112 -bits META, and then depending on whether the CRC is being computed -or verified either 16 zero bits or the received CRC. - -The test vectors in Table 6 are calculated by feeding the given -message and then 16 zero bits to the CRC algorithm. - -.. list-table:: CRC test vectors - :header-rows: 1 - - * - Message - - CRC output - * - (empty string) - - 0xFFFF - * - ASCII string "A" - - 0x206E - * - ASCII string "123456789" - - 0x772B - * - Bytes from 0x00 to 0xFF - - 0x1C31 - -Packet Mode ------------ - -In *packet mode*, a finite amount of payload data (for example – text -messages or application layer data) is wrapped with a packet, sent -over the physical layer, and is completed when done. ~~Any -acknowledgement or retransmission is done at the application -layer.~~ - -Link Setup Frame -~~~~~~~~~~~~~~~~ - -Packet mode uses the same link setup frame that has been defined for stream mode above. -The packet/stream indicator is set to 0 in the type field. - -.. list-table:: Bitfields of type field - :header-rows: 1 - - * - Bits - - Meaning - * - 0 - - Packet/stream indicator, 0=packet, 1=stream - * - 1..2 - - Data type indicator, :math:`01_2` =data (D), :math:`10_2` =voice - (V), :math:`11_2` =V+D, :math:`00_2` =reserved - * - 3..4 - - Encryption type, :math:`00_2` =none, :math:`01_2` =AES, - :math:`10_2` =scrambling, :math:`11_2` =other/reserved - * - 5..6 - - Encryption subtype (meaning of values depends on encryption type) - * - 7..10 - - Channel Access Number (CAN) - * - 11..15 - - Reserved (don't care) - -Raw packet frames have no packet type metadata associated with them. Encapsulated packet -format is discussed in :ref:`packet-superframes` in the Application Layer section. This -provides data type information and is the preferred format for use on M17. - -When encryption type is :math:`00_2`, meaning no encryption, the -encryption subtype bits are used to indicate the contents of the -META field in the LSF. Since that space would otherwise go be unused, -we can store small bits of data in that field such as free text or the -sender's GNSS position. - -Encryption type and subtype bits, including the plaintext data formats -when not using encryption, are described in more detail in the Application -Layer section of this document. - -Currently the contents of the source and destination fields are arbitrary as no behavior -is defined which depends on the content of these fields. The only requirement is that -the content is base-40 encoded. - -Packet Format -~~~~~~~~~~~~~ - -M17 packet mode can transmit up to 798 bytes of payload data. It acheives a base throughput -of 5kbps, and a net throughput of about 4.7kbps for the largest data payload, and over 3kbps -for 100-byte payloads. (Net throughput takes into account preamble and link setup overhead.) - -The packet superframe consists of 798 payload data bytes and a 2-byte CCITT CRC-16 checksum. - -.. list-table:: Byte fields of packet superframe - :header-rows: 1 - - * - Bytes - - Meaning - * - 1-798 - - Packet payload - * - 2 - - CCITT CRC-16 - - -Packet data is split into frames of 368 type 4 bits preceded by a packet-specific 16-bit sync -word (0xFF5D). This is the same size frame used by stream mode. - -The packet frame starts with a 210 bit frame of type 1 data. It is noteworthy that it does -not terminate on a byte boundary. - -The frame has 200 bits (25 bytes) of payload data, 6 bits of frame metadata, and 4 bits to -flush the convolutional coder. - -.. list-table:: Bit fields of packet frame - :header-rows: 1 - - * - Bits - - Meaning - * - 0-199 - - Packet payload - * - 1 - - EOF indicator - * - 5 - - Frame/byte count - * - 4 - - Flush bits for convolutional coder - - -The metadata field contains a 1 bit **end of frame** (**EOF**) indicator, and a 5-bit frame/byte counter. - -The **EOF** bit is 1 only on the last frame. The **counter** field is used to indicate the frame number -when **EOF** is 0, and the number of bytes in the last frame when **EOF** is 1. This encodes the -exact packet size, up to 800 bytes, in a 6-bit field. - -.. list-table:: Metadata field with EOF = 0 - :header-rows: 1 - - * - Bits - - Meaning - * - 0 - - Set to 0, Not end of frame - * - 1-5 - - Frame number, 0..31 - -.. list-table:: Metadata field with EOF = 1 - :header-rows: 1 - - * - Bits - - Meaning - * - 0 - - Set to 1, End of frame - * - 1-5 - - Number of bytes in frame, 1..25 - -Note that it is non-conforming to send a last frame with a length of 0 bytes. - -Convolutional Coding -~~~~~~~~~~~~~~~~~~~~ - -The entire frame is convolutionally coded, giving 420 bits of type 2 data. It is then punctured using -a 7/8 puncture matrix (1,1,1,1,1,1,1,0) to give 368 type 3 bits. These are then interleaved and -decorrelated to give 368 type 4 bits. - -.. list-table:: Packet frame - :header-rows: 1 - - * - Bits - - Meaning - * - 16 bits - - Sync word 0xFF5D - * - 368 bits - - Payload - - -Carrier-sense Multiple Access -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When sending packets, the sender is reponsible for ensuring the channel is clear before transmitting. -`CSMA `_ is used to minimize collisions on -a shared network. Specifically, P-persistent access is used. Each time slot is 40ms (one packet length) -and the probability SHOULD default to 25%. In terms of the values used by the KISS protocol, these -equate to a slot time of 4 and a P-persistence value of 63. - -The benefit of this method is that it imposes no penalty on uncontested networks. - diff --git a/docs/decorrelator.md b/docs/decorrelator.md new file mode 100644 index 0000000..09d7d9c --- /dev/null +++ b/docs/decorrelator.md @@ -0,0 +1,27 @@ +# Decorrelator Sequence + +Seq. number | Value | Seq. number | Value +----------- | ----- | ----------- | ----- +00 | 0xD6 | 23 | 0x6E +01 | 0xB5 | 24 | 0x68 +02 | 0xE2 | 25 | 0x2F +03 | 0x30 | 26 | 0x35 +04 | 0x82 | 27 | 0xDA +05 | 0xFF | 28 | 0x14 +06 | 0x84 | 29 | 0xEA +07 | 0x62 | 30 | 0xCD +08 | 0xBA | 31 | 0x76 +09 | 0x4E | 32 | 0x19 +10 | 0x96 | 33 | 0x8D +11 | 0x90 | 34 | 0xD5 +12 | 0xD8 | 35 | 0x80 +13 | 0x98 | 36 | 0xD1 +14 | 0xDD | 37 | 0x33 +15 | 0x5D | 38 | 0x87 +16 | 0x0C | 39 | 0x13 +17 | 0xC8 | 40 | 0x57 +18 | 0x52 | 41 | 0x18 +19 | 0x43 | 42 | 0x2D +20 | 0x91 | 43 | 0x29 +21 | 0x1D | 44 | 0x78 +22 | 0xF8 | 45 | 0xC3 \ No newline at end of file diff --git a/docs/decorrelator.rst b/docs/decorrelator.rst deleted file mode 100644 index 902608f..0000000 --- a/docs/decorrelator.rst +++ /dev/null @@ -1,32 +0,0 @@ -Decorrelator sequence -===================== - -.. _sec-decorr-seq: - -.. csv-table:: Decorrelator scrambling sequence - :header-rows: 1 - - Seq. number, Value, Seq. number, Value - 00, 0xD6, 23, 0x6E - 01, 0xB5, 24, 0x68 - 02, 0xE2, 25, 0x2F - 03, 0x30, 26, 0x35 - 04, 0x82, 27, 0xDA - 05, 0xFF, 28, 0x14 - 06, 0x84, 29, 0xEA - 07, 0x62, 30, 0xCD - 08, 0xBA, 31, 0x76 - 09, 0x4E, 32, 0x19 - 10, 0x96, 33, 0x8D - 11, 0x90, 34, 0xD5 - 12, 0xD8, 35, 0x80 - 13, 0x98, 36, 0xD1 - 14, 0xDD, 37, 0x33 - 15, 0x5D, 38, 0x87 - 16, 0x0C, 39, 0x13 - 17, 0xC8, 40, 0x57 - 18, 0x52, 41, 0x18 - 19, 0x43, 42, 0x2D - 20, 0x91, 43, 0x29 - 21, 0x1D, 44, 0x78 - 22, 0xF8, 45, 0xC3 diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 0000000..c00641f --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,22 @@ +# Glossary + +#### ECC +Error Correcting Code + +#### FEC +Forward Error Correction + +#### Frame +The individual components of a stream, each of which contains payload data interleaved with frame signalling. + +#### Link Information Frame +The first frame of any transmission. It contains full LICH data. + +#### LICH +Link Information Channel. The LICH contains all information needed to establish an M17 link. The first frame of a transmission contains full LICH data, and subsequent frames each contain one sixth of the LICH data so that late-joiners can obtain the LICH. + +#### Packet +A single burst of transmitted data containing 100s to 1000s of bytes, after which the physical layer stops sending data. + +#### Superframe +A set of six consecutive frames which collectively contain full LICH data are grouped into a superframe. \ No newline at end of file diff --git a/docs/glossary.rst b/docs/glossary.rst deleted file mode 100644 index 8a98e8f..0000000 --- a/docs/glossary.rst +++ /dev/null @@ -1,25 +0,0 @@ -Glossary -======== - -.. glossary:: - - ECC - Error Correcting Code - - FEC - Forward Error Correction - - Frame - The individual components of a stream, each of which contains payload data interleaved with frame signalling. - - Link Information Frame - The first frame of any transmission. It contains full LICH data. - - LICH - Link Information Channel. The LICH contains all information needed to establish an M17 link. The first frame of a transmission contains full LICH data, and subsequent frames each contain one sixth of the LICH data so that late-joiners can obtain the LICH. - - Packet - A single burst of transmitted data containing 100s to 1000s of bytes, after which the physical layer stops sending data. - - Superframe - A set of six consecutive frames which collectively contain full LICH data are grouped into a superframe. diff --git a/images/LFSR_16.svg b/docs/img/LFSR_16.svg similarity index 100% rename from images/LFSR_16.svg rename to docs/img/LFSR_16.svg diff --git a/images/LFSR_24.svg b/docs/img/LFSR_24.svg similarity index 100% rename from images/LFSR_24.svg rename to docs/img/LFSR_24.svg diff --git a/images/LFSR_8.svg b/docs/img/LFSR_8.svg similarity index 100% rename from images/LFSR_8.svg rename to docs/img/LFSR_8.svg diff --git a/images/M17_stream.png b/docs/img/M17_stream.png similarity index 100% rename from images/M17_stream.png rename to docs/img/M17_stream.png diff --git a/images/convolutional.svg b/docs/img/convolutional.svg similarity index 100% rename from images/convolutional.svg rename to docs/img/convolutional.svg diff --git a/images/frame_encoding.svg b/docs/img/frame_encoding.svg similarity index 100% rename from images/frame_encoding.svg rename to docs/img/frame_encoding.svg diff --git a/images/link_setup_frame_encoding.svg b/docs/img/link_setup_frame_encoding.svg similarity index 100% rename from images/link_setup_frame_encoding.svg rename to docs/img/link_setup_frame_encoding.svg diff --git a/images/m17_logo_shadow.svg b/docs/img/m17_logo_shadow.svg similarity index 100% rename from images/m17_logo_shadow.svg rename to docs/img/m17_logo_shadow.svg diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..1757b71 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,43 @@ +# Welcome to the M17 Protocol Specification + +Edit these docs at [GitHub](https://github.com/M17-Project/m17-specification). + +## [Part I - Air and IP Interface](partI.md) +* [M17 RF Protocol: Summary](summary.md) +* [Glossary](glossary.md) +* [Physical Layer](physical_layer.md) + * [4FSK generation](physical_layer.md#4fsk-generation) + * [Preamble](physical_layer.md#preamble) + * [Bit types](physical_layer.md#bit-types) + * [Error correction coding schemes and bit type conversion](physical_layer.md#error-correction-coding-schemes-and-bit-type-conversion) +* [Data Link Layer](data_link_layer.md) + * [Stream Mode](data_link_layer.md#stream-mode) + * [Packet Mode](data_link_layer.md#packet-mode) +* [Application Layer](application_layer.md) + * [Packet Superframes](application_layer.md#packet-superframes) + * [Encryption Types](application_layer.md#encryption-types) + +## [Part II - Codeplug](partII.md) +* [Recommendation for the codeplug structure](codeplug.md#recommendation-for-the-codeplug-structure) + * [Introduction](codeplug.md#introduction) + * [Codeplug file structure](codeplug.md#codeplug-file-structure) + * [Example Codeplug](codeplug.md#example-codeplug) + +## [Appendix](appendix.md) +* [Address Encoding](address_encoding.md) + * [Callsign Encoding: base40](address_encoding.md#callsign-encoding-base40) + * [Callsign Formats](address_encoding.md#callsign-formats) +* [Decorrelator sequence](decorrelator.md) +* [Interleaving](interleaving.md) +* [M17 Internet Protocol (IP) Networking](ip_networking.md) + * [Standard IP Framing](ip_networking.md#standard-ip-framing) + * [Control Packets](ip_networking.md#control-packets) +* [KISS Protocol](kiss_protocol.md) + * [References](kiss_protocol.md#references) + * [Glossary](kiss_protocol.md#glossary) + * [M17 Protocols](kiss_protocol.md#m17-protocols) + * [KISS Basics](kiss_protocol.md#kiss-basics) + * [Packet Protocols](kiss_protocol.md#packet-protocols) + * [Stream Protocol](kiss_protocol.md#stream-protocol) + * [Mixing Modes](kiss_protocol.md#mixing-modes) + * [Implementation Details](kiss_protocol.md#implementation-details) diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index f5f255e..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,33 +0,0 @@ -M17 Protocol Specification -========================== - -.. toctree:: - :maxdepth: 2 - :caption: Part I - Air and IP Interface: - - summary - glossary - physical_layer - data_link_layer - application_layer - -.. toctree:: - :maxdepth: 2 - :caption: Part II - Codeplug: - - codeplug - -.. raw:: latex - - \appendix - -.. toctree:: - :maxdepth: 2 - :caption: Appendix: - - address_encoding - decorrelator - interleaving - ip_encapsulation - kiss_protocol - diff --git a/docs/indexPartI.rst b/docs/indexPartI.rst deleted file mode 100644 index 0c50a4f..0000000 --- a/docs/indexPartI.rst +++ /dev/null @@ -1,26 +0,0 @@ -M17 Protocol Specification -========================== - -.. toctree:: - :maxdepth: 2 - :caption: Part I - Air and IP Interface: - - summary - glossary - physical_layer - data_link_layer - application_layer - -.. raw:: latex - - \appendix - -.. toctree:: - :maxdepth: 2 - :caption: Appendix: - - address_encoding - decorrelator - interleaving - ip_encapsulation - kiss_protocol diff --git a/docs/indexPartII.rst b/docs/indexPartII.rst deleted file mode 100644 index fde7c9e..0000000 --- a/docs/indexPartII.rst +++ /dev/null @@ -1,8 +0,0 @@ -M17 Protocol Codeplug -===================== - -.. toctree:: - :maxdepth: 2 - :caption: Part II - Codeplug: - - codeplug diff --git a/docs/interleaving.md b/docs/interleaving.md new file mode 100644 index 0000000..c859419 --- /dev/null +++ b/docs/interleaving.md @@ -0,0 +1,96 @@ +# Interleaving + +input index | output ind | input index | output ind | input index | output ind | input index | output ind +----------- | ---------- | ----------- | ---------- | ----------- | ---------- | ----------- | ---------- +0 | 0 | 92 | 92 | 184 | 184 | 276 | 276 +1 | 137 | 93 | 229 | 185 | 321 | 277 | 45 +2 | 90 | 94 | 182 | 186 | 274 | 278 | 366 +3 | 227 | 95 | 319 | 187 | 43 | 279 | 135 +4 | 180 | 96 | 272 | 188 | 364 | 280 | 88 +5 | 317 | 97 | 41 | 189 | 133 | 281 | 225 +6 | 270 | 98 | 362 | 190 | 86 | 282 | 178 +7 | 39 | 99 | 131 | 191 | 223 | 283 | 315 +8 | 360 | 100 | 84 | 192 | 176 | 284 | 268 +9 | 129 | 101 | 221 | 193 | 313 | 285 | 37 +10 | 82 | 102 | 174 | 194 | 266 | 286 | 358 +11 | 219 | 103 | 311 | 195 | 35 | 287 | 127 +12 | 172 | 104 | 264 | 196 | 356 | 288 | 80 +13 | 309 | 105 | 33 | 197 | 125 | 289 | 217 +14 | 262 | 106 | 354 | 198 | 78 | 290 | 170 +15 | 31 | 107 | 123 | 199 | 215 | 291 | 307 +16 | 352 | 108 | 76 | 200 | 168 | 292 | 260 +17 | 121 | 109 | 213 | 201 | 305 | 293 | 29 +18 | 74 | 110 | 166 | 202 | 258 | 294 | 350 +19 | 211 | 111 | 303 | 203 | 27 | 295 | 119 +20 | 164 | 112 | 256 | 204 | 348 | 296 | 72 +21 | 301 | 113 | 25 | 205 | 117 | 297 | 209 +22 | 254 | 114 | 346 | 206 | 70 | 298 | 162 +23 | 23 | 115 | 115 | 207 | 207 | 299 | 299 +24 | 344 | 116 | 68 | 208 | 160 | 300 | 252 +25 | 113 | 117 | 205 | 209 | 297 | 301 | 21 +26 | 66 | 118 | 158 | 210 | 250 | 302 | 342 +27 | 203 | 119 | 295 | 211 | 19 | 303 | 111 +28 | 156 | 120 | 248 | 212 | 340 | 304 | 64 +29 | 293 | 121 | 17 | 213 | 109 | 305 | 201 +30 | 246 | 122 | 338 | 214 | 62 | 306 | 154 +31 | 15 | 123 | 107 | 215 | 199 | 307 | 291 +32 | 336 | 124 | 60 | 216 | 152 | 308 | 244 +33 | 105 | 125 | 197 | 217 | 289 | 309 | 13 +34 | 58 | 126 | 150 | 218 | 242 | 310 | 334 +35 | 195 | 127 | 287 | 219 | 11 | 311 | 103 +36 | 148 | 128 | 240 | 220 | 332 | 312 | 56 +37 | 285 | 129 | 9 | 221 | 101 | 313 | 193 +38 | 238 | 130 | 330 | 222 | 54 | 314 | 146 +39 | 7 | 131 | 99 | 223 | 191 | 315 | 283 +40 | 328 | 132 | 52 | 224 | 144 | 316 | 236 +41 | 97 | 133 | 189 | 225 | 281 | 317 | 5 +42 | 50 | 134 | 142 | 226 | 234 | 318 | 326 +43 | 187 | 135 | 279 | 227 | 3 | 319 | 95 +44 | 140 | 136 | 232 | 228 | 324 | 320 | 48 +45 | 277 | 137 | 1 | 229 | 93 | 321 | 185 +46 | 230 | 138 | 322 | 230 | 46 | 322 | 138 +47 | 367 | 139 | 91 | 231 | 183 | 323 | 275 +48 | 320 | 140 | 44 | 232 | 136 | 324 | 228 +49 | 89 | 141 | 181 | 233 | 273 | 325 | 365 +50 | 42 | 142 | 134 | 234 | 226 | 326 | 318 +51 | 179 | 143 | 271 | 235 | 363 | 327 | 87 +52 | 132 | 144 | 224 | 236 | 316 | 328 | 40 +53 | 269 | 145 | 361 | 237 | 85 | 329 | 177 +54 | 222 | 146 | 314 | 238 | 38 | 330 | 130 +55 | 359 | 147 | 83 | 239 | 175 | 331 | 267 +56 | 312 | 148 | 36 | 240 | 128 | 332 | 220 +57 | 81 | 149 | 173 | 241 | 265 | 333 | 357 +58 | 34 | 150 | 126 | 242 | 218 | 334 | 310 +59 | 171 | 151 | 263 | 243 | 355 | 335 | 79 +60 | 124 | 152 | 216 | 244 | 308 | 336 | 32 +61 | 261 | 153 | 353 | 245 | 77 | 337 | 169 +62 | 214 | 154 | 306 | 246 | 30 | 338 | 122 +63 | 351 | 155 | 75 | 247 | 167 | 339 | 259 +64 | 304 | 156 | 28 | 248 | 120 | 340 | 212 +65 | 73 | 157 | 165 | 249 | 257 | 341 | 349 +66 | 26 | 158 | 118 | 250 | 210 | 342 | 302 +67 | 163 | 159 | 255 | 251 | 347 | 343 | 71 +68 | 116 | 160 | 208 | 252 | 300 | 344 | 24 +69 | 253 | 161 | 345 | 253 | 69 | 345 | 161 +70 | 206 | 162 | 298 | 254 | 22 | 346 | 114 +71 | 343 | 163 | 67 | 255 | 159 | 347 | 251 +72 | 296 | 164 | 20 | 256 | 112 | 348 | 204 +73 | 65 | 165 | 157 | 257 | 249 | 349 | 341 +74 | 18 | 166 | 110 | 258 | 202 | 350 | 294 +75 | 155 | 167 | 247 | 259 | 339 | 351 | 63 +76 | 108 | 168 | 200 | 260 | 292 | 352 | 16 +77 | 245 | 169 | 337 | 261 | 61 | 353 | 153 +78 | 198 | 170 | 290 | 262 | 14 | 354 | 106 +79 | 335 | 171 | 59 | 263 | 151 | 355 | 243 +80 | 288 | 172 | 12 | 264 | 104 | 356 | 196 +81 | 57 | 173 | 149 | 265 | 241 | 357 | 333 +82 | 10 | 174 | 102 | 266 | 194 | 358 | 286 +83 | 147 | 175 | 239 | 267 | 331 | 359 | 55 +84 | 100 | 176 | 192 | 268 | 284 | 360 | 8 +85 | 237 | 177 | 329 | 269 | 53 | 361 | 145 +86 | 190 | 178 | 282 | 270 | 6 | 362 | 98 +87 | 327 | 179 | 51 | 271 | 143 | 363 | 235 +88 | 280 | 180 | 4 | 272 | 96 | 364 | 188 +89 | 49 | 181 | 141 | 273 | 233 | 365 | 325 +90 | 2 | 182 | 94 | 274 | 186 | 366 | 278 +91 | 139 | 183 | 231 | 275 | 323 | 367 | 47 \ No newline at end of file diff --git a/docs/interleaving.rst b/docs/interleaving.rst deleted file mode 100644 index d54577b..0000000 --- a/docs/interleaving.rst +++ /dev/null @@ -1,101 +0,0 @@ -Interleaving -============ - -.. _sec-interleaver: - -.. csv-table:: Interleaving table - :header-rows: 1 - - input index, output ind, input index, output ind, input index, output ind, input index, output ind - 0, 0, 92, 92, 184, 184, 276, 276 - 1, 137, 93, 229, 185, 321, 277, 45 - 2, 90, 94, 182, 186, 274, 278, 366 - 3, 227, 95, 319, 187, 43, 279, 135 - 4, 180, 96, 272, 188, 364, 280, 88 - 5, 317, 97, 41, 189, 133, 281, 225 - 6, 270, 98, 362, 190, 86, 282, 178 - 7, 39, 99, 131, 191, 223, 283, 315 - 8, 360, 100, 84, 192, 176, 284, 268 - 9, 129, 101, 221, 193, 313, 285, 37 - 10, 82, 102, 174, 194, 266, 286, 358 - 11, 219, 103, 311, 195, 35, 287, 127 - 12, 172, 104, 264, 196, 356, 288, 80 - 13, 309, 105, 33, 197, 125, 289, 217 - 14, 262, 106, 354, 198, 78, 290, 170 - 15, 31, 107, 123, 199, 215, 291, 307 - 16, 352, 108, 76, 200, 168, 292, 260 - 17, 121, 109, 213, 201, 305, 293, 29 - 18, 74, 110, 166, 202, 258, 294, 350 - 19, 211, 111, 303, 203, 27, 295, 119 - 20, 164, 112, 256, 204, 348, 296, 72 - 21, 301, 113, 25, 205, 117, 297, 209 - 22, 254, 114, 346, 206, 70, 298, 162 - 23, 23, 115, 115, 207, 207, 299, 299 - 24, 344, 116, 68, 208, 160, 300, 252 - 25, 113, 117, 205, 209, 297, 301, 21 - 26, 66, 118, 158, 210, 250, 302, 342 - 27, 203, 119, 295, 211, 19, 303, 111 - 28, 156, 120, 248, 212, 340, 304, 64 - 29, 293, 121, 17, 213, 109, 305, 201 - 30, 246, 122, 338, 214, 62, 306, 154 - 31, 15, 123, 107, 215, 199, 307, 291 - 32, 336, 124, 60, 216, 152, 308, 244 - 33, 105, 125, 197, 217, 289, 309, 13 - 34, 58, 126, 150, 218, 242, 310, 334 - 35, 195, 127, 287, 219, 11, 311, 103 - 36, 148, 128, 240, 220, 332, 312, 56 - 37, 285, 129, 9, 221, 101, 313, 193 - 38, 238, 130, 330, 222, 54, 314, 146 - 39, 7, 131, 99, 223, 191, 315, 283 - 40, 328, 132, 52, 224, 144, 316, 236 - 41, 97, 133, 189, 225, 281, 317, 5 - 42, 50, 134, 142, 226, 234, 318, 326 - 43, 187, 135, 279, 227, 3, 319, 95 - 44, 140, 136, 232, 228, 324, 320, 48 - 45, 277, 137, 1, 229, 93, 321, 185 - 46, 230, 138, 322, 230, 46, 322, 138 - 47, 367, 139, 91, 231, 183, 323, 275 - 48, 320, 140, 44, 232, 136, 324, 228 - 49, 89, 141, 181, 233, 273, 325, 365 - 50, 42, 142, 134, 234, 226, 326, 318 - 51, 179, 143, 271, 235, 363, 327, 87 - 52, 132, 144, 224, 236, 316, 328, 40 - 53, 269, 145, 361, 237, 85, 329, 177 - 54, 222, 146, 314, 238, 38, 330, 130 - 55, 359, 147, 83, 239, 175, 331, 267 - 56, 312, 148, 36, 240, 128, 332, 220 - 57, 81, 149, 173, 241, 265, 333, 357 - 58, 34, 150, 126, 242, 218, 334, 310 - 59, 171, 151, 263, 243, 355, 335, 79 - 60, 124, 152, 216, 244, 308, 336, 32 - 61, 261, 153, 353, 245, 77, 337, 169 - 62, 214, 154, 306, 246, 30, 338, 122 - 63, 351, 155, 75, 247, 167, 339, 259 - 64, 304, 156, 28, 248, 120, 340, 212 - 65, 73, 157, 165, 249, 257, 341, 349 - 66, 26, 158, 118, 250, 210, 342, 302 - 67, 163, 159, 255, 251, 347, 343, 71 - 68, 116, 160, 208, 252, 300, 344, 24 - 69, 253, 161, 345, 253, 69, 345, 161 - 70, 206, 162, 298, 254, 22, 346, 114 - 71, 343, 163, 67, 255, 159, 347, 251 - 72, 296, 164, 20, 256, 112, 348, 204 - 73, 65, 165, 157, 257, 249, 349, 341 - 74, 18, 166, 110, 258, 202, 350, 294 - 75, 155, 167, 247, 259, 339, 351, 63 - 76, 108, 168, 200, 260, 292, 352, 16 - 77, 245, 169, 337, 261, 61, 353, 153 - 78, 198, 170, 290, 262, 14, 354, 106 - 79, 335, 171, 59, 263, 151, 355, 243 - 80, 288, 172, 12, 264, 104, 356, 196 - 81, 57, 173, 149, 265, 241, 357, 333 - 82, 10, 174, 102, 266, 194, 358, 286 - 83, 147, 175, 239, 267, 331, 359, 55 - 84, 100, 176, 192, 268, 284, 360, 8 - 85, 237, 177, 329, 269, 53, 361, 145 - 86, 190, 178, 282, 270, 6, 362, 98 - 87, 327, 179, 51, 271, 143, 363, 235 - 88, 280, 180, 4, 272, 96, 364, 188 - 89, 49, 181, 141, 273, 233, 365, 325 - 90, 2, 182, 94, 274, 186, 366, 278 - 91, 139, 183, 231, 275, 323, 367, 47 diff --git a/docs/ip_encapsulation.rst b/docs/ip_encapsulation.rst deleted file mode 100644 index 784adc0..0000000 --- a/docs/ip_encapsulation.rst +++ /dev/null @@ -1,159 +0,0 @@ -M17 Internet Protocol (IP) Networking -===================================== - -Digital modes are commonly networked together through linked repeaters using IP networking. - -For commercial protocols like DMR, this is meant for linking metropolitan -and state networks together and allows for easy interoperability between -radio users. -Amateur Radio uses this capability for creating global communications -networks for all imaginable purposes, and makes 'working the world' with -an HT possible. - -M17 is designed with this use in mind, and has native IP framing to support it. - -In competing radio protocols, a repeater or some other RF to IP bridge -is required for linking, leading to the use of hotspots (tiny simplex -RF bridges). - -The TR-9 and other M17 radios may support IP networking directly, such -as through the ubiquitous ESP8266 chip or similar. This allows them to -skip the RF link that current hotspot systems require, finally bringing -to fruition the "Amateur digital radio is just VoIP" dystopian future -we were all warned about. - - -Standard IP Framing -------------------- - -M17 over IP is big endian, consistent with other IP protocols. -We have standardized on UDP port 17000, this port is recommended but not required. -Later specifications may require this port. - -.. list-table:: Internet frame fields - - * - MAGIC - - 32 bits - - Magic bytes 0x4d313720 ("M17 ") - * - StreamID (SID) - - 16 bits - - Random bits, changed for each PTT or stream, but consistent from frame to frame within a stream - * - LICH - - 240 bits - - The meaningful contents of a LICH frame (dst, src, streamtype, META field, CRC16) as defined earlier. - * - FN - - 16 bits - - Frame number (exactly as would be transmitted as an RF stream frame, including the last frame indicator at (FN & 0x8000) - * - Payload - - 128 bits - - Payload (exactly as would be transmitted in an RF stream frame) - * - CRC16 - - 16 bits - - CRC for the entire packet, as defined earlier (TODO: specific link) - - -The CRC checksum must be recomputed after modification or re-assembly -of the packet, such as when translating from RF to IP framing. - -.. todo:: RF->IP & IP->RF bridging reassembly, UDP NAT punching, callsign routing lookup - -.. points_of_contact N7TAE, W2FBI - -Control Packets ----------------------- - -Reflectors use a few different types of control frames, identified by their magic: - -* *CONN* - Connect to a reflector -* *ACKN* - acknowledge connection -* *NACK* - deny connection -* *PING* - keepalive for the connection from the reflector to the client -* *PONG* - keepalive response from the client to the reflector -* *DISC* - Disconnect (client->reflector or reflector->client) - -CONN -~~~~~~~~~~~~~~~ - -.. table :: Bytes of a CONN packet - - +-------+----------------------------------------------------------------------------------------------------------------+ - | Bytes | Purpose | - +=======+================================================================================================================+ - | 0-3 | Magic - ASCII "CONN" | - +-------+----------------------------------------------------------------------------------------------------------------+ - | 4-9 | 6-byte 'From' callsign including module in last character (e.g. "A1BCD D") encoded as per `Address Encoding` | - +-------+----------------------------------------------------------------------------------------------------------------+ - | 10 | Module to connect to - single ASCII byte A-Z | - +-------+----------------------------------------------------------------------------------------------------------------+ - -.. todo:: it would ne nice to include the destination callsign in full rather than just the module - it's only an extra 5 bytes, and it would allow hosting multiple reflectors on one instance and maybe some other use cases where you want to be explicit about what you're connecting to - -A client sends this to a reflector to initiate a connection. The reflector replies with ACKN on successful linking, or NACK on failure. - -ACKN -~~~~~~~~~~~~~~~~~ - -.. table :: Bytes of ACKN packet - - +-------+----------------------------------------------------------------------------------------------------------------+ - | Bytes | Purpose | - +=======+================================================================================================================+ - | 0-3 | Magic - ASCII "ACKN" | - +-------+----------------------------------------------------------------------------------------------------------------+ - -.. todo:: Originally this was defined as having the callsign including module encodes as per 'Address Encoding' simular to the CONN frame, while current implementations of the client do not accept packets with that, it may be go to eventually re-work this to once again include that field. - -NACK -~~~~~~~~~~~~~~~~~ - -.. table :: Bytes of NACK packet - - +-------+--------------------------------------------------------------------------------------------------------------------------+ - | Bytes | Purpose | - +=======+==========================================================================================================================+ - | 0-3 | Magic - ASCII "NACK" | - +-------+--------------------------------------------------------------------------------------------------------------------------+ - -PING -~~~~~~~~~~~~~~~~~ - -.. table :: Bytes of PING packet - - +-------+----------------------------------------------------------------------------------------------------------------+ - | Bytes | Purpose | - +=======+================================================================================================================+ - | 0-3 | Magic - ASCII "PING" | - +-------+----------------------------------------------------------------------------------------------------------------+ - | 4-9 | 6-byte 'From' callsign including module in last character (e.g. "A1BCD D") encoded as per `Address Encoding` | - +-------+----------------------------------------------------------------------------------------------------------------+ - -Upon receivng a PING from a reflector, the client replies with a PONG - -PONG -~~~~~~~~~~~~~~~~~ - -.. table :: Bytes of PONG packet - - +-------+----------------------------------------------------------------------------------------------------------------+ - | Bytes | Purpose | - +=======+================================================================================================================+ - | 0-3 | Magic - ASCII "PONG" | - +-------+----------------------------------------------------------------------------------------------------------------+ - | 4-9 | 6-byte 'From' callsign including module in last character (e.g. "A1BCD D") encoded as per `Address Encoding` | - +-------+----------------------------------------------------------------------------------------------------------------+ - - -DISC -~~~~~~~~~~~~~~~~~ - -.. table :: Bytes of DISC packet - - +-------+----------------------------------------------------------------------------------------------------------------+ - | Bytes | Purpose | - +=======+================================================================================================================+ - | 0-3 | Magic - ASCII "DISC" | - +-------+----------------------------------------------------------------------------------------------------------------+ - | 4-9 | 6-byte 'From' callsign including module in last character (e.g. "A1BCD D") encoded as per `Address Encoding` | - +-------+----------------------------------------------------------------------------------------------------------------+ - -Sent by either end to force a disconnection. Acknowledged with 4-byte packet "DISC" (without the callsign field) diff --git a/docs/ip_networking.md b/docs/ip_networking.md new file mode 100644 index 0000000..f94c1fd --- /dev/null +++ b/docs/ip_networking.md @@ -0,0 +1,94 @@ +# M17 Internet Protocol (IP) Networking + +Digital modes are commonly networked together through linked repeaters using IP networking. + +For commercial protocols like DMR, this is meant for linking metropolitan and state networks together and allows for easy interoperability between radio users. Amateur Radio uses this capability for creating global communications networks for all imaginable purposes, and makes ‘working the world’ with an HT possible. + +M17 is designed with this use in mind, and has native IP framing to support it. + +In competing radio protocols, a repeater or some other RF to IP bridge is required for linking, leading to the use of hotspots (tiny simplex RF bridges). + +The TR-9 and other M17 radios may support IP networking directly, such as through the ubiquitous ESP8266 chip or similar. This allows them to skip the RF link that current hotspot systems require, finally bringing to fruition the “Amateur digital radio is just VoIP” dystopian future we were all warned about. + +## Standard IP Framing + +M17 over IP is big endian, consistent with other IP protocols. We have standardized on UDP port 17000, this port is recommended but not required. Later specifications may require this port. + +##### Internet Frame Fields + +Field | Size | Description +----- | ---- | ----------- +MAGIC | 32 bits | Magic bytes 0x4d313720 (“M17 “) +StreamID (SID) | 16 bits | Random bits, changed for each PTT or stream, but consistent from frame to frame within a stream +LICH | 240 bits | The meaningful contents of a LICH frame (dst, src, streamtype, META field, CRC16) as defined earlier. +FN | 16 bits | Frame number (exactly as would be transmitted as an RF stream frame, including the last frame indicator at (FN & 0x8000) +Payload | 128 bits | Payload (exactly as would be transmitted in an RF stream frame) +CRC16 | 16 bits | CRC for the entire packet, as defined earlier (TODO: specific link) + +The CRC checksum must be recomputed after modification or re-assembly of the packet, such as when translating from RF to IP framing. + +## Control Packets + +Reflectors use a few different types of control frames, identified by their magic: + +* CONN - Connect to a reflector +* ACKN - acknowledge connection +* NACK - deny connection +* PING - keepalive for the connection from the reflector to the client +* PONG - keepalive response from the client to the reflector +* DISC - Disconnect (client->reflector or reflector->client) + +#### CONN + +##### Bytes of CONN Packet + +Bytes | Purpose +----- | ------- +0..3 | Magic - ASCII "CONN" +4..9 | 6-byte ‘From’ callsign including module in last character (e.g. “A1BCD D”) encoded as per Address Encoding +10 | Module to connect to - single ASCII byte A-Z + +A client sends this to a reflector to initiate a connection. The reflector replies with ACKN on successful linking, or NACK on failure. + +#### ACKN + +##### Bytes of ACKN Packet + +Bytes | Purpose +----- | ------- +0..3 | Magic - ASCII "ACKN" + +#### NACK + +##### Bytes of NACK Packet + +Bytes | Purpose +----- | ------- +0..3 | Magic - ASCII "NACK" + +#### PING + +##### Bytes of PING Packet + +Bytes | Purpose +----- | ------- +0..3 | Magic - ASCII "PING" +4..9 | 6-byte ‘From’ callsign including module in last character (e.g. “A1BCD D”) encoded as per Address Encoding + +#### PONG + +##### Bytes of PONG Packet + +Bytes | Purpose +----- | ------- +0..3 | Magic - ASCII "PONG" +4..9 | 6-byte ‘From’ callsign including module in last character (e.g. “A1BCD D”) encoded as per Address Encoding + +#### DISC + +##### Bytes of DISC Packet + +Bytes | Purpose +----- | ------- +0..3 | Magic - ASCII "DISC" +4..9 | 6-byte ‘From’ callsign including module in last character (e.g. “A1BCD D”) encoded as per Address Encoding diff --git a/docs/kiss_protocol.md b/docs/kiss_protocol.md new file mode 100644 index 0000000..314cda9 --- /dev/null +++ b/docs/kiss_protocol.md @@ -0,0 +1,211 @@ +# KISS Protocol + +The purpose of this appendix is to document conventions for adapting KISS TNCs to M17 packet and streaming modes. M17 is a more complex protocol, both at the baseband level and at the data link layer than is typical for HDLC-based protocols commonly used on KISS TNCs. However, it is well suited for modern packet data links, and can even be used to stream digital audio between a host and a radio. + +This appendix assumes the reader is familiar with the streaming and packet modes defined in the M17 spec, and with KISS TNCs and the KISS protocol. + +In all cases, the TNC expects to get the data payload to be sent and is responsible for frame construction, FEC encoding, puncturing, interleaving and decorrelation. It is also responsible for baseband modulation. + +For streaming modes, all voice encoding (Codec2) is done on the host and not on the TNC. The host is also responsible for constructing the LICH. + +### References + +* [http://www.ax25.net/kiss.aspx](http://www.ax25.net/kiss.aspx) +* [https://packet-radio.net/wp-content/uploads/2017/04/multi-kiss.pdf](https://packet-radio.net/wp-content/uploads/2017/04/multi-kiss.pdf) +* [https://en.wikipedia.org/wiki/OSI_model](https://en.wikipedia.org/wiki/OSI_model) + +### Glossary + +#### TNC +Terminal node controller -- a baseband network interface device to allow host computers to send data over a radio network, similar to a modem. It connects a computer to a radio and handles the baseband portion of the physical layer and the data link layer of network protocol stack. + +#### KISS +Short for "Keep it simple, stupid". A simplified TNC protocol designed to move everything except for the physical layer and the data link layer out of the TNC. Early TNCs could include everything up through the application layer of the OSI network model. + +#### SLIP +[Serial Line Internet Protocol](https://en.wikipedia.org/wiki/Serial_Line_Internet_Protocol) -- the base protocol used by the KISS protocol, extended by adding a single **type indicator** byte at the start of a frame. + +#### type indicator +A one byte code at the beginning of a KISS frame which indicates the TNC **port** and KISS **command**. + +#### port +A logical port on a TNC. This allowed a single TNC to connect to multiple radios. Its specific use is loosely defined in the KISS spec. The high nibble of the KISS **type indicator**. Port 0xF is reserved. + +#### command +A KISS command. This tells the TNC or host how to interpret the KISS frame contents. The low nibble of the KISS **type indicator**. Command 0xF is reserved. + +#### CSMA +[Carrier-sense multiple access](https://en.wikipedia.org/wiki/Carrier-sense_multiple_access) -- a protocol used by network devices to minimize collisions on a shared communications channel. + +#### HDLC +[High-Level Data Link Control](https://en.wikipedia.org/wiki/High-Level_Data_Link_Control) -- a data link layer framing protocol used in many AX.25 packet radio networks. Many existing protocol documents, including KISS, reference HDLC because of its ubiquity when the protocols were invented. However, HDLC is not a requirement for higher level protocols like KISS which are agnostic to the framing used at the data link layer. + +#### EOS +End of stream -- an indicator bit in the frame number field of a stream data frame. + +#### LICH +Link information channel -- a secondary data channel in the stream data frame containing supplemental information, including a copy of the link setup frame. + +### M17 Protocols + +This specification defines KISS TNC modes for M17 packet and streaming modes, allowing the KISS protocol to be used to send and receive M17 packet and voice data. Both are bidirectional. There are two packet modes defined. This is done to provide complete access to the M17 protocol while maintaining the greatest degree of backwards compatibility with existing packet applications. + +These protocols map to specific KISS port. The host tells the TNC what type of data to transmit based on the port used in host to TNC transfers. And the TNC tells the host what data it has received by the port set on TNC to host transfers. + +This document outlines first the two packet protocols, followed by the streaming protocol. + +### KISS Basics + +#### TX Delay + +If a **KISS TX** delay $T_d$ greater than 0 is specified, the transmitter is keyed for $T_d ∗ 10ms$ with only a DC signal present. + +The $T_d$ value should be adjusted to the minimum required by the transmitter in order to transmit the full preamble reliably. + +Only a single 40ms preamble frame is ever sent. + +!!! note + A TX delay may be necessary because many radios require some time between when PTT is engaged and the transmitter can begin transmitting a modulated signal. + +### Packet Protocols + +In order to provide backward compatibility with the widest range of existing ham radio software, and to make use of features in the the M17 protocol itself, we will define two distint packet interfaces BASIC and FULL. + +The KISS protocol allows us to target specific modems using the port identifier in the control byte. + +We first define basic packet mode as this is initially likely to be the most commonly used mode over KISS. + +#### M17 Basic Packet Mode + +Basic packet mode uses only the standard KISS protocol on TNC port 0. This is the default port for all TNCs. Packets are sent using command 0. Again, this is normal behavior for KISS client applications. + +##### Sending Data + +In basic mode, the TNC only expects to receive packets from the host, as it would for any other mode supported AFSK, G3RUH, etc. + +If the TNC is configured for half-duplex, the TNC will do P-persistence CSMA using a 40ms slot time and obey the P value set via the KISS interface. CSMA is disabled in full-duplex mode. + +The **TX Tail** value is deprecated and is ignored. + +The TNC sends the preamble burst. + +The TNC is responsible for constructing the link setup frame, identifying the content as a raw mode packet. The source field is an encoded TNC identifier, similar to the APRS TOCALL, but it can be an arbitrary text string up to 9 characters in length. The destination is set to the broadcast address. + +In basic packet mode, it is expected that the sender callsign is embedded within the packet payload. + +The TNC sends the link setup frame. + +The TNC then computes the CRC for the full packet, splits the packet into data frames encode and modulate each frame back-to-back until the packet is completely transmitted. + +If there is another packet to be sent, the preamble can be skipped and the TNC will construct the next link setup frame (it can re-use the same link setup frame as it does not change) and send the next set of packet frames. + +##### Limitations + +The KISS specification defines no limitation to the packet size allowed. Nor does it specify any means of returning error conditions back to the host. M17 packet protocol limits the raw packet payload size to 798 bytes. The TNC must drop any packets larger than this. + +##### Receiving Data + +When receiving M17 data, the TNC must receive and parse the link setup frame and verify that the following frames contain raw packet data. + +The TNC is responsible for decoding each packet, assembling the packet from the sequence of frames received, and verifying the packet checksum. If the checksum is valid, the TNC transfers the packet, excluding the CRC to the host using **KISS port** 0. + +#### M17 Full Packet Mode + +The purpose of full packet mode is to provide access to the entire M17 packet protocol to the host. This allows the host to set the source and destination fields, filter received packets based on the content these fields, enable encryption, and send and receive type-coded frames. + +Use M17 full packet mode by sending to **KISS port** 1. In this mode the host is responsible for sending both the link setup frame and the packet data. It does this by prepending the 30-byte link setup frame to the packet data, sending this to the TNC in a single KISS frame. The TNC uses the first 30 bytes as the link setup frame verbatim, then splits the remaining data into M17 packet frames. + +As with basic mode, the TNC uses the **Duplex** setting to enable/disable CSMA, and uses the **P value** for CSMA, with a fixes slot time of “4” (40 ms). + +##### Receiving Data + +For TNC to host transfers, the same occurs. The TNC combines the link setup frame with the packet frame and sends both in one KISS frame to the host using **KISS port** 1. + +### Stream Protocol + +The streaming protocol is fairly trivial to describe. It is used by sending first a link setup frame followed by a stream of 26-byte data frames to KISS port 2. + +#### Stream Format + +##### M17 Kiss Stream Protocol + +Frame Size | Contents +---------- | -------- +30 | Link Setup Frame +26 | LICH + Payload +26 | LICH + Payload +... | ... +26 | LICH + Payload with EOS bit set + +The host must not send any frame to any other KISS port while a stream is active (a frame with the EOS bit has not been sent). + +It is a protocol violation to send anything other than a link setup frame with the stream mode bit set in the first field as the first frame in a stream transfer to KISS port 2. Any such frame is ignored. + +It is a protocol violation to send anything to any other KISS port while a stream is active. If that happens the stream is terminated and the packet that caused the protocol violation is dropped. + +#### Data Frames + +The data frames contain a 6-byte (48-bit) LICH segment followed by a 20 byte payload segment consisting of frame number, 16-byte data payload and CRC. The TNC is responsible for parsing the frame number and detecting the end-of-stream bit to stop transmitting. + +##### KISS Stream Data Frame + +Frame Size | Contents +---------- | -------- +6 | LICH (48 bits) +2 | Frame Number and EOS Flag +16 | Payload +2 | M17 CRC of frame number and payload + +The TNC is responsible for FEC-encoding both the LICH the payload, as well as interleaving, decorrelation, and baseband modulation. + +#### Timing Constraints + +Streaming mode provides additional timing constraints on both host to TNC transfers and on TNC to host transfers. Payload frames must arrive every 40ms and must have a jitter below 40ms. In general, it is expected that the TNC has up to 2 frames buffered (buffering occurs while sending the preamble and link setup frames), it should be able to keep the transmit buffers filled with packet jitter of 40ms. + +The TNC must stop transmitting if the transmit buffers are empty. The TNC communicates that it has stopped transmitting early (before seeing a frame with the end of stream indicator set) by sending an empty data frame to the host. + +### TNC to Host Transfers + +TNC to host transfers are similar in that the TNC first sends the 30-byte link setup frame received to the host, followed by a stream of 26-byte data frames as described above. These are sent using **KISS port** 2. + +The TNC must send the link setup frame first. This means that tne TNC must be able to decode LICH segments and assemble a valid link setup frame before it sends the first data frame. The TNC will only send a link setup frame with a valid CRC to the host. After the link setup frame is sent, the TNC ignores the CRC and sends all valid frames (those received after a valid sync word) to the host. If the stream is lost before seeing an end-of-stream flag, the TNC sends a 0-byte data frame to indicate loss of signal. + +The TNC must then re-acquire the signal by decoding a valid link setup frame from the LICH in order to resume sending to the host. + +### Busy Channel Lockout + +The TNC implements **busy channel lockout** by enabling half-duplex mode on the TNC, and disables **busy channel lockout** by enabling full-duplex mode. When busy channel lockout occurs, the TNC keeps the link setup frame and discards all data frames until the channel is available. It then sends the preamble, link setup frame, and starts sending the data frames as they are received. + +Note: BCL will be apparent to a receiver as the first frame received after the link setup frame will not start with frame number 0. + +#### Limitations + +Information is lost by having the TNC decode the LICH. It is not possible to communicate to the host that the LICH bytes are known to be invalid. + +Should we have the TNC signal the host by dropping known invalid LICH segments? The host can tell that the LICH is missing by looking at the frame size. + +### Mixing Modes + +An M17 KISS TNC need not keep track of state across distinct TNC ports. Packet transfers are sent one packet at a time. It is OK to send to port 0 and port 1 in subsequent transfers. It is also OK to send a packet followed immediately by a voice streams. As mentioned earlier, it is a protocol violation to sent a KISS frame to any other port while a stream is active. However, a packet can be sent immediately following a voice stream (after EOS is sent). + +#### Back-to-back Transfers + +The TNC is expected to detect back-to-back transfers from the host, even across different KISS ports, and suppress the generation of the preamble. + +For example, a packet containing APRS data sent immediately on PTT key-up should be sent immediately after the EOS frame. + +Back-to-back transfers are common for packet communication where the window size determines the number of unacknowledged frames which may be outstanding (unacknowledged). Packet applications will frequently send back-to-back packets (up to window size packets) before waiting for the remote end to send ACKs for each of the packets. + +### Implementation Details + +#### Polarity + +One of the issues that must be addressed by the TNC designer, and one which the KISS protocol offers no ready solution for, is the issue of polarity. + +A TNC must interface with a RF transceiver for a complete M17 physical layer implementation. RF transceivers may have different polarity for their TX and RX paths. + +M17 defines that the +3 symbol is transmitted with a +2.4 kHz deviation (2.4 kHz above the carrier). **Normal polarity** in a transceiver results in a positive voltage driving the frequency higher and a lower voltage driving the frequency lower. **Reverse polarity** is the opposite. A higher voltage drives the frequency lower. + +On the receive side the same issue exists. **Normal polarity** results in a positive voltage output when the received signal is above the carrier frequency. **Reverse polarity** results in a positive voltage when the frequency is below the carrier. + +Just as with transmitter deviation levels and received signal levels, the polarity of the transmit and receive path must be adjustable on a 4-FSK modem. The way these adjustments are made to the TNC are not addressed by the KISS specification. diff --git a/docs/kiss_protocol.rst b/docs/kiss_protocol.rst deleted file mode 100644 index 9ca2aff..0000000 --- a/docs/kiss_protocol.rst +++ /dev/null @@ -1,395 +0,0 @@ -************* -KISS Protocol -************* - -The purpose of this appendix is to document conventions for adapting KISS TNCs -to M17 packet and streaming modes. M17 is a more complex protocol, both at -the baseband level and at the data link layer than is typical for HDLC-based -protocols commonly used on KISS TNCs. However, it is well suited for modern -packet data links, and can even be used to stream digital audio between a host -and a radio. - -This appendix assumes the reader is familiar with the streaming and packet -modes defined in the M17 spec, and with KISS TNCs and the KISS protocol. - -In all cases, the TNC expects to get the data payload to be sent and is -responsible for frame construction, FEC encoding, puncturing, interleaving -and decorrelation. It is also responsible for baseband modulation. - -For streaming modes, all voice encoding (Codec2) is done on the host and -not on the TNC. The host is also responsible for constructing the LICH. - - -References -========== - - - http://www.ax25.net/kiss.aspx - - https://packet-radio.net/wp-content/uploads/2017/04/multi-kiss.pdf - - https://en.wikipedia.org/wiki/OSI_model - - -Glossary -======== - -.. glossary:: - - TNC - Terminal node controller -- a baseband network interface device to allow - host computers to send data over a radio network, similar to a modem. It - connects a computer to a radio and handles the baseband portion of the - physical layer and the data link layer of network protocol stack. - - KISS - Short for "Keep it simple, stupid". A simplified TNC protocol designed - to move everything except for the physical layer and the data link layer - out of the TNC. Early TNCs could include everything up through the - application layer of the OSI network model. - - SLIP - `Serial Line Internet Protocol `_ -- - the base protocol used by the KISS protocol, extended by adding a single - :term:`type indicator` byte at the start of a frame. - - type indicator - A one byte code at the beginning of a KISS frame which indicates the TNC - :term:`port` and KISS :term:`command`. - - port - A logical port on a TNC. This allowed a single TNC to connect to multiple - radios. Its specific use is loosely defined in the KISS spec. The high - nibble of the KISS :term:`type indicator`. Port 0xF is reserved. - - command - A KISS command. This tells the TNC or host how to interpret the KISS - frame contents. The low nibble of the KISS :term:`type indicator`. - Command 0xF is reserved. - - CSMA - `Carrier-sense multiple access `_ -- - a protocol used by network devices to minimize collisions on a shared - communications channel. - - HDLC - `High-Level Data Link Control `_ -- - a data link layer framing protocol used in many AX.25 packet radio - networks. Many existing protocol documents, including KISS, reference - HDLC because of its ubiquity when the protocols were invented. However, - HDLC is not a requirement for higher level protocols like KISS which - are agnostic to the framing used at the data link layer. - - EOS - End of stream -- an indicator bit in the frame number field of a stream - data frame. - - LICH - Link information channel -- a secondary data channel in the stream data - frame containing supplemental information, including a copy of the link - setup frame. - - -M17 Protocols -============= - -This specification defines KISS TNC modes for M17 packet and streaming modes, -allowing the KISS protocol to be used to send and receive M17 packet and voice -data. Both are bidirectional. There are two packet modes defined. This is done -to provide complete access to the M17 protocol while maintaining the greatest -degree of backwards compatibility with existing packet applications. - -These protocols map to specific KISS :term:`port`. The host tells the TNC what -type of data to transmit based on the port used in host to TNC transfers. And -the TNC tells the host what data it has received by the port set on TNC to -host transfers. - -This document outlines first the two packet protocols, followed by the -streaming protocol. - -KISS Basics -=========== - -TX Delay --------- - -If a KISS **TX delay** :math:`T_d` greater than 0 is specified, the transmitter -is keyed for :math:`T_d * 10 ms` with only a DC signal present. - -The :math:`T_d` value should be adjusted to the minimum required by the -transmitter in order to transmit the full preamble reliably. - -Only a single 40ms preamble frame is ever sent. - -.. note:: - - A TX delay may be necessary because many radios require some time between - when PTT is engaged and the transmitter can begin transmitting a modulated - signal. - - -Packet Protocols -================ - -In order to provide backward compatibility with the widest range of existing -ham radio software, and to make use of features in the the M17 protocol -itself, we will define two distint packet interfaces *BASIC* and *FULL*. - -The KISS protocol allows us to target specific modems using the port -identifier in the control byte. - -We first define basic packet mode as this is initially likely to be the -most commonly used mode over KISS. - -M17 Basic Packet Mode ---------------------- - -Basic packet mode uses only the standard KISS protocol on **TNC port** 0. -This is the default port for all TNCs. Packets are sent using command 0. -Again, this is normal behavior for KISS client applications. - -Sending Data -^^^^^^^^^^^^ - -In basic mode, the TNC only expects to receive packets from the host, as it -would for any other mode supported AFSK, G3RUH, etc. - -If the TNC is configured for half-duplex, the TNC will do P-persistence CSMA -using a 40ms slot time and obey the P value set via the KISS interface. CSMA -is disabled in full-duplex mode. - -The **TX Tail** value is deprecated and is ignored. - -The TNC sends the preamble burst. - -The TNC is responsible for constructing the link setup frame, identifying the -content as a raw mode packet. The source field is an encoded TNC identifier, -similar to the APRS TOCALL, but it can be an arbitrary text string up to 9 -characters in length. The destination is set to the broadcast address. - -In basic packet mode, it is expected that the sender callsign is embedded within -the packet payload. - -The TNC sends the link setup frame. - -The TNC then computes the CRC for the full packet, splits the packet into data -frames encode and modulate each frame back-to-back until the packet is -completely transmitted. - -If there is another packet to be sent, the preamble can be skipped and the -TNC will construct the next link setup frame (it can re-use the same link -setup frame as it does not change) and send the next set of packet frames. - -Limitations -^^^^^^^^^^^ - -The KISS specification defines no limitation to the packet size allowed. Nor -does it specify any means of returning error conditions back to the host. -M17 packet protocol limits the raw packet payload size to 798 bytes. The -TNC must drop any packets larger than this. - -Receiving Data -^^^^^^^^^^^^^^ - -When receiving M17 data, the TNC must receive and parse the link setup frame -and verify that the following frames contain raw packet data. - -The TNC is responsible for decoding each packet, assembling the packet from -the sequence of frames received, and verifying the packet checksum. If the -checksum is valid, the TNC transfers the packet, excluding the CRC to the host -using **KISS port** 0. - -M17 Full Packet Mode ---------------------- - -The purpose of full packet mode is to provide access to the entire M17 packet -protocol to the host. This allows the host to set the source and destination -fields, filter received packets based on the content these fields, enable -encryption, and send and receive type-coded frames. - -Use M17 full packet mode by sending to **KISS port** 1. In this mode the host -is responsible for sending both the link setup frame and the packet data. It -does this by prepending the 30-byte link setup frame to the packet data, -sending this to the TNC in a single KISS frame. The TNC uses the first 30 -bytes as the link setup frame verbatim, then splits the remaining data into -M17 packet frames. - -As with basic mode, the TNC uses the **Duplex** setting to enable/disable CSMA, -and uses the **P value** for CSMA, with a fixes slot time of "4" (40 ms). - -Receiving Data -^^^^^^^^^^^^^^ - -For TNC to host transfers, the same occurs. The TNC combines the link setup -frame with the packet frame and sends both in one KISS frame to the host using -**KISS port** 1. - -Stream Protocol -=============== - -The streaming protocol is fairly trivial to describe. It is used by sending -first a link setup frame followed by a stream of 26-byte data frames to -**KISS port** 2. - -Stream Format -------------- - -.. list-table:: M17 KISS Stream Protocol - :header-rows: 1 - - * - Frame Size - - Contents - * - 30 - - Link Setup Frame - * - 26 - - LICH + Payload - * - 26 - - LICH + Payload - * - ... - - ... - * - 26 - - LICH + Payload with EOS bit set. - -The host must not send any frame to any other KISS port while a stream is -active (a frame with the EOS bit has not been sent). - -It is a protocol violation to send anything other than a link setup frame with -the stream mode bit set in the first field as the first frame in a stream -transfer to KISS port 2. Any such frame is ignored. - -It is a protocol violation to send anything to any other KISS port while a -stream is active. If that happens the stream is terminated and the packet -that caused the protocol violation is dropped. - - -Data Frames ------------ - -The data frames contain a 6-byte (48-bit) LICH segment followed by a 20 byte -payload segment consisting of frame number, 16-byte data payload and CRC. The -TNC is responsible for parsing the frame number and detecting the end-of-stream -bit to stop transmitting. - -.. list-table:: KISS Stream Data Frame - :header-rows: 1 - - * - Frame Size - - Contents - * - 6 - - LICH (48 bits) - * - 2 - - Frame number and EOS flag - * - 16 - - Payload - * - 2 - - M17 CRC of frame number and payload - -The TNC is responsible for FEC-encoding both the LICH the payload, as well -as interleaving, decorrelation, and baseband modulation. - -Timing Constraints ------------------- - -Streaming mode provides additional timing constraints on both host to TNC -transfers and on TNC to host transfers. Payload frames must arrive every -40ms and must have a jitter below 40ms. In general, it is expected that the -TNC has up to 2 frames buffered (buffering occurs while sending the preamble -and link setup frames), it should be able to keep the transmit buffers filled -with packet jitter of 40ms. - -The TNC must stop transmitting if the transmit buffers are empty. The TNC -communicates that it has stopped transmitting early (before seeing a frame -with the **end of stream** indicator set) by sending an empty data frame to -the host. - -TNC to Host Transfers ---------------------- - -TNC to host transfers are similar in that the TNC first sends the 30-byte -link setup frame received to the host, followed by a stream of 26-byte data -frames as described above. These are sent using **KISS port** 2. - -The TNC must send the link setup frame first. This means that tne TNC must -be able to decode LICH segments and assemble a valid link setup frame before -it sends the first data frame. The TNC will only send a link setup frame -with a valid CRC to the host. After the link setup frame is sent, the TNC -ignores the CRC and sends all valid frames (those received after a valid -sync word) to the host. If the stream is lost before seeing an end-of-stream -flag, the TNC sends a 0-byte data frame to indicate loss of signal. - -The TNC must then re-acquire the signal by decoding a valid link setup frame -from the LICH in order to resume sending to the host. - -Busy Channel Lockout --------------------- - -The TNC implements **busy channel lockout** by enabling half-duplex mode on -the TNC, and disables **busy channel lockout** by enabling full-duplex mode. -When busy channel lockout occurs, the TNC keeps the link setup frame and -discards all data frames until the channel is available. It then sends the -preamble, link setup frame, and starts sending the data frames as they are -received. - -Note: BCL will be apparent to a receiver as the first frame received after -the link setup frame will not start with frame number 0. - -Limitations ------------ - -Information is lost by having the TNC decode the LICH. It is not possible to -communicate to the host that the LICH bytes are known to be invalid. - -Should we have the TNC signal the host by dropping known invalid LICH segments? -The host can tell that the LICH is missing by looking at the frame size. - -Mixing Modes -============ - -An M17 KISS TNC need not keep track of state across distinct TNC ports. Packet -transfers are sent one packet at a time. It is OK to send to port 0 and port 1 -in subsequent transfers. It is also OK to send a packet followed immediately -by a voice streams. As mentioned earlier, it is a protocol violation to sent -a KISS frame to any other port while a stream is active. However, a packet -can be sent immediately following a voice stream (after EOS is sent). - -Back-to-back Transfers ----------------------- - -The TNC is expected to detect back-to-back transfers from the host, even across -different KISS ports, and suppress the generation of the preamble. - -For example, a packet containing APRS data sent immediately on PTT key-up -should be sent immediately after the EOS frame. - -Back-to-back transfers are common for packet communication where the -**window size** determines the number of unacknowledged frames which may be -outstanding (unacknowledged). Packet applications will frequently send -back-to-back packets (up to **window size** packets) before waiting for -the remote end to send ACKs for each of the packets. - -Implementation Details -====================== - -Polarity --------- - -One of the issues that must be addressed by the TNC designer, and one which -the KISS protocol offers no ready solution for, is the issue of polarity. - -A TNC must interface with a RF transceiver for a complete M17 physical layer -implementation. RF transceivers may have different polarity for their -TX and RX paths. - -M17 defines that the +3 symbol is transmitted with a +2.4 kHz deviation -(2.4 kHz above the carrier). **Normal polarity** in a transceiver results -in a positive voltage driving the frequency higher and a lower voltage -driving the frequency lower. **Reverse polarity** is the opposite. A -higher voltage drives the frequency lower. - -On the receive side the same issue exists. **Normal polarity** results -in a positive voltage output when the received signal is above the carrier -frequency. **Reverse polarity** results in a positive voltage when the -frequency is below the carrier. - -Just as with transmitter deviation levels and received signal levels, the -polarity of the transmit and receive path must be adjustable on a 4-FSK -modem. The way these adjustments are made to the TNC are not addressed -by the KISS specification. - diff --git a/docs/mathjaxhelper.js b/docs/mathjaxhelper.js new file mode 100644 index 0000000..f8f2254 --- /dev/null +++ b/docs/mathjaxhelper.js @@ -0,0 +1,5 @@ +MathJax.Hub.Config({ + config: ["MMLorHTML.js"], + jax: ["input/TeX", "output/HTML-CSS", "output/NativeMML"], + extensions: ["MathMenu.js", "MathZoom.js"] +}); \ No newline at end of file diff --git a/docs/partI.md b/docs/partI.md new file mode 100644 index 0000000..1cd3550 --- /dev/null +++ b/docs/partI.md @@ -0,0 +1,14 @@ +## [Part I - Air and IP Interface](partI.md) +* [M17 RF Protocol: Summary](summary.md) +* [Glossary](glossary.md) +* [Physical Layer](physical_layer.md) + * [4FSK generation](physical_layer.md#4fsk-generation) + * [Preamble](physical_layer.md#preamble) + * [Bit types](physical_layer.md#bit-types) + * [Error correction coding schemes and bit type conversion](physical_layer.md#error-correction-coding-schemes-and-bit-type-conversion) +* [Data Link Layer](data_link_layer.md) + * [Stream Mode](data_link_layer.md#stream-mode) + * [Packet Mode](data_link_layer.md#packet-mode) +* [Application Layer](application_layer.md) + * [Packet Superframes](application_layer.md#packet-superframes) + * [Encryption Types](application_layer.md#encryption-types) \ No newline at end of file diff --git a/docs/partII.md b/docs/partII.md new file mode 100644 index 0000000..7cd8929 --- /dev/null +++ b/docs/partII.md @@ -0,0 +1,5 @@ +## [Part II - Codeplug](partII.md) +* [Recommendation for the codeplug structure](codeplug.md#recommendation-for-the-codeplug-structure) + * [Introduction](codeplug.md#introduction) + * [Codeplug file structure](codeplug.md#codeplug-file-structure) + * [Example Codeplug](codeplug.md#example-codeplug) \ No newline at end of file diff --git a/docs/physical_layer.md b/docs/physical_layer.md new file mode 100644 index 0000000..68794dc --- /dev/null +++ b/docs/physical_layer.md @@ -0,0 +1,159 @@ +# Physical Layer + +## 4FSK generation + +M17 standard uses 4FSK modulation running at 4800 symbols/s (9600 bits/s) with a deviation index h=0.33 for transmission in 9 kHz channel bandwidth. Channel spacing is 12.5 kHz. The symbol stream is converted to a series of impulses which pass through a root-raised-cosine (alpha=0.5) shaping filter before frequency modulation at the transmitter and again after frequency demodulation at the receiver. + +```mermaid +graph LR + id1[Dibibits Input] --> id2[RRC Filter] --> id3[Frequency Modulation] --> id4[4FSK Output] +``` + +The bit-to-symbol mapping is shown in the table below. + +Bit 1 | Bit 0 | Symbol | 4FSK Deviation +----- | ----- | ------ | -------------- +0 | 1 | +3 | +2.4 kHz +0 | 0 | +1 | +0.8 kHz +1 | 0 | -1 | -0.8 kHz +1 | 1 | -3 | -2.4 kHz + +The most significant bits are sent first, meaning that the byte 0xB4 (= 0b10’11’01’00) in type 4 bits (see Bit types) would be sent as the symbols -1 -3 +3 +1. + +### Preamble + +Every transmission starts with a preamble, which shall consist of at least 40 ms of alternating -3, +3… symbols. This is equivalent to 40 milliseconds of a 2400 Hz tone. + +### Bit Types + +The bits at different stages of the error correction coding are referred to with bit types, given in the following table. + +Type | Description +---- | ----------- +Type 1 | Data link layer bits +Type 2 | Bits after appropriate encoding +Type 3 | Bits after puncturing (only for convolutionally coded data, for other ECC schemes type 3 bits are the same as type 2 bits) +Type 4 | Decorrelated and interleaved (re-ordered) type 3 bits + +Type 4 bits are used for transmission over the RF. Incoming type 4 bits shall be decoded to type 1 bits, which are then used to extract all the frame fields. + +### Error correction coding schemes and bit type conversion + +Two distinct ECC/FEC schemes are used for different parts of the transmission. + +#### Link Setup Frame + +![LSF Encoding](img/link_setup_frame_encoding.svg) + +240 DST, SRC, TYPE, META and CRC type 1 bits are convolutionally coded using rate 1/2 coder with constraint K=5. 4 tail bits are used to flush the encoder’s state register, giving a total of 244 bits being encoded. Resulting 488 type 2 bits are retained for type 3 bits computation. Type 3 bits are computed by puncturing type 2 bits using a scheme shown in chapter 4.4. This results in 368 bits, which in conjunction with the synchronization burst gives 384 bits (384 bits / 9600bps = 40 ms). + +Interleaving type 3 bits produce type 4 bits that are ready to be transmitted. Interleaving is used to combat error bursts. + +#### Subsequent Frames + +![Frame Encoding](img/frame_encoding.svg) + +A 48-bit (type 1) chunk of the LSF is partitioned into 4 12-bit parts and encoded using Golay (24, 12) code. This produces 96 encoded bits of type 2. These bits are used in the Link Information Channel (LICH). + +16-bit FN and 128 bits of payload (144 bits total) are convolutionally encoded in a manner analogous to that of the link setup frame. A total of 148 bits is being encoded resulting in 296 type 2 bits. These bits are punctured to generate 272 type 3 bits. + +96 type 2 bits of LICH are concatenated with 272 type 3 bits and re-ordered to form type 4 bits for transmission. This, along with 16-bit sync in the beginning of frame, gives a total of 384 bits. + +The LICH chunks allow for late listening and indepedent decoding to check destination address. The goal is to require less complexity to decode just the LICH and check if the full message should be decoded. + +#### Golay (24,12) + +The Golay (24,12) encoder uses generating polynomial g given below to generate the 11 check bits. The check bits and an overall parity bit are appended to the 12 bit data, resulting in a 24 bit codeword. The resulting code is systematic, meaning that the input data (message) is embedded in the codeword. + +$$ +\begin{align} + g(x) =& x^{11} + x^{10} + x^6 + x^5 + x^4 + x^2 + 1 +\end{align} +$$ + +This is equivalent to 0xC75 in hexadecimal notation. The output of the Golay encoder is shown in the table below. + +Field | Data | Check bits | Parity +----- | ---- | ---------- | ------ +Position | 23..12 | 11..1 | 0 (LSB) +Length | 12 | 11 | 1 + +Four of these 24-bit blocks are used to reconstruct the LSF. + +#### Convolutional encoder + +The convolutional code shall encode the input bit sequence after appending 4 tail bits at the end of the sequence. Rate of the coder is R=½ with constraint length K=5. The encoder diagram and generating polynomials are shown below: + +$$ +\begin{align} + G_1(D) =& 1 + D^3 + D^4 \\ + G_2(D) =& 1+ D + D^2 + D^4 +\end{align} +$$ + +The output from the encoder must be read alternately. + +![Convolutional Coder Diagram](img/convolutional.svg) + +#### Code Puncturing + +Removing some of the bits from the convolutional coder’s output is +called code puncturing. The nominal coding rate of the encoder used in +M17 is ½. This means the encoder outputs two bits for every bit of the +input data stream. To get other (higher) coding rates, a puncturing +scheme has to be used. + +Two different puncturing schemes are used in M17 stream mode: + +1. $P_1$ leaving 46 from 61 encoded bits +2. $P_2$ leaving 11 from 12 encoded bits + +Scheme $P_1$ is used for the *link setup frame*, taking 488 bits of encoded data and selecting 368 bits. The $gcd(368,488)$ is 8 which, when used to divide, leaves 46 and 61 bits. However, a full puncture pattern requires the puncturing matrix entries count to be divisible by the number of encoding polynomials. For this case a partial puncture matrix is used. It has 61 entries with 46 of them being ones and shall be used 8 times, repeatedly. The construction of the partial puncturing pattern $P_1$ is as follows: + +$$ +\begin{align} + \mathbb{M} = & \begin{bmatrix} + 1 & 0 & 1 & 1 + \end{bmatrix} \\ + P_1 = & \begin{bmatrix} + 1 & \mathbb{M}_{1} & \cdots & \mathbb{M}_{15} + \end{bmatrix} +\end{align} +$$ + +In which $\mathbb{M}$ is a standard 2/3 rate puncture matrix and is used 15 times, along with a leading 1 to form an array of length 61. + +The first pass of the partial puncturer discards $G_1$ bits only, second pass discards $G_2$, third - $G_1$ again, and so on. This ensures that both bits are punctured out evenly. + +Scheme $P_2$ is for frames (excluding LICH chunks, which are coded differently). This takes 296 encoded bits and selects 272 of them. Every 12th bit is being punctured out, leaving 272 bits. The full matrix shall have 12 entries with 11 being ones. + +The puncturing scheme $P_2$ is defined by its partial puncturing matrix: + +$$ +\begin{align} + P_2 = & \begin{bmatrix} + 1 & 1 & 1 & 1 & 1 & 1 \\ + 1 & 1 & 1 & 1 & 1 & 0 + \end{bmatrix} +\end{align} +$$ + +The linearized representations are: + +``` +P1 = [1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, + 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, + 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, + 1, 1, 1, 0, 1, 1, 1, 0, 1, 1] + +P2 = [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0] +``` + +#### Interleaving + +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. See Appendix for pattern. + +#### Data Decorrelator + +To avoid transmitting long sequences of constant symbols (e.g. 010101…), a simple algorithm is used. All 46 bytes of type 4 bits shall be XORed with a pseudorandom, predefined stream. The same algorithm has to be used for incoming bits at the receiver to get the original data stream. See Appendix for sequence. diff --git a/docs/physical_layer.rst b/docs/physical_layer.rst deleted file mode 100644 index fd5398f..0000000 --- a/docs/physical_layer.rst +++ /dev/null @@ -1,290 +0,0 @@ -Physical Layer -============== - -4FSK generation ---------------- - -M17 standard uses 4FSK modulation running at 4800 symbols/s (9600 -bits/s) with a deviation index h=0.33 for transmission in 9 kHz -channel bandwidth. Channel spacing is 12.5 kHz. The symbol stream is -converted to a series of impulses which pass through a -root-raised-cosine (alpha=0.5) shaping filter before frequency modulation -at the transmitter and again after frequency demodulation at the -receiver. - -.. graph:: modulation - :alt: RRC filter and Frequency Modulation - :caption: 4FSK modulator dataflow - - rankdir="LR" - src [shape=none, label=""] - out [shape=none, label=""] - "RRC Filter"[shape=box] - "Frequency Modulation"[shape=box] - - src -- "RRC Filter" [label="Dibits Input"] - "RRC Filter" -- "Frequency Modulation" - "Frequency Modulation" -- out [label="4FSK output"] - -The bit-to-symbol mapping is shown in the table below. - -.. table:: Dibit symbol mapping to 4FSK deviation - - +-------------------------------+---------------+---------------+ - |Information bits |Symbol |4FSK deviation | - +---------------+---------------+ | | - |Bit 1 | Bit 0 | | | - +===============+===============+===============+===============+ - |0 |1 |+3 |+2.4 kHz | - +---------------+---------------+---------------+---------------+ - |0 |0 |+1 |+0.8 kHz | - +---------------+---------------+---------------+---------------+ - |1 |0 |-1 |-0.8 kHz | - +---------------+---------------+---------------+---------------+ - |1 |1 |-3 |-2.4 kHz | - +---------------+---------------+---------------+---------------+ - -.. todo:: update section - -The most significant bits are sent first, meaning that the byte 0xB4 (= 0b10'11'01'00) -in type 4 bits (see :ref:`bit_types`) would be sent as the symbols -1 -3 +3 -+1. - -Preamble --------- - -Every transmission starts with a preamble, which shall consist of at -least 40 ms of alternating -3, +3... symbols. This is equivalent to 40 -milliseconds of a 2400 Hz tone - - -.. _bit_types: - -Bit types ---------- - -The bits at different stages of the error correction coding are -referred to with bit types, given in :numref:`table_bit_types`. - -.. _table_bit_types: -.. table:: Bit types - - +---------------+------------------------------------------+ - |Type 1 |Data link layer bits | - +---------------+------------------------------------------+ - |Type 2 |Bits after appropriate encoding | - +---------------+------------------------------------------+ - |Type 3 |Bits after puncturing (only for | - | |convolutionally coded data, for other | - | |ECC schemes type 3 bits are the same as | - | |type 2 bits) | - +---------------+------------------------------------------+ - |Type 4 |Decorrelated and interleaved (re-ordered) | - | |type 3 bits | - +---------------+------------------------------------------+ - -Type 4 bits are used for transmission over the RF. Incoming type 4 -bits shall be decoded to type 1 bits, which are then used to extract -all the frame fields. - -Error correction coding schemes and bit type conversion -------------------------------------------------------- - -Two distinct :term:`ECC`/:term:`FEC` schemes are used for different parts of -the transmission. - - -Link setup frame (LSF) -~~~~~~~~~~~~~~~~~~~~~~ - -.. figure:: ../images/link_setup_frame_encoding.* - - ECC stages for the link setup frame - -240 DST, SRC, TYPE, META and CRC type 1 bits are convolutionally -coded using rate 1/2 coder with constraint K=5. 4 tail bits are used -to flush the encoder's state register, giving a total of 244 bits -being encoded. Resulting 488 type 2 bits are retained for type 3 bits -computation. Type 3 bits are computed by puncturing type 2 bits using -a scheme shown in chapter 4.4. This results in 368 bits, which in -conjunction with the synchronization burst gives 384 bits (384 bits / -9600bps = 40 ms). - -Interleaving type 3 bits produce type 4 bits that are ready to be -transmitted. Interleaving is used to combat error bursts. - - -Subsequent frames -~~~~~~~~~~~~~~~~~ - -.. figure:: ../images/frame_encoding.* - - ECC stages of subsequent frames - -A 48-bit (type 1) chunk of the LSF is partitioned into 4 12-bit parts and -encoded using Golay (24, 12) code. This produces 96 encoded bits -of type 2. These bits are used in the Link Information Channel (LICH). - -16-bit FN and 128 bits of payload (144 bits total) are convolutionally encoded in a manner -analogous to that of the link setup frame. A total of 148 bits is -being encoded resulting in 296 type 2 bits. These bits are punctured -to generate 272 type 3 bits. - -96 type 2 bits of LICH are concatenated with 272 type 3 bits and -re-ordered to form type 4 bits for transmission. This, along with -16-bit sync in the beginning of frame, gives a total of 384 bits - -The LICH chunks allow for late listening and indepedent decoding to -check destination address. The goal is to require less complexity to -decode just the LICH and check if the full message should be decoded. - -Golay (24,12) -~~~~~~~~~~~~~ - -The Golay (24,12) encoder uses generating polynomial *g* given below to generate the 11 -check bits. The check bits and an overall parity bit are appended to -the 12 bit data, resulting in a 24 bit codeword. The resulting code is systematic, -meaning that the input data (message) is embedded in the codeword. - -.. math:: - - \begin{align} - g =& x^{11} + x^{10} + x^6 + x^5 + x^4 + x^2 + 1 - \end{align} - -This is equivalent to 0xC75 in hexadecimal notation. -The output of the Golay encoder is shown in the table below. - - +------------+----------+-------------+---------+ - | Field | Data | Check bits | Parity | - +------------+----------+-------------+---------+ - | Position | 23..12 | 11..1 | 0 (LSB) | - +------------+----------+-------------+---------+ - | Length | 12 | 11 | 1 | - +------------+----------+-------------+---------+ - -Four of these 24-bit blocks are used to reconstruct the LSF. - -Convolutional encoder -~~~~~~~~~~~~~~~~~~~~~ - -.. [ECC] Moreira, Jorge C.; Farrell, Patrick G. "Essentials of - Error‐Control Coding" Wiley 2006, ISBN: 9780470029206 - -The convolutional code shall encode the input bit sequence after -appending 4 tail bits at the end of the sequence. Rate of the coder is -R=½ with constraint length K=5 [NXDN]_. The encoder diagram and generating -polynomials are shown below - -.. math:: - :nowrap: - - \begin{align} - G_1(D) =& 1 + D^3 + D^4 \\ - G_2(D) =& 1+ D + D^2 + D^4 - \end{align} - -The output from the encoder must be read alternately. - -.. [NXDN] NXDN Technical Specifications, Part 1: Air Interface; - Sub-part A: Common Air Interface - -.. figure:: ../images/convolutional.* - :scale: 30% - - Convolutional coder diagram - -Code puncturing -~~~~~~~~~~~~~~~ - -Removing some of the bits from the convolutional coder’s output is -called code puncturing. The nominal coding rate of the encoder used in -M17 is ½. This means the encoder outputs two bits for every bit of the -input data stream. To get other (higher) coding rates, a puncturing -scheme has to be used. - -Two different puncturing schemes are used in M17 stream mode: - -#. :math:`P_1` leaving 46 from 61 encoded bits -#. :math:`P_2` leaving 11 from 12 encoded bits - -Scheme :math:`P_1` is used for the *link setup frame*, taking 488 -bits of encoded data and selecting 368 bits. The :math:`gcd(368, 488)` -is 8 which, when used to divide, leaves 46 and 61 bits. However, a full puncture -pattern requires the puncturing matrix entries count to be divisible by the number of encoding -polynomials. For this case a partial puncture matrix is used. It has 61 -entries with 46 of them being ones and shall be used 8 times, repeatedly. -The construction of the partial puncturing pattern :math:`P_1` is as follows: - -.. math:: - :nowrap: - - \begin{align} - \mathbb{M} = & \begin{bmatrix} - 1 & 0 & 1 & 1 - \end{bmatrix} \\ - P_1 = & \begin{bmatrix} - 1 & \mathbb{M}_{1} & \cdots & \mathbb{M}_{15} - \end{bmatrix} - \end{align} - -In which :math:`\mathbb{M}` is a standard 2/3 rate puncture matrix and is used 15 times, -along with a leading `1` to form an array of length 61. - -The first pass of the partial puncturer discards :math:`G_1` bits only, second pass discards -:math:`G_2`, third - :math:`G_1` again, and so on. This ensures that both bits are punctured out evenly. - -Scheme :math:`P_2` is for frames (excluding LICH chunks, which are coded -differently). This takes 296 encoded bits and selects 272 of them. -Every 12th bit is being punctured out, leaving 272 bits. -The full matrix shall have 12 entries with 11 being ones. - -The puncturing scheme :math:`P_2` is defined by its partial puncturing matrix: - -.. math:: - :nowrap: - - \begin{align} - P_2 = & \begin{bmatrix} - 1 & 1 & 1 & 1 & 1 & 1 \\ - 1 & 1 & 1 & 1 & 1 & 0 - \end{bmatrix} - \end{align} - - -The linearized representations are: - -.. code-block:: python - :caption: linearized puncture patterns - - P1 = [1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, - 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, - 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1] - - P2 = [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0] - - - -Interleaving -~~~~~~~~~~~~ - -For interleaving a Quadratic Permutation Polynomial (QPP) is used. The -polynomial :math:`\pi(x)=(45x+92x^2)\mod 368` is used for a 368 bit interleaving -pattern [QPP]_. See appendix :numref:`sec-interleaver` for pattern. - -.. [QPP] Trifina, Lucian, Daniela Tarniceriu, and Valeriu - Munteanu. "Improved QPP Interleavers for LTE Standard." ISSCS - 2011 - International Symposium on Signals, Circuits and - Systems (2011): n. pag. Crossref. Web. https://arxiv.org/abs/1103.3794 - - -Data decorrelator -~~~~~~~~~~~~~~~~~ - -To avoid transmitting long sequences of constant symbols -(e.g. 010101…), a simple algorithm is used. All 46 -bytes of type 4 bits shall be XORed with a pseudorandom, predefined -stream. The same algorithm has to be used for incoming bits at the -receiver to get the original data stream. See :numref:`sec-decorr-seq` for sequence. - -.. todo:: add diagram diff --git a/docs/requirements.txt b/docs/requirements.txt index 20174f4..90014df 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,2 +1,3 @@ -sphinx_rtd_theme -sphinxcontrib-svg2pdfconverter>=1.1.0 +python-markdown-math +mkdocs-material +mkdocs-mermaid2-plugin \ No newline at end of file diff --git a/docs/summary.md b/docs/summary.md new file mode 100644 index 0000000..9b915a6 --- /dev/null +++ b/docs/summary.md @@ -0,0 +1,20 @@ +# M17 RF Protocol: Summary + +M17 is an RF protocol that is: + +* Completely open: open specification, open source code, open source hardware, open algorithms. Anyone must be able to build an M17 radio and interoperate with other M17 radios without having to pay anyone else for the right to do so. +* Optimized for amateur radio use. +* Simple to understand and implement. +* Capable of doing the things hams expect their digital protocols to do: + * Voice (eg: DMR, D-Star, etc) + * Point to point data (eg: Packet, D-Star, etc) + * Broadcast telemetry (eg: APRS, etc) + * Extensible, so more capabilities can be added over time. + +To do this, the M17 protocol is broken down into three protocol layers, like a network: + +* Physical Layer: How to encode 1s and 0s into RF. Specifies RF modulation, symbol rates, bits per symbol, etc. +* Data Link Layer: How to packetize those 1s and 0s into usable data. Packet vs Stream modes, headers, addressing, etc. +* Application Layer: Accomplishing activities. Voice and data streams, control packets, beacons, etc. + +This document attempts to document these layers. \ No newline at end of file diff --git a/docs/summary.rst b/docs/summary.rst deleted file mode 100644 index 6147540..0000000 --- a/docs/summary.rst +++ /dev/null @@ -1,39 +0,0 @@ -M17 RF Protocol: Summary -======================== - -M17 is an RF protocol that is: - -* Completely open: open specification, open source code, open source - hardware, open algorithms. Anyone must be able to build an M17 radio - and interoperate with other M17 radios without having to pay anyone - else for the right to do so. -* Optimized for amateur radio use. -* Simple to understand and implement. -* Capable of doing the things hams expect their digital protocols to - do: - - * Voice (eg: DMR, D-Star, etc) - * Point to point data (eg: Packet, D-Star, etc) - * Broadcast telemetry (eg: APRS, etc) - * Extensible, so more capabilities can be added over time. - -To do this, the M17 protocol is broken down into three protocol layers, like a network: - -#. Physical Layer: How to encode 1s and 0s into RF. Specifies RF - modulation, symbol rates, bits per symbol, etc. -#. Data Link Layer: How to packetize those 1s and 0s into usable - data. Packet vs Stream modes, headers, addressing, etc. -#. Application Layer: Accomplishing activities. Voice and data - streams, control packets, beacons, etc. - -This document attempts to document these layers. - -.. [TETRA] Dunlop, John; Girma, Demessie; Irvine, James "Digital - Mobile Communications and the TETRA System" Wiley 1999, - ISBN: 9780471987925 - -.. [DMR] ETSI TS 102 361-1 V2.2.1 (2013-02): "Electromagnetic - compatibility and Radio spectrum Matters (ERM); Digital - Mobile Radio (DMR) Systems; Part 1: DMR Air Interface (AI) - protocol" - https://www.etsi.org/deliver/etsi_ts/102300_102399/10236101/02.02.01_60/ts_10236101v020201p.pdf diff --git a/images/LFSR_16.pdf b/images/LFSR_16.pdf deleted file mode 100644 index 5a5d37d..0000000 Binary files a/images/LFSR_16.pdf and /dev/null differ diff --git a/images/LFSR_24.pdf b/images/LFSR_24.pdf deleted file mode 100644 index 8a5fc31..0000000 Binary files a/images/LFSR_24.pdf and /dev/null differ diff --git a/images/LFSR_8.pdf b/images/LFSR_8.pdf deleted file mode 100644 index 8ea8165..0000000 Binary files a/images/LFSR_8.pdf and /dev/null differ diff --git a/images/M17_framing.ods b/images/M17_framing.ods deleted file mode 100644 index 9db00c4..0000000 Binary files a/images/M17_framing.ods and /dev/null differ diff --git a/images/M17_stream.svg b/images/M17_stream.svg deleted file mode 100644 index af878ce..0000000 --- a/images/M17_stream.svg +++ /dev/null @@ -1,669 +0,0 @@ - - - - - - - - - - image/svg+xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 40ms - 40ms - 40ms - 40ms - 40ms - 40ms - 40ms - PREAMBLE - LSF_SYNC - LSF - FRAME_SYNC - FRAME_DATA - FRAME_SYNC - FRAME_DATA - FRAME_SYNC - FRAME_DATA - FRAME_SYNC - FRAME_DATA - FRAME_SYNC - FRAME_DATA - FRAME_SYNC - FRAME_DATA - LINK SETUP - FRAME 1 - FRAME 2 - FRAME 3 - FRAME 4 - FRAME 5 - FRAME 6 - SUPERFRAME 1 - ≥ - 40ms - - diff --git a/images/convolutional.pdf b/images/convolutional.pdf deleted file mode 100644 index ece29ce..0000000 Binary files a/images/convolutional.pdf and /dev/null differ diff --git a/images/dibits_modulator.pdf b/images/dibits_modulator.pdf deleted file mode 100644 index 787ef09..0000000 Binary files a/images/dibits_modulator.pdf and /dev/null differ diff --git a/images/dibits_modulator.svg b/images/dibits_modulator.svg deleted file mode 100644 index ab86589..0000000 --- a/images/dibits_modulator.svg +++ /dev/null @@ -1,211 +0,0 @@ - - - - - - - - - - - - image/svg+xml - - - - - - - - - RRCFilter - - FrequencyModulator - DibitsInput - 4FSKOutput - - diff --git a/images/end-to-end-delay.pdf b/images/end-to-end-delay.pdf deleted file mode 100644 index 577ac19..0000000 Binary files a/images/end-to-end-delay.pdf and /dev/null differ diff --git a/images/end-to-end-delay.png b/images/end-to-end-delay.png deleted file mode 100644 index d44bbbc..0000000 Binary files a/images/end-to-end-delay.png and /dev/null differ diff --git a/images/end-to-end-delay.svg b/images/end-to-end-delay.svg deleted file mode 100644 index eb2d533..0000000 --- a/images/end-to-end-delay.svg +++ /dev/null @@ -1,899 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - image/svg+xml - - - - - - - - Speechframe - Speechframe - Speechframe - Speechframe - Speechframe - Speechframe - Speechframe - - Speechframe - - - - - - - - Encoding - - - - Transmission - - - Transmission - Transmission - Reception - Reception - Reception - - - Decoding - - - Speechframe - - Speechframe - - - Speechframe - Speechframe - - - Speechframe - - - - End-to-end delay - - - - - - diff --git a/images/frame_encoding.pdf b/images/frame_encoding.pdf deleted file mode 100644 index 322a274..0000000 Binary files a/images/frame_encoding.pdf and /dev/null differ diff --git a/images/link_setup_frame_encoding.pdf b/images/link_setup_frame_encoding.pdf deleted file mode 100644 index 8ccd18a..0000000 Binary files a/images/link_setup_frame_encoding.pdf and /dev/null differ diff --git a/images/m17_logo_shadow.pdf b/images/m17_logo_shadow.pdf deleted file mode 100644 index 1094b74..0000000 Binary files a/images/m17_logo_shadow.pdf and /dev/null differ diff --git a/images/m17_logo_shadow_400.png b/images/m17_logo_shadow_400.png deleted file mode 100644 index f5c7ead..0000000 Binary files a/images/m17_logo_shadow_400.png and /dev/null differ diff --git a/kickstart b/kickstart deleted file mode 100644 index 9a86819..0000000 --- a/kickstart +++ /dev/null @@ -1 +0,0 @@ -23 SEP 2020 13:49 \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..6c35356 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,31 @@ +site_name: M17 Protocol Specification +plugins: + - mermaid2 +markdown_extensions: + - extra + - tables + - mdx_math: + enable_dollar_delimiter: True + - fenced_code + - admonition +extra_javascript: + - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.4/MathJax.js?config=TeX-AMS-MML_HTMLorMML +theme: + name: readthedocs + logo: img/m17_logo_shadow.svg +nav: + - Home: 'index.md' + - 'Part I: Air and IP Interface': + - Summary: 'summary.md' + - Glossary: 'glossary.md' + - Physical Layer: 'physical_layer.md' + - Data Link Layer: 'data_link_layer.md' + - Application Layer: 'application_layer.md' + - 'Part II: Codeplug': + - Recommendation for the Codeplug Structure: 'codeplug.md' + - Appendix: + - Address Encoding: 'address_encoding.md' + - Decorrelator Sequence: 'decorrelator.md' + - Interleaving: 'interleaving.md' + - M17 IP Networking: 'ip_networking.md' + - KISS Protocol: 'kiss_protocol.md' \ No newline at end of file