From 6ea82435212e35e0bf5e4c44c9777d76ceb5c268 Mon Sep 17 00:00:00 2001 From: Thomas Kolb Date: Thu, 25 Apr 2024 22:16:25 +0200 Subject: [PATCH 1/9] Starting to write the documentation with AsciiDoc --- doc/.gitignore | 2 + doc/hamnet70.adoc | 110 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 112 insertions(+) create mode 100644 doc/.gitignore create mode 100644 doc/hamnet70.adoc diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..23f832b --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1,2 @@ +*.html +*.pdf diff --git a/doc/hamnet70.adoc b/doc/hamnet70.adoc new file mode 100644 index 0000000..d67a755 --- /dev/null +++ b/doc/hamnet70.adoc @@ -0,0 +1,110 @@ += Hamnet70: IP-based networking in the 70 cm amateur radio band +Thomas Kolb DL5TKL +0.1, 2024-04-25 +:toc: + +== Introduction + +== General Notes + +All data is transmitted in network byte order (big endian = MSB first). + +== Layer 1: Physical Layer + +The Physical Layer (PHY) is responsible for encoding a Layer 2 packet such that +it can be transmitted over the air. Therefore, it encodes and modulates the +data, and adds a fixed preamble to aid synchronization to the signal. +Additionally, a mechanism is defined that allows to group packets in a „burst“, +which reduces overhead. + +=== PHY Packet Format + +A packet encoded by the PHY consists of the following blocks: + +. Preamble: a fixed symbol sequence that the receiver can use to determine the start time, frequency and phase offset of the following data. +. PHY header: contains information about the packet length and modulation/coding scheme. +. Data symbols: encoded and modulated data. + +==== Preamble + +The preamble is a fixed 63-bit sequence generated from a linear feedback shift register with 6 bits and the generator polynomial stem:[x^6 + x^5 + 1]. + +The generated sequence is: `111000101111001010001100001000001111110101011001101110110100100`. + +This sequence is modulated using BPSK. + +The preamble is prefixed to each transmitted packet, even inside a burst. + +==== PHY Header + +The PHY header describes how the following data symbols should be interpreted. It consists of the following fields: + +. Modulation/code combination ID (MODCOD): 4 bit +. Number of data symbols: 12 bit +. CRC16 of the raw layer 2 packet data: 16 bit +. CRC8 of the previous 32 header bits: 8 bit + +Therefore the PHY header has as size of 40 bit, including CRC. + +For additional protection, the header in encoded using a [8,4] Hamming code, which can reliably correct single-bit errors and detect double-bit errors in every block of four bits. + +The encoded data is always modulated using QPSK. + +===== Modulation/code combinations + +The following table lists all supported combinations of modulation and forward error correction. + +[options="header"] +.Supported modulation/code combinations +|=== +| ID (binary) | Modulation | Channel Code + +| 0000 +| 16-QAM +| Punctured convolutional code: stem:[r=3/4], stem:[K=7] + +| 0001 +| QPSK +| Punctured convolutional code: stem:[r=3/4], stem:[K=7] + +| _others_ +| _reserved_ +| _reserved_ +|=== + +==== Data modulation + +The first data symbol follows directly after the last symbol of the PHY header. The data is encoded and modulated using the scheme defined in the PHY header’s MODCOD field. The number of symbols resulting from the encoding and modulation process is stored in the PHY header as well. + +=== Burst Transmission + +Burst transmission allows the transmitter to send multiple packets in quick succession. + +tbd. + +=== Pulse Forming + +Pulse forming is applied to control the bandwidth of the transmitted signal and to reduce inter-symbol interference at the receiver. + +This system uses Root Raised Cosine (RRC) filters with a roll-off factor of stem:[alpha=0.2]. Therefore the bandwidth is 1.2 times the symbol rate. + +The filter is applied to the whole symbol sequence of the burst. The same filter must be applied at the receiver to minimize inter-symbol interference. + +== Layer 2: Link Layer + +== Higher Layer Protocols + +[appendix] +== Modulation Details + +=== BPSK + +In binary phase shift keying, a `1` bit is sent as +1.0 and a `0` bit is sent as -1.0. + +=== QPSK + +tbd. + +=== 16-QAM + +tbd. -- 2.44.2 From d7861425c7ddae38b752c2c0b3f8865e3c8b4fe2 Mon Sep 17 00:00:00 2001 From: Thomas Kolb Date: Sat, 27 Apr 2024 22:40:44 +0200 Subject: [PATCH 2/9] doc: document burst format --- doc/hamnet70.adoc | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/doc/hamnet70.adoc b/doc/hamnet70.adoc index d67a755..a39a13e 100644 --- a/doc/hamnet70.adoc +++ b/doc/hamnet70.adoc @@ -17,6 +17,7 @@ data, and adds a fixed preamble to aid synchronization to the signal. Additionally, a mechanism is defined that allows to group packets in a „burst“, which reduces overhead. +[#phy_packet_format] === PHY Packet Format A packet encoded by the PHY consists of the following blocks: @@ -80,11 +81,24 @@ The first data symbol follows directly after the last symbol of the PHY header. Burst transmission allows the transmitter to send multiple packets in quick succession. -tbd. +A burst consists of the following elements: + +. Ramp-up sequence +. Pre-packet idle sequence (optional) +. One or more packets as defined in <> +. Ramp-down sequence + +The ramp-up, ramp-down and idle sequences consist of alternating +1/-1 BPSK symbols. + +During ramp-up, their amplitude stem:[A_u(k)] is scaled up across stem:[L_u] symbols, following the curve stem:[A_u(k) = sin(π/2 * k / L_u)]. Ramp-down follows a similar sinusoidal for stem:[L_d] symbols: stem:[A_d(k) = cos(π/2 * k / L_d)]. The purpose of these sequences is to avoid splatter while turning on and off the transmitted signal. + +During the pre-packet idle sequence, the alternating BPSK symbols are continued with constant amplitude 1.0. This sequence may help synchronizers acquire the signal better (especially the gain and timing regulation can benefit), but is not needed if they are fast enough. If and how this part is used is still to be determined. + +Each packet in a burst includes a preamble. Packets are directly concatenated, i.e. after the last data symbol follows the first preamble symbol. === Pulse Forming -Pulse forming is applied to control the bandwidth of the transmitted signal and to reduce inter-symbol interference at the receiver. +Pulse forming is applied to limit the bandwidth of the transmitted signal and to reduce inter-symbol interference at the receiver. This system uses Root Raised Cosine (RRC) filters with a roll-off factor of stem:[alpha=0.2]. Therefore the bandwidth is 1.2 times the symbol rate. @@ -99,7 +113,7 @@ The filter is applied to the whole symbol sequence of the burst. The same filter === BPSK -In binary phase shift keying, a `1` bit is sent as +1.0 and a `0` bit is sent as -1.0. +In binary phase shift keying, a `1` bit is sent as -1.0 and a `0` bit is sent as +1.0. === QPSK -- 2.44.2 From 66d41a3eb3cb5412d97bc044547abf0f1faa0e49 Mon Sep 17 00:00:00 2001 From: Thomas Kolb Date: Sat, 27 Apr 2024 23:35:45 +0200 Subject: [PATCH 3/9] doc: start defining the layer 2 --- doc/hamnet70.adoc | 80 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) diff --git a/doc/hamnet70.adoc b/doc/hamnet70.adoc index a39a13e..69b6f66 100644 --- a/doc/hamnet70.adoc +++ b/doc/hamnet70.adoc @@ -106,6 +106,86 @@ The filter is applied to the whole symbol sequence of the burst. The same filter == Layer 2: Link Layer +The Hamnet70 link layer is designed to ensure reliable communication between a central station (digipeater) and several clients, while making efficient use of the available airtime. To accomplish this, it uses several technologies, including variable-length addressing and Go-Back-N retransmission. + +=== Node Addresses + +Node addresses use the https://github.com/arngll/arnce-spec/blob/main/n6drc-arnce.md#introduction[HAM-64 address format]. This format allows to encode callsigns of up to 12 characters in a number of 16, 32, 48 or 64 bits. Additionally, it allows to replace the full version of an address with a temporary short address with only 16 bits that is used during a connection. Multicast and broadcast addresses are also specified. + +=== Link Layer Header + +Each layer 2 packet contains a header that identifies how the message should be interpreted. It is of variable length and composed as follows: + +[cols="2,1,5", options="header"] +.Link layer header layout +|=== +| Field | Length | Description + +| Message type +| 3 bit +| The type of the message. See below for a list of values. + +| TX request +| 1 bit +| After this message, the burst ends and the destination may transmit. + +| Source address length +| 2 bit +| Length of the source address. + +| Destination address length +| 2 bit +| Length of the destination address. + +| TX sequence number +| 4 bit +| Sequence number of the currently transmitted packet. + +| RX sequence number +| 4 bit +| Sequence number of the packet expected next. + +| Source address +| 16, 32, 48 or 64 bit +| HAM-64 address identifying the sending station. + +| Destination address length +| 16, 32, 48 or 64 bit +| HAM-64 address identifying the target station. +|=== + +The total Link Layer Header length is therefore at least 6 byte and at most 18 byte. + +[cols="1,2,5", options="header"] +.Message types +|=== +| Value | Name | Description + +| `000` +| Data frame +| A regular data packet. + +| `100` +| Connection management +| Includes functions such as establishing (or denying) new connections or closing open connections. + +| _other_ +| _reserved_ +| All values not explicitly listed are reserved and shall be ignored by receivers. + +|=== + +The length of the source and destination addresses is encoded as follows: `00` = 16 bit, `01` = 32 bit, `10` = 48 bit, `11` = 64 bit. + +=== Ideas + +To be defined: +- connection establishment procedure (request, response) +- when are new clients allowed to connect? +- handling of packets from unknown clients that are not connection requests +- signal quality handling +- go-back-N algorithm (maybe dynamic burst length depending on previous packet loss?) + == Higher Layer Protocols [appendix] -- 2.44.2 From d73c2bd5b5f81a049290ff54893b68853d3ac854 Mon Sep 17 00:00:00 2001 From: Thomas Kolb Date: Sun, 28 Apr 2024 14:01:47 +0200 Subject: [PATCH 4/9] doc: document data whitening procedure --- doc/hamnet70.adoc | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/doc/hamnet70.adoc b/doc/hamnet70.adoc index 69b6f66..b982960 100644 --- a/doc/hamnet70.adoc +++ b/doc/hamnet70.adoc @@ -73,7 +73,19 @@ The following table lists all supported combinations of modulation and forward e | _reserved_ |=== -==== Data modulation +==== Data Whitening + +The IP packets transferred by Hamnet70 may contain long sequences of identical bytes (think of the zeros in the middle of IPv6 addresses), which make it hard to keep the system synchronized. To prevent the transmission of many identical symbols in a row, the data is whitened using a pseudo-random sequence. + +Here, a 9-bit linear feedback shift register (LFSR) according to the CCITT specification is used to generate the pseudo-random sequence. The generator polynomial is stem:[x^9 + x^5 + 1]. The data is whitened by XORing data bytes with the _whitening key_ generated from the LFSR. + +The whitening key is generated by taking the LSB of the LFSR state, and shifting it into an 8-bit register from the right. Then the LFSR is advanced and the process is repeated. Every 8 repetitions the contents of the 8-bit register are XORed with a data byte to calculate the whitened data. + +To remove the whitening, the same procedure is applied to the whitened data at the receiver side. XORing with the same sequence results in the original data. + +Whitening is only applied to the layer 2 packet data, but not the PHY header. + +==== Data Modulation The first data symbol follows directly after the last symbol of the PHY header. The data is encoded and modulated using the scheme defined in the PHY header’s MODCOD field. The number of symbols resulting from the encoding and modulation process is stored in the PHY header as well. -- 2.44.2 From 2d70c344e6e848a1125c08bea77e5ead1f6e1f89 Mon Sep 17 00:00:00 2001 From: Thomas Kolb Date: Sun, 28 Apr 2024 14:02:58 +0200 Subject: [PATCH 5/9] doc: added Makefile --- doc/Makefile | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 doc/Makefile diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..345abee --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,2 @@ +hamnet70.html: hamnet70.adoc + asciidoctor $< -- 2.44.2 From 5150c3bc14faf4d6a844a5f11ea94a3cb614743d Mon Sep 17 00:00:00 2001 From: Thomas Kolb Date: Tue, 30 Apr 2024 21:47:19 +0200 Subject: [PATCH 6/9] doc: automatic packet repetition algorithm --- doc/hamnet70.adoc | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/doc/hamnet70.adoc b/doc/hamnet70.adoc index b982960..61fd2e1 100644 --- a/doc/hamnet70.adoc +++ b/doc/hamnet70.adoc @@ -118,7 +118,7 @@ The filter is applied to the whole symbol sequence of the burst. The same filter == Layer 2: Link Layer -The Hamnet70 link layer is designed to ensure reliable communication between a central station (digipeater) and several clients, while making efficient use of the available airtime. To accomplish this, it uses several technologies, including variable-length addressing and Go-Back-N retransmission. +The Hamnet70 link layer is designed to ensure reliable communication between a central station (digipeater) and several clients, while making efficient use of the available airtime. To accomplish this, it uses several technologies, including variable-length addressing and automatic repetition of packets that could not be decoded. === Node Addresses @@ -189,6 +189,22 @@ The total Link Layer Header length is therefore at least 6 byte and at most 18 b The length of the source and destination addresses is encoded as follows: `00` = 16 bit, `01` = 32 bit, `10` = 48 bit, `11` = 64 bit. +=== Automatic Packet Repetition + +Lost packets are automatically repeated in Hamnet70. As the system is also designed for high throughput, it uses the Go-Back-N algorithm to handle this. The algorithm is described in this section. + +Both the digipeater and the client send two sequence numbers with each packet. + +The _TX sequence number_ is the number of the current packet. It uniquely identifies that packet at the time it is transmitted. The _TX sequence number_ is incremented (with overflow) with each new packet that is sent. + +The _RX sequence number_ is the packet number the sending station expects to see next from the other side. It is incremented when a packet with this expected sequence number is decoded successfully. Received packets with other sequence numbers than the expected one must be dropped. + +Example: The two stations A and B just connected and expect to see sequence number 0 from each other. Station A transmits a burst with three packets: P0, P1, P2. Station B decodes packet P0 and increases the expected number to 1. P1 is not decoded due to noise and therefore lost. P2 is again decoded, but is dropped because its sequence number is 2 and not the expected 1. In its transmission cycle, station B tells station A that it expects P1 next. Station A therefore _goes back to_ P1 in its transmission queue and starts transmitting all packets after P1 again. + +As the sequence numbers in Hamnet70 have 4 bits, up to 15 packets can be transmitted in a burst before the numbers become ambiguous. + +Due to the long possible bursts, this system can achieve high throughput if there is low packet loss. However, it can also become very slow if many packets are lost because all packets after the first error have to be repeated. Therefore it might be a good idea to adjust the burst length depending on the packet loss and send smaller bursts if only few packets go through. + === Ideas To be defined: -- 2.44.2 From 76da14fa5cbc2b4c2fe2ae3406ca99493aa3eff9 Mon Sep 17 00:00:00 2001 From: Thomas Kolb Date: Wed, 1 May 2024 10:40:51 +0200 Subject: [PATCH 7/9] doc: minor clarifications --- doc/hamnet70.adoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/hamnet70.adoc b/doc/hamnet70.adoc index 61fd2e1..804531c 100644 --- a/doc/hamnet70.adoc +++ b/doc/hamnet70.adoc @@ -47,16 +47,16 @@ The PHY header describes how the following data symbols should be interpreted. I Therefore the PHY header has as size of 40 bit, including CRC. -For additional protection, the header in encoded using a [8,4] Hamming code, which can reliably correct single-bit errors and detect double-bit errors in every block of four bits. +For additional protection, the header is encoded using a [8,4] Hamming code, which can reliably correct single-bit errors and detect double-bit errors in every block of four bits. -The encoded data is always modulated using QPSK. +The PHY header is always modulated using QPSK. ===== Modulation/code combinations -The following table lists all supported combinations of modulation and forward error correction. +The following table lists all supported combinations of modulation and forward error correction for the packet data. [options="header"] -.Supported modulation/code combinations +.Supported packet data modulation/code combinations (MODCODs) |=== | ID (binary) | Modulation | Channel Code @@ -91,7 +91,7 @@ The first data symbol follows directly after the last symbol of the PHY header. === Burst Transmission -Burst transmission allows the transmitter to send multiple packets in quick succession. +Packets are transmitted in bursts which combine multiple packets in a contiguous transmission. A burst consists of the following elements: -- 2.44.2 From a85487f53464853683b79716f0fe96a042fee477 Mon Sep 17 00:00:00 2001 From: Thomas Kolb Date: Thu, 2 May 2024 20:53:16 +0200 Subject: [PATCH 8/9] doc: define connectionless frame type --- doc/hamnet70.adoc | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/doc/hamnet70.adoc b/doc/hamnet70.adoc index 804531c..97e1d27 100644 --- a/doc/hamnet70.adoc +++ b/doc/hamnet70.adoc @@ -91,7 +91,7 @@ The first data symbol follows directly after the last symbol of the PHY header. === Burst Transmission -Packets are transmitted in bursts which combine multiple packets in a contiguous transmission. +Packets are transmitted in bursts which can combine multiple packets in a contiguous transmission. A burst consists of the following elements: @@ -175,12 +175,16 @@ The total Link Layer Header length is therefore at least 6 byte and at most 18 b | `000` | Data frame -| A regular data packet. +| A regular data packet (inside a connection). -| `100` +| `001` | Connection management | Includes functions such as establishing (or denying) new connections or closing open connections. +| `100` +| Connectionless frame +| A data packet that is sent outside of a connection. + | _other_ | _reserved_ | All values not explicitly listed are reserved and shall be ignored by receivers. @@ -212,7 +216,6 @@ To be defined: - when are new clients allowed to connect? - handling of packets from unknown clients that are not connection requests - signal quality handling -- go-back-N algorithm (maybe dynamic burst length depending on previous packet loss?) == Higher Layer Protocols -- 2.44.2 From 6494c699820fc5b2974b341984b262b5a0f47ec7 Mon Sep 17 00:00:00 2001 From: Thomas Kolb Date: Thu, 2 May 2024 21:05:40 +0200 Subject: [PATCH 9/9] doc: moved CRC from layer 1 to layer 2 --- doc/hamnet70.adoc | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/doc/hamnet70.adoc b/doc/hamnet70.adoc index 97e1d27..598738d 100644 --- a/doc/hamnet70.adoc +++ b/doc/hamnet70.adoc @@ -42,10 +42,9 @@ The PHY header describes how the following data symbols should be interpreted. I . Modulation/code combination ID (MODCOD): 4 bit . Number of data symbols: 12 bit -. CRC16 of the raw layer 2 packet data: 16 bit -. CRC8 of the previous 32 header bits: 8 bit +. CRC8 of the previous 16 header bits: 8 bit -Therefore the PHY header has as size of 40 bit, including CRC. +Therefore the PHY header has as size of 24 bit, including CRC. For additional protection, the header is encoded using a [8,4] Hamming code, which can reliably correct single-bit errors and detect double-bit errors in every block of four bits. @@ -120,6 +119,16 @@ The filter is applied to the whole symbol sequence of the burst. The same filter The Hamnet70 link layer is designed to ensure reliable communication between a central station (digipeater) and several clients, while making efficient use of the available airtime. To accomplish this, it uses several technologies, including variable-length addressing and automatic repetition of packets that could not be decoded. +=== Frame Structure + +The link layer frame consist of three elements, as follows: + +. The <<_link_layer_header,link layer header>> +. A variable amount of data, depending on the packet type +. CRC16 of all previous bytes, including the link layer header + +The CRC16 is calculated using the generator polynomial stem:[x^15 + x^2 + 1]. + === Node Addresses Node addresses use the https://github.com/arngll/arnce-spec/blob/main/n6drc-arnce.md#introduction[HAM-64 address format]. This format allows to encode callsigns of up to 12 characters in a number of 16, 32, 48 or 64 bits. Additionally, it allows to replace the full version of an address with a temporary short address with only 16 bits that is used during a connection. Multicast and broadcast addresses are also specified. -- 2.44.2