Astarte Interfaces

io.edgehog.devicemanager.BaseImage v0.1

About

This interface is of type properties and is owned by the device, meaning that it is the device which initiates the data flow. Thanks to this type of interface, the device can set a persistent, stateful, synchronized state with no concept of history or timestamping.

Mappings

The interface has the following mappings:

  • /fingerprint with string type. OS bundle release identification code
  • /name with string type. Name of the bundle
  • /version with string type. Version of the bundle
  • /buildId with string type. Human readable build identifier. Examples are [date][time] or [date]-[time]-[git-commit]

/fingerprint

OS bundle release identification code

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The value of the property cannot be unset.

/name

Name of the bundle

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The value of the property cannot be unset.

/version

Version of the bundle

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The value of the property cannot be unset.

/buildId

Human readable build identifier. Examples are [date][time] or [date]-[time]-[git-commit]

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The value of the property cannot be unset.

io.edgehog.devicemanager.BatteryStatus v0.1

About

This interface is of type datastream and is owned by the device, meaning that it is the device which initiates the data flow. Thanks to this type of interface, the device can send a mutable, ordered stream of data, with no concept of persistent state or synchronization.

Data gets sent with an object aggregation. Astarte expects the owner to send all of the interface's mappings at the same time, packed in a single message.

Mappings

The interface has the following mappings:

  • /%{battery_slot}/levelPercentage with double type. Battery level estimated percentage [0.0%-100.0%]
  • /%{battery_slot}/levelAbsoluteError with double type. Battery level measurement absolute error [0.0-100.0]
  • /%{battery_slot}/status with string type. Battery status string, any of: Charging, Discharging, Idle, EitherIdleOrCharging, Failure, Removed, Unknown

/%{battery_slot}/levelPercentage

Battery level estimated percentage [0.0%-100.0%]

This endpoint accepts values of type double: a double-precision floating-point number as specified by binary64, by the IEEE 754 standard.

The endpoint is parametric and battery_slot can be replaced with any valid string to send data on specialized paths.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

/%{battery_slot}/levelAbsoluteError

Battery level measurement absolute error [0.0-100.0]

This endpoint accepts values of type double: a double-precision floating-point number as specified by binary64, by the IEEE 754 standard.

The endpoint is parametric and battery_slot can be replaced with any valid string to send data on specialized paths.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

/%{battery_slot}/status

Battery status string, any of: Charging, Discharging, Idle, EitherIdleOrCharging, Failure, Removed, Unknown

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The endpoint is parametric and battery_slot can be replaced with any valid string to send data on specialized paths.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

io.edgehog.devicemanager.CellularConnectionProperties v0.1

About

This interface is of type properties and is owned by the device, meaning that it is the device which initiates the data flow. Thanks to this type of interface, the device can set a persistent, stateful, synchronized state with no concept of history or timestamping.

Mappings

The interface has the following mappings:

  • /%{id}/apn with string type. Operator apn address.
  • /%{id}/imei with string type. The modem IMEI code of the device.
  • /%{id}/imsi with string type. The SIM IMSI code of the device.

/%{id}/apn

Operator apn address.

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The endpoint is parametric and id can be replaced with any valid string to send data on specialized paths.

The value of the property can be unset.

/%{id}/imei

The modem IMEI code of the device.

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The endpoint is parametric and id can be replaced with any valid string to send data on specialized paths.

The value of the property can be unset.

/%{id}/imsi

The SIM IMSI code of the device.

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The endpoint is parametric and id can be replaced with any valid string to send data on specialized paths.

The value of the property can be unset.

io.edgehog.devicemanager.CellularConnectionStatus v0.1

About

This interface is of type datastream and is owned by the device, meaning that it is the device which initiates the data flow. Thanks to this type of interface, the device can send a mutable, ordered stream of data, with no concept of persistent state or synchronization.

Data gets sent with an object aggregation. Astarte expects the owner to send all of the interface's mappings at the same time, packed in a single message.

Mappings

