Basics of communication

General communication convention

Communication with the agrirouter includes communication with inbox AND outbox, regardless whether an app only sends messages or only consumes messages. Every message or command is sent to the inbox, results are always delivered through the outbox.

Prerequisites for communication

Every communication is initiated by the App Instance. The agrirouter endpoint will never contact the app instance.

After application registration, the communication is secured using the SSL certificate retrieved during the onboarding process. The agrirouter provides PKCS12 certificates as well as PEM certificates which can be set within the SSL context of the request to ensure authenticated communication with the agrirouter.

After the validation has happened, the agrirouter provides all necessary security information to establish a messaging connection. The developer is obliged to store this certificate or the tokens secured and encrypted within the application. Receiving the certificate is described in onboarding .

Different layers, the "onion principle"

agrirouter is a platform that is mostly used to transport messages through it and not towards it.

Therefore:

  • the content is encapsulated in

    • messages and commands, which are encapsulated into

      • the request to and the result from the agrirouter, which are encapsulated into

        • the protocol layer of REST using Request and Response or MQTT using Publish and Subscribe.

With exception of EFDI telemetry messages (DeviceDescription and live data), agrirouter doesn’t analyse the messages inside the agrirouter request. It just checks the technical message type and the addressing to determine the recipients based on the routings and subscriptions.

The onion principle for a non-telemetry message
Figure 1. The onion principle for a non-telemetry message

An exception are the EFDI telemetry messages.

The device descriptions are needed by the agrirouter to

  • determine the relevant CU when sending a message directly to a machine

  • filter for DDIs that are allowed to be sent to specific endpoints

  • be sent to endpoints that subscribe to telemetry data after the device description was already sent

Please note that the device description has to be sent every time before the machine starts sending live telemetry data to ensure that all other endpoints are able to update their formerly received device descriptions and new endpoints get the latest updates as well.

The live telemetry data is analysed so that filtering for value categories like fuel consumption is possible.

The onion principle for a telemetry message
Figure 2. The onion principle for a telemetry message

Even if a client uses native protobuf for communication instead of JSON, a command has to be put into a payload wrapper that mentions the message/command type.

The protocol layer

The protocol layer describes the basic communication layer. All agrirouter communication is based on a TCP/IP communication. When onboarding an endpoint, the developer can choose between REST and MQTT.

MQTT

MQTT is a subscription based protocol. Therefore, the client can be informed by agrirouter that new messages are available. For further information, please refer to the following resources:

The agrirouter provides an MQTT Broker server side, so, an app instance has to connect to this server with its client.

When not using Router Devices, the agrirouter provides one MQTT Broker per Endpoint, so there is no danger or chance to subscribe for messages of another endpoint.

General setup

The agrirouter MQTT broker is only reachable via MQTT over TLS using client certificates, providing an encrypted communication channel. Thus, while establishing an MQTT connection to the agrirouter, two different certificates play a role.

On the one hand, the MQTT broker presents a server certificate during the initial handshake. This certificate is signed by a common public intermediate CA whose root CA should be present in all relevant default CA stores. This certificate should be checked for validity while establishing the connection. Most MQTT libraries provide this functionality out-of-the-box and enabled by default.

Additionally, TLS needs to be activated and the TLS client certificate can either be the certificate received during onboarding of the endpoint or from the Router Device.

Communication with the Inbox and Outbox

Using MQTT, the app instance will publish the request and after a while, the agrirouter will publish the response. Polling is not required.

Request and Response using MQTT
Figure 3. Request and Response using MQTT

If there are messages available in the outbox, agrirouter will simply publish them to the MQTT App Instance.

This only applies to command results, not to messages that are sent to the feed by another app instance. Those messages still have to be requested through the inbox but are automatically delivered through the outbox afterwards.

Exception: If Push Notifications are activated, the messages are delivered without a special feed request.

Router Devices

