From ccc4e452ffaab3cdcf5f6f6a714a012e9c68cd7e Mon Sep 17 00:00:00 2001
From: Thomas Kolb <cfr34k-git@tkolb.de>
Date: Sat, 27 Apr 2024 23:35:45 +0200
Subject: [PATCH] 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]