The interface has the following mappings:

  • /%{id}/carrier with string type. Connectivity carrier operator name.
  • /%{id}/cellId with longinteger type. The Cell ID in hexadecimal format, either 16 bit for 2G or 28 bit for 3G or 4G.
  • /%{id}/mobileCountryCode with integer type. The mobile country code (MCC) for the device's home network. Valid range: 0–999.
  • /%{id}/mobileNetworkCode with integer type. The Mobile Network Code for the device's home network. This is the MNC for GSM, WCDMA, LTE and NR. CDMA uses the System ID (SID). Valid range for MNC: 0–999. Valid range for SID: 0–32767.
  • /%{id}/localAreaCode with integer type. Two byte location area code in hexadecimal format.
  • /%{id}/registrationStatus with string type. GSM/LTE registration status. Possible values: [NotRegistered, Registered, SearchingOperator, RegistrationDenied, Unknown, RegisteredRoaming]
  • /%{id}/rssi with double type. Signal strenght of the device in dBm.
  • /%{id}/technology with string type. Access Technology. Possible values [GSM, GSMCompact, UTRAN, GSMwEGPRS, UTRANwHSDPA, UTRANwHSUPA, UTRANwHSDPAandHSUPA, EUTRAN]

/%{id}/carrier

Connectivity carrier operator name.

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The endpoint is parametric and id can be replaced with any valid string to send data on specialized paths.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

/%{id}/cellId

The Cell ID in hexadecimal format, either 16 bit for 2G or 28 bit for 3G or 4G.

This endpoint accepts values of type longinteger: a signed 64 bit integer (please note that longinteger is represented as a string by default in JSON-based APIs.).

The endpoint is parametric and id can be replaced with any valid string to send data on specialized paths.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

/%{id}/mobileCountryCode

The mobile country code (MCC) for the device's home network. Valid range: 0–999.

This endpoint accepts values of type integer: a signed 32 bit integer.

The endpoint is parametric and id can be replaced with any valid string to send data on specialized paths.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

/%{id}/mobileNetworkCode

The Mobile Network Code for the device's home network. This is the MNC for GSM, WCDMA, LTE and NR. CDMA uses the System ID (SID). Valid range for MNC: 0–999. Valid range for SID: 0–32767.

This endpoint accepts values of type integer: a signed 32 bit integer.

The endpoint is parametric and id can be replaced with any valid string to send data on specialized paths.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

/%{id}/localAreaCode

Two byte location area code in hexadecimal format.

This endpoint accepts values of type integer: a signed 32 bit integer.

The endpoint is parametric and id can be replaced with any valid string to send data on specialized paths.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

/%{id}/registrationStatus

GSM/LTE registration status. Possible values: [NotRegistered, Registered, SearchingOperator, RegistrationDenied, Unknown, RegisteredRoaming]

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The endpoint is parametric and id can be replaced with any valid string to send data on specialized paths.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

/%{id}/rssi

Signal strenght of the device in dBm.

This endpoint accepts values of type double: a double-precision floating-point number as specified by binary64, by the IEEE 754 standard.

The endpoint is parametric and id can be replaced with any valid string to send data on specialized paths.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

/%{id}/technology

Access Technology. Possible values [GSM, GSMCompact, UTRAN, GSMwEGPRS, UTRANwHSDPA, UTRANwHSUPA, UTRANwHSDPAandHSUPA, EUTRAN]

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The endpoint is parametric and id can be replaced with any valid string to send data on specialized paths.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

io.edgehog.devicemanager.Commands v0.1

About

This interface is of type datastream and is owned by the server, meaning that it is the server which initiates the data flow. Thanks to this type of interface, the server can send a mutable, ordered stream of data, with no concept of persistent state or synchronization.

Data gets sent with an individual aggregation. Each mapping is treated as an independent value and is managed individually.

Mappings

The interface has the following mappings:

  • /request with string type. Command request. Possible values ['Reboot']

/request

Command request. Possible values ['Reboot']

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when it has been received exactly once by the recipient. Data is discarded if the transport is temporarily uncapable of delivering it.

io.edgehog.devicemanager.ForwarderSessionRequest v0.1

Configuration to open a session with the Edgehog Forwarder from a device to a certain host.

About

