ptpToUtc
Signature
Section titled “Signature”ptpToUtc(timestamp: PtpTimestamp | { seconds: number; nanoseconds: number; }, currentUtcOffset: number): stringConverts a PTP (IEEE 1588) timestamp to a UTC instant string ending in Z.
- A PTP timestamp counts TAI seconds since 1970-01-01T00:00:00 TAI. The result is
seconds + nanoseconds × 10⁻⁹ − currentUtcOffsetseconds after 1970-01-01T00:00:00Z. currentUtcOffsetis TAI − UTC, as the grandmaster announces it in its time properties (RFC 8575 section 3 defines thecurrent-utc-offsetleaf and itsint16type only; that the Announce message carries it is IEEE 1588, not reached). It is required and has no default. Passing0gives the reading of a receiver that ignores the offset: 37 s ahead from 2017 on.- Two preconditions. Call this function only when the grandmaster announces
ptpTimescaletrue andcurrentUtcOffsetValidtrue. On the arbitrary time scale (ARB) the offset “has no meaning”, and when the offset is not marked valid the number is not valid. The function cannot see either flag, so it cannot check them. WhentimeTraceableis false, the offset is not traceable to a primary reference. - It applies the announced offset and does not look up the leap-second table. To check the grandmaster’s offset, compare
currentUtcOffsetwithtaiMinusUtc(result). - It never writes a second of
60. During an inserted second, the reading follows whichever offset the caller passes. Pass the new offset once the grandmaster announces it. secondscan be abigintor a safe-integernumber, from 0 to 2^48 − 1.nanosecondsmust be an integernumberfrom 0 to 999 999 999. Both members are required.- Returns
""for an invalid record or offset, for a result before 1970-01-01T00:00:00Z (in practice a clock that has not been set), and for a result past+275760-09-13T00:00:00Z. A year past 9999 is written in Temporal’s expanded form (+010000-…). It never throws.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
timestamp | PtpTimestamp | { seconds: number; nanoseconds: number; } | PTP timestamp, with bigint or safe-integer number seconds |
currentUtcOffset | number | TAI − UTC in seconds, as announced: an integer from -32768 to 32767 |
Returns
Section titled “Returns”the UTC instant string, or "" on invalid input
Related types
Section titled “Related types”Examples
Section titled “Examples”import { ptpToUtc } from "@northguild/gmt/iot/convert";
ptpToUtc({ seconds: 1704067237n, nanoseconds: 0 }, 37) // "2024-01-01T00:00:00Z"Source
Section titled “Source”© 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.