KNX Agent

KNX Agent

ID: uniflow.plugin.knxagent Category: Building Automation Version: v1.1.0 Min Uniflow Version: Uniflow ≥ v1.4.0

KNX Agent Plugin Reference Manual

1. Overview

Plugin Name: KNX Agent

Type: Building Automation

Identifier: uniflow.plugin.knxagent

Description

Simulates a KNX IP Server/Gateway for virtual device emulation and testing.


2. Technical Architecture

The KNX Agent plugin operates as an in-memory KNX IP server and gateway simulator. It listens for inbound KNXnet/IP connections (in TunnelingServer or RoutingGateway modes) and acts as a virtual KNX bus device network.

The plugin maintains an internal virtual register memory map keyed by KNX Group Addresses (1/1/1). It automatically responds to incoming GroupValueRead requests from external KNX clients/controllers, accepts incoming GroupValueWrite commands, and broadcasts updated values to connected clients. Additionally, it features a built-in simulation engine capable of generating dynamic telemetry test patterns.

Simulation Patterns

Pattern NameDescriptionGenerated Value Type
Static  Retains fixed initial value until explicitly overwritten.
All DPT types
SineWave  Smooth sinusoidal wave oscillation (ideal for temperature/humidity testing).
Double
RandomWalk  Bounded random value walk across steps.
Double / Int32
TogglePulse  Periodic boolean state toggle (0 / 1 pulse).
Bool
NoiseGenerator  Random floating point noise within specified band.
Double

System Interaction & Exposed Catalog Routes

The KNX Agent plugin acts as an embedded KNX IP Server / Device. It maps Uniflow telemetry to KNX Group Addresses (1/2/3), listening for GroupValueWrite packets and answering GroupValueRead queries from KNX IP Routers.

Catalog Routes & Node Integration

Input Event Triggers (Input Nodes):

  • knx.group_read_received - Fired when an external KNX device reads a group address.
  • knx.group_write_received - Fired when a KNX device writes a value.
  • knx.point_updated - Internal point state change.
  • Executable Actions (Action Nodes):

  • knx.write_group_address - Emits a GroupValueWrite telegram to KNX bus.
  • knx.respond_group_read - Sends a GroupValueResponse telegram.
  • knx.set_point_value - Sets internal agent point value.
  • Architecture Diagram

    VISUAL ARCHITECTURE FLOW DIAGRAM
    Rendering Flow Architecture Diagram...

    3. Configuration Parameters

    The following configuration fields are available in the User Interface for this plugin:

    Configuration SettingDescription
    Friendly NameLabel for this KNX Agent instance (e.g., *Virtual KNX Gateway Simulator*).
    EnabledMaster toggle to enable or disable the UDP server listener.
    Listen IPIP interface to bind socket (0.0.0.0 for all interfaces).
    PortListening UDP port (default 3671).
    Server ModeTunnelingServer (point-to-point server) or RoutingGateway (multicast gateway).
    Server Physical AddressIndividual Address reported by virtual server (e.g., 1.1.0).
    Max Tunnel ConnectionsMaximum concurrent client connection capacity (default 5).
    Simulation Tick Interval (ms)Engine update frequency for animated virtual points (default 1000 ms).
    Virtual Points TableConfigured virtual Group Address registry detailing DPT, initial values, and simulation patterns.

    4. Exposed Routes & Data Types

    This plugin exposes catalog fields across the following rule graph nodes:

    Input Source

    The Input Source node reads live values held inside the virtual KNX agent register map.

    Human-Readable Field NameData TypeDescription
    Virtual KNX Group Address Point  Double` / `Bool` / `Int32` / `String
    Current value stored in virtual KNX agent memory space.

    Output Target

    The Output Target node acts as an action sink node to set or overwrite virtual KNX register values and broadcast telegrams to external connected clients.

    Target NameData TypeAssociated ParametersParameter Data TypeRequiredDescription
    Writable Virtual KNX Group Address  Double` / `Bool` / `Int32` / `String
    ValueDouble / Bool / Int32 / StringTrueValue payload to set in virtual memory and broadcast to connected KNX client devices.

    5. Usage Examples

    Scenario A: KNX Wall Switch Press Triggers Milestone PTZ Preset & Avigilon Bookmark

    Workflow Overview:

    When an external KNX physical switch panel sends a GroupValueWrite telegram setting Group Address 1/0/5 to True (knx.group_write_received), Uniflow intercepts the KNX telegram and executes two parallel security actions:

    1. Commands an ONVIF PTZ camera to focus on the office entrance preset (PresetToken: Entrance_Preset).

    2. Creates a video bookmark in Avigilon Control Center.

    Rule Node Configuration:

    1. Event Input Node: KNX Agent Listener

  • Filter Event: knx.group_write_received
  • Exposed Schema Fields: GroupAddress (String), Value (String), Timestamp (DateTime)
  • 2. Logic Filter Node: And Condition

  • Expression: GroupAddress == "1/0/5" AND Value == "True"
  • 3. Output Target Node A: ONVIF PTZ Action

  • Action Target: Go to Preset
  • PresetToken: Entrance_Preset
  • 4. Output Target Node B: Avigilon ACC Action

  • Action Target: Alarms / Get Media / Bookmark
  • Notes: KNX Wall Switch 1/0/5 Pressed
  • Logic Flow Diagram:

    VISUAL ARCHITECTURE FLOW DIAGRAM
    Rendering Flow Architecture Diagram...

    Scenario B: Scheduled Night Mode Event Writes KNX Group Dimming Value

    Workflow Overview:

    At 22:00 PM every night, a Uniflow Scheduler cron timer triggers an automated lighting scene by issuing a knx.write_group_address action to set KNX Group Address 2/1/10 (Corridor Dimming) to 30%.

    Rule Node Configuration:

    1. Event Input Node: Scheduler Event Listener

  • Cron Expression: 0 0 22 * * ? (Daily at 22:00 PM)
  • 2. Logic Pass-Through Node: Constant Int32

  • Output Value: 30
  • 3. Output Target Node: KNX Agent Writer

  • Action Target: Writable Virtual KNX Group Address (knx.write_group_address)
  • GroupAddress: 2/1/10
  • Value: 30
  • Logic Flow Diagram:

    VISUAL ARCHITECTURE FLOW DIAGRAM
    Rendering Flow Architecture Diagram...
    Architecture Flow Diagram — Full Preview