Debian: Getting Started with the BeagleBone Black

Embedded Linux Guides
1

This is a page about BeagleBoard’s TI Cortex-A8 based; BeagleBone Black.

Availability

Boards:

Power Supplies:

Serial Cable:

Basic Requirements

Learning

Cross Compiler: 32bit arm-linux-gnueabi-gcc

This is a pre-built (64bit) version of GCC that runs on generic linux, sorry (32bit) x86 users, it’s time to upgrade…

Download/Extract:

#user@localhost:~$
wget -c https://mirrors.edge.kernel.org/pub/tools/crosstool/files/bin/x86_64/11.5.0/x86_64-gcc-11.5.0-nolibc-arm-linux-gnueabi.tar.xz
tar -xf x86_64-gcc-11.5.0-nolibc-arm-linux-gnueabi.tar.xz
export CC32=`pwd`/gcc-11.5.0-nolibc/arm-linux-gnueabi/bin/arm-linux-gnueabi-

Test Cross Compiler:

#user@localhost:~$
${CC32}gcc --version

#Test Output:
arm-linux-gnueabi-gcc (GCC) 11.5.0
Copyright (C) 2021 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Bootloader:

Pre install a few host packages with build-essential and git, which will be utilized to build everything else.

Host Package Requirements

#user@localhost:~$
sudo apt update ; \
sudo apt-get install -y build-essential git

Bootloader: U-Boot

Das U-Boot – the Universal Boot Loader: http://www.denx.de/wiki/U-Boot

Host Package Requirements

#user@localhost:~$
sudo apt update ; \
sudo apt-get install -y bc bison flex libgnutls28-dev ; \
sudo apt-get install -y libssl-dev python3-dev python3-minimal ; \
sudo apt-get install -y python3-setuptools swig uuid-dev

Download:

#user@localhost:~$
git clone -b v2022.04-bbb.io-am335x-am57xx https://github.com/beagleboard/u-boot.git --depth=1

Configure and Build:

#user@localhost:~$
make -C ./u-boot/ CROSS_COMPILE=${CC32} am335x_evm_defconfig ; \
make -C ./u-boot/ -j4 CROSS_COMPILE=${CC32}

Copy Build Objects:

#user@localhost:~$
mkdir -p ./fs/ ; \
cp -v ./u-boot/MLO ./fs/ ; \
cp -v ./u-boot/u-boot-dtb.img ./fs/

Linux Kernel

This script will build the kernel, modules, device tree binaries and copy them to the deploy directory.

Download:

#user@localhost:~$
git clone https://github.com/RobertCNelson/bb-kernel ./kernelbuildscripts
cd kernelbuildscripts/

For am33x-v6.12 (Longterm 6.12.x):

#user@localhost:~/kernelbuildscripts$
git checkout origin/am33x-v6.12 -b tmp

Build:

#user@localhost:~/kernelbuildscripts$
./build_kernel.sh

Root File System

Debian 13

User Password
debian temppwd

Download:

#user@localhost:~$
wget -c https://rcn-ee.com/rootfs/eewiki/minfs/debian-13.1-base-armhf-2025-11-14.tar.xz

Verify:

#user@localhost:~$
sha256sum debian-13.1-base-armhf-2025-11-14.tar.xz

#sha256sum output:
214ad3de55cc612a3eff8d5782e5ec6f55925564bd9b887c2ac613403f4f7570  debian-13.1-base-armhf-2025-11-14.tar.xz

Extract:

#user@localhost:~$
tar xf debian-13.1-base-armhf-2025-11-14.tar.xz

Install Kernel and Root File System

To help new users, since the kernel version can change on a daily basis. The kernel building scripts listed on this page will now give you a hint of what kernel version was built.

-----------------------------
Script Complete
eewiki.net: [user@localhost:~$ export kernel_version=5.X.Y-Z]
-----------------------------

Copy and paste that “export kernel_version=5.X.Y-Z” exactly as shown in your own build/desktop environment and hit enter to create an environment variable to be used later.

