add Unix Socket API

2025-12-12 10:46:49 +01:00
parent 2edffd5f76
commit fe0af4dc64
7 changed files with 1033 additions and 19 deletions
--- a/SOCKET_API.md
+++ b/SOCKET_API.md
@@ -0,0 +1,514 @@
+# VizionStreamer Socket Control API
+
+VizionStreamer can be controlled via a Unix Domain Socket interface. This allows external applications to configure camera parameters and stream settings at runtime.
+
+## Socket Connection
+
+- **Socket Path**: `/tmp/vizion_control.sock`
+- **Protocol**: Unix Domain Socket (SOCK_STREAM)
+- **Message Format**: JSON
+
+## Command Format
+
+All commands follow this JSON structure:
+
+```json
+{
+  "command": "command_name",
+  "params": {
+    "param1": "value1",
+    "param2": "value2"
+  }
+}
+```
+
+## Response Format
+
+All responses follow this JSON structure:
+
+**Success Response:**
+```json
+{
+  "status": "success",
+  "message": "Optional success message"
+}
+```
+
+**Error Response:**
+```json
+{
+  "status": "error",
+  "message": "Error description"
+}
+```
+
+## Available Commands
+
+### 1. Get Available Formats
+
+Retrieve all supported video formats.
+
+**Command:**
+```json
+{
+  "command": "get_formats"
+}
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "formats": [
+    {
+      "width": 1920,
+      "height": 1080,
+      "framerate": 30,
+      "format": "YUY2"
+    },
+    {
+      "width": 1280,
+      "height": 720,
+      "framerate": 60,
+      "format": "MJPG"
+    }
+  ]
+}
+```
+
+**Supported Formats:** YUY2, UYVY, NV12, MJPG, BGR, RGB
+
+---
+
+### 2. Set Video Format
+
+Change the video format (resolution, framerate, pixel format).
+
+**Note:** Cannot be changed while streaming is active.
+
+**Command:**
+```json
+{
+  "command": "set_format",
+  "params": {
+    "width": "1920",
+    "height": "1080",
+    "framerate": "30",
+    "format": "YUY2"
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "message": "Format set successfully"
+}
+```
+
+---
+
+### 3. Start Streaming
+
+Start video streaming from the camera.
+
+**Command:**
+```json
+{
+  "command": "start_stream"
+}
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "message": "Streaming started"
+}
+```
+
+---
+
+### 4. Stop Streaming
+
+Stop video streaming.
+
+**Command:**
+```json
+{
+  "command": "stop_stream"
+}
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "message": "Streaming stopped"
+}
+```
+
+---
+
+### 5. Get Status
+
+Get current streaming status.
+
+**Command:**
+```json
+{
+  "command": "get_status"
+}
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "streaming": true
+}
+```
+
+---
+
+### 6. Set Exposure
+
+Configure camera exposure settings.
+
+**Command:**
+```json
+{
+  "command": "set_exposure",
+  "params": {
+    "mode": "manual",
+    "value": "100"
+  }
+}
+```
+
+**Parameters:**
+- `mode`: "auto" or "manual"
+- `value`: Exposure value (only used in manual mode)
+
+**Response:**
+```json
+{
+  "status": "success",
+  "message": "Exposure set successfully"
+}
+```
+
+---
+
+### 7. Set White Balance
+
+Configure white balance settings.
+
+**Command:**
+```json
+{
+  "command": "set_whitebalance",
+  "params": {
+    "mode": "auto",
+    "temperature": "4500"
+  }
+}
+```
+
+**Parameters:**
+- `mode`: "auto" or "manual"
+- `temperature`: Color temperature in Kelvin (only used in manual mode)
+
+**Response:**
+```json
+{
+  "status": "success",
+  "message": "White balance set successfully"
+}
+```
+
+---
+
+### 8. Set Brightness
+
+Adjust camera brightness.
+
+**Command:**
+```json
+{
+  "command": "set_brightness",
+  "params": {
+    "value": "50"
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "message": "Brightness set successfully"
+}
+```
+
+---
+
+### 9. Set Contrast
+
+Adjust camera contrast.
+
+**Command:**
+```json
+{
+  "command": "set_contrast",
+  "params": {
+    "value": "32"
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "message": "Contrast set successfully"
+}
+```
+
+---
+
+### 10. Set Saturation
+
+Adjust color saturation.
+
+**Command:**
+```json
+{
+  "command": "set_saturation",
+  "params": {
+    "value": "64"
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "message": "Saturation set successfully"
+}
+```
+
+---
+
+### 11. Set Sharpness
+
+Adjust image sharpness.
+
+**Command:**
+```json
+{
+  "command": "set_sharpness",
+  "params": {
+    "value": "3"
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "message": "Sharpness set successfully"
+}
+```
+
+---
+
+### 12. Set Gamma
+
+Adjust gamma correction.
+
+**Command:**
+```json
+{
+  "command": "set_gamma",
+  "params": {
+    "value": "100"
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "message": "Gamma set successfully"
+}
+```
+
+---
+
+### 13. Set Gain
+
+Adjust camera gain.
+
+**Command:**
+```json
+{
+  "command": "set_gain",
+  "params": {
+    "value": "0"
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "message": "Gain set successfully"
+}
+```
+
+---
+
+## Usage Examples
+
+### Using `socat`
+
+```bash
+# Get available formats
+echo '{"command":"get_formats"}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock
+
+# Set video format
+echo '{"command":"set_format","params":{"width":"1920","height":"1080","framerate":"30","format":"YUY2"}}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock
+
+# Start streaming
+echo '{"command":"start_stream"}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock
+
+# Set exposure to auto
+echo '{"command":"set_exposure","params":{"mode":"auto"}}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock
+
+# Set brightness
+echo '{"command":"set_brightness","params":{"value":"50"}}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock
+
+# Get status
+echo '{"command":"get_status"}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock
+
+# Stop streaming
+echo '{"command":"stop_stream"}' | socat - UNIX-CONNECT:/tmp/vizion_control.sock
+```
+
+### Using `nc` (netcat with Unix socket support)
+
+```bash
+echo '{"command":"get_formats"}' | nc -U /tmp/vizion_control.sock
+```
+
+### Using Python
+
+```python
+import socket
+import json
+
+def send_command(command, params=None):
+    sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    sock.connect('/tmp/vizion_control.sock')
+
+    cmd = {"command": command}
+    if params:
+        cmd["params"] = params
+
+    sock.send(json.dumps(cmd).encode())
+    response = sock.recv(4096).decode()
+    sock.close()
+
+    return json.loads(response)
+
+# Examples
+print(send_command("get_formats"))
+print(send_command("set_format", {
+    "width": "1920",
+    "height": "1080",
+    "framerate": "30",
+    "format": "YUY2"
+}))
+print(send_command("set_exposure", {"mode": "auto"}))
+print(send_command("start_stream"))
+```
+
+### Using C++
+
+```cpp
+#include <sys/socket.h>
+#include <sys/un.h>
+#include <unistd.h>
+#include <string>
+#include <iostream>
+
+std::string sendCommand(const std::string& command) {
+    int sock = socket(AF_UNIX, SOCK_STREAM, 0);
+
+    struct sockaddr_un addr;
+    memset(&addr, 0, sizeof(addr));
+    addr.sun_family = AF_UNIX;
+    strcpy(addr.sun_path, "/tmp/vizion_control.sock");
+
+    connect(sock, (struct sockaddr*)&addr, sizeof(addr));
+    send(sock, command.c_str(), command.length(), 0);
+
+    char buffer[4096];
+    int bytesRead = recv(sock, buffer, sizeof(buffer) - 1, 0);
+    buffer[bytesRead] = '\0';
+
+    close(sock);
+    return std::string(buffer);
+}
+
+// Example usage
+int main() {
+    std::cout << sendCommand(R"({"command":"get_formats"})") << std::endl;
+    std::cout << sendCommand(R"({"command":"set_brightness","params":{"value":"50"}})") << std::endl;
+    return 0;
+}
+```
+
+## Parameter Value Ranges
+
+The valid ranges for camera parameters depend on the specific camera model. You can query the camera capabilities through the VizionSDK API or experimentally determine valid ranges.
+
+**Typical ranges (camera-dependent):**
+- Brightness: 0-255
+- Contrast: 0-255
+- Saturation: 0-255
+- Sharpness: 0-255
+- Gamma: 72-500
+- Gain: 0-100
+- Exposure: 1-10000 (in auto mode, value is ignored)
+- White Balance Temperature: 2800-6500 Kelvin
+
+## Error Handling
+
+Always check the `status` field in the response:
+
+```python
+response = send_command("set_format", {...})
+if response["status"] == "error":
+    print(f"Command failed: {response['message']}")
+else:
+    print("Command successful")
+```
+
+## Thread Safety
+
+The socket server handles one client connection at a time. Commands are processed sequentially with mutex protection to ensure thread safety with the camera operations.
+
+## Notes
+
+- The socket file is automatically created when VizionStreamer starts
+- The socket file is removed when VizionStreamer exits cleanly
+- Format changes require streaming to be stopped first
+- Some parameters may not be supported on all camera models
+- Invalid parameter values will return an error response