# IoT

Industry: 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

- **A sensor's time reads ahead of every other clock.** [`ptpToUtc`](/gmt/reference/iot/convert/ptpToUtc/) subtracts 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](/gmt/guides/industries/iot-ptp-time/), [scenario](/gmt/scenarios/a-ptp-stamp-37-seconds-ahead/), [tool](/gmt/tools/ptp-clock-converter/).
- **A grandmaster announces the wrong offset.** [`taiMinusUtc`](/gmt/reference/timescale/calculate/taiMinusUtc/) gives 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](/gmt/tools/ptp-clock-converter/), [mistakes](/gmt/mistakes/iot/).
- **A UTC time put back on the wire loses the offset.** [`utcToPtp`](/gmt/reference/iot/convert/utcToPtp/) adds the announced offset back and returns the seconds as a bigint, so a round trip gives the same timestamp. See [guide](/gmt/guides/industries/iot-ptp-time/), [tool](/gmt/tools/ptp-clock-converter/).
- **A malformed timestamp converts without a complaint.** [`isValidPtpTimestamp`](/gmt/reference/iot/validate/isValidPtpTimestamp/) checks the seconds and nanoseconds against the ranges the wire format allows. See [mistakes](/gmt/mistakes/iot/).
- **Nanoseconds are lost on the way to milliseconds.** [`ptpToUtc`](/gmt/reference/iot/convert/ptpToUtc/) writes every nanosecond the timestamp carries, and [`toNanoseconds`](/gmt/reference/precision/convert/toNanoseconds/) reads the instant back as a whole count. See [guide](/gmt/guides/industries/iot-ptp-time/).

Start with the guide: [IoT: PTP Time](/gmt/guides/industries/iot-ptp-time/).

## Its own functions

### [`iot`](/gmt/reference/iot/)

**[convert](/gmt/reference/iot/convert/)**

- [`ptpToUtc`](/gmt/reference/iot/convert/ptpToUtc/): Converts a PTP (IEEE 1588) timestamp to a UTC instant string ending in `Z`.
- [`utcToPtp`](/gmt/reference/iot/convert/utcToPtp/): Converts a UTC instant to the PTP (IEEE 1588) timestamp a grandmaster announcing `currentUtcOffset` would send.

**[validate](/gmt/reference/iot/validate/)**

- [`isValidPtpTimestamp`](/gmt/reference/iot/validate/isValidPtpTimestamp/): Return true when `value` is a PTP timestamp record that `ptpToUtc` reads.

## Functions it draws on

### [`timescale`](/gmt/reference/timescale/)

**[calculate](/gmt/reference/timescale/calculate/)**

- [`leapSecondsBetween`](/gmt/reference/timescale/calculate/leapSecondsBetween/): Return how many leap seconds start between two UTC instants, signed.
- [`nextLeapSecond`](/gmt/reference/timescale/calculate/nextLeapSecond/): Return the first leap second after a UTC instant, as its UTC label `…T23:59:60Z`.
- [`taiMinusUtc`](/gmt/reference/timescale/calculate/taiMinusUtc/): Return TAI − UTC, in whole seconds, at a UTC instant.
- [`tcgMinusTt`](/gmt/reference/timescale/calculate/tcgMinusTt/): Return TCG − TT, in seconds, at a UTC instant.

**[convert](/gmt/reference/timescale/convert/)**

- [`fromJ2000Seconds`](/gmt/reference/timescale/convert/fromJ2000Seconds/): Convert seconds since J2000.0 on a time scale to a UTC instant string.
- [`fromJulianDate`](/gmt/reference/timescale/convert/fromJulianDate/): Convert a single Julian Date on a time scale to a UTC instant string.
- [`fromJulianDateParts`](/gmt/reference/timescale/convert/fromJulianDateParts/): Convert a two-part Julian Date on a time scale to a UTC instant string.
- [`fromModifiedJulianDate`](/gmt/reference/timescale/convert/fromModifiedJulianDate/): Convert a Modified Julian Date on a time scale to a UTC instant string.
- [`fromTAI`](/gmt/reference/timescale/convert/fromTAI/): Convert a TAI time-scale string to a UTC instant string.
- [`fromTai64n`](/gmt/reference/timescale/convert/fromTai64n/): Convert a TAI64, TAI64N or TAI64NA label in hex text to a UTC instant string.
- [`fromTCG`](/gmt/reference/timescale/convert/fromTCG/): Convert a Geocentric Coordinate Time string to a UTC instant string.
- [`fromTT`](/gmt/reference/timescale/convert/fromTT/): Convert a Terrestrial Time string to a UTC instant string.
- [`toJ2000Seconds`](/gmt/reference/timescale/convert/toJ2000Seconds/): Convert a UTC instant to seconds since J2000.0 on a time scale.
- [`toJulianDate`](/gmt/reference/timescale/convert/toJulianDate/): Convert a UTC instant to a single Julian Date on a time scale.
- [`toJulianDateParts`](/gmt/reference/timescale/convert/toJulianDateParts/): Convert a UTC instant to a two-part Julian Date `{ jd1, jd2 }` on a time scale, exact to the nanosecond.
- [`toModifiedJulianDate`](/gmt/reference/timescale/convert/toModifiedJulianDate/): Convert a UTC instant to a Modified Julian Date on a time scale.
- [`toTAI`](/gmt/reference/timescale/convert/toTAI/): Convert a UTC instant to a TAI time-scale string, `YYYY-MM-DDTHH:MM:SS[.fraction] TAI`.
- [`toTai64n`](/gmt/reference/timescale/convert/toTai64n/): Convert a UTC instant to its TAI64N label in the daemontools text form, `@` and 24 lowercase hex digits.
- [`toTCG`](/gmt/reference/timescale/convert/toTCG/): Convert a UTC instant to a Geocentric Coordinate Time string, `YYYY-MM-DDTHH:MM:SS[.fraction] TCG`.
- [`toTT`](/gmt/reference/timescale/convert/toTT/): Convert a UTC instant to a Terrestrial Time string, `YYYY-MM-DDTHH:MM:SS[.fraction] TT`.

