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:

{
  "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:

[
  {
    "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:

{
  "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:

{
  "name": "New Device",
  "protocol": "arctech",
  "model": "selflearning-switch",
  "parameters": {
    "house": "12345678",
    "unit": "2"
  }
}

Response: (201 Created)

{
  "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:

{
  "name": "Updated Device",
  "protocol": "arctech",
  "model": "selflearning-switch",
  "parameters": {
    "house": "12345678",
    "unit": "1"
  }
}

Response:

{
  "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)

{
  "house": "12345678",
  "unit": "1"
}

Nexa (codeswitch, bell)

{
  "house": "A",
  "unit": "1"
}

Sartano

{
  "code": "0000000001"
}

Ikea

{
  "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

// 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

# 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