feat(tuner-relay): add command history tracking and related configurations

Coriou · Coriou · commit dd244b540db1 · 2026-01-12T13:30:23.000+01:00
diff --git a/cli/source/types.ts b/cli/source/types.ts
@@ -80,13 +80,34 @@ export interface TunerRelayStatus {
 	bytesReceived: number
 	lastCommand?: string
 	lastCommandAt?: string
+	lastCommandValue?: number
 	lastFrequency?: number
 	lastSampleRate?: number
 	lastGain?: number
 	lastPpm?: number
+	commandHistoryLimit?: number
+	commandStats?: TunerRelayCommandStat[]
+	commandHistory?: TunerRelayCommandHistoryEntry[]
 	lastError?: string
 }
 
+export interface TunerRelayCommandStat {
+	id: number
+	name: string
+	count: number
+	lastValue: number
+	lastSeenAt: string
+}
+
+export interface TunerRelayCommandHistoryEntry {
+	id: number
+	name: string
+	value: number
+	at: string
+	clientId?: string
+	clientRemote?: string
+}
+
 // ============================================================================
 // Backpressure Types
 // ============================================================================
diff --git a/config/default.yaml b/config/default.yaml
@@ -201,6 +201,7 @@ audio:
 #   sourceId      - Source to expose (default: first configured source)
 #   controlPolicy - "exclusive" (first client controls) or "shared"
 #   maxClients    - Optional cap on number of connected clients
+#   commandHistoryLimit - Number of command entries to retain (0 disables)
 #   note         - Relay streams the primary source (first in `sources`)
 #
 # Example:
@@ -211,11 +212,13 @@ audio:
 #   sourceId: "rtl-pi"
 #   controlPolicy: "exclusive"
 #   maxClients: 2
+#   commandHistoryLimit: 200
 
 tunerRelay:
   enabled: false
   host: "0.0.0.0"
   port: 1234
+  commandHistoryLimit: 200
 
 # -----------------------------------------------------------------------------
 # API Server
diff --git a/config/dev_test.yaml b/config/dev_test.yaml
@@ -124,6 +124,7 @@ tunerRelay:
   sourceId: pi-iq
   controlPolicy: exclusive
   maxClients: 1
+  commandHistoryLimit: 200
 
 api:
   host: 0.0.0.0
diff --git a/docs/API.md b/docs/API.md
@@ -115,7 +115,30 @@ curl http://localhost:9000/api/status
 		"bytesSent": 421000000,
 		"bytesReceived": 120,
 		"lastFrequency": 446524920,
-		"lastSampleRate": 2048000
+		"lastSampleRate": 2048000,
+		"lastCommand": "set-frequency",
+		"lastCommandAt": "2024-05-21T03:12:01.123Z",
+		"lastCommandValue": 446524920,
+		"commandHistoryLimit": 200,
+		"commandStats": [
+			{
+				"id": 1,
+				"name": "set-frequency",
+				"count": 6,
+				"lastValue": 446524920,
+				"lastSeenAt": "2024-05-21T03:12:01.123Z"
+			}
+		],
+		"commandHistory": [
+			{
+				"id": 1,
+				"name": "set-frequency",
+				"value": 446524920,
+				"at": "2024-05-21T03:12:01.123Z",
+				"clientId": "client-1",
+				"clientRemote": "192.168.1.50:50522"
+			}
+		]
 	}
 }
 ```
@@ -181,7 +204,30 @@ curl http://localhost:9000/api/tuner-relay
 	"bytesSent": 421000000,
 	"bytesReceived": 120,
 	"lastFrequency": 446524920,
-	"lastSampleRate": 2048000
+	"lastSampleRate": 2048000,
+	"lastCommand": "set-frequency",
+	"lastCommandAt": "2024-05-21T03:12:01.123Z",
+	"lastCommandValue": 446524920,
+	"commandHistoryLimit": 200,
+	"commandStats": [
+		{
+			"id": 1,
+			"name": "set-frequency",
+			"count": 6,
+			"lastValue": 446524920,
+			"lastSeenAt": "2024-05-21T03:12:01.123Z"
+		}
+	],
+	"commandHistory": [
+		{
+			"id": 1,
+			"name": "set-frequency",
+			"value": 446524920,
+			"at": "2024-05-21T03:12:01.123Z",
+			"clientId": "client-1",
+			"clientRemote": "192.168.1.50:50522"
+		}
+	]
 }
 ```
 
