Executing Bela scripts on the command line
While we recommend using the the browser-based IDE to run your code on Bela, we also supply some shell scripts in order to interact with the board via the command line interface. These scripts allow to access all the functions provided by the IDE, as well as a few extra ones.
On this page we explore why you might want to use shell scripts, discuss the scripts that ship with Bela and how to use them, and offer some techniques for going further with the command line.
Table of contents
- What are scripts, and why should I use them?
- What do I need to use shell scripts?
- Some things to know
- Run modes
- Project naming
- Passing options to make
- Passing command line options
- Default values in scripts
- Changing defaults
What are scripts, and why should I use them?
Scripts are little programs that ship with your board that allow you to do some stuff that you can’t do with the IDE, such as:
- Using the Heavy compiler for PureData patches
- Using your favourite text editor instead of the Bela IDE
- Automate the building process (e.g.: re-compile when a file changes)
Except for using the Heavy compiler, using scripts is totally optional. You can make powerful, complex projects without using them. Some people find using scripts to be more efficient and faster, but it’s up to you.
However, if you want to build your confidence with the command line, using scripts is a good way to do that as well as become more familiar with Bela’s internal file system. If that sounds interesting, try them out!
What do I need to use shell scripts?
First, you need a terminal and a
bash shell. These come pre-installed on Mac and Linux systems, and once you open a terminal you’re ready to go.
If you're on Windows you will need a terminal emulator. If you don't have one, you will need to install one, such as cygwin.
Second, you’ll need a copy of the Bela source code. Download it by clicking here, then unzip it on your desktop.
Some things to know
The built-in shell scripts available in the
scripts/ folder of your Bela board (if you need help getting started with the Bela command line, [check out our introduction][/using-bela/command-line]).
The scripts have been tailored for use with the
bash shell (though they are mostly compatible with
sh as well). There is a configuration file,
.bela_common that contains the default values for username and IP address of the board, Bela path and to board and many other parameters and utility functions. Read about how to change default values in scripts if your system is not using the most common configuration.
Extended documentation for each script can be accessed from the command line by invoking the script with the
--help option. For example:
$ ./stop_running.sh --help Usage: stop_running.sh This script stops the Bela program which is running on the board regardless of how it was started.
As a last note, these scripts should be position-independent (as in: they can be run from any working directory, provided you give the appropriate path to the script), but if you get any error complaining about
.bela_common, such as:
bash: ./.bela_common: No such file or directory
then try running the scripts from within the scripts/ folder itself and please [[raise an issue|https://github.com/BelaPlatform/Bela/issues/new]].
Examples below assume you run the scripts from within the
This script updates both the Bela Core and the Bela IDE files on your board. It discards all changes made to the following folders and files in the
This is the only script that does not have a
.sh extension. This means it can be double clicked from a GUI folder explorer (like Finder), so it can be run without the terminal if necessary.
When run with no parameters, it tries to install or update Bela using username
root on IP address
192.168.7.2. It also asks for confirmation before running and requires to press a key before exiting:
All the changes to the CORE files in the remote folder ~/Bela will be LOST. The content of these files/folders will be lost: core include Makefile libNE10.a libprussdrv.a examples Doxyfile samples Your projects stored in ~/Bela/projects should be safe (and surely you have already backed them up somewhere safe, haven't you?). Are you sure you want to continue? (y/N)
y followed by enter if you want to continue.
Arguments can be added when
update_board is run via the terminal. These are:
-i arg : allows to set the username and IP address of the remote end (default: firstname.lastname@example.org) -b arg : allows to set the path to the Bela folder on the remote end. Use quotes if you use the \"~\" symbol (default: ~/Bela) --clean : removes all the files in the remote ~/Bela folder, INCLUDING any files you may have in the ~/Bela/projects/ subdirectory. -d : skips re-generating Doxygen documentation on the board. -n : do not update the IDE. --no-frills : skips some optional commands (e.g.: the IDE is not stopped/restarted). -y : does not prompt the user before deleting the remote files.
Examples of use
To run with default settings (can also be run by double clicking the script in the file explorer):
If your Bela board is not on the default IP address (in this example the IP address is 10.0.0.10):
$ ./update_board -i email@example.com
To disable the prompt before deleting files on the board:
$ ./update_board -y
For a quick update of the core only, and not the IDE:
$ ./update_board -y -d -n
In this example, the script does not prompt for confirmation (
-y), does not generate documentation (
-d), and does not update the IDE (
This script copies a directory of source files from your computer to the board, then compiles the project and runs it. It needs to be followed by the source directory path (see the example below).
The source directory should contain at least one
_main.scd file - that is, files that make up a Bela project.
(Note that the first time you run
update_board, it will take over a minute. Successive runs will be much faster.)
Examples of use
To compile and run a project (in this case, the
$ ./build_project.sh ../examples/01-Basics/print/
We can add command line arguemnts to customise the build behaviour (read more about command line arguments here. In the next example, we compile and run the project located on our computer in
~/Desktop/myBelaProjects/testProject, running it in the background (
-b) and refreshing it every time a file in the source folder changes (
$ ./build_project.sh ~/Desktop/myBelaProjects/testProject -b --watch
To see a a full list of the available options:
$ ./build_project.sh --help
This script compiles a PureData patch using the online Heavy Audio Tools compiler.
|Note that before using this script for the first time you need to go through the preparation steps detailed in [[ PureData and Heavy||Running Puredata patches on Bela#heavy ]], and this script requires your computer to have an internet connection.|
Examples of use
Build a Pd project from the examples folders. This generates a long log output and may take up to a minute to run (especially the first time you create a new project):
$ ./build_pd_heavy.sh ../examples/08-PureData/basicAnalogIn
Flags allow you to customise this build behaviour. In this example we build a Pd project against the latest revision of heavy (
-r dev) and run it with a block size of 64 (
-c "-p 64"):
$ ./build_pd_heavy.sh ../examples/terminal-only/vangelisiser/ -r dev -c "-p 64"
For more info see
- Run modes,
- Project naming,
- Passing command line options, and
[[ PureData and Heavy Running Puredata patches on Bela#heavy ]].
For a full list of the available options, run:
$ ./build_pd_project.sh --help
This script runs a Bela project that is already on the board.
Running it without arguments lists all the projects installed on your Bela:
$ ./run_project.sh # list all installed projects
$ ./run_project.sh --help
This script brings a Bela program that is already running in the background to the foreground, so that you can interact with it (for example, you might want to display the project’s output to the command line).
This program does not take any command line option.
This script enables or disables running a specific Bela project automatically when the board starts up (think Run On Boot in the IDE).
$ ./set_project.sh --help
This script stops the Bela program that is currently running on the board.
This program does not take any arguments.
This script allows you to control the IDE from the command line.
Examples of use
To start or restart the IDE:
$ ./ide.sh start
To stop the IDE:
$ ./ide.sh stop
For a full list of the available options, run:
$ ./ide.sh --help
This script gracefully halts the BeagleBone Black. Run it and wait for the on-board LEDs to stop blinking before disconnecting the board.
This program does not take any command line option.
When running a script, you can either run it in the foreground or in the background.
When running in the foreground you see the output of your program there in your terminal. This is very useful when debugging it, as you can see the values you print on screen. When running in the foreground, you can stop the currently running program with
Ctrl + c.
When running in the background your program’s output doesn’t print to the terminal and we can’t stop it using
Ctrl + c on the command line, but we can still access these functions. When a Bela program is running in the background you can use
./connect_to_project.sh to see the program’s output, and
./stop_running.sh to stop the current process.
The two main advantages of running a project in the background are:
- As long as it’s externally powered, you can detach your Bela board from your computer and it will keep running
- You can update your running project automatically when one of the files in the source folder is modified (using the
When you build a project using
build_pd_heavy.pd, the folder content will be copied to the board in
projectname is the name of the folder that is passed to the build script).
For instance, if you run:
$ ./build_project.sh ~/Desktop/myBelaProjects/testProject
this will store the project’s files and binary on Bela in
~/Bela/projects/testProject. If a folder already exists at the destination, you will be prompted for confirmation.
You can override this default behaviour passing a
-p projectname to the build script. For instance:
$ ./build_pd_heavy.sh ../examples/08-PureData/basicAnalogIn -p theremin
Please do not use spaces in your project names or paths (we are not ready for it yet)!
If you want to use
set_startup.sh on a project, you will need to know that project’s name.
Passing options to make
You can pass options to
make from the
build_pd_heavy.sh scripts. These options are passed to
make before the run target. Use the
-m flag for this.
This will clean the basicAnalogIn project on the board before building it. (Sometimes cleaning a project is necessary because the board’s date has gone out of sync – more info here).
$ ./build_pd_heavy.sh ../examples/08-PureData/basicAnalogIn -m projectclean
The following tells
make to use
gcc as the compiler for C and C++ files. This may be useful if you want to benchmark your program with different compilers (Bela’s default compiler is
$ ./build_project.sh ../examples/03-Analog/analog-input/ -m COMPILER=gcc
If you want to pass multiple options, make sure you enclose them in quotes. Make sure you nest your single and double quotes carefully:
$ ./build_project.sh ../examples/03-Analog/analog-input/ -m 'COMPILER=gcc CPPFLAGS="-g0 -O0" AT='
To learn more about the options you can pass to
make, read [[ the Bela makefile ]].
Passing command line options
You can pass command line arguments when using the
set_startup.sh scripts using the
-c argument. Any program will respond to the arguments listed here, but specific programs can also respond to additional arguments.
To build the project
../projects/myproject and run it with a blocksize of 64 audio samples per block (Note that the command line options which follow
-c need to be entirely enclosed in quotes):
$ ./build_project.sh ../projects/myproject -c "-p 64"
To run the project
basic – in this example we assume it’s already built and exists on the board – with 2 analog channels, a blocksize of 32 samples and a headphone level of -20dB, run (note the argument after
-c, again, is enclosed in quotes):
./run_project.sh -c "-p 32 -C 2 -H -20"
Default values in scripts
The build scripts assume the following default username and IP address for your board:
username: root IP address: 192.168.7.2
These and other values are set in the
scripts/.bela_common file. Note the ‘.’ at the beginning of the file name – this means the file is hidden and will not be shown by default by many file browsers. If you want to peek into the file, you can access it from the terminal. To open the file
.bela_common in the terminal in read-only mode, navigate to the
scripts/ folder and run the following:
$ less .bela_common
The first lines in the file set the default values. This line defines the default IP address:
[ -z "$BBB_HOSTNAME" ] && BBB_HOSTNAME="192.168.7.2"
In shell syntax, this means:
[) the variable
$BBB_HOSTNAME is empty (
-z), then (
&&) assign to the variable
BBB_HOSTNAME the value of
Sometimes a Bela board is configured differently from the default values. For instance, you may be connecting to it over wifi or an ethernet connection, in which case the IP address of the board may be different from
The easiest and most tempting way to change the default values is to simply edit the
scripts/.bela_common file. This way is effective but we don’t recommend it, because when you update board your changes to that file will be discarded.
The correct way of changing the default behaviour permanently is to create a file
.belarc in your home folder. This file will be read at the beginning of
.bela_common and the values it contains are going to become the new default values.
To create and start to edit your
.belaarc file, we can use Nano:
$ nano ~/.belarc
This will create and open this file in Nano. In this example, we’ll change our board’s IP address to
10.0.0.10. To achieve this, place this line in your
~/.belarc file, then exit with
Ctrl + x and save your changes (
[ -z "$BBB_HOSTNAME" ] && BBB_HOSTNAME="10.0.0.10"
Sometimes you will want to override some of the default values only for a single command or for a session, but do not save the change permanently. For example, you may want to give multiple Bela boards different IP addresses, but don’t want to change them permanently.
As we saw above, Bela’s IP address is specified in the
.belarc file with the variable
BBB_HOSTNAME. In this example we’ll run a project called
basic on a board with an IP address different to that in our
We do this by specifying the variable name (in this case,
BBB_HOSTNAME) before running the command. Note that there has to be a space – not a semicolon! – between the variable assignment and the command, and there are no spaces around the
= sign or in the IP address. The shell is unforgiving about spaces!
$ BBB_HOSTNAME=10.0.0.10 ./run_project.sh basic
Sometimes you may want an override to last longer than a single command – like the duration of your current session, or until you close your terminal window. In this case, you can
export the variable once, and then every process that uses
BBB_HOSTNAME will use that value: