Skip to content

PTP Clock Converter

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

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.

1. Read a PTP timestamp

The count minus the offset is UTC.

UTC
nothing typed
ptpToUtc
Offset ignored
nothing typed
ptpToUtc

Type the seconds, the nanoseconds and the offset.

2. Check the offset

The announced offset against the leap-second table, read at the announced UTC reading.

Table offset
nothing typed
taiMinusUtc
Table reading
nothing typed
ptpToUtc

No reading, so nothing to check

Nothing to draw.

3. Write a PTP timestamp

Writing uses the offset typed in section 1.

02:00 at +02:00 is midnight UTC.

Seconds
nothing typed
utcToPtp
Nanoseconds
nothing typed
utcToPtp

Round trip: nothing typed

Type a UTC instant, such as 2024-01-01T00:00:00Z.

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"); // 37
isValidPtpTimestamp({ seconds: 281474976710656n, nanoseconds: 0 }); // false
utcToPtp("2024-01-01T02:00:00+02:00", 37); // { seconds: 1704067237n, nanoseconds: 0 }
utcToPtp("2016-12-31T23:59:60Z", 37); // null

Worth 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.