MQTT for CueTracker

How it works

Each club connects CueTracker to its own MQTT broker and selects the match and competition events it wants to publish. Every club has an isolated, asynchronous client, so a slow or unreachable broker does not block another club. Open the club, choose Settings, expand Broker connection, then enter the broker details and test the connection. Automations subscribe to the club event stream or an individual match state topic.

Use a dedicated broker account for CueTracker. Broker passwords are encrypted at rest and credentials are redacted from connection errors. Keep controller, display, session and API credentials separate from MQTT broker credentials.

Real-world venue ideas

MQTT is best for actions that should happen immediately when somebody uses the Controller screen. CueTracker publishes information outward; MQTT subscribers cannot change scores or control a match.

Other useful ideas include a referee call button workflow after a foul, accessibility announcements, sponsor animations between frames, a “next match” display and a private club activity log. Keep celebrations brief so they do not interfere with nearby tables.

Topics

CueTracker permanently assigns cuetracker/<club-id> to the club. The prefix is read-only, remains stable when the club is renamed and prevents two clubs from publishing to the same topics.

Event names

• frame.started
• frame.finished
• match.called_to_table
• match.started
• match.paused
• match.resumed
• match.finished
• competition.started
• competition.finished
• turn.changed
• ball.potted
• foul.recorded
• achievement.master_break
• achievement.master_first_visit
• shot_clock.reset
• shot_clock.warning
• shot_clock.alert
• shot_clock.expired

Select the event types CueTracker publishes in the club’s MQTT settings. Existing clubs can enable the two achievement events by reopening Broker connection and saving their event selections.

Master achievement events are published only when the recorded frame data proves the achievement; they are not inferred from a final score. Their payload identifies the achievement type, player, side, frame and eight-ball run. Warning and alert messages follow each match’s configured timer thresholds. A disabled warning or alert does not publish its corresponding event. Each threshold publishes once per shot, and resetting the clock begins a new shot.

Event payload

{
  "schemaVersion": 1,
  "messageType": "event",
  "eventId": "unique-event-id",
  "event": "frame.finished",
  "occurredAt": "2026-09-10T12:30:00.000Z",
  "club": {
    "id": "club-id",
    "name": "Example Club"
  },
  "match": {
    "id": "match-id",
    "name": "Friday Final",
    "format": "singles",
    "table": "Table 1",
    "teams": {
      "A": { "name": "Craig", "players": ["Craig"] },
      "B": { "name": "Taylor", "players": ["Taylor"] }
    }
  },
  "frame": {
    "number": 3,
    "winner": "Craig",
    "score": {
      "A": 2,
      "B": 1
    }
  }
}

{
  "event": "achievement.master_break",
  "match": {
    "id": "match-id",
    "table": "Table 1",
    "teams": {
      "A": { "name": "Craig", "players": ["Craig"] },
      "B": { "name": "Taylor", "players": ["Taylor"] }
    }
  },
  "frame": {
    "number": 3,
    "winner": "Craig",
    "score": { "A": 2, "B": 1 }
  },
  "achievement": {
    "type": "master-break",
    "frame": 3,
    "side": "A",
    "player": "Craig",
    "run": 8
  }
}

Every event has the same required envelope: schemaVersion, messageType, eventId, event, occurredAt and club. Match, competition, frame, turn, ball, foul, pause, achievement and shot-clock blocks are added only when relevant. Each logical event receives one UUID event ID before it enters the durable outbox; a retry keeps that same ID.

Match blocks include the table plus both team names and player lists, making call-up announcements possible without another lookup. Turn events include previous and current side/player details. Pot events include the side, player, number potted and balls remaining. Foul events include the frame, side, player and that player’s match total. Pause and resume events include the active frame, side and player. Achievement events include the verified type, player, side, frame and run. Shot-clock events include the frame, side, player, total limit and threshold remaining.

Schema versioning

Schema version 1 is the current contract. CueTracker validates the version when building every event envelope. Adding an optional field or a new event name remains version 1; removing or renaming a field, changing its type, or changing required envelope semantics requires a new schema version. Consumers should reject unsupported major schema versions and ignore unknown optional fields.

Delivery behaviour

Subscribe to the exact /events topic for automations based on event names. A wildcard subscription also receives retained match-state updates and availability messages. CueTracker operators monitor active connections, last successful publish time, publish successes and failures, reconnects, pending messages and cap drops; broker credentials are never included in those metrics.

Home Assistant use

These examples listen to the same club event topic but respond only to one selected event name.

Call both sides to their table

alias: CueTracker - call players to table
mode: queued
trigger:
  - platform: mqtt
    topic: cuetracker/club-id/events
condition:
  - condition: template
    value_template: "{{ trigger.payload_json.event == 'match.called_to_table' }}"
action:
  - service: notify.mobile_app_club_manager
    data:
      title: "Match ready · {{ trigger.payload_json.match.table }}"
      message: >-
        {{ trigger.payload_json.match.teams.A.players | join(', ') }} versus
        {{ trigger.payload_json.match.teams.B.players | join(', ') }}.
        Please report to {{ trigger.payload_json.match.table }}.

Celebrate a Master Break or Master First Visit

alias: CueTracker - master achievement party
mode: queued
trigger:
  - platform: mqtt
    topic: cuetracker/club-id/events
condition:
  - condition: template
    value_template: >-
      {{ trigger.payload_json.event in
         ['achievement.master_break', 'achievement.master_first_visit'] }}
action:
  - service: light.turn_on
    target:
      entity_id: light.pool_room
    data:
      flash: short
      color_name: purple
  - service: media_player.play_media
    target:
      entity_id: media_player.pool_room
    data:
      media_content_id: https://example.com/master-achievement.mp3
      media_content_type: music

The event’s achievement.player and achievement.type values can also be used in a spoken announcement or display animation. For reliable real-world use, store the event ID in the automation so repeated QoS 1 delivery does not call the players or play the same celebration twice.