Register R/W over MQTT is a simple and intuitive approach to model a distributed key/value map over the network. Each key/value pair in the distributed map is referred to as a register. There is no central point other than the MQTT broker. This protocol unifies communication between smart devices and allows to expose the state of these devices in the form of metrics, which can be further stored and visualized.
This repository servers for the following purposes:
- Provides Go language library to consume and provide registers.
- Provides simple CLI tool to manipulate the registers.
- Describes the communication protocol.
Register R/W over MQTT is a simple protocol based on generic MQTT. The protocol models so called "registers" where register value can be read or written by MQTT topics.
Each register is identified by a string name. By convention the name is lowercase string without spaces. Optionally the name can be formed as a logical path separated by dots, e.g. kitchen.temperature, kitchen.humidity or buildingA.floor0.room10.lights
Register value may be any valid JSON type, i.e. number, string, boolean, object or array. Null values are passed as empty (zero-length) messages. Meaning of null (or undefined on js API level) values is, that the register is unavailable.
There are two mandatory topics every device has to implement: listen for get, publish is and two optional topics: listen for set, publish advertise.
message format: none
Register MUST listen for this topic and immediately send current state of the register by publishing is topic.
example:
register/kitchen.temperature/get (no message data)
message format: any valid JSON value
This is mandatory topic for writable registers. Register MAY listen for this topic and set the register value to the decoded JSON data from message. If register listens for the topic, then it MUST publish is topic with the new state. In some situations the value sent in is topic is not exactly the value received in set topic - this may happen if the value to be set is out of range and the register clips the value to an acceptable value.
example:
register/kitchen.lights/set true
register/kitchen.display.text/set "Refrigerator door open"
register/livingroom.curtain.position/set 50
register/livingroom.lights/set [50,50,100]
message format: any valid JSON value
Register MUST publish this topic in following situations:
- when register receives
gettopic - when register receives
settopic and is writable register
Message data is JSON encoded register value.
example:
register/kitchen.lights/is true
register/kitchen.temperature/is 24.3
message format: JSON object
Register MAY publish this topic in order to let other parties know about register presence. Message sent with this topic is JSON encoded object with details about register. Register SHOULD set these properties in published data:
devicea device identifier, which may serve to logically group registers in a graphical UI.typeone of data type identifiers:number,string,boolean,array,objectunitname of a unit if the register represents physical property, e.g.°C.
message format: none
This is a broadcast challenge for all registers to advertise. Registers MAY respond with register/(registername)/advertise.
TBD
Download binary for your platform from the latest release.
go mod tidy
go build -o regreg is a command line tool for working with registers over MQTT.
The reg command is a command line tool for working with registers over MQTT. It allows you to read, write and list registers. Furthermore it can provide a 'virtual' register which is convenient for debugging of consumers of the register.
MQTT broker is specified using environment variable MQTT as hostname or hostname:port.
For more information on registers over MQTT, see: https://github.com/burgrp/go-reg .
-h, --help help for reg
- reg get - Read a register
- reg list - List all known registers
- reg provide - Provide a register
- reg set - Write a register
- reg version - Show version
Read a register
Reads the specified register. With --stay flag, the command will remain connected and write any changes to stdout.
reg get <register> [flags]
-h, --help help for get
-s, --stay Stay connected and write changes to stdout
- reg - reg is a command line tool for working with registers over MQTT.
Help about any command
Help provides help for any command in the application. Simply type reg help [path to command] for full details.
reg help [command] [flags]
-h, --help help for help
- reg - reg is a command line tool for working with registers over MQTT.
List all known registers
Lists all known registers by sending advertise challenge to all devices. With --stay flag, the command will remain connected and write any changes to stdout. If registers are specified, only those will be listed.
reg list [<reg1> <reg2> ...] [flags]
-h, --help help for list
-s, --stay Stay connected, write changes to stdout
-t, --timeout duration Timeout for waiting for advertise challenge to be answered (default 5s)
- reg - reg is a command line tool for working with registers over MQTT.
Provide a register
Registers are established by advertising them to the network. The 'meta' argument is a JSON object containing metadata for the register, such as {"device": "My device"}. You can also specify an initial value as the last argument. If no initial value is provided, the register will be created with a null value. Values for registers are defined using JSON expressions, such as true, false, 3.14, "hello world," or null. Additionally, subsequent values can be read from stdin and written to stdout.
reg provide <name> <meta> [<value>] [flags]
-h, --help help for provide
-r, --read-only Make the register read-only.
- reg - reg is a command line tool for working with registers over MQTT.
Write a register
Writes the specified register. With --stay flag, the command will remain connected, read values from stdin and write any changes to stdout. Values are specified as JSON expressions, e.g. true, false, 3.14, "hello world" or null.
reg set <register> <value> [flags]
-h, --help help for set
-s, --stay Stay connected, read values from stdin and write changes to stdout
-t, --timeout duration Timeout for waiting for the register to be set (default 5s)
- reg - reg is a command line tool for working with registers over MQTT.
Show version
Shows version of reg command line tool.
reg version [flags]
-h, --help help for version
- reg - reg is a command line tool for working with registers over MQTT.