# ptpToUtc

Industry: IoT

:::caution[Unreleased]
Not in `@northguild/gmt` 1.21.0 on npm yet. It is on `main` and ships in the next release.
:::

## Signature

```ts
ptpToUtc(timestamp: PtpTimestamp | { seconds: number; nanoseconds: number; }, currentUtcOffset: number): string
```

Converts 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⁻⁹ − currentUtcOffset` seconds after 1970-01-01T00:00:00Z.
- `currentUtcOffset` is TAI − UTC, as the grandmaster announces it in its time properties (RFC 8575 section 3 defines the `current-utc-offset` leaf and its `int16` type only; that the Announce message carries it is IEEE 1588, not reached). It is required and has no default. Passing `0` gives 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 `ptpTimescale` true and `currentUtcOffsetValid` true. 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. When `timeTraceable` is 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 `currentUtcOffset` with `taiMinusUtc(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.
- `seconds` can be a `bigint` or a safe-integer `number`, from 0 to 2^48 − 1. `nanoseconds` must be an integer `number` from 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

| 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

the UTC instant string, or "" on invalid input

## Related types

- [`PtpTimestamp`](/gmt/reference/types/PtpTimestamp/)

## Examples

```ts
import { ptpToUtc } from "@northguild/gmt/iot/convert";

ptpToUtc({ seconds: 1704067237n, nanoseconds: 0 }, 37) // "2024-01-01T00:00:00Z"
```

## Source

[iot/convert/ptpToUtc.ts](https://github.com/northguild/gmt/blob/main/packages/gmt/src/iot/convert/ptpToUtc.ts)
