This is an old revision of the document!
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 1) . 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/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 2) |
| 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 |
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 | Image |
|---|---|---|---|---|
| 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} | |||
| 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 | |||
| name | String | 0 | 1 | on | off |
realraum Graz, Brockmanngasse 15, 8010 Graz, realraum - Verein für Technik in Kultur und Gesellschaft