Router Devices

General function

Without router devices, an application would need to create multiple MQTT connections, which might cost quite a lot of resources. Therefore, router devices were implemented to allow routing multiple connections using one MQTT broker.

Figure 1. Using Router devices vs. not using router devices

Figure 2. Using router devices vs. communication using communication units

Setup of router devices

Router devices can be set up and managed in the agrirouter developer UI

Figure 3. Router device management in the agrirouter developer UI

When clicking on "+ Router device" and adding a name, a new device will be generated.

Figure 4. Router device management in the agrirouter developers UI

To check the connection properties, click on the name of the router device.

Figure 5. Router device details

The certificate for the router device can be downloaded as PEM or P12.

Figure 6. Generate certificate of router device

The certificate for the router device can also be downloaded in this view.

Figure 7. Download certificate of router device

The file includes a JSON structure containing all necessary information for the router device

{
    "authentication": {
        "type": "PEM",
        "secret": "s7jRq5jEvru914M3INJ6B0SluVYKHRmradqo",
        "certificate": "-----BEGIN ENCRYPTED PRIVATE KEY-----\n...\n-----END CERTIFICATE-----\n"
    },
    "deviceAlternateId": "d410a40c-920a-4af5-b4f8-80e45d2904f8",
    "connectionCriteria": {
        "clientId": "27b5ca3e-eb96-4b38-b586-61f9c6a724c4",
        "gatewayId": "2",
        "host": "dke-qa.eu10.cp.iot.sap",
        "port": 8883
    }
}

ConnectionCriteria and Authentication of a single endpoint can be replaced by the data given from the router device, so that every software component of a specific manufacturer can communicate using one router device, as long as all the application instance is connected to the same server. There cannot exist multiple connections using the same router device.

Every time the certificate is downloaded, it is updated in the agrirouter backend. Make sure you store the certificate in a secure place after you downloaded it and only click the download button again if you want to update your certificate (see below).

Certificate update

As well as the certificates received after onboarding an endpoint, the certificates of the router device have a limited validity period of 10 years (changed from 1 year in July 2022). To ensure the communication is not blocked after this, the certificate needs to be updated before the validity period ends. To update a certificate, the developer has to open the details of the certificate view and click on the download button.

High Availability/Load Balancing considerations

Router Devices also introduce the possibility to have two or more instances of your software communicate with agrirouter.

You need to create one router device for every instance of your software. Do not try to connect to the same router device from multiple instances, because all other instances will be disconnected when you open a new connection.

When you have two or more router devices active the following rules apply:

Every Router Device…

can publish commands to the measure topic of every endpoint
can subscribe to the command topic of every endpoint
subscribed to the command topic of an endpoint will receive a separate copy of the respective MQTT messages

Due to the design of the interface, you can not have a specific Router Device receive only a subset of Technical Message Types.

The following configurations could be implemented (not a complete list!):

Active/Active

All Router Devices are actively taking part in agrirouter communication at all times.

This means that you have to make sure that sending commands and processing messages is distributed to specific nodes in order to not process duplicate messages.

You can partition the subset of endpoints you want to handle per instance by ensuring that a specific router device only publishes and subscribes to the topics of endpoints you want it to handle. From the technical process perspective, this is the same as having an Active/Passive configuration.

Active/Passive

Only one Router Device is active at any given time, at least per endpoint.

You can have multiple router devices active, but only one of them responsible for every single endpoint. This partitioning is strictly done on the client/application side.

In that case, the failover implementation of your HA architecture needs to ensure that another instance takes over the communication when the active node fails.