Skip to content

Interact with Bela using the Bela scripts

Jump to bottom Edit New page
roberthjack edited this page Mar 23, 2021 · 26 revisions

The Bela Wiki has moved to learn.bela.io. This material has been superseded. Click here for the maintained version.

While the browser-based IDE is the recommended method to run your code on Bela, you can alternatively use the available 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 and also a few extra ones.

Why would I want to use shell scripts and why should I keep reading this lengthy page?

The shell scripts are needed/help to

  • use the Heavy compiler for PureData patches,
  • use your favourite text editor instead of the one built into the IDE,
  • improve your confidence with the terminal,
  • be more efficient,
  • automate the building process (e.g.: re-compile when a file changes),
  • becoming a nerd

What do I need?

  • a terminal emulator and the bash shell.

What is a terminal emulator?

The answer is too long for this text. Suffices to say: if you are on Mac or Linux you are ok, just "open a terminal". On Mac invoke spotlight (cmd-<space>), type terminal, and hit <enter>. If you are on Linux, then you are not reading this paragraph anyhow.

If you are on Windows then things may be a more complicated. You will need to install a terminal emulator, bash and a toolkit that allows you to use ssh and some other basic shell tools. The shell scripts in this project have been tested with mingw. Other options are cygwin or Windows 10 Anniversary Update's bash. If you decide to install mingw, make sure you select the optional components rsync and openssh with it. Useful note, in case you need to paste code into the mingw terminal you have to right click on the terminal's title bar and navigate the menu to edit->paste.

What else do I need?

A copy of the Bela source code. You can get the latest version downloading this archive. Before proceeding, download it and unzip it on your desktop.

The Bela scripts

If you got to this point, downloaded the Bela source code, and (if on Windows) installed a terminal emulator, but still you don't know how to use one, read the minimal introduction to the terminal before continuing.

A number of shell scripts are available in the scripts/ folder that allow you to edit your project files on the host machine, copy them over to the BBB and have your project built on the BBB without the need to install any tools on your host.

General considerations

These are the scripts contained in the scripts/ folder:

  • update_board
  • build_pd_heavy.sh
  • build_project.sh
  • connect_to_project.sh
  • halt_board.sh
  • ide.sh
  • run_project.sh
  • set_startup.sh
  • setup_ssh.sh
  • stop_running.sh

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 instance

$ ./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.
Examples below assume you run the scripts from within the scripts/ folder.

update_board

This script updates core and IDE Bela files on the board, discarding all changes made on the board to the following folders and files:

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

This is the only script that does not have a .sh extension, because this way it can be double clicked from a GUI folder explorer on some systems (e.g.: from a finder window on Mac OSX), thus allowing terminal-impaired users to restore their board if they soft-bricked it.

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:

The default behaviour can be overridden with command line options as described below (this requires you to use a terminal).

-i arg : allows to set the username and IP address of the remote end (default: [email protected])
-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

If your Bela board is configured with the default settings, e.g.: it is on IP address 192.168.7.2, you would simply run

$ ./update-board

or even just double click the file from the file browser window, if your system supports it.

If your Bela board is not on the default IP address, but it is on, e.g.: 10.0.0.10, then you would run

$ ./update_board -i [email protected]

If you do not want to be prompted before deleting files on the board, you would run

$ ./update_board -y

If you are really trying to make a quick update of the core code only (e.g.: to copy over your local changes), you would probably do

$ ./update_board -y -d -n

so that the script:

  • does not prompt for confirmation -y
  • does not generate the documentation -d
  • does not update the IDE -n

build_project.sh

This script copies a directory of source files to the board, compiles and runs it. The source directory should contain at least one .c, .cpp, .S, .pd, or _main.scd file. The first time you run update_board after update_board, it will take over a minute. Successive runs will be much faster.

Examples

Compile and run the basics/print example:

$ ./build_project.sh ../examples/01-Basics/print/

Compile and run your project stored in ~/Desktop/myBelaProjects/testProject in the background (-b) and refresh it every time a file in the source folder changes (--watch):

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

For more info see Run modes, Project naming, Passing command line options, Passing options to make.

