Getting started with Bela

giuliomoro edited this page Jul 31, 2018 · 46 revisions

Getting started with Bela

  1. Hardware Setup

  2. Software Setup

  3. Build your first project

Hardware Setup

What you'll need

Before starting, make sure you have:

  • Beaglebone (Black, Green or Black Wireless) and Bela cape OR
  • PocketBeagle and BelaMini
  • USB cable
  • 4GB or larger micro-SD card
  • two audio adapter cables for audio in/out


Cape and BBB

Stack the Bela cape on top of the Beaglebone. 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.


Bela Mini

If you ordered a starter kit from us, the BelaMini is already soldered to the PocketBeagle. If you ordered only a BelaMini cape, follow the enclosed instructions to connect it to the PocketBeagle.

Software Setup

Bela SD card image

You will need an SD card with the Bela image on it before continuing. You can download a copy of the image from here

In case you did not get a Bela SD card with your kit, you will need to follow the instructions to flash the Bela image.

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 up after around 40 seconds and advertise itself to your computer as a network interface.

Installing network drivers

Communication between Bela and the host pc takes place through the Ethernet over USB network connection. You may need some network drivers depending on your operating system, as detailed below. In order to log into Bela for advanced use you need an ssh client (optional).

MacOS users

Linux users

Windows users

MacOS users

If you are running OS X 10.10 or earlier:

If you are running OS X 10.11 or later:

If you are running OS X 10.13 or later:

macos security and privacy

Now you should be ready to go:

  • make sure the BBB is plugged in and booted up (might take up to one minute after you plug it in). You should see blinking blue lights on the Bela.
  • if you don't see blinking blue lights, see the release notes for tips on booting older versions of the Bela board from SD.
  • if you do see blinking lights, open a browser and go to . If the IDE shows up, then you are all set and you can jump to Build your first project.

If you cannot see the IDE in the browser visit Troubleshooting - Mac OS.

Linux users

If you're using Linux, everything you need should already be on your machine!

  • make sure the BBB is plugged in and booted up (might take up to one minute after you plug it in).
  • depending on your system's configuration, everything could already be working. Open a browser and go to , if the IDE show ups then you are all set and you can go to Build your first project.

If you cannot see the IDE in the browser visit Troubleshooting - Linux.

Windows users

If you're using Windows with a recent Bela image, then your board should not require any drivers.

If you cannot see the IDE in the browser visit Troubleshooting - Windows.


These notes are for users with legacy versions of Windows or of the Bela image

You'll need to install the following network drivers:

Once the drivers are installed, plug in the board using the USB cable and wait about 40 seconds. Depending on your system configuration, everything could already be working. Open a browser and go to, if the IDE show ups then you are all set and you can jump to Build your first project.

If you cannot see the IDE in the browser visit Troubleshooting - Windows.

Build your first project

Before building your first project it's a good idea to acquaint yourself with Bela's hardware. An explanation of everything that you have at your disposal and how it works can be found in the Hardware explained section.

Building projects with the browser-based IDE couldn't be easier. Make sure your flashed SD card is inserted into the BeagleBone Black and connect the USB to the mini-USB port on the same side as the ethernet port. Then plug in your BBB to the computer and once it is up and running (under a minute the first time you run) open a browser and go to

You can edit the code in the browser window, click the button to compile and run it on the board. The IDE also allows you to manage projects in the Project Explorer tab, to edit project settings in the Project Settings tab, to explore many examples in the Code Examples tab and to browse the built-in documentation in the Documentation tab. Messages from the compiler will be displayed in the browser window. A full explanation of the IDE can be found at Bela IDE.

To find out more about building projects with Bela visit:


Troubleshooting - Mac OS

In case the IDE is not showing up try the following:

  • go to System Preferences->Network, click the + symbol at the bottom left. From the popup window, select "Beaglebone Black"
  • now set the "Configure IP v4" field to "Using DHCP with manual address" and set the IP address to as in the image below


  • click apply and wait a few seconds, the indicator next to the icon should turn green

  • open a browser and go to , the IDE should show up, so you can jump to Build your first project.

  • if that is still not the case, you may want to try to reload the kernel extensions (or you could try to reboot you computer, but this is quicker). Open up a terminal and run