When using MQTT for a telemetry platform or a farming software with multiple accounts, multiple MQTT connections to different brokers would be required. To avoid this, agrirouter introduced router devices which allow to use just one connection for multiple, virtual endpoints.

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 single MQTT broker.

Using router devices vs. not using router devices
Figure 4. Using router devices vs. not using router devices
Using router devices vs. communication using communication units
Figure 5. Using router devices vs. communication using communication units
Setup of router devices

Router devices can be set up and managed within the agrirouter developer UI .Router device management in the agrirouter developer UI image::general/router-devices-screen1.png[Router device management in the agrirouter developer UI]

The setup and usage of router devices is described in the chapter router devices.

REST

Use of the REST protocol should only be considered for single-device communication like CUs!

REST is a well-known principle for online APIs. For more information on REST, please see following resources:

REST uses HTTP requests that results in an HTTP Response.

REST is based on single, request only methods, therefore, the agrirouter cannot contact any endpoint. This means that the endpoint for example has to poll for new messages in the outbox.

Communication Workflow with the Inbox

Using REST, an app instance just receives an HTTP 200 "OK" Response. The App Instance sends a HTTP Post request over an SSL secured connection.

Request and Response in HTTP
Figure 6. Request and Response in HTTP

Communication with the Outbox

Using REST, the communication with the Outbox requires polling:

REST Communication with the outbox
Figure 7. REST Communication with the outbox

Make sure to meet the request frequency requirements.

Comparison of protocols

Both protocols have several advantages and disadvantages. To select the right protocol for your needs, check the following table

Topic MQTT REST

Communication with all Endpoints via one pooled connection

X

Can send JSON

X

X

Can send raw protobuf

X

Needs no polling

X

Steps for Call and Result

3

min. 4; polling

Advice on protocol choice

Every app provider is free to select their preferred protocol.

DKE however advises to use MQTT using Router Devices for any application that handles multiple endpoints (e.g. Telemetry Platforms, but also Farming Software that is a cloud software and communicates on behalf of multiple accounts) or sends data at a frequency higher than 1 message per minute.

Abstraction of communication workflows

To avoid graphs with too many arrows, we simplify the upcoming requests, abstracting MQTT and REST. Whatever protocol you use, a request and response in this document will look like this:

Abstraction of Calls to the Inbox

Abstraction of a Call or Message Sending to the Inbox
Figure 8. Abstraction of a Call or Message Sending to the Inbox

Abstraction of Results from Outbox

Abstraction of a result from the outbox
Figure 9. Abstraction of a result from the outbox

Communication of App Instance and Endpoint

Endpoint Addresses

The endpoint addresses of the inbox and outbox are delivered with the onboarding request. Please refer to Send onboarding Request.

Assigning a result to a request

The assignment between messages sent to the inbox and their corresponding messages in the outbox is done by comparing the application_message_id provided by the app. Therefore, this application_message_id should be unique.

EXCEPTION:

If a message is not correctly encoded, so that the agrirouter cannot decode it, there will be no application_message_id in the result.

Flow for sending messages

Sending messages to the agrirouter creates an ACK message in the outbox of the agrirouter

Send Message or Command to agrirouter
Figure 10. Send Message or Command to agrirouter

Flow of commands

Command Flow
Figure 11. Command Flow

Flow of requesting messages from the feed

If the command is a feed command requesting messages from the feed, the app instance has to confirm the receival of the message, so that it is deleted from the feed.

Command flow for reading the feed
Figure 12. Command flow for reading the feed

The first message to a new endpoint always has to be the Capabilities Message!

Flow of push notifications

When activated, agrirouter will deliver messages directly as push notifications.

Command flow for push Notifications
Figure 13. Command flow for push Notifications

For further information, see the chapter about push notifications.

Terms

A command-process consists of a call (1.1) to the inbox. This call consists of the request and a processing status response. agrirouter will return a result through the outbox. If a message list was delivered from the feed, the messages have to be confirmed.