From be0cac13c14bff13c203eee597f45146f97905c7 Mon Sep 17 00:00:00 2001
From: Thomas Kolb <cfr34k-git@tkolb.de>
Date: Thu, 25 Apr 2024 22:16:25 +0200
Subject: [PATCH] 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.