Demos and Tutorials

The fastest way to see what BeagleBadge can do is to write the demo image to a microSD card and boot from it. Nothing on the board is overwritten, so you can return to whatever was installed before by removing the card.

Embedded World 2026 demo image

An Armbian image built for Embedded World 2026 is published on the BeagleBoard.org distros page. It is a minimal Debian trixie userland with the BeagleBadge device tree and ePaper support already in place.

Image	Armbian BeagleBadge demo for EW 2026
Version	Armbian 26.02.0-trunk, Debian trixie, kernel 6.12.57, minimal
File	Armbian-EW_root_beagle_26.02.0-trunk_Beaglebadge_trixie_vendor-edge_6.12.57_minimal.img.xz.zip
SHA256	6b1dbb155a22e2ed72dd868996fabfbf7aa69ae0432dc43f86214ca7b34628f6

Download and verify

Download the image from the distros page above, then check it against the published checksum before writing it:

Linux

sha256sum Armbian-EW_root_beagle_*.img.xz.zip

macOS

shasum -a 256 Armbian-EW_root_beagle_*.img.xz.zip

Windows

certutil -hashfile Armbian-EW_root_beagle_*.img.xz.zip SHA256

The download is a .zip wrapping an .img.xz. Extract the .zip first so that you are left with a single .img.xz file, which both of the writers below accept directly, there is no need to decompress it any further.

Write the image to a microSD card

You need a microSD card of 8GB or larger and a card reader.

Tip

If you are using a Linux system, you can write the image from the command line with xzcat Armbian-EW_root_beagle_*.img.xz | sudo dd of=/dev/sdX bs=4M conv=fsync where /dev/sdX is the device name of your card. Check it carefully before running the command, as it will overwrite whatever is on that device.

Important

Writing the image to the card will erase whatever is on it. Make sure you have selected the correct device before proceeding.

bb-imager

Download and install bb-imager for your operating system, then:

1. Click CHOOSE DEVICE. If BeagleBadge is not in the list, pick No filtering so that every image type is offered.

2. Click CHOOSE OS, scroll to the bottom and select Use custom image, then browse to the .img.xz you extracted.

3. Click CHOOSE STORAGE and select your microSD card. Check the device size carefully before continuing.

4. Click NEXT and confirm. Skip the customisation settings. The demo image supplies its own configuration.

5. Wait for writing and verification to finish, then eject the card.

Tip

The same walkthrough with screenshots, for a board that is listed by name, is in the BeagleY-AI quick start. The only step that differs for BeagleBadge is choosing a custom image instead of a named OS.

balenaEtcher

Download and install balenaEtcher, then:

1. Click Flash from file and select the .img.xz.

2. Click Select target and choose your microSD card.

3. Click Flash and wait for the write and validation to complete.

Etcher decompresses the image as it writes, so the .img.xz does not need to be unpacked first.

Boot from the microSD card

1. Insert the microSD card into the socket on the back of the board.

2. Hold down SELECT on the front.

3. While still holding SELECT, switch the board ON by simply connecting a USB Type-C cable, or press the Power button if it is running from a battery.

4. Release SELECT after a couple of seconds. The boot device is chosen the moment power is applied.

To boot from the card again after a RESET, switch the board OFF and ON with SELECT held. RESET keeps the current boot device. See Boot Modes.

If the board does not start from the card, it has moved on to its backup boot device, USB DFU, and is waiting on the USB connection. Check that the image was written to the whole card rather than to a partition on it, that the card is fully seated, and that SELECT was held until power was applied.

Watching it boot

If you want to see what is happening rather than guess, attach a serial console over the same USB-C cable that powers the board and watch the boot log. Settings are in Serial debug.

Todo

Add a photograph of the EW 2026 demo on the ePaper panel, and describe what it shows at first boot and what the joystick, BACK and SELECT do within it.

Tutorials

The tutorials below are still to be written. Each one is a page under boards/beaglebadge/demos-and-tutorials/, added to a toctree here in the same way as Demos and Tutorials.

Display

Todo

Draw to the ePaper panel from Linux.

Todo

Build an interface for the ePaper panel with LVGL.

Todo

Drive the ePaper panel from MicroPython.

Todo

Compare full and partial refresh of the ePaper panel, and what each costs in battery life.

Sensors

Todo

Read the IMU, including tap and orientation detection. See Sensors.

Todo

Read the ambient light sensor through ADC0_AIN2.

Todo

Rotate the display to match the orientation reported by the IMU.

Controls and indicators

Todo

Read the joystick and buttons as Linux input events. See Buttons and joystick.

Todo

Drive the RGB status LED.

Todo

Drive the 7-segment digits through the MCP23S18 expander, using the segment mapping in Indicators and buzzer.

Todo

Play tones on the passive buzzer.

Wireless

Todo

Join a Wi-Fi network, including switching the radio’s power on. See Wi-Fi and Bluetooth.

Todo

Use Bluetooth Low Energy.

Todo

Send and receive LoRa messages. See LoRa.

Todo

Run Meshtastic for off-grid messaging.

Todo

Set up the ActivityPub integration.

Expansion

Todo

Add a QWIIC sensor. See QWIIC connectors.

Todo

Add a Grove module. See Grove connector.

Todo

Use a mikroBUS Click board. See mikroBUS socket.

Power

Todo

Read state of charge from the BQ27220 fuel gauge. See Battery charging and power path.

Todo

Measure battery life and extend it with the SoC low power modes. See Low power modes.

Zephyr

BeagleBadge has an upstream Zephyr board port, with the board target beaglebadge/am62l3/a53. Building and running a Zephyr application is covered in Running Zephyr.