chaos/NTP-Timeturner
1
0
Fork 0
mirror of https://github.com/cjfranko/NTP-Timeturner.git synced 2025-11-08 10:22:02 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: Update API docs with new endpoints and response details

Browse source 
Co-authored-by: aider (gemini/gemini-2.5-pro) <aider@aider.chat>
This commit is contained in:
Chris Frankland-Wright 2025-08-07 21:59:32 +01:00
parent 5f35139f3b
commit 32712d1f3c
1 changed files with 92 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

106
docs/api.md
View file

@ -4,12 +4,17 @@ This document describes the HTTP API for the NTP Timeturner application.
## Endpoints ## Endpoints
### Status ### Status and Logs
- **`GET /api/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`). 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:** **Example Response:**
```json ```json
{ {
@ -25,11 +30,23 @@ This document describes the HTTP API for the NTP Timeturner application.
"lock_ratio": 99.5, "lock_ratio": 99.5,
"ntp_active": true, "ntp_active": true,
"interfaces": ["192.168.1.100"], "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`** - **`POST /api/sync`**
@ -37,7 +54,7 @@ This document describes the HTTP API for the NTP Timeturner application.
**Request Body:** None **Request Body:** None
**Success Response:** **Success Response (200 OK):**
```json ```json
{ {
"status": "success", "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 ```json
{ {
"status": "error", "status": "error",
"message": "No LTC timecode available to sync to." "message": "No LTC timecode available to sync to."
} }
``` ```
**Error Response (500 Internal Server Error):**
```json ```json
{ {
"status": "error", "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`** - **`POST /api/set_date`**
Sets the system date. This is useful as LTC does not contain date information. Requires `sudo` privileges. 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 ```json
{ {
"status": "success", "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 ```json
{ {
"status": "error", "status": "error",
@ -90,29 +134,63 @@ This document describes the HTTP API for the NTP Timeturner application.
- **`GET /api/config`** - **`GET /api/config`**
Retrieves the current application configuration. Retrieves the current application configuration from `config.yml`.
**Example Response:** **Example Response (200 OK):**
```json ```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`** - **`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:** **Example Request:**
```json ```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 ```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"
} }
``` ```