Pico Agent CoAP Protocol Adapter
This section presents configuration options and functionalities of the Pico Agent Protocol Adapter, which enables connecting a Pico Agent application to the relayr Gateway Agent with the use of CoAP (Constrained Application Protocol).
For a step-by-step guide on how to install the Pico Adapter, see the Installation Guide.
For more information on how to create a Pico Agent, see the Pico Agent Development Guide.
Configuring the Pico Adapter
There are two configuration files of the Pico Adapter:
Deployment configuration file - Configuration of the MQTT connection and health monitoring.
Application configuration file - Configuration of CoAP connections to Pico Agents, security settings and devices configuration.
When you modify the Pico Adapter configuration, restart the adapter to apply the changes by means of the following command:
systemctl restart gwa-pico-agent-coap-adapter-c
The adapter configuration is then updated.
For an example of Pico Adapter configuration files, see here.
Deployment Configuration File
The deployment configuration file of the Pico Agent CoAP Adapter is located at:
/etc/relayr/gwa-pico-agent-coap-adapter-c/gwa-pico-agent-coap-adapter-config.json
To modify the file, edit it in a text editor.
The following configuration settings are available:
mqtt_connection
- Connection settings of the MQTT message broker:
Configuration Setting | Description | Default Value |
---|---|---|
host | IP address of the MQTT message broker. | localhost |
port | Port number for connecting to the MQTT broker. | 1883 |
keepalive | Keepalive value of the MQTT connection. | 20 |
max_inflight_messages | Maximum number of QoS 1 or 2 messages that can be in the process of being transmitted simultaneously. This includes messages currently going through handshakes and messages that are being retried. If set to 1 , it guarantees an in-order delivery of messages. | 100 |
qos_levels | Quality of Service level for each traffic type. | measurements: 0 , alerts: 1 . configuration: 1 , metadata: 1 |
health_monitor
- Health monitoring settings:
Configuration Setting | Description | Default Value |
---|---|---|
heartbeat_interval | Time interval at which the periodic heartbeat messages are sent, given in seconds. | 60 |
For an example of the deployment configuration file, see here.
Application Configuration File
The application configuration file of the Protocol Adapter is located at:
/etc/relayr/gwa-pico-agent-coap-adapter-c/gwa-pico-agent-coap-adapter-application-config.json
If you have the Configuration Manager installed, it becomes the primary way of editing application configuration files. If you do not have the Configuration Manager, edit the application configuration file in a text editor.
The file contains the following settings:
coap.max_retransmission
- A number of CoAP transmission retries if there is no response. By default,2
.complex_measurement
- Settings related to the reporting of complex measurements:
Configuration Setting | Description | Default Value |
---|---|---|
retry_count | Number of times that the adapter retries to get a complex measurement resource from a Pico device. | 3 |
retry_interval_ms | Time interval, given in milliseconds, at which the adapter retries to get a complex measurement resource from a Pico device. | 556 |
connection.limit
- A maximum number of connected Pico devices. By default,10
.connection.connections_list
- Connections to Pico devices. For each configured connection, define the following settings:
Configuration Setting | Description | Default Value |
---|---|---|
host | IP address on which the Pico Adapter listens for incoming Pico Agent connections. Both IPv4 and IPv6 are supported. If set to 0.0.0.0 , the adapter listens on all available addresses. | 0.0.0.0 |
port | Port number on which the Pico Adapter listens for incoming Pico Agent connections. | 5683 |
security | Optional setting. Identifier of the security configuration used by the adapter. This ID must me mapped to the identifier provided in the security section of the configuration file (see below for details). If left empty, no security is used. For more information, see the Security Configuration section. | "" |
security
- Security configuration options. For more information and examples, see the Security Configuration section. For each configured security, the following settings are available:
Configuration Setting | Description |
---|---|
id | Identifier of the security configuration. Mandatory setting. To use this security configuration, enter this identifier in the security setting of the connections_list section (see above). |
certificate | Path to the X.509 certificate file of the adapter. |
private_key | Path to the X.509 private key. If you don't have a separate certificate file, the private_key may contain a path to a private key with a certificate. |
private_key_password_file | Path to the file with a password to the adapter's X.509 private key. If the private key doesn't have a password, leave this setting empty. |
ca_file | Path to the X.509 certificate authority file with trusted certificates checked by the adapter when it verifies the device's certificate. |
psk_file | Path to the pre-shared key file. |
devices
- Mapping of the device ID (did
) and the device UUID from the relayr Cloud (uuid
). See the Mapping of Device DID and UUID section for more information.
Configuration Setting | Description | Example of Value |
---|---|---|
uuid | Device unique identifier in the relayr Cloud. This UUID is automatically generated when the device is created in the Cloud. | "f33c6bah-b31e-4f5a-964h-13a935a8b25f" |
did | Device unique identifier. This ID is usually a MCU serial number of a Pico device. You can read it from the Pico Agent's logs. | "12345678" |
custom_prefix
- Optional setting. See below for details.pico_time_sync
- Optional configuration section, which lets you configure the time synchronization settings:
Configuration Setting | Description | Example of Value |
---|---|---|
resource_active | If set to true , the adapter handles the time synchronization of Pico devices by enabling the actual time as a CoAP /time resource. Using a GET command, a device can obtain the Epoch time in milliseconds. Configure this setting if there is no NTP server available, which is the default way of the time synchronization for Pico devices. | true |
report_setup_observe_messages | If set to false , the adapter blocks the reporting of messages from GET with observe responses on MQTT (messages that do not have the proper Epoch time). | false |
Custom Prefix
In the application configuration file, you can optionally configure a custom prefix, which determines where to report data. If not defined, all data is reported to v1/sb
, by default.
The custom_prefix
option enables setting a different prefix to publish data e.g. to a custom MQTT topic for local data processing, or directly to the Gateway Agent northbound interface.
Example:
"custom_prefix": "v1/nb"
Security Configuration
The Pico Adapter allows you to configure a secure connection to Pico devices. Two security types are supported:
Security with a PSK (pre-shared key)
Public-key cryptography based on X.509 certificates (RSA, ECDSA)
You can configure the security settings in the security
section of the application configuration file of the Pico Adapter.
Depending on the security type you want to use (PSK, X.509 or both), you need to include a different set of settings. See below for examples of security configuration.
The security configuration is optional.
Examples of Security Configuration
- No security. If you don't want to configure a secure connection, you can:
- leave the
security
setting empty in theconnections_list
section. - not include the
security
setting at all for a given connection. - configure a security object with the
id
only, without any other settings, e.g.:
- leave the
"security":
[
{
"id": "no_sec"
}
Remember to include the same
id
for a given connection in theconnections_list
configuration.
- Security with both PSK and X.509 RSA:
{
"id": "sec_rsa_psk",
"certificate": "",
"private_key": "./examples/security/rsa/rsa_certkey.pem",
"private_key_password_file": "./examples/security/rsa/rsa_pass",
"ca_file": "./examples/security/rsa/rsa_trusted_certs.pem",
"psk_file": "./examples/security/psk/psk_key"
}
- Security with both PSK and X.509 ECC:
{
"id": "sec_ecc_psk",
"certificate": "",
"private_key": "./examples/security/ecc/ecc_certkey.pem",
"private_key_password_file": "./examples/security/ecc/ecc_pass",
"ca_file": "./examples/security/ecc/ecc_trusted_certs.pem",
"psk_file": "./examples/security/psk/psk_key"
}
- Security with PSK:
{
"id": "sec_psk",
"psk_file": "./examples/security/psk/psk_key"
}
Mapping of Device DID and UUID
For Pico devices, you need to map their UUIDs from the relayr Cloud to their DIDs.
A UUID identifies a device in the relayr Cloud. This identifier is assigned automatically when you create a device in the Cloud, e.g. 82d2695d-a552-4764-88fd-0d3ea4ab981g
. For more information on creating devices, refer to the relayr Cloud API documentation.
A DID is a device unique identifier (usually an MCU serial number). You can view it in the Pico Agent's logs after starting the device.
If you do not configure the mapping, the Pico Adapter assumes that DID is equal to UUID and uses DID for communication up to the Cloud.
You do not need to configure the mapping only if the Pico Agent running on the device has the UUID explicitly given as its DID in its application code.
To map the device UUID and DID identifiers, configure them in the devices
section of the application configuration file, e.g.:
"devices": [
{
"uuid": "f33c6bah-b31e-4f5a-964h-13a935a8b25f",
"did": "1234567"
}
]
Support for Firmware Upgrade
The Pico Adapter supports remote firmware upgrades of the Pico Agent. A firmware upgrade involves changing the application logic or configuration on a device. New firmware often fixes bugs, contains new features, and protects you from security vulnerabilities.
See below for a list of requirements for the Pico firmware upgrade and a detailed description of the process.
Requirements
Your Pico Agent application must support firmware upgrades. For details, see the Pico SDK Firmware Upgrade documentation.
Gateway Agent's Task Executor must include a
.lua
script for processing firmware installation tasks. For an example of such a script, see here.Firmware upgrade must be defined in the relayr Cloud. For more information, see the relayr Cloud API documentation.
Steps
Firmware upgrade of the Pico Agent has the following stages:
The relayr Cloud operator applies new firmware to Pico devices.
The Gateway Agent receives the firmware upgrade task.
The task processing is governed by the Task Executor. It downloads the firmware file to the local Gateway Agent's storage and transfers the task to the southbound interface. On the southbound interface, the task is handled by the Pico Adapter.
- The Pico Adapter transmits the task to the Pico Agent.
The Pico device receives a URL to the firmware file exposed by the Pico Adapter. The device downloads the file from the Gateway Agent's storage in chunks (64 B each).
The Pico device receives the task and starts to download new firmware only when it is active, i.e. it has woken up from the suspension mode and sent an update message to the Pico Adapter.
- The Pico Agent reports the firmware upgrade result to the Pico Adapter.
As defined in the Task Executor's
.lua
script, the result is then reported from the southbound interface to the northbound one.
- The Gateway Agent reports the firmware upgrade result to the relayr Cloud.
Support for Complex Measurements
A complex measurement is a batch of measurement data, in which several samples of collected data values are published as a single message. The support for complex measurements in the Pico Adapter allows you to work with high-frequency (10kHz+) data acquisition sensors on Pico-enabled platforms. The Pico Adapter is able to receive such high frequency data from Pico devices and then publish it as a complex measurement message.
For details on enabling complex measurements on Pico devices, see the Pico SDK documentation.
To report a complex measurement, a Pico device collects data from sensors and then transfers it to the Pico Adapter in blocks, typically 64 B each. When the Pico Adapter receives all data blocks, it combines them into a complex measurement:
- It converts the received measurement values to the data
type
reported by the Pico device. - It publishes the acquired values as a complex measurement message.
In a complex measurement message:
startTs
is a moment when data acquisition begins.endTs
is a moment when data acquisition finishes.xStart
is the first value on the X axis. ThexStart
unit depends on the measured value. For measurements in the time domain, it is a timestamp indicating the moment when the first data sample is collected. For measurements in the frequency domain, it is the first frequency on the X axis.xStep
represents a resolution of data on the X axis. For measurements in the time domain,xStep
is a time interval between consecutive data samples, given in milliseconds, which allows you to know the precise moment when each data sample was collected. For measurements in the frequency domain,xStep
represents the frequency resolution of data representation on the X axis.yValues
is an array of ordered measurement values reported by the Pico device.
Example 1: time-based measurement:
v1/sb/{UUID}/complex_measurements/temperature {
“id”:“temperature”,
“startTs”: 1492515087123,
“endTs”: 1492515092123,
“xStart”: 1492515087123,
“xStep”: 1000,
“yValues”: [42, 43, 39, 37, 40, 48, 45, 40, 38, 33, 30, 31...]
}
In this example,
temperature
is a time-based measurement. ThexStart
value is1492515087123
, which shows the moment when the first data sample (42
) was collected. ThexStep
value is1000
, which means that consecutive data samples were collected at the interval of 1000 milliseconds.
Example 2: frequency-based measurement:
v1/sb/{UUID}/complex_measurements/acceleration_xaxis_fft {
“id”:“acceleration_xaxis_fft”,
“startTs”: 1492515087123,
“endTs”: 1492515092123,
“xStart”: 90,
“xStep”: 10,
“yValues”: [3, 12, 48, 579, 644, 689, 711, 647, 78, 644, 669, 112, 638, 652, 617, 48...]
}
In this example,
acceleration_xaxis_fft
is a frequency-based measurement. ThexStart
value is90
, which shows that the first frequency on the X axis is 90 Hz. ThexStep
value is10
, which means that the frequency step on the X axis, between consecutive data samples, is 10 Hz.
Session Sustain Mechanism
For receiving complex measurements, the Pico Adapter provides a session sustain mechanism.
Each complex measurement has its unique CoAP ETag. While downloading a complex measurement, the adapter saves its CoAP ETag, payload, and block number.
If the Pico Agent restarts during sending a complex measurement (sending another registration message), and tries to send the same complex measurement, with the same CoAP ETag, the adapter starts downloading the complex measurement from the block last saved.
If another complex measurement with a different ETag has arrived in the meantime of the restart, the adapter isn't able to resume downloading the previous one.
Examples of Configuration Files
Deployment Configuration File
{
"mqtt_connection": {
"host": "localhost",
"port": 1883,
"keepalive": 20,
"max_inflight_messages": 100,
"qos_levels": {
"measurements": 0,
"alerts": 1,
"configuration": 1,
"metadata": 1
}
},
"health_monitor": {
"heartbeat_interval": 60
}
}
Application Configuration File
{
"coap":
{
"max_retransmission": 2
},
"pico_time_sync":
{
"report_setup_observe_messages": false,
"resource_active": true
},
"complex_measurement":
{
"retry_count": 3,
"retry_interval_ms": 556
},
"connection":
{
"limit": 10,
"connections_list":
[
{
"host": "0.0.0.0",
"port": 5683
},
{
"host": "0.0.0.0",
"port": 5684,
"security": "sec_rsa_psk"
},
{
"host": "0.0.0.0",
"port": 5685,
"security": "sec_ecc_psk"
},
{
"host": "0.0.0.0",
"port": 5686,
"security": "sec_psk"
}
]
},
"security":
[
{
"id": "sec_rsa_psk",
"certificate": "",
"private_key": "./examples/security/rsa/rsa_certkey.pem",
"private_key_password_file": "./examples/security/rsa/rsa_pass",
"ca_file": "./examples/security/rsa/rsa_trusted_certs.pem",
"psk_file": "./examples/security/psk/psk_key"
},
{
"id": "sec_ecc_psk",
"certificate": "",
"private_key": "./examples/security/ecc/ecc_certkey.pem",
"private_key_password_file": "./examples/security/ecc/ecc_pass",
"ca_file": "./examples/security/ecc/ecc_trusted_certs.pem",
"psk_file": "./examples/security/psk/psk_key"
},
{
"id": "sec_psk",
"psk_file": "./examples/security/psk/psk_key"
}
],
"devices":
[
{
"uuid": "f33c6bah-b31e-4f5a-964h-13a935a8b25f",
"did": "1234567"
}
]
}