NTP-Timeturner/docs/api.md

NTP Timeturner API

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

Endpoints

Status and Logs

• 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).

  Possible values for status fields:

  • ltc_status: "LOCK", "FREE", or "(waiting)"
  • sync_status: "IN SYNC", "CLOCK AHEAD", "CLOCK BEHIND", "TIMETURNING"
  • jitter_status: "GOOD", "AVERAGE", "BAD"

  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": 20
  }
  

• GET /api/logs

  Retrieves the last 100 log entries from the application.

  Example Response:

  [
    "2025-08-07 10:00:00 [INFO] Starting TimeTurner daemon...",
    "2025-08-07 10:00:01 [INFO] Found serial port: /dev/ttyACM0"
  ]
  

System Clock Control

• 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 (200 OK):

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

  Error Response (400 Bad Request):

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

  Error Response (500 Internal Server Error):

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

• POST /api/nudge_clock

  Nudges the system clock by a specified number of microseconds. This requires sudo privileges to run adjtimex.

  Example Request:

  {
    "microseconds": -2000
  }
  

  Success Response (200 OK):

  {
    "status": "success",
    "message": "Clock nudge command issued."
  }
  

  Error Response (500 Internal Server Error):

  {
    "status": "error",
    "message": "Clock nudge 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 (200 OK):

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

  Error Response (500 Internal Server Error):

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

Configuration

• GET /api/config

  Retrieves the current application configuration from config.yml.

  Example Response (200 OK):

  {
    "hardwareOffsetMs": 20,
    "timeturnerOffset": {
      "hours": 0,
      "minutes": 0,
      "seconds": 0,
      "frames": 0,
      "milliseconds": 0
    },
    "defaultNudgeMs": 2,
    "autoSyncEnabled": false
  }
  

• POST /api/config

  Updates the application configuration. The new configuration is persisted to config.yml and takes effect immediately.

  Example Request:

  {
    "hardwareOffsetMs": 55,
    "timeturnerOffset": {
      "hours": 1,
      "minutes": 2,
      "seconds": 3,
      "frames": 4,
      "milliseconds": 5
    },
    "defaultNudgeMs": 2,
    "autoSyncEnabled": true
  }
  

  Success Response (200 OK): (Returns the updated configuration)

  {
    "hardwareOffsetMs": 55,
    "timeturnerOffset": {
      "hours": 1,
      "minutes": 2,
      "seconds": 3,
      "frames": 4,
      "milliseconds": 5
    },
    "defaultNudgeMs": 2,
    "autoSyncEnabled": true
  }
  

  Error Response (500 Internal Server Error):

  {
    "status": "error",
    "message": "Failed to write config.yml"
  }