**[format](/gmt/reference/timescale/format/)**

- [`formatCcsdsAsciiA`](/gmt/reference/timescale/format/formatCcsdsAsciiA/): Write an instant as a CCSDS ASCII Time Code A string (`YYYY-MM-DDThh:mm:ss.d…dZ`).
- [`formatCcsdsAsciiB`](/gmt/reference/timescale/format/formatCcsdsAsciiB/): Write an instant as a CCSDS ASCII Time Code B string (`YYYY-DDDThh:mm:ss.d…dZ`, day of year).

**[parse](/gmt/reference/timescale/parse/)**

- [`parseCcsdsAsciiA`](/gmt/reference/timescale/parse/parseCcsdsAsciiA/): Read a CCSDS ASCII Time Code A (`YYYY-MM-DDThh:mm:ss.d…dZ`) as an ISO 8601 UTC instant string.
- [`parseCcsdsAsciiB`](/gmt/reference/timescale/parse/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.

**[validate](/gmt/reference/timescale/validate/)**

- [`isLeapSecond`](/gmt/reference/timescale/validate/isLeapSecond/): Return true when a UTC instant string is one of the 27 inserted leap seconds.

### [`precision`](/gmt/reference/precision/)

**[calculate](/gmt/reference/precision/calculate/)**

- [`truncateNanoseconds`](/gmt/reference/precision/calculate/truncateNanoseconds/): Truncate nanoseconds since the Unix epoch to the precision a store can actually hold.

**[convert](/gmt/reference/precision/convert/)**

- [`fromArrowLocalTimestamp`](/gmt/reference/precision/convert/fromArrowLocalTimestamp/): Convert the `int64` of an Apache Arrow `Timestamp` column that has no timezone to a wall-clock date-time string.
- [`fromArrowTimestamp`](/gmt/reference/precision/convert/fromArrowTimestamp/): Convert the `int64` of an Apache Arrow `Timestamp` column that has a timezone to a UTC instant string.
- [`fromDotNetTicks`](/gmt/reference/precision/convert/fromDotNetTicks/): Convert .NET `DateTime.Ticks` back to an ISO 8601 instant string.
- [`fromExcelSerial`](/gmt/reference/precision/convert/fromExcelSerial/): Convert an Excel day serial back to an ISO 8601 instant string.
- [`fromFileTime`](/gmt/reference/precision/convert/fromFileTime/): Convert a Windows `FILETIME` back to an ISO 8601 instant string.
- [`fromNanoseconds`](/gmt/reference/precision/convert/fromNanoseconds/): Convert nanoseconds since the Unix epoch back to an ISO 8601 string.
- [`fromNtpTimestamp`](/gmt/reference/precision/convert/fromNtpTimestamp/): Convert a 64-bit NTP timestamp (RFC 5905) back to an ISO 8601 instant string.
- [`fromParquetInt96`](/gmt/reference/precision/convert/fromParquetInt96/): Convert a Parquet `INT96` timestamp back to an ISO 8601 instant string.
- [`fromPgMicroseconds`](/gmt/reference/precision/convert/fromPgMicroseconds/): Convert PostgreSQL's internal `timestamptz` value back to an ISO 8601 instant string.
- [`fromProtoDuration`](/gmt/reference/precision/convert/fromProtoDuration/): Convert a protobuf `google.protobuf.Duration` record back to an ISO 8601 duration string.
- [`fromProtoTimestamp`](/gmt/reference/precision/convert/fromProtoTimestamp/): Convert a protobuf `google.protobuf.Timestamp` record back to an ISO 8601 instant string.
- [`toArrowLocalTimestamp`](/gmt/reference/precision/convert/toArrowLocalTimestamp/): Convert an ISO 8601 plain date-time to the `int64` of an Apache Arrow `Timestamp` column that has no timezone.
- [`toArrowTimestamp`](/gmt/reference/precision/convert/toArrowTimestamp/): Convert an ISO 8601 instant string to the `int64` of an Apache Arrow `Timestamp` column that has a timezone.
- [`toDotNetTicks`](/gmt/reference/precision/convert/toDotNetTicks/): Convert an ISO 8601 instant string to .NET `DateTime.Ticks`.
- [`toExcelSerial`](/gmt/reference/precision/convert/toExcelSerial/): Convert an ISO 8601 instant string to an Excel day serial.
- [`toFileTime`](/gmt/reference/precision/convert/toFileTime/): Convert an ISO 8601 instant string to a Windows `FILETIME`.
- [`toNanoseconds`](/gmt/reference/precision/convert/toNanoseconds/): Convert an ISO 8601 instant string to nanoseconds since the Unix epoch.
- [`toNtpTimestamp`](/gmt/reference/precision/convert/toNtpTimestamp/): Convert an ISO 8601 instant string to a 64-bit NTP timestamp (RFC 5905).
- [`toParquetInt96`](/gmt/reference/precision/convert/toParquetInt96/): Convert an ISO 8601 instant string to a Parquet `INT96` timestamp record.
- [`toPgMicroseconds`](/gmt/reference/precision/convert/toPgMicroseconds/): Convert an ISO 8601 instant string to PostgreSQL's internal `timestamptz` value.
- [`toProtoDuration`](/gmt/reference/precision/convert/toProtoDuration/): Convert an ISO 8601 duration string to a protobuf `google.protobuf.Duration` record.
- [`toProtoTimestamp`](/gmt/reference/precision/convert/toProtoTimestamp/): Convert an ISO 8601 instant string to a protobuf `google.protobuf.Timestamp` record.

**[format](/gmt/reference/precision/format/)**

- [`formatNanoseconds`](/gmt/reference/precision/format/formatNanoseconds/): Format nanoseconds since the Unix epoch as a decimal string, for JSON and other text transports.

**[identifiers](/gmt/reference/precision/identifiers/)**

- [`fromKsuid`](/gmt/reference/precision/identifiers/fromKsuid/): Read the instant a KSUID carries (segmentio/ksuid, `ksuid.go` and `base62.go`).
- [`fromObjectId`](/gmt/reference/precision/identifiers/fromObjectId/): Read the creation second a MongoDB ObjectId carries (mongodb/specifications `bson-objectid/objectid.md`, § Specification and § Timestamp Field).
- [`fromSnowflake`](/gmt/reference/precision/identifiers/fromSnowflake/): Read the instant a Snowflake id carries, using a layout the caller supplies.
- [`fromUlid`](/gmt/reference/precision/identifiers/fromUlid/): Read the instant a ULID carries (ulid/spec README, § Components and § Canonical String Representation).
- [`fromUuidTimestamp`](/gmt/reference/precision/identifiers/fromUuidTimestamp/): Read the instant a version 1, 6 or 7 UUID carries (RFC 9562 §5.1, §5.6, §5.7).
- [`ulidTimestampPrefix`](/gmt/reference/precision/identifiers/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`](/gmt/reference/precision/identifiers/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).

**[parse](/gmt/reference/precision/parse/)**

- [`parseNanoseconds`](/gmt/reference/precision/parse/parseNanoseconds/): Parse a decimal string produced by `formatNanoseconds` — typically one field of a JSON payload — back to nanoseconds since the Unix epoch.

**[validate](/gmt/reference/precision/validate/)**

- [`isValidInstant`](/gmt/reference/precision/validate/isValidInstant/): Validate whether a string is an ISO 8601 instant string the `precision/` namespace accepts.
- [`isValidInt64NanosecondDateTime`](/gmt/reference/precision/validate/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 an `int64`: the check to run before `toArrowLocalTimestamp(dateTime, "nanosecond")`.
- [`isValidInt64NanosecondInstant`](/gmt/reference/precision/validate/isValidInt64NanosecondInstant/): Validate whether a string is an instant whose epoch-nanosecond count fits an `int64`: the check to run before `toArrowTimestamp(isoString, "nanosecond")`.
- [`isValidNanoPattern`](/gmt/reference/precision/validate/isValidNanoPattern/): Validate whether a string is a nanosecond timestamp `parseNanoseconds` will parse.
- [`isValidNanoseconds`](/gmt/reference/precision/validate/isValidNanoseconds/): Validate whether a value is an epoch-nanosecond `bigint` the `precision/` namespace accepts.

## Guides

- [IoT: PTP Time](/gmt/guides/industries/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.

## Tools

- [PTP Clock Converter](/gmt/tools/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

- [A PTP Stamp 37 Seconds Ahead](/gmt/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

- [IoT](/gmt/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.
