Tutorial

How to use the library

This tutorial guides you through creating a simple sketch to interact with KNX.

Barebones first

1. Create a new sketch and import esp-knx.ip.h:

#include <esp-knx-ip.h>

void setup() {
  // put your setup code here, to run once:

}

void loop() {
  // put your main code here, to run repeatedly:

}

2. Add WiFi connection code to setup() and call knx.start() after the WiFi connection has been established. Also call knx.loop() inside your loop():

#include <esp-knx-ip.h>

// WiFi config here
const char* ssid = "myssid";
const char* pass = "mypass";

void setup() {
  // Init WiFi
  WiFi.begin(ssid, pass);

  Serial.println("");
  Serial.print("[Connecting]");
  Serial.print(ssid);

  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }

  // Start knx
  knx.start();

  Serial.println();
  Serial.println("Connected to wifi");
  Serial.println(WiFi.localIP());
}

void loop() {
  knx.loop();

}

3. You can now start programming your logic. If you want to send a KNX telegram, you can use the write functions described in the API:

#include <esp-knx-ip.h>

// WiFi config here
const char* ssid = "myssid";
const char* pass = "mypass";

void setup() {
  // Init WiFi
  WiFi.begin(ssid, pass);

  Serial.println("");
  Serial.print("[Connecting]");
  Serial.print(ssid);

  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }

  // Start knx
  knx.start();

  Serial.println();
  Serial.println("Connected to wifi");
  Serial.println(WiFi.localIP());
}

int16_t counter = 0;

void loop() {
  knx.loop();
  
  // We want to send a counter to 3/0/16
  address_t receiving_ga;
  receiving_ga.ga.area = 3;
  receiving_ga.ga.line = 0;
  receiving_ga.ga.member = 16;

  knx.write2ByteInt(receiving_ga, counter);

  counter++;

  delay(1000); // Wait one second
}

Reacting to telegrams

If you want to react to KNX telegrams, you need to register a callback:

#include <esp-knx-ip.h>

// WiFi config here
const char* ssid = "myssid";
const char* pass = "mypass";

void setup() {

  knx.callback_register("My callback", my_callback);
  
  // Init WiFi
  WiFi.begin(ssid, pass);

  Serial.println("");
  Serial.print("[Connecting]");
  Serial.print(ssid);

  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }

  // Start knx
  knx.start();

  Serial.println();
  Serial.println("Connected to wifi");
  Serial.println(WiFi.localIP());
}

int16_t stored_data = 0;

void my_callback(message_t const &msg, void *arg)
{
  // First, figure out what kind of message we got
  switch (msg.ct)
  {
    case KNX_CT_WRITE:
      // It's a write, so we should probably do something with the data. Lets store it.
      stored_data = data_to_2byte_int(msg.data);
      break;
    case KNX_CT_READ:
      // It's a read, so we should reply something, e.g., the data we got before.
      knx.answer2ByteInt(msg.received_on, stored_data);
      break;
  }
  
}

int16_t counter = 0;

void loop() {
  knx.loop();
  
  // We want to send a counter to 3/0/16
  address_t receiving_ga;
  receiving_ga.ga.area = 3;
  receiving_ga.ga.line = 0;
  receiving_ga.ga.member = 16;

  knx.write2ByteInt(receiving_ga, counter);

  counter++;

  delay(1000); // Wait one second
}