Receiving Results

General

Results for commands and messages from calls for messages are returned to the outbox. An application instance receives them from the outbox and can than decode the data.

Please be aware that an online platform response in general might take up to a minute and the agrirouter is no different from that. So, don’t set a too short timeout for your requests.

Any feed query message has to be confirmed or deleted to be deleted from the feed. If you do not confirm, your customer will receive an email about outdated messages.

MQTT

The endpoint address of the MQTT broker is delivered as host+port in the onboarding request. The outbox is the topic delivered with the "commands" attribute of the onboarding request. The app instance has to subscribe for this topic. The address can be found in Message Sending.

For more information on command management using MQTT, see the Gateway Documentation.

REST

The REST endpoint address of the outbox is delivered with the "command" attribute of the onboarding request.

An application Instance has to perform a GET request to this endpoint to receive all messages from the outbox.

Method Address

GET

/iot/gateway/rest/commands/{{deviceAlternateId}}

Format of received messages

agrirouter returns an array of messages, so, there can be multiple responses in one response package.

The result format depends on the setting of the Accept-Header in the GET Request to the Outbox:

Accept Header Will Receive

application/json

JSON

application/x-protobuf

Native Protobuf

JSON Result

[
    {
        "sensorAlternateId": "49dcf152-eb2a-4b50-ad5c-1af5b737ed80",
        "capabilityAlternateId": "49dcf152-eb2a-4b50-ad5c-1af5b737ed80",
        "command": {
            "message": "fskjlaflasdfkjlasdfkjfalkefnFSDLKDFJL33221sdldgkjglfdkjldkgjDFAFKJLKJSFDSFEESXFRRDGDGRDGDGRSDDGRddrrrg354grdgIODIO35445DGDGLKKJWE3333425H1SJK=="
        }
    }
]

Protobuf Result

The result of a protobuf call is delivered as a CommandResponseList that includes a List of CommandResponses, which includes the sender ID (sensorAlternateId) and a List of Any-Elements value. This list only includes 1 CommandResponseMessage-Element (Index is 0).

syntax = "proto3";
package gateway;
option java_package = "com.sap.iotservices.common.protobuf.gateway";
option java_outer_classname = "CommandResponseMessageProtos";
message CommandResponseMessage {
    bytes message = 1;
}
syntax = "proto3";
import "google/protobuf/any.proto";
package gateway;
option java_package = "com.sap.iotservices.common.protobuf.gateway";
option java_outer_classname = "CommandResponseProtos";
message CommandResponse {
    string capabilityAlternateId = 1;
    string sensorAlternateId = 2;
    Command command = 3;
    message Command {
     repeated google.protobuf.Any values = 1;
    }
}
syntax = "proto3";
import "CommandResponse.proto";
package gateway;
option java_package = "com.sap.iotservices.common.protobuf.gateway";
option java_outer_classname = "CommandResponseListProtos";
message CommandResponseList {
    repeated CommandResponse commands = 1;
}

Here is an example for an unfiltered endpoint list. It’s of course sent as binary, but to be able to put it into this documentation, it’s encoded in Base64:

XgjIARAKGiQ2N2QxY2ZjMC02ZjA5LTRhZmYtYjlhZi05NTk4MzViMjZjNmYiJDI3YmEyYmZiLT
k3YTAtNGFiZC1iYTQ4LTU2MzZiYjNlYWYyMioLCJyW/uEFEMC3oVfEBwrBBwpOdHlwZXMuYWdy
aXJvdXRlci5jb20vYWdyaXJvdXRlci5yZXNwb25zZS5wYXlsb2FkLmFjY291bnQuTGlzdEVuZH
BvaW50c1Jlc3BvbnNlEu4GCvUBCiQwNTI1Y2M0MS0zN2M0LTQ1YjYtOWMwZC04YTEyNTAyYzhm
YWESKEFncmlyb3V0ZXIgQVBJIEltcGxlbWVudGF0aW9uIEV4YW1wbGUgQ1UaC2FwcGxpY2F0aW
9uIgZhY3RpdmUqDAoIaW1nOmpwZWcQAioLCgdpbWc6cG5nEAIqHgoaaXNvOjExNzgzOi0xMDp0
YXNrZGF0YTp6aXAQAioRCg1zaHA6c2hhcGU6emlwEAIqCwoHdmlkOmF2aRACKgsKB3ZpZDptcD
QQAioLCgd2aWQ6d212EAIyGURLRTpEYXRhOkV4YW1wbGVDVTowMDAwMDQKfwokMWMyY2Y2Zjct
ZmEwOS00MDRhLWE5M2ItYmNiMmIyYWUzY2U1EihBZ3Jpcm91dGVyIEFQSSBJbXBsZW1lbnRhdG
lvbiBFeGFtcGxlIENVGgthcHBsaWNhdGlvbiIGYWN0aXZlMhhES0VEYXRhOkV4YW1wbGVDVTow
MDAwMDIK9wEKJDgyYThiYzIzLTdjYzItNDMxYS1iNzdlLTBiNzRmOWE1M2NiNxIoQWdyaXJvdX
RlciBBUEkgSW1wbGVtZW50YXRpb24gVHV0b3JpYWxDVRoLYXBwbGljYXRpb24iBmFjdGl2ZSoM
CghpbWc6anBlZxACKgsKB2ltZzpwbmcQAioeChppc286MTE3ODM6LTEwOnRhc2tkYXRhOnppcB
ACKhEKDXNocDpzaGFwZTp6aXAQAioLCgd2aWQ6YXZpEAIqCwoHdmlkOm1wNBACKgsKB3ZpZDp3
bXYQAjIbMDAwMDAxLUV4YW1wbGVDVUZvclR1dG9yaWFsClgKJDgwYjlmOWQ1LWMwODMtNGE2Zi
1hMDk0LTU5NTNmMjg3ZDRkYxIZVGVzdEFjY291bnRfT2ZfQ29udHJhY3RvchoNcGFpcmVkQWNj
b3VudCIGYWN0aXZlClYKJGMyZDhmMmFmLTI0ODQtNGYzNy05ZTg1LTU1MzgxOTAzMTc3YhIOTW
Vzc2FnZSBSZXBsYXkaFm1lc3NhZ2VSZWNvcmRpbmdSZXBsYXkiBmFjdGl2ZQpHCiQ3ZDRhZGQ1
Ny1mNWM1LTQ3YjctYTQ3ZC1mYzkxYjVkZjZjM2ISCFN0YW5kYXJkGg1lbmRwb2ludEdyb3VwIg
ZhY3RpdmU=

What you will find:

  • 3 CU endpoints with different capabilities

  • 1 connected account

  • 1 Message/Replay Tool

  • 1 Group "Standard"

Troubleshooting

If you experience problems with the message exchange and have parts of the message that are 3 bytes longer than they should be, this is a typical hint for having packed data in an additional Any-Container.

Parameter List

The result of a request to the outbox is an array of messages each including the following parameters:

Name Type Description

capabilityAlternateId

String

Equals value from onboarding

sensorAlternateId

String

Source of the message

CommandResponseList

String

The Base64 encoded message or a protobuf object if agrirouter sent a protobuf object.

For a full documentation of this Message format, see the SAP documentation.