export kernel_version=5.X.Y-Z

Create Root File System with genimage:

The genimage https://github.com/pengutronix/genimage tool is now used to generate a sdcard.img vs directly interfacing with the microSD.

Host Package Requirements

#user@localhost:~$
sudo apt update ; \
sudo apt-get install -y dosfstools genimage mtools

Copy Root File System

#Debian; Root File System: user@localhost:~$
sudo tar xfvp ./debian-*-*-armhf-*/armhf-rootfs-*.tar -C ./fs/fs-rootfs/
sync

Enable first boot customization

#user@localhost:~$
sudo cp ./fs/fs-rootfs/etc/bbb.io/templates/sysconf.txt ./fs/fs-bootfs/

Open ./fs/fs-bootfs/sysconf.txt in your text editor and change any user setting.

  • user_name=
  • user_password=
  • hostname=
#user@localhost:~$
sudo nano ./fs/fs-bootfs/sysconf.txt

Set uname_r in /boot/uEnv.txt

#user@localhost:~$
sudo sh -c "echo 'uname_r=${kernel_version}' >> ./fs/fs-rootfs/boot/uEnv.txt"
sudo sh -c "echo 'cmdline=fsck.repair=yes earlycon net.ifnames=0' >> ./fs/fs-rootfs/boot/uEnv.txt"

Copy Kernel Image

Kernel Image:

#user@localhost:~$
sudo cp -v ./kernelbuildscripts/deploy/${kernel_version}.zImage ./fs/fs-rootfs/boot/vmlinuz-${kernel_version}

Copy Kernel Device Tree Binaries

#user@localhost:~$
sudo mkdir -p ./fs/fs-rootfs/boot/dtbs/${kernel_version}/
sudo tar xfv ./kernelbuildscripts/deploy/${kernel_version}-dtbs.tar.gz -C ./fs/fs-rootfs/boot/dtbs/${kernel_version}/

Copy Kernel Modules

#user@localhost:~$
sudo tar xfv ./kernelbuildscripts/deploy/${kernel_version}-modules.tar.gz -C ./fs/fs-rootfs/usr/

File Systems Table (/etc/fstab)

#user@localhost:~/$
sudo sh -c "echo '/dev/mmcblk0p2  /  auto  errors=remount-ro  0  1' >> ./fs/fs-rootfs/etc/fstab"
sudo sh -c "echo '/dev/mmcblk0p1  /boot/firmware  vfat user,uid=1000,gid=1000,defaults 0 2' >> ./fs/fs-rootfs/etc/fstab"

Create sdcard.img with genimage

The genimage https://github.com/pengutronix/genimage tool is now used to generate a sdcard.img vs directly interfacing with the microSD.

Create genimage.cfg file

#user@localhost:~$
nano genimage.cfg

#genimage.cfg
image sdcard.img {
        hdimage {
                partition-table-type = "mbr"
        }
        partition MLO {
                in-partition-table = "no"
                image = "MLO"
                offset = 128K
        }
        partition u-boot {
                in-partition-table = "no"
                image = "u-boot-dtb.img"
                offset = 384K
        }
        partition boot {
                bootable = "true"
                partition-type = 0xc
                image = "boot.vfat"
                offset = 4M
        }
        partition rootfs {
                partition-type = 0x83
                image = "rootfs.ext4"
        }
}
image boot.vfat {
        size = 36M
        vfat {
                label = "BOOT"
        }
        mountpoint = "fs-bootfs"
}
image rootfs.ext4 {
        size = "120%"
        ext4 {
                label = "rootfs"
        }
        mountpoint = "fs-rootfs"
}

Run genimage on genimage.cfg

#user@localhost:~$
sudo genimage --rootpath fs --inputpath fs --config genimage.cfg

genimage output

sdcard.img can be flashed to a microSD using bb-imager-rs https://github.com/beagleboard/bb-imager-rs or rpi-imager https://github.com/raspberrypi/rpi-imager or your favorite image writing software.

#user@localhost:~$
tree images/
images/
└── sdcard.img

