OpenKNX Common

OpenKNX Common is a library meant to be used once in every OpenKNX Device firmware.

The main functions are:

• setup and calling the knx stack
• setup and calling of the OpenKNX Modules
• flash handling for persistent data of the OpenKNX Modules

Includes ETS configuration and own group objects, see application description (German only).

Usage

It is designed for usage with the headerfile generated by OpenKNXproducer, which provides the necessary defines in knxprod.h:

MAIN_OpenKnxId
MAIN_ApplicationNumber
MAIN_ApplicationVersion

BASE_StartupDelayBase
ParamBASE_StartupDelayTimeMS
BASE_HeartbeatDelayBase
KoBASE_Heartbeat
ParamBASE_HeartbeatDelayTimeMS

Hardware

ARCH	info
RP2040	the reference platform with full support (including dual core support)
SAMD21	obsolete but still supported. no hw should be developed on this anymore
ESP32	experimental

Configuration

To configure the Hardware-Setup use the following defines in hardware.h

General HW settings

define	default	unit	function	mandatory/optional
SAVE_INTERRUPT_PIN			if defined >= 0, falling edge on this pin will trigger power save actions	optional
KNX_UART_RX_PIN			UART receive Pin to connect to BCU	mandatory for TP devices
KNX_UART_TX_PIN			UART transmit Pin to connect to BCU	mandatory for TP devices
KNX_UART_NUM			HW UART number	mandatory for TP devices
SAVE_POWER_PIN			if defined >= 0 this pin will be used to shut off non crucial power	optional
SAVE_POWER_PIN_POWER_OFF			value of SAVE_POWER_PIN to shut the power off (e.g. LOW or HIGH)	mandatory if SAVE_POWER_PIN defined
SAVE_POWER_PIN_POWER_ON			value of SAVE_POWER_PIN to shut the power on (e.g. LOW or HIGH)	mandatory if SAVE_POWER_PIN defined

General FW settings

define	default	unit	function
OPENKNX_RECOVERY_TIME	6000	ms	hold prog button to erase knx and openknx data (not firmware or filesystem). Turn off with 0
OPENKNX_DUALCORE			build with dualcore support (only on RP2040)
OPENKNX_WATCHDOG			compile with watchdog (use only for releases. debugger not working with active watchdog)
OPENKNX_WATCHDOG_MAX_PERIOD	16	s	the timeout period of watchdog
OPENKNX_WATCHDOG_AUTOERASE_RESETS	5	s	erase knx flash after X fast watchdog restarts
OPENKNX_WATCHDOG_AUTOERASE_TIMEOUT	16	s	timeout after the fast restart counter is to be reset
OPENKNX_MAX_MODULES	9
OPENKNX_WAIT_FOR_SERIAL	2000	ms	wait at startup until SERIAL_DEBUG is connected. (optional with timeout - in devmode use high values like 20000 - 0 will disable waiting) Not supported on ESP32
OPENKNX_MAX_LOOPTIME	4000	µs	how much time is the loop allowed to consume. (soft limit)
OPENKNX_LOOPTIME_WARNING	7	ms	issue a warning if the loop has lasted X ms or longer longer.
OPENKNX_LOOPTIME_WARNING_INTERVAL	1000	ms	how often the warning may be issued in the console
OPENKNX_RUNTIME_STAT			Integrate Collection of Runtime-Statistics.
OPENKNX_RUNTIME_STAT_BUCKETN	16		the number of histogram buckets for Runtime-Statistics
OPENKNX_RUNTIME_STAT_BUCKETS	default set	µs	The upper (included) limits of histogram bucket, without last bucket as this will be limited by data-type only. Must be a comma-separated list with OPENKNX_RUNTIME_STAT_BUCKETN-1 entries
OPENKNX_DEBUG			Enable debug mode
OPENKNX_TRACE1..5			Enable debug mode + tracing. to see trace logs, they must match one of the 5 regex filters.
OPENKNX_DEBUGGER			Must be defined if you want to use a debugger (SWD). (e.g., switches off watchdog)
OPENKNX_TIME_DIGAGNOSTIC			Enable time diagnostic console commands. Will be automatically defined if OPENKNX_DEBUG is defined.
OPENKNX_TIME_TESTCOMMAND			Enable time text command to check the behavior of the posix time calculation functions
OPENKNX_TIME_CLOCK	arch depen.		Specifies the used time class. The default for SAMD21 is OpenKNX::Time::TimeClockMillis, for all other architectures OpenKNX::Time::TimeClockSystem
OPENKNX_LITTLE_FS	arch depen.		If true, LittleFS will be enabled. Default true for RP2040 and ESP32.
OPENKNX_OVERRIDE_MASK_VERSION			defines a mask version which will be returned regardless of the MASK_VERSION used for the build. Set this define if the used mask version does not match the media type.
OPENKNX_RTT			Enable RTT Mode (Disable USB Serial output) + Increase BUFFER_SIZE_UP to 10240!
BUFFER_SIZE_UP	1024	Bytes	Using by Segger RTT

