Read the eco system

To communicate with all the other endpoints in the eco system of the specific agrirouter account, it is required to read,

  • which endpoints are available

  • which TMT they can send

  • which TMT they can receive

  • which TMT they are subscribed for

Call for endpoints that support a technical message type

Definition

Every App Instance can call for a list of endpoints that are capable of receiving or sending specific messages. This command only takes into account capabilities of endpoints, but does not take into account any routes.

A complete list of endpoints in the connected agrirouter account is returned. Only the message_types list will be filtered according to the parameters.

Command

Command

dke:list_endpoints_unfiltered

Protobuf Schema

agrirouter.request.payload.account.ListEndpointsQuery

TypeURL

types.agrirouter.com/agrirouter.request.payload.account.ListEndpointsQuery
# Name Type Description

1

technical_message_type

String

The technical message type the remote endpoint supports

2

direction

Direction

The direction the remote endpoint supports (e.g. "Can the remote endpoint SEND this message type?")

The direction describes if messages shall be sendable or receivable:

Nr Direction

0

Send

1

Receive

2

Send or Receive

Result

ResultCode

ENDPOINTS_LISTING

Protobuf Schema

agrirouter.response.payload.account.ListEndpointsResponse

TypeURL

types.agrirouter.com/agrirouter.response.payload.account.ListEndpointsResponse

The endpoint response includes a list of available endpoints:

# Name Type Description

1

endpoint_id

String

The endpoint ID to address a message to

2

endpoint_name

String

The name of the endpoint as displayed in the agrirouter UI

3

endpoint_type

String

The type of Endpoint, see below

4

status

String

The current activity status of the endpoint

5

message_types

MessageTypes

See below

6

external_id

String

The id provided as "id" in the onboarding request

The endpoint Type can be one of the following Values:

Code Description Comment

application

Software Application

Software Application

foreignMachine

External Machine

Machine shared by a paired agrirouter account

machine

Machine

Agricultural machine

messageRecordingReplay

Recording Player

Can replay recorded messages

pairedAccount

Paired Account

Represents a paired agrirouter account with which you can exchange messages

endpointGroup

Group

A group of other assets (applications, machines) with common rules

virtualCU

Telemetry Platform

Connection via Telemetry Platform

The status can be one of the following values:

Status

active

inactive

The Message object describes technical message type and direction.

# Name Type Description

1

technical_message_type

String

The technical message type the remote endpoint supports

2

direction

Direction

The direction the remote endpoint supports (e.g. "Can the remote endpoint SEND this message type?")

The direction describes if messages shall be sendable or receivable:

Nr Direction

0

Send

1

Receive

2

Send and Receive

  • The endpoint requesting the endpoint list is also part of this answer.

  • The concept of groups is only used to give a little more comfort to the end user when setting rules. It is currently not possible to address a message to the group.

Implementation advises

If your application can send messages without user interaction, it is advised to update the endpoint list in a cyclic manor, e.g. every 5 minutes.

If your application only sends messages if a user is present, it is advised to update the endpoint list depending on the user interaction, e.g. manually with an "update" button or integrated in another user interaction like opening the destination selection dialog.

These are advises, not requirements

Errors

If the message was incorrect, an ACK_WITH_FAILURE will be reported. For specific error messages, see the error list.

Call for filtered list of endpoints that support a specific message type

Definition

This request is used for request a list of endpoints that support a technical message type and has corresponding routings to the requesting endpoint.

This command takes into account the routes between endpoints, which implicitly includes capabilities.

Command

Command

dke:list_endpoints

Protobuf Schema

agrirouter.request.payload.account.ListEndpointsQuery

TypeURL

types.agrirouter.com/agrirouter.request.payload.account.ListEndpointsQuery
# Name Type Description

1

technical_message_type

String

The technical message type the remote endpoint supports

2

direction

Direction

The direction the data can flow from the perspective of the requesting endpoint (e.g. "Can I SEND this specific data type to the other endpoint?")

For further information, see Call for endpoints that support a technical message type

Result

ResultCode

ENDPOINTS_LISTING

Protobuf Schema

agrirouter.response.payload.account.ListEndpointsResponse

TypeURL

types.agrirouter.com/agrirouter.response.payload.account.ListEndpointsResponse
# Name Type Description

1

technical_message_type

String

The technical message type the remote endpoint supports

2

direction

Direction

The direction the data can flow from the perspective of the requesting endpoint (e.g. "Can I SEND this specific data type to the other endpoint?")

For further information, see Call for endpoints that support a technical message type

Errors

If the message was incorrect, an ACK_WITH_FAILURE will be reported. For specific error messages, see the error list.