QKnxNetIpRouter Class

The QKnxNetIpRouter class enables sending and receiving routing KNXnet/IP packets to and from other KNXnet/IP routers. More...

Header: #include <QKnxNetIpRouter>
qmake: QT += knx
Since: Qt 5.12
Inherits: QObject

This class was introduced in Qt 5.12.

Public Types

enum class Error { None, KnxRouting, Network }
enum class FilterAction { RouteDecremented, RouteLast, ForwardLocally, IgnoreTotally, IgnoreAcked }
(alias) KnxAddressWhitelist
enum class RoutingMode { Block, RouteAll, Filter }
enum class State { NotInit, Routing, NeighborBusy, Stop, Failure }

Public Functions

QKnxNetIpRouter(QObject *parent = nullptr)
QKnxNetIpRouter::Error error() const
QString errorString() const
QKnxNetIpRouter::KnxAddressWhitelist filterTable() const
QKnxAddress individualAddress() const
QNetworkInterface interfaceAffinity() const
QHostAddress multicastAddress() const
QKnxNetIpRouter::RoutingMode routingMode() const
void setFilterTable(const QKnxNetIpRouter::KnxAddressWhitelist &table)
void setIndividualAddress(const QKnxAddress &address)
void setInterfaceAffinity(const QHostAddress &address)
void setInterfaceAffinity(const QNetworkInterface &iface)
void setMulticastAddress(const QHostAddress &address)
void setRoutingMode(QKnxNetIpRouter::RoutingMode mode)
QKnxNetIpRouter::State state() const

Public Slots

void sendRoutingBusy(const QKnxNetIpFrame &frame)
void sendRoutingIndication(const QKnxNetIpFrame &frame)
void sendRoutingLostMessage(const QKnxNetIpFrame &frame)
void sendRoutingSystemBroadcast(const QKnxNetIpFrame &frame)
void start()
void stop()


void errorOccurred(QKnxNetIpRouter::Error error, QString errorString)
void routingBusyReceived(QKnxNetIpFrame frame)
void routingBusySent(QKnxNetIpFrame frame)
void routingIndicationReceived(QKnxNetIpFrame frame, QKnxNetIpRouter::FilterAction routingAction)
void routingIndicationSent(QKnxNetIpFrame frame)
void routingLostCountReceived(QKnxNetIpFrame frame)
void routingLostCountSent(QKnxNetIpFrame frame)
void routingSystemBroadcastReceived(QKnxNetIpFrame frame)
void routingSystemBroadcastSent(QKnxNetIpFrame frame)
void stateChanged(QKnxNetIpRouter::State state)

Detailed Description

The QKnxNetIpRouter is bound to a physical network interface which is used for transmitting and receiving the routing frames. It also requires the multicast address used by the KNX installation.

The following code sample illustrates how to use the QKnxNetIpRouter to send and receive KNXnet/IP frames:

QKnxNetIpRouter router1;
QKnxNetIpRouter router2;

auto busyWaitTime = ...
auto busyControlField = ...

// Sending a routing indication to another router on the same IP network
auto routingBusyFrame = QKnxNetIpRoutingBusyProxy::builder()

