michelmu/knxd-docker repository overview

ADDRESS=1.5.1
CLIENT_ADDRESS=1.5.2:10
INTERFACE=tpuart
DEVICE=/dev/knx
DEBUG_ERROR_LEVEL=error
FILTERS=single

ADDRESS=1.5.1
CLIENT_ADDRESS=1.5.2:10
INTERFACE=usb
USB_DEVICE=/dev/bus/usb/001/002
DEBUG_ERROR_LEVEL=error
FILTERS=single

ADDRESS=1.5.1
CLIENT_ADDRESS=1.5.2:10
INTERFACE=ipt
IP_ADDRESS=192.168.1.50
DEST_PORT=3671
NAT=false
DEBUG_ERROR_LEVEL=error

ADDRESS=1.5.1
CLIENT_ADDRESS=1.5.2:10
INTERFACE=ft12
DEVICE=/dev/ttyS0
DEBUG_ERROR_LEVEL=error
FILTERS=single

docker run \
--name=knxd \
-p 6720:6720/tcp \
-p 3671:3671/udp \
--device=/dev/bus/usb:/dev/bus/usb:rwm \
--device=/dev/mem:/dev/mem:rw \
--device=/dev/serial/by-id/usb-busware.de_TPUART_transparent_95738343235351D032C0-if00:/dev/knx \
--cap-add=SYS_MODULE \
--cap-add=SYS_RAWIO \
-e ADDRESS="1.5.1" \
-e CLIENT_ADDRESS="1.5.2:10" \
-e INTERFACE=tpuart \
-e DEVICE="/dev/knx" \
-e DEBUG_ERROR_LEVEL="error" \
-e FILTERS="single" \
--restart unless-stopped michelmu/knxd-docker:latest

services:
  knxd:
    image: michelmu/knxd-docker:latest
    container_name: knxd
    ports:
      - "6720:6720/tcp"
      - "3671:3671/udp"
    devices:
      - "/dev/bus/usb:/dev/bus/usb:rwm"
      - "/dev/mem:/dev/mem:rw"
      - "/dev/serial/by-id/usb-busware.de_TPUART_transparent_95738343235351D032C0-if00:/dev/knx"
    cap_add:
      - SYS_MODULE
      - SYS_RAWIO
    environment:
      - ADDRESS=1.5.1
      - CLIENT_ADDRESS=1.5.2:10
      - INTERFACE=tpuart
      - DEVICE=/dev/knx
      - DEBUG_ERROR_LEVEL=error
      - FILTERS=single
    restart: unless-stopped

# Check if container is running
docker ps | grep knxd

# Check container logs for startup messages
docker logs knxd

# Check container resource usage
docker stats knxd --no-stream

# Verify knxd process is running inside container
docker exec knxd ps aux | grep knxd

# Check if knxd is listening on expected ports
docker exec knxd netstat -ln | grep -E '(6720|3671)'

# Test TCP port 6720 (KNX daemon)
telnet localhost 6720

# Test UDP port 3671 (KNXnet/IP) - requires netcat
nc -u localhost 3671

# Access container shell
docker exec -it knxd bash

# Test basic KNX communication with knxtool
knxtool on ip:127.0.0.1 0/1/50    # Turn on device at group address 0/1/50
knxtool off ip:127.0.0.1 0/1/50   # Turn off device at group address 0/1/50

# Read group address value
knxtool read ip:127.0.0.1 0/1/50

# Monitor KNX bus traffic
knxtool groupsocketlisten ip:127.0.0.1

services:
  knxd:
    image: michelmu/knxd-docker:latest
    container_name: knxd
    ports:
      - "6720:6720/tcp"
      - "3671:3671/udp"
    devices:
      - "/dev/bus/usb:/dev/bus/usb:rwm"
      - "/dev/mem:/dev/mem:rw"
      - "/dev/serial/by-id/usb-busware.de_TPUART_transparent_95738343235351D032C0-if00:/dev/knx"
    cap_add:
      - SYS_MODULE
      - SYS_RAWIO
    environment:
      - ADDRESS=1.5.1
      - CLIENT_ADDRESS=1.5.2:10
      - INTERFACE=tpuart
      - DEVICE=/dev/knx
      - DEBUG_ERROR_LEVEL=error
      - FILTERS=single
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "sh", "-c", "ps aux | grep -v grep | grep knxd && netstat -ln | grep 6720"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

docker run \
--name=knxd \
-p 6720:6720/tcp \
-p 3671:3671/udp \
--device=/dev/bus/usb:/dev/bus/usb:rwm \
--device=/dev/mem:/dev/mem:rw \
--device=/dev/serial/by-id/usb-busware.de_TPUART_transparent_95738343235351D032C0-if00:/dev/knx \
--cap-add=SYS_MODULE \
--cap-add=SYS_RAWIO \
--health-cmd="sh -c 'ps aux | grep -v grep | grep knxd && netstat -ln | grep 6720'" \
--health-interval=30s \
--health-timeout=10s \
--health-retries=3 \
--health-start-period=40s \
-e ADDRESS="1.5.1" \
-e CLIENT_ADDRESS="1.5.2:10" \
-e INTERFACE=tpuart \
-e DEVICE="/dev/knx" \
-e DEBUG_ERROR_LEVEL="error" \
-e FILTERS="single" \
--restart unless-stopped michelmu/knxd-docker:latest

# Check detailed logs
docker logs knxd --details

# Check if configuration file was generated correctly
docker exec knxd cat /etc/knxd.ini

# Verify environment variables
docker exec knxd env | grep -E "(ADDRESS|INTERFACE|DEVICE)"

# Check device permissions on host
ls -la /dev/serial/by-id/
ls -la /dev/ttyUSB*

# Check if devices are accessible inside container
docker exec knxd ls -la /dev/knx
docker exec knxd ls -la /dev/bus/usb/

# Test from host system
telnet localhost 6720
nc -u localhost 3671

# Check firewall rules
sudo iptables -L | grep -E "(6720|3671)"

# Test KNX/IP gateway connectivity (for IP tunneling)
ping 192.168.1.50  # Replace with your gateway IP
telnet 192.168.1.50 3671

# Enable debug logging
docker run ... -e DEBUG_ERROR_LEVEL="debug" ...

# Monitor all KNX traffic
docker exec -it knxd knxtool groupsocketlisten ip:127.0.0.1

# Test with different group addresses
docker exec knxd knxtool read ip:127.0.0.1 0/0/1  # Test with a known device

# Follow logs in real-time
docker logs -f knxd

# Search for specific errors
docker logs knxd 2>&1 | grep -i error

# Check startup sequence
docker logs knxd | head -20

# Monitor resource usage
docker stats knxd

# Check container health status
docker inspect knxd | grep -A 10 '"Health"'

# Test KNX integration from Home Assistant
# Add to configuration.yaml:
# knx:
#   host: <docker_host_ip>
#   port: 3671

# Verify connection in Home Assistant logs

# Configure ETS to connect to:
# IP: <docker_host_ip>
# Port: 3671
# Connection type: Tunneling