Configuring a Pictorus app to always run on your device

In a previous blog post we showed off how to build a range finder in Pictorus using a simple off-the-shelf acoustic transceiver. Now that we have this component working, we'll dive into how to deploy this app permanently to a Linux device, so other apps can communicate with it.

The primary motivation for this blog post is to show users how to install their Pictorus apps permanently to their devices. Since our Beta product does not support running multiple apps concurrently, this is something folks will need to manage on their own.

Also, this range finder app is a great example of why you might want to split an app into multiple smaller apps - primarily because this single sensor requires a 10,000 hz update rate. Running a larger app at this rate could strain resources and lead to degraded performance. Better to isolate high frequency components into their own smaller app.

Step One: Confirm the app is currently deployed

If you load your app in browser, and select the device you want to deploy to, after a few seconds you'll see one of two icons. Either a green check box will appear, indicating that the app you see is what is running on the device, or an orange "out of sync" icon will appear, which means this app is not currently installed on your device.

If you see the out of sync warning, you need to re-deploy the app before proceeding (as shown above).

Now, SSH into your device, and confirm the Pictorus app's location. You should see it by using the linux list command (might require sudo):

 ls /root/.pictorus/device_manager/apps/pictorus_managed_app

All Pictorus apps are currently deployed to this location. So, if we want to install this app permanently, we should copy this executable elsewhere. We can do this like so:

sudo mkdir /rangefinder
cd /root/.pictorus/device_manager/apps/
sudo cp pictorus_managed_app /rangefinder/rangefinder_app
sudo chmod 755 /rangefinder/rangefinder_app

This will create a new root directory for our app, copy it over, and make sure it has appropriate run permissions.

There's several ways to configure an app to run at bootup. We'll highlight one of the "better" ways (SystemD), and an "easier" way (add to etc/rc.local).

Method 1: Create a SystemD service to run at boot

This approach has the advantage of automatically handling restarting your program if it crashes, and logging its output to a standard location that you can view with journalctl.

1. Create a new service file under the /etc/systemd/system/ directory. The service file should end in .service, for example /etc/systemd/system/rangefinder.service.
2. Open this file in a text editor. You might use sudo nano /etc/systemd/system/rangefinder.service to open it with nano.
3. Inside this file, you need to include a [Service] section and an [Install] section. In the [Service] section, you specify the command to start your program. In the [Install] section, you specify when the service should be started. Here is a template for what the file might look like:

[Unit]
Description=Ultrasonic Range Finder App

[Service]
ExecStart=/rangefinder/rangefinder_app

[Install]
WantedBy=multi-user.target

Make sure the new file is available to systemd by running sudo systemctl daemon-reload. Now you can start the service with sudo systemctl start rangefinder.service. If it's working correctly, you can enable it to run at boot with sudo systemctl enable rangefinder.service.

Try rebooting your device, and then watching the logs with:

journalctl -u rangefinder.service -f

Method 2: Start your app at boot using rc.local

This approach is a little easier, but a lot less robust. By simply adding /rangefinder/rangefinder_app & to your /etc/rc.local file, Linux will start your app at boot and put it into the background.

You won't get journal logs this way, and if the app crashes, it won't restart itself.

Final thoughts

Both of these approaches will allow you to permanently install your Pictorus app to your device. This way you can deploy additional apps to the same device to run concurrently. To communicate between multiple apps, UDP is a good protocol currently supported in Beta. We've dedicated another blog post here to highlight a multi-app setup with UDP communication.