// Processing routing indications received
             [](QKnxNetIpFrame frame,
                QKnxNetIpRouter::FilterAction routingAction) {
        QKnxNetIpRoutingIndicationProxy indication(frame);
        qInfo().noquote() << "Received routing indication:"
                          << indication.isValid();

        switch (routingAction) {
        case QKnxNetIpRouter::FilterAction::RouteDecremented:
            auto cemi = indication.cemi();
            auto extCtrl = cemi.extendedControlField();
            count = extCtrl.hopCount();
            // decrement and send to other subnet
            auto newIndication =  QKnxNetIpRoutingIndicationProxy::builder()
            // ....
        case QKnxNetIpRouter::FilterAction::RouteLast:
        case QKnxNetIpRouter::FilterAction::ForwardLocally:
        case QKnxNetIpRouter::FilterAction::IgnoreTotally:
        case QKnxNetIpRouter::FilterAction::IgnoreAcked:

See also QKnxLinkLayerFrame and Routing.

Member Type Documentation

enum class QKnxNetIpRouter::Error

This enum holds the state of the QKnxNetIpRouter.

QKnxNetIpRouter::Error::None0No errors.
QKnxNetIpRouter::Error::KnxRouting1Error found at the KNX routing protocol level.
QKnxNetIpRouter::Error::Network2UDP/IP network error.

enum class QKnxNetIpRouter::FilterAction

This enum holds the possible courses of action of a router in response to a received layer service data unit (LSDU). An LSDU is a type of frame used by the L_Data service belonging to the data link layer.

QKnxNetIpRouter::FilterAction::RouteDecremented0The LSDU shall be routed from one subnetwork (on the primary side or the secondary side) to the second subnetwork side (on the secondary side or the primary side) after the hop count value is decremented. The LSDU shall only be routed to the second subnetwork after it has been positively acknowledged on the first subnetwork.
QKnxNetIpRouter::FilterAction::RouteLast1The LSDU shall be routed from the first subnetwork to the second subnetwork and the hop count value shall be set to zero. The telegram shall be acknowledged according to the Data Link Layer specifications of the medium of the first subnetwork and then the LSDU shall be routed to the second subnetwork.
QKnxNetIpRouter::FilterAction::ForwardLocally2The LSDU shall be processed to an NSDU and given to the local network layer user after it has been acknowledged positively on the subnetwork from which it has arrived.
QKnxNetIpRouter::FilterAction::IgnoreTotally3The LSDU shall be ignored; no acknowledgment shall be sent back to the originator of the LSDU.
QKnxNetIpRouter::FilterAction::IgnoreAcked4The LSDU shall be ignored, nonetheless it shall be acknowledged on the subnetwork from which it has arrived.

[alias] QKnxNetIpRouter::KnxAddressWhitelist

This is a type alias for QSet<QKnxAddress>.

A synonym for QKnxNetIpRouter::QSet<QKnxAddress>, which is the type used to store the filter table of the router. The filter table is interpreted as a whitelist by the routing algorithm. The addresses stored are allowed to be routed. Any frame with a destination address that is not contained in the table is blocked.

enum class QKnxNetIpRouter::RoutingMode

This enum holds the possible parameterization actions that a router shall apply on telegrams of a point-to-multipoint connectionless communication mode with standard group addresses.

QKnxNetIpRouter::RoutingMode::Block0No telegrams are allowed to be forwarded on the interface.
QKnxNetIpRouter::RoutingMode::RouteAll1All telegrams are routed and the filter table is ignored.
QKnxNetIpRouter::RoutingMode::Filter2All telegrams with destination addresses not in the filter table are blocked, the rest of telegrams are forwarded.

enum class QKnxNetIpRouter::State

This enum holds the state of the QKnxNetIpRouter.

QKnxNetIpRouter::State::NotInit0Router not started yet.
QKnxNetIpRouter::State::Routing1Router is listening for incoming messages and accepting messages for sending.
QKnxNetIpRouter::State::NeighborBusy2A KNX router in the same network sent a busy message or the QKnxNetIpRouter itself detected a busy situation.
QKnxNetIpRouter::State::Stop3Router has been explicitly stopped by the user.
QKnxNetIpRouter::State::Failure4Any error that occurs in the router shall set this state.

Member Function Documentation

QKnxNetIpRouter::QKnxNetIpRouter(QObject *parent = nullptr)

Constructs a KNXnet/IP router with the parent parent.

[signal] void QKnxNetIpRouter::errorOccurred(QKnxNetIpRouter::Error error, QString errorString)

This signal is emitted when the KNXnet/IP router encounters the error error that is described by errorString.

[signal] void QKnxNetIpRouter::routingBusyReceived(QKnxNetIpFrame frame)

This signal is emitted when the KNXnet/IP router receives a routing busy frame.

[signal] void QKnxNetIpRouter::routingBusySent(QKnxNetIpFrame frame)

This signal is emitted when the KNXnet/IP router has finished sending the routing busy frame.

[signal] void QKnxNetIpRouter::routingIndicationReceived(QKnxNetIpFrame frame, QKnxNetIpRouter::FilterAction routingAction)

This signal is emitted when the KNXnet/IP router receives a routing indication frame and specifies the action routingAction to be applied by the router.

[signal] void QKnxNetIpRouter::routingIndicationSent(QKnxNetIpFrame frame)

This signal is emitted when the KNXnet/IP router has finished sending the routing indication frame.

[signal] void QKnxNetIpRouter::routingLostCountReceived(QKnxNetIpFrame frame)

This signal is emitted when the KNXnet/IP router receives a routing lost count message held in frame.

[signal] void QKnxNetIpRouter::routingLostCountSent(QKnxNetIpFrame frame)

This signal is emitted when the KNXnet/IP router has finished sending the routing lost count frame.

[signal] void QKnxNetIpRouter::routingSystemBroadcastReceived(QKnxNetIpFrame frame)

This signal is emitted when the KNXnet/IP router receives the routing system broadcast frame.

[signal] void QKnxNetIpRouter::routingSystemBroadcastSent(QKnxNetIpFrame frame)

This signal is emitted when the KNXnet/IP router has finished sending the routing system broadcast frame.

[slot] void QKnxNetIpRouter::sendRoutingBusy(const QKnxNetIpFrame &frame)

Multicasts the routing busy message containing frame through the network interface associated with the QKnxNetIpRouter.

[slot] void QKnxNetIpRouter::sendRoutingIndication(const QKnxNetIpFrame &frame)

Multicasts the routing indication frame through the network interface associated with the QKnxNetIpRouter.

[slot] void QKnxNetIpRouter::sendRoutingLostMessage(const QKnxNetIpFrame &frame)

Multicasts the routing lost message frame through the network interface associated with the QKnxNetIpRouter.

[slot] void QKnxNetIpRouter::sendRoutingSystemBroadcast(const QKnxNetIpFrame &frame)

Multicasts the routing system broadcast frame through the network interface associated with the QKnxNetIpRouter.

[slot] void QKnxNetIpRouter::start()

Signals the QKnxNetIpRouter to start listening for messages received and accept sending messages.

[signal] void QKnxNetIpRouter::stateChanged(QKnxNetIpRouter::State state)

This signal is emitted when the KNXnet/IP router transitions to a different state.

[slot] void QKnxNetIpRouter::stop()

Stops the QKnxNetIpRouter. No messages can be received from or sent to the network.

QKnxNetIpRouter::Error QKnxNetIpRouter::error() const

Returns a routing error code that describes the last error to occur in the KNX router.

QString QKnxNetIpRouter::errorString() const

Returns a QString describing the latest known error that occurred in the KNX router.

QKnxNetIpRouter::KnxAddressWhitelist QKnxNetIpRouter::filterTable() const

Returns the filter table used by the routing algorithm.

See also setFilterTable().

QKnxAddress QKnxNetIpRouter::individualAddress() const

Returns the routing interface's individual address.

See also setIndividualAddress().

QNetworkInterface QKnxNetIpRouter::interfaceAffinity() const

Returns the current network interface used by this KNX routing instance.

See also setInterfaceAffinity().

QHostAddress QKnxNetIpRouter::multicastAddress() const

Returns the multicast address used by the QKnxNetIpRouter.

See also setMulticastAddress().

QKnxNetIpRouter::RoutingMode QKnxNetIpRouter::routingMode() const

Returns the routing mode.

See also setRoutingMode().

void QKnxNetIpRouter::setFilterTable(const QKnxNetIpRouter::KnxAddressWhitelist &table)

Sets the filter table used by the routing algorithm to table.

See also filterTable().

void QKnxNetIpRouter::setIndividualAddress(const QKnxAddress &address)

Sets the routing interface's individual address to address.

See also individualAddress().

void QKnxNetIpRouter::setInterfaceAffinity(const QHostAddress &address)

Searches for the network interface that is bound to address that the QKnxNetIpRouter instance shall use.

See also interfaceAffinity().

void QKnxNetIpRouter::setInterfaceAffinity(const QNetworkInterface &iface)

Sets the network interface iface that the QNetworkInterface instance shall use.

void QKnxNetIpRouter::setMulticastAddress(const QHostAddress &address)

Sets the multicast address to address.

See also multicastAddress().

void QKnxNetIpRouter::setRoutingMode(QKnxNetIpRouter::RoutingMode mode)

Sets the routing mode to mode.

See also routingMode().

QKnxNetIpRouter::State QKnxNetIpRouter::state() const

Returns the current state of the KNX router.

© 2023 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.