Update Debian Packages in your IoT using SocketXP OTA Update

In this article, we will show you how to build and update an IoT application as a debian package on a fleet of IoT devices using SocketXP’s Over-the-Air(OTA) update feature.

SocketXP is an IoT device management platform that can be used to remotely manage, monitor, access, update and control IoT or any embedded Linux devices at massive scale.

SocketXP’s OTA update feature is extremely useful when you have to deploy software update on a fleet of IoT devices in your customer’s network behind a NAT router or Firewall or out in the field connected via a cellular network.

The OTA update feature can be used to update the following types of artifacts:

• Firmware
• Software packages (Debian, RPM)
• Application binaries
• Docker containers
• Program files
• Config files
• Execute a script or command

on multiple remote devices.

Creating and Deploying OTA Updates

Creating and deploying OTA updates using the tool is a two step process:

1. Create and upload an artifact (debian pkg) to the SocketXP Artifact Registry
2. Deploy the artifact on a group of devices

The basic concept behind this two-step approach is to reuse the uploaded artifact to deploy OTA updates on different group of devices.

Simple IoT App Example:

We will be using a simple C program to demonstrate SocketXP’s OTA update capabilities. We will build a debian package using the compiled C program binary.

Note: We are using a C program for our example but the IoT app can be created using any programming language or script. Eg: Java, C++, Golang, Python, Javascript, C# etc.

The app will print “Hello, OTA update!” every 10 minutes.

We also assume that the app is running as a Linux systemd service in the IoT devices.

/*
 * To build: gcc myapp.c -o myapp
 * To run: ./myapp
 * Output: "Hello, OTA update!"
 */

#include <stdio.h>
#include <unistd.h> 

int main() {
    while (1) {
        printf("Hello, OTA update!\n");
        fflush(stdout); // Ensure immediate output
        sleep(600); // in seconds
    }
    return 0;
}

The above C program, the build script and the debian package build scripts we will use for this demo can be downloaded from our official git repository here:

Build the App Binary

First, let’s clone the git repository using the link provided above:

$ git clone https://github.com/ampaslabs/ota-update-build-artifacts

For this exercise, we will use the example in the debian_pkg folder. So let’s get into the debian_pkg folder.

 ~/$ cd ota-update-build-artifacts/debian_pkg

Let’s look into the contents of the debian_pkg folder.

/ota-update-build-artifacts/debian_pkg$ ls 
make_artifact.sh    myapp/			update.sh

~/ota-update-build-artifacts/debian_pkg$ ls myapp/
debian/		makefile	myapp.c

~/ota-update-build-artifacts/debian_pkg$ ls myapp/debian/
control		myapp.service	postinst	postrm		prerm

The debian_pkg folder contains the following three items:

1. A myapp folder containing our app code written in the the C language and a makefile to compile the app and build a debian package using the app binary. The myapp folder also includes a debian folder that has necessary scripts required to install and configure the app binary as a debian package on the target device.
2. An update.sh shell script – the workflow script that runs in the target devices and updates the myapp debian package.
3. A make_artifact.sh shell script – a packaging script that creates a tar.gz zipped archive file containing the above two items: the debian package containing the myapp binary and the update.sh script file. We call the tar.gz file as an artifact that can be uploaded to the SocketXP cloud artifact registry.

Create a New Version of the App:

Let’s get into the myapp directory and start building our app.

Before we do that, we will edit the myapp.c file and make it to print "Hello, OTA update! Version 1.0.0". Let’s call it as the version 1.0.0 of the app.

/*
 * To build: gcc myapp.c -o myapp
 * To run: ./myapp
 * Output: "Hello, OTA update!"
 */

#include <stdio.h>
#include <unistd.h> 

int main() {
    while (1) {
        printf("Hello, OTA update! Version 1.0.0\n");
        fflush(stdout); // Ensure immediate output
        sleep(600); // in seconds
    }
    return 0;
}

Next build the app and package it as a debian package using the "make all" command.

$ cd myapp
$ make all
++ Building myapp
gcc myapp.c -o myapp
++ Building Debian package
rm -rf debian_build
mkdir -p debian_build/myapp_1.0.0
mkdir -p debian_build/myapp_1.0.0/usr/bin
cp myapp debian_build/myapp_1.0.0/usr/bin
mkdir -p debian_build/myapp_1.0.0/etc/systemd/system
cp debian/myapp.service debian_build/myapp_1.0.0/etc/systemd/system
mkdir -p debian_build/myapp_1.0.0/DEBIAN
cp debian/postinst debian_build/myapp_1.0.0/DEBIAN
cp debian/prerm debian_build/myapp_1.0.0/DEBIAN
cp debian/postrm debian_build/myapp_1.0.0/DEBIAN
cp debian/control debian_build/myapp_1.0.0/DEBIAN
dpkg-deb --build --root-owner-group debian_build/myapp_1.0.0
dpkg-deb: building package 'myapp' in 'debian_build/myapp_1.0.0.deb'.
root@ubuntu:~/go/src/ota-update-build-artifacts/debian_pkg/myapp# ls
debian  debian_build  makefile  myapp  myapp.c

Now that we have built our app binary and the debian package of the app, we are ready to create a tar.gz style artifact using them.

Why should we create a tar.gz archive file: SocketXP OTA update expects the artifact to be uploaded as a tar.gz archive file containing the app binary and the workflow script update.sh in it. When the artifact is downloaded on the target device, the SocketXP agent running in the device will unzip and extract the tar.gz file contents into the /tmp directory and start executing the update.sh workflow script contained in the myapp_1.0.0 folder.

Let’s go back to the parent directory and execute the make_artifact.sh script.

~/ota-update-build-artifacts/debian_pkg/myapp$ cd ..
~/ota-update-build-artifacts/debian_pkg$ ls
make_artifact.sh  myapp  update.sh
~/ota-update-build-artifacts/debian_pkg$ sh make_artifact.sh 
myapp_1.0.0/
myapp_1.0.0/myapp_1.0.0.deb
myapp_1.0.0/update.sh
~/ota-update-build-artifacts/debian_pkg# ls
make_artifact.sh  myapp  myapp_1.0.0.tar.gz  update.sh

Verify the contents of the tar.gz file built.

$ tar -tf myapp_1.0.0.tar.gz
myapp_1.0.0/
myapp_1.0.0/myapp_1.0.0.deb
myapp_1.0.0/update.sh

Workflow Script - update.sh

The OTA update workflow script contains all the instructions required to update the myapp service running in the IoT devices.

Let’s quickly look at the contents of the update.sh script

#!/bin/bash

#================================================
# MyApp Update Workflow Script
#================================================

# backup the existing app
mv /usr/bin/myapp /usr/bin/myapp.bkup

# update the myapp package
sudo dpkg -i myapp_*.deb

# verify the app is working fine
service_name="myapp"
if systemctl --quiet is-active "$service_name"; then
  echo "$service_name is running."
  # update success
  # clean up the backup and exit
  rm -f /usr/bin/myapp.bkup
else
  echo "$service_name is not running."
  # update failed
  # restore from the backup
  mv /usr/bin/myapp.bkup /usr/bin/myapp
  # start the previous working version
  systemctl start myapp
fi

Explanation:

What the update.sh script does is:

• Creates a backup of the myapp already running in the device
• Installs the debian package containing the new version of the app using the “dpkg -i” command. What the command does is:
  • The “dpkg -i” command will run the “postrm” script in the debian package that will stop the myapp service
  • The “dpkg -i” command will also copy over the new version of myapp to the /usr/bin directory
  • The “dpkg -i” command will run the “postinstall” script in the debian package that will start the myapp service
  • The myapp service will kickstart the new version of the app binary
• Finally, the update.sh script verifies if the service is running fine. If the app fails to run properly after the update, the script will restore the previous working version of the app that it backed up initially. And, will start the app service.
• If the app starts running fine after the update, it will delete the backup files and exit.

Upload the artifact

Now that we have built the artifact, let’s upload it to the SocketXP Artifact Registry.

Login to your SocketXP account using the web potal and go to the OTA update page. In the Artifacts table, click the “Upload new artifact” button.

Browse and select the myapp_1.0.0.tar.gz file we have just built.

Specify the appropriate version for the artifact, 1.0.0 in this example.

Finally, click the “Upload” button to upload the artifact to the cloud registry. You’ll see a message saying “File uploaded successfully”

Deploy the Artifact

Now that the artifact has been uploaded to the SocketXP Artifact Registry in the cloud, let’s deploy the artifact on target devices.

From the Artifacts table, view and select the artifact you have just uploaded.

Note: If you don’t see your artifact yet, click the “Refresh” button to reload the table data.

Click the “+” icon next to the artifact to create a new deployment.

A new window will popup.

Give a name for the deployment, say for example, “deploy-version-1.0.0-to-test-devices”.

Specify the target device ID or the device group or select a tag to deploy the artifact on.

Note: You can deploy the artifact on a single device ID, or a device group or a device tag. If you want to deploy the artifact on more than one device group or device tag, repeat the “Create New Deployment” process for the different group or tag.

Finally, click the “Create Deployment” button.

Now, go to the “Deployments” tab, hit the refresh button.

View and select the deployment we just created to see its progress.

Click the “More Info < >” button to view and monitor the progress of the deployment on each target devices (in the device group or tag).

Click the “Refresh” button to view the progress.

You can check the stdout and stderr logs generated by the update process, by clicking the “view log” buttons.

Let’s login into one of the devices to check if the myapp deployment is successful.

$ systemctl status myapp
● myapp.service - myapp service
     Loaded: loaded (/etc/systemd/system/myapp.service; enabled; vendor preset: enabled)
     Active: active (running) since Tue 2025-02-25 00:25:47 UTC; 2 seconds ago
   Main PID: 486462 (myapp)
      Tasks: 1 (limit: 3301)
     Memory: 152.0K
        CPU: 291ms
     CGroup: /system.slice/myapp.service
             └─486462 /usr/bin/myapp

Feb 25 00:25:47 ubuntu myapp[486462]: Hello, OTA update! Version 1.0.0

We can also view the app logs using journalctl.

$ journalctl -u myapp -n 10
Feb 24 02:00:52 ubuntu myapp[486462]: Hello, OTA update!
Feb 25 00:25:47 ubuntu myapp[486462]: Hello, OTA update! Version 1.0.0

Congratulations! We have successfully updated the debian package app in the remote IoT devices using SocketXP OTA update.

Now that you have learnt how to create and publish a debian package app as OTA updates to remote devices, you can learn to create OTA updates for the following types of artifacts:

• App Binary
• Firmware
• Config File
• Script File
• Docker Container