r3 MQTT Topics
- - Broker
  - Topics currently in use
- Structure of Topics
  - Clients\\ aka 1st level topics
  - 2nd level topics and payload types

r3 MQTT Topics

A go-module and exact definitions of current r3events can be found at github: https://github.com/realraum/door_and_sensors/tree/master/r3events

A guide on mqtt essentials: http://www.hivemq.com/blog/mqtt-essentials-part-5-mqtt-topics-best-practices

Broker

mqtt.realraum.at:1883 (reachable only in local realraum network)

Topics currently in use

Topics can be retained by the message broker. In this case, the most recent event for that topic is sent to a client immediately upon subscription of that topic.

Topic	Retain	Description
Sensor Messages
zigbee2mqtt/w1/AjarWindowMasha	false	MaSha Window ajar or not
zigbee2mqtt/w2/AjarWindowR2W2right	false	R2W2 right Window ajar or not
zigbee2mqtt/w2/AjarWindowR2W2left	false	R2W2 left Window ajar or not
zigbee2mqtt/w2/AjarWindowTesla	false	TESLA Window ajar or not
zigbee2mqtt/w2/AjarWindowKitchen	false	TESLA Window ajar or not
zigbee2mqtt/w1/AjarWindowOLGA	false	OLGA Window ajar or not
realraum/frontdoor/lock	True	Frontdoor locked or not
realraum/w2frontdoor/lock	True	w2 door locked or not
realraum/frontdoor/ajar	True	Frontdoor ajar or shut
realraum/w2frontdoor/ajar	True	w2 door ajar or not
realraum/frontdoor/cmdevt	False	Command that was sent to the frontdoor and by whom
realraum/frontdoor/problemevt	False	Problem that occured at the frontdoor
realraum/frontdoor/manuallockmovement	True	If the frontdoor was locker / unlocked by hand
realraum/frontdoor/rawfwlines	False	raw communication between door_client and door_daemon
realraum/smallkiosk/temperature	True	LoTHR Temperature, DHT11 Sensor
realraum/smallkiosk/relhumidity	True	LoTHR Humidity, DHT11 Sensor
realraum/printerbone/temperature	True	Tesla R1W2 BMP180 Sensor
realraum/printerbone/barometer	True	Tesla R1W2 BMP180 Sensor
realraum/pillar/boredoombuttonpressed	False	indicates the BoreDOOOOOOMButton has been pressed
realraum/pillar/illumination	True
realraum/pillar/dust	True	currently nonexistant Dust Sensor
realraum/pillar/movement	False	PIR Movement Sensors on Arduino on Beaglebone in LoTHR, one event per detected movement
realraum/xbee/relhumidity	True	XBee non-fixed sensors humidity, DHT11
realraum/xbee/temperature	True	XBee non-fixed sensors temperature, DHT11
realraum/xbee/voltage	True	XBee non-fixed sensors battery voltage
realraum/w2tesla/relhumidity	True	sensors humidity, BMP280 in R2W2
realraum/w2tesla/temperature	True	temperature, BMP280 in R2W2
realraum/backdoorcx/movement	False	currently nonexistant future PIR Movement Sensor in CX
realraum/olgafreezer/temperature	False	OlgaFreezer DS18B20 Temp Sensors
realraum/olgafreezer/overtemp	False	Alarm Event, triggered if Temperature exceeds a pre-set limit (see olga_freezer_sensordata_forwarder.py )
realraum/olgafreezer/sensorlost	False	Triggered if a olgafreezer sensor stopped transmitting data
realraum/backdoorcx/temperature	True	Temperature in CX, between Network, Backdoor and WC
realraum/backdoorcx/lock	False	no sensor, does not exist
realraum/backdoorcx/ajar	True	Backdoor Ajar Sensor
realraum/backdoorcx/gasalert	False	Sent if LPG/Gas-Alert on CX-Ceiling is triggered
realraum/backdoorcx/powerloss	False	Sent if UPS connected to `smsgw.realraum.at` reports powerloss, power-regained or change in battery charge
realraum/gateway/NetDHCPACK	False	not-implemented. Info about new DHCP client in network.
realraum/gateway/NetGWStatUpdate	True	not-implemented. TODO ¹⁾ . regular updated network statistics
realraum/lasercutter/cardpresent	True	indicateds if and who's card actives the lasercutters's laser
realraum/w2frontdoor/online	True	indicates ip of device and if online or offline (LastWill)
action/ceilingN/online	True	indicates ip of device and if online or offline (LastWill)
Meta Events
realraum/metaevt/presence	True	Indicates if someone is present in realraum. Sent everytime presence status changes. .Meta-Event generated by 'r3-metaevt-maker'
realraum/metaevt/aggregatecontactsensor	True	Collects all shut,locked,contact sensors into one event. Sent on change. Meta-Event generated by 'r3-metaevt-maker'
realraum/metaevt/overtemp	False	Meta-event triggered if a temperature sensor exceeds a warning threshold
realraum/metaevt/sensorlost	False	Meta-event triggered if a sensor stopped transmitting data
realraum/metaevt/realmovement	False	Tries to distinguish between real movement and spurious sensor errors
realraum/metaevt/duskordawn	False	Meta-event that indicates Sunset, Sunrise, astronomical dawn, nautical dawn, civil dawn.
realraum/metaevt/TempSensorSpike	False	not-implemented. TODO. Meta-event that triggers if a temperature sensor's value rises above its running average standard deviation –> possible Fire
realraum/metaevt/DustSensorSpike	False	not-implemented. TODO. Meta-event that triggers if a dust sensor's value rises above its running average standard deviation –> possible Fire
realraum/metaevt/timetoclean	False	Meta-event: Cleanup Time Event
realraum/rauchmelderN/online	True	N={1…} smokealarm online or not. includes last known IP
realraum/rauchmelderN/smokealarm	True	N={1…] SmokeALARM triggered in given room
Action Requests
action/rf433/sendcode3byte	False	Tell RF433 Transmitters to transmit the attached 3byte code over the air to powerplugs
action/rf433/setdelay	True	Tell Sender at Location X to wait DelayMs until sending a command receivce via `sendcode3byte` ²⁾
action/yamahastereo/ircmd	False	Send command to ir-emitter for yamaha stereo (list of named commands)
action/PipeLEDs/pattern	False	Select pattern of Pipe LED stripe
action/PipeLEDs/restart	False	Restart ESP8266 controlling pipe LEDs
action/ceiling1/light	False	Set R,G,B,CW,WW Value of ceiling1
action/ceiling2/light	False	Set R,G,B,CW,WW Value of ceiling2
action/ceiling3/light	False	Set R,G,B,CW,WW Value of ceiling3
action/ceiling4/light	False	Set R,G,B,CW,WW Value of ceiling4
action/ceiling5/light	False	Set R,G,B,CW,WW Value of ceiling5
action/ceiling6/light	False	Set R,G,B,CW,WW Value of ceiling6
action/flooddoor/light	False	Set R,G,B,CW,WW Value of ceiling7 flodder
action/abwasch/light	False	Set R,G,B,UV,WW Value of ceiling8 flodder
action/ceilingAll/light	False	Set R,G,B,UV,CW,WW Value of all ceiling lights
action/gonamectrl/name	False	Switch named thing on/off
action/ceilingscripts/activescript	Falsce	active script with options '{script:name,…}'
action/GoLightCtrl/basiclight1	False	switch basiclight on/off
action/GoLightCtrl/basiclight2	False	switch basiclight on/off
action/GoLightCtrl/basiclight3	False	switch basiclight on/off
action/GoLightCtrl/basiclight4	False	switch basiclight on/off
action/GoLightCtrl/basiclight5	False	switch basiclight on/off
action/GoLightCtrl/basiclight6	False	switch basiclight on/off
action/realraum/resendstatus	False	True: trigger resending of current status of all locks, door-sensors, ajar-sensors, etc

