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

Steps

1. Build the agent

   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": "http://<your-server-ip>:8000/api/devices",
       "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 URL of the OTA-Pulse backend, including /api/devices
   RootfsPartA / RootfsPartB	Block device paths for your A and B root partitions
   SoCAPIKey	An API key generated in the console under Settings → API Keys
   SoCDeviceID	A stable unique identifier for this device (e.g. MAC address or hardware serial)

   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

   Navigate to http://localhost:3000/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 from the command line:

   curl -s http://localhost:8000/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 http://<server-ip>:8000/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 →