Search

Bela Gem Get Started Guide

Get up and running with Bela Gem.

Bela Gem is our next‑generation embedded audio and sensor platform built around PocketBeagle 2 (PB2). This guide walks you from an unopened box to running your first project.

To learn how to port your old Bela projects to the new family of boards, see the migration guide.

Table of contents

  1. What You’ll Need
  2. Download the Bela Gem Image
  3. Flash the microSD Card
  4. Assemble Your Hardware
  5. Power Up & First Boot
  6. Open the Bela IDE
  7. Take a Quick Tour of the IDE
  8. Run Your First Example
  9. Updating the System (Optional but Recommended)
  10. Next Steps

What You’ll Need

Before you begin:

  • PocketBeagle 2 (PB2) — the single‑board computer that powers Bela Gem
  • Bela Gem Stereo or Bela Gem Multi board
  • microSD card (≥16GB, Class 10 recommended)
  • USB‑C cable to connect the PB2 to your computer
  • A computer with a web browser
  • Optional: headphones, speakers, audio cables, sensors
Tip

If you bought a pre‑flashed SD card from Bela, you can skip ahead to Assemble Your Hardware

Download the Bela Gem Image

The Bela Gem system runs from the microSD card. You’ll need to download and flash the official Bela Gem image before first boot.

Download the latest image here.

This is a .img.xz archive containing the full SD card image. When using the recommended tool per the instructions below, there is no need to uncompress. If you use Balena Etcher, you should uncompress it before flashing it.

Flash the microSD Card

You’ll now write the system image to your microSD card.

Beagleboard Imaging Utility works on macOS, Windows, and Linux and handles compressed images automatically.

  1. Download the imager from: https://beagleboard.github.io/bb-imager-rs/
  2. Insert your microSD card into your computer (use an adapter if needed)
  3. Open the program and:
    • Click Chose Device → select PocketBeagle 2
    • Click Chose Image → select Custom Image at the bottom of the list and select the file you downloaded in the following dialog
    • Click Chose Destination → select the SD card (often called FDisk)
    • Click Write

Wait for the imager to finish writing and verifying the card.

Important

Flashing will erase all data on the microSD card.

Advanced Users (Linux / macOS)

You can also use dd or similar command‑line tools. For more information, see Managing your SD card.

Make sure you select the correct device — writing to the wrong disk can erase your system.

Assemble Your Hardware

  1. Insert the flashed microSD card into the PB2’s microSD slot.
  2. Carefully mount PocketBeagle 2 onto the Bela Gem headers, ensuring the pins and sockets are aligned. The USB port on the Bela Gem should be above the USB-C port on the PB2. Apply an even, firm pressure until the pins of the Bela Gem are fully inserted into the sockets on the PB2.
  3. Attach the baseplate and spacers, securing with the supplied screws.

Bela Gem Multi

  1. Attach the wing PCBs which provide 3.5mm TRS jacks for each audio input and output channel.

Power Up & First Boot

  • Connect the USB‑C cable from the PocketBeagle 2 to your computer.
  • When powered over USB‑C, PocketBeagle 2 will boot automatically from the microSD card. After 5-10 seconds, you should see the power light on the Bela Gem change from solid blue to blinking in a heartbeat pattern.
  • The board takes about 90 seconds for the first boot, at which point you can proceed to the next step.

Open the Bela IDE

Bela Gem hosts the Bela IDE directly on the board, no internet connection needed. You can use your browser to connect directly with the board.

  1. Open your web browser
  2. Go to: http://bela.local (important: use http, not https)

You should see the Bela IDE interface — this is where you write, build, and run projects on the board.

If bela.local doesn’t Load

Try one of the following:

  • Wait another 30-60 seconds and refresh
  • Make sure the blue power LED on the P2 side is blinking, not solid (blinking means the PB2 is running)
  • Try http://192.168.7.2 in your browser
  • If using Windows 10 try http://192.168.6.2
  • Check that your USB-C cable supports data, not just power

Take a Quick Tour of the IDE

Inside the IDE you’ll find:

  • Editor — write code and documentation
  • Run / Stop buttons — compile and run on the board
  • Console — system messages and program output
  • Side tab — examples, project files, settings, pin diagram and board tools
  • Signal monitor and oscilloscope - monitor the status of I/O pins and signals on your board

For a full walkthrough, see: Get to know the IDE

Run Your First Example

The best place to start is the project which is automatically opened when you boot the board, basic.

Click Run to start the project. The Run button will turn yellow and spin while the code compiles. The first time you boot the board, or after an update, it may take several minutes to compile the Bela core. Thereafter, compiling projects will be much quicker.

When finished, the button will turn green and spin quickly, and you will see the LED next to the button on the Bela Gem begin to blink quickly. If you have headphones or speakers connected, you should hear audio output from Bela Gem.

Check out the readme.md file for more information.

Once you’re up and running, check for system and IDE updates:

  1. Open the Settings tab in the side menu of the IDE
  2. Look for Other System Functions options
  3. Click Check for Updates
  4. Follow the on‑screen instructions
  5. If you encounter issues, solve or report them here.

This keeps your board aligned with the latest examples, documentation, and performance improvements.

Tip

With an internet connection on your computer you can update the board automatically, no need to download anything, just follow the steps in the IDE.

Next Steps

Now that Bela Gem is running, you can:

<< Previous: Hello World
Next: Bela Gem Get Started >>