MQTT Topics

This is the list of MQTT Topics that are use by the various HackSpace Instrumentation projects.

All of these are available on holly, and most are available on JARVIS via an MQTT/mosquitto bridge.

All topics should be prefixed with "nh/"

STATUS

Topic	Description	Notes
nh/status/req	Status Request topic	"STATUS" message is sent out by nh-monitor
nh/status/res	Status Reporting topic	Used to respond to a request or just broadcast a new/change of state
nh/status/tool/{tool name}	Tool current state report	Current state of the tool (eg IN_USE, SIGNED_OFF) set by nh-tools

All clients should subscribe to the `nh/status/req` topic and listen for the message "STATUS"
Clients should respond on `nh/status/res` with their name and status.

Three states

• Restart:
• Running:
• Terminated:

ie. "Running: MatrixMQTT"

Include the : and a space before the clients name,

The status of all running clients is logged and reported here https://hms.nottinghack.org.uk/instrumentation/status

Gatekeeper

Topic	Direction (G=Gatekeeper Arduino, H=Gatekeeper process on Holly, B=Doorbell)	Description	Notes
nh/gk/<door id>/Unlock	H > G	Shows message on LCD / unlocks door	Not available on Jarvis
nh/gk/<door id>/DoorState	G > H	One of "OPEN", "CLOSED", "LOCKED", "FAULT"
nh/gk/entry_announce/known	H > (IRC, etc)	"Door Opened by: username (last seen xxx ago)"	Sent by Gatekeeper process on receiving "OPEN", all doors other than the airlock are prefixed with the door name and direction arrow
nh/gk/entry_announce/unknown	H > (IRC, etc)	"Door opened"	Sent by Gatekeeper process
nh/gk/<door id>/Keypad	G > H	PIN entered	Not available on Jarvis
nh/gk/<door id>/DoorButton	G > H	"OUTER", "INNER" or "REAR" for different doors	Message payload is unimportant
nh/gk/DoorButton	H > (IRC/slack, etc)	Door bell button pushed	Message payload is the short name of the door (e.g. "INNER")
nh/gk/bell/<bell name>	H > B	Door bell in the given area	Payload is the number of rings (1-3)
nh/gk/<door id>/RFID	G > H	Serial of RFID card presented, or "Unknown Card Type"	Not available on Jarvis
nh/gk/LastManState	G > H	"First In" or "Last Out"	Knife switch by door. There is an intentional delay between the switch being thrown, and publishing to this topic

MatrixMQTT

Topic	Description	Notes
nh/mb/tx	nh-matrix script transmits messages to be displayed
nh/mb/rx	confirmation of displayed message is returned to nh-matrix

IRC Bot: nh-holly

Living in #nottinghack on Libera Chat, nh-holly is our MQTT to IRC bridge

Topic	Description	Notes
nh/irc/tx	Sends to the default #nottinghack channel
nh/irc/tx/nottinghack	Sends to the #nottinghack channel
nh/irc/tx/pm/<nick>	Sends a pm to <nick>
nh/irc/rx/nottinghack/<nick>	Incoming message from irc #nottinghack channel
nh/irc/rx/pm/<nick>	Incoming pm from irc user <nick>

Slack: nh-holly

Lives in various channels in the HSNOTTS team slack, nh-holly is our MQTT to slack bridge

Topic	Description	Notes
nh/slack/tx	Sends payload to #activity channel
nh/slack/tx/<channel>	Sends to #<channel>	Bot must be invited into channel first
nh/slack/tx/pm/<nick>	Sends a direct message to <nick>
nh/slack/rx/<channel>/<nick>	Incoming message from #<channel>
nh/slack/rx/pm/<nick>	Incoming direct message from <nick>

Discord: Nottinghack Bot

rx of direct messages is not currently supported.

