Manage your SD card - BelaPlatform/Bela GitHub Wiki

This material has been superseded. Visit learn.bela.io for the maintained version.

Both the BeagleBone Black and the BeagleBone Green have 4GB of internal storage, in the so-called eMMC (embedded multimedia card). They also come with a micro-SD card reader. When the device is powered up, it will boot from the SD card, if there is one, otherwise it will boot from the eMMC

The eMMC normally ships with a distribution of Linux which is not suitable for running Bela, so you would normally start by flashing the Bela image on an SD card. If your image is smaller than the size of the eMMC, you can later copy your SD to the eMMC.

Flashing the Bela image

Preparing a disk image for flashing

Once you have downloaded the desired image file from the official releases page, you will need to uncompress it. The size of the xz-compressed file is about 550MB. Once uncompressed it will be just below 4GB. Various GUI tools for uncompressing xz-compressed files are readily available for Linux, Mac and Windows.

If, instead, you are using xz from the command line, you would run:

$ unxz -k bela_version_date.img.xz

Once you have your .img file, you are now ready to flash the image on to the SD card. You may have an SD card reader embedded into your computer, otherwise you may need to source a USB SD card reader.

Flashing an SD card

IMPORTANT NOTES:

  1. These instructions are to be run on your computer and NOT on the BeagleBone Black itself.
  2. By executing the instructions below all the data on the SD card will be lost. If you mistakenly write to the wrong device (e.g.: an internal hard drive instead of the SD card), you may also permanently lose data from your computer, so make sure you choose your destination device with great care.
  3. The user performing the operation needs to be the administrator of the computer in use and may be required to enter its password during the operations below.

