IoT: PTP Time
Sensors, lidar and broadcast gear can share one clock over the Precision Time Protocol (PTP, IEEE 1588). A device stamps each reading with a PTP timestamp. That timestamp counts TAI, which has no leap seconds, so it is not UTC. A receiver turns it into UTC by subtracting an offset that its grandmaster announces. If it skips that step, the data sits 37 seconds ahead of every other clock, and nothing raises an error.
The functions here apply the announced offset in both directions and check the timestamp record. They take the offset from the caller and never pick one.
import { ptpToUtc, utcToPtp } from "@northguild/gmt/iot/convert";import { isValidPtpTimestamp } from "@northguild/gmt/iot/validate";The functions live in @northguild/gmt/iot/convert and @northguild/gmt/iot/validate.
TAI on the wire
Section titled “TAI on the wire”RFC 8877 section 4.3 says PTP “uses an 80-bit timestamp format”. The nanoseconds take 32 bits, so the 80-bit timestamp leaves 48 bits for the seconds. The RFC also says the timestamp is “not affected by leap seconds”. The count starts at 1970-01-01T00:00:00 TAI.
That is the same epoch value as Unix time, but a different time scale. UTC has stepped 27 times since 1972 to stay near the Earth’s rotation, and TAI has not. As of 2024, TAI is 37 seconds ahead of UTC. Reading a PTP count as Unix seconds therefore gives a time 37 seconds ahead of the truth.
GMT holds the record as { seconds, nanoseconds }. The seconds come back as a bigint, and a
safe-integer number is read too, because a 48-bit count fits in one.
The announced offset
Section titled “The announced offset”currentUtcOffset is TAI minus UTC, as a signed 16-bit integer. RFC 8575 defines it as the
current-utc-offset leaf of time-properties-ds, which the grandmaster announces. Reading it
out of an Announce message is IEEE 1588’s job and is not reached here.
ptpToUtc(record, offset) subtracts the offset and returns a
UTC instant string. utcToPtp(instant, offset) adds it back
and returns the record, or null. The two are inverses for the same offset.
import { ptpToUtc, utcToPtp } from "@northguild/gmt/iot/convert";
ptpToUtc({ seconds: 1704067237n, nanoseconds: 0 }, 37);// "2024-01-01T00:00:00Z"utcToPtp("2024-01-01T00:00:00Z", 37);// { seconds: 1704067237n, nanoseconds: 0 }utcToPtp("2024-01-01T02:00:00+02:00", 37);// { seconds: 1704067237n, nanoseconds: 0 } (a numeric offset in the input is read)utcToPtp("2024-01-01T00:00:00.5Z", 37);// { seconds: 1704067237n, nanoseconds: 500000000 }The round trip gives the record it started with.
import { ptpToUtc, utcToPtp } from "@northguild/gmt/iot/convert";
const utc = ptpToUtc({ seconds: 1704067237n, nanoseconds: 0 }, 37);// "2024-01-01T00:00:00Z"
utcToPtp(utc, 37);// { seconds: 1704067237n, nanoseconds: 0 }The 37-second error
Section titled “The 37-second error”Pass 0 and the function reads the count as a receiver does that ignores the offset. The result
is a valid instant, 37 seconds ahead.
import { ptpToUtc } from "@northguild/gmt/iot/convert";
ptpToUtc({ seconds: 1704067237n, nanoseconds: 0 }, 37);// "2024-01-01T00:00:00Z" (the right reading)ptpToUtc({ seconds: 1704067237n, nanoseconds: 0 }, 0);// "2024-01-01T00:00:37Z" (37 s ahead, and no error)Nothing in the second result says it is wrong. The frames from a lidar that were stamped this way sit 37 seconds ahead of the camera’s. See A PTP Stamp 37 Seconds Ahead.
No default, on purpose
Section titled “No default, on purpose”The offset has no default. In TypeScript, leaving it out is a type error. At run time, from
JavaScript or an any, it returns the sentinel for invalid input, and never a guess.
import { ptpToUtc, utcToPtp } from "@northguild/gmt/iot/convert";
ptpToUtc({ seconds: 1704067237n, nanoseconds: 0 });// ""utcToPtp("2024-01-01T00:00:00Z");// nullA default of 37 would be right today and wrong for any grandmaster that announces another value.
The offset must be an integer from -32768 to 32767, and 37.5 returns "".
The flags beside the offset
Section titled “The flags beside the offset”RFC 8575’s time-properties-ds announces three other values next to the offset.
ptp-timescalefalse means the arbitrary time scale (ARB). The offset then has no meaning.current-utc-offset-validfalse means the number is not valid.time-traceablesays whether the time can be traced to a primary reference, so whether to trust the reading at all.
The library reads none of the three. The record carries only the count, and the function receives
only the offset, so it cannot see a flag. Check them before you call. If ptpTimescale is false or
currentUtcOffsetValid is false, do not call ptpToUtc with the number. In that state the number
may be stale, a default, or 0, and passing a 0 through gives the 37-second error with no
warning.
Checking a grandmaster against the table
Section titled “Checking a grandmaster against the table”The functions apply the offset you give them and never look up the leap-second table. To check
the grandmaster, compare the announced offset with what the table says for the reading, using
taiMinusUtc from timescale.
import { ptpToUtc } from "@northguild/gmt/iot/convert";import { taiMinusUtc } from "@northguild/gmt/timescale/calculate";
const record = { seconds: 1704067237n, nanoseconds: 0 };
const reading = ptpToUtc(record, 36);// "2024-01-01T00:00:01Z" (a grandmaster still announcing the 2016 value)taiMinusUtc(reading);// 37 (not the 36 it announced)The announced 36 was right until the end of 2016. The table says 37 for this date, so the two
disagree and the reading is 1 second out.
fromTAI from timescale converts through the table
and ignores the announcement. Use it when you want to know what UTC was, and use ptpToUtc when
you want to know what the receiver read. They differ exactly when the grandmaster is wrong.
import { fromTAI } from "@northguild/gmt/timescale/convert";
fromTAI("2024-01-01T00:00:37 TAI");// "2024-01-01T00:00:00Z" (what UTC was, whatever the grandmaster announced)See Leap seconds and TAI for the table.
The lookup uses the announced reading, so within a second of a step it can be one second out. A
record stamped during the inserted second of 2016-12-31, read with the correct offset of 36,
shows it.
import { ptpToUtc } from "@northguild/gmt/iot/convert";import { taiMinusUtc } from "@northguild/gmt/timescale/calculate";
const record = { seconds: 1483228836n, nanoseconds: 0 };
const reading = ptpToUtc(record, 36);// "2017-01-01T00:00:00Z" (the function never writes a second of 60)taiMinusUtc(reading);// 37 (the table's answer for the next second, not the 36 announced)Before 1970, before 1972, and leap seconds
Section titled “Before 1970, before 1972, and leap seconds”- Before 1970. A count smaller than the offset gives a result before the epoch, and
ptpToUtcreturns"". In practice this is a clock that was never set. - Before 1972. UTC had no whole-second offset from TAI before 1972. The IERS file
Leap_Second.dat, as of IERS Bulletin C 72, starts at 1972-01-01 with TAI − UTC at 10 seconds, and ITU-R TF.460-6 defines UTC from 1972. SotaiMinusUtcreturnsnullthere and no offset is a true reading. The functions still do the arithmetic with the offset you pass. - A leap second.
utcToPtprefuses…23:59:60Z, because one offset for the whole call gives an inserted second no reading of its own. During an insertion, pass the newly announced offset.
import { ptpToUtc, utcToPtp } from "@northguild/gmt/iot/convert";import { taiMinusUtc } from "@northguild/gmt/timescale/calculate";
ptpToUtc({ seconds: 0n, nanoseconds: 0 }, 37);// "" (before 1970: an unset clock)ptpToUtc({ seconds: 37n, nanoseconds: 0 }, 37);// "1970-01-01T00:00:00Z"taiMinusUtc("1971-01-01T00:00:00Z");// null (before 1972)utcToPtp("2016-12-31T23:59:60Z", 37);// null (a second of 60)Checking a record
Section titled “Checking a record”isValidPtpTimestamp(value) checks the record
against the ranges of the wire format. The seconds member is a bigint or a safe-integer
number from 0 to 2⁴⁸ − 1, and nanoseconds is an integer number from 0 to 999 999 999. Both
members are required. It is a type predicate, so it narrows unknown to a record.
import { isValidPtpTimestamp } from "@northguild/gmt/iot/validate";
isValidPtpTimestamp({ seconds: 1704067237n, nanoseconds: 0 });// trueisValidPtpTimestamp({ seconds: 1704067237, nanoseconds: 999999999 });// true (number seconds)isValidPtpTimestamp({ seconds: 281474976710656n, nanoseconds: 0 });// false (2⁴⁸)isValidPtpTimestamp({ seconds: 0n, nanoseconds: 1000000000 });// falseisValidPtpTimestamp({ seconds: 0n });// false (no nanoseconds)isValidPtpTimestamp("2024-01-01T00:00:00Z");// falseA record that passes can still convert to something before 1970. It checks the record, not a conversion.
import { ptpToUtc } from "@northguild/gmt/iot/convert";import { isValidPtpTimestamp } from "@northguild/gmt/iot/validate";
isValidPtpTimestamp({ seconds: 0n, nanoseconds: 0 });// trueptpToUtc({ seconds: 0n, nanoseconds: 0 }, 37);// "" (the result would be before 1970)What this layer does not do
Section titled “What this layer does not do”- It does not parse an Announce message or any PTP message bytes. It starts from the seconds, the nanoseconds and the offset you have already read.
- It does not apply the rules of gPTP (IEEE 802.1AS). The same trap applies there, but its text was not reached, so GMT claims nothing about it. IEC/IEEE 61588 itself was also not reached.
- It does not look up the leap-second table inside
ptpToUtcorutcToPtp. Checking the announcement against the table is your call totaiMinusUtc. - It does not read
ptpTimescale,currentUtcOffsetValidortimeTraceable. You check them.
See it break, then work
Section titled “See it break, then work”- A PTP Stamp 37 Seconds Ahead
- IoT mistakes
- PTP Clock Converter, a tool that reads a PTP timestamp as UTC, beside the same count with the offset ignored, and checks the offset against the table
Sources
Section titled “Sources”- IETF, RFC 8877, section 4.3: the 80-bit PTP timestamp, the epoch, and “not affected by leap seconds”.
- IETF, RFC 8575, the
time-properties-dscontainer:current-utc-offset,current-utc-offset-valid,ptp-timescaleandtime-traceable. - IERS,
Leap_Second.dat, and Bulletin C 72: TAI − UTC from 1972-01-01, the tabletaiMinusUtcreads. - ITU-R Recommendation TF.460-6: UTC defined from 1972.
- IEC/IEEE 61588 (IEEE 1588): not reached. Its text, including how the Announce message carries the offset, is not cited.
© 2026 NorthGuild · Licences
Code examples: MIT-0. Packages: MIT. Third-party data and components: their own licences, credited where they appear. Everything else: © 2026 NorthGuild, all rights reserved.