LEDs

see README_LED.md

Buttons

define	default	unit	function
PROG_BUTTON_PIN	undef	GPIO	to drive the OpenKNX programming button. Button supports short press (<1000ms), long press, and double press (500ms intervals).
PROG_BUTTON_PIN_MODE	INPUT_PULLUP		values: INPUT_PULLUP, INPUT_PULLDOWN, INPUT. Specifies the mode for the programming button pin.
OPENKNX_BUTTON_DEBOUNCE	50	ms	Software debounce time for buttons to avoid false triggers. Setting to 0 disables it (i.e. to use Hardware debounce).

OpenKNX GPIO Abstraction Layer

OpenKNX Common includes an abstraction layer for GPIOs to seamlessly access GPIOs from the OpenKNX modules, if the GPIOs are integrated into the MCU or provided by port expanders.

Configuration hardware.h

#define OPENKNX_GPIO_NUM 1
#define OPENKNX_GPIO_TYPES OPENKNX_GPIO_T_TCA9555
#define OPENKNX_GPIO_ADDRS 0x20
#define OPENKNX_GPIO_INTS 0xFF  

#define OPENKNX_GPIO_WIRE Wire
#define OPENKNX_GPIO_CLOCK 400000
#define OPENKNX_GPIO_SDA 28
#define OPENKNX_GPIO_SCL 29

#define OPENKNX_xxx_PINS 0x010D, 0x010B, 0x0102, 0x0104

Note:

If you use one or more GPIO expanders (OPENKNX_GPIO_NUM ≥ 1), the lists >OPENKNX_GPIO_TYPES, OPENKNX_GPIO_ADDRS, and OPENKNX_GPIO_INTS must contain exactly as >many entries as specified. The order of entries determines the assignment of expander >addresses and types in the system.

GPIO Numbering:
For expander 1, the IOs are addressed as 0x0100 to 0x01FF, for expander 2 as 0x0200 to 0x02FF, and so on, where XX stands for the IO number on the respective expander (usually 0–7 or 0–15, depending on the expander type).
For MCU-internal GPIOs, use the plain pin number (e.g., 24).

Example:

• 0x0105 means IO 5 on expander 1
• 0x0202 means IO 2 on expander 2

Sample code

openknx.gpio.pinMode(24, OUTPUT);        // Set MCU-GPIO 24 to OUTPUT
openknx.gpio.digitalWrite(24, HIGH);     // Write MCU-GPIO 24 to HIGH

openknx.gpio.pinMode(0x0105, OUTPUT);    // Set IO 5 on expander 1 (addressed as 0x01) to OUTPUT
openknx.gpio.digitalWrite(0x0105, HIGH); // Write HIGH to IO 5 on expander 1

openknx.gpio.digitalRead(0x0105);        // Read IO 5 on expander 1

openknx.gpio.pinMode(0x0202, INPUT_PULLUP); // Set IO 2 on expander 2 (addressed as 0x02) to INPUT_PULLUP

Supported Hardware

• TCA6408: 8-bit I2C port expander
• TCA9555: 16-bit I2C port expander
• PCA9554: 8-bit I2C-bus expander (I2C slave address range 0x20 to 0x27)
• PCA9557: 8-bit I2C-bus expander (I2C slave address range 0x18 to 0x1F)

Features

Current

pinMode, digitalRead, digitalWrite, attachInterrupt

Planned Features

• Interrupt handling on expanders
• analogRead/Write
• bulk setting of pins

Further improvements

• Multicore
• expanders on different I2C units (e.g. 0x01 on Wire, 0x02 on Wire1)