Managing your SD card
The SD card is a vital part of the Bela system. It’s often necessary to copy (or “flash”) the Bela software from your computer to an SD card for use in your Bela system, or to back up your projects or the entire contents of your SD card.
This article is about managing the data on your SD card - flashing it (using free GUI software or the command line) - as well as backing up both your projects as well as your whole Bela software image.
If you bought a Bela Starter Kit, your Bela unit's internal memory will be pre-flashed with the Bela software. Bela Mini Starter Kits include a micro SD card flashed with the Bela software.
Table of contents
- Requirements of the SD card
- Flash an SD card using Balena Etcher
- Flash an SD card using the command line
- Backing up your SD card
- Flashing the eMMC
- Having trouble?
Requirements of the SD card
All Bela systems use micro SD cards. The Bela Mini Starter Kit comes with an SD card pre-flashed with the latest software. You can also purchase a pre-flashed SD card from our shop, or add one to any order.
If you want to use an SD card of your own, make sure it has at least 8GB of space. We recommend using a 16GB card to ensure lots of space for assets like audio clips.
We recommend using a high-quality SD card. Your SD card is the core of your system, and if it fails you risk losing everything that's not backed up - make sure your SD card is reliable!
Flash an SD card using Balena Etcher
1. Download Balena Etcher
Balena Etcher is free, open-source software used for copying image files (
.img) and zipped files (
.zip) to storage media.
2. Download the latest Bela software image.
You need to download the Bela software image to flash to an SD card. Note that this is different from the ZIP file used for updating your Bela system.
Download the latest Bela image release from our Github page.
3. Insert your SD card into your computer
Insert your SD card into your laptop using the SD card slot (you may need an SD card adapter), or use a dongle.
4. Flash the card using Balena Etcher
Open Balena Etcher. You’ll see the following:
Make sure you choose the SD card in Balena Etcher! This process will overwrite the selected device, so double check the device selected.
Select Image, and select the Bela software
.img.xz file you downloaded in the previous step (you don’t need to uncompress it):
Select Target, and select SD card you inserted into your computer:
Flash to start the process. A progress bar will appear:
5. Insert the SD card into your Bela system
When your SD card is finished, insert it into your Bela system. Plug your system in to your computer by USB and load up the IDE.
Flash an SD card using the command line
If you’re comfortable using the command line, you can use this method. No extra software required!
1. Download the latest Bela software image
Download the latest Bela image release from our Github page. The downloaded file will be about 550MB.
Though updating your Bela system requires a ZIP file, you need to download the Bela software image to flash to an SD card.
2. Uncompress the Bela software image
When your download is complete, uncompress it. The uncompressed file will be about 4GB. Various GUI tools for uncompressing
xz files are available for Linux, Mac and Windows, but you can also use the command line from a bash shell:
$ unxz -k bela_version_date.img.xz
3. Insert your SD card into your computer
You can use the SD card slot on your computer with an SD card adapter, or an external USB SD card reader.
4. Find the name of your SD card by listing your volumes
This step is crucial! The flashing process re-writes the device you choose, so make sure you double check the name and that you're sure you've specified your SD card.
On Linux, run the following command:
$ sudo fdisk -l
On Mac OS X, run:
$ diskutil list
This will list your volumes. At least one will be your computer’s hard drive, and one will be your SD card. If you’re not sure which is your SD card, eject it and list your volumes again - the volume that’s now not listed will be your SD card.
NOTE: on MacOS, if your SD card is, e.g.: in
/dev/disk3, you will be able to write to and read from the corresponding “raw” disk
/dev/rdisk3 (note the additional
r). This will make the copy faster.
5. Unmount your SD card partition
We assume for the rest of this document that your SD card is
$ sudo umount /dev/mydisk
$ sudo diskutil unmountDisk /dev/mydisk
6. Write the image to the SD card.
Run the following command. (On a Mac, add an
r to your disk name to increase writing speed, ie
$ sudo dd if=/path/to/inputFile.img of=/dev/mydisk bs=1024k
There is usually no command line output during this process, and it may take several minutes. To display the process, enter
CTRL + T.
7. Verify the image
dd command is finished, eject and re-insert the SD card into your computer. List your volumes as you did in Step 4.
If your SD card has flashed correctly, it will be listed as an external driver called
8. Insert your SD card into your Bela system
Your SD card is ready! Insert it into your Bela or Bela Mini system, and you’re ready to go.
Backing up your SD card
If you simply want to download all projects and assets from your Bela system, go to
Settings , scroll down to
Other System Functions, and click
Download all projects. Your entire project directory will automatically download in a single ZIP file.
However, you might want to back up your entire Bela system as well as your project files (to use the SD card in another Bela system, for example, or as an emergency backup for a performance). This process creates a Bela software image of what’s on your Bela system, which can then be flashed to an SD card.
1. Remove the SD card from your Bela system and boot it up
For this process your Bela system must boot from its internal memory. To do this, remove your SD card, then connect your board to your computer and boot it up.
ssh into your Bela system
Open a terminal on your computer, and connect to your Bela system by
ssh by running:
$ ssh firstname.lastname@example.org
Now you’re connected to your Bela system. Your command line will look like this:
This means you’ve connected to your Bela system, and commands run here will execute on your Bela system and not on your local computer. Bela is based on Linux, so all Bela commands are based on the Linux command line.
2. Download your Bela image
Your Bela software image file will be large - the Bela software is 4GB, plus any space required for your projects and assets.
Run the following on your Bela command line:
$ sudo dd conv=sparse if=/dev/mydisk of=outputFile.img
3. Flash your image to an SD card
Now that you have a
.img file that contains your entire Bela system and projects, you can flash it to an SD card using the instructions on this page.
Flashing the eMMC
This section applies only to Bela, and not to Bela Mini. Bela Mini requires an SD card and does not have internal memory.
Bela uses a BeagleBone Black, which has a built-in eMMC. This means you can copy the Bela software to this eMMC using a flashed SD card. You then won’t need the SD card to boot up.
To flash the Bela eMMC, follow these steps:
1. Flash the Bela software to an SD card
2. Insert the flashed SD card into your Bela and boot it up
Insert the flashed SD card, and boot up the Bela system. It will automatically boot from the SD card.
3. Access the browser-based IDE
In a web browser (we recommend Chrome) access the Bela IDE (you can use
bela.local, or use the IP for your OS).
4. Find the version of the Bela software you’re running
In the console at the bottom of the IDE, type this command and press
grep "Bela image" /etc/motd
The version of the Bela software on your SD card will be printed to the console.
5. Copy the image from the SD card to the eMMC
If you are on v0.2.1 or earlier, run this line in the console:
If you are on v0.3.0 or later, run:
The copy process will take a few minutes.
6. Verify it
This tests if your image has been properly copied to the eMMC.
Shut down your Bela and remove the SD card. Then plug it back into your computer, and wait for it to boot up. Load up the IDE in a web browser - if it loads, you’ve successfully flashed your Bela system’s internal memory.