Design a heartbeat for a desk notification light
Status Light can represent software activity through a custom integration, but a colour without freshness information can become misleading. A heartbeat is a periodic liveness signal between components of that integration. Define what it proves before using it to keep a display looking healthy. Bridge activity, source availability and successful hardware control are different conditions.
Which component should send the heartbeat?
Choose the component whose absence you need to detect. A receiver heartbeat can show that its process is responding, while a worker heartbeat can show that the device-writing process is alive. Neither automatically proves that the upstream job source remains reachable.
Document the meaning in plain language, such as bridge last responded or source last checked. Avoid a generic healthy label that hides the boundary being monitored. If several components matter, retain separate timestamps internally even when the physical display can show only a simplified state.
How should freshness affect the displayed result?
Keep the task outcome and the age of the evidence as separate values. A previously successful job does not become a failed job because the bridge disappears, but its displayed status may no longer be trustworthy. Define a supported visual convention for stale information rather than silently leaving an apparently current success.
Do not assume the device supports flashing patterns or arbitrary combinations without confirmation. If the available hardware states cannot express every distinction, use a companion text indicator or a documented priority rule. The physical signal should direct attention without pretending to carry more information than it can.
How do you choose a timeout?
Base it on the expected heartbeat interval, ordinary delays and how quickly stale information matters to your workflow. Allow for scheduling jitter so a single minor delay does not repeatedly change the display. There is no universal duration appropriate to every desk integration.
Test the rule with delayed and missing signals, not just the normal path. Use elapsed-time handling appropriate to your runtime for local expiry decisions. If timestamps cross machines, consider clock differences instead of assuming every recorded time can be compared without qualification.
What should happen after recovery?
Require the relevant checks to succeed again, then resynchronise the current task state before restoring a confident display. A resumed heartbeat should not automatically revive an old green command. Record why the integration changed from stale to current so the behaviour can be diagnosed later.
The Status Light product page describes the physical signal device. Heartbeats and freshness rules belong to the software you build around it, and need tests that distinguish process liveness from actual end-to-end status delivery.