Difference between revisions of "MQTT Topics"

From Nottinghack Wiki
Jump to navigation Jump to search
(36 intermediate revisions by 4 users not shown)
Line 1: Line 1:
−
This is the list of MQTT Topics that are use by the various [[HackSpace_Instrumentation|HackSpace Instrumentation]] projects.
+
This is the list of [[Wikipedia:MQTT|MQTT]] Topics that are use by the various [[HackSpace_Instrumentation|HackSpace Instrumentation]] projects.
 +
 
 +
All of these are available on [[holly]], and most are available on [[JARVIS]] via an MQTT/[http://mosquitto.org/ mosquitto] bridge.
  
 
All topics should be prefixed with "nh/"
 
All topics should be prefixed with "nh/"
 +
 +
==STATUS==
 +
nh/status/req<br/>
 +
All clients should subscribe to this topic and listen for the message "STATUS"<br/>
 +
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,
 +
 +
Current list of clients
 +
*MatrixMQTT
 +
*Gatekeeper (arduino)
 +
*nh-irccat
 +
*nh-irc
 +
*nh-matrix
 +
*GateKeeper (process)
 +
*nh-irc-misc
 +
*nh-temperature
 +
*WorkshopMQTT
 +
*nh-vend
 +
 +
The status of all running clients is logged and reported here http://lspace.nottinghack.org.uk/instrumentation.php
  
 
==[[Gatekeeper]]==
 
==[[Gatekeeper]]==
 +
{| class="wikitable"
 +
|-
 +
! 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  || "Door Opened", "Door Opened by:" or "Door Closed" ||
 +
|-
 +
| nh/gk/entry_announce/known || H > (IRC, etc) || "Door Opened by: ''username'' (last seen ''xxx'' ago)" || Sent by Gatekeeper process on receiving "Door Opened by:"
 +
|-
 +
| 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
 +
|-
 +
|}
 +
 +
==[[LED Matrix|MatrixMQTT]]==
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
Line 10: Line 70:
 
! Notes
 
! Notes
 
|-
 
|-
−
| nh/gk/Unlock || ||
+
| nh/mb/tx || nh-matrix script transmits messages to be displayed ||  
 
|-
 
|-
−
| nh/gk/DoorState || ||
+
| nh/mb/rx || confirmation of displayed message is returned to nh-matrix||
 +
|}
 +
 
 +
==IRC Bot: [[nh-holly]]==
 +
Living in [ircs://irc.libera.chat:6697/#nottinghack #nottinghack on Libera Chat], nh-holly is our MQTT to IRC bridge
 +
 +
{| class="wikitable"
 
|-
 
|-
−
| nh/gk/Keypad || ||
+
! Topic
 +
! Description
 +
! Notes
 +
|-
 +
| nh/irc/tx || Sends to the default #nottinghack channel ||
 
|-
 
|-
−
| nh/gk/DoorButton || ||
+
| nh/irc/tx/nottinghack || Sends to the #nottinghack channel ||
 +
|-
 +
| nh/irc/tx/pm/<nick> || Sends a pm to <nick> ||
 
|-
 
|-
−
| nh/gk/RFID || ||
+
| nh/irc/rx/nottinghack/<nick> || Incoming message from irc #nottinghack channel ||
 
|-
 
|-
−
| nh/gk/LastManState || ||
+
| nh/irc/rx/pm/<nick>|| Incoming pm from irc user <nick> ||
 
|-
 
|-
−
| nh/gk/Status || ||
 
 
|}
 
|}
  
  
−
==ICR Bot==
+
==Slack: [[nh-holly]]==
 +
Lives in various channels in the [http://slack.nottinghack.org.uk/ HSNOTTS team slack], nh-holly is our MQTT to slack bridge
 +
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
Line 33: Line 106:
 
! Notes
 
! Notes
 
|-
 
|-
−
| nh/irc/tx || ||
+
| 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> ||
 
|-
 
|-
−
| nh/irc/rx || ||
 
 
|}
 
|}
  
 +
==@Holly533MHz: [[nh-twitter]]==
 +
Twitter to MQTT bridge
  
−
==Twitter Bot: @Holly533MHz==
 
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
Line 48: Line 129:
 
| nh/twitter/tx || ||
 
| nh/twitter/tx || ||
 
|-
 
|-
−
| nh/twitter/rx || ||
+
| 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 Monitoring|Temperature]]==
 +
Readings from DS18B20 1-Wire digital temperature sensors around the space are published at least every 2.5 minutes.<br />
 +
nh/temp<br>
 +
Message format as follows<br/>
 +