This interface is of type datastream and is owned by the server, meaning that it is the server which initiates the data flow. Thanks to this type of interface, the server can send a mutable, ordered stream of data, with no concept of persistent state or synchronization.

Data gets sent with an object aggregation. Astarte expects the owner to send all of the interface's mappings at the same time, packed in a single message.

Mappings

The interface has the following mappings:

  • /request/session_token with string type. The session token thanks to which the device can authenticates itself through Edgehog.
  • /request/port with integer type. The host port the device must connect to.
  • /request/host with string type. The IP address or host name the device must connect to.
  • /request/secure with boolean type. Indicates whether the connection should use TLS, i.e. 'ws' or 'wss' scheme.

/request/session_token

The session token thanks to which the device can authenticates itself through Edgehog.

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 31556952 seconds before it is erased from the database.

/request/port

The host port the device must connect to.

This endpoint accepts values of type integer: a signed 32 bit integer.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 31556952 seconds before it is erased from the database.

/request/host

The IP address or host name the device must connect to.

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 31556952 seconds before it is erased from the database.

/request/secure

Indicates whether the connection should use TLS, i.e. 'ws' or 'wss' scheme.

This endpoint accepts values of type boolean: either true or false, adhering to JSON boolean type.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 31556952 seconds before it is erased from the database.

io.edgehog.devicemanager.ForwarderSessionState v0.1

Information provided by the device about the status of a forwarder session.

About

This interface is of type properties and is owned by the device, meaning that it is the device which initiates the data flow. Thanks to this type of interface, the device can set a persistent, stateful, synchronized state with no concept of history or timestamping.

Mappings

The interface has the following mappings:

  • /%{session_token}/status with string type. Indicates if the device is connecting, or connected to a forwarder session.

/%{session_token}/status

Indicates if the device is connecting, or connected to a forwarder session.

An enum with the following possible values: Connecting | Connected.

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The endpoint is parametric and session_token can be replaced with any valid string to send data on specialized paths.

The value of the property can be unset.

io.edgehog.devicemanager.Geolocation v0.1

Generic Geolocation sampled data.

Geolocation allows geolocation sensors to stream location data, such as GPS data. Values availability depends on what sensors are present on devices and what measurement systems are in use. The id represents a unique identifier for an individual sensor.

About

This interface is of type datastream and is owned by the device, meaning that it is the device which initiates the data flow. Thanks to this type of interface, the device can send a mutable, ordered stream of data, with no concept of persistent state or synchronization.

Data gets sent with an object aggregation. Astarte expects the owner to send all of the interface's mappings at the same time, packed in a single message.

Mappings

The interface has the following mappings:

  • /%{id}/latitude with double type. Sampled latitude value.
  • /%{id}/longitude with double type. Sampled longitude value.
  • /%{id}/altitude with double type. Sampled altitude value.
  • /%{id}/accuracy with double type. Sampled accuracy of the latitude and longitude properties.
  • /%{id}/altitudeAccuracy with double type. Sampled accuracy of the altitude property.
  • /%{id}/heading with double type. Sampled value representing the direction towards which the device is facing.
  • /%{id}/speed with double type. Sampled value representing the velocity of the device.

/%{id}/latitude

Sampled latitude value.

This endpoint accepts values of type double: a double-precision floating-point number as specified by binary64, by the IEEE 754 standard.

The endpoint is parametric and id can be replaced with any valid string to send data on specialized paths.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

/%{id}/longitude

Sampled longitude value.

This endpoint accepts values of type double: a double-precision floating-point number as specified by binary64, by the IEEE 754 standard.

The endpoint is parametric and id can be replaced with any valid string to send data on specialized paths.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

/%{id}/altitude

Sampled altitude value.

This endpoint accepts values of type double: a double-precision floating-point number as specified by binary64, by the IEEE 754 standard.

The endpoint is parametric and id can be replaced with any valid string to send data on specialized paths.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

/%{id}/accuracy

Sampled accuracy of the latitude and longitude properties.

This endpoint accepts values of type double: a double-precision floating-point number as specified by binary64, by the IEEE 754 standard.

