Client APIs¶

The Knut Message¶

As mentioned in the previous sections, Knut provides various APIs for clients to control services of different types. For example, to control a light service like the PyTradfriLight, the corresponding Light API is used.

When running knutserver, a TCP server is bound on default to the configured address and port (see Configuration). To interact with Knut, a client can send a JSON message terminated with a null byte \0.

Each message to be send to Knut or send form Knut, must have the following JSON schema:

{
  "$schema": "http://json-schema.org/draft/2019-09/schema",
  "title": "Knut Message",
  "type": "object",
  "required": ["apiId", "msgId", "msg"],
  "properties": {
    "apiId": {
      "type": "integer",
      "description": "API identifier"
    },
    "msgId": {
      "type": "integer",
      "description": "Message identifier"
    },
    "msg": {
      "type": "object",
      "description": "API specific message",
      "default": {}
    }
  }
}

For example, sending a message via netcat as client with the Knut server bound to 127.0.0.1:8080 could look like the following:

$ echo -ne '{"apiId": 0, "msgId": 0, "msg": {}}\0' | netcat localhost 8080

The key apiId is an identifier of the API which should be used to process the message. The msgId tells the API which message is received and msg contains finally an individual JSON message which is supported by the API.

Supported Messages¶

Temperature¶

apiId = 1

TEMPERATURE_STATUS_REQUEST = 1¶

Requests the status of a back-end. The message message must have the key id which is the identifier of the requested back-end. For example:

{
  "id": "myTemperatureBackend"
}

TEMPERATURE_STATUS_RESPONSE = 2¶

Upon a TEMPERATURE_STATUS_REQUEST or change of the back-end is a status response send which has the following keys:

The identifier id of the back-end.
The location where the temperature is measured.
The unit in which the temperature value is provided.
The condition at the location as a code point for the Weather Icons font.
The temperature value.

{
  "id": "myTemperatureBackend",
  "location": "Miami",
  "unit": "K",
  "condition": "\\uf00d",
  "temperature": 275.13
}

TEMPERATURE_LIST_REQUEST = 3¶: Requests a list of all temperature back-ends with their status. The msg can be an empty.

TEMPERATURE_LIST_RESPONSE = 4¶

The temperature list response is similar to the TEMPERATURE_STATUS_RESPONSE, only with the key backends. The value of backends is an array containing the status response of all known back-ends. For example:

{
  "backends": [
    {
      "id": "myTemperatureBackend1",
      "location": "Miami",
      "unit": "K",
      "condition": "\\uf00d",
      "temperature": 303.15
    },
    {
      "id": "myTemperatureBackend1",
      "location": "Hamburg",
      "unit": "K",
      "condition": "\\uf008",
      "temperature": 288.05
    }
  ]
}

TEMPERATURE_HISTORY_REQUEST = 5¶: Request the temperature history of a back-end. The msg equals the TEMPERATURE_STATUS_REQUEST message.

TEMPERATURE_HISTORY_RESPONSE = 6¶

The response upon a temperature history request has the following keys:

The identifier id of the back-end.
The temperature with an array of temperature values.
The time with an array of UNIX timestamps where the entries correspond to the temperature array.

For example:

{
  "id": "myTemperatureBackend",
  "temperature": [
    288.05,
    291.05
  ],
  "time": [
    1581863822.2132704,
    1581863882.2132704
  ]
}

Light¶

apiId = 2

LIGHT_STATUS_REQUEST = 1¶

Requests the status of a back-end. The message has the key id with the identifier of the back-end as value. The server will respond with a LIGHT_STATUS_RESPONSE. For example:

{
  "id": "myLightBackend"
}

LIGHT_STATUS_RESPONSE = 2¶

The status of a back-end with the following keys:

The identifier id of the back-end.
The location where the light is located inside a room.
The room in which the light is.
The state of the light whether it is on or off as boolean.
The hasTemperature key indicating whether the light has a light temperature.
The hasDimlevel key indicating whether the light is dimmable.
The hasColor key indicating whether the light can change its color.
The lights temperature as percentage value where 0 is the coldest and 100 the warmest color temperature.
The colorCold defining the lights color when the temperature is 0 as hex code.
The colorWarm defining the lights color when the temperature is 100 as hex code.
The dimlevel in percentage.
The light’s color as hex code.

Note

A client can send the status response to change the state of the light. When sending from a client, only the id key is required and the key of which the value should be changed.

For example a response send by the server:

{
  "id": "myLightBackend",
  "location": "Somewhere in a room...",
  "room": "Some room",
  "state": false,
  "hasTemperature": true,
  "hasDimlevel": true,
  "hasColor": false,
  "temperature": 100,
  "colorCold": "#f5faf6",
  "colorWarm": "#efd275",
  "dimlevel": 50,
  "color": ""
}

An example response send by a client to switch the light on:

{
  "id": "myLightBackend",
  "state": true
}

LIGHTS_REQUEST = 3¶: Requests the status of all back-ends. The message msg can be empty.

LIGHTS_RESPONSE = 4¶

The lights response is similar to the LIGHT_STATUS_RESPONSE, only with the key backends. The value of backends is an array containing the status response of all known back-ends. For example:

{
  "backends": [
    {
      "id": "myLightBackend1",
      "location": "Somewhere in a room...",
      "room": "Some room",
      "state": false,
      "hasTemperature": true,
      "hasDimlevel": true,
      "hasColor": false,
      "temperature": 100,
      "colorCold": "#f5faf6",
      "colorWarm": "#efd275",
      "dimlevel": 50,
      "color": ""
    },
    {
      "id": "myLightBackend1",
      "location": "Somewhere else in a room...",
      "room": "Some other room",
      "state": true,
      "hasTemperature": true,
      "hasDimlevel": true,
      "hasColor": false,
      "temperature": 100,
      "colorCold": "#f5faf6",
      "colorWarm": "#efd275",
      "dimlevel": 50,
      "color": ""
    }
  ]
}

ALL_LIGHTS_REQUEST = 5¶: Requests the combined state of all lights. The message can be empty.

ALL_LIGHTS_RESPONSE = 6¶

The response has the key state, where the value -1 indicates all lights off and 1 all lights on. If the value is 0, neither all lights are on nor off.

Note

If this message is send from a client, only -1 and 1 can be set as value.

For example:

{
  "state": 1
}

ROOMS_LIST_REQUEST = 7¶: Requests a list of all rooms with their state. The message can be empty.

ROOMS_LIST_RESPONSE = 8¶

The response has a key rooms with an array as value containing room state objects. A room state object has the following keys:

The identifier id of the room.
The room’s state with the possible value -1, 0 and 1 analog to the ALL_LIGHTS_RESPONSE.

For example:

{
  "rooms": [
    {
      "id": "myRoom1",
      "state": -1
    },
    {
      "id": "myRoom2",
      "state": 0
    }
  ]
}

ROOM_REQUEST = 9¶

Requests to set the state for a room. The message has the following keys:

The identifier id of the room.
The state which should be set, where only -1 and 1 are valid values.

{
  "id": "myRoom1",
  "state": -1
}

ROOM_RESPONSE = 10¶: The response has the same keys as the ROOM_REQUEST, only that the value of state can be also 0.

Task¶

apiId = 3

REMINDER = 1¶

A message that is send as reminder. It has the following keys:

The identifier id of the task.
The timeRemaining in seconds before due.

{
  "id": "f3b14c5e-8458-11ea-9daa-b88a60bd7559",
  "timeRemaining": 3600
}

TASK_REQUEST = 2¶

Requests the task with the identifier id.

{
  "id": "f3b14c5e-8458-11ea-9daa-b88a60bd7559"
}

TASK_RESPONSE = 3¶

The task response has the following keys:

The identifier id of the task.
The assignee who has the task assigned.
The author of the task.
The task description.
The boolean done which describes whether the task is done or not.
The due time of the task as UNIX timestamp.
The UNIX timestamp reminder, when a REMINDER should be send.
The title of the task.

Note

If the task response is send by a client with an empty id, a new task will be created.

{
  "id": "f3b14c5e-8458-11ea-9daa-b88a60bd7559",
  "assignee": "John",
  "author": "Doug",
  "description": "We need 12 bottles Champagne for the party tonight!",
  "done": false,
  "due": 1577815200,
  "reminder": 1577800800,
  "title": "Drinks for the party"
}

ALL_TASKS_REQUEST = 4¶: Requests a list of all tasks. The message can be empty.

ALL_TASKS_RESPONSE = 5¶

The response has the key tasks with an array as value, containing the object of the TASK_RESPONSE for each task. For example:

{
  "tasks": [
    {
      "id": "f3b14c5e-8458-11ea-9daa-b88a60bd7559",
      "assignee": "John",
      "author": "Doug",
      "description": "We need 12 bottles Champagne for the party tonight!",
      "done": false,
      "due": 1577815200,
      "reminder": 1577800800,
      "title": "Drinks for the party"
    },
    {
      "id": "f3b14c5e-8458-11ea-9daa-va131fassd59",
      "assignee": "John",
      "author": "Doug",
      "description": "Just saw we ran out of cigars!",
      "done": true,
      "due": 1577815200,
      "reminder": 1577800800,
      "title": "Fill up the humidor"
    }
  ]
}

DELETE_TASK_REQUEST = 6¶: Requests to delete a task. The message has the identifier key id of the task which should be deleted.

Local¶

apiId = 4

LOCAL_REQUEST = 1¶: Requests local information. The message msg can be empty.

LOCAL_RESPONSE = 2¶

The local information response has the following keys:

The identifier id of the local object.
The boolean indicator isDaylight describing whether the sun has already set or not.
The location of the location information.
The next sunrise as UNIX timestamp.
The next sunset as UNIX timestamp.

For example:

{
  "id": "home",
  "isDaylight": true,
  "location": "Beverly Hills",
  "sunrise": 1589513114.5880833,
  "sunset": 1589483203.418921
}

Configuration

API Reference