address:temp<br/>
 +
{| class="wikitable"
 +
|-
 +
| address || Hex string 16 long
 +
|-
 +
| temp || Float 00.00
 +
|-
 +
|}
 +
 
 +
==Light Level==
 +
Currently only one LDR connected to [[WorkshopMQTT]]
 +
 
 +
{| class="wikitable"
 +
|-
 +
! 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.
 +
 +
{| class="wikitable"
 +
|-
 +
! 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 [https://github.com/NottingHack/instrumentation/blob/master/cpp/nh-tools-bookings.cpp nh-tools] process then downloads the ICAL formatted calendar from google, and publishes the now/next booking to the booking topic.
 +
 +
{| class="wikitable"
 +
|-
 +
! 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 <code>nownext</code> topic || Payload is tool name
 +
|}
 +
 +
Example payload for <code>nownext</code> message:
 +
<code>
 +
{
 +
  "now":{
 +
      "display_time":"now",
 +
      "display_name":"<member name1>"
 +
  },
 +
  "next":{
 +
      "display_time":"10:30",
 +
      "display_name":"<member name2>"
 +
  }
 +
}
 +
</code>
 +
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==
 +
A count of the number of network devices currently connected (results of a minutely [http://en.wikipedia.org/wiki/Address_Resolution_Protocol ARP] scan).
 +
 +
{| class="wikitable"
 +
|-
 +
! 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).
 +
|-
 +
|}
 +
 +
==XRF & LLAP==
 +
 +
LLAP message format <br/>
 +
12 Char's<br/>
 +
aXXDDDDDDDDD<br/>
 +
* 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.<br/>
 +
aNOHELLO----<br/>
 +
becomes<br/>
 +
nh/xrf/?x/NO HELLO
 +
{| class="wikitable"
 +
|-
 +
! Topic
 +
! Description
 +
! Notes
 +
|-
 +
| nh/xrf/tx/XX || Send out a LLAP message || XX is DEVID
 +
|-
 +
| nh/xrf/rx/XX || LLAP message received || XX is DEVID
 +
|}
 +
 +
 +
==[[Lighting Automation]]==
 +
For more details see [[Lighting Automation/Control Software]]
 +
 +
{| class="wikitable"
 +
|-
 +
! Topic
 +
! Description
 +
! Notes
 +
|-
 +
| nh/li/{controllerName}/{channel}/set || Lighting Command || For channels 00-23 only, Payload can be one of [ON, OFF, TOGGLE]
 +
|-
 +
| nh/li/{controllerName}/{channel}/state || Lighting State || Retained Topic! Current state of the channel [ON, OFF]
 +
|}
 +
 +
{channel}<br/>
 +
00-23 represent the output channels<br/>
 +
I0-I7 are the inputs
 +
 +
Set payload can be
  
−
[[Category:Projects]]
 
−
[[Category:Current Projects]]
 
 
[[Category:Network]]
 
[[Category:Network]]
−
[[Category:Hackspace]]
+
[[Category:MQTT]]
 
[[Category:Instrumentation]]
 
[[Category:Instrumentation]]

Revision as of 19:27, 19 November 2021

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

nh/status/req
All clients should subscribe to this 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,

Current list of clients

  • MatrixMQTT
  • Gatekeeper (arduino)
  • nh-irccat
  • nh-irc
  • nh-matrix
  • GateKeeper (process)
  • nh-irc-misc
  • nh-temperature
  • WorkshopMQTT
  • nh-vend

The status of all running clients is logged and reported here http://lspace.nottinghack.org.uk/instrumentation.php

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 "Door Opened", "Door Opened by:" or "Door Closed"
nh/gk/entry_announce/known H > (IRC, etc) "Door Opened by: username (last seen xxx ago)" Sent by Gatekeeper process on receiving "Door Opened by:"
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>

@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
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).

XRF & LLAP

LLAP message format
12 Char's
aXXDDDDDDDDD

  • a start character
  • XX Device ID
  • DDDDDDDDD message

more detail can be found here:-

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

Topic Description Notes
nh/xrf/tx/XX Send out a LLAP message XX is DEVID
nh/xrf/rx/XX LLAP message received XX is DEVID


Lighting Automation

For more details see Lighting Automation/Control Software

Topic Description Notes
nh/li/{controllerName}/{channel}/set Lighting Command For channels 00-23 only, Payload can be one of [ON, OFF, TOGGLE]
nh/li/{controllerName}/{channel}/state Lighting State Retained Topic! Current state of the channel [ON, OFF]

{channel}
00-23 represent the output channels
I0-I7 are the inputs

Set payload can be

Retrieved from "https://wiki.nottinghack.org.uk/index.php?title=MQTT_Topics&oldid=25962"