The endpoint is parametric and id can be replaced with any valid string to send data on specialized paths.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

/%{id}/altitudeAccuracy

Sampled accuracy of the altitude property.

This endpoint accepts values of type double: a double-precision floating-point number as specified by binary64, by the IEEE 754 standard.

The endpoint is parametric and id can be replaced with any valid string to send data on specialized paths.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

/%{id}/heading

Sampled value representing the direction towards which the device is facing.

This endpoint accepts values of type double: a double-precision floating-point number as specified by binary64, by the IEEE 754 standard.

The endpoint is parametric and id can be replaced with any valid string to send data on specialized paths.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

/%{id}/speed

Sampled value representing the velocity of the device.

This endpoint accepts values of type double: a double-precision floating-point number as specified by binary64, by the IEEE 754 standard.

The endpoint is parametric and id can be replaced with any valid string to send data on specialized paths.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

io.edgehog.devicemanager.HardwareInfo v0.1

General hardware capabilities

About

This interface is of type properties and is owned by the device, meaning that it is the device which initiates the data flow. Thanks to this type of interface, the device can set a persistent, stateful, synchronized state with no concept of history or timestamping.

Mappings

The interface has the following mappings:

  • /cpu/architecture with string type. CPU Architecture
  • /cpu/model with string type. CPU Model Code
  • /cpu/modelName with string type. CPU Model Display Name
  • /cpu/vendor with string type. CPU Vendor
  • /mem/totalBytes with longinteger type. Total RAM quantity (Bytes)

/cpu/architecture

CPU Architecture

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The value of the property cannot be unset.

/cpu/model

CPU Model Code

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The value of the property cannot be unset.

/cpu/modelName

CPU Model Display Name

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The value of the property cannot be unset.

/cpu/vendor

CPU Vendor

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The value of the property cannot be unset.

/mem/totalBytes

Total RAM quantity (Bytes)

This endpoint accepts values of type longinteger: a signed 64 bit integer (please note that longinteger is represented as a string by default in JSON-based APIs.).

The value of the property cannot be unset.

io.edgehog.devicemanager.LedBehavior v0.1

About

This interface is of type datastream and is owned by the server, meaning that it is the server which initiates the data flow. Thanks to this type of interface, the server can send a mutable, ordered stream of data, with no concept of persistent state or synchronization.

Data gets sent with an individual aggregation. Each mapping is treated as an independent value and is managed individually.

Mappings

The interface has the following mappings:

  • /%{led_id}/behavior with string type. Enum describing the behavior of the given led. Possible values: [Blink60Seconds | DoubleBlink60Seconds | SlowBlink60Seconds]

/%{led_id}/behavior

Enum describing the behavior of the given led. Possible values: [Blink60Seconds | DoubleBlink60Seconds | SlowBlink60Seconds]

Blink60Seconds: Blinking DoubleBlink60Seconds: Double blinking SlowBlink60Seconds: Slow blinking

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The endpoint is parametric and led_id can be replaced with any valid string to send data on specialized paths.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Data is considered delivered when it has been received exactly once by the recipient. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

io.edgehog.devicemanager.NetworkInterfaceProperties v0.1

About

This interface is of type properties and is owned by the device, meaning that it is the device which initiates the data flow. Thanks to this type of interface, the device can set a persistent, stateful, synchronized state with no concept of history or timestamping.

Mappings

The interface has the following mappings:

  • /%{iface_name}/macAddress with string type. Normalized physical address. Example value is "00:aa:bb:cc:dd:ee" (always lower case)
  • /%{iface_name}/technologyType with string type. Connection technology. Possible values: [Ethernet, Bluetooth, Cellular, WiFi]

/%{iface_name}/macAddress

Normalized physical address. Example value is "00:aa:bb:cc:dd:ee" (always lower case)

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The endpoint is parametric and iface_name can be replaced with any valid string to send data on specialized paths.

The value of the property can be unset.

/%{iface_name}/technologyType

Connection technology. Possible values: [Ethernet, Bluetooth, Cellular, WiFi]

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The endpoint is parametric and iface_name can be replaced with any valid string to send data on specialized paths.