Topic	Description	Notes
nh/discord/tx	Sends payload to #bot-spam channel
nh/discord/tx/<channel>	Sends to #<channel>
nh/discord/tx/pm/<username>	Sends a direct message to <nick>
nh/discord/rx/<channel>/<displayName>	Incoming message from #<channel>	Only if channel doesn't end in '-private'
nh/discord/json/rx	JSON blob of entire Message entity	Only if channel doesn't end in '-private'
nh/discord/presence/<username>	Status presence update	(e.g. online, offline, idle, dnd)
nh/discord/avatar/<username>	The users' current avatar URL	pushed alongside presence - this should be cached if used
nh/discord/error	Errors from discord/mqtt bridge	e.g. when DMing a user which doesn't allow non-friend DMs

@Holly533MHz: nh-twitter

Twitter to MQTT bridge

Topic	Description	Notes
nh/twitter/tx
nh/twitter/rx/dm/<screen_name	DM to @Holly533Mhz from <Screen_name>
nh/twitter/rx/mention/<screen_name>	mention of @Holly533Mhz by <screen_name>
nh/twitter/rx/hs	latest tweet from @HSNOTTS includes retweets	payload <screen_name>:<text>

Temperature

Readings from DS18B20 1-Wire digital temperature sensors around the space are published at least every 2.5 minutes.
nh/temp

Topic	Description
nh/temp	Sensors should regularly publish readings to this topic as `address:temp` (see below)
nh/temperature/{name}	nh-temperature republishes temps to the topic with a friendly name

Message format as follows
address:temp

address	Hex string 16 long
temp	Float 00.00

Light Level

Currently only one LDR connected to WorkshopMQTT

Topic	Description
nh/lightlevel/workshop	Light level in the Workshop. > ~800 = lights are on
nh/lightlevel/{sensor}	Light level from the `sensor`.

Humidity

Relative Humidity (%)

Topic	Description
nh/humidity/{sensor}	Relative Humidity (%) from the `sensor`.

Barometric Pressure

Pressure in millibars (hPa)

Topic	Description
nh/barometric-pressure/{sensor}	pressure in millibars (hPa) from the `sensor`.

Sensor Battery

Battery voltage for a given sensor

Topic	Description
nh/sensor-battery/{sensor}	Battery voltage (V) from the `sensor`.

Tools RFID access control: Nhtools

Tools access control module. See Nhtools for a better description of these messages.

Topic	Description (A=Arduino, S=Server)	Notes
nh/tools/<tool name>/AUTH	A > S: RFID card presented	payload is RFID serial
nh/tools/<tool name>/GRANT	S > A: RFID card belongs to a member who has been inducted on the tool - enable power
nh/tools/<tool name>/DENY	S > A: Sign on request denied	payload is the reason (e.g. not inducted)
nh/tools/<tool name>/COMPLETE	A > S: Tool sign off
nh/tools/<tool name>/INDUCT	A > S: Request to induct member	payload is signed on RFID card + RFID of member to induct
nh/tools/<tool name>/ISUC	S > A: Induction successful
nh/tools/<tool name>/IFAL	S > A: Induction failed (e.g. unknown card)	payload is failure reason
nh/tools/<tool name>/RESET	A > S: Arduino has either just booted, or has reconnected	Payload is cause

Tools bookings

This provides limited details of tool bookings made via HMS. When a booking is made from HMS, a push notification is received from google for the underlying google calendar, which results in a poll message being sent with the payload set to tool name that's been updated. The nh-tools process then downloads the ICAL formatted calendar from google, and publishes the now/next booking to the booking topic.

Topic	Description	Notes
nh/bookings/<tool name>/nownext	Now and next booking information for <tool name>	Payload is JSON encoded, see below.
nh/bookings/poll	Request to poll google for updated calendar data, then publish to nownext topic	Payload is tool name

Example payload for nownext message:

{
  "now":{
     "display_time":"now",
     "display_name":"<member name1>"
  },
  "next":{
     "display_time":"10:30",
     "display_name":"<member name2>"
  }
}

For the nownext message payload, bookings which start more that 20hrs in the future are ignored to remove ambiguity in the time displayed.

Network Devices

A count of the number of network devices currently connected (results of a minutely ARP scan).

