MQTT Brokers

MQTT is a popular protocol for connecting IoT (Internet of Things) devices. The Shared Game Timer (SGT) can connect to a MQTT broker to both read commands (e.g. 'End Turn') as well as publish the current state of a timer (e.g. current player color).

Here are some examples of what you could do:

• Set the color of a smart lightbulb to the current player's color.
• Three minutes into someone's turn, tell your alert bracelet to vibrate.
• Six minutes into someone's turn, tell the doorbell to ring.
• When you press some button, end your turn.
• When you shake the device, perform Undo.
• During Admin Time, play elevator music on your stereo.

Popular ways to do the above is to either activate MQTT integration with your Home Assistant or program a micro-controller to act as a remote control.

After activating the MQTT integration, SGT will start writing the state of your open timers to the {userid}/game feed (in JSON format), which your IoT devices can subscribe to. The SGT will in turn subscribe to the {userid}/commands where your IoT devices can post messages to do things like pause the game, end your turn etc.

You can use your own MQTT broker or a free broker that SGT has set up via HiveMQ.

Example Projects

Below are example projects that uses the MQTT integration. Let me know if you want to add your own here.

TFT Sandwich

A remote with 3 buttons, a screen and buzzer.

Summary of Setup

You must be logged in to activate the MQTT integration. (your user ID is part of the MQTT topic that will be read/written) Once logged in, navigate to the MQTT Setup page and activate the integration. You should do this on only one device (e.g. your phone), and the activation is active for only that device. This MQTT enabled device should be the one you have open during the game so it can 1) write updates to the {userID}/game feed and 2) perform commands written to the {userID}/commands feed.

The {userID}/game topic

Whenever you enter a game timer on a MQTT enabled device or when the game state changes, a retained message is written to the {userID}/game feed. Since it is retained, any IoT device that subscribes to the {userID}/game feed will get the latest game state message, even if it was sent earlier.

When you exit the game by e.g. navigating away, it will clear the game state message. However, if you simply close the browser abruptly, the game message will remain for some time.

The game state message is in JSON format. All times are in seconds. There are four kind of messages sent, depending on the timer mode and if the game is finished or not.

The Action Map

The action map includes available actions that can be sent to the {userId}/commands topic. The keys correspond to the placement in the main SGT UI where you would expect to find the buttons to do those actions.

Each of the above keys may be missing from the action map if there is no action in the designated spot.

Each entry of the map points to a object with two properties:

• label: Human friendly description of the action, e.g. 'End Turn'
• action: An ID of the action e.g. 'game/endTurn'.

Example Message

{
  "gameStateVersion": 7,
  "timerMode": "cu",
  "state": "pl",
  "color": "486bfa",
  "name": "Gustav",
  "turnTime": 0,
  "playerTime": 16,
  "totalPlayTime": 26,
  "actions": {
    "primary": { "label": "End Turn", "action": "game/endTurn" },
    "admin":   { "label": "Start mid-turn admin", "action": "game/startMidTurnAdmin" },
    "pause":   { "label": "Pause", "action": "game/pause" }
  }
}

The {userID}/commands topic

To execute a command in the action map, publish a JSON-formatted string to the userID/commands topic.

The JSON should have two properties:

• gameStateVersion: The current gameStateVersion. If the SGT version and the command versions don't match, the command will be ignored.
• action: The action to execute, taken from actions[actionKey].action, e.g. 'game/endTurn'.

Example Message

{
  "gameStateVersion": 7,
  "action": "game/endTurn"
}