Getting started with Bela » History » Version 41

Giulio Moro, 2016-05-17 12:09 AM

1 19 Giulio Moro
h1.  Getting started with Bela
2 1 Giulio Moro
3 1 Giulio Moro
h2. Prerequisites
4 1 Giulio Moro
5 1 Giulio Moro
Before starting, make sure you have:
6 1 Giulio Moro
* Beaglebone Black
7 20 Giulio Moro
* Bela cape
8 1 Giulio Moro
* standard-A to mini-B USB cable
9 39 Giulio Moro
* 2GB or larger micro-SD card
10 3 Giulio Moro
* Optional, but recommended: up to two 3-ways female connectors for audio in/out from the cape. You will probably want some sort of stereo female jack connector at the other end.
11 1 Giulio Moro
12 1 Giulio Moro
h2. Hardware setup
13 1 Giulio Moro
14 40 Giulio Moro
Stack the audio cape on top of the Beaglebone Black (BBB). Make sure all the pins from the cape fit into the socket header of the BBB and that no pin gets bent in the process.
15 1 Giulio Moro
16 1 Giulio Moro
h2. Software setup
17 1 Giulio Moro
18 39 Giulio Moro
In case you did not get a Bela SD card with your kit, you will need to follow the instructions detailed here to flash your own SD card:
19 40 Giulio Moro
20 39 Giulio Moro
Once you have your SD card, Insert it into the BBB and plug it into your computer with the USB cable. The BBB will boot Debian and advertise itself to your computer as a network interface.
21 2 Giulio Moro
22 39 Giulio Moro
Communication between the BBB and the host pc takes place through the Ethernet over USB network connection. In order to log into the BBB you need an ssh client and you may need some network drivers according to your operating system, as detailed below.
23 6 Giulio Moro
24 5 Giulio Moro
h3. MacOS users
25 5 Giulio Moro
26 36 Giulio Moro
If you are running *Yosemite* or earlier:
27 29 Giulio Moro
* install network drivers for the BBB from and the serial drivers from . This requires a reboot.
28 36 Giulio Moro
If you are running *El Capitan*, please make sure you upgrade to 10.11.4 and install HoRNDIS-rel8pre2.pkg instead  (from
29 38 Giulio Moro
NOTE: earlier versions of El Capitan may have troubles with the Beaglebone Black over USB.
30 23 Giulio Moro
31 23 Giulio Moro
 * make sure the BBB is plugged in and booted up (might take up to one minute after you plug it in).
32 1 Giulio Moro
Everything might be already working now. Open a browser and go to, the IDE should show up.
33 1 Giulio Moro
34 1 Giulio Moro
In case the IDE is not showing up and the ssh test below fails, try the following:
35 1 Giulio Moro
* go to System Preferences->Network, click the + symbol at the bottom left. From the popup window, select "Beaglebone Black"
36 1 Giulio Moro
* now set the "Configure IP v4" field to "Using DHCP with manual address" and set the IP address to
37 1 Giulio Moro
38 1 Giulio Moro
* click apply and wait a few seconds, the indicator close to the icon should turn green
39 1 Giulio Moro
* jump to the *Test the ssh connection* section below to check that everything is working properly
40 1 Giulio Moro
41 32 Andrew McPherson
* *Note: using libsndfile on Mac OS X is not fully supported yet*
42 41 Giulio Moro
43 41 Giulio Moro
h3. Linux users
44 41 Giulio Moro
45 41 Giulio Moro
All you need should be already on your machine, jump to *Test the ssh connection* below and have fun!
46 41 Giulio Moro
If you are having trouble, you may have to manually turn the interface on: the
47 41 Giulio Moro
48 41 Giulio Moro
command will show you the list of available interfaces on your computer, one of them will be the BeagleBone Black. Once you identify the name of the interface, you have to assign your computer an IP address on that interface:
49 41 Giulio Moro
<pre>ifconfig interfaceName up</pre>
50 41 Giulio Moro
where you will have to replace interfaceName with the name of the interface connected to the BeagleBone Black.
51 1 Giulio Moro
52 5 Giulio Moro
h3. Windows users
53 5 Giulio Moro
54 26 Giulio Moro
* you will need 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* Make sure you install also a copy of rsync with it. You will want to note that in order 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 .
55 6 Giulio Moro
* additionally, you need to install the network drivers from (Windows 64 bit) or (Windows 32bit)
56 1 Giulio Moro
* in the network connections manually set thel IP address for the BBB to
57 9 Giulio Moro
58 32 Andrew McPherson
* Open a browser and go to, the IDE should show up. In case it does not (or if it does but you plan to use ssh as well) jump to the *Test the ssh connection* section below to check that everything is working properly
59 1 Giulio Moro
60 1 Giulio Moro
h3. Test ssh connection
61 1 Giulio Moro
62 27 Andrew McPherson
When using the USB network connection, the BBB has a self-assigned IP of, we will log in with username *root* and an empty password (older images have a password 'a').
63 1 Giulio Moro
64 6 Giulio Moro
If you have gone through operating system-specific steps above, you should be able to connect to the beaglebone with
65 6 Giulio Moro
<pre>$ ssh root@</pre>
66 6 Giulio Moro
67 6 Giulio Moro
According to the settings of your ssh client, you might, or might not, be prompted with something along the lines of 
68 6 Giulio Moro
<pre>The authenticity of host ' (' can't be established.
69 6 Giulio Moro
RSA key fingerprint is 35:b2:ff:ae:c2:02:30:af:84:1e:0d:f5:c9:c8:4b:34.
70 1 Giulio Moro
Are you sure you want to continue connecting (yes/no)? </pre>
71 6 Giulio Moro
type @yes@ and press the return key.
72 6 Giulio Moro
73 6 Giulio Moro
If everything is ok, you will now be displayed the BBB prompt:
74 13 Andrew McPherson
<pre>root@arm ~#</pre>
75 6 Giulio Moro
76 22 Giulio Moro
h3. (Optional) ssh config and ssh keys setup
77 1 Giulio Moro
78 22 Giulio Moro
If you set a password on your beaglebone, ssh would require you to enter the password everytime you open a connection to the BBB. This will happen a few times during setup and then 3 times every time you build and run your project. To avoid quickly getting annoyed by this, you can use ssh keys. In the @scripts/@ you will find a setup script which
79 6 Giulio Moro
* generates (if not exists) a key-pair on your host machine (stored in @~/.ssh/@ )
80 6 Giulio Moro
* sets the @~/.ssh/config@ file
81 6 Giulio Moro
* copies the public key to the BBB
82 16 Giulio Moro
83 6 Giulio Moro
To do so, run the @./ if you are on Windows or @./ otherwise from the @scripts/@ folder
84 5 Giulio Moro
85 1 Giulio Moro
This way you will be able to log into the BBB simply typing:
86 7 Giulio Moro
<pre>ssh bbb</pre>
87 5 Giulio Moro
88 1 Giulio Moro
h2. Build your first project
89 4 Giulio Moro
90 20 Giulio Moro
Clone the Bela repository to your machine using Mercurial:
91 28 Andrew McPherson
<pre>hg clone</pre>
92 20 Giulio Moro
or download a zip file of the archive from 
93 10 Giulio Moro
94 20 Giulio Moro
Do you want to experience C++ development from a web browser? Open a new tab and you are ready for [[ Compiling Bela projects in a web browser]]
95 20 Giulio Moro
Do you want to get started immediately, without need to install any software on your machine? Grab a terminal and learn about  [[ Compiling Bela projects on the board]]
96 20 Giulio Moro
Do you want to turn your computer into a cross-compiling machine, with the advantages of an IDE and you are willing to put (some) effort into it? [[ Compiling Bela projects in Eclipse]]