View on GitHub


Modern Model Railroad Control - Documentation

Home > The MMRC Convention

The MMRC Convention

Version: 0.1.0

Date: 20 Feb 2019

Heavily based on the Homie Convention by David Gräff and contributors. Thank you!

MQTT Restrictions

MMRC communicates through MQTT and is hence based on the basic principles of MQTT topic publication and subscription.

Topic IDs

An MQTT topic consists of one or more topic levels, separated by the slash character (/). A topic level ID MAY contain lowercase letters from a to z, numbers from 0 to 9 as well as the hyphen character (-).

A topic level ID MUST NOT start or end with a hyphen (-). The special character $ is used and reserved for MMRC attributes.








QoS and retained messages

The nature of the MMRC convention makes it safe about duplicate messages, so the recommended QoS for reliability is QoS 1. All messages defined in this convention MUST be sent as retained, UNLESS stated otherwise.

Last will

MQTT only allows one last will message per connection. MMRC requires a last will for the mmrc / device ID / $state attribute, see Device Lifecycle. As a consequence a new MQTT connection to the broker is required per published device.

Base Topic

The root topic for this convention is mmrc/.


Devices: An instance of a physical piece of hardware is called a device. For example, a car, an Arduino/ESP8266 or a coffee machine.

Nodes: A device can expose multiple nodes. Nodes are independent or logically separable parts of a device. For example, a car might expose a wheels node, an engine node and a lights node.

Properties: A node can have multiple properties. Properties represent basic characteristics of the node/device, often given as numbers or finite states. For example the wheels node might expose an angle property. The engine node might expose a speed, direction and temperature property. The lights node might expose an intensity and a color property.

Attributes: Devices, nodes and properties have specific attributes characterizing them. Attributes are represented by topic identifier starting with $. The precise definition of attributes is important for the automatic discovery of devices following the MMRC convention.

Examples: A device might have an IP attribute, a node will have a name attribute, and a property will have a unit attribute.


Device Attributes

The following device attributes are mandatory and MUST be send, even if it is just an empty string.

Topic Description
$name Friendly name of the device
$state See Device Lifecycle
$nodes Nodes the device exposes, separated by , for multiple ones.

Optional topics include:

Topic Description
$mmrc The implemented MMRC convention version
$type An identifier for the type of device used (example “esp8266” or “Arduino Uno”)

For example, a device with an ID of super-car that comprises of a wheels, engine and a lights node would send:

mmrc/super-car/$mmrc  "2.1.0"
mmrc/super-car/$name  "Super car"
mmrc/super-car/$nodes  "wheels,engine,lights[]"
mmrc/super-car/$type  "esp8266"
mmrc/super-car/$state  "ready"

Device Lifecycle

The $state device attribute represents the current state of the device. There are 6 different states:


Node Attributes

All listed attributes are required. A node attribute MUST be one of these:

Topic Description
$name Friendly name of the Node
$type Type of the node
$properties Exposed properties, separated by , for multiple ones.

For example, our engine node would send:

mmrc/super-car/engine/$name  "Car engine"
mmrc/super-car/engine/$type  "V8"
mmrc/super-car/engine/$properties  "speed,direction,temperature"


Property Attributes

The following attributes are required:

Topic Description Payload type
$name Friendly name of the property. String
$datatype The data type. See Payloads. Enum: [integer, float, boolean,string, enum, color]

The following attributes are optional:

Topic Description Payload type
$format Specifies restrictions or options for the given data type See below
$settable Settable (true). Default is read-only (false) Boolean
$retained Non-retained (false). Default is Retained (true). Boolean

For example, our temperature property would send:

mmrc/super-car/engine/temperature/$name  "Engine temperature"
mmrc/super-car/engine/temperature/$settable  "false"
mmrc/super-car/engine/temperature/$unit  "°C"
mmrc/super-car/engine/temperature/$datatype  "float"
mmrc/super-car/engine/temperature/$format  "-20:120"
mmrc/super-car/engine/temperature  "21.5"

Settable and retained:

A combination of those flags compiles into this list:


Property command topic

A MMRC controller publishes to the set command topic with non-retained messages only.

The assigned and processed payload must be reflected by the MMRC device in the property topic mmrc / device ID / node ID / property ID as soon as possible. This property state update not only informs other devices about the change but closes the control loop for the commanding controller, important for deterministic interaction with the client device.

To give an example: A kitchen-light device exposing the light node with a settable power property subscribes to the topic mmrc/kitchen-light/light/power/set for commands:

mmrc/kitchen-light/light/power/set  "true"

In response the device will turn on the light and upon success update its power property state accordingly:

mmrc/kitchen-light/light/power  "true"

Broadcast Channel

MMRC defines a broadcast channel, so a controller is able to broadcast a message to all MMRC devices:

For example, you might want to broadcast an alert event with the alert reason as the payload. Devices are then free to react or not. In our case, every buzzer of your home automation system would start buzzing.

mmrc/$broadcast/alert  "Intruder detected"

Any other topic is not part of the MMRC convention.

« Back