diff --git a/docs/api.md b/docs/api.md index 83471bb..6657028 100644 --- a/docs/api.md +++ b/docs/api.md @@ -4,12 +4,17 @@ This document describes the HTTP API for the NTP Timeturner application. ## Endpoints -### Status +### 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:** ```json { @@ -25,11 +30,23 @@ This document describes the HTTP API for the NTP Timeturner application. "lock_ratio": 99.5, "ntp_active": true, "interfaces": ["192.168.1.100"], - "hardware_offset_ms": 0 + "hardware_offset_ms": 20 } ``` -### Sync +- **`GET /api/logs`** + + Retrieves the last 100 log entries from the application. + + **Example Response:** + ```json + [ + "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`** @@ -37,7 +54,7 @@ This document describes the HTTP API for the NTP Timeturner application. **Request Body:** None - **Success Response:** + **Success Response (200 OK):** ```json { "status": "success", @@ -45,13 +62,14 @@ This document describes the HTTP API for the NTP Timeturner application. } ``` - **Error Responses:** + **Error Response (400 Bad Request):** ```json { "status": "error", "message": "No LTC timecode available to sync to." } ``` + **Error Response (500 Internal Server Error):** ```json { "status": "error", @@ -59,6 +77,32 @@ This document describes the HTTP API for the NTP Timeturner application. } ``` +- **`POST /api/nudge_clock`** + + Nudges the system clock by a specified number of microseconds. This requires `sudo` privileges to run `adjtimex`. + + **Example Request:** + ```json + { + "microseconds": -2000 + } + ``` + **Success Response (200 OK):** + ```json + { + "status": "success", + "message": "Clock nudge command issued." + } + ``` + **Error Response (500 Internal Server Error):** + ```json + { + "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. @@ -70,7 +114,7 @@ This document describes the HTTP API for the NTP Timeturner application. } ``` - **Success Response:** + **Success Response (200 OK):** ```json { "status": "success", @@ -78,7 +122,7 @@ This document describes the HTTP API for the NTP Timeturner application. } ``` - **Error Response:** + **Error Response (500 Internal Server Error):** ```json { "status": "error", @@ -90,29 +134,63 @@ This document describes the HTTP API for the NTP Timeturner application. - **`GET /api/config`** - Retrieves the current application configuration. + Retrieves the current application configuration from `config.yml`. - **Example Response:** + **Example Response (200 OK):** ```json { - "hardware_offset_ms": 0 + "hardwareOffsetMs": 20, + "timeturnerOffset": { + "hours": 0, + "minutes": 0, + "seconds": 0, + "frames": 0, + "milliseconds": 0 + }, + "defaultNudgeMs": 2, + "autoSyncEnabled": false } ``` - **`POST /api/config`** - Updates the `hardware_offset_ms` configuration. The new value is persisted to `config.json` and reloaded by the application automatically. + Updates the application configuration. The new configuration is persisted to `config.yml` and takes effect immediately. **Example Request:** ```json { - "hardware_offset_ms": 10 + "hardwareOffsetMs": 55, + "timeturnerOffset": { + "hours": 1, + "minutes": 2, + "seconds": 3, + "frames": 4, + "milliseconds": 5 + }, + "defaultNudgeMs": 2, + "autoSyncEnabled": true } ``` - **Success Response:** + **Success Response (200 OK):** (Returns the updated configuration) ```json { - "hardware_offset_ms": 10 + "hardwareOffsetMs": 55, + "timeturnerOffset": { + "hours": 1, + "minutes": 2, + "seconds": 3, + "frames": 4, + "milliseconds": 5 + }, + "defaultNudgeMs": 2, + "autoSyncEnabled": true + } + ``` + **Error Response (500 Internal Server Error):** + ```json + { + "status": "error", + "message": "Failed to write config.yml" } ```