Internet protocol
MorseKOB clients communicate with other stations by sending UDP packets to the KOB server. The server relays packets containing Morse code timing and sender identification information to other clients connected to the same wire.
There are five packet types:
- Connect: connects the client to the server on a particular wire
- Disconnect: disconnects the client from the server
- ID: contains station identification
- Code: contains Morse code timing information
- Acknowledge: received from the server in response to a connect packet sent by the client
The structure of the various packet types:
Note the following:
- The format of the acknowledge packet is not shown. It is a simple 2-byte packet containing only the command code.
- The flags field in the ID packet is not used in PyKOB.
- The data packet format should be seen as the code packet format.
- The byte count field in data packets (ID packets and code packets) is always 492.
- The sequence number field contains an integer that is incremented every time a unique data packet is sent.
Command code: 4 (CON)
The connect command connects the client to a particular wire on the server. It is always followed by an ID packet. The server responds to a successful connect request by returning an acknowledge packet to the client. The connect command can also be used to change the current wire number without disconnecting.
The client sends a connect packet to the server every 10 seconds as a keepalive function. If the server doesn't receive any connect packets from a client over a 30 second interval, then the server considers that client to be no longer connected.
Command code: 2 (DIS)
This is the normal way a client disconnects from the server.
Command code: 3 (DAT)
An ID packet is sent after each connect packet. It includes the client's station ID (as a zero-delimited ASCII string) and client version information (also as a zero-delimited ASCII string).
The n field in ID packets is zero. This is how ID packets are distinguished from code packets. (CWCom and MorseKOB 2.5 used a 0 or 1 in the flags field, which in retrospect is probably a better way of doing it.)
Command code: 3 (DAT)
Code packets contain the Morse code timing information of a code sequence. The length of the code sequence is contained in the n field.
Command code: 5 (ACK)
An acknowledge packet is sent from the server to the client in response to a client's connect request to the server. It is never sent by the client.
By their very nature, UDP packets are not guaranteed to arrive in order, or at all. To compensate for this limitation, PyKOB data packets (both ID packets and code packets) contain a sequence number that is incremented every time a unique data packet is sent. This allows clients to detect out of order or missing packets. Currently the software does not attempt to correct the error, but it can and does alert the user that a transmission error has occurred.
To partially guard against dropped packets, each data packet is actually sent twice. These duplicate packets are sent with the same sequence number as the original, and the receiving client disregards all duplicates.