PTP Clock Converter
A Precision Time Protocol (IEEE 1588) timestamp is a count of seconds and nanoseconds from 1970-01-01T00:00:00 TAI. ptpToUtc turns a record and the currentUtcOffset into a UTC string, and gives "" when it cannot. isValidPtpTimestamp says whether the record is in range. A second section checks the announced offset against the leap-second table with taiMinusUtc and draws the two on a fixed ruler, and a last section goes the other way with utcToPtp. Everything on the page is what those calls returned.
The offset has no default. The library does not guess one: the grandmaster announces it, and a receiver that assumes 0, or the value from last year’s firmware, is wrong without any sign. That is why the offset box sits in section 1 and section 3 reads it too.
Two flags the library does not read. A grandmaster also announces currentUtcOffsetValid and ptpTimescale. The library reads neither, so the tool has no switch for them: a receiver checks both before it trusts the offset. The guide, IoT: PTP time, says how.
The check. The table plate is taiMinusUtc at the announced reading, so it can be one second out within a second of a step. At 2024-01-01T00:00:00Z it is 37, and an announced offset of 36 shows as 1 s apart on the ruler. The ruler runs from 0 to 40 s and never rescales; an offset outside it is drawn at the edge and named “off the ruler”.
Refusals. The library gives no reason, so the tool asks again. If the record is out of range, that is the reason. If a known-good record with the same offset is refused, the offset is. If the record read at offset 0 is refused too, the count is past the last instant the library can write. Otherwise the count is smaller than the offset, which in practice is a clock that was never set. Section 3 names a leap second or a time before 1970 only when the text is exactly the preset that shows it.
import { ptpToUtc, utcToPtp } from "@northguild/gmt/iot/convert";import { isValidPtpTimestamp } from "@northguild/gmt/iot/validate";import { taiMinusUtc } from "@northguild/gmt/timescale/calculate";
const record = { seconds: 1704067237n, nanoseconds: 0 };ptpToUtc(record, 37); // "2024-01-01T00:00:00Z"ptpToUtc(record, 0); // "2024-01-01T00:00:37Z"ptpToUtc(record, 36); // "2024-01-01T00:00:01Z"taiMinusUtc("2024-01-01T00:00:00Z"); // 37isValidPtpTimestamp({ seconds: 281474976710656n, nanoseconds: 0 }); // falseutcToPtp("2024-01-01T02:00:00+02:00", 37); // { seconds: 1704067237n, nanoseconds: 0 }utcToPtp("2016-12-31T23:59:60Z", 37); // nullWorth trying: a stale offset of 36 is 1 s out; offset 0 is 37 s out; and a clock that was never set is refused.
© 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.