diff --git a/docs/DOCKER-SETUP.md b/docs/DOCKER-SETUP.md
@@ -68,17 +68,18 @@ make docker-build-sdrpp  # SDR++ only
 
 ### Environment Variables
 
-| Variable                         | Default | Description                       |
-| -------------------------------- | ------- | --------------------------------- |
-| `WAVEKIT_API_PORT`               | 3000    | API server port                   |
-| `WAVEKIT_LOG_LEVEL`              | info    | Log level (debug/info/warn/error) |
-| `WAVEKIT_SOURCES_0_HOST`         | -       | First source hostname             |
-| `WAVEKIT_SOURCES_0_PORT`         | -       | First source port                 |
-| `WAVEKIT_TUNER_RELAY__ENABLED`   | false   | Enable RTL-TCP tuner relay        |
-| `WAVEKIT_TUNER_RELAY__PORT`      | 1234    | Tuner relay port                  |
-| `WAVEKIT_TUNER_RELAY__SOURCE_ID` | -       | Source ID to expose               |
-| `RTL_TCP_HOST`                   | -       | rtl_tcp host (full mode)          |
-| `RTL_TCP_PORT`                   | 1234    | rtl_tcp port (full mode)          |
+| Variable                                     | Default | Description                       |
+| -------------------------------------------- | ------- | --------------------------------- |
+| `WAVEKIT_API_PORT`                           | 3000    | API server port                   |
+| `WAVEKIT_LOG_LEVEL`                          | info    | Log level (debug/info/warn/error) |
+| `WAVEKIT_SOURCES_0_HOST`                     | -       | First source hostname             |
+| `WAVEKIT_SOURCES_0_PORT`                     | -       | First source port                 |
+| `WAVEKIT_TUNER_RELAY__ENABLED`               | false   | Enable RTL-TCP tuner relay        |
+| `WAVEKIT_TUNER_RELAY__PORT`                  | 1234    | Tuner relay port                  |
+| `WAVEKIT_TUNER_RELAY__SOURCE_ID`             | -       | Source ID to expose               |
+| `WAVEKIT_TUNER_RELAY__COMMAND_HISTORY_LIMIT` | 200     | Tuner relay command history size  |
+| `RTL_TCP_HOST`                               | -       | rtl_tcp host (full mode)          |
+| `RTL_TCP_PORT`                               | 1234    | rtl_tcp port (full mode)          |
 
 ### Mount Configuration
 
diff --git a/readme.md b/readme.md
@@ -191,6 +191,7 @@ tunerRelay:
   port: 1234
   sourceId: "rtl-pi"
   controlPolicy: "exclusive" # or "shared"
