go-telldus-matter/CONFIG_API.md

# Configuration API Documentation

The configuration API allows you to read and modify the `tellstick.conf` file through REST endpoints.

## Endpoints

### Get Full Configuration
```
GET /api/config
```
Returns the complete configuration including global settings, controllers, and devices.

**Response:**
```json
{
  "user": "root",
  "group": "plugdev",
  "devicePath": "/dev/tellstick",
  "ignoreControllerConfirmation": 0,
  "controllers": [
    {
      "id": 0,
      "name": "TellStick",
      "type": "tellstick"
    }
  ],
  "devices": [...]
}
```

### List All Config Devices
```
GET /api/config/devices
```
Returns an array of all devices defined in the configuration file.

**Response:**
```json
[
  {
    "id": 1,
    "name": "Device 1",
    "protocol": "arctech",
    "model": "selflearning-switch",
    "parameters": {
      "house": "12345678",
      "unit": "1"
    }
  }
]
```

### Get Single Config Device
```
GET /api/config/devices/{id}
```
Returns a specific device by ID from the configuration file.

**Response:**
```json
{
  "id": 1,
  "name": "Device 1",
  "protocol": "arctech",
  "model": "selflearning-switch",
  "parameters": {
    "house": "12345678",
    "unit": "1"
  }
}
```

### Create Config Device
```
POST /api/config/devices
```
Creates a new device in the configuration file. If `id` is 0 or not provided, it will be auto-assigned.

**Request Body:**
```json
{
  "name": "New Device",
  "protocol": "arctech",
  "model": "selflearning-switch",
  "parameters": {
    "house": "12345678",
    "unit": "2"
  }
}
```

**Response:** (201 Created)
```json
{
  "id": 2,
  "name": "New Device",
  "protocol": "arctech",
  "model": "selflearning-switch",
  "parameters": {
    "house": "12345678",
    "unit": "2"
  }
}
```

### Update Config Device
```
PUT /api/config/devices/{id}
```
Updates an existing device in the configuration file.

**Request Body:**
```json
{
  "name": "Updated Device",
  "protocol": "arctech",
  "model": "selflearning-switch",
  "parameters": {
    "house": "12345678",
    "unit": "1"
  }
}
```

**Response:**
```json
{
  "id": 1,
  "name": "Updated Device",
  "protocol": "arctech",
  "model": "selflearning-switch",
  "parameters": {
    "house": "12345678",
    "unit": "1"
  }
}
```

### Delete Config Device
```
DELETE /api/config/devices/{id}
```
Removes a device from the configuration file.

**Response:** 204 No Content

## Device Parameters

Common parameters for different protocols:

### Arctech (selflearning-switch, selflearning-dimmer)
```json
{
  "house": "12345678",
  "unit": "1"
}
```

### Nexa (codeswitch, bell)
```json
{
  "house": "A",
  "unit": "1"
}
```

### Sartano
```json
{
  "code": "0000000001"
}
```

### Ikea
```json
{
  "system": "1",
  "units": "1",
  "fade": "true"
}
```

## Notes

- Changes to the configuration file will trigger an automatic daemon restart and device reload
- The config file watcher will detect changes and sync devices/sensors automatically
- Device IDs in the config file are separate from runtime device IDs
- All modifications are written immediately to `/etc/tellstick.conf`

## Example Usage

### JavaScript/Fetch
```javascript
// Get all config devices
const devices = await fetch('/api/config/devices').then(r => r.json());

// Create a new device
const newDevice = await fetch('/api/config/devices', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Living Room Light',
    protocol: 'arctech',
    model: 'selflearning-switch',
    parameters: {
      house: '12345678',
      unit: '3'
    }
  })
}).then(r => r.json());

// Update device
await fetch(`/api/config/devices/${newDevice.id}`, {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Living Room Lamp',
    protocol: 'arctech',
    model: 'selflearning-switch',
    parameters: {
      house: '12345678',
      unit: '3'
    }
  })
});

// Delete device
await fetch(`/api/config/devices/${newDevice.id}`, {
  method: 'DELETE'
});
```

### cURL
```bash
# Get all devices
curl http://localhost:8080/api/config/devices

# Create device
curl -X POST http://localhost:8080/api/config/devices \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Device",
    "protocol": "arctech",
    "model": "selflearning-switch",
    "parameters": {
      "house": "12345678",
      "unit": "5"
    }
  }'

# Update device
curl -X PUT http://localhost:8080/api/config/devices/1 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "protocol": "arctech",
    "model": "selflearning-switch",
    "parameters": {
      "house": "12345678",
      "unit": "1"
    }
  }'

# Delete device
curl -X DELETE http://localhost:8080/api/config/devices/1
```