For a full list of the available options, run:

$ ./build_project.sh --help

build_pd_heavy.sh

This script compiles a PureData patch using the online Heavy Audio Tools compiler. Before using this script for the first time you need to go through the preparation steps detailed in PureData and Heavy.

Also, this script requires an internet connection on your desktop.

Examples

Build a Pd project from the examples folders:

$ ./build_pd_heavy.sh ../examples/08-PureData/basicAnalogIn

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

For a full list of the available options, run:

$ ./build_pd_project.sh --help

run_project.sh

This script runs a Bela project that is already installed to the board. To know what projects are already on the board, run it without any argument.

$ ./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 to the foreground a Bela program that is already running in the background, so that it can be run interactively (e.g.: you can display the standard output).

For more info see Run modes. This program does not take any command line option.

set_startup.sh

This script enables or disables running a Bela project when the board starts up. Run it to make your project start automatically every time you power up the board.

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

$ ./set_project.sh --help

stop_running.sh

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

This program does not take any command line option.

ide.sh

This program controls the Bela IDE.

Examples

To start or restart the IDE run:

$ ./ide.sh start

To stop the IDE run:

$ ./ide.sh stop

For more info see Bela IDE. 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 using the scripts, 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, you do not see the values printed by your program. If you are using the in-browser scope, you will still be able to use the scope as normal. 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. You can detach the board from the computer and it will keep running (of course, the board needs to be powered from a battery or power supply to actually 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, where projectname is, by default, 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).

You will need to know the name with which your project is stored on the board when you want to act on it using the run_project.sh and set_startup.sh scripts.

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, followed by the actual

Examples

$ ./build_pd_heavy.sh  ../examples/08-PureData/basicAnalogIn -m projectclean

will clean the basicAnalogIn project on the board before building it. See [here](Date on the BeagleBone) why you may want to do this.

$ ./build_project.sh  ../examples/03-Analog/analog-input/ -m COMPILER=gcc

This 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 (default compiler is clang).

If you want to pass multiple options, make sure you enclose them in quotes, e.g.:

$ ./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 options to the program that is executed when using the build_project.sh, build_pd_heavy.sh, run_project.sh, set_startup.sh scripts using the -c option . Any program will respond to the arguments listed [here](Bela command line arguments) but specific programs can respond to additional arguments.

Examples

To build the project ../projects/myproject and run it with a blocksize of 64 samples per block, run:

./build_project.sh ../projects/myproject -c "-p 64"

Note that the command line options which follow -c need to be, themselves, wrapped in quotes.

To run the project basic which has already been built and already exists on the board with 2 analog channels, a blocksize of 32 samples and a headphone level of -20dB, run:

./run_project.sh -c "-p 32 -C 2 -H -20"

Default values in scripts

The build scripts assume the following default values for your Bela 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 that 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 easily access it from the terminal. You can, for instance, use the command:

less .bela_common

to open the file in read-only mode. The first lines in the file set the default values. For instance the default IP address is defined with the line

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

which, in shell syntax, 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 discouraged, because when you update your copy of the source code, your changes to that file would 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.

For instance, if your board's IP address is 10.0.0.10, the content of your ~/.belarc file will be:

[ -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. A use case for this is when you have multiple boards on different IP addresses.

In order to override a default value for the duration of a single command you need to prepend an assignment to the corresponding variable to the command. For instance, to run an existing project called basic on the board at 10.0.0.10 you would do

BBB_HOSTNAME=10.0.0.10 ./run_project.sh basic

note that there has to be a space but no semicolon between the variable assignment and the command. Also, no spaces around the = sign or in the middle of the IP address. The shell is pretty unforgiving about spaces.

If you want an override to last for the entire duration of the current session (e.g.: until you close a given terminal window), then you can export the variable once.

export BBB_HOSTNAME=10.0.0.10

Every command issued on the given terminal after the line above will consider 10.0.0.10 as the value of $BBB_HOSTNAME.

Add a custom footer

Getting started with Bela

Bela IDE

Bela Hardware

Examples and Tutorials

Updating Bela

Clone this wiki locally