+  commandHistoryLimit: 200 # 0 disables command history
 ```
 
 **Usage:**
@@ -204,6 +205,7 @@ tunerRelay:
 - The relay expects an IQ source in `U8_IQ` format (standard RTL-TCP/rtlmux output).
 - In `exclusive` mode, the first client gets control and others are read-only.
 - The relay streams the primary source (first in `sources`), so set `sourceId` to match it.
+- RTL-TCP commands are tracked and available via `GET /api/tuner-relay`.
 
 ## Configuration
 
diff --git a/src/api/routes/health.ts b/src/api/routes/health.ts
@@ -128,10 +128,41 @@ const tunerRelayStatusSchema = {
 		bytesReceived: { type: "number" },
 		lastCommand: { type: "string" },
 		lastCommandAt: { type: "string", format: "date-time" },
+		lastCommandValue: { type: "number" },
 		lastFrequency: { type: "number" },
 		lastSampleRate: { type: "number" },
 		lastGain: { type: "number" },
 		lastPpm: { type: "number" },
+		commandHistoryLimit: { type: "number" },
+		commandStats: {
+			type: "array",
+			items: {
+				type: "object",
+				properties: {
+					id: { type: "number" },
+					name: { type: "string" },
+					count: { type: "number" },
+					lastValue: { type: "number" },
+					lastSeenAt: { type: "string", format: "date-time" },
+				},
+				required: ["id", "name", "count", "lastValue", "lastSeenAt"],
+			},
+		},
+		commandHistory: {
+			type: "array",
+			items: {
+				type: "object",
+				properties: {
+					id: { type: "number" },
+					name: { type: "string" },
+					value: { type: "number" },
+					at: { type: "string", format: "date-time" },
+					clientId: { type: "string" },
+					clientRemote: { type: "string" },
+				},
+				required: ["id", "name", "value", "at"],
+			},
+		},
 		lastError: { type: "string" },
 		rtlTcpHeader: {
 			type: "object",
diff --git a/src/api/routes/tuner-relay.ts b/src/api/routes/tuner-relay.ts
@@ -30,10 +30,41 @@ const tunerRelayStatusSchema = {
 		bytesReceived: { type: "number" },
 		lastCommand: { type: "string" },
 		lastCommandAt: { type: "string", format: "date-time" },
+		lastCommandValue: { type: "number" },
 		lastFrequency: { type: "number" },
 		lastSampleRate: { type: "number" },
 		lastGain: { type: "number" },
 		lastPpm: { type: "number" },
+		commandHistoryLimit: { type: "number" },
+		commandStats: {
+			type: "array",
+			items: {
+				type: "object",
+				properties: {
+					id: { type: "number" },
+					name: { type: "string" },
+					count: { type: "number" },
+					lastValue: { type: "number" },
+					lastSeenAt: { type: "string", format: "date-time" },
+				},
+				required: ["id", "name", "count", "lastValue", "lastSeenAt"],
+			},
+		},
+		commandHistory: {
+			type: "array",
+			items: {
+				type: "object",
+				properties: {
+					id: { type: "number" },
+					name: { type: "string" },
+					value: { type: "number" },
+					at: { type: "string", format: "date-time" },
+					clientId: { type: "string" },
+					clientRemote: { type: "string" },
+				},
+				required: ["id", "name", "value", "at"],
+			},
+		},
 		lastError: { type: "string" },
 		rtlTcpHeader: {
 			type: "object",
diff --git a/src/config.ts b/src/config.ts
@@ -115,6 +115,8 @@ export const TunerRelayConfigSchema = z.object({
 	controlPolicy: z.enum(["exclusive", "shared"]).default("exclusive"),
 	/** Max number of connected clients (optional cap) */
 	maxClients: z.number().int().positive().optional(),
+	/** Command history entries to retain (0 disables history) */
+	commandHistoryLimit: z.number().int().min(0).max(10000).default(200),
 })
 
 /**
@@ -595,6 +597,7 @@ export function getSupportedEnvVars(): string[] {
 		"WAVEKIT_TUNER_RELAY__SOURCE_ID",
 		"WAVEKIT_TUNER_RELAY__CONTROL_POLICY",
 		"WAVEKIT_TUNER_RELAY__MAX_CLIENTS",
+		"WAVEKIT_TUNER_RELAY__COMMAND_HISTORY_LIMIT",
 		"WAVEKIT_LOGGING__LEVEL",
 		"WAVEKIT_LOGGING__DIR",
 		"WAVEKIT_SOURCES__<ID>__HOST",
diff --git a/src/core/tuner-relay.ts b/src/core/tuner-relay.ts
