Added another packet desc file

Author: Tom Early

M17-ref-packet-description.ods

@@ -0,0 +1,63 @@
+# TCP packets sent to or from *mrefd*
+
+## 1. Introduction
+
+All packets begin with a 4-byte ASCII sequence of character sometimes called *magic*. This magic is make up from uppercase letters with possibly a space, ` ` in the 4th position. Some packets are just made up of 4-byte magic, they contain nothing else. All other packets have addition data following the magic. All possible *mrefd* packet sizes are 4, 10, 11, 37, 54, or 55 bytes. The two largest packets have a magic of `M17 `. These are the only packets that have a magic that contains a space. The 54-byte version is the streaming voice packet described in Section 4 of the [M17 Specification](https://github.com/M17-Project/M17_spec) and is used between the *mrefd* server and all simple clients. The 55-byte is also a streaming voice packet but used between interlinked *mrefd* instances. This packet is just like the server-client 54-byte packet but contains an additional byte used by interlinked reflectors to ensure proper routing in large, *i.e.*, greater than two, interlinked groups of reflectors. These packets are represented in the `Packet.h` file in this repository. These voice packets will not be further discussed in this document.
+
+## 2. Packet types
+
+All other packet are made up of one, two or three parts:
+
+1. **Magic:** a 4-byte magic sequence. In addtion to `M17 `, magic can be `ACKN`, `CONN`, `DISC`, `LSTN`, `NACK`, `PING` or `PONG`.
+2. **Encoded Callsign:** This is a 6-byte encoded callsign. This will be the encoded callsign of either an *mrefd* reflector or the callsign of the sending client.  See the *Address Encoding* appendix of the [M17 Specification](https://github/M17-Project/M17_spec).
+3. **Module(s):** This is either a single byte, an ASCII character from 'A' to 'Z' designating a reflector module, or a null-terminated string that is a list of possible reflector modules. A reflector can have up to 26 modules so, in this case, this third piece of the packet is 27 bytes in length in order to accommodate the maximum length possible.
+
+## 3. Packet Descriptions
+
+### 3.1 `ACKN` is used to acknowledge a link or interlink request
+
+A one-part simple 4-byte acknowledgement is send by *mrefd* to a simple client and acknowledges that the client has successfully linked. Keep alive packets will commence immediately.
+
+A three-part 37-byte acknowledgement is used to acknowledge an *mrefd* interlink request. The encoded callsign is the designation of the responding *mrefd* instance. A null-terminated list of modules that are now interlinked is included.
+
+### 3.2 `CONN` is used to initiate a link or interlink request
+
+A three-part packet is sent to initiate a link or interlink. There are two scenarios:
+
+1. A simple client is requesting to link with a specific *mrefd* module. The 11-byte packet include the encoded callsign of the requesting client, followed by the *mrefd* module to which it wants to link.
+2. A reflector is requesting an interlink with another reflector. The 37-byte packet includes the encoded callsign from the requesting reflector and a null-terminated list of modules to which it wants to interlink.
+
+Please note that a reflector-reflector interlink must be configured in the interlink file on both reflectors, and the configured interlinked modules have to be identical.
+
+### 3.3 `DISC` is used to initiate a disconnection
+
+A two-part 10-byte packet is used to initiate a disconnection. The encoded callsign is the encoded callsign of the node initiating the request. There are three scenarios:
+
+1. A client will send this to *mrefd* because the user has initiated an unlink command.
+2. A simple client will receive this from a linked *mrefd* if the client has recently been added to the reflector's blacklist.
+3. A reflector will send this to an interlinked reflector if the reflector has recently been removed from the interlink file, or if the connection parameters have been changed.
+
+A single-part 4-byte packet is send from *mrefd* to acknowledge an incoming `DISC` request from a simple client.
+
+### 3.4 `LSTN` is used to initiate a listen-only client
+
+A three-part 11-byte packet is used to initiate a listen-only client. THis is identical to what a simple client would use, but the endcoded callsign is more permissive.
+
+### 3.5 `NACK` is the "not acknowledgement"
+
+A one-part packet is used to refuse a connection, `CONN`, request. There are two scenarios:
+
+1. A simple client can receive this when trying to initiate a link with *mrefd*. Either the client is requesting a module that doesn't exist, or the client is listed in the blacklist.
+2. A reflector can receive this from another reflector if the requested connection is not listed or the requested modules are different.
+
+### 3.6 `PING` is the keep-alive packet
+
+A one-part packet is used by *mrefd* as a keep-alive packet to all connected nodes, both simple clients and other interlinked reflectors. It will be sent approximately every 3 seconds. If a node hasn't received a `PING` in the last 30 seconds, it can assume the reflect has stopped working.
+
+### 3.7 `PONG` is the keep-alive response
+
+A one-part packet is used by simple clients to let the connected reflector that it's alive. If the reflector has not received a `PONG` packet for at least 30 seconds, it will be disconnected.
+
+There is no `PONG` response for a reflector-reflector interlink. Both sides send `PING` packets every 3 seconds.
+
+#### Copyright (c) 2025 by Thomas A. Early N7TAE

Packet-Description.md

@@ -33,8 +33,8 @@
 using SM17Lich = struct __attribute__((__packed__)) lich_tag {
 	uint8_t  addr_dst[6];
 	uint8_t  addr_src[6];
-	uint16_t frametype; //frametype flag field per the M17 spec
-	uint8_t  nonce[14]; //bytes for the nonce
+	uint16_t frametype;      //frametype flag field per the M17 spec
+	uint8_t  meta_data[14];  //bytes for the meta data, as described in the M17 spec
 }; // 6 + 6 + 2 + 14 = 28 bytes
 
 //without SYNC or other parts