Search

Using scripts

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

  1. What are scripts, and why should I use them?
  2. What do I need to use shell scripts?
  3. Some things to know
  4. update_board
  5. build_project.sh
  6. build_pd_hvcc.sh
  7. run_project.sh
  8. connect_to_project.sh
  9. set_startup.sh
  10. stop_running.sh
  11. ide.sh
  12. halt_board.sh
  13. Run modes
  14. Project naming
  15. Passing options to make
  16. Passing command line options
  17. Default values in scripts
  18. 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 Pure Data 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.

Tip

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 scripts/ folder.

update_board

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 ~/Bela directory:

  • core/
  • include/
  • Makefile
  • libNE10.a
  • libprussdrv.a
  • examples/
  • Doxyfile
  • samples/
  • Documentation/
  • IDE/
  • ~/usr/lib/libpd.so

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)

press y followed by enter if you want to continue.

Arguments:

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: root@192.168.7.2)
-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):

$ ./update-board

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 root@10.0.0.10

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 (-n).

build_project.sh

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 .c, .cpp, .S, .pd, or _main.scd file - that is, files that make up a Bela project.

(Note that the first time you run build_project after 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 01-basics/print example):

$ ./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 (--watch):

$ ./build_project.sh ~/Desktop/myBelaProjects/testProject -b --watch

To see a a full list of the available options:

$ ./build_project.sh --help

build_pd_hvcc.sh

This script compiles a Pure Data patch into efficient C code using the a local version of the Heavy Audio Tools compiler. This is a useful tool if you are hitting the CPU limits when running a Pure Data patch on Bela.

There is tutorial on how to use the script here.

run_project.sh

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

For more info see Run modes, Project naming, Passing command line options. For a full list of the available options, run:

$ ./run_project.sh --help

connect_to_project.sh

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.

set_startup.sh

This script enables or disables running a specific Bela project automatically when the board starts up (think Run On Boot in the IDE).

For more info see Project naming, Passing command line options,. For a full list of the available options, run:

$ ./set_startup.sh --help

stop_running.sh

This script stops the Bela program that is currently running on the board.

This program does not take any arguments.

ide.sh

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

halt_board.sh

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.

Run modes

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:

  1. As long as it’s externally powered, you can detach your Bela board from your computer and it will keep running
  2. You can update your running project automatically when one of the files in the source folder is modified (using the --watch option).

Project naming

When you build a project using build_project.sh or build_pd_heavy.pd, the folder content will be copied to the board in ~/Bela/projects/projectname (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 run_project.sh or 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_project.sh and build_pd_heavy.sh scripts. These options are passed to make before the run target. Use the -m flag for this.

Examples

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 clang).

$ ./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 build_project.sh, build_pd_heavy.sh, run_project.sh, 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.

Examples

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:

if ([) the variable $BBB_HOSTNAME is empty (-z), then (&&) assign to the variable BBB_HOSTNAME the value of 192.168.7.2.

Changing defaults

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 192.168.7.2.

Permanent override

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 (Y):

[ -z "$BBB_HOSTNAME" ] && BBB_HOSTNAME="10.0.0.10"

Temporary override

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 .belarc file.

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:

export BBB_HOSTNAME=10.0.0.10