Concept of Message exchange

Overview

The main purpose of the agrirouter platform is to exchange messages between endpoints.

The agrirouter provides a mechanism to receive and forward messages according to a combination of app subscriptions, public or direct addressed messaging and routings configured by the end-user.

This chapter only handles the message exchange on the agrirouter in a general way. This chapter does not handle network layers or TCP-IP protocols. The communication of an application with its endpoint at the agrirouter is described in 10 Application Interaction with agrirouter

General message exchange

In general, there are 3 steps:

  1. An application instance sends a message to its endpoints inbox

  2. agrirouter forwards ("routes") this message to all relevant and permitted endpoints storage ("feed")

  3. Each application instance can call for available messages in its endpoints feed and pull them from the outbox

The following graph shows the way of a message through the agrirouter:

Way of a message through agrirouter
Figure 1. Way of a message through agrirouter

Every endpoint can send messages to specific endpoints and/or publish them.

Every end user can provide routings to allow this message delivery. Per default, no routings are set and therefore, the delivery is disallowed. This can be changed easily by the end user. See the Learning box for further details.

If messages are sent published, they are only delivered to those allowed endpoints that subscribed for this message type. If messages are sent directly and recipients are mentioned in the address lists, they are delivered if the endpoint supports this message type and if there is a routing allowing the delivery.

Message addressing

Messages can be directly addressed to one or more endpoints. They can also be published to send the message to all subscribed endpoints. It is remarked in the message header if the message is directly sent, published, or if both techniques shall be used. agrirouter will take care of not delivering a message twice to the same endpoint.

Message addressing to multiple endpoints; simplified
Figure 2. Message addressing to multiple endpoints; simplified

Sending messages to machines

As a machine has its own endpoint in the agrirouter account, it is possible to address messages to a machine.

To deliver messages that are addressed to a machine, agrirouter needs to know, which application instance (CU or Virtual CU) currently is connected to that machine. Therefore, delivery of messages to a machine can only work if the connected CU or Virtual CU properly reports its teamset including the EFDI Device Description. The command to define a teamset can be found here.

Currently, this is an optional feature of Virtual CU or CUs and not required for a certification.

Buffering and message delivery

After onboarding, every endpoint can send commands to the agrirouter inbox. agrirouter forwards and potentially duplicates the included messages to store them in the feed of the relevant target endpoint(s).

The feed is the time limited storage for messages in each endpoint.

All messages in agrirouter Connectivity-Platform have a retention time of maximum 4 weeks in total before they are deleted. The end-user will be informed about a possible data loss after 3 weeks, so that he has time to react. After an application instance received and confirmed the receipt, the message will be deleted from the agrirouter feed storage.

Every registered endpoint can request the list of messages available in his feed and request specific messages. agrirouter forwards those requested messages to the outbox, delivery to the endpoint depends on the protocol.

In- and outbox of an agrirouter endpoint; simplified
Figure 3. In- and outbox of an agrirouter endpoint; simplified

A more specific description of the parts of an endpoint can be found here .

EXAMPLE

The following example shall describe the terms and the way of a message through agrirouter.

  • An App instance sends a message to the inbox of its endpoint.

  • The message is addressed to another app instances endpoint.

  • agrirouter forwards this message to the feed of the addressed endpoint if there is a routing.

  • The addressed App Instance is than able to request agrirouter to pull this message from its endpoints feed to its endpoints outbox.

  • From there, it can be pulled by the app instance.

Message Header and Message Payload

Every message or command sent to or received from agrirouter consists of a Message header and a payload.

Message Header

The header includes information on how to handle the message. When sending a message, it includes the recipient list and which technical message type is encoded in the payload. It also includes the creation timestamp and a unique ID.

When receiving a message, it includes the source, creation date, technical message type and a unique ID

The header creation is described here

Payload

The payload includes the encoded raw data of the message content. Its structure and content differs depending on the technical message type.

Information types and Technical message types

The technical message type describes the type (e.g. the format) of the content of an agrirouter message. Every endpoint capable of sending such a message declares that it is able to create a valid message of such type. Every endpoint capable of receiving such a message declares that it can interpret that message.

Information types are an abstraction of the technical message types to simplify the setting up of routings.

One technical message type can be part of multiple Information types.

Each technical message type must be assigned to an information type, which represents its meaning and purpose. The technical message types Bitmap, PNG and JPEG for example are summarized as Information Type "Image". This means that endpoints can send Bitmaps, PNGs and JPEGs if a routing for Images exists.

Technical message types are defined by groups outside the agrirouter project. If message types are missing, DKE will add a useful standardized message type. DKE however will not standardize any formats.

An information type is a group of technical message types.

The agrirouter message payload has a technical message type, which is indicated on the envelope. The list of technical message types can be found here. The definition of a new technical message type is possible.

