From c61a7a7cf75f8315f0b1a1dd8b3519a5d8f82383 Mon Sep 17 00:00:00 2001
From: Thomas Kolb <cfr34k-git@tkolb.de>
Date: Fri, 30 Aug 2024 23:46:47 +0200
Subject: [PATCH] doc: start documenting the Layer 2 packets (WIP)

---
 doc/hamnet70.adoc | 153 +++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 152 insertions(+), 1 deletion(-)

diff --git a/doc/hamnet70.adoc b/doc/hamnet70.adoc
index 21189d3..031bd3f 100644
--- a/doc/hamnet70.adoc
+++ b/doc/hamnet70.adoc
@@ -254,6 +254,157 @@ They therefore do not have a _TX sequence number_; this field is reserved and mu
 
 The _RX sequence number_ and all other header fields are used as usual.
 
+==== Connection Management
+
+Connection Management Frames control the Layer 2 connection between a client and the digipeater.
+They are especially important for connect and disconnect procedures.
+
+Connection Management Frames have at least one byte in the data field: the type of the management packet.
+The following types are defined:
+
+[cols="1,2,5", options="header"]
+.Connection Management Types
+|===
+|Type Indicator
+|Sent by
+|Description
+
+|`0x00`
+|Digipeater
+|Beacon
+
+|`0x01`
+|Client
+|Connection Request
+
+|`0x02`
+|Digipeater
+|Connection Parameters
+
+|`0x03`
+|Digipeater
+|Connection Reset
+
+|`0x04`
+|Digipeater
+|Disconnect Request
+
+|`0x05`
+|Client
+|Disconnect
+|===
+
+===== Beacons
+
+Beacons are sent periodically by the digipeater to show it’s presence to potential new clients.
+
+The layer 2 header is filled as follows:
+
+- Message Type: `001` (Connection Management)
+- TX Request: `1`
+- Source Address: the digipeater’s HAM-64 address
+- Destination Address: the HAM-64 broadcast address
+- TX sequence number: reserved, always 0
+- RX sequence number: reserved, always 0
+
+The message contains exactly 1 data byte: `0x00` to indicate that this is a Beacon packet.
+
+A Beacon packet shall always be sent as the last or only packet in a burst.
+After a Beacon is sent by the digipeater it listens for a short time for Connection Requests from new clients.
+A new client that intends to connect shall send the Connection Request as soon as possible after the beacon transmission ends.
+
+===== Connection Request
+
+A Connection Request is sent by a client that intends to connect to a digipeater.
+
+The layer 2 header is filled as follows:
+
+- Message Type: `001` (Connection Management)
+- TX Request: `1`
+- Source Address: the new client’s HAM-64 address
+- Destination Address: the digipeater’s HAM-64 address
+- TX sequence number: reserved, always 0
+- RX sequence number: reserved, always 0
+
+The message contains exactly 1 data byte: `0x01` to indicate that this is a Connection Request packet.
+
+A Connection Request is always a response to a Beacon packet.
+It shall be the only packet in a burst.
+
+When the digipeater receives a Connection Request it has two options for a response:
+
+. Accept the connection by sending a Connection Parameters packet to the client in the next burst.
+. Reject the connection by sending a Connection Reset packet to the client in the next burst.
+
+===== Connection Parameters
+
+The Connection Parameters packet has two functions: it indicates to a client that its Connection Request was accepted and tells it how to configure its network stack.
+This is the first packet in the regular Go-back-N data flow.
+
+The layer 2 header is filled as follows:
+
+- Message Type: `001` (Connection Management)
+- TX Request: `1`
+- Source Address: the digipeater’s HAM-64 address
+- Destination Address: the new client’s HAM-64 address
+- TX sequence number: 0 (the first packet)
+- RX sequence number: 0 (no packets received yet)
+
+The type indicator is `0x02`.
+
+After the type indicator follow one or more configuration blocks.
+Each block consists of three data fields:
+
+. Configuration Type: 1 byte
+. Configuration Data Length: 1 byte
+. Configuration data: variable number of bytes as indicated by Configuration Data Length
+
+The following Configuration Types are defined:
+
+[cols="1,1,5", options="header"]
+.Configuration Types
+|===
+|Type Indicator
+|Length
+|Description
+
+|`0x00`
+|16 Byte
+|IPv6 address
+
+|`0x01`
+|16 Byte
+|IPv6 gateway
+
+|`0x02`
+|16 Byte
+|IPv6 DNS server (may appear multiple times)
+
+|`0x03` - `0x07`
+|-
+|_reserved_
+
+|`0x08`
+|4 Byte
+|IPv4 address
+
+|`0x09`
+|4 Byte
+|IPv4 gateway
+
+|`0x0A`
+|4 Byte
+|IPv4 DNS server (may appear multiple times)
+
+|`0x0B` - `0xFF`
+|-
+|_reserved_
+
+|===
+
+If the client receives an unknown Configuration Type the corresponding block shall be skipped.
+The remaining blocks shall be parsed as usual.
+
 === Ideas
 
 To be defined:
@@ -290,7 +441,7 @@ msc {
 	digi box client [label="Connection established"];
 
 	--- [label="Alternative 2: Connection is rejected"];
-	digi -> client [label="Connection Refusal"];
+	digi -> client [label="Connection Reset"];
 }
 ....