Digital Lock On

Appearance

ADR-007: Heartbeat Frequency for Handover System ​

Status: Completed
Date: 2025-08-20
Affects: REQ-PROT-008: Worksite Protector Handover, ADR-006: Handover Flow Design

Scope Clarification ​

(Added 2025-10-31) While initially designed for handover sessions, this heartbeat mechanism serves as the system-wide presence detection layer. It enables the platform to:

  • Detect offline devices during handover (original purpose)
  • Restrict functionality requiring online connectivity
  • Support data synchronisation strategies (see ADR-009)

The 5-second interval remains appropriate for these broader use cases.

Context ​

During the handover system design, we needed to determine the optimal heartbeat frequency for the outgoing protector's device. The heartbeat system ensures that the server can detect if the outgoing protector goes offline and automatically cancel the handover to prevent conflicts.

The team discussed various intervals:

  • 5-10 seconds: More responsive, better for safety-critical operations
  • 10-30 seconds: Less network overhead, more forgiving of temporary connectivity issues

Decision ​

We will use a 5 second heartbeat interval for the handover system.

Consequences ​

Positive ​

  • Faster Detection: Quicker detection of offline protectors (within 5-10 seconds)
  • Better Safety: Reduces the window where two protectors might think they have control
  • Responsive UX: Users get faster feedback about handover status changes
  • Rail Safety Alignment: Appropriate for safety-critical rail protection operations

Negative ​

  • Higher Network Usage: More frequent API calls (though minimal data transfer)
  • Battery Impact: Slightly higher battery usage on mobile devices
  • Server Load: More frequent heartbeat processing on the server

Neutral ​

  • Configurable: The exact interval can be tuned per environment
  • Standard Practice: 5-10 seconds is a common heartbeat interval for real-time systems

Implementation Notes ​

Configuration ​

  • Default Interval: 5 seconds
  • Environment Override: Configurable via environment variables

Technical Considerations ​

  • Timeout Calculation: Handover automatically cancels after 2 missed heartbeats
  • Grace Period: Allow for network latency and temporary connectivity issues
  • Fallback: If heartbeat fails, retry once before marking as offline

Monitoring ​

  • Success Rate: Track heartbeat success/failure rates
  • Network Performance: Monitor impact on overall system performance
  • User Experience: Ensure heartbeats don't interfere with normal app usage

Alternatives Considered ​

10-30 Second Intervals ​

  • Pros: Lower network overhead, more forgiving of connectivity issues
  • Cons: Slower offline detection, larger safety risk window
  • Rejection Reason: Safety-critical nature of rail protection requires faster response

1-5 Second Intervals ​

  • Pros: Very fast offline detection
  • Cons: Excessive network usage, potential battery drain
  • Rejection Reason: Over-engineering for the safety requirements

Review Notes ​

This decision was made to balance safety requirements with practical implementation considerations. The 5-10 second interval provides the right balance of responsiveness and efficiency for rail protection operations.

Internal use only