Device Status Tracking Blueprint

Continuously monitor whether GPS devices are actively reporting, and automatically transition them between online, offline, and unknown states based on configurable inactivity thresholds, emitting …

   
Feature device-status-tracking
Category Data
Version 1.0.0
Tags gps, tracking, device-status, connectivity, fleet, monitoring
YAML Source View on GitHub
JSON API device-status-tracking.json

Actors

ID Name Type Description
device GPS Device external Physical hardware that transmits positions; its silence drives offline detection
scheduler Inactivity Checker system Periodically scans devices whose last_update has exceeded the inactivity threshold
fleet_user Fleet User human Views real-time device status in the fleet map or device list

Fields

Name Type Required Label Description
status select Yes Current connectivity status: online, offline, or unknown  
last_update datetime No Timestamp of the most recently received position from this device  
inactivity_start number No Milliseconds of silence after which the device is flagged as inactive; inherited from group if no…  
inactivity_period number No Repeat interval (milliseconds) for generating repeated inactivity events after the initial one  

States

State field: status

Values:

State Initial Terminal
unknown Yes  
online    
offline    

Transitions:

Name From To Actor Condition
  unknown online device  
  offline online device  
  online offline scheduler  
  unknown offline scheduler  

Rules

  • processing:
    • online_on_position_received: Status transitions to online as soon as a new position is received, regardless of current status
    • offline_on_inactivity_threshold: Status transitions to offline when (current_time - last_update) > inactivity_start
    • threshold_inheritance: If inactivity_start is not set on the device, it inherits the value from the parent group or server default
    • check_schedule: The inactivity check runs on a configurable schedule (typically every few minutes); status is not updated in real time between check runs
    • repeated_inactivity_events: If inactivity_period is set, repeated inactivity events are generated each time the silence duration increases by another inactivity_period interval
  • event_emission:
    • transitions_trigger_notifications: Status transitions are recorded as events and can trigger notifications to fleet users

Outcomes

Device_remains_inactive (Priority: 4)

Given:

  • device continues to be silent beyond additional inactivity_period intervals
  • inactivity_period (db) gt 0

Then:

  • emit_event event: device.inactive

Result: Repeated inactivity event emitted at each period boundary while device remains silent

Device_goes_offline (Priority: 5)

Given:

  • scheduler determines that (now - last_update) > inactivity_start
  • status (db) eq online

Then:

  • set_field target: status value: offline
  • emit_event event: device.offline

Result: Device is marked offline; alert handlers can dispatch notifications to users

Device_comes_online (Priority: 8)

Given:

  • device transmits a new position
  • status (db) neq online

Then:

  • set_field target: status value: online
  • set_field target: last_update value: now
  • emit_event event: device.online

Result: Device status is updated to online and subscribers are notified

Errors

Code Status Message Retry
DEVICE_STATUS_NOT_FOUND 404 The specified device does not exist No

Events

Event Description Payload
device.online Device has resumed transmitting positions after being offline or unknown device_id, last_update
device.offline Device has exceeded the inactivity threshold without transmitting device_id, last_update, silence_duration_ms
device.inactive Device remains silent beyond a repeated inactivity period boundary device_id, silence_duration_ms
Feature Relationship Reason
gps-device-registration required Devices must be registered before their status can be tracked
gps-position-ingestion required Receiving a position is the trigger for transitioning to online
device-alarm-notifications recommended Offline events can be routed as notifications to fleet users

AGI Readiness

Goals

Reliable Device Status Tracking

Continuously monitor whether GPS devices are actively reporting, and automatically transition them between online, offline, and unknown states based on configurable inactivity thresholds, emitting …

Success Metrics:

Metric Target Measurement
data_accuracy 100% Records matching source of truth
duplicate_rate 0% Duplicate records detected post-creation

Constraints:

  • performance (non-negotiable): Data consistency must be maintained across concurrent operations

Autonomy

Level: supervised

Human Checkpoints:

  • before transitioning to a terminal state

Escalation Triggers:

  • error_rate > 5

Tradeoffs

Prefer Over Reason
data_integrity performance data consistency must be maintained across all operations

Coordination

Protocol: orchestrated

Consumes:

Capability From Fallback
gps_device_registration gps-device-registration degrade
gps_position_ingestion gps-position-ingestion degrade

Safety

Action Permission Cooldown Max Auto
device_comes_online autonomous - -
device_goes_offline autonomous - -
device_remains_inactive autonomous - -
Extensions (framework-specific hints) ```yaml source: repo: https://github.com/traccar/traccar project: Traccar GPS Tracking Server tech_stack: Java 17, Hibernate files_traced: 6 entry_points: - src/main/java/org/traccar/model/Device.java - src/main/java/org/traccar/schedule/TaskDeviceInactivityCheck.java ```