Skip to content

Latest commit

 

History

History
63 lines (35 loc) · 5.32 KB

Packet-Description.md

File metadata and controls

63 lines (35 loc) · 5.32 KB

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 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.
  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