Topic	Description
nh/addr/known	Number of known/fixed network devices (e.g. printers, VM's, etc).
nh/addr/unknown	Number of unknown network devices (e.g. members laptops).

Wireless Things LLAP

Topic	Description	Notes
nh/llap/tx/XX	Send out a LLAP message	XX is DEVID
nh/llap/rx/XX	LLAP message received	XX is DEVID
nh/llap/messagebridge/send	JSON to Send out a LLAP message	Can also be sent broadcast on UDP 50141
nh/llap/messagebridge/listen	JSON of LLAP message received	Also broadcast on UDP 50140

LLAP Messages

LLAP message format
12 Char's
aXXDDDDDDDDD

• a start character
• XX Device ID
• DDDDDDDDD message

more detail can be found here:-

• LLAP http://openmicros.org/index.php/articles/85-llap-lightweight-local-automation-protocol/112-llap
• LLAP device details http://openmicros.org/index.php/articles/87-llap-devices-commands-and-instructions

Payload for MQTT message is upto 9byte's, the message part of LLAP, padding is automatically added and striped.
aNOHELLO----
becomes
nh/llap/?x/NO HELLO

Message Bridge

For the MessageBridge JSON details see:-
https://github.com/WirelessThings/WirelessThings-LaunchPad/blob/master/Documentation/ExampleJSONMessages.json

Lighting Automation

For more details see Lighting Automation/Control Software
Note the `set` and `sate` topics are detailed here for reference only since only the nh-lighting software running on queen should be the only thing to interact with them, custom projects wishing to interact with the light should use the web socket protocol exposed via nh-lighting on ws://queen:8181/lighting (subprotocol 'lighting')

Topic	Description	Notes
nh/li/{controllerName}/{channel}/set	Lighting Command	Only for channels 00-23 on v2 controllers and 00-31 on v3 controllers, Payload can be one of [ON, OFF, TOGGLE]
nh/li/{controllerName}/{channel}/state	Lighting State	Retained Topic! Current state of the channel [ON, OFF]
nh/li/{controllerName}/EM/Voltage	V
nh/li/{controllerName}/EM/Current	A
nh/li/{controllerName}/EM/Power	Kw
nh/li/{controllerName}/EM/ReactivePower	Var
nh/li/{controllerName}/EM/PowerFactor
nh/li/{controllerName}/EM/Frequency	Hz
nh/li/{controllerName}/EM/TotalActivePower	Kwh
nh/li/{controllerName}/EM/TotalReactivePower	Kvarh

{channel}
00-31 represent the output channels, note only 00-23 on v2 controllers
I0-I7 are the local input channels Ixxyy are rs485 input channels. Where 'xx' is the (node id + 10) and 'yy' is the channel 00-15 (v3 controller only)

Fun things

Train Departures

cron job on jarvis runs every 5 minutes (as user asj) and pushes the stripped train departure board (currently only for Nottingham) to MQTT

Topic	Description	Notes
nh/tdb/{CRS}	JSON Array	Example for MAN [{"destination":"Blackpool North","std":"00:09","platform":"14","etd":"00:17"},... ]

Studio Display WC/Service Indicators

The topic nh/StudioDisplay/Lamps can be used for setting the status of the Studio Display WC and Service lamps. There are three lamps in total - two WC indicators, which can be lit green or red, and a Service indicator which can be lit red. Turning these lamps on or off can be done by sending a hex value to the MQTT topic. The following table defines what bits do what.

Topic	Description	Notes
nh/StudioDisplay/Lamps	Hex value	See bit descriptions below
nh/ElectronicsDisplay/Lamps	Hex value	See bit descriptions below

Bit	Description
0	Nothing
1	Nothing
2	WC1 (Red)
3	WC1 (Green)
4	WC2 (Red)
5	WC2 (Green)
6	Service (Top and Bottom)
7	Service (Left and Right)

For example, to set WC1 to Green and illuminate all of the Service section, you'd get the bit pattern 0b11001000, which in hex is 0xC8.

Pager Transmitter (MB7PNH)

The hackspace has a pager transmitter, which is documented at Radio Group/Pager. Unfortunately this must only be used by those that have an amateur radio license (licensing is weird). There are a number of RICs which you can subscribe to without a license though. Ideas for "pager services" are welcome.