agrirouter Certification

In General

Every application needs to be certified to communicate with the agrirouter. The certification ensures that the communication protocol of the agrirouter is successfully implemented and the application can communicate correctly with the agrirouter.

A certification is needed any time the application changes its capabilities or their sending directions, changes the commands or uses a different protocol to communicate with the agrirouter.

Also, if core functionality of the agrirouter integration is being reimplemented in the certified product for whatever reason, a re-certification is mandatory.

Failure to communicate functional changes and re-certify them can lead to temporary deactivation of the application in case of malfunction!

For a new certification version capabilities can never be removed. Neither can a sending direction of a capability be removed. It is only allowed to add capabilities or sending directions for a new version to ensure downwards compatibility. The capabilities command however can of course only include a subset which is smaller than in the version before.

Out of focus

The certification will not check if an application is able to work with the data sent over the agrirouter. The process will only check if the application can send and receive data for the technical message types which were selected for the certification version earlier on.

Certification companies

There are multiple certification companies, a list can be found here.

Certification Requirements

To pass the certification tests there are multiple requirements have to be fulfilled before the certification can start.

Prerequisites

Additional requirements during the process

The following information is not required to start the certification but will be required before finishing it:

  • Message protocol of the application (MQTT / REST).

  • Message format of the application (JSON / Native Protobuf).

  • The capabilities of the application including the technical message types and sending directions.

  • A list of all commands that are used by the application.

  • Is this an initial certification or a recertification for a new version of an existing software?

  • For some test case there has to be at least one extracted original message (as JSON or Base64-Encoded native Protobuf) provided to the certification company.

Relaxed requirements when using SDKs

When using one of the official SDKs for the implementation, some requirements will be assumed ok without explicit checks. These requirements are annotated with [1] below.

To apply this relaxation, you are required to use the most up-to-date release of the respective SDK!

Certification timeout

Once the certification is started, it needs to be successfully passed within 10 weeks. Otherwise, additional costs could be incurred. It is important to respect this time range as part of the implementation planning.

Certification tests

Not all of the certification tests are necessary for your implementation. The certification company is able to tell you which of the tests are necessary to full fill all requirements.

The term "All TMTs" on this page means "All Technical Message Types that were reported in the application certification version".

The selection depends on several parameters and attributes of the specific application. These parameters are listed in the following chapters

Based on the application type

Based on the type of your application, different tests are required. Check here, which type of application suites your requirements best.

Message type Major for Expected results / Acceptance criteria

Onboarding

CUs

  • A new endpoint is visible in the certification account.

  • The external Id is a valid URN, see general requirements.

  • The following application information is visible in the agrirouter UI:

    • The application name

    • The application manufacturer

    • A valid support URL is available

    • By clicking on the support URL the following information is available:

      • Mail

      • Address

      • Phone number

  • After an endpoint was deleted by the user, a new onboarding has to be possible.

  • In case of any error during the onboarding (with the same (re-onboarding) or a different external Id (new onboarding)):

    • An error message is shown to the user (Remark: During onboarding, there is always a UI available).

    • The error message includes the error code returned from agrirouter.

    • The error code does not simply copy the error message from agrirouter.

    • Error codes that might not yet be documented have to be displayed as well.

  • After onboarding, the time of certificate expiration needs to be visible to the user (might be hidden in an "advanced" view or similar)

Authorization

Telemetry platform

Farming software

  • After clicking the "Connect"-Button, the success of the onboarding should be shown to the user; e.g. by displaying a website or updating the own UI.

  • After clicking the "Reject"-Button, the failure to onboard should be shown to the user.

    • The notification should indicate that the onboarding was rejected.

Verification (optional, if supported)

Telemetry platform

Farming software

  • After clicking the "Connect"-Button, the success of verification should be shown to the user; e.g. by displaying a website or updating the own UI.

  • After clicking the "Reject"-Button, the failure to verify should be shown to the user.

    • The notification should indicate that the onboarding was rejected.

Secured Onboarding

Telemetry platform

Farming software

  • A new endpoint is visible in the certification account.

  • The external Id is a valid URN, see general requirements.

  • The following application information is visible in the agrirouter UI:

    • The application name

    • The application manufacturer

    • A valid support URL is available

    • By clicking on the support URL the following information is available:

      • Mail

      • Address

      • Phone number

  • After an endpoint was deleted by the user, a new onboarding has to be possible.

  • In case of any error during the onboarding (with the same (re-onboarding) or a different external Id (new onboarding)):

    • An error message is shown to the user (Remark: During onboarding, there is always a UI available).

    • The error message includes the error code returned from agrirouter.

    • The error code does not simply copy the error message from agrirouter.

    • Error codes that might not yet be documented have to be displayed as well.

  • After onboarding, if not using router devices, the time of certificate expiration needs to be visible to the user (might be hidden in an "advanced" view or similar)

Revoking

Telemetry platform

Farming software

  • The specific endpoint disappears from the certification account.

  • After an endpoint was deleted by the user, revoking has to be possible.

