aprs.no

Protocol for remote control

The purpose of this protocol is that multiple APRS nodes (typically multiple instances of the polaric-aprsd) can exchange information or commands. Currently we use this to keep multiple instances of the aprsd synchronised wrt. the following information:

  • Aliases or tags associated with point objects (typically APRS stations identified by callsigns).
  • Alternative icons for APRS stations or objects, set manually
  • SAR-mode activation/deactivation

The synchronisation is done via authenticated APRS messages. Authentication is based on a shared key and sequence numbers. The nodes that synchronise form an overlay network in a strict hierarchy (tree structure).

The shared key (password) should be more than 8 characters long and hard to guess.

Authenticated APRS messages

The format of a message is as follows:

:<recipient><content>#<MAC>{<messsage-id>

recipient : (as defined in the APRS standard), callsign of the recipient padded with spaces so that its length is excactly 9 characters.

content : The message to be sent

MAC : A checksum is computed by concatenating a secret key, the sender callsign, the recipient callsign, the content and the message-id and generating a MD5 hash from the resulting byte-string (the characters of the message are UTF-8 encoded before generating the hash). The resulting MD5 hash is base-64 encoded and the first 8 bytes of the encoded hash is used as the message authentication code (MAC) sent with the message. Both the sender and receiver of a message compute the MAC. On receipt of a message a node should compute the MAC and compare it with the MAC received with the message. If not match, the message should be rejected.

messsage-id : (as defined in the APRS standard). It should be unique for each message. Polaric APRSD use a sequence-number that is incremented with each message.

Acknowledgment messages

On receipt of a message a node should respond with an ACK or REJ message as described in the APRS protocol to indicate if the message was successfully delivered to the application and that a command was successfully executed or not. The sender should retry a message if an acknowledgement is not received within a certain time (but there should be a limit on the number of retries, eg. 3). The recipient node should use the message-id to ensure that the same message is not delivered to the application more than once.

Requests (commands)

The content field of a message carry a request consisting of a request identifier and zero or more arguments separated by whitespace characters. A request message should be acknowledgded (ACK message) if successfully processed, or rejected (REJ) if delivery or processing failed.

Group Subscription

CON

A node can send a CON message to another node (parent) to subscribe to subsequent updates (it can also send updates). At receipt of a CON request, a node should record the identity of sender and the time of receipt. Then, the sending node is regarded as a member of the group. A node typically sends a CON message to its parent at startup. CON requests can be repeated later to renew the membership of the group, for example every 10 minutes. If no CON request is received for 30 minutes, the node should remove the child from the group (record is purged).

A node initiates association to at most one other node (the parent) and may receive CON requests from any number of other nodes (children). This means that nodes in a group are associated with each other in a strictly hierarchical structure.

Group synchronisation commands

The following requests are used to propagate information to all members of a group. On receipt of such a request, a node should execute it and propagate it further to all other nodes that it knows about (parent + children), except the node that it got it from in the first place.

ALIAS <callsign> <alias> Set an alias for a given callsign.

ICON <callsign> Set an alternative icon for a given callsign. Use filename for graphics without path (location of files is a part of server configuration).

TAG <callsign> <tag> Add a tag to the given point object. A tag is basically a keyword.

RMTAG <callsign> <tag> Remove a tag from the given point object.

SAR <ON|OFF> <user-id> <filter> <reason> Turn on or off SAR mode. The user-id, filter and reason arguments are used when first argument is 'ON'. user-id is the login-identifier of the user that initiated SAR mode, filter is a regular expression describing what callsigns to be hidden or 'NONE' if no filtering should be done on callsigns. reason is a short textual description.

USER <ident> Announce that user is logged on to the system. NB: From v. 2.8 the ident can be encrypted.

RMUSER <ident> Announce that user is logged off. NB: From v. 2.8 the ident can be encrypted.

RMNODE <ident> Announce that a node is closing down.

Encryption

From v. 2.8 we may encrypt userids. This may be necessary to comply with privacy regulations (GDPR). It is possible to specify in the setup for which servers this is to be used. If on, the ident is encrypted using AES (128bit) where key is generated from the password (same as used for authenticating messages). An initialisation vector is used, where the two first bytes are random and the third byte is the day of the year (modulo 256). The two random bytes are used as a prefix on the encrypted id. The resulting length is either 144 or 272 bits depending on the length of the id. The encrypted id (prefixed) is encoded using base64.

Before activating encryption for messages to be sent over amateur radio, be sure to check the HAM radio regulations in your country.

devel/remote_control.txt · Last modified: 2021/09/15 20:19 by la7eca
CC Attribution-Share Alike 4.0 International
Powered by PHP Driven by DokuWiki Recent changes RSS feed Valid CSS Valid XHTML 1.0 Valid HTML5