On Windows, we recommend the use of the GUI tool Win 32 disk imager (instructions for use can be found on the developer's website).

If, instead, you prefer to use the command line on Windows, the dd program is available and can be used in a similar way to what described below for Mac and Linux, though some commands may vary slightly.

NOTE: instructions below are for Mac and Linux users only and require the use of the terminal

Find the name of your SD card

Put your SD card in the SD card reader and open a terminal.

# On Linux:
$ sudo fdisk -l
# On MacOS:
$ diskutil list

Your volumes will be listed - at least one will be your 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 missing volume 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.

We assume for the rest of this document that your SD card is /dev/mydisk. Other valid values could be, e.g.: /dev/rdisk3 or /dev/mmcblk0 . In any case, make sure you:

  • select a disk (e.g.: sdc, disk3, mmcblk0) and not a partition (e.g.: sdc1, disk3s1, mmcblk0p0)
  • select the correct disk (you could delete the entire content of your computer if you were to write to the wrong disk).

Unmount the SD card partitions

Always start by unmounting the SD card.

# on Linux:
$ sudo umount /dev/mydisk
# on MacOS:
$ sudo diskutil unmountDisk /dev/mydisk

Writing the image to the SD card

Make sure that the SD card is inserted and it is unmounted (as explained in the previous step) and:

$ sudo dd if=/path/to/inputFile.img of=/dev/mydisk bs=1024k

Again, using of=/dev/rmydisk (add an r just after /dev/) when on a Mac will perform the write faster.

Verifying the image

Once the dd command above returns (or Win32 Disk Imager has finished), remove the SD card and re-insert it in your computer. It should come up on your system as an external driver "BELABOOT". If it does, then you are probably good to go. Put the SD card in your Bela and fire it up. If it doesn't, then check the steps above; in particular: did you run the unxz line / did you uncompress the image file before flashing?

Booting problems

If you are on Bela Mini, a correctly flashed SD card will boot properly straight away. On Bela, whether a correctly flashed SD card the image will boot or not will depend on the content of the built-in memory (eMMC). For instance, if you have a Bela v0.3.4 or newer image on the SD card and a Bela v0.3.3 or earlier (or any beagleboard.org) image on the eMMC, the board will not boot from the SD card.

In such a case, in order to boot from the SD card, you can use one of the following options. If there is a beagleboard.org image on the eMMC, the eMMC will need to be re-flashed with a Bela image in order to become usable again.

Option 1

Use this if you have 3 jumper wires available.

  • connect P8_45 and P8_46 to 3.3V (P9_03 and P9_04) and connect P8_44 to GND (P9_01). Check out the pin diagram here.
  • insert the SD card
  • power on the board
  • it will boot from the SD card
  • jump to Common steps below

Option 2

Use this if you have ssh access to the image on the eMMC.

  • remove SD card
  • plug the board into the host over USB. It will boot from the eMMC.
  • ssh to the board, e.g.:
    • if the eMMC contains a beagleboard.org image, do ssh [email protected], password temppwd, or anything else needed to log into it (there have been many versions over time, some of them may require a domain/user/password to access them)
    • if the eMMC contains a Bela image, do ssh [email protected]
  • run on the board the following commands:
sudo dd if=/dev/zero of=/dev/mmcblk1 bs=1024k count=50
sudo dd if=/dev/zero of=/dev/mmcblk1p1 bs=1024k count=50
sudo dd if=/dev/zero of=/dev/mmcblk0 bs=1024k count=50
sudo dd if=/dev/zero of=/dev/mmcblk0p1 bs=1024k count=50

probably, 2 or more of these commands will fail, but that's just fine.*

  • insert SD card and reboot. It will boot from the SD card
  • jump to Common steps below

* : what we are trying to do is to make the eMMC unbootable, so that the board will always boot from the SD card. So, we try to write zeros to the beginning of the boot partition. This is supposed to be /dev/mmcblk1p1, hence writing to /dev/mmcblk1 should be fine. However, some board will have the eMMC on /dev/mmcblk0p1. The reason we have for the multiple commands above is to cover both cases, which is also why some of them will fail, and that is just fine.

Option 3

Use this option if you do not have ssh access to the image on the eMMC and you do not have 3 jumper wires available.

  • remove the Bela cape (see here)
  • insert the SD card in the slot
  • press the "USER" button on the BeagleBone (at the back just above the SD card slot) and hold it while powering up the Beaglebone.
  • jump to Common steps below and come back here for the final two steps once you are done
  • power off the board and put the Bela cape back on
  • power on the board. It should now successfully boot from the SD card without need to press the USER button.

Common steps

  • Once the board boots successfully, check that you can load the Bela IDE: open a web browser and go to the address 192.168.7.2 (if you are on Mac or Linux) or 192.168.6.2 (if you are on Windows). You should then run one of the following commands on the board (either at the bottom of the Bela IDE, or after sshing into the board):
    • if you have a Bela image on the eMMC and you want to keep using it in its current state: /opt/Bela/bela_bootloader.sh. This should restore functionality of the image on the eMMC, but if there is an SD card inserted, it will boot from the SD card.
    • if you have a beagleboard.org image on the eMMC, or if you want to update the Bela image on the eMMC with that is on the SD card, then run /opt/Bela/bela_flash_emmc.sh

Backing up your SD card

The simplest, most straightforward way is to make sure that the SD card is inserted and unmount all of its partitions as explained above and then run the following command:

$ sudo dd if=/dev/mydisk of=outputFile.img

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

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

2. (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, run: (Linux only, e.g.: from the BBB)

$ sudo 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 higher value in the "End" column. Pass that value to dd as the count parameter:

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

Copying the SD card to the eMMC

If you want to get rid of the SD card and use only the internal storage, then you can copy the content of the SD card to the eMMC.

When you are ready to copy the SD card to the eMMC, first thing you should backup your SD card, then boot the BeagleBone from the SD card, and run a command in the console at the bottom or the IDE (or from an ssh shell). Which command you run depends on the version of the Bela image you have. To find out what version you have, run:

grep "Bela image" /etc/motd

then, to initiate the copy process, if you are on a v0.2.1 or earlier image, run:

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

otherwise, if you are on a v0.3 or later image, run:

/opt/Bela/bela_flash_emmc.sh

This will take a few minutes to complete and then quit once it's done. Remove the SD card and reboot to verify it is working properly.

Note: the filesystems on the Bela image we provide has the correct size to fit the 4GB available on the eMMC. If you changed the size of the partition at some point, then there may not be enough space in the eMMC for all of your files.

Resizing filesystems on an existing SD card

The images that we provide use smaller filesystem sizes, so that they can be flashed on a small SD cards and also on the BeagleBone's internal eMMC which is just under 4GB. On the other hand, this means you will not be able to use all of the space available on your SD card if it is larger than the size of the image. In order to use all of the space available on your SD card you will need to resize your partition or create a new one.

In this section we are going to show you how to resize the filesystem on your SD card from the command line, from within the BeagleBone itself. If you prefer to use a GUI tool, you can consider GParted, if you are on Linux, or GParted live on a USB stick otherwise.

So, let's get started: for the rest of this guide, we assume that your BeagleBone's network address is 192.168.7.2 and the username is root. You may have to change these values according to your configuration.

NOTE: Needless to say, by following the instructions below YOU MAY LOSE ALL YOUR DATA, so make a backup of your SD card first. Also, note that you cannot use the procedure below to shrink a live filesystem, only to expand it. Shrinking an existing filesystem would cause data loss even if the amount of space in use on the disk is smaller than the new size.

  • Make sure the SD card is properly inserted, connect your BeagleBone to your computer and wait about 30 seconds
  • Open up a terminal window and make sure you can connect to the BeagleBone by typing
$ ssh [email protected]
  • You should now be displayed the prompt root@bela
  • Run
$ fdisk /dev/mmcblk0

where /dev/mmcblk0 is the device file corresponding to your SD card. You are prompted

Command (m for help):

You can now have a look at the help pressing m, if you want.

  • Press p to check the current state of the disk. You will see something like this (note: the actual values displayed depend on the size and content of your SD card).
Disk /dev/mmcblk0: 7969 MB, 7969177600 bytes
4 heads, 16 sectors/track, 243200 cylinders, total 15564800 sectors
Units = sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disk identifier: 0x000a671b

        Device Boot      Start         End      Blocks   Id  System
/dev/mmcblk0p1   *          63      144584       72261    c  W95 FAT32 (LBA)
/dev/mmcblk0p2          144585     6289407     3072411+  83  Linux

The value in MB at the top is the size of your SD card, while the Start and End columns are the boundaries of the partitions, expressed in the Units displayed on the third line (512bytes in this case), while Blocks is the number of blocks in the partition (the unit for Blocks is, confusingly, 1024bytes).

The two partitions /dev/mmcblk0p1 and /dev/mmcblk0p2 are the small FAT32 boot partition (a few MB) and your root filesystem, respectively. In this example you can see that /dev/mmcblk0p2 ends at 6289407*512=3220176384 bytes, that is about 3GB. So there are about 5GB unused in this SD card.

  • We now need to delete the large Linux partition and recreate it. The first sector of the new partition will need to match the one of the old partition, so make a note of the values in the Start column above. Also, the End value of the new partition will have to be greater or equal than the value in the End column.

NOTE: changes made within fdisk are not applied to disk until they are written in the final step, so it is safe to exit (using ctrl-C) at any time.

So let us press d to delete a partition. The successive prompt:

Partition number (1-4):

asks which partition to delete. We want to delete the large Linux partition, which is partition 2 from the list above.

  • Now we create a new primary partition by pressing n.
Command (m for help): n
Partition type:
   p   primary (1 primary, 0 extended, 3 free)
   e   extended
Select (default p):

we want to create a primary partition so we can just press enter. The next prompt is for the partition number:

Partition number (1-4, default 2):

again, we are happy with the default value of 2, as it matches the value of the old partition, so we can just press enter.

Now we need to set the First sector of the partition. This HAS TO match the value of the old partition, which you read earlier. Make sure that either the default value is ok or you enter the correct Start value of the old partition before pressing enter.

First sector (144585-15564799, default 144585):

Last, we are asked for the Last sector. This is the one value that ultimately sets the size of the partition. Again, the value entered here should be greater than End value of the old partition (and NOT the blocks columns), otherwise data loss will occur.

Last sector, +sectors or +size{K,M,G} (144585-15564799, default 15564799):

Again, this value is in 512bytes sectors and the size of the partition will be ( Last sector - First sector )*512bytes. The default value will resize your partition to occupy all the space available on disk. Enter your value of choice, or accept the default, and press enter.

On recent versions of fdisk you may see the following:

Created a new partition 2 of type 'Linux' and of size 14.4 GiB.
Partition #2 contains a ext4 signature.

Do you want to remove the signature? [Y]es/[N]o:

Type N and hit enter.

  • Almost done! If you now use the p command again, you will see your partition with its the new size
Disk /dev/mmcblk0: 7969 MB, 7969177600 bytes
4 heads, 16 sectors/track, 243200 cylinders, total 15564800 sectors
Units = sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disk identifier: 0x000a671b

        Device Boot      Start         End      Blocks   Id  System
/dev/mmcblk0p1   *          63      144584       72261    c  W95 FAT32 (LBA)
/dev/mmcblk0p2          144585     7553023     3704219+  83  Linux
  • Spend one second to check again that Start matches the one of the old partition and End is greater or equal than the old value. Once you are sure everything is alright, press w and enter to write your changes to disk.

You will then see something like this

Command (m for help): w
The partition table has been altered!

Calling ioctl() to re-read partition table.
Re-reading the partition table failed.: Device or resource busy

The kernel still uses the old table. The new table will be used at the next reboot or after you run partprobe(8) or kpartx(8).

Nothing to be worried about.

  • We now need to reboot:
$ reboot
  • After reboot, you can ssh back into the board with
$ ssh [email protected]
  • Now the partition size has changed, but the filesystem hasn't yet. You can run
$ resize2fs /dev/mmcblk0p2

to extend the filesystem to use the whole partition.

The output of the program will look like this

resize2fs 1.42.5 (29-Jul-2012)
Filesystem at /dev/mmcblk0p2 is mounted on /; on-line resizing required
old_desc_blocks = 1, new_desc_blocks = 1
The filesystem on /dev/mmcblk0p2 is now 926054 blocks long.
  • Done! You can test the size of your filesystem with
$ df -h /

which will return something like:

Filesystem      Size  Used Avail Use% Mounted on
/dev/mmcblk0p2  3.5G  1.9G  1.5G  57% /

The Size column tells you the size of the filesystem you extended. The G unit stands for "gigabyte".

Accessing the other card

Whether you are running the operating system, the IDE and the Bela program out of the SD card or the eMMC (the embedded storage), you can still access the one storage device from the other.

They will both show up in your /dev/ folder:

$ ls /dev/mmcbl*
/dev/mmcblk0  /dev/mmcblk0p1  /dev/mmcblk0p2  /dev/mmcblk1  /dev/mmcblk1boot0  /dev/mmcblk1boot1  /dev/mmcblk1p1

The device you booted from will be /dev/mmcblk0 and the other will be /dev/mmcblk1. The file systems are denoted by the sub p1, p2, boot0, boot1 etc. The p0 partitions are the ones that contain configuration files useful for boot and the Linux kernel. /dev/mmcblk0p1 is the device that would show up on your host computer as BELABOOT when you connect Bela to it. The p1 partitions are about 3.5G large by default and will contain most files for the operating system, programs, your home folder and - in the case of a Bela image - the Bela files.

Typically you may want to access the "big" partition on the other device, that is /dev/mmcblk1p1. In order to access those files you need to mount it somewhere in your filesystem. For instance, let's mount it in /root/other/:

(run these commands after you ssh into the BBB from a terminal, or directly in the console at the bottom of the IDE)

  1. create the destination folder if it does not exist:
    mkdir -p /root/other
  2. mount the partition:
    mount /dev/mmcblk1p2 /root/other
  3. you can now access the files stored on the mounted partition, e.g.:
$ ls /root/other/
bin  boot  dev  etc  home  lib  lost+found  media  mnt  opt  proc  root  run  sbin  selinux  srv  sys  tmp  usr  var

Use case

At this point, say that you are running out of space in the device you booted from and you want to write a big file in the home folder of the mounted partition, you would write to file /root/other/root/mynewbigfile.

NOTE: you will need to re-mount the partition after every reboot, or set a rule in fstab to automatically do that.