Re-onboarding

Always

(if the application does not use router devices)

  • The application instance uses the same external Id as it has used for onboarding.

  • New credentials can be provided to communicate with agrirouter.

  • After a successful re-onboarding, the endpoint has to communicate with agrirouter using those new credentials.

  • An application instance can also be re-onboarded with the same id if it was deleted in the agrirouter UI or revoked before.

  • In case of the following errors, an error message is required:

    • Wrong account: During re-onboarding, the user is logged in with a different agrirouter account than before. This should result in a new endpoint onboarding in a different account.

Updating RouterDevice

Farming Software

Telemetry Platforms

(If the application uses router devices)

  • The app provider has to demonstrate that he is able to replace the router device with a new one and that the communication via this new router device can be continued. (A restart of the application is allowed)

VCU onboarding

Telemetry platform

  • A new endpoint representing the VCU shows up in the certification account.

  • The external Id is a valid URN, see general requirements

  • A notification is shown in the UI of the telemetry platform or the VCU that informs the user about the successfull onboarding.

  • In case of an error, a notification is shown in the UI of the telemetry platform or the VCU that informs the user about the reason.

VCU offboarding

Telemetry platform

  • The specific endpoint disappears from the certification account.

  • In case of an error, a notification is provided to the initiator of the offboarding

Based on commands

It will be checked in advance by the certification company, which commands are supported by your software in which characteristic. Those will be checked. Here is an overview of the commands:

Message type Condition Expected results / Acceptance criteria

dke:capabilities

Always

  • Setting routes (as sender or/and as receiver) is possible.

  • All information types defined in the certification version of the application to be certified can be selected.

dke:subscription

If the application can receive messages.

  • The application receives published messages of every technical message type mentioned in its certification version as a recipient.

  • An application can optionally offer the possibility to deactivate subscriptions for specific message types. During certifications, all subscriptions are required.

dke:feed_header_query

If application can receive messages.

  • see "Clean your feed"

dke:feed_message_query

If application can receive messages.

  • see "Clean your feed"

dke:feed_confirm

If application can receive messages.

  • see "Clean your feed"

dke:feed_delete

If application can receive messages.

  • see "Clean your feed"

dke:list_endpoints

Optional, if supported.

  • The application instance receives a list of endpoints to which messages of a certain type can be sent.

dke:list_endpoints_unfiltered

Optional, if supported.

  • The application instance receives a list of endpoints to which messages of a certain type can be sent (not considering routing rules)

iso:11783:-10:device_description:protobuf

If application can send messages.

  • If the application reports machines connected via ISOBUS, the AEF conformance test "TaskController" is advised.

  • If the application reports self-built device descriptions (e.g. by translating a TractorECU or using Bluetooth beacons), the reported device descriptions have to be compatible with ISO11783-10 Annex F.

iso:11783:-10:time_log:protobuf

If application can send messages.

  • see "Teamset reports"

Applications sending messages

These tests are only required if your application can send messages.
Message type Condition Expected results / Acceptance criteria

Building chunks

All TMTs except for EFDI and gps:info

  • The sending of a file with a size of more than 1 MB is possible. The chunks context information is filled.

  • The chunkContextId is equal for all chunks that represent 1 file.

  • The chunkContextId changes when a new file is sent.

  • The chunks have to be enumerated in ChunkComponent.current starting from 1, ChunkComponent.total has to equal the highest chunk number

Base64 encoding

All TMTs except for EFDI and gps:info

  • A file that should be sent is encoded in Base64.

  • If multiple chunks are required, each chunk is a valid Base64 string.

Sending gps:info and/or EFDI

App can send gps:info and/or EFDI

  • GPS Position Lists are not Base64-Encoded

  • EFDI Datasets are not Base64-encoded

Exchange zipped folders

TaskData and Shape

  • The TaskData.zip and / or Shape.zip are valid zip files that can be unpacked.

Message addressing

Always; optional, if supported.

  • Sending a message directly to one recipient.

  • Sending a message directly to multiple recipient.

  • Publishing a message.

  • Publishing a message and sending it directly to 1 recipient.

  • Publishing a message and sending it directly to multiple recipient.

Applications receiving messages

These tests are only required if your application can receive data.
Message type Condition Expected results / Acceptance criteria

Merging chunks

All TMTs except for EFDI and gps:info

  • The receiving of a file that consists of 1 chunk without chunk context is possible.

  • The receiving of a file that consists of 1 chunk with chunk context is possible.

  • The receiving of a file that consists of 2 chunks is possible.

  • The receiving of a file that consists of more than 2 chunks is possible.

  • The receiving of a file of multiple chunks, which are not delivered in the right order is possible.

Receive gps:info and EFDI

App can receive gps:info and/or EFDI

  • The application can receive gps:info and EFDI that are not Base64-encoded

Receive Base64 encoded TMTs

All TMTs except for EFDI and gps:info

  • The receiving of a file that is base64-encoded is possible.

Push notifications