Capabilities

Each endpoint has to describe, which technical message types it can send and/or receive. The listing of those technical message types is called capabilities. Each endpoint has to provide its capabilities when starting to communicate with the agrirouter. The capabilities, an endpoint generally supports (e.g. with all optional features enabled) is required for the Certification.

Some applications are offered with several optional features that are only available to the end user under specific circumstances, e.g. if he buys a special package. an app instance that has such optional features should always send those capabilities to the agrirouter that it really supports under its current configuration. Otherwise, this might lead to data exchange problems.

Subscriptions

As a sender of a message (e.g. an EFDI Telemetry message) does not always know the relevant endpoints, he can send the message as a published message. Every other endpoint can subscribe to any message type that is part of its capabilities.

Before sending the Subscription message, the endpoint has to send the Capabilities message

The steps for this – in general nd with given routings – are:

  1. Endpoint EP3 subscribes for a technical message type(TMT)

  2. App Instance 1 of App 1 sends a message of this TMT to its EP1 Inbox

  3. agrirouter forwards the message to the feed of Endpoint EP3

  4. This message is forwarded to any endpoint that subscribed for that list

  5. As EP 3 is subscribed, the message is forwarded to the outbox of EP3

  6. The App instance 47 can now pull this message from its endpoints feed

Subscribing for a message; simplified
Figure 4. Subscribing for a message; simplified

Exchange with other user accounts

Messages can be sent to other users’ accounts if this users account is connected with the agrirouter account of the sending endpoint. A connected account is represented as an endpoint in the users agrirouter account.

For guidance, how to connect 2 accounts, see the Learning box.

A message that is addressed to this endpoint will be published in the connected account. An app instance that wants to receive messages from a different account has to subscribe its endpoint to the desired technical message type. The process is visible in the following graph:

Sending messages into another account
Figure 5. Sending messages into another account

Short description:

  1. App Instance 1 sends a message of TMT1 to the Endpoint EP9. As there is a routing, agrirouter will forward that message.

  2. agrirouter recognizes that EP9 in real is the connection to Contractor Johns account. Therefore, it now handles the message like an incoming message, published in EP7 of Contractor Johns account. agrirouter looks for endpoints that are:

    • Part of Contractor Johns account

    • have an existing Routing with TMT1 and EP7

    • Are subscribed for the TMT.

  3. The message will be forwarded to any endpoint matching these criteria.

By default, connected accounts do not forward subscriptions. This means: If App Instance 1 in Account A publishes a message of TMT2 and App Instance 4 in Account B is subscribed for that, the message will not be delivered, even though the accounts are connected. However, there is a setting in the account connection to forward those subscriptions, see

Routings

General

To control the message flow between endpoints and to avoid sensitive data being forwarded to the wrong endpoints, end users can setup routings. Only forwardings that are allowed by these routings will be performed by the agrirouter.

A routing consists of:

  • Sender

  • Information Type as abstraction of technical message types

  • Receiver

Message addressing and routing through the agrirouter
Figure 6. Message addressing and routing through the agrirouter

Image Description:

  1. EP 1 sends 2 messages, each addressed to EP2 and EP3.

  2. While both messages of TMT1 reach the destination, because there is a routing given in agrirouter, Only the TMT2 message for EP2 arrives at its destination, because there is no routing given between EP1 and EP3 for TMT2.

Setup of routings

Routings are created by the end user in his agrirouter account. Please refer to the Learning Box

Endpoint Groups

To simplify the creation of routings, endpoints can be grouped in the end user’s user interface. This grouping is only done on the visual layer, an endpoint group can not be addressed with a message.

The default group

The default groups

The CU and machine group

Sometimes new machines are added to the ecosystem, because a CU is connected, a (virtual) CU is connected to a new machine or a virtual CU is created by a telemetry platform. If this happens, a new endpoint for that machine is created in the end users agrirouter account. As the end user is not always logged in to setup routings, he can just setup routings for a "not deletable" default group. Every new endpoint is automatically assigned to the default group and can be removed from that group. The default group itself however cannot be deleted.

The farming software and telemetry platform group

If a new farming software or a telemetry platform is connected, it is automatically added to the group of farming software and telemetry platforms. Any endpoint can be removed from that group, the default group itself however cannot be deleted.

Routings between the default groups

The two default groups are connected through routings, so that any data can be exchanged in both ways.

Routing of telemetry data

For most information types, agrirouter does not read but only route the messages from the inbox of the sending endpoint to the feed(s) of the target endpoint(s). For telemetric data, this is different. The agrirouter does still not read the values, but it can setup routings based on the purpose of the values context.

A more specific definition of EFDI messages can be found here.

Message delivery due to routings
Figure 7. Message delivery due to routings, subscription and public address