agrirouter Terms and short descriptions

agrirouter in a nutshell

This chapter will give you an overview of the used terms in the agrirouter documentation. Take a look at the linked chapters for further details.

The following paragraphs give a short overview of what you will learn in the linked chapter and how the terms connect to each other. After reading the whole chapter, the following sentences should make good sense to you.

General

  • agrirouter is a neutral data exchange platform.

  • The data exchange shall be performed between different software products of different manufacturers.

  • End users of agrirouter are participants of the agricultural process like farmers and contractors.

The whole chapter can be found here

Accounts

  • agrirouter can handle multiple users.

  • A user can create an account at the agrirouter.

  • One account is meant to represent one company, e.g. a farm or a contractor.

  • The users of the agrirouter create end user accounts.

  • Application providers need a Developer Account.

The whole chapter can be found here

Applications

  • Applications can be created to be connected to the agrirouter.

  • An application is a software product.

  • An application can be a communication unit, a telemetry platform or a farming software.

  • Companies and developers can create software that integrate an interface to the agrirouter.

  • This software is called application.

  • The short term for application is app.

  • The providers of applications are app providers.

  • Users can onboard application instances of an application to their account.

  • These onboarded application instances can than communicate with instances of other apps within this agrirouter account.

  • Apps need to be certified to be onboarded to the agrirouter.

The whole chapter can be found here

Ecosystem of agrirouter

A schema of the hierarchy of agrirouter app instances
Figure 1. A schema of the hierarchy of agrirouter app instances

  • There is 1 agrirouter solution, with multiple accounts, one for each end user. An end user equals a Farm, a Contractor, etc.

  • Every Account can onboard multiple Application Instances.

  • Applications can be onboarded to multiple accounts (dotted grey lines).

  • Applications can be CUs, Farming Software or Telemetry Platforms.

  • Applications of type "Telemetry platform" can onboard multiple virtual CUs.

  • Machines are connected to CUs or Virtual CUs. Machines can be attached to different CUs or Virtual CUs.

  • A teamset is one (virtual) CU with zero to n attached machines.

  • An account can be connected to another account. If that happens, an endpoint is created in each of the 2 accounts, each endpoint representing the other account in that account.

  • If there are 2 CUs installed on a real-world machine, a machine can be found in multiple teamsets and therefore even in multiple accounts.

  • Applications, Virtual CUs, other users accounts and Machines are endpoints that can be source or target of a message.

The whole chapter can be found here.

Concept of message exchange

General:

  • application instances communicate with their corresponding endpoint at the agrirouter.

  • agrirouter provides an inbox, an outbox and a feed unique for each endpoint.

  • an application instance can subscribe for technical message types that it would like to receive from endpoints in that account.

Message forwarding:

  • Every App Instance can send messages to the inbox of its endpoint at the agrirouter.

  • Each message has a technical message type(TMT) and a list of recipient addresses.

  • Instead of or in addition to the recipients list, a message can also be published.

  • If a message is published, agrirouter adds all endpoints to the recipients list that are subscribed for this TMT.

  • agrirouter forwards the messages to the feed of all relevant endpoints.

  • If message pushing is active, the message will directly be delivered to the endpoints outbox

Routings:

  • Messages are only delivered if there is a routing for that.

  • Routings are used to control the message flow and disallow wrong message flow.

  • Routings are created by the end user.

The whole chapter can be found here

Messaging Workflow

  • App Providers can use an authorization process, to assign endpoints and users of application instances.

  • Any App Instance has to perform onboarding to create an endpoint in an agrirouter account.

  • For onboarding, the app instance has to provide a TAN for assignment to the end users account.

  • The authorization process can be used to receive a TAN.

  • A TAN can alternatively be provided by the user interface of the agrirouter for CUs.

  • Telemetry Platforms can onboard their own Virtual CUs.

  • After onboarding, each app instance can communicate with its endpoint using REST or MQTT.

  • App instances using REST send requests to their inbox and receive responses from their outbox.

  • App instances using MQTT send requests to their inbox and receive responses from their outbox.

  • Using the desired protocol, App Instances send commands and messages to their inbox.

  • The HTTP response for a request to the inbox buffer of a REST endpoint through the inbox will be the information that the command or message is being processed.

  • For an MQTT endpoint, there will be no processing information for a request to the inbox.

  • App Instances using the REST protocol will have to poll for a result of this processing at the outbox.

  • App instances using the MQTT protocol will receive the result without polling.

  • Messages that are no commands for the agrirouter will be forwarded to addressing and routing.

  • Commands will be processed by the agrirouter.

  • If a command has a result, this result will be placed in the outbox.

  • An app instance uses commands to call for information.

  • App Instances call for messages from their feed by sending a command to their inbox.

  • The agrirouter will then forward the desired messages from the endpoints feed to its outbox.

  • Additionally, app instances can activate the message pushing, so that they receive messages directly through their outbox.

  • App Instances can call for a filtered header list of available messages.

  • A message containing a list of message headers will then be delivered to the outbox.

  • An app instance can call for a list of endpoints that can receive a specific technical message format.

  • A list of endpoints will then be delivered to the outbox.

The whole chapter can be found here