Always (if supported).

  • It is tested if push notifications are activated in the capabilities message.

  • It is tested if pushed messages are confirmed by the application after receiving them.

  • There has to be a concept for the case if push notifications are not delivered from the AR because an outage appeared or the push notification gets lost in another way. We recommend to check the feed at least once a day for messages that were not delivered via push notification.

Other requirements

Topic Description Expected results / Acceptance criteria

Timestamps[1]

It will be tested that the software uses UTC Timestamp for every message it sends. See also the general conventions.

  • It’s checked if sent messages are in a range of +/- 1 minute of UTC.

Id requirements[1]

There are several general requirements on counters and Ids communicated to agrirouter.

  • Every application message Id has to be a UUId.

  • On every start up, the sequence number needs to start at 1 and has to be incremented with every command / message.

  • The external Id requirements will be checked.

Billing requirements

To avoid problems during the invoicing and billing process, there are some requirements to support the whole process.

  • The application should save the accountId provided during the onboarding process. The account ID is part of the billing / invoicing and can used to check the invoice, therefore, it should be saved.

Account management

If supported, it is checked if the application / communication unit correctly changes the agrirouter endpoint used for the communication when changing the account internally.

  • After creating a new account / user in the application to be certified, the test steps have to be repeated with the new account.

  • Differentiation between different accounts exists.

  • No messages are sent to a wrong account.

Teamset reports

The application to be certified needs to report teamsets and provide unique teamset Ids.

  • A change of the machine configuration (adding a machine) leads to a new machine in the agrirouter UI.

  • A change of the machine configuration (removing a machine) leads to a new teamset context Id.

  • A change of the machine configuration (changing a device description) leads to a new teamset context Id

Clean your feed

Make sure, your feed will be cleaned by confirming or deleting messages after receiving them.

For the certification, the rule of cleaning your feed applies with a shorter period of time to clean it, just by practical reasons of the certification. Please check the specific time periods with your certification company.

  • After the several tests of receiving or rejecting messages, it will be checked if the feed is empty.

  • All messages are removed from the feed of the endpoint (either be deleting or receiving and confirming) within a certain period of time.

Valid commands[1]

The application to be certified has to show that it can build and send all commands relevant for its implementation without producing an ACK_WITH_FAILURE at agrirouter mentioning an invalid message.

  • All relevant all commands for the implementation can be built and sent without producing an ACK_WITH_FAILURE at agrirouter mentioning an invalid message

Error handling

All errors that show up during communication with agrirouter need to be documented by the application to be certified.

  • Application has to document or display any error that occurs in communication with agrirouter. In particular:

    • agrirouter system messages

    • agrirouter validation messages

  • The application provider can show an error message received from agrirouter to the certification company. This can be an administration functionality (e.g. log or UI).

  • Error messages shown to an end user should include the error code and a self-defined message of the application provider (not just the agrirouter error message).

Buffering

If the Internet connection gets lost or agrirouter is not available for another reason, the application instance should buffer data that needs to be sent when the connection is re-established.

The application instance needs to check for reconnection on its own.

  • It is checked if an application instance keeps trying to communicate with agrirouter when it is not available.

  • It is checked if an application instance will retry to send a dataset that should have been sent when the agrirouter was offline. This applies for EFDI as well as for every other technical message type

Test coverage for Telemetry platform

For Telemetry platform, it will be checked in advance of the test, which functionalities are required for the platform itself and which functionalities are required for its Virtual CUs.

Telemetry platform must at least support the onboarding and offboarding of VCUs as well as the secured onboarding and authorization.

Tests are setup depending on the capabilities of the telemetry platform itself and its VCUs.

  • All requirements described above need to work with 2 different VCUs and - if sending and/or receiving is supported by the platform itself - by the Telemetry platform.

Base64 Encoding

Base64 Encoded strings shall not include line breaks.

Neither Base64 encoded files nor the Base64-encoded messages may include line breaks

Message protocol layer and message format

If your software supports REST or MQTT with JSON, sending and receiving of those formats is checked.

If your software supports REST with native Protobuf, sending and receiving of those formats is checked.

For HTTP REST

Topic Description Expected results / Acceptance criteria

Polling

It is checked that your application does not flood agrirouter with polls

The application shall not poll the outbox of each app instance more often than described here.

Recertification cases

An application has to be re-certified if one of the following things apply:

  • A new technical message type and/or direction is supported by your application

  • The basic message protocol (MQTT or REST) has changed

  • The basic message format (JSON or native Protobuf) has changed

  • The list of implemented commands changed

  • Push notifications are activated in the capabilities

The supported TMTs as well as the used protocol and format are assigned to the certification. A change of any of those functionalities will cause an invalidity of the certificate, which will block your applications communication to agrirouter.

In the unlikely event of an update of agrirouter software, which requires changes in the app providers software (e.g. a new error code that shall be handled), a new certification is not required. However, the app provider is responsible for keeping his software up to date.
1. This check is obsolete when using one of the official SDKs