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.

Tip

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

  1. Requirements of the SD card
  2. Flash an SD card using Balena Etcher
  3. Flash an SD card using the command line
  4. Backing up your SD card
  5. Flashing the eMMC
  6. 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.

Important

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

Download and install Balena Etcher.

Balena Etcher is free, open-source software used for copying image files (.iso and .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:

Important

Make sure you choose the SD card in Balena Etcher! This process will overwrite the selected device, so double check the device selected.

Next, click Select Image, and select the Bela software .img.xz file you downloaded in the previous step (you don’t need to uncompress it):

Then, click Select Target, and select SD card you inserted into your computer:

Finally, click 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

Warning!

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 /dev/mydisk.

On Linux:

$ sudo umount /dev/mydisk

On Mac:

$ 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 /dev/rmydisk):

$ 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

Once the 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 BELABOOT.

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.

2. ssh into your Bela system

Open a terminal on your computer, and connect to your Bela system by ssh by running:

$ ssh root@192.168.7.2

Now you’re connected to your Bela system. Your command line will look like this:

~/Bela $

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

Note

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

This requires an SD card flashed with the Bela software. Flash an SD card of at least 8GB using the methods on this page: using Balena Etcher, or using your computer’s command line.

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

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:

/boot/uboot/tools/scripts/beaglebone-black-copy-microSD-to-eMMC.sh

If you are on v0.3.0 or later, run:

/opt/Bela/bela_flash_emmc.sh

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.

Having trouble?

Check out our Troubleshooting Guide for info on common SD problems, or check the Bela Forum.