Running a program as a service
Run a program in the background using `systemd`
This is a guide for running a program as a service on Bela. This can be useful when you want other processes to run alongisde the main Bela program, for instance to run a daemon that you can communicate with from your Bela program. Any program run this way will not be able to access Bela’s audio, analog and digital I/Os while another Bela program is running.
Table of contents
- Creating a service file
- Controlling the service
- Running at boot
The operating system on your Bela is a customised version of a Debian Linux distribution.
systemd to run services in the background at various times, for instance at boot, when a peripheral is connected or at regular time intervals.
In this document we explain how to create a
systemd service, how to manually start and stop it, how to access its logs and how to set it to start automatically on boot.
Running regular Bela projects on boot is also done using
systemd, but in a more complex way than what is explained here. To run Bela projects on boot, you do not need to follow the instructions below and you can simply use the Bela IDE's 'Run on boot' menu, instead. See here for more information.
Pre-requisites and naming conventions
The instructions below assume that you already have a working program on your board that you want to run in the background. The executable file will be located somewhere on your Bela’s file system, we use the following placeholder text below, which you will have to replace with the actual values for your system:
EXEC_DIRis the absolute path to the folder containing your executable file
EXEC_NAMEis the name of the executable file
For example, if you have a Bela project in your IDE called
O2O, its full path will be
EXEC_DIR will be
EXEC_NAME will be
Creating a service file
The first step is to create a
systemd service file.
Service files are contained in
/lib/systemd/system/ and define some variables used by
systemd do determine how to run a program within a service, when to start it, whether to restart it in case of crash, etc.
A detailed description of all the options available is beyond the scope of this document, but you can read more about it here.
Create a file in
/lib/systemd/system/EXEC_NAME.service on your Bela with this content (replace any placeholder text entries as appropriate):
[Unit] Description=EXEC_NAME Launcher After=network-online.target [Service] ExecStart=EXEC_DIR/EXEC_NAME Type=simple Restart=always RestartSec=1 WorkingDirectory=EXEC_DIR Environment=HOME=/root KillMode=process [Install] WantedBy=default.target
You can create this file from the terminal, if you are familiar with it, or you can do this via the Bela IDE as follows:
- create a file
EXEC_NAME.servicein your project (make sure the file includes only the text above and none of the automatically-generated content in the file you create)
- move the file into place by running
mv /root/Bela/projects/CURRENT_PROJECT_NAME/EXEC_NAME.service /lib/systemd/system/
in the Bela IDE console, where
CURRENT_PROJECT_NAMEis the name of the project that is currently open in the Bela IDE. If the
EXEC_NAMEprogram was built through the IDE and that’s the project that is currently open, then
EXEC_NAMEwill be the same.
Controlling the service
Once the service file is in place, you can start the program running in the background with
systemctl start EXEC_NAME
in a terminal or in the console of the Bela IDE. You can stop the program with
systemctl stop EXEC_NAME
While this program is running in the background, you can visualise the process’s output running
journalctl -fu EXEC_NAME in a terminal, or
journalctl -n 20 -u EXEC_NAME | cat in the Bela IDE’s console.
Running at boot
Once you are happy with how this is working, you can enable the
EXEC_NAME service to start automatically in the background at boot with
systemctl enable EXEC_NAME
Later you can disable it with
systemctl disable EXEC_NAME
When the program is started on boot you can still use the
journalctl commands above to access its output.
Note that when starting at boot, your program may start a few seconds after the Bela program that may also be running on boot.