Skip to content

Packet-Description.md

Latest commit

 

History

History
72 lines (43 loc) · 5.48 KB

Packet-Description.md

File metadata and controls

72 lines (43 loc) · 5.48 KB
Raw

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 printable characters. 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 38-859 bytes. Packets that carry the Stream and Packet Mode data are discussed in Section 3.3 of the M17 Specification. By their magic value, the packets supported by mrefd are:

  • M17 is a 54 byte packet used to carry Stream Mode data between mrefd and all simple clients.
  • M17P is a 38-839 byte packet used to carry Packet Mode data between mrefd and all simple clients.

2. Packet types

All other packet are made up of one, two or three parts:

  1. Magic: a 4-byte magic sequence if ASCII characters. In addition to M17 , magic can be ACKN, CONN, DISC, LSTN, NACK, PING or PONG.
  2. Encoded Callsign: This is a 6-byte encoded callsign. In all cases, this is the encoding callsign of the node that is sending the packet. 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.
  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, with a trailing null byte.

A one part packet is 4 bytes long and just contains the magic value. A two part packet is 10 bytes long and contains the magic value and the sender's encoded callsign. A three part packet is either 11 or 37 bytes and also includes the reflector module(s) to which the sender is requesting to link. This will be a single byte in the case of a simple client requesting a link to a module. In the case of an mrefd interlink, this is a null-terminated list of modules specify from 1 to 26 different modules.

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 as the third part.

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:

3.2.1 CONN is used by clients

A simple client uses CONN to request 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.

3.2.2 CONN is used by mrefd

  1. A reflector uses CONN to request 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 and PONG is the keep-alive packet

A two-part packet is used by mrefd as a keep-alive packet to all connected nodes, both simple clients and other interlinked reflectors. The second part is always the callsign of the node sending the packet. These two packets server the same purpose and are in fact identical. It will be sent approximately every 3 seconds.If a node hasn't received a PING or PONG in the last 30 seconds, it can assume the reflect has stopped working.

Copyright (c) 2025 by Thomas A. Early N7TAE