IoT
Industrial sensors, lidar and broadcast gear share one clock over the Precision Time Protocol. Its timestamps count TAI, which has no leap seconds, so a receiver turns them into UTC with the offset its grandmaster announces. This layer applies that offset in both directions and checks the timestamp itself; it never picks an offset for you.
What these functions solve
Section titled “What these functions solve”- A sensor’s time reads ahead of every other clock.
ptpToUtcsubtracts the UTC offset the grandmaster announces, and takes no default, so a missing offset is a type error instead of a silent shift. See guide, scenario, tool. - A grandmaster announces the wrong offset.
taiMinusUtcgives TAI minus UTC from the leap-second table for the reading’s date. Compare it with the announced offset before you trust a reading. See tool, mistakes. - A UTC time put back on the wire loses the offset.
utcToPtpadds the announced offset back and returns the seconds as a bigint, so a round trip gives the same timestamp. See guide, tool. - A malformed timestamp converts without a complaint.
isValidPtpTimestampchecks the seconds and nanoseconds against the ranges the wire format allows. See mistakes. - Nanoseconds are lost on the way to milliseconds.
ptpToUtcwrites every nanosecond the timestamp carries, andtoNanosecondsreads the instant back as a whole count. See guide.
Start with the guide: IoT: PTP Time.
Its own functions
Section titled “Its own functions”ptpToUtc: Converts a PTP (IEEE 1588) timestamp to a UTC instant string ending inZ.utcToPtp: Converts a UTC instant to the PTP (IEEE 1588) timestamp a grandmaster announcingcurrentUtcOffsetwould send.
isValidPtpTimestamp: Return true whenvalueis a PTP timestamp record thatptpToUtcreads.
Functions it draws on
Section titled “Functions it draws on”leapSecondsBetween: Return how many leap seconds start between two UTC instants, signed.nextLeapSecond: Return the first leap second after a UTC instant, as its UTC label…T23:59:60Z.taiMinusUtc: Return TAI − UTC, in whole seconds, at a UTC instant.tcgMinusTt: Return TCG − TT, in seconds, at a UTC instant.
fromJ2000Seconds: Convert seconds since J2000.0 on a time scale to a UTC instant string.fromJulianDate: Convert a single Julian Date on a time scale to a UTC instant string.fromJulianDateParts: Convert a two-part Julian Date on a time scale to a UTC instant string.fromModifiedJulianDate: Convert a Modified Julian Date on a time scale to a UTC instant string.fromTAI: Convert a TAI time-scale string to a UTC instant string.fromTai64n: Convert a TAI64, TAI64N or TAI64NA label in hex text to a UTC instant string.fromTCG: Convert a Geocentric Coordinate Time string to a UTC instant string.fromTT: Convert a Terrestrial Time string to a UTC instant string.toJ2000Seconds: Convert a UTC instant to seconds since J2000.0 on a time scale.toJulianDate: Convert a UTC instant to a single Julian Date on a time scale.toJulianDateParts: Convert a UTC instant to a two-part Julian Date{ jd1, jd2 }on a time scale, exact to the nanosecond.toModifiedJulianDate: Convert a UTC instant to a Modified Julian Date on a time scale.toTAI: Convert a UTC instant to a TAI time-scale string,YYYY-MM-DDTHH:MM:SS[.fraction] TAI.toTai64n: Convert a UTC instant to its TAI64N label in the daemontools text form,@and 24 lowercase hex digits.toTCG: Convert a UTC instant to a Geocentric Coordinate Time string,YYYY-MM-DDTHH:MM:SS[.fraction] TCG.toTT: Convert a UTC instant to a Terrestrial Time string,YYYY-MM-DDTHH:MM:SS[.fraction] TT.
formatCcsdsAsciiA: Write an instant as a CCSDS ASCII Time Code A string (YYYY-MM-DDThh:mm:ss.d…dZ).formatCcsdsAsciiB: Write an instant as a CCSDS ASCII Time Code B string (YYYY-DDDThh:mm:ss.d…dZ, day of year).
parseCcsdsAsciiA: Read a CCSDS ASCII Time Code A (YYYY-MM-DDThh:mm:ss.d…dZ) as an ISO 8601 UTC instant string.parseCcsdsAsciiB: Read a CCSDS ASCII Time Code B (YYYY-DDDThh:mm:ss.d…dZ, day of year) as an ISO 8601 UTC instant string in calendar form.
isLeapSecond: Return true when a UTC instant string is one of the 27 inserted leap seconds.
truncateNanoseconds: Truncate nanoseconds since the Unix epoch to the precision a store can actually hold.
fromArrowLocalTimestamp: Convert theint64of an Apache ArrowTimestampcolumn that has no timezone to a wall-clock date-time string.fromArrowTimestamp: Convert theint64of an Apache ArrowTimestampcolumn that has a timezone to a UTC instant string.fromDotNetTicks: Convert .NETDateTime.Ticksback to an ISO 8601 instant string.fromExcelSerial: Convert an Excel day serial back to an ISO 8601 instant string.fromFileTime: Convert a WindowsFILETIMEback to an ISO 8601 instant string.fromNanoseconds: Convert nanoseconds since the Unix epoch back to an ISO 8601 string.fromNtpTimestamp: Convert a 64-bit NTP timestamp (RFC 5905) back to an ISO 8601 instant string.fromParquetInt96: Convert a ParquetINT96timestamp back to an ISO 8601 instant string.fromPgMicroseconds: Convert PostgreSQL’s internaltimestamptzvalue back to an ISO 8601 instant string.fromProtoDuration: Convert a protobufgoogle.protobuf.Durationrecord back to an ISO 8601 duration string.fromProtoTimestamp: Convert a protobufgoogle.protobuf.Timestamprecord back to an ISO 8601 instant string.toArrowLocalTimestamp: Convert an ISO 8601 plain date-time to theint64of an Apache ArrowTimestampcolumn that has no timezone.toArrowTimestamp: Convert an ISO 8601 instant string to theint64of an Apache ArrowTimestampcolumn that has a timezone.toDotNetTicks: Convert an ISO 8601 instant string to .NETDateTime.Ticks.toExcelSerial: Convert an ISO 8601 instant string to an Excel day serial.toFileTime: Convert an ISO 8601 instant string to a WindowsFILETIME.toNanoseconds: Convert an ISO 8601 instant string to nanoseconds since the Unix epoch.toNtpTimestamp: Convert an ISO 8601 instant string to a 64-bit NTP timestamp (RFC 5905).toParquetInt96: Convert an ISO 8601 instant string to a ParquetINT96timestamp record.toPgMicroseconds: Convert an ISO 8601 instant string to PostgreSQL’s internaltimestamptzvalue.toProtoDuration: Convert an ISO 8601 duration string to a protobufgoogle.protobuf.Durationrecord.toProtoTimestamp: Convert an ISO 8601 instant string to a protobufgoogle.protobuf.Timestamprecord.
formatNanoseconds: Format nanoseconds since the Unix epoch as a decimal string, for JSON and other text transports.
fromKsuid: Read the instant a KSUID carries (segmentio/ksuid,ksuid.goandbase62.go).fromObjectId: Read the creation second a MongoDB ObjectId carries (mongodb/specificationsbson-objectid/objectid.md, § Specification and § Timestamp Field).fromSnowflake: Read the instant a Snowflake id carries, using a layout the caller supplies.fromUlid: Read the instant a ULID carries (ulid/spec README, § Components and § Canonical String Representation).fromUuidTimestamp: Read the instant a version 1, 6 or 7 UUID carries (RFC 9562 §5.1, §5.6, §5.7).ulidTimestampPrefix: The first 10 characters of every ULID minted in the same millisecond as an instant, for range scans over stored ULID text (ulid/spec README, § Components and § Encoding).uuidV7TimestampPrefix: The first 13 characters of every version 7 UUID minted in the same millisecond as an instant, for range scans over stored UUID text (RFC 9562 §5.7, §6.11).
parseNanoseconds: Parse a decimal string produced byformatNanoseconds— typically one field of a JSON payload — back to nanoseconds since the Unix epoch.
isValidInstant: Validate whether a string is an ISO 8601 instant string theprecision/namespace accepts.isValidInt64NanosecondDateTime: Validate whether a string is a plain date-time whose epoch-nanosecond count, read as if it were UTC (Arrow’s rule for a zoneless timestamp), fits anint64: the check to run beforetoArrowLocalTimestamp(dateTime, "nanosecond").isValidInt64NanosecondInstant: Validate whether a string is an instant whose epoch-nanosecond count fits anint64: the check to run beforetoArrowTimestamp(isoString, "nanosecond").isValidNanoPattern: Validate whether a string is a nanosecond timestampparseNanosecondswill parse.isValidNanoseconds: Validate whether a value is an epoch-nanosecondbiginttheprecision/namespace accepts.
Guides
Section titled “Guides”- IoT: PTP Time: Convert a Precision Time Protocol timestamp, which counts TAI, to UTC with the offset the grandmaster announces, write a UTC instant back, check the record, and check the announced offset against the leap-second table.
- PTP Clock Converter: Read a PTP timestamp, TAI seconds and nanoseconds, as UTC with ptpToUtc and the currentUtcOffset the grandmaster announces. The tool also reads the same count with the offset ignored, checks the offset against the leap-second table with taiMinusUtc, and writes an instant back with utcToPtp.
Scenarios
Section titled “Scenarios”- A PTP Stamp 37 Seconds Ahead: An ingest job stores a lidar’s PTP seconds as Unix time, and every frame sits 37 seconds ahead of the camera’s.
Mistakes
Section titled “Mistakes”- IoT: Common mistakes with PTP timestamps — reading them as Unix time, hard-coding 37, trusting a stale or invalid announced offset, and converting through the table instead of the announcement — in GMT’s IoT layer.
© 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.