Sign states

A sign is in exactly one of five states at any moment. This page is the lookup reference — colors, meanings, transition triggers, and the heartbeat thresholds that drive automated transitions.

For narrative explanations of how monitoring works, see Monitoring & health.

State table

Color semantics:

• Green (online): everything working
• Gray (offline): absence of signal — not necessarily broken, just not heard from
• Red (error): active failure requiring attention
• Amber (maintenance): intentionally out of service
• Yellow (unlinked): needs action, but not broken

Transition rules

                       ┌──────────────────────┐
                       │      unlinked        │
                       │ (DB record, no       │
                       │   device claimed)    │
                       └──────┬───────────────┘
                              │ link/claim
                              ↓
       ┌──────────────────────────────────────────┐
       │                  online                  │
       └─┬──────────┬──────────┬─────────┬────────┘
         │          │          │         │
         │          │          │         │ Ctrl+Shift+Q on kiosk,
         │          │          │         │ or .maintenance sentinel
         │          │          │         ↓
         │          │          │      ┌─────────────────┐
         │          │          │      │  maintenance    │
         │          │          │      └────────┬────────┘
         │          │          │               │ reboot, sentinel removed
         │          │          │               ↓
         │          │          │             online
         │          │          │
         │          │ kiosk emits sign:content_unreachable
         │          ↓
         │       ┌──────────┐
         │       │  error   │
         │       └────┬─────┘
         │            │ kiosk emits sign:content_recovered
         │            ↓
         │         online
         │
         │ no heartbeat for 15s+ (3 missed beats)
         ↓
      ┌──────────┐
      │ offline  │
      └────┬─────┘
           │ heartbeat resumes
           ↓
        online

A sign can also transition to unlinked at any time when an admin unregisters or deletes the device from the dashboard.

Online ↔ offline thresholds

The 60 s notification deferral means a sign that goes offline and comes back within ~75 s total never notifies anyone. The dashboard still reflects the brief offline blip in the audit log.

Cadence is fixed. The 5-second emit interval and the 60-second notification deferral are product defaults; they aren't customer-tunable per-kiosk. Backend ping/pong cadences are deployment-side settings. If you're investigating disconnect timing on a specific kiosk, the lever is venue-side network hygiene (firewall keepalive, AP stability), not these cadences.

How each state is determined

The kiosk's heartbeat carries a fixed status: 'online'. Other states are derived backend-side from auxiliary signals:

The kiosk cannot self-report offline, error, or maintenance in its heartbeat — those are backend-derived conclusions.

Orthogonal mode field

In addition to the five states above, heartbeats carry an orthogonal mode field:

This isn't a new state — a sign can be online + mode monitoring (running normally but display intentionally dark) or online + mode active (running and displaying). The dashboard surfaces mode: 'monitoring' as a Monitoring badge alongside the state color.

States that trigger notifications

Per the Notifications defaults:

Notification types

The filter key is the dashboard's per-event subscription toggle. Subscribing to signOffline covers sign_offline, content_unreachable, content_recovered, and network_failover — the four "offline-flavored" notifications.

State persistence

Sign state is not persistent across DisplaySync deploys — Redis holds the latest heartbeat with a 30 s TTL. If the backend restarts or Redis flushes, signs all transition to offline briefly until each kiosk emits its next heartbeat (within 5 s).

The sign's historical state transitions live in the audit log indefinitely, scoped per-event.

Source of truth

Sign-state colors and names are part of the product surface — the dashboard, mobile app, and these docs all derive from the same canonical list. If you see a state name or color that disagrees with what your dashboard shows, the dashboard is authoritative.

Pre-claim lifecycle

Before a sign reaches one of the five states above, it goes through a brief pre-claim lifecycle managed in Redis (not the SQL Sign records table).

The handshake-in-flight stage is part of the acknowledged claim flow when LINK_HANDSHAKE_ENABLED is enabled. See Claiming signs → How a claim is committed.

See also

• Monitoring & health — the narrative companion to this reference
• Sign won't claim — common state-transition issues at claim time
• Sign shows offline — diagnosing unwanted offline transitions