The value of the property can be unset.

io.edgehog.devicemanager.OSInfo v0.1

About

This interface is of type properties and is owned by the device, meaning that it is the device which initiates the data flow. Thanks to this type of interface, the device can set a persistent, stateful, synchronized state with no concept of history or timestamping.

Mappings

The interface has the following mappings:

  • /osName with string type. Name of the Operating System
  • /osVersion with string type. Version of the Operating System

/osName

Name of the Operating System

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The value of the property cannot be unset.

/osVersion

Version of the Operating System

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The value of the property cannot be unset.

io.edgehog.devicemanager.OTAEvent v0.1

OTA Events sampled data.

Allows to stream OTA Events data, including OTA Update status, its progress, code and internal message.

About

This interface is of type datastream and is owned by the device, meaning that it is the device which initiates the data flow. Thanks to this type of interface, the device can send a mutable, ordered stream of data, with no concept of persistent state or synchronization.

Data gets sent with an object aggregation. Astarte expects the owner to send all of the interface's mappings at the same time, packed in a single message.

Mappings

The interface has the following mappings:

  • /event/requestUUID with string type. OTA Request identifier.
  • /event/status with string type. OTA Update status.
  • /event/statusProgress with integer type. Current OTA Update status progress percentage [0%-100%].
  • /event/statusCode with string type. Status code expands OTA Update status with additional information.
  • /event/message with string type. Contains internal message for status code or empty string otherwise.

/event/requestUUID

OTA Request identifier.

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when it has been received exactly once by the recipient. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 31556952 seconds before it is erased from the database.

/event/status

OTA Update status.

Value is one of the following strings:

  • Acknowledged: the device received an OTA Request.
  • Downloading: an update is in the process of downloading.
  • Deploying: an update is in the process of deploying.
  • Deployed: an update deployed on the device.
  • Rebooting: the device is in the process of rebooting.
  • Success: an update succeeded. This is a final status of OTA Update.
  • Error: an error happened during the update. Also this status can be used to notify about handled errors.
  • Failure: an update failed. This is a final status of OTA Update.

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when it has been received exactly once by the recipient. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 31556952 seconds before it is erased from the database.

/event/statusProgress

Current OTA Update status progress percentage [0%-100%].

Every OTA Update status has own progress that starts from 0 and ends at 100, for example (pairs of "status, progress"): "Downloading, 0", "Downloading, 50", "Downloading, 100", "Deploying, 10", etc.

This endpoint accepts values of type integer: a signed 32 bit integer.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when it has been received exactly once by the recipient. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 31556952 seconds before it is erased from the database.

/event/statusCode

Status code expands OTA Update status with additional information.

Some common status codes are:

  • InvalidRequest: an update request contains incorrect data.
  • UpdateAlreadyInProgress: another update is currently in progress.
  • NetworkError: a network error happened during the update.
  • IOError: a filesystem error happened during the update.
  • InternalError: an internal error happened during the update.
  • InvalidBaseImage: an update failed to apply due to an invalid base image.
  • SystemRollback: a system rollback has occurred.
  • Canceled: an update was canceled.

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when it has been received exactly once by the recipient. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 31556952 seconds before it is erased from the database.

/event/message

Contains internal message for status code or empty string otherwise.

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when it has been received exactly once by the recipient. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 31556952 seconds before it is erased from the database.

io.edgehog.devicemanager.OTARequest v1.0

About

This interface is of type datastream and is owned by the server, meaning that it is the server which initiates the data flow. Thanks to this type of interface, the server can send a mutable, ordered stream of data, with no concept of persistent state or synchronization.

Data gets sent with an object aggregation. Astarte expects the owner to send all of the interface's mappings at the same time, packed in a single message.

Mappings

The interface has the following mappings:

  • /request/operation with string type. OTA Request operation
  • /request/url with string type. File URL
  • /request/uuid with string type. Request identifier

/request/operation

OTA Request operation

Value is one of the following strings:

  • Update: push an OTA update operation.
  • Cancel: cancel an OTA update if it can still be cancelled.

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 31556952 seconds before it is erased from the database.

