mirror of
https://github.com/cjfranko/NTP-Timeturner.git
synced 2025-11-08 10:22:02 +00:00
docs: Update API docs with new endpoints and response details
Co-authored-by: aider (gemini/gemini-2.5-pro) <aider@aider.chat>
This commit is contained in:
Chris Frankland-Wright
parent
5f35139f3b
commit
32712d1f3c
1 changed files with 92 additions and 14 deletions
106
docs/api.md
106
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"
|
||||
}
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue