Merge pull request #12 from mich181189/master

Rough documentation of reflctor protocol messages

docs/ip_encapsulation.rst

@@ -58,3 +58,86 @@ of the packet, such as when translating from RF to IP framing.
 .. todo:: RF->IP & IP->RF bridging reassembly, UDP NAT punching, callsign routing lookup
 
 .. points_of_contact:: N7TAE, W2FBI
+
+Control Packets
+----------------------
+
+Reflectors use a few different types of control frames, identified by their magic:
+
+* *CONN* - Connect to a reflector
+* *ACKN* - acknowledge connection
+* *PING/PONG* - keepalives for the connection
+* *DISC* - Disconnect (client->reflector or reflector->client)
+
+CONN
+~~~~~~~~~~~~~~~
+
+.. table :: Bytes of a CONN packet
+
+  +-------+----------------------------------------------------------------------------------------------------------------+
+  | Bytes | Purpose                                                                                                        |
+  +=======+================================================================================================================+
+  | 0-3   | Magic - ASCII "CONN"                                                                                           |
+  +-------+----------------------------------------------------------------------------------------------------------------+
+  | 4-9   | 6-byte 'From' callsign including module in last character (e.g. "A1BCD   D") encoded as per `Address Encoding` |
+  +-------+----------------------------------------------------------------------------------------------------------------+
+  | 10    | Module to connect to - single ASCII byte A-Z                                                                   |
+  +-------+----------------------------------------------------------------------------------------------------------------+
+
+.. todo:: it would ne nice to include the destination callsign in full rather than just the module - it's only an extra 5 bytes, and it would allow hosting multiple reflectors on one instance and maybe some other use cases where you want to be explicit about what you're connecting to
+
+A client sends this to a reflector to initiate a connection. The reflector replies with ACKN on successful linking, or NACK on failure.
+
+ACKN
+~~~~~~~~~~~~~~~~~
+
+.. table :: Bytes of ACKN packet
+
+  +-------+----------------------------------------------------------------------------------------------------------------+
+  | Bytes | Purpose                                                                                                        |
+  +=======+================================================================================================================+
+  | 0-3   | Magic - ASCII "ACKN"                                                                                           |
+  +-------+----------------------------------------------------------------------------------------------------------------+
+  | 4-9   | 6-byte callsign including module in last character (e.g. "A1BCD   D") encoded as per `Address Encoding`        |
+  +-------+----------------------------------------------------------------------------------------------------------------+
+
+NACK
+~~~~~~~~~~~~~~~~~
+
+.. table :: Bytes of NACK packet
+
+  +-------+--------------------------------------------------------------------------------------------------------------------------+
+  | Bytes | Purpose                                                                                                                  |
+  +=======+==========================================================================================================================+
+  | 0-3   | Magic - ASCII "NACK"                                                                                                     |
+  +-------+--------------------------------------------------------------------------------------------------------------------------+
+
+PONG
+~~~~~~~~~~~~~~~~~
+
+.. table :: Bytes of PONG packet
+
+  +-------+----------------------------------------------------------------------------------------------------------------+
+  | Bytes | Purpose                                                                                                        |
+  +=======+================================================================================================================+
+  | 0-3   | Magic - ASCII "PONG"                                                                                           |
+  +-------+----------------------------------------------------------------------------------------------------------------+
+  | 4-9   | 6-byte 'From' callsign including module in last character (e.g. "A1BCD   D") encoded as per `Address Encoding` |
+  +-------+----------------------------------------------------------------------------------------------------------------+
+
+Upon receing a PING, the client replies with a PONG
+
+DISC
+~~~~~~~~~~~~~~~~~
+
+.. table :: Bytes of DISC packet
+
+  +-------+----------------------------------------------------------------------------------------------------------------+
+  | Bytes | Purpose                                                                                                        |
+  +=======+================================================================================================================+
+  | 0-3   | Magic - ASCII "DISC"                                                                                           |
+  +-------+----------------------------------------------------------------------------------------------------------------+
+  | 4-9   | 6-byte 'From' callsign including module in last character (e.g. "A1BCD   D") encoded as per `Address Encoding` |
+  +-------+----------------------------------------------------------------------------------------------------------------+
+
+Sent by either end to force a disconnection. Acknowledged with 4-byte packet "DISC" (without the callsign field)