# utcToPtp

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
utcToPtp(value: string, currentUtcOffset: number): PtpTimestamp | null
```

Converts a UTC instant to the PTP (IEEE 1588) timestamp a grandmaster announcing `currentUtcOffset` would send.

- The result is the instant's seconds since 1970-01-01T00:00:00Z plus the offset, counted as TAI from 1970-01-01T00:00:00 TAI. It is the inverse of `ptpToUtc` for the same offset.
- `currentUtcOffset` is TAI − UTC as announced. It is required, has no default, and must be an integer from −32 768 to 32 767. The same `ptpTimescale` and `currentUtcOffsetValid` preconditions as `ptpToUtc` apply: call it only when the grandmaster announces both as true.
- Accepts `Z` or a numeric offset (`2024-01-01T02:00:00+02:00`). An offset-less string, a zone or calendar annotation, and a second of `60` return `null`. With one offset for the whole call, an inserted second has no reading of its own.
- `seconds` comes back as a `bigint`, and every nanosecond written in the input is kept.
- Returns `null` for an instant before 1970-01-01T00:00:00Z, which `ptpToUtc` would refuse, and for a result below 0 seconds. It never throws.

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `value` | `string` | ISO 8601 instant string with `Z` or a numeric offset |
| `currentUtcOffset` | `number` | TAI − UTC in seconds, as announced: an integer from -32768 to 32767 |

## Returns

the `{ seconds, nanoseconds }` record, or null on invalid input

## Related types

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

## Examples

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

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

## Source

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