sudo kextunload /Library/Extensions/HoRNDIS.kext
sudo kextload /Library/Extensions/HoRNDIS.kext

note that you may be prompted to enter your computer's password. If that happens, type it in and press enter. Note that there will be no characters or * will be displayed in the terminal window as you type the password in.

  • if you are on 10.13 or above and getting System policy prevents loading the kernel extension., then you should go to System Preferences -> Security & Privacy as explained above.
  • if none of the above works, go to the Test the ssh connection section below to troubleshoot even further.
Troubleshooting - Linux

A. If you are having trouble, you may have to manually turn the interface on: bring up a terminal and type

$ ifconfig -a

The command will return a list of the network interfaces available on your computer, one of them will be the BeagleBone Black. Once you identify the name of the interface, you have to self-assign an IP address on that interface. To do so, run:

$ sudo ifconfig interfaceName up

where you will have to replace interfaceName with the interface representing the BeagleBone Black.

B. If ifconfig is not on your system or it does not list your Bela device, in some systems you can identify the interface name by typing:

ip link

and once identified you can wake it up and assign the ip address by typing:

sudo ip link set interfaceName up
sudo ip addr add dev interfaceName

C. Alternatively, if you have dhclient installed AND you are using the USB connection, you can try to ask the interface to self-configure itself with

$ sudo dhclient interfaceName

note that this will not work if the board is connected via ethernet or wi-fi.

Troubleshooting - Windows

If the IDE does NOT show up, then try the following:

  • open the Control Panel, select "Network and Internet" > "Network connections". The BeagleBone should show up with a name of the type "Local Area Connection Linux Ethernet Rndis Gadget". Right click on it and choose Properties. In the dialog (image below, left), click on "Internet Protocol Version 4 (TCP/IPv4)" and press the "Properties" button. Fill-in the details of as per the image below (right ) and click exit on the two dialogs to exit.


Now try again to open a browser and go to, hopefully the IDE will show up now, so you can jump to Build your first project. In case it does not or if you plan to use ssh as well, jump to the Test the ssh connection section below to check that everything is working properly.

NOTE: if you're using Windows 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 the optional package 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.

Test the ssh connection

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.

If you have gone through operating system-specific steps above, you should be able to connect to the BeagleBone Black by opening a terminal and entering the following:

$ ssh root@

According to the settings of your ssh client, you might, or might not, be prompted with something along the lines of

The authenticity of host ' (' can't be established. RSA key fingerprint is 35:b2:ff:ae:c2:02:30:af:84:1e:0d:f5:c9:c8:4b:34. Are you sure you want to continue connecting (yes/no)?

type yes and press the return key.

If everything is ok, you will now be displayed the BBB prompt:

root@bela ~$

If it does not work, make sure you installed the drivers for your operating system and you rebooted after installing them. At that point, try to get a list of the network interfaces from the terminal with ifconfig on Mac or Linux and ipconfig on Windows and check that your computer is assigned the address in the ethernet-over-usb interface to the BeagleBone, as outlined above.

Last resort

In case none of the above works and you have the possibility to connect the BeagleBone through an ethernet cable to a home router, try the following:

  • once connected, the BeagleBone will expect a DHCP server on the port to assign an IP address to it. This should work on most home router configurations.
  • you can then retrieve that IP address from your router's configuration panel, typically in the "attached devices" panel. Consult your router's manual to help you through these two steps.
  • try then to connect to the IDE by opening in your web browser the page (where is the IP address you retrieved at the previous step), or, from the terminal:
$ ssh

You could also try to log in over serial: when connected to the host, Bela will show up also as a serial device, you should find it under /dev/tty.usbmodem__bela_* where * will be one or more digits. You should therefore be able to do

screen /dev/tty.usbmodem__bela_* 115200

and then insert the user root when prompted. Once logged in, you may be able to inspect the behaviour of the board and possibly troubleshoot it from the inside.

If not even this works, then you may have a faulty unit or a faulty SD card. Try first to re-flash the SD card or use a different SD card. If that fails, please get in touch with us at info [at]

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.