NTP-Timeturner/docs/api.md

NTP Timeturner API

This document describes the HTTP API for the NTP Timeturner application.

Endpoints

Status

• GET /api/status

  Retrieves the real-time status of the LTC reader and system clock synchronization. The ltc_timecode field uses : as a separator for non-drop-frame timecode, and ; for drop-frame timecode between seconds and frames (e.g., 10:20:30;00).

  Example Response:

  {
    "ltc_status": "LOCK",
    "ltc_timecode": "10:20:30;00",
    "frame_rate": "25.00fps",
    "system_clock": "10:20:30.005",
    "system_date": "2025-07-30",
    "timecode_delta_ms": 5,
    "timecode_delta_frames": 0,
    "sync_status": "IN SYNC",
    "jitter_status": "GOOD",
    "lock_ratio": 99.5,
    "ntp_active": true,
    "interfaces": ["192.168.1.100"],
    "hardware_offset_ms": 0
  }
  

Sync

• POST /api/sync

  Triggers a manual synchronization of the system clock to the current LTC timecode. This requires the application to have sudo privileges to execute the date command.

  Request Body: None

  Success Response:

  {
    "status": "success",
    "message": "Sync command issued."
  }
  

  Error Responses:

  {
    "status": "error",
    "message": "No LTC timecode available to sync to."
  }
  

  {
    "status": "error",
    "message": "Sync command failed."
  }
  

• POST /api/set_date

  Sets the system date. This is useful as LTC does not contain date information. Requires sudo privileges.

  Example Request:

  {
    "date": "2025-07-30"
  }
  

  Success Response:

  {
    "status": "success",
    "message": "Date update command issued."
  }
  

  Error Response:

  {
    "status": "error",
    "message": "Date update command failed."
  }
  

Configuration

• GET /api/config

  Retrieves the current application configuration.

  Example Response:

  {
    "hardware_offset_ms": 0
  }
  

• POST /api/config

  Updates the hardware_offset_ms configuration. The new value is persisted to config.json and reloaded by the application automatically.

  Example Request:

  {
    "hardware_offset_ms": 10
  }
  

  Success Response:

  {
    "hardware_offset_ms": 10
  }