vizionStreamer/SOCKET_API.md

# 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