Device status
First things first, you can check if your device is correctly registered in Data Orchestrator, and its current status.
Let's assume our Device has f0VMRgIBAQAAAAAAAAAAAA as its id.
A Device's status includes a number of useful information, among which whether it is connected or not to its Transport,
its introspection, the amount of exchanged data and more.
Query Device status using astartectl
$ astartectl appengine devices show f0VMRgIBAQAAAAAAAAAAAA
Device ID: f0VMRgIBAQAAAAAAAAAAAA
Connected: false
Last Connection: 2018-02-07 18:38:57.266 +0000 UTC
Last Disconnection: 2018-02-08 09:49:26.566 +0000 UTC
Introspection: com.example.ExampleInterface v1.0 exchanged messages: 20 exchanged bytes: 200B
org.example.TestInterface v0.2 exchanged messages: 8 exchanged bytes: 147B
Received Messages: 221
Data Received: 11.7K
Last Seen IP: 203.0.113.89
Last Credentials Request IP: 203.0.113.201
First Registration: 2018-01-31 17:10:59.270 +0000 UTC
First Credentials Request: 2018-01-31 17:10:59.270 +0000 UTC
Query Device status using Data Orchestrator Dashboard
After logging in to Data Orchestrator dashboard, go to the "Devices" page clicking on the menu on your left. A list of available Device IDs will appear. If you do not see your device at a glance, use the search bar on the top right to find it. Clicking on the Device ID will take you to its details page.
Query Device status using AppEngine API
GET api.<your astarte domain>/appengine/v1/test/devices/f0VMRgIBAQAAAAAAAAAAAA
{
"data": {
"total_received_msgs": 221,
"total_received_bytes": 11660,
"last_seen_ip": "203.0.113.89",
"last_credentials_request_ip": "203.0.113.201",
"last_disconnection": "2018-02-07T18:38:57.266Z",
"last_connection": "2018-02-08T09:49:26.556Z",
"id": "f0VMRgIBAQAAAAAAAAAAAA",
"first_registration": "2018-01-31T17:10:59.270Z",
"connected": true,
"introspection": {
"com.example.ExampleInterface" : {
"major" : 1,
"minor" : 0,
"exchanged_msgs": 20,
"exchanged_bytes": 200
},
"org.example.TestInterface" : {
"major" : 0,
"minor" : 2,
"exchanged_msgs": 8,
"exchanged_bytes": 147
}
},
"aliases": {
"name": "device_a"
},
"attributes": {
"attributes_key": "attributes_value"
},
"groups": [
"my_group",
],
"previous_interfaces": [
{
"name": "com.example.ExampleInterface",
"major" : 0,
"minor" : 2,
"exchanged_msgs": 3,
"exchanged_bytes": 120
}
]
}
}
Through the API, it is also possible to get the Introspection of the device only:
GET api.<your astarte domain>/appengine/v1/test/devices/f0VMRgIBAQAAAAAAAAAAAA/interfaces
{
"data": [
"com.example.ExampleInterface",
"com.example.TestInterface"
]
}
This returns the Interfaces which the device reported in its Introspection and which are known to the Realm.
Arbitrary information can be added to the device by means of attributes: they allow to store any
number of string values associated to a corresponding string key.
To set, modify and delete attributes, a PATCH on the device endpoint is required:
PATCH api.<your astarte domain>/appengine/v1/test/devices/f0VMRgIBAQAAAAAAAAAAAA
In the request body, the data JSON object should have a attributes key which bears a dictionary
of strings. A valid request body which changes only device attributes, for example, is
{"data":{"attributes": {"<key>": "<value>"}}}. To delete an attribute entry, set the value of the
corresponding key to null. For example, POSTing {"data":{"attributes": {"my_key": null}}} will
remove the my_key attribute entry from the device.
Depending on the aggregation and ownership of the Interface, you can GET/PUT/POST on the interface itself or one of its mappings,
or use astartectl to perform the same operation on the command line. Some examples are:
Get data from an aggregate device properties interface
astartectl invocation: astartectl appengine devices data-snapshot f0VMRgIBAQAAAAAAAAAAAA com.example.ExampleInterface
AppEngine API invocation: GET api.<your astarte domain>/appengine/v1/test/devices/f0VMRgIBAQAAAAAAAAAAAA/interfaces/com.example.ExampleInterface
Get last sent value from an individual device datastream interface
astartectl invocation: astartectl appengine devices data-snapshot f0VMRgIBAQAAAAAAAAAAAA com.example.TestInterface
AppEngine API invocation: GET api.<your astarte domain>/appengine/v1/test/devices/f0VMRgIBAQAAAAAAAAAAAA/interfaces/com.example.TestInterface/myValue?limit=1
Set values in an individual server datastream interface
astartectl invocation: astartectl appengine devices send-data f0VMRgIBAQAAAAAAAAAAAA com.example.OtherTestInterface /myOtherValue <value>
AppEngine API invocation: POST api.<your astarte domain>/appengine/v1/test/devices/f0VMRgIBAQAAAAAAAAAAAA/interfaces/com.example.OtherTestInterface/myOtherValue
Request body: {"data": <value>}
API Query semantics
In general, to query AppEngine, the following things must be kept in mind
- When sending data, use
PUTif dealing withproperties,POSTif dealing withdatastream. - When
GETting, if you are querying anaggregateinterface, make sure to query the interface itself rather than its mappings. - When
GETtingdatastream, keep in mind that AppEngine's default behavior is to return a large as possible timeseries.