Run the R1 demo

Use this workshop flow when you want to build a voice-first AI companion locally, then connect an R1 device to that agent through the BK7258 firmware workflow.

What you will build

By the end of this workshop, you will have:

• A local Python-backed Conversational AI quickstart running on your computer
• A browser demo exposed through an ngrok tunnel
• A backend tunnel that the R1 firmware can reach
• BK7258 beken_genie firmware compiled with your Wi-Fi and backend URL settings
• The generated firmware flashed to an R1 development board
• A working voice conversation between the R1 hardware and your agent

Prerequisites

Before you begin, prepare the following:

• Node.js, Bun or npm, Git, and your preferred AI coding tool
• The Agora CLI
• An R1 development board based on BK7258
• A 2.4 GHz Wi-Fi network that the R1 device can join
• A USB cable for the USB TO UART interface
• A firmware flashing tool, such as BKFIL for desktop or a workshop-provided web flashing flow

Install Agora Skills and CLI

Install Agora Skills so your AI coding tool has Agora product context for the workshop:

npx skills add github:AgoraIO/skills

Install the Agora CLI:

curl -fsSL https://dl.agora.io/cli/install.sh | sh
agora --version

After installing the skills and CLI, you can ask your AI coding tool to inspect the quickstart, explain request flow, trace /api/* routes, or customize the agent greeting.

Clone and run the voice agent quickstart

Clone the workshop repository and check out the workshop branch:

git clone https://github.com/AgoraIO-Conversational-AI/agent-quickstart-python.git
cd agent-quickstart-python
git checkout r1-workshop

Install dependencies:

bun install

npm install

Connect the repository to your Agora project:

agora login
agora project create my-first-voice-agent --feature rtc --feature convoai
agora project use my-first-voice-agent
agora project env write server/.env.local --with-secrets

Start the local quickstart:

bun run dev

npm run dev

The quickstart exposes two local services:

Before continuing:

1. Open http://localhost:3000 and confirm the web app loads.
2. Open http://localhost:3000/api/get_config and confirm it returns JSON.
3. Start a conversation session from the web app.
4. Keep this terminal running. You will start ngrok in another terminal.

Configure ngrok URLs

Use ngrok for two separate tasks:

• Expose the web app on port 3000 so people can open the demo in a browser.
• Expose the backend on port 8000 so the R1 device can reach the device protocol.

Keep these URLs separate. The frontend URL is for browser users. The backend URL is the value you compile into firmware as --server-url.

Copy your ngrok auth token from the ngrok dashboard, then authenticate ngrok locally:

ngrok config add-authtoken <YOUR_AUTH_TOKEN>

Share the web demo

In a new terminal, expose the web app:

ngrok http 3000

Copy the HTTPS forwarding URL and treat it as YOUR_FRONTEND_NGROK_URL.

Expose the backend for R1

In another terminal, expose the backend:

ngrok http 8000

Copy the HTTPS forwarding URL and treat it as YOUR_BACKEND_NGROK_URL. Use this value later when you run the firmware setup script.

The backend terminal shows a forwarding URL in the same location as the web demo terminal. Copy the HTTPS URL from the terminal running ngrok http 8000, not the terminal running ngrok http 3000.

Before continuing:

1. Open YOUR_FRONTEND_NGROK_URL and confirm it loads the same web app as http://localhost:3000.
2. Open YOUR_BACKEND_NGROK_URL/get_config and confirm it returns JSON for the IoT device protocol.
3. Keep both ngrok tunnels running while the device is connected.

Prepare the R1 hardware

The R1 development kit integrates the Agora Conversational AI workflow with BK7258 hardware. It supports microphone and speaker I/O, Wi-Fi Station mode, BLE, AEC and NS audio processing, G.711 and G.722 audio codecs, and development interfaces for flashing and debugging.

Before flashing, identify these interfaces on the board:

• USB TO UART interface for flashing and serial debugging
• Speaker and microphone ports for voice input and output
• Reset button for boot or flash recovery
• Side buttons for user input during demos
• USB-C, power, and battery connector paths
• UART expansion pins for debugging or extension

During flashing, keep the reset button accessible. If the flashing tool waits for reset, press the reset button once and continue.

For the reference project, see the Beken AIDK beken_genie documentation.

Create the BK AIDK Codespaces workspace

Open the original factory development environment for the BK hardware:

1. Open the bekencorp/bk_aidk repository.
2. Select the ai_release/v2.0.1 branch.
3. Click Code or +, then create a GitHub Codespaces environment from that branch.

After the Codespace opens, add bk_aidk_codespaces_setup.sh to the root of the bk_aidk workspace. The terminal should already be in the repository root, usually /workspaces/bk_aidk/.

Download the setup script:

curl -fL -o bk_aidk_codespaces_setup.sh \
  https://raw.githubusercontent.com/AgoraIO-Conversational-AI/agent-quickstart-python/r1-workshop/.github/workshop/bk_aidk_codespaces_setup.sh

Make the script executable and run it with your 2.4 GHz Wi-Fi credentials and backend ngrok URL:

chmod +x bk_aidk_codespaces_setup.sh
./bk_aidk_codespaces_setup.sh \
  --ssid "YOUR_WIFI_SSID" \
  --password "YOUR_WIFI_PASSWORD" \
  --server-url "YOUR_BACKEND_NGROK_URL"

Replace YOUR_BACKEND_NGROK_URL with the full HTTPS forwarding URL from ngrok http 8000, for example https://abc123.ngrok-free.app.

Compile the firmware

Run the following block from the Codespaces terminal:

# Install missing Python packages.
pip install click future click_option_group cryptography pycryptodome

# Point the build to the Codespaces Python runtime.
export PYTHON=/home/codespace/.python/current/bin/python
export PATH=/home/codespace/.python/current/bin:$PATH
export ARMINO_PATH=/workspaces/bk_aidk/bk_avdk/bk_idk
export PYTHON_EXECUTABLE=$PYTHON

unset PYTHONNOUSERSITE
$PYTHON -m pip install --user --force-reinstall "setuptools==80.9.0"

# Confirm the Python runtime and package path before compiling.
$PYTHON - <<'PY'
import sys
print(sys.executable)
print(sys.version)
import pkg_resources
print(pkg_resources.__file__)
PY

# Compile.
make bk7258 PROJECT=beken_genie

When the build finishes, locate the generated firmware artifact. The expected output is an all-app.bin file under the build/beken_genie/bk7258 output tree. Use that file for flashing unless the workshop host provides a prebuilt firmware binary.

If you need to find the artifact, run:

python3 - <<'PY'
from pathlib import Path
for path in Path("build/beken_genie").rglob("all-app.bin"):
    print(path)
PY

For lower-level flashing details, see the Beken firmware flashing documentation.

Flash the firmware

Use either desktop BKFIL or the workshop-provided web flashing flow.

Option A: Desktop BKFIL

For macOS, use the BKFIL macOS package, unless your workshop host provides a different version.

1. Connect the board over USB.
2. Choose the correct serial port.
3. Select the generated all-app.bin file, or a workshop-provided firmware binary.
4. Set the baudrate, commonly 1500000.
5. Start flashing.
6. If prompted, press reset on the board.
7. Wait for the success message before unplugging or rebooting the device.

Option B: Web BKFIL

1. Open the BKFIL web UI provided by the workshop host.
2. Select the serial port from the dropdown.
3. Confirm the baud settings, such as 1500000 and AppResetBaud 115200 when required.
4. Select the generated all-app.bin file.
5. Start download or flash.
6. Reset the chip if prompted.
7. Wait for erase and download progress to complete.

Validate the workshop

Confirm each item before considering the workshop complete:

• The local quickstart starts without backend or credential errors.
• http://localhost:3000 loads the web app.
• http://localhost:3000/api/get_config returns JSON.
• YOUR_FRONTEND_NGROK_URL loads the web app.
• YOUR_BACKEND_NGROK_URL/get_config returns JSON.
• bk_aidk_codespaces_setup.sh was run with the 2.4 GHz Wi-Fi credentials and YOUR_BACKEND_NGROK_URL.
• The firmware build produces all-app.bin.
• The board appears on a valid serial port.
• The flash process completes successfully.
• The device captures microphone input.
• The agent returns audio through the device speaker.
• Transcript or voice interaction works in the web UI.

Troubleshooting

Useful commands

Use these commands from the agent-quickstart-python repository:

# full local stack
bun run dev

# health checks
bun run doctor
bun run doctor:local

# verification
bun run verify
bun run verify:local
bun run verify:web

# full local stack
npm run dev

# health checks
npm run doctor
npm run doctor:local

# verification
npm run verify
npm run verify:local
npm run verify:web