Register your first device

The OTA agent (soc-ota-agent) runs on your target device. It polls the OTA-Pulse backend for pending deployments, downloads firmware artifacts, writes them to the inactive partition, and reboots into the new image. This page explains how to build or obtain the agent, deploy it to a device, and confirm registration.

System requirements

Requirement	Minimum
CPU	ARM or x86_64
RAM	512 MB
Storage	Dual root partitions (A/B layout)
OS	Linux with systemd and kernel 4.x+
Network	IP connectivity to the OTA-Pulse backend

How a device gets its credentials

A device needs a device API key to talk to the backend. There are two ways to get one onto it.

Provisioning token (recommended). In the console, open Provisioning in the sidebar and create a fleet provisioning token (spt_...). Copy it when it is shown. On a device built with the Yocto layer, the otapulse-auto-provision service runs at boot. It reads OTAPULSE_PROVISIONING_TOKEN from /etc/otapulse/provision.env, registers the device with the backend, and receives a unique API key for it. It saves SoCAPIKey and SoCDeviceID to the persistent configuration file and restarts the agent. No recipe writes provision.env for you, so your image or provisioning process must place it. See Install the agent and the End-to-end quickstart.

Device API key. In the console, open API Keys in the sidebar and create a key (smk_...). Put it in the device’s configuration as SoCAPIKey. This is the path for a manual install, which has no first-boot provisioning service, and it is what the steps below use.

Both paths use the same agent settings: UseSoCMonitoring set to true, plus SoCAPIKey and SoCDeviceID. The configuration is split across two files, and a device that installs updates by A/B slot switch reads both. See Configuration files.

Steps

1. Build the agent

   For production devices, add the agent through the Yocto layer or the Buildroot external tree instead. See Install the agent. The steps below install the agent by hand, which suits development devices and VMs.

   The agent is written in Go. Build it from the soc-ota-agent/ directory in the repository:

   cd ota-pulse/soc-ota-agent
   make build

   This produces a statically linked otapulse binary in the project root. Alternatively, if you use Yocto, the agent is already packaged as a recipe:

   # In your Yocto build environment
   IMAGE_INSTALL:append = " soc-ota-agent"
   bitbake soc-monitoring-image

   The Yocto path bakes the agent, its config directory, and the systemd service unit directly into your image — skip steps 2–4 below if you take that route.

2. Copy the agent to the device

   Copy the binary over SSH:

   scp otapulse user@<device-ip>:/tmp/soc-ota-agent
   ssh user@<device-ip> "sudo install -m 0755 /tmp/soc-ota-agent /usr/bin/soc-ota-agent"

3. Write the configuration

   Create the config directory and write /etc/otapulse/otapulse.conf on the device:

   ssh user@<device-ip> "sudo mkdir -p /etc/otapulse"

   Then place the following JSON at /etc/otapulse/otapulse.conf, filling in your values:

   {
       "ServerURL": "https://<your-server>",
       "RootfsPartA": "/dev/disk/by-partlabel/rootfs_a",
       "RootfsPartB": "/dev/disk/by-partlabel/rootfs_b",
       "UpdatePollIntervalSeconds": 1800,
       "InventoryPollIntervalSeconds": 28800,
       "RetryPollIntervalSeconds": 300,
       "RetryPollCount": 10,
       "StateScriptTimeoutSeconds": 600,
       "ModuleTimeoutSeconds": 14400,
       "SkipVerify": false,
       "UseSoCMonitoring": true,
       "SoCAPIKey": "<paste-from-console>",
       "SoCDeviceID": "<your-device-id>",
       "ArtifactVerifyKeys": [
           "/etc/soc-monitoring/signing-keys/active/production-rsa-public.pem",
           "/etc/soc-monitoring/signing-keys/active/production-ecdsa-public.pem"
       ]
   }

   Optional fields shown in examples/soc-monitoring-otapulse.conf can be added if you need them.

   Field	What to put here
   ServerURL	The bare URL of the OTA-Pulse backend — the agent appends /api/devices/... itself; including that suffix here causes a doubled path
   RootfsPartA / RootfsPartB	Block device paths for your A and B root partitions
   SoCAPIKey	A device API key generated in the console from API Keys in the sidebar
   SoCDeviceID	A stable unique identifier for this device (e.g. MAC address or hardware serial)

   Note

   A device that installs root filesystem updates boots the new image’s own copy of /etc/otapulse/otapulse.conf. Settings you wrote here are not carried over. The agent also reads a persistent file named otapulse.conf in the directory given by the OTAPULSE_DATASTORE_DIR environment variable (default /var/lib/otapulse). Yocto images set it to /data/otapulse, on the data partition. Credentials kept there survive an update, as long as the directory is on a partition that updates leave alone. See Configuration files.

   Tip

   For a quick test on a VM without dual partitions, set "SkipVerify": true and point both RootfsPartA and RootfsPartB to the same device. The agent will register and report telemetry; the deployment install step will fail, but you can still verify registration and monitoring.

4. Install the systemd service

   Copy the unit file from the repository:

   scp ota-pulse/soc-ota-agent/support/soc-ota-agent.service \
       user@<device-ip>:/tmp/
   ssh user@<device-ip> \
       "sudo cp /tmp/soc-ota-agent.service /etc/systemd/system/ && \
        sudo systemctl daemon-reload && \
        sudo systemctl enable soc-ota-agent && \
        sudo systemctl start soc-ota-agent"

5. Verify the device appears in the console

   Open Devices in the console. Within about 30 seconds of starting the agent, your device should appear with an online status badge.

   You can also check that the backend is reachable from the device:

   curl -s https://<your-server>/health

Quick troubleshooting

If the device does not appear online after 60 seconds, check these first:

• Service not running: sudo systemctl status soc-ota-agent on the device — look for config file errors.
• Network blocked: Run curl https://<your-server>/health from the device to confirm the backend is reachable. Check any firewalls between the device and the server.
• Clock skew: JWT tokens carry timestamps. If the device clock is more than a few minutes off, authentication will fail. Ensure NTP is running: sudo systemctl start systemd-timesyncd.
• Agent logs: sudo journalctl -u soc-ota-agent -f shows real-time output.

Next: Ship your first update

With a device registered and online, you’re ready to upload firmware and deploy it.

Ship your first update →