Device Configuration

This guide explains how to configure devices remotely using Nexigon device properties.

What are device properties? Device properties are key-value pairs attached to devices that store arbitrary JSON data. They can be protected (read-only for devices) or unprotected (readable and writable by devices).

Device properties serve as a flexible mechanism to store and manage device configuration remotely. For instance, protected properties can be used to enable and disable certain features of a device or configure hardware peripherals, including numerical and other complex JSON-based configurations. Beyond remote configuration, device properties can also be used to track device state and store inventory information (e.g., serial numbers).

Declarative Configuration

A common pattern is to define the desired device state in a property and have a script on the device periodically reconcile the actual device configuration with the desired state. This declarative approach ensures devices converge to the desired configuration, even after reboots or temporary failures.

Example: Configuring a Sensor Service

Define the desired configuration in a protected property via the UI or CLI:

nexigon-cli devices properties set --protected <device-id> com.example.sensor.config \
  '{"sample_rate_hz": 10, "enabled_channels": ["temperature", "humidity"]}'

Create a configuration script on the device that reads the property and applies the configuration:

/usr/local/bin/apply-sensor-config.sh
#!/usr/bin/env bash

set -euo pipefail

CONFIG=$(nexigon-agent device properties get com.example.sensor.config)

# Atomic write using `mv` for robustness against power failures.
echo "$CONFIG" >/etc/sensor-service/config.json.tmp
mv /etc/sensor-service/config.json.tmp /etc/sensor-service/config.json

systemctl reload sensor-service

Run the script periodically using a Systemd timer or cron job:

/etc/systemd/system/apply-sensor-config.service
[Unit]
Description=Apply Sensor Service Configuration
Requires=network.target
After=network.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/apply-sensor-config.sh

[Install]
WantedBy=multi-user.target

/etc/systemd/system/apply-sensor-config.timer
[Unit]
Description=Apply Sensor Service Configuration Timer

[Timer]
OnBootSec=1min
OnUnitInactiveSec=5min
Persistent=true

[Install]
WantedBy=timers.target

With this approach, you can update the configuration from the cloud and the device will automatically apply it within the polling interval. This approach also gives you full flexibility for how to apply configurations.

tip

Want feedback about the currently applied configuration and telemetry regarding the configuration application? Use an additional unprotected property com.example.sensor.state to report the sensor service state back to the cloud and have the configuration script emit events about it's progress.

To avoid conflicts, we recommend using domain prefixes for properties. In particular, dev.nexigon is reserved for properties defined by Nexigon itself (e.g., system and OTA update information).

Declarative Configuration​

Declarative Configuration