1 directory, 1 file

Final Tweaks (extend rootfs partition)

At this point you are running on your target board with the flashed sdcard.img.

Extend the rootfs partition to fill available space on drive.

Use growpart to extend a partition in a partition table

sudo growpart /dev/mmcblk0 2

voodoo@eewiki:~$ sudo growpart /dev/mmcblk0 2
CHANGED: partition=2 start=524289 old: size=3276800 end=3801088 new: size=61809630 end=62333918

First Reboot

sudo reboot

Use resize2fs to enlarge the existing filesystem

sudo resize2fs /dev/mmcblk0p2

voodoo@eewiki:~$ sudo resize2fs /dev/mmcblk0p2
resize2fs 1.47.0 (5-Feb-2023)
Filesystem at /dev/mmcblk0p2 is mounted on /; on-line resizing required
old_desc_blocks = 1, new_desc_blocks = 4
The filesystem on /dev/mmcblk0p2 is now 7726203 (4k) blocks long.

Second Reboot

This last reboot will take awhile as fsck is checking the partition on bootup.

sudo reboot
### HDMI
This sections assumes you have already installed your favorite xorg based window manager, such as lxde, xfce, kde, gnome, etc... These are packages that need to be installed on top of your selected windows manager and an xorg.conf needed to correctly setup the video interface.
*Note: If the cursor doesn\'t show up right away, first hit: ctlr-alt-f1 then: ctrl-alt-f7 after which it \'should\' show up...*
Make sure to install, fbdev driver and xrandr utilities:
```bash
sudo apt update
sudo apt install read-edid xserver-xorg-video-fbdev x11-xserver-utils

#/etc/X11/xorg.conf
Section "Monitor"
        Identifier      "Builtin Default Monitor"
EndSection
Section "Device"
        Identifier      "Builtin Default fbdev Device 0"
        Driver          "fbdev"
EndSection
Section "Screen"
        Identifier      "Builtin Default fbdev Screen 0"
        Device          "Builtin Default fbdev Device 0"
        Monitor         "Builtin Default Monitor"
EndSection
Section "ServerLayout"
        Identifier      "Builtin Default Layout"
        Screen          "Builtin Default fbdev Screen 0"
EndSection

xrandr:

xrandr
xrandr --output HDMI-0 --mode 1024x768 --rate 60

xrandr (over serial/ssh)

xrandr -display :0.0 -q
xrandr -display :0.0 --output HDMI-0 --mode 1024x768 --rate 60

U-Boot Overlays

Full Documentation: [readme|Making sure you're not a bot!]
Enable:

#/boot/uEnv.txt
enable_uboot_overlays=1

To Disable: eMMC:

#/boot/uEnv.txt
disable_uboot_overlay_emmc=1

To Disable: HDMI VIDEO & AUDIO:

#/boot/uEnv.txt
disable_uboot_overlay_video=1

To Disable: HDMI AUDIO:

#/boot/uEnv.txt
disable_uboot_overlay_audio=1

To Disable: WL1835:

#/boot/uEnv.txt
disable_uboot_overlay_wireless=1

U-Boot: override detected capes

#/boot/uEnv.txt
uboot_overlay_addr0=<file0>.dtbo
uboot_overlay_addr1=<file1>.dtbo
uboot_overlay_addr2=<file2>.dtbo
uboot_overlay_addr3=<file3>.dtbo

U-Boot: disable auto-loading of detected capes

#/boot/uEnv.txt
disable_uboot_overlay_addr0=1
disable_uboot_overlay_addr1=1
disable_uboot_overlay_addr2=1
disable_uboot_overlay_addr3=1

U-Boot: load 4 more un-detected capes

#/boot/uEnv.txt
uboot_overlay_addr4=<file4>.dtbo
uboot_overlay_addr5=<file5>.dtbo
uboot_overlay_addr6=<file6>.dtbo
uboot_overlay_addr7=<file7>.dtbo

Comments

Any questions or comments please go to our TechForum: TechForum