/request/url

File URL

If the operation is Update, this will contain the URL that can be used to download the Update. If the operation is Cancel, this will be an empty string. Note that the URL will be valid only until the OTA update is active (i.e. it didn't reach a Failure or Success state), after that it's possible that the URL can become invalid.

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 31556952 seconds before it is erased from the database.

/request/uuid

Request identifier

A UUID that uniquely identifies the OTA request. It must be stored when receiving an Update operation so that it can be matched against in case a Cancel operation is received.

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 31556952 seconds before it is erased from the database.

io.edgehog.devicemanager.RuntimeInfo v0.1

About

This interface is of type properties and is owned by the device, meaning that it is the device which initiates the data flow. Thanks to this type of interface, the device can set a persistent, stateful, synchronized state with no concept of history or timestamping.

Mappings

The interface has the following mappings:

  • /name with string type. Name of the Edgehog runtime. Example value: edgehog-esp32-device
  • /url with string type. URL that uniquely identifies the Edgehog Edgehog runtime implementation. Example value: https://github.com/edgehog-device-manager/edgehog-esp32-device.
  • /version with string type. Version of the Edgehog runtime. Example value: 0.5
  • /environment with string type. Environment of the Edgehog runtime. Example value: esp-idf VERSION, Rust 1.58 or Java 8

/name

Name of the Edgehog runtime. Example value: edgehog-esp32-device

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The value of the property cannot be unset.

/url

URL that uniquely identifies the Edgehog Edgehog runtime implementation. Example value: https://github.com/edgehog-device-manager/edgehog-esp32-device.

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The value of the property cannot be unset.

/version

Version of the Edgehog runtime. Example value: 0.5

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The value of the property cannot be unset.

/environment

Environment of the Edgehog runtime. Example value: esp-idf VERSION, Rust 1.58 or Java 8

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The value of the property cannot be unset.

io.edgehog.devicemanager.StorageUsage v0.1

About

This interface is of type datastream and is owned by the device, meaning that it is the device which initiates the data flow. Thanks to this type of interface, the device can send a mutable, ordered stream of data, with no concept of persistent state or synchronization.

Data gets sent with an object aggregation. Astarte expects the owner to send all of the interface's mappings at the same time, packed in a single message.

Mappings

The interface has the following mappings:

  • /%{label}/totalBytes with longinteger type. Total storage size in bytes
  • /%{label}/freeBytes with longinteger type. Available storage bytes

/%{label}/totalBytes

Total storage size in bytes

This endpoint accepts values of type longinteger: a signed 64 bit integer (please note that longinteger is represented as a string by default in JSON-based APIs.).

The endpoint is parametric and label can be replaced with any valid string to send data on specialized paths.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

/%{label}/freeBytes

Available storage bytes

This endpoint accepts values of type longinteger: a signed 64 bit integer (please note that longinteger is represented as a string by default in JSON-based APIs.).

The endpoint is parametric and label can be replaced with any valid string to send data on specialized paths.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

io.edgehog.devicemanager.SystemInfo v0.1

Information about the system

About

This interface is of type properties and is owned by the device, meaning that it is the device which initiates the data flow. Thanks to this type of interface, the device can set a persistent, stateful, synchronized state with no concept of history or timestamping.

Mappings

The interface has the following mappings:

  • /serialNumber with string type. The serial number of the system
  • /partNumber with string type. The part number of the system

/serialNumber

The serial number of the system

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The value of the property cannot be unset.

/partNumber

The part number of the system

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The value of the property cannot be unset.

io.edgehog.devicemanager.SystemStatus v0.1

About

This interface is of type datastream and is owned by the device, meaning that it is the device which initiates the data flow. Thanks to this type of interface, the device can send a mutable, ordered stream of data, with no concept of persistent state or synchronization.

Data gets sent with an object aggregation. Astarte expects the owner to send all of the interface's mappings at the same time, packed in a single message.

Mappings

The interface has the following mappings:

  • /systemStatus/availMemoryBytes with longinteger type. Available memory (Bytes)
  • /systemStatus/bootId with string type. UUID representing the Boot Id
  • /systemStatus/taskCount with integer type. Number of running tasks or processes
  • /systemStatus/uptimeMillis with longinteger type. Get time in milliseconds since boot

/systemStatus/availMemoryBytes

Available memory (Bytes)

This endpoint accepts values of type longinteger: a signed 64 bit integer (please note that longinteger is represented as a string by default in JSON-based APIs.).

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

/systemStatus/bootId

UUID representing the Boot Id

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

/systemStatus/taskCount

Number of running tasks or processes

This endpoint accepts values of type integer: a signed 32 bit integer.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

/systemStatus/uptimeMillis

Get time in milliseconds since boot

This endpoint accepts values of type longinteger: a signed 64 bit integer (please note that longinteger is represented as a string by default in JSON-based APIs.).

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

io.edgehog.devicemanager.WiFiScanResults v0.2

About

This interface is of type datastream and is owned by the device, meaning that it is the device which initiates the data flow. Thanks to this type of interface, the device can send a mutable, ordered stream of data, with no concept of persistent state or synchronization.

Data gets sent with an object aggregation. Astarte expects the owner to send all of the interface's mappings at the same time, packed in a single message.

Mappings

The interface has the following mappings:

  • /ap/channel with integer type. The channel over which the client is communicating with the access point.
  • /ap/connected with boolean type. Identifies if the device is connected to this Access Point
  • /ap/essid with string type. Extended Service Set Identification of the current AP, empty string if the AP is hidden.
  • /ap/macAddress with string type. Lower case mac address string formatted like de:ad:be:ff:11:22.
  • /ap/rssi with integer type. The current signal strength measured in dBm.

/ap/channel

The channel over which the client is communicating with the access point.

The channel represents one of the ranges into which the reference frequency is divided and it's identified by an integer number in the range 1 - 165, depending on the frequency itself and the region.

This endpoint accepts values of type integer: a signed 32 bit integer.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

/ap/connected

Identifies if the device is connected to this Access Point

This endpoint accepts values of type boolean: either true or false, adhering to JSON boolean type.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

/ap/essid

Extended Service Set Identification of the current AP, empty string if the AP is hidden.

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

/ap/macAddress

Lower case mac address string formatted like de:ad:be:ff:11:22.

This endpoint accepts values of type string: an UTF-8 string, at most 65536 bytes long.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

/ap/rssi

The current signal strength measured in dBm.

This endpoint accepts values of type integer: a signed 32 bit integer.

The endpoint has a specific configuration for how data is stored, transferred and indexed. Astarte expects a valid timestamp to be attached each time data is produced. Data is considered delivered when the transport successfully sends the data regardless of the outcome. Data is discarded if the transport is temporarily uncapable of delivering it. Delivered data is kept for 5184000 seconds before it is erased from the database.

io.edgehog.devicemanager.config.Telemetry v0.1

About

This interface is of type properties and is owned by the server, meaning that it is the server which initiates the data flow. Thanks to this type of interface, the server can set a persistent, stateful, synchronized state with no concept of history or timestamping.

Mappings

The interface has the following mappings:

  • /request/%{interface_name}/enable with boolean type. Enable/Disable telemetry update. Unset returns to the previous state configured in the device.
  • /request/%{interface_name}/periodSeconds with longinteger type. Set interval of period seconds between the end of the previous update and the start of the next one. Unset returns to the previous state configured in the device.

/request/%{interface_name}/enable

Enable/Disable telemetry update. Unset returns to the previous state configured in the device.

This endpoint accepts values of type boolean: either true or false, adhering to JSON boolean type.

The endpoint is parametric and interface_name can be replaced with any valid string to send data on specialized paths.

The value of the property can be unset.

/request/%{interface_name}/periodSeconds

Set interval of period seconds between the end of the previous update and the start of the next one. Unset returns to the previous state configured in the device.

This endpoint accepts values of type longinteger: a signed 64 bit integer (please note that longinteger is represented as a string by default in JSON-based APIs.).

The endpoint is parametric and interface_name can be replaced with any valid string to send data on specialized paths.

The value of the property can be unset.