Difference between revisions of "MQTT Topics"
m (→Gatekeeper) |
|||
(18 intermediate revisions by 2 users not shown) | |||
Line 15: | Line 15: | ||
|- | |- | ||
| nh/status/res || Status Reporting topic || Used to respond to a request or just broadcast a new/change of state | | 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 | ||
|} | |} | ||
Line 28: | Line 30: | ||
Include the : and a space before the clients name, | 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 | The status of all running clients is logged and reported here https://hms.nottinghack.org.uk/instrumentation/status | ||
− | |||
==[[Gatekeeper]]== | ==[[Gatekeeper]]== | ||
Line 54: | Line 43: | ||
| nh/gk/<door id>/Unlock || H > G || Shows message on LCD / unlocks door || Not available on Jarvis | | nh/gk/<door id>/Unlock || H > G || Shows message on LCD / unlocks door || Not available on Jarvis | ||
|- | |- | ||
− | | nh/gk/<door id>/DoorState || G > H || " | + | | 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 " | + | | 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/entry_announce/unknown || H > (IRC, etc) || "Door opened" || Sent by Gatekeeper process | ||
Line 127: | Line 116: | ||
| nh/slack/rx/pm/<nick>|| Incoming direct message from <nick> || | | nh/slack/rx/pm/<nick>|| Incoming direct message from <nick> || | ||
|- | |- | ||
+ | |} | ||
+ | |||
+ | ==Discord: Nottinghack Bot== | ||
+ | |||
+ | rx of direct messages is not currently supported. | ||
+ | |||
+ | {| class="wikitable" | ||
+ | |- | ||
+ | ! 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 | ||
|} | |} | ||
Line 151: | Line 167: | ||
Readings from DS18B20 1-Wire digital temperature sensors around the space are published at least every 2.5 minutes.<br /> | Readings from DS18B20 1-Wire digital temperature sensors around the space are published at least every 2.5 minutes.<br /> | ||
nh/temp<br> | nh/temp<br> | ||
+ | {| class="wikitable" | ||
+ | |- | ||
+ | ! 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<br/> | Message format as follows<br/> | ||
address:temp<br/> | address:temp<br/> | ||
Line 214: | Line 241: | ||
Example payload for <code>nownext</code> message: | Example payload for <code>nownext</code> message: | ||
− | + | ||
{ | { | ||
"now":{ | "now":{ | ||
Line 225: | Line 252: | ||
} | } | ||
} | } | ||
− | + | ||
For the <code>nownext</code> message payload, bookings which start more that 20hrs in the future are ignored to remove ambiguity in the time displayed. | For the <code>nownext</code> message payload, bookings which start more that 20hrs in the future are ignored to remove ambiguity in the time displayed. | ||
− | |||
− | |||
==Network Devices== | ==Network Devices== | ||
Line 246: | Line 271: | ||
==Wireless Things LLAP== | ==Wireless Things LLAP== | ||
+ | {| class="wikitable" | ||
+ | |- | ||
+ | ! 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 <br/> | LLAP message format <br/> | ||
12 Char's<br/> | 12 Char's<br/> | ||
Line 260: | Line 301: | ||
becomes<br/> | becomes<br/> | ||
nh/llap/?x/NO HELLO | nh/llap/?x/NO HELLO | ||
− | + | ||
− | + | ===Message Bridge=== | |
− | + | For the MessageBridge JSON details see:-<br> | |
− | + | https://github.com/WirelessThings/WirelessThings-LaunchPad/blob/master/Documentation/ExampleJSONMessages.json | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
==[[Lighting Automation]]== | ==[[Lighting Automation]]== | ||
For more details see [[Lighting Automation/Control Software]]<br> | For more details see [[Lighting Automation/Control Software]]<br> | ||
− | Note the `set` and `sate` topics are detailed here for reference only since only the [https://github.com/NottingHack/instrumentation-lighting 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 | + | Note the `set` and `sate` topics are detailed here for reference only since only the [https://github.com/NottingHack/instrumentation-lighting 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') |
{| class="wikitable" | {| class="wikitable" | ||
Line 307: | Line 342: | ||
Ixxyy are rs485 input channels. Where 'xx' is the (node id + 10) and 'yy' is the channel 00-15 (v3 controller only) | 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 | ||
+ | |||
+ | {| class="wikitable" | ||
+ | |- | ||
+ | ! Topic | ||
+ | ! Description | ||
+ | ! Notes | ||
+ | |- | ||
+ | | nh/tdb/{CRS} || JSON Array || Example for MAN <code>[{"destination":"Blackpool North","std":"00:09","platform":"14","etd":"00:17"},... ]</code> | ||
+ | |} | ||
+ | |||
+ | === Studio Display WC/Service Indicators === | ||
+ | |||
+ | The topic <code>nh/StudioDisplay/Lamps</code> 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. | ||
+ | |||
+ | {| class="wikitable" | ||
+ | |- | ||
+ | ! Topic | ||
+ | ! Description | ||
+ | ! Notes | ||
+ | |- | ||
+ | | nh/StudioDisplay/Lamps || Hex value || See bit descriptions below | ||
+ | |} | ||
+ | |||
+ | {| class="wikitable" | ||
+ | |- | ||
+ | ! 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 <code>0b11001000</code>, which in hex is <code>0xC8</code>. | ||
+ | |||
+ | === 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. | ||
[[Category:Network]] | [[Category:Network]] | ||
[[Category:MQTT]] | [[Category:MQTT]] | ||
[[Category:Instrumentation]] | [[Category:Instrumentation]] |
Revision as of 19:54, 8 July 2024
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 |
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 |
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.