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:

• A macOS or Linux computer. On Windows, use WSL, because the quickstart scripts require a Bash shell.
• Bun, Python 3.10 or later with the venv module, Node.js, Git, and your preferred AI coding tool
• The Agora CLI
• An ngrok account and the ngrok agent installed
• A GitHub account that can create GitHub Codespaces
• 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 Mac to run the BKFIL flashing tool

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

1. Clone the quickstart repository and check out the r1-demo branch. This branch adds the backend routes that the R1 firmware calls:

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

2. Sign in to Agora and select the project to use. If you already have a project with Conversational AI enabled, skip agora project create and pass your project name to agora project use:

   agora login
   agora project create my-first-voice-agent
   agora project use my-first-voice-agent

3. Install dependencies, write your project credentials to server/.env, and check the setup:

   bun run setup
   agora quickstart env write .
   bun run doctor:local

4. Start the local quickstart:

   bun run dev

   The quickstart serves the web app at http://localhost:3000 and the local backend at http://localhost:8000.

5. Verify the quickstart:

   • Open http://localhost:3000 and confirm the web app loads.
   • Open http://localhost:3000/api/get_config and confirm it returns JSON.
   • Click Start Conversation, allow microphone access, and confirm that the agent greets you and answers a question.

Keep this terminal running. You start ngrok in another terminal in the next section.

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.

On a free ngrok plan, the browser shows an ngrok warning page the first time you open each URL. Click Visit Site to continue. The warning page does not affect requests from the R1 device.

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-demo/.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

Flash the firmware

Flash the firmware with the Beken Flash Image Loader (BKFIL) for macOS. Download the all-app.bin file from your Codespace to your computer first. In the Codespaces file explorer, right-click the file and select Download.

If you use Windows, see the Beken firmware flashing documentation.

1. Download and unzip the BKFIL macOS package, then open BKFIL.

2. Connect the board to your computer using the USB TO UART interface.

3. Click Select Port and choose the USB serial port, for example /dev/cu.usbserial-1130.

4. Set Baud to 1500000 and AppResetBaud to 115200, then click OK.

   

5. In the BIN section, select your all-app.bin file.

6. Click Download.

7. If the log shows Please reset the chip and Waiting reset, press the reset button on the board once.

   

8. Wait for erase and download to reach 100% before you unplug or restart the device.

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