interface added and web ui created
This commit is contained in:
Martino Ferrari
@@ -1,61 +1,281 @@
|
||||
# API Documentation
|
||||
|
||||
## 1. TCP Control Interface (Port 8080)
|
||||
|
||||
### 1.1 `TREE`
|
||||
Retrieves the full object hierarchy.
|
||||
- **Request:** `TREE
|
||||
`
|
||||
- **Response:** `JSON_OBJECT
|
||||
OK TREE
|
||||
`
|
||||
|
||||
### 1.2 `DISCOVER`
|
||||
Lists all registrable signals and their metadata.
|
||||
- **Request:** `DISCOVER
|
||||
`
|
||||
- **Response:** `{"Signals": [...]}
|
||||
OK DISCOVER
|
||||
`
|
||||
|
||||
### 1.3 `TRACE <path> <state>`
|
||||
Enables/disables telemetry for a signal.
|
||||
- **Example:** `TRACE App.Data.Timer.Counter 1
|
||||
`
|
||||
- **Response:** `OK TRACE <match_count>
|
||||
`
|
||||
|
||||
### 1.4 `FORCE <path> <value>`
|
||||
Overrides a signal value in memory.
|
||||
- **Example:** `FORCE App.Data.DDB.Signal 123.4
|
||||
`
|
||||
- **Response:** `OK FORCE <match_count>
|
||||
`
|
||||
|
||||
### 1.5 `PAUSE` / `RESUME`
|
||||
Controls global execution state via the Scheduler.
|
||||
- **Request:** `PAUSE
|
||||
`
|
||||
- **Response:** `OK
|
||||
`
|
||||
This document covers both transport implementations. The command text protocol is identical
|
||||
for both; only the carrier differs.
|
||||
|
||||
---
|
||||
|
||||
## 2. UDP Telemetry Format (Port 8081)
|
||||
## 1. DebugService — TCP Command Interface (default port 8080)
|
||||
|
||||
Telemetry packets are Little-Endian and use `#pragma pack(1)`.
|
||||
Commands are newline-terminated (`\n`) UTF-8 text strings sent over a persistent TCP
|
||||
connection. One client is served at a time; concurrent connections queue.
|
||||
|
||||
### 2.1 TraceHeader (20 Bytes)
|
||||
| Offset | Type | Name | Description |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| 0 | uint32 | magic | Always `0xDA7A57AD` |
|
||||
| 4 | uint32 | seq | Incremental sequence number |
|
||||
| 8 | uint64 | timestamp | High-resolution timestamp |
|
||||
| 16 | uint32 | count | Number of samples in payload |
|
||||
A client sending more than **100 commands per second** is disconnected (rate limit).
|
||||
A client that sends no data for **30 seconds** is disconnected (idle timeout).
|
||||
|
||||
### 2.2 Sample Entry
|
||||
| Offset | Type | Name | Description |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| 0 | uint32 | id | Internal Signal ID (from `DISCOVER`) |
|
||||
| 4 | uint32 | size | Data size in bytes |
|
||||
| 8 | Bytes | data | Raw signal memory |
|
||||
### 1.1 `DISCOVER`
|
||||
List all registered signals with full metadata.
|
||||
|
||||
- **Request:** `DISCOVER\n`
|
||||
- **Response:**
|
||||
```
|
||||
{"Signals":[{"id":<n>,"name":"…","alias":"…","type":"…","elements":<n>},...]}
|
||||
OK DISCOVER
|
||||
```
|
||||
|
||||
### 1.2 `TREE`
|
||||
Return the full live `ObjectRegistryDatabase` hierarchy as JSON.
|
||||
|
||||
- **Request:** `TREE\n`
|
||||
- **Response:**
|
||||
```json
|
||||
{"name":"Root","children":[…]}
|
||||
OK TREE
|
||||
```
|
||||
|
||||
### 1.3 `INFO <path>`
|
||||
Return metadata for a specific ORD node. Response is enriched with config fields
|
||||
(Frequency, Units, PVNames, …) when a full config has been provided via `SetFullConfig`.
|
||||
|
||||
- **Request:** `INFO App.Functions.GAM1\n`
|
||||
- **Response:**
|
||||
```
|
||||
{"path":"…","class":"…","signals":[…],"config":{…}}
|
||||
OK INFO
|
||||
```
|
||||
|
||||
### 1.4 `LS [path]`
|
||||
List the immediate children of an ORD node.
|
||||
|
||||
- **Request:** `LS App.Data\n`
|
||||
- **Response:**
|
||||
```
|
||||
{"nodes":["Timer","DDB"]}
|
||||
OK LS
|
||||
```
|
||||
|
||||
### 1.5 `TRACE <name> <0|1> [decimation]`
|
||||
Enable or disable high-speed tracing for a signal. Optional `decimation` controls
|
||||
how many RT cycles are skipped between samples (default 1 = every cycle).
|
||||
|
||||
- **Request:** `TRACE App.Data.DDB.Counter 1\n`
|
||||
- **Request:** `TRACE App.Data.DDB.Counter 1 10\n` *(every 10th sample)*
|
||||
- **Response:** `OK TRACE <match_count>\n`
|
||||
|
||||
### 1.6 `FORCE <name> <value>`
|
||||
Inject a persistent value into a signal's memory location. The RT broker will copy
|
||||
the forced value on every cycle until `UNFORCE` is called.
|
||||
|
||||
- **Request:** `FORCE App.Data.DDB.Counter 9999\n`
|
||||
- **Response:** `OK FORCE <match_count>\n`
|
||||
|
||||
### 1.7 `UNFORCE <name>`
|
||||
Remove a forced value; the signal resumes its normal data-flow value.
|
||||
|
||||
- **Request:** `UNFORCE App.Data.DDB.Counter\n`
|
||||
- **Response:** `OK UNFORCE <match_count>\n`
|
||||
|
||||
### 1.8 `BREAK <name> <op> <threshold>`
|
||||
Set a conditional breakpoint on a signal. When the condition fires, the application
|
||||
pauses and execution stepping becomes available. Supported operators:
|
||||
|
||||
| `op` string | Condition |
|
||||
|---|---|
|
||||
| `>` | signal > threshold |
|
||||
| `<` | signal < threshold |
|
||||
| `==` | signal == threshold |
|
||||
| `>=` | signal >= threshold |
|
||||
| `<=` | signal <= threshold |
|
||||
| `!=` | signal != threshold |
|
||||
| `OFF` | disable break (same as `BREAK <name> OFF`) |
|
||||
|
||||
- **Request:** `BREAK App.Data.DDB.Counter > 1000\n`
|
||||
- **Response:** `OK BREAK <match_count>\n`
|
||||
|
||||
### 1.9 `BREAK <name> OFF`
|
||||
Clear the breakpoint on a signal (equivalent to `BREAK <name> OFF 0`).
|
||||
|
||||
- **Request:** `BREAK App.Data.DDB.Counter OFF\n`
|
||||
- **Response:** `OK BREAK <match_count>\n`
|
||||
|
||||
### 1.10 `PAUSE`
|
||||
Halt all patched RT threads at the start of their next Execute cycle.
|
||||
|
||||
- **Request:** `PAUSE\n`
|
||||
- **Response:** `OK\n`
|
||||
|
||||
### 1.11 `RESUME`
|
||||
Release paused RT threads.
|
||||
|
||||
- **Request:** `RESUME\n`
|
||||
- **Response:** `OK\n`
|
||||
|
||||
### 1.12 `STEP <n> [thread]`
|
||||
Resume execution for exactly `n` RT output-broker cycles then pause again.
|
||||
Optional `thread` (OS thread name) restricts counting to one thread.
|
||||
|
||||
- **Request:** `STEP 5\n`
|
||||
- **Request:** `STEP 1 RealTimeThread1\n`
|
||||
- **Response:** `OK STEP\n`
|
||||
|
||||
### 1.13 `STEP_STATUS`
|
||||
Query current pause and stepping state.
|
||||
|
||||
- **Request:** `STEP_STATUS\n`
|
||||
- **Response:**
|
||||
```json
|
||||
{"paused":true,"gam":"App.Functions.GAM1","remaining":3}
|
||||
OK STEP_STATUS
|
||||
```
|
||||
|
||||
### 1.14 `VALUE <name>`
|
||||
Read the current raw value of a signal from its memory address. Arrays are
|
||||
capped at 256 elements; larger signals include `"truncated":true`.
|
||||
|
||||
- **Request:** `VALUE App.Data.DDB.Counter\n`
|
||||
- **Response:**
|
||||
```json
|
||||
{"name":"App.Data.DDB.Counter","type":"uint32","elements":1,"values":[42]}
|
||||
OK VALUE
|
||||
```
|
||||
|
||||
### 1.15 `MONITOR SIGNAL <name> <periodMs>`
|
||||
Register a signal for slow-rate polling. The service reads the signal directly
|
||||
from its `DataSourceI` and sends the value at the specified period.
|
||||
|
||||
- **Request:** `MONITOR SIGNAL App.Data.DDB.Counter 500\n`
|
||||
- **Response:** `OK MONITOR <id>\n`
|
||||
|
||||
On `DebugService`, monitored values are pushed over UDP with signal ID = internal monitor ID.
|
||||
On `WebDebugService`, they are broadcast as `{"type":"monitor",…}` SSE events.
|
||||
|
||||
### 1.16 `UNMONITOR SIGNAL <name>`
|
||||
Stop polling a monitored signal.
|
||||
|
||||
- **Request:** `UNMONITOR SIGNAL App.Data.DDB.Counter\n`
|
||||
- **Response:** `OK UNMONITOR\n`
|
||||
|
||||
### 1.17 `CONFIG`
|
||||
Return the full application configuration as JSON. Requires that `SetFullConfig()` was
|
||||
called after `ConfigureApplication()`.
|
||||
|
||||
- **Request:** `CONFIG\n`
|
||||
- **Response:**
|
||||
```json
|
||||
{"App":{"Class":"RealTimeApplication",…}}
|
||||
OK CONFIG
|
||||
```
|
||||
|
||||
### 1.18 `MSG <object> <function> [key=value …]`
|
||||
Send a MARTe2 `Message` to any object in the ORD.
|
||||
|
||||
- **Request:** `MSG App.Functions.GAM1 Reset\n`
|
||||
- **Request:** `MSG App.StateMachine GOTOSTATE NewState=Running\n`
|
||||
- **Response:** `OK MSG\n` or `ERROR MSG <reason>\n`
|
||||
|
||||
### 1.19 `SERVICE_INFO`
|
||||
Return metadata about the debug service itself.
|
||||
|
||||
- **Request:** `SERVICE_INFO\n`
|
||||
- **Response:**
|
||||
```json
|
||||
{"transport":"TCP","controlPort":8080,"udpPort":8081,"logPort":8082}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. WebDebugService — HTTP Interface (default port 8090)
|
||||
|
||||
### 2.1 `GET /`
|
||||
Returns the embedded single-page application. Open in any web browser.
|
||||
|
||||
### 2.2 `POST /api/command`
|
||||
Execute any command from Section 1. The request body is the command text
|
||||
(without a trailing newline). CORS headers are included.
|
||||
|
||||
- **Request headers:** `Content-Type: text/plain`
|
||||
- **Request body:** e.g. `TRACE App.Data.DDB.Counter 1`
|
||||
- **Response:** Plain text; same content as the TCP response.
|
||||
|
||||
### 2.3 `GET /api/events`
|
||||
Long-lived Server-Sent Events stream. Up to 8 simultaneous clients.
|
||||
|
||||
Each event is formatted as:
|
||||
```
|
||||
event: message
|
||||
data: <json>
|
||||
|
||||
```
|
||||
(blank line terminates each event per SSE spec)
|
||||
|
||||
#### SSE event types
|
||||
|
||||
| `type` field | Additional fields | Description |
|
||||
|---|---|---|
|
||||
| `trace` | `name`, `ts` (ns), `value` (f64) | One traced signal sample |
|
||||
| `monitor` | `name`, `ts` (ns), `value` (f64) | One slow-rate monitor sample |
|
||||
| `log` | `level`, `msg` | Forwarded `REPORT_ERROR` log entry |
|
||||
| `status` | `paused` (bool), `gam`, `remaining` | Pause/step state heartbeat (every 500 ms) |
|
||||
| `discover` | `signals` (array) | Full signal list (sent on SSE connect) |
|
||||
| `tree` | `tree` (object) | Full ORD tree (sent on SSE connect) |
|
||||
|
||||
Example trace event:
|
||||
```
|
||||
event: message
|
||||
data: {"type":"trace","name":"App.Data.DDB.Counter","ts":1234567890,"value":42.0}
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. UDP Telemetry Format (DebugService, default port 8081)
|
||||
|
||||
Packets are little-endian and packed (`#pragma pack(1)`).
|
||||
|
||||
### 3.1 `TraceHeader` (20 bytes)
|
||||
|
||||
| Offset | Type | Field | Description |
|
||||
|---|---|---|---|
|
||||
| 0 | uint32 | `magic` | Always `0xDA7A57AD` |
|
||||
| 4 | uint32 | `seq` | Monotonically incrementing sequence number |
|
||||
| 8 | uint64 | `timestamp` | High-resolution hardware timestamp |
|
||||
| 16 | uint32 | `count` | Number of samples in this datagram |
|
||||
|
||||
### 3.2 Sample Entry (per signal)
|
||||
|
||||
| Offset | Type | Field | Description |
|
||||
|---|---|---|---|
|
||||
| 0 | uint32 | `id` | Signal ID from `DISCOVER` |
|
||||
| 4 | uint64 | `timestamp` | Per-sample RT timestamp |
|
||||
| 12 | uint32 | `size` | Payload size in bytes |
|
||||
| 16 | bytes | `data` | Raw signal memory (`size` bytes) |
|
||||
|
||||
Multiple samples may be packed into one datagram up to `STREAMER_MTU = 1400` bytes.
|
||||
A new datagram is started when the next sample would overflow the MTU.
|
||||
|
||||
---
|
||||
|
||||
## 4. Log Forwarding (DebugService, default port 8082)
|
||||
|
||||
The `TcpLogger` component (`Source/Components/Interfaces/TCPLogger/`) connects to the
|
||||
MARTe2 global `LoggerI` and forwards every `REPORT_ERROR` call as a text line:
|
||||
|
||||
```
|
||||
<level>|<object>|<function>|<message>\n
|
||||
```
|
||||
|
||||
Up to 8 simultaneous log clients are supported. If no client is connected, log events
|
||||
are silently discarded.
|
||||
|
||||
To enable:
|
||||
|
||||
```text
|
||||
+Logger = {
|
||||
Class = TcpLogger
|
||||
Port = 8082
|
||||
MaxClients = 8
|
||||
}
|
||||
```
|
||||
|
||||
On `WebDebugService`, logs are forwarded to SSE clients as `{"type":"log","level":"…","msg":"…"}`
|
||||
events — no separate `TcpLogger` instance is required.
|
||||
|
||||
Reference in New Issue
Block a user