Урок 31. Архитектура времени и синхронизация устройств: monotonic clock, UTC, NTP, PPS и оценка drift

monotonic time:
  сколько времени прошло внутри текущего запуска
UTC / wall clock:
  календарное время: дата, часы, минуты, секунды
hardware capture time:
  точный момент внешнего фронта относительно таймера
local civil time:
  UTC с часовым поясом и правилами перехода времени

SNTP/NTP synchronization
instant step и smooth adjustment
PPS
clock offset
clock drift
holdover
timestamp quality
wraparound
синхронизация ESP32, STM32, камеры и HIL-стенда

phase=GREEN
mono_us=128493820
utc=2026-07-18T06:42:31.438217Z
time_quality=SYNCED
sequence=817

monotonic:
  timeout AT-команды;
  reconnect backoff;
  ожидание регистрации;
  watchdog modem_task;
  RTT запроса.
UTC:
  timestamp телеметрии;
  время SMS;
  TLS certificate validation;
  журнал ошибок;
  сопоставление событий на сервере.

frame_sync_capture_ticks
frame_sequence
mono_us
exposure_mode
IR pulse duration
optional UTC

DUT local monotonic time
Raspberry Pi monotonic time
UTC Raspberry Pi
UTC DUT

- никогда не идти назад;
- увеличиваться с постоянной шкалой;
- не зависеть от NTP;
- не зависеть от timezone;
- использоваться для всех интервалов.

uint64_t started_us;
uint64_t timeout_us;
uint64_t last_progress_us;
uint64_t debounce_started_us;
if ((now_us - started_us) >= timeout_us) {
    timeout();
}

duration / timeout / debounce / watchdog:
  monotonic
calendar / telemetry / logs:
  UTC

GPIO edge
→ queue
→ phase task
→ MQTT task
→ timestamp добавлен при publish

GPIO edge:
  hardware capture timestamp
phase confirmed:
  monotonic timestamp подтверждения
MQTT publish:
  передаёт уже существующий timestamp

typedef struct {
    uint64_t observed_mono_us;
    uint64_t confirmed_mono_us;
} phase_timing_t;

typedef enum {
    TIME_QUALITY_UNSYNCED = 0,
    TIME_QUALITY_ESTIMATED,
    TIME_QUALITY_SYNCED,
    TIME_QUALITY_HOLDOVER,
    TIME_QUALITY_INVALID,
} time_quality_t;
typedef struct {
    uint64_t mono_us;
    int64_t utc_us;
    bool utc_valid;
    time_quality_t quality;
    uint32_t sync_generation;
    uint32_t boot_id;
} event_timestamp_t;

mono_us:
  основной timestamp и порядок событий
utc_us:
  привязка к UTC, если она известна
quality:
  насколько UTC заслуживает доверия
sync_generation:
  какая синхронизация использована
boot_id:
  отличает одинаковые mono_us после reboot

UNSYNCED:
  устройство только загрузилось, NTP/RTC ещё нет.
ESTIMATED:
  время восстановлено из RTC или сохранённого значения.
SYNCED:
  получен свежий NTP/SNTP/GNSS-источник.
HOLDOVER:
  источник потерян, но устройство продолжает считать время локальным генератором.
INVALID:
  время явно неверно или противоречит другим источникам.

typedef struct {
    uint64_t anchor_mono_us;
    int64_t anchor_utc_us;
    int32_t rate_ppb;
    uint32_t generation;
    time_quality_t quality;
    bool valid;
} time_anchor_t;

utc_us = anchor_utc_us + (mono_us - anchor_mono_us)

delta_us = mono_us - anchor_mono_us
correction_us = delta_us × rate_ppb / 1 000 000 000
utc_us = anchor_utc_us + delta_us + correction_us

+20 000 ppb = +20 ppm
-10 000 ppb = -10 ppm

20 микросекунд ошибки за секунду
1.2 миллисекунды за минуту
72 миллисекунды за час
1.728 секунды за сутки

первый sync после загрузки:
  step, если UTC ещё не использовался
небольшая последующая ошибка:
  smooth
очень большая ошибка:
  fault event + controlled step

PPS pin
→ timer Input Capture
→ capture_ticks
→ PPS event
→ time discipline task

1. Использовать UTC для timeout.
2. Добавлять timestamp при MQTT publish.
3. Считать любое calendar time синхронизированным.
4. Не хранить boot_id.
5. Считать PPS полноценным UTC.
6. Резко исправлять monotonic clock.
7. Игнорировать drift в holdover.
8. Смешивать ms, us, ticks и RTOS ticks.
9. Не учитывать wraparound.
10. Применять timezone внутри протокола.
11. Считать NTP доказательством микросекундной точности.

# Time architecture policy
1. All timeouts use monotonic time.
2. UTC is never used for duration measurement.
3. Hardware events are timestamped at their source.
4. Every event contains boot_id and sequence.
5. UTC timestamps include time quality.
6. SNTP corrections never change monotonic time.
7. After loss of synchronization, state becomes HOLDOVER.
8. Local timezone is applied only for display.
9. Units are encoded in variable and field names.
10. Wraparound behavior is covered by tests.

typedef enum {
    TIME_QUALITY_UNSYNCED = 0,
    TIME_QUALITY_ESTIMATED,
    TIME_QUALITY_SYNCED,
    TIME_QUALITY_HOLDOVER,
    TIME_QUALITY_INVALID,
} time_quality_t;
typedef struct {
    uint64_t mono_us;
    int64_t utc_us;
    uint32_t boot_id;
    uint32_t sync_generation;
    time_quality_t quality;
    bool utc_valid;
} event_timestamp_t;
void time_service_init(uint32_t boot_id);
uint64_t time_service_mono_us(void);
void time_service_apply_sync(uint64_t mono_us,
                             int64_t utc_us,
                             time_quality_t quality);
event_timestamp_t time_service_timestamp(void);
event_timestamp_t time_service_from_mono(uint64_t mono_us);
void time_service_mark_holdover(void);

typedef struct {
    uint32_t sequence;
    phase_t phase;
    uint8_t mask;
    event_timestamp_t observed;
    event_timestamp_t confirmed;
} phase_event_t;

time status

time:
quality=SYNCED
boot_id=42
sync_generation=7
mono_us=1834291203
utc=2026-07-18T06:42:31.438217Z
last_sync_age=1842s
offset_last=-1240us
drift_estimate=+18.4ppm
uncertainty=4200us
source=SNTP
smooth_sync=yes

hardware event
→ hardware capture / monotonic timestamp
→ event sequence + boot_id
→ time_service
→ optional UTC mapping + quality
→ queue / MQTT / CAN / log