Skip to content

docs(site): focus published docs on AkidaTag #96

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nikunj95 merged 2 commits into from
Sep 27, 2026
Merged

docs(site): focus published docs on AkidaTag #96

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
975fb89
docs(site): focus published docs on AkidaTag
nikunj95 Sep 27, 2026
1f44ba1
fix(docs): correct setup command continuations
nikunj95 Sep 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 16 additions & 25 deletions docs/developer-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,6 @@ If you only want to run the demos from your phone, read the [user guide](user-gu
| Part | What it is |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Board | AkidaTag: a Nordic nRF5340 (the application core runs this firmware, the network core runs the Bluetooth controller) and a BrainChip Akida AKD1500 neural processor connected over SPI, with a PDM microphone, an ISM330 accelerometer and gyroscope, a BQ27427 fuel gauge, two INA190 current monitors, a CP2105 USB-to-UART bridge behind the USB-C connector, a red and a green LED. The AKD1500 has its own SPI flash, which holds the model. |
| Bench alternative | An nRF5340 DK with an AKD1500 PCIe card in SPI mode on an interposer board. [Environment setup](setup.md) describes the wiring. |
| SDK | nRF Connect SDK v3.1.1 (Zephyr), built with sysbuild. MCUboot is the bootloader and its secondary image slot is in the external SPI NOR flash on the nRF side. |
| Application | One application, `demo_apps`, which runs keyword spotting on the AKD1500 with on-device edge learning, and serves the BrainChip Connect app over Bluetooth Low Energy. |
| Toolchain | A Docker image, `akidatag-ncs:v3.1.1-py3.12`, holding the SDK, the Akida Python package for model conversion, and clang-format. |
Expand All @@ -22,7 +21,7 @@ If you only want to run the demos from your phone, read the [user guide](user-gu
.
├── src/ The firmware. Source directory of the demo_apps application.
│ ├── apps/demo_apps/ main.cpp, the app's Kconfig fragment and its sample inputs
│ ├── boards/ Devicetree overlays and dk.conf for the AkidaTag board and the nRF5340 DK
│ ├── boards/ Devicetree overlays and board-specific configuration
│ ├── core/ SPI to the AKD1500, its flash, BLE services, audio, LEDs, battery, boot manager
│ ├── deps/ Imported code: the Akida engine, FlatBuffers headers, kissfft (see deps/VENDORING.md)
│ ├── include/ Headers
Expand All @@ -41,10 +40,9 @@ If you only want to run the demos from your phone, read the [user guide](user-gu
└── CONTRIBUTING.md Commit and pull request rules, enforced in CI
```

Both boards build for the same Zephyr board target, `nrf5340dk/nrf5340/cpuapp`. What separates
an AkidaTag build from a DK build is the set of CMake arguments `scripts/run.sh` passes when you
give it `--dk`: the devicetree overlay, the MCUboot overlay, `CONFIG_AKIDATAG_BOARD`, and
`boards/dk.conf`. The two overlays under `src/boards/` list every pin on both boards.
The AkidaTag build uses the Zephyr board target `nrf5340dk/nrf5340/cpuapp` with the board's
devicetree and MCUboot overlays and `CONFIG_AKIDATAG_BOARD=y`. The target name comes from Zephyr;
the custom overlays define the AkidaTag hardware.

## 2. Set up the environment

Expand All @@ -55,8 +53,8 @@ Everything goes through `scripts/run.sh` inside the Docker image. Build the imag
```

It downloads the SDK and takes a while; the result is about 17.6 GB. If you would rather install
the toolchain on the host, Appendix I of [Environment setup](setup.md) lists what to install on
Ubuntu 22.04. The CI release build pulls the same image from
the toolchain on the host, the [local install appendix](setup.md#appendix-install-dependencies-locally)
lists what to install on Ubuntu 22.04. The CI release build pulls the same image from
`ghcr.io/brainchip-inc/akidatag-ncs:v3.1.1-py3.12`.

Host-side tools, outside Docker:
Expand All @@ -73,13 +71,10 @@ On macOS, Docker Desktop has no USB passthrough, so build inside Docker and flas
## 3. Build

```sh
./scripts/run.sh -d -b --app demo_apps # AkidaTag board
BUILD_DIR=build_docker_dk ./scripts/run.sh -d -b --dk --app demo_apps # nRF5340 DK
./scripts/run.sh -d -b --app demo_apps
```

A Docker build lands in `build_docker/demo_apps/`; a host build in `build/demo_apps/`. `--dk`
changes the configuration, not the directory, so the two boards overwrite each other's build
unless you set `BUILD_DIR`, which is why the DK command above builds into `build_docker_dk/`.
A Docker build lands in `build_docker/demo_apps/`; a host build in `build/demo_apps/`.
`./scripts/run.sh -d -i` opens a shell inside the image.

| Output | What it is |
Expand All @@ -102,11 +97,9 @@ Flashing `merged.hex` and `merged_CPUNET.hex` over SWD replaces everything on th
bootloader included. It does not touch the AKD1500's flash, so a model on the board survives.

```sh
./scripts/run.sh -d -f --app demo_apps # Linux, west flash inside Docker
./scripts/run.sh -f -jf --app demo_apps # host J-Link, network core then application core
BUILD_DIR=build_docker ./scripts/run.sh -f -jf --app demo_apps # macOS: flash the Docker build from the host
BUILD_DIR=build_docker_dk ./scripts/run.sh -d -f -jf --dk --app demo_apps # the DK build, from its own directory
./scripts/run.sh -d -r # reset the board
./scripts/run.sh -d -f -jf --app demo_apps # Linux: J-Link inside Docker
BUILD_DIR=build_docker ./scripts/run.sh -f -jf --app demo_apps # macOS: host J-Link
./scripts/run.sh -d -r # reset the board
```

Use the J-Link path, `-jf`, on an AkidaTag board. The board's debug header reports a target
Expand Down Expand Up @@ -138,8 +131,7 @@ full chip erase.
The application's console and shell are on `uart0`, TX P0.29 and RX P1.04, at 115200 baud. On the
AkidaTag board those pins reach the CP2105 bridge behind the USB-C connector, so the cable that
powers the board carries the console. The bridge presents two serial ports and only the
higher-numbered one is the console; the other stays silent. On the DK the pins go to a header, so
use a USB-to-TTL adapter.
higher-numbered one is the console; the other stays silent.

```sh
minicom -D /dev/ttyUSB1 # or ./scripts/run.sh -m /dev/ttyUSB1
Expand Down Expand Up @@ -219,9 +211,8 @@ The transfer stages one 4,096-byte flash sector at a time, carries an absolute o
write and a committed position in every acknowledgement, and checks the whole file against a
CRC32 before trusting it. The board reports `DONE` when the file is stored and verified, then
programs the AKD1500, runs a test inference, and reports `READY`. Only `READY` means the model is
running. [BLE model transfer protocol](ble-model-transfer.md) is the wire contract; change the
firmware and that page together, and remember that BrainChip Connect is a second repository that
has to move with them.
running. Keep the firmware and BrainChip Connect implementations aligned when changing this
exchange.

On the board, the model data is written to the AKD1500's SPI flash at the address the package
names (0x101000 for the keyword model), and the metadata and program info are stored as LittleFS
Expand Down Expand Up @@ -406,7 +397,7 @@ on a pull request.

This is what BrainChip Connect speaks. All of it is in `src/core/interface/ble_services`.

**Advertising.** The board advertises as `AkidaTag` (`AkidaTag-DK` for a DK build) with
**Advertising.** The board advertises as `AkidaTag` with
manufacturer data of twelve ASCII bytes: a Bluetooth version `53`, a three-digit firmware version,
and the accelerator id `AKD1500`. The app filters on the accelerator id, so every board built
around an AKD1500 appears in its list. There is no scan response and no service UUID on the air:
Expand Down Expand Up @@ -444,7 +435,7 @@ is on its main page.
**Model transfer service**, UUID `f000aa00-0451-4000-b000-000000000000`: metadata
characteristics, a control characteristic (start, abort), a data characteristic that carries an
absolute offset in every write, and a status notification that reports the committed position and
the result codes. [BLE model transfer protocol](ble-model-transfer.md) specifies every message.
the result codes.

**Edge learning service**, UUID `f000bb11-0111-9000-c000-000000000000`: a command characteristic
(`f000bb10-...`) that takes one byte, and an acknowledgement characteristic (`f000bb12-...`) that
Expand Down
5 changes: 1 addition & 4 deletions docs/firmware-update-over-usb.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ CDC flashing is not possible and is not what this page describes.

Listening at every boot is not free. `CONFIG_BOOT_SERIAL_WAIT_FOR_DFU_TIMEOUT` in
`src/sysbuild/mcuboot.conf` makes MCUboot hold the board for about a second before it starts
the application, on both build targets and in every release: measured, the application banner
the application in every release: measured, the application banner
appears about 1.5 s after a reset. That timeout is a budget which also covers the slot 0
signature check, which happens whether or not this option is set, so raising it does not add
delay one for one.
Expand Down Expand Up @@ -95,9 +95,6 @@ the image in slot 0 fails signature validation, the bootloader stays in serial r
the USB-C cable instead of halting, and waits there without any command from the host. That
is what makes a board carrying a bad image recoverable without a debug probe.

Because `src/sysbuild/mcuboot.conf` is shared by both build targets, the nRF5340 DK build
behaves exactly the same way.

### What you see on the board

In update mode the red LED is on and steady, and the green LED stops blinking. A blinking
Expand Down
7 changes: 3 additions & 4 deletions docs/hardware/datasheet.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -478,10 +478,10 @@ board.

| Interface | Detail | Source |
|---|---|---|
| Bluetooth device name | `AkidaTag` (`AkidaTag-DK` on the development-kit build) | `src/prj.conf`, `src/boards/dk.conf` |
| Bluetooth device name | `AkidaTag` | `src/prj.conf` |
| Bluetooth role and security | Peripheral; LE Secure Connections only, MITM protection required, bonding with up to 3 bonds, 128-bit keys, resolvable private address rotated every 900 s | `src/prj.conf` |
| Advertising | Flags, complete device name, manufacturer-specific data; the device serial is never advertised | `ble_initialization.c` |
| Model transfer service | `f000aa00-0451-4000-b000-000000000000`, one flash sector per stage with an absolute offset in every write | [BLE model transfer](../ble-model-transfer.md) |
| Model transfer service | `f000aa00-0451-4000-b000-000000000000`, one flash sector per stage with an absolute offset in every write | `src/core/interface/ble_services/file_transfer.c` |
| Edge learning service | `f000bb11-0111-9000-c000-000000000000` (command `f000bb10`, acknowledgement `f000bb12`) | `edge_learning.c` |
| Command and streaming channel | Nordic UART Service frames, including battery state of charge and charger status | `src/README.md`, `battery_service.c` |
| Firmware update over Bluetooth | MCUmgr SMP over Bluetooth with the image, OS and statistics groups; MCUboot with RSA-3072 signatures, two updateable images (application and network core) | `src/prj.conf`, `src/sysbuild/mcuboot.conf` |
Expand Down Expand Up @@ -556,8 +556,7 @@ first board shipped. Source: the revision summary on the Rev2 schematic cover sh
`src/Kconfig`, `src/pm_static.yml`, `src/apps/demo_apps/custom_app.conf`,
`src/imu_app.conf`, `src/README.md`, `src/core/interface/gpio/gpio.c`,
`src/core/interface/audio/pdm_mic.c`, `src/core/interface/ble_services/`,
`src/include/fuel_gauge/fuel_gauge.h`, `docs/ble-model-transfer.md`,
`docs/firmware-update-over-usb.md`, `AGENTS.md`.
`src/include/fuel_gauge/fuel_gauge.h`, `docs/firmware-update-over-usb.md`, `AGENTS.md`.
- [AKD1500 Product Brief V2.4](https://brainchip.com/wp-content/uploads/2025/10/AKD1500-Product-Brief-V2.4-Oct.25.pdf).
- [Nordic Semiconductor nRF5340 product page](https://www.nordicsemi.com/Products/nRF5340)
and [product specification key features](https://docs.nordicsemi.com/bundle/ps_nrf5340/page/keyfeatures_html5.html).
Expand Down
12 changes: 5 additions & 7 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,18 +25,16 @@ BrainChip Connect app on your phone.

| Page | What it holds |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| [Environment setup](setup.md) | The Docker toolchain image, a local install as the alternative, and the nRF5340 DK bench with an AKD1500 PCIe card. |
| [Firmware update over USB-C](firmware-update-over-usb.md) | Updating a board with nothing but its USB-C cable, through the bootloader's serial recovery mode. |
| [BLE model transfer protocol](ble-model-transfer.md) | The wire contract between the firmware and BrainChip Connect for loading a model. |
| [Firmware setup](setup.md) | Building the Docker toolchain image, connecting an AkidaTag, and building and flashing the firmware. |
| [Firmware update over USB-C](firmware-update-over-usb.md) | Updating a board with nothing but its USB-C cable, through the bootloader's serial recovery mode. |

## Help

| Page | What it holds |
| ----------------------------------- | ---------------------------------------------------------------------- |
| [FAQ](faq.md) | Short answers to the questions people ask first. |
| [Support](support.md) | Where to ask for help and what to include. |
| [Release notes](release-notes.md) | What each firmware release changed, and what each release file is for. |
| [Open-source licences](licences.md) | The licence of the firmware and of the code it imports. |
| [FAQ](faq.md) | Short answers to the questions people ask first. |
| [Support](support.md) | Where to ask for help and what to include. |
| [Release notes](release-notes.md) | What each firmware release changed, and what each release file is for. |

## Downloads

Expand Down
42 changes: 0 additions & 42 deletions docs/licences.md
View file
Open in desktop

This file was deleted.

9 changes: 2 additions & 7 deletions docs/release-notes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,14 +13,9 @@ changes. The app shows the same version on its firmware update screen.

## Releases

| Release | Date | What it was for |
| ---------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Release | Date | What it was for |
| ---------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `v1.2.0+0` | 2026-09-14 | Pre-release. The product rename from Spark to AkidaTag, firmware update over the USB-C cable with no probe and no button, a build that works from a fresh clone, and the Akida engine committed to the tree. |
| `v1.1.1+0` | 2026-08-25 | Patch release fixing the two defects that shipped in `v1.1.0+0`: a model update over Bluetooth never completed, and the DK build did not compile. |
| `v1.1.0+0` | 2026-08-25 | Pre-release. Power measurement and power control on the board, a rewritten keyword-spotting scoring path, and the first hardware-in-the-loop CI job. |
| `v1.0.0+0` | 2026-04-07 | First alpha of the firmware platform. |

Releases before `v1.2.0+0` carry the product's earlier name, Spark, in their file names.

### Known issues in `v1.2.0+0`

Expand Down
Loading
Loading