Skip to content

IoT: PTP Time

  • Device and sensor time on industrial networks: Precision Time Protocol timestamps, which count TAI, and the UTC offset a grandmaster announces.

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.

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.

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 }

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.

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");
// null

A 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 "".

RFC 8575’s time-properties-ds announces three other values next to the offset.

  • ptp-timescale false means the arbitrary time scale (ARB). The offset then has no meaning.
  • current-utc-offset-valid false means the number is not valid.
  • time-traceable says 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.

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 ptpToUtc returns "". 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. So taiMinusUtc returns null there and no offset is a true reading. The functions still do the arithmetic with the offset you pass.
  • A leap second. utcToPtp refuses …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)

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 });
// true
isValidPtpTimestamp({ seconds: 1704067237, nanoseconds: 999999999 });
// true (number seconds)
isValidPtpTimestamp({ seconds: 281474976710656n, nanoseconds: 0 });
// false (2⁴⁸)
isValidPtpTimestamp({ seconds: 0n, nanoseconds: 1000000000 });
// false
isValidPtpTimestamp({ seconds: 0n });
// false (no nanoseconds)
isValidPtpTimestamp("2024-01-01T00:00:00Z");
// false

A 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 });
// true
ptpToUtc({ seconds: 0n, nanoseconds: 0 }, 37);
// "" (the result would be before 1970)
  • 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 ptpToUtc or utcToPtp. Checking the announcement against the table is your call to taiMinusUtc.
  • It does not read ptpTimescale, currentUtcOffsetValid or timeTraceable. You check them.
  • 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-ds container: current-utc-offset, current-utc-offset-valid, ptp-timescale and time-traceable.
  • IERS, Leap_Second.dat, and Bulletin C 72: TAI − UTC from 1972-01-01, the table taiMinusUtc reads.
  • 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.