# PTP Clock Converter

Industry: IoT

**Key point — Sensor and device time**

A PTP timestamp counts TAI, and UTC is the count minus the offset the grandmaster announces. Read 1704067237 seconds with an offset of 37 and you get midnight, 2024-01-01T00:00:00Z. Skip the subtraction and the same count reads 37 s later, with no error to tell you.

A Precision Time Protocol (IEEE 1588) timestamp is a count of seconds and nanoseconds from 1970-01-01T00:00:00 TAI. [`ptpToUtc`](/gmt/reference/iot/convert/ptpToUtc/) turns a record and the `currentUtcOffset` into a UTC string, and gives `""` when it cannot. [`isValidPtpTimestamp`](/gmt/reference/iot/validate/isValidPtpTimestamp/) says whether the record is in range. A second section checks the announced offset against the leap-second table with [`taiMinusUtc`](/gmt/reference/timescale/calculate/taiMinusUtc/) and draws the two on a fixed ruler, and a last section goes the other way with [`utcToPtp`](/gmt/reference/iot/convert/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](/gmt/guides/industries/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.

```ts
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](/gmt/tools/ptp-clock-converter/?w=ptpclock&wa=%7B%22preset%22%3A%22stale-36%22%7D) is 1 s out; [offset 0](/gmt/tools/ptp-clock-converter/?w=ptpclock&wa=%7B%22preset%22%3A%22announced-0%22%7D) is 37 s out; and [a clock that was never set](/gmt/tools/ptp-clock-converter/?w=ptpclock&wa=%7B%22preset%22%3A%22unset-clock%22%7D) is refused.
