# Debian: Getting Started with the BeagleBone Black

**URL:** <https://forum.digikey.com/t/debian-getting-started-with-the-beaglebone-black/12967>\
**Category:** Linux Guides\
**Created:** [March 24, 2021, 9:28pm UTC](https://forum.digikey.com/t/debian-getting-started-with-the-beaglebone-black/12967 "2021-03-24T21:28:32Z")\
**Posts on this page:** 5\
**Page:** 1

<div class="post-metadata">

**Author:** ![RobertCNelson](https://sea2.discourse-cdn.com/digikey/user_avatar/forum.digikey.com/robertcnelson/32/12_2.png) [@RobertCNelson](https://forum.digikey.com/u/RobertCNelson)\
**Post date:** [March 24, 2021, 9:28pm UTC](https://forum.digikey.com/t/debian-getting-started-with-the-beaglebone-black/12967/1 "2021-03-24T21:28:32Z")

</div>

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

# Availability

Boards:

- [BeagleBone Black (Seeed)](https://www.digikey.com/en/products/detail/beagleboard-by-seeed-studio/102110420/12719590) at DigiKey
- [BeagleBone Black (GHI RevC)](https://www.digikey.com/en/products/detail/ghi-electronics-llc/BBB01-SC-505/6210999) at DigiKey
- [BeagleBone Black Industrial (Seeed RevD)](https://www.digikey.com/en/products/detail/beagleboard-by-seeed-studio/102110423/12342853) at DigiKey
- [BeagleBone Green (Seeed)](https://www.digikey.com/en/products/detail/seeed-technology-co-ltd/102010027/5482485) at DigiKey
- [BeagleBone Green Wireless (Seeed)](https://www.digikey.com/en/products/detail/seeed-technology-co-ltd/102010048/5965297) at DigiKey

Power Supplies:

- [USB Micro for BeagleBone Green](https://www.digikey.com/en/products/detail/phihong-usa/PSA10F-050-R/4935858) at DigiKey

Serial Cable:

- [(USB to serial adapter) TTL-232R-3V3](https://www.digikey.com/en/products/detail/ftdi-future-technology-devices-international-ltd/TTL-232R-3V3/1836393) at DigiKey
- [Raspberry Pi Serial Probe](https://www.digikey.com/en/products/detail/raspberry-pi/SC0889/17877576) at DigiKey

# Basic Requirements

- Running a recent supported release of Debian, Fedora or Ubuntu on a x86 64bit based PC; without OS Virtualization Software.
- Many of the listed commands assume /bin/bash as the default shell.
- [Kernel.org](http://Kernel.org) Cross Compilers – [https://mirrors.edge.kernel.org/pub/tools/crosstool/](https://mirrors.edge.kernel.org/pub/tools/crosstool/)
- Bootloader
  - Das U-Boot – the Universal Boot Loader: [http://www.denx.de/wiki/U-Boot](http://www.denx.de/wiki/U-Boot)
  - Source: [https://github.com/u-boot/u-boot/](https://github.com/u-boot/u-boot/)

- Linux Kernel
  - Linus’s Mainline tree: [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git)

- ARM based rootfs
  - Debian: [https://www.debian.org](https://www.debian.org)

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

```bash
#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:

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

```

```bash
#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**

```bash
#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](http://www.denx.de/wiki/U-Boot)

**Host Package Requirements**

```bash
#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:

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

```

Configure and Build:

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

```

Copy Build Objects:

```bash
#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:

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

```

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

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

```

Build:

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

```

# Root File System

### Debian 13

| User | Password |
| --- | --- |
| debian | temppwd |

Download:

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

```

Verify:

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

```

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

```

Extract:

```bash
#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.

```bash
-----------------------------
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.

```bash
export kernel_version=5.X.Y-Z

```

### Create Root File System with genimage:

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

**Host Package Requirements**

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

```

### Copy Root File System

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

```

### Enable first boot customization

```bash
#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=** _

```bash
#user@localhost:~$
sudo nano ./fs/fs-bootfs/sysconf.txt

```

### Set uname\_r in /boot/uEnv.txt

```bash
#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:

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

```

### Copy Kernel Device Tree Binaries

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

```

### Copy Kernel Modules

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

```

### File Systems Table (/etc/fstab)

```bash
#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](https://github.com/pengutronix/genimage) tool is now used to generate a sdcard.img vs directly interfacing with the microSD.

### Create genimage.cfg file

```bash
#user@localhost:~$
nano genimage.cfg

```

```bash
#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

```bash
#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](https://github.com/beagleboard/bb-imager-rs) or rpi-imager [https://github.com/raspberrypi/rpi-imager](https://github.com/raspberrypi/rpi-imager) or your favorite image writing software.

```bash
#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

```bash
sudo growpart /dev/mmcblk0 2

```

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

```

### First Reboot

```bash
sudo reboot

```

### Use resize2fs to enlarge the existing filesystem

```bash
sudo resize2fs /dev/mmcblk0p2

```

```bash
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.

````bash
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

````

```bash
#/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:

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

```

xrandr over serial/ssh

```bash
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!](https://elinux.org/Beagleboard:BeagleBoneBlack_Debian#U-Boot_Overlays)]  
Enable:

```bash
#/boot/uEnv.txt
enable_uboot_overlays=1

```

To Disable: eMMC:

```bash
#/boot/uEnv.txt
disable_uboot_overlay_emmc=1

```

To Disable: HDMI VIDEO & AUDIO:

```bash
#/boot/uEnv.txt
disable_uboot_overlay_video=1

```

To Disable: HDMI AUDIO:

```bash
#/boot/uEnv.txt
disable_uboot_overlay_audio=1

```

To Disable: WL1835:

```bash
#/boot/uEnv.txt
disable_uboot_overlay_wireless=1

```

U-Boot: override detected capes

```bash
#/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

```bash
#/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

```bash
#/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](https://forum.digikey.com/c/embedded/linux-discussions/5)

---

<div class="post-metadata">

**Author:** ![RobertCNelson](https://sea2.discourse-cdn.com/digikey/user_avatar/forum.digikey.com/robertcnelson/32/12_2.png) [@RobertCNelson](https://forum.digikey.com/u/RobertCNelson)\
**Post date:** [December 1, 2025, 8:33pm UTC](https://forum.digikey.com/t/debian-getting-started-with-the-beaglebone-black/12967/9 "2025-12-01T20:33:29Z")

</div>

Split this topic on December 1, 2025, 8:33pm UTC

2 posts were split to a new topic: [AM335x - config-pin](https://forum.digikey.com/t/am335x-config-pin/62852)

---

<div class="post-metadata">

**Author:** ![RobertCNelson](https://sea2.discourse-cdn.com/digikey/user_avatar/forum.digikey.com/robertcnelson/32/12_2.png) [@RobertCNelson](https://forum.digikey.com/u/RobertCNelson)\
**Post date:** [June 3, 2026, 12:57pm UTC](https://forum.digikey.com/t/debian-getting-started-with-the-beaglebone-black/12967/10 "2026-06-03T12:57:58Z")

</div>

Split this topic on June 3, 2026, 12:57pm UTC

A post was split to a new topic: [BeagleBone Black Learning](https://forum.digikey.com/t/beaglebone-black-learning/69407)

---

<div class="post-metadata">

**Author:** ![RobertCNelson](https://sea2.discourse-cdn.com/digikey/user_avatar/forum.digikey.com/robertcnelson/32/12_2.png) [@RobertCNelson](https://forum.digikey.com/u/RobertCNelson)\
**Post date:** [June 4, 2026, 1:26pm UTC](https://forum.digikey.com/t/debian-getting-started-with-the-beaglebone-black/12967/11 "2026-06-04T13:26:21Z")

</div>

Split this topic on June 4, 2026, 1:26pm UTC

3 posts were split to a new topic: [Getting Started with the BeagleBone Black Changes](https://forum.digikey.com/t/getting-started-with-the-beaglebone-black-changes/69439)

---

<div class="post-metadata">

**Author:** ![RobertCNelson](https://sea2.discourse-cdn.com/digikey/user_avatar/forum.digikey.com/robertcnelson/32/12_2.png) [@RobertCNelson](https://forum.digikey.com/u/RobertCNelson)\
**Post date:** [June 30, 2026, 2:52pm UTC](https://forum.digikey.com/t/debian-getting-started-with-the-beaglebone-black/12967/12 "2026-06-30T14:52:51Z")

</div>

Split this topic on June 30, 2026, 2:52pm UTC

4 posts were split to a new topic: [BBB: custom: bb.org-debian-trixie-base-v6.18-armhf-am335x.conf](https://forum.digikey.com/t/bbb-custom-bb-org-debian-trixie-base-v6-18-armhf-am335x-conf/70157)