M.A.R-T>Y. Micro Protocol Specification v1

Version 1 of the specification document for the M.A.R-T>Y. Micro Protocol.

Quality Status: Release

Functionality Status: Iterative

M.A.R-T>Y. Micro Protocol (MuP) is an endpoint-based request/response RPC protocol for small-ish interlinked systems. The little brother of the M.A.R-T>Y. Middleware Protocol (MMP), it shares some basic structure with some differences to tailor it to more unsophisticated systems. For example, since MMP operates on UNIX hosts error detection does not need to be on its layer. MuP might run on embedded systems over UART, where error detection would be nice.

A MuP packet consists of a header and a variable number of payloads. Whether a message can have payloads is determined by its type - if a packet has payloads CRC32 is placed in the header. The header is 5 bytes long if a message type has no payloads, or 9 bytes long if it does to include CRC32. The first 5 bytes of the header are always the same - a type (1 byte), argument (1 byte), version (1 byte) and size (2 bytes).

Like MMP, MuP delimits its payloads with the 0xFE character and terminates its packet with the 0xFF character. Terminators in this manner were chosen to give payloads a similar workflow in C to strings which are terminated with the NULL character 0x00. This means the entire ASCII range can be used as payloads, though for arbitrary integers you should choose an encoding strategy. The size field was added as another data mismatch detection method, and the argument field has been reduced from 2 bytes to 1 byte.

Unlike MMP, there are no 'targets' supported; this is not a multi-client protocol. There is expected to be only a single connection partner, or a 'master' coordinating messaging on the application level.

The CRC algorithm used in the reference implementation 'libmup' is CRC-32/ISO-HDLC based on polynomial 0x04C11DB7. Theoretically you could use a CRC16 algorithm instead and leave the highest 2 bytes blank. 'API' type response messages are defined by this protocol and serializable in the reference implementation but it is left to the application designer to send them appropriately.

Multi-byte integers (like the size and CRC fields) are Big Endian.

MAX PACKET SIZE (configurable): 2048 bytes
MIN PACKET SIZE WITHOUT CRC (header + packet term): 6 bytes
MIN PACKET SIZE WITH CRC (header + crc + packet term): 12 bytes

PAYLOAD DELIMITER: 0xFE
PACKET TERMINATOR: 0xFF

Types

Type	Description	Byte	Payloads
UNSET	No action, used internally by libraries as a NULL type.	0x00	== 0
INIT	Initialise a session with partner. Sends its name as a payload.	0x01	== 1
BAD	Notify partner they sent an invalid message.	0x02	== 0
CONTERM	Notify partner I'm terminating the connection.	0x03	== 0
SONAR	Ping the partner to see if they respond (heartbeat).	0x04	== 0
SEND	Send a request to the partner, this makes the request part of the API layer.	0x05	>= 1
API	Notify partner about the status of their API request - making the response component.	0x06	== 0

Arguments

UNSET

Argument	Description	Byte
UNSET	No action, used internally by libraries as a NULL type.	0x00

INIT

Argument	Description	Byte
INIT	Partner requests initialisation.	0x01
ACCEPT	Partner accepts initialisation.	0x02
REJECT	Partner rejects initialisation.	0x03

BAD

Argument	Description	Byte
TYPE	Type of last message was invalid.	0x01
PACK_LEN	Length of last packet was too big, too small or didn't match the header.	0x02
ARG	Argument of last message was invalid.	0x03
PAYL	A value in one of the payloads was invalid.	0x04
PAYL_COUNT	Payload count did not align with type.	0x05
VERSION	Version mismatch between my protocol version and partner's.	0x0A
CRC	Calculated CRC did not match the received CRC.	0x0B
INTERN_ERR	Partner experienced an unspecified internal error.	0x0C

CONTERM

Argument	Description	Byte
CLEAN	Partner requests clean disconnect.	0x01
SPAM	Partner is closing the connection due to high frequency of messages (up to user to implement).	0x02
MANY_BAD	Partner is closing the connection due to too many invalid messages (up to user to implement).	0x03

SONAR

Argument	Description	Byte
PING	Partner wants to see if we're up.	0x00
PONG	We respond and tell the partner we're alive.	0x01

SEND

Argument	Description	Byte
DIRECT	Partner sends a 'direct' API message to me, in MuP currently the only API message.	0x01

API

Argument	Description	Byte
SUCCESS	Partner informs the API request was successful.	0x01
BUSY	Partner informs it is too busy to complete the API request.	0x03
RANGE	Partner informs value(s) in the payload was out of range for this endpoint (e.g. it might be ASCII only).	0x04
ENDPOINT	Partner informs the requested endpoint was out of range.	0x05
VALUE	Partner informs one or more entire payloads were made up of invalid characters.	0x06
COUNT	Partner informs the payload count sent does not match its endpoint config.	0x07
EXEC	Partner informs that while the request was technically valid, an error occurred in executing it.	0x0A

Examples