Reading HOS Timer Clocks

Recommended calculation

This is the same logic the Platform Science portal uses to display live clocks between messages. Apply it to each entry in data.attributes.timers.

for each timer in data.attributes.timers:

    if timer.next_reset_timestamp is not null
       and NOW() >= timer.next_reset_timestamp:
        # the driver completed the qualifying rest; clock is full
        current = timer.available_hours * 3600

    else if timer.running == true:
        current = timer.seconds_left
                  - seconds_between(data.attributes.submitted_at, NOW())

    else:
        # paused clock: hold the value exactly as sent
        current = timer.seconds_left

Use submitted_at, not submitted_at_original. Before publishing, Platform Science advances seconds_left to the moment the message is sent and sets submitted_at to that moment. submitted_at_original is the time the device calculated the clocks. Counting down from it subtracts the same elapsed time twice, so running clocks drift low.

A new message replaces everything. When one arrives, discard your running values and start again from its fields.

Which clocks run in which duty status

US 70-hour / 8-day property ruleset. The running flag in each message already reflects this table. It is here so you can check what you see in the data.

Personal conveyance is treated as off duty. Yard move is treated as on duty. The 60-hour / 7-day ruleset follows the same pattern with a 60-hour cycle and a 7-day window.

Where do the clocks stop when the driver is in the sleeper berth?

We see drift compared to the UI while the driver is in the sleeper.

In the sleeper berth the 11 and the 70 stop, and the 14 keeps running until a qualifying rest is complete. When the device determines that a sleeper period qualifies as part of a split sleeper pair, the 14 is adjusted to exclude that period, and the 11 and 14 are recalculated from the end of the first rest period of the pair.

Two things commonly cause drift in sleeper:

• Counting down a clock whose running value is false, for example applying driving or on-duty rules to the 11 or 70.
• Counting from submitted_at_original instead of submitted_at.

Messages are sent on events (duty status changes, violations, scheduled recalculation points such as a reset), not on a fixed interval. A driver can sit in the sleeper for hours with no new message. During split sleeper, the device can change a clock's paused or running state at a scheduled point between messages. The feed carries a snapshot, not that schedule, so a short difference from the portal is possible until the next message arrives.

When the device stops communicating, does Platform Science reset the clocks?

There is no communication-loss threshold. The portal shows full clocks when, and only when, the next_reset_timestamp sent by the device has passed. That timestamp is the device's forecast of when the driver's current rest will complete the reset (10 hours for the 11 and 14, 30 minutes for the 8, 34 hours for the 70).

Do the same on your side: once NOW() >= next_reset_timestamp, show available_hours in full for that clock. No separate reset message is sent when that time passes.

When next_reset_timestamp is null, the driver is not currently in a rest that would reset that clock, and the clock should not reset automatically.

Should a negative 11 or 14 be reset to full?

No. A clock does not reset because it went negative. It stays negative until the driver completes a qualifying rest (see Q4). There is no threshold that restores hours.

Reset rules for each clock

Each clock resets under its own rule, independently of the others. A partial state, where one clock is full and another is not, is normal and correct. For example, after a 10-hour break the 11 and 14 are full while the 70 can still be partly used.

Changes that are not a full reset

• Split sleeper berth. One rest of at least 2 hours (off duty or sleeper) paired with one of at least 7 hours in the sleeper berth, totalling at least 10 hours. The 11 and 14 are recalculated from the end of the first rest of the pair, so they usually come back partial, not full.
• Adverse driving conditions. Adds 2 hours to both the 11 and the 14.
• 16-hour short-haul exception. Extends the 14 to 16. available_hours reads 16 while it applies. After a reset the clock returns to 14.

Off duty and sleeper berth time count equally toward every full reset.

When is a negative value expected?

Clocks are not limited to zero. A negative seconds_left means the driver has used more than the limit, but a negative value alone is not a violation. Use the violations array on each timer to see actual violations.

• 14: goes negative when the driver is past 14 hours and has not yet completed a 10-hour rest. It keeps decreasing through on duty, off duty and sleeper berth time. Working on duty past the 14 is permitted. Driving past it is a violation.
• 11: goes negative only while driving past the limit, then holds that value until a 10-hour reset.
• 70: goes negative while on duty or driving past the cycle limit. It holds that value until a 34-hour restart or until hours drop off the 8-day window at midnight.

Show negative values as sent until a reset occurs or a new message arrives.

When should seconds be subtracted, by duty status?

When do we subtract elapsed drive seconds when the status is not Driving? Some of our rules subtract only when the driver is off duty, not in sleeper.

Do not base subtraction on duty status. Subtract elapsed time from a clock only when that clock's running flag is true, and measure elapsed time from submitted_at. The device sets running per clock, taking duty status, split sleeper and exceptions into account.

For reference, a rule that subtracts only during off duty does not match the HOS rules for any clock:

• The 11 counts down only while driving.
• The 70 is paused in both off duty and sleeper berth.
• The 14 counts down in off duty and sleeper berth alike.

There is no other duty-status-based subtraction logic to apply on your side.

Other things to know

• One message per ruleset. Drivers with both US and Canadian rulesets produce a separate message for each. active: true marks the ruleset the driver is currently using.
• Edited logs. By default only current clocks are published. Recalculated clocks for past dates, after a log edit, can be enabled on request. They arrive with is_edit: true and a past timer_date_utc, and should not replace the live clock.
• Driver sessions. Clocks are only as current as the last message. If you need more frequent updates for drivers who are idle for long periods, talk to your Customer Success Representative.