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 and you are on macOS or Linux, 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. The instructions below should work for macos and Linux. Windows users could use Balena Etcher instead.

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

2. Find the name of your SD card by listing your volumes

Note

This step is crucial! 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.

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

4. Make an image copy of the SD card

The following line will make an image copy of the disk SD card to the file mybackup.img. Remember to modify the paths /dev/mydisk and mybackup.img below as appropriate

$ sudo dd if=/dev/mydisk of=mybackup.img bs=1024k

This may take a few minutes to complete. No progress indication is displayed on screen, you will just have to wait for the process to end. 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, either by continuing with the command line approach or using Balena etcher as described above. Note that Balena etcher does not currently allow you to copy from an SD card so it is necessary to use the command line for this part of the work.

The following are optional steps which would reduce the size of the .img file:

a. (optional) Fill the empty space with zeroes

Before backing up the data, if you are planning to compress your image file (e.g.: for sharing over the network, or for archiving), you may want to run the following commands, which fills the unused space with zeroes, so that the compressed file will have a smaller size.

# create a file and fill it with zeroes
$ sudo dd if=/dev/zero of=/path/to/the/mounted/sdcard/bigfile bs=1024k
# delete the file you just created
$ sudo rm /path/to/the/mounted/sdcard/bigfile

To run the commands above you need to be able to mount the ext4 partition on the SD card. Note that it is not advised to run these commands on the drive where your running operating system resides, as it could become unresponsive. If you have to do so, then make sure you set a count= parameter to dd with the number of block of size bs that need to be written. Set this value so that you fill, e.g.: 99% of the space, but not all of it.

b. (optional) Determine the amount of data you need to copy

In case your partition is smaller than the size of the SD card, you do not need to backup the whole card, so if this is the case, you can follow the steps below. You wouldrun these commands while being logged onto the Bela system, before any of the other steps:

$ fdisk -u -l /dev/mmcblk0

You will get something along the lines of

            Device Boot      Start         End      Blocks   Id  System
    /dev/mydisk1     *          63      144584       72261    c  W95 FAT32 (LBA)
    /dev/mydisk2            144585     3743144     1799280   83  Linux

You are interested in the highest value in the “End” column. This number is the number of 512-bytes blocks used on your SD card. Pass that value to dd as the count parameter, and set the bs= parameter to 512:

$ sudo dd count=3743144 if=/dev/mydisk of=outputFile.img bs=512

the above is going to be slow because of the small block size. To speed up the copy process, you can increase bs and decrease count correspondingly, ensuring that their product stays the same.

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.