Structure of Topics

level0/level1/level2/level3/….

Level	Content
0	`realraum` (indicates sensor information) or `action` (indicates a request for action)
1	clientID. Either ID of sender (if topic[0] == `realraum`) or ID of recipient (if topic[0] == `action`) Future use: access restrictions for topics of `+/clientid/#` to senders with the correct clientid
2	uniquely identifies the type and format of the payload. E.g. means is directly maps to a certain json object structure
3	discouraged, but could be used to distinguish between several types of sensors of the same type at the same location, subcommands, etc

Reasons

eg.:to get all temperature sensors in realraum, subscribe to: “realraum/+/temperature”
e.g. mosquitto does not support wildcards subscriptions of the type “realraum/#/temperature”, which means message content/format should always be at level 2
“realraum/” should be at the front, since other hackerspaces MQTT sensors can also be subscribed to. e.g. “devlol/”, or “metalab/”
having the message format indicated in the topic makes parsing easier
having the clientID in the topic makes access control easier, e.g. only that clientid can publish to this topic

Clients\\ aka 1st level topics

ClientID	on Host	Description	Network Requirements
frontdoor	torwaechter.mgmt.realraum.at	ALIX Board mounted on the front door	LAN mqtt.realraum.at DNS
backdoorcx	mqtt.realraum.at	MinimusAVR connected to `smsgw.realraum.at` and running `backdoorcx_sensor_node` binary. Located in CX/Network	LAN mqtt.realraum.at DNS
GoLightCtrl	licht.realraum.at	RaspberryPi serving http://licht.realraum.at/switch.html site and sending `action/rf433/sendcode3byte` mqtt messages. Listens to topics like `action/GoLightCtrl/basiclight1` Sits on top shelf next to beamer in LoTHR. Connected to Ceilinglightcontrolbuttons.	LAN mqtt.realraum.at DNS provides HTTP licht.realraum.at
ventilation	ventilation.realraum.at	RaspberryPi with Touchscreen controlling Ventilation and serving http://lüftung.realraum.at/ and sending `realraum/ventlation/ventstate` mqtt messages. Listens to lasercutter	LAN mqtt.realraum.at DNS provides HTTP ventilation.realraum.at
pillar	kiosk1.realraum.at	arduinosensor.py script running on RPi2 `kiosk1.realraum.at`, located between pillar in LoTHR and the window glas.	LAN internet for kiosk mqtt.realraum.at DNS
smallkiosk	smallkiosk.realraum.at	dht11sensor.py script running on RPi1 `smallkiosk.realraum.at`, which is the small display next to the passage from LoTHR to CX	LAN mqtt.realraum.at DNS Internet for Kiosk
xbee	smsgw.realraum.at	xbeesensor.py script running on RasperriPi `smsgw.realraum.at`, connects to XBEE temperature and humidity sensors outside or cellar	LAN mqtt.realraum.at DNS
olgafreezer	olgafreezer.realraum.at	Arduino+NetworkShield POE-powered TemperatureDisplay next to freezer in OLGA. smsgw.realraum.at runs a sensornode called `olga_freezer_sensordata_forwarder.py`	LAN accessible from wherever `olga_freezer_sensordata_forwarder.py` runs
metaevt	mqtt.realraum.at	Metaevents generated from other events by `r3-metaevt-maker` binary running on `mqtt.realraum.at`	LAN mqtt.realraum.at DNS
w2tesla	w2tesla.mgmt.realraum.at	Temp/Humidity DHT11 Sensor in Tesla's PowerPlugBar	mgmtWIFI mqtt.realraum.at DNS
w2frontdoor	?	bsod built ESP8266 sensor sensing if the flat-door to flat2/Wohnung2 is locked or not	mgmtWIFI mqtt.realraum.at DNS
gateway	gw.realraum.at	ALIX board `gw.realraum.at`, located in CX/Network, runs NO sensors	all?
lasercutter	lasercutter.mgmt.realraum.at	RaspberryPI1 used for accesscontrol to the lasercutter. Mounted on the lasercutter.	mgmtWIFI mqtt.realraum.at DNS provides ssh
xmppbot	mqtt.realraum.at	The binary `r3-xmppbot` running on `mqtt.realraum.at`. Possible future backchannel for xmpp-bot	LAN mqtt.realraum.at DNS idl.wirdorange.org or wherever xmpp:realraum.at runs
r3-spaceapistatus	mqtt.realraum.at	The binary `r3-spaceapistatus` running on `mqtt.realraum.at`.	LAN mqtt.realraum.at DNS ssh to vex.realraum.at provides http:8080/json as future alternative to ssh-out
rf433	kiosk.realraum.at	Action Destination for rf433 powerplug-control transmitters	LAN mqtt.realraum.at DNS
yamahastereo	kiosk.realraum.at	Action Destionation to control the YamahaStereoReceiver/Amplifier in LoTHR	LAN mqtt.realraum.at DNS
ircchanbot	dhcp-12.realraum.at	IRC Bot running on verr's raspberryPI2 (thinkpi) on the shelf next to the beamer	LAN mqtt.realraum.at Internet
r3LEDPipe	dhcp:NODE-ABE95, usually 192.168.127.151	LEDs on top of Pipe in LoTHR	r3WIFI provides telnet needs DHCP DNS mqtt.realraum.at
ceiling1-6	ceiling*.mgmt.realraum.at	RGB+CW+WW controllable ceilinglights in LoTHR	mgmtWIFI with r3WIFI as fallback mqtt.realraum.at DNS provides telnet
flooddoor	flooddoor.mgmt.realraum.at	RGB+CW+WW controllable light above entrance in LoTHR	mgmtWIFI with r3WIFI as fallback mqtt.realraum.at DNS provides telnet
abwasch	abwasch.mgmt.realraum.at	RGB+WW+UV controllable LED strips for LoTHR Abwasch	mgmtWIFI with r3WIFI as fallback mqtt.realraum.at DNS provides telnet
mashaesp	mashaesp.mgmt.realraum.at	planned but currently disabled movement sensor to combat people leaving the lights on in MaSha	mgmtWIFI mqtt.realraum.at DNS
couchred	dhcp:couchred-8128	SonOff S20 PowerPlug controlling the “Ducks”	r3WIFI mqtt.realraum.at needs DHCP DNS provides http
printerbone	drucker.realraum.at	BeagleBoneGreen managing printer power	mqtt.realraum.at needs DNS provides cups
lothrboiler	dhcp:"lothrboiler-6135	SonOff Pow Relay controlling power to the warm water boiler in LoTHR	r3WIFI mqtt.realraum.at needs DHCP DNS provides http
rauchmelder1	rauchmelder1.mgmt.realraum.at	ESP8266 connected to smoke alarm at TESLA. Only powers on if smoke alarm goes off

2nd level topics and payload types

see e.g. basicevents to get a feel for a payload message structure.

Ts stands for timestamp and should be a int64 value of seconds since the epoch at the time the event occured.

2nd Level Topic	Payload Type	Payload Type Format
Sensor Messages
lock	JSON Object	{“Locked”:bool, “Ts”:int64}
ajar	JSON Object	{“Shut”:bool, “Ts”:int64}
cmdevt	JSON Object	{“Command”:string, “Using”:string (“Card”,“Button”,“ssh”,…), “Who”:string, “Ts”:int64}
problemevt	JSON Object	{“Severity”:int, “Problem”:string “Ts”:int64}
manuallockmovement	JSON Object	{“Ts”:int64}
rawfwlines	string
boredoombuttonpressed	JSON Object	{“Ts”:int64}
temperature	JSON Object	{“Location”:string, “Value”:float64 (°C), “Ts”:int64}
voltage	JSON Object	{“Location”:string, “Value”:float64 (V), “Min”:float64 (V, optional),“Max”:float64 (V, optional),“Percent”:float64 (%, optional), “Ts”:int64}
overtemp	JSON Object	{“Location”:string, “Value”:float64 , “Threshold”:float64, “Ts”:int64}
illumination	JSON Object	{“Location”:string, “Value”:int64 , “Ts”:int64}
dust	JSON Object	{“Location”:string, “Value”:int64 , “Ts”:int64}
relhumidity	JSON Object	{“Location”:string, “Percent”:float64 , “Ts”:int}
barometer	JSON Object	{“Location”:string, “HPa”:float64, “Ts”:int}
gasalert	JSON Object	{“Ts”:int64}
powerloss	JSON Object	{“OnBattery”:bool, PercentBattery:float, LineVoltage: float, LoadPercent: float, “Ts”:int}
NetDHCPACK	JSON Object	{“Mac”:string, “IP”:string, “Name”:string, “Ts”:int} TODO
NetGWStatUpdate	JSON Object	{TODO, “Ts”:int64}
cardpresent	JSON Object	{“IsHot”:bool, “Who”:string(name of user), “Ts”:int}
foodorderrequest	JSON Object	{“Who”:string, “Preference”:string, “Ts”:int}
foodorderinvite	JSON Object	{“Who”:string, “Where”:string, “URL”:string (http or phone), “Ts”:int64}
foodordereta	JSON Object	{“TSofInvite”:int64, “ETA”:int64, “Ts”:int}
online	JSON Object	{“online”:bool, “ip”:string}
smokealarm	JSON Object	{“room”:string, “voltage”:float}
Meta Events
presence	JSON Object	{“Present”:bool, “InSpace1”:bool, “InSpace2”:bool, “Ts”:int64}
aggregatecontactsensor	JSON Object	{“AllDoorsShut”:bool, “AllWindowsShut”:bool, “AllDoorsLocked”:bool, “Ts”:bool}
realmovement	JSON Object	{“Movement”:bool, “Confidence”:uint8, “Ts”:int} largely useless
overtemp	JSON Object	{“Location”:string, “Value”:float, “Threshold”:float, “Ts”:int}
sensorlost	JSON Object	{“Topic”:string, “LastSeen”:int, “UsualInterval”:int64, “Ts”:int}
duskordawn	JSON Object	{“Event”: string,“HaveSunlight”:bool, “Ts”:int}
TempSensorSpike	JSON Object	{“Location”:string, “Value”:float64, “Ts”:int}
DustSensorSpike	JSON Object	{“Location”:string, “Value”:int64, “Ts”:int}
3dprintprogress	JSON Object	{“Printer”:string, “Job”:string, “Elapsed_time_s”:int64, “Progress_percent”:int}

Action Requests
sendcode3byte	JSON Object	{“Code”:[3]byte, “Ts”:int64}
setdelay	JSON Object	{“Location”:string, “DelayMs”:int64, “Ts”:int64}
ircmd	JSON Object	{“Cmd”:string, “Ts”:int64}
pattern	JSON Object	{“pattern”:string, “arg”: optional argument for pattern, “arg1”: opt, “brightness”:0..100, “hue”:-1..255, “speed”:0..255}
restart
light	JSON Object	see schema
timetoclean	JSON Object	{}
name	String	0	1	on	off

¹⁾

equinox doesn't like this™ so may never be implemented

²⁾

currently not used, even though implemented

Table of Contents