maulik9898/knx-ws repository overview

⁠KNX Backend API Documentation

⁠Table of Contents

1. Introduction⁠
2. Types⁠
   • KnxMessage⁠
   • KnxEvent⁠
3. REST API Endpoints⁠
   • Write Group Address⁠
   • Read Group Address⁠
   • Health Check⁠
4. WebSocket Communication⁠
   • Connection⁠
   • Message Format⁠
   • Event Types⁠
     • Write Event⁠
     • Read Event⁠
   • Server-to-Client Events⁠
     • GroupValue_Write Event⁠
     • GroupValue_Read Event⁠
     • GroupValue_Response Event⁠
5. Error Handling⁠
6. Examples⁠
   • Write Group Address⁠
   • Read Group Address⁠
   • WebSocket Communication⁠
7. Usage⁠

⁠Introduction

The KNX backend API allows you to interact with KNX devices and perform various operations such as reading and writing group addresses. It provides REST endpoints for synchronous communication and supports WebSocket for real-time updates and asynchronous communication.

⁠Types

⁠KnxMessage

The KnxMessage type represents the message format used for communication with the KNX backend. It can be either a KnxReadMessage or a KnxWriteMessage.

export enum KnxOperation {
  Read = 'read',
  Write = 'write',
}

export interface KnxReadMessage {
  operation: KnxOperation.Read;
  groupAddress: string;
  callback?: string;
}

export interface KnxWriteMessage {
  operation: KnxOperation.Write;
  groupAddress: string;
  value: any;
  dpt: string;
}

export type KnxMessage = KnxReadMessage | KnxWriteMessage;

⁠KnxEvent

The KnxEvent type represents the event format used for WebSocket communication. It can be either a KnxGroupValueWriteEvent, KnxGroupValueReadEvent, or KnxGroupValueResponseEvent.

export enum KnxEventType {
  GroupValueWrite = 'GroupValue_Write',
  GroupValueRead = 'GroupValue_Read',
  GroupValueResponse = 'GroupValue_Response',
}

export interface KnxGroupValueWriteEvent {
  type: KnxEventType.GroupValueWrite;
  source: string;
  destination: string;
  value: any;
}

export interface KnxGroupValueReadEvent {
  type: KnxEventType.GroupValueRead;
  source: string;
  destination: string;
}

export interface KnxGroupValueResponseEvent {
  type: KnxEventType.GroupValueResponse;
  source: string;
  destination: string;
  value: any;
}

export type KnxEvent = KnxGroupValueWriteEvent | KnxGroupValueReadEvent | KnxGroupValueResponseEvent;

⁠REST API Endpoints

⁠Write Group Address

Endpoint: POST /api/knx/write

Description: Writes a value to a specific group address.

Request Body:

{
  "operation": "write",
  "groupAddress": "group_address",
  "value": "value_to_write",
  "dpt": "datapoint_type"
}

Successful Response:

• Status Code: 200 (OK)
• Body:

  {
    "message": "Write successful"
  }
  

  Copy

Error Responses:

• Status Code: 400 (Bad Request)
  • Body:

    {
      "error": "Invalid operation"
    }
    

    Copy
• Status Code: 500 (Internal Server Error)
  • Body:

    {
      "error": "Write failed"
    }
    

    Copy

⁠Read Group Address

Endpoint: GET /api/knx/read

Description: Reads the current value of a specific group address.

Request Parameters:

• groupAddress (string, required): The group address to read.

Successful Response:

• Status Code: 200 (OK)
• Body:

  {
    "type": "GroupValue_Response",
    "source": "server",
    "destination": "group_address",
    "value": "current_value"
  }
  

  Copy

Error Response:

• Status Code: 500 (Internal Server Error)
  • Body:

    {
      "error": "Read failed"
    }
    

    Copy

⁠Health Check

Endpoint: GET /api/knx/health

Description: Checks the connection status of the KNX backend.

Successful Response:

• Status Code: 200 (OK)

Error Response:

• Status Code: 404 (Not Found)

⁠WebSocket Communication

⁠Connection

To establish a WebSocket connection with the KNX backend, connect to the following URL:

• ws://ip:port/api/knx/ws

⁠Message Format

The WebSocket messages are exchanged in JSON format. Each message consists of an operation type (read or write) and associated data.

⁠Event Types

⁠Write Event

Description: Requests a write operation on a specific group address.

Message Format:

{
  "operation": "write",
  "groupAddress": "group_address",
  "value": "value_to_write",
  "dpt": "datapoint_type"
}

⁠Read Event

Description: Requests a read operation on a specific group address.

Message Format:

{
  "operation": "read",
  "groupAddress": "group_address",
  "callback": "optional_callback"
}

⁠Server-to-Client Events

The KNX backend sends the following events to all connected WebSocket clients:

⁠GroupValue_Write Event

Description: Indicates that a group address value has been written.

Event Format:

{
  "type": "GroupValue_Write",
  "source": "knx_device_address",
  "destination": "group_address",
  "value": "written_value"
}

⁠GroupValue_Read Event

Description: Indicates that a group address value has been requested to be read.

Event Format:

{
  "type": "GroupValue_Read",
  "source": "knx_device_address",
  "destination": "group_address"
}

⁠GroupValue_Response Event

Description: Indicates the response to a read request, containing the current value of a group address.

Event Format:

{
  "type": "GroupValue_Response",
  "source": "knx_device_address",
  "destination": "group_address",
  "value": "current_value"
}

⁠Error Handling

In case of an error, the API will respond with an appropriate HTTP status code and an error message in the response body.

Example Error Response:

{
  "error": "Error message"
}

⁠Examples

⁠Write Group Address Example

Request:

POST /api/knx/write

Request Body:

{
  "operation": "write",
  "groupAddress": "1/0/1",
  "value": false,
  "dpt": "DPT1.001"
}

Successful Response:

{
  "message": "Write successful"
}

Error Response:

{
  "error": "Write failed"
}

⁠Read Group Address Example

Request:

GET /api/knx/read?groupAddress=1/0/1

Successful Response:

{
  "type": "GroupValue_Response",
  "source": "server",
  "destination": "1/0/1",
  "value": true
}

Error Response:

{
  "error": "Read failed"
}

⁠WebSocket Communication Example

1. Connect to the WebSocket URL: ws://ip:port/api/knx/ws

2. Send a read event:

   {
     "operation": "read",
     "groupAddress": "1/0/1"
   }
   

   Copy

3. Receive a GroupValue_Response event:

   {
     "type": "GroupValue_Response",
     "source": "1.1.100",
     "destination": "1/0/1",
     "value": true
   }
   

   Copy

4. Send a write event:

   {
     "operation": "write",
     "groupAddress": "1/0/1",
     "value": false,
     "dpt": "DPT1.001"
   }
   

   Copy

5. Receive a GroupValue_Write event:

   {
     "type": "GroupValue_Write",
     "source": "1.1.100",
     "destination": "1/0/1",
     "value": false
   }
   

   Copy

⁠Usage

The KNX backend is packaged as a Docker container and can be deployed using the Docker CLI directly.

⁠Docker CLI

1. Open a terminal and run the following command:

docker run -d --network=host -e NODE_ENV=production maulik9898/knx-ws:latest

This command will pull the maulik9898/knx-ws:0.0.1 image from the Docker Hub registry and start the container in detached mode. It will also run the container in the host's network mode and set the NODE_ENV environment variable to production.

Visit http://localhost:5666 to open KNX testing page

1. To stop the container, first find its ID or name using docker ps, and then run:

docker stop <container_id_or_name>