BrainChip Developer Hub

Docs · Hardware · Getting Started · Examples · Structure · Community · License

Resources for developing and deploying AI models on BrainChip Akida neuromorphic processors — training, conversion, evaluation, deployment, and benchmarking.

This repository complements the official BrainChip documentation. It focuses on practical, runnable examples and insider knowledge for getting the best out of Akida hardware.

---

What do you want to do?

Goal	Where to go
Train, convert, and evaluate a model	Akida 1 · Akida 2 · Akida Pico (COMING SOON)
Deploy to hardware and benchmark	Deployment (COMING SOON)
Understand how Akida works	Concepts (COMING SOON)
New to Akida — not sure where to start	Getting Started

---

Platform overview

Akida 1 and Akida 2 examples are available today; more Akida 2 models can be found here in the official docs, and Akida Pico content for this repo is on the way.

	Akida 1	Akida 2	Akida Pico
Chip	AKD1500	AKD2500	—
Typical use cases	Image classification, keyword spotting, object detection	Larger models, higher accuracy targets	Always-on sensing, edge inference
Examples in this repo	Image Classification (PlantVillage) · ImageNet / AkidaNet · Visual Wake Words · Keyword Spotting · ECG Arrhythmia	Visual Wake Words · Image Classification (PlantVillage) · Keyword Spotting	🔜 Coming soon

---

Why Akida?

Akida is BrainChip's neuromorphic processor — it processes data event by event instead of running dense computation on every input, so it only spends power and cycles on activity that's actually there. In practice, that means real models running at a fraction of the latency and power of conventional hardware.

The examples in this repo make that concrete on real AKD1500 silicon: Image Classification (PlantVillage) reaches 99.43% accuracy.

Full benchmark breakdowns, mapping comparisons, and reproduction steps live in each example's own README.

---

Get Akida Hardware

Every result in this repo runs on real Akida silicon, not a simulation.

Chips

• AKD1500 — 22nm neuromorphic co-processor, up to 800 effective GOPS, pairs with any host CPU/MCU over PCIe or SPI
• AKD1000 — the processor behind the PCIe and Raspberry Pi dev boards below; ARM Cortex-M4 host, Linux (x86-64/ARM) support

Dev kits & boards

• AKD1000 PCIe Development Board
• AKD1000 Raspberry Pi 4 Dev Kit
• AKD1000 Raspberry Pi 5 Dev Kit
• AKD1500 Edge AI Co-Processor

All available through the BrainChip Shop.

No hardware yet? Akida Cloud gives you remote access to an FPGA implementation of Akida 2, so you can test, benchmark, and validate models without a board.

---

Getting Started

Go from a fresh clone to your first result in four steps.

1. Clone the repo (with Git LFS). Pretrained weights are stored with Git LFS, so set it up first — otherwise the weight files arrive as small text pointers. More detail in Trained models.

   git lfs install        # one-time per machine
   git clone https://github.com/Brainchip-Inc/brainchip_devhub.git
   cd brainchip_devhub
   git lfs pull           # fetch the real model files

2. Create an environment and install. Python 3.10–3.12 in a fresh venv or conda env (details in Requirements). pip install -e . pulls the Python toolkit — TensorFlow and akida_models (which brings in the Akida / MetaTF packages). Add the cuda extra if you'll train the examples on a GPU.

   conda create -n brainchip_devhub_env python=3.12 -y
   conda activate brainchip_devhub_env
   pip install -v -e ".[cuda]"   # GPU training; plain `pip install -v -e .` is enough to evaluate and benchmark

3. (For on-device runs) set up hardware. You can train, quantize, convert, and evaluate in simulation with no board. To reproduce the latency and power numbers you'll need a physical AKD1500 / AKD1000 device and its runtime/driver — see the official installation guide. No hardware? Akida Cloud runs models remotely on an FPGA implementation of Akida 2.

4. Pick an example and follow its README. Browse the available examples across Akida 1 and Akida 2 and open the one you want under its model_zoo/ directory (akida1/model_zoo/ or akida2/model_zoo/). Each README walks you through dataset setup, evaluation, and hardware benchmarking, and lists the accuracy and power numbers you should expect. New to Akida? plant_village is a good first run — the full pipeline goes end-to-end in about 20 minutes.

---

Requirements

This section covers the why and the gotchas.

• Python 3.10–3.12. The range is pinned by the TensorFlow 2.19 and akida_models 1.14 dependencies; other Python versions won't have matching wheels. Use whatever environment manager you prefer (venv, conda, or Docker) — the quickstart uses conda.
• What pip install -e . actually installs. Beyond TensorFlow, it pulls akida_models, which brings in the Akida / MetaTF stack (akida, cnn2snn, quantizeml), plus the helpers the examples need: pyftdi (reads power measurements from the board over I²C), pywavelets and wfdb (used by the ECG example), and ipykernel for the notebooks. The full pinned list is in pyproject.toml.
• Optional extras. pip install -e ".[cuda]" adds the CUDA libraries TensorFlow needs to train on a GPU; evaluation, conversion and benchmarking run fine without them. pip install -e ".[torch]" is for the PyTorch-based examples: it adds onnx2akida, which converts ONNX models exported from PyTorch for Akida 2 (the ONNX route has no quantization-aware training, so it is limited to 8-bit models), plus PyTorch itself (pinned to 2.10.0, the newest release whose ONNX exporter works with the current onnx2akida). [cuda] and [torch] need separate environments (e.g. a second brainchip_devhub_torch_env); pip will refuse to install both. See PyTorch and TensorFlow in one environment below.
• No separate toolkit install needed. The Python toolkit comes from that one command; the official installation guide is only for the on-device runtime and drivers, which you need to run on real silicon — not for simulation.

PyTorch and TensorFlow in one environment

Getting both frameworks onto the GPU in one environment is a common stumbling block, because each installs its own CUDA libraries from pip. With the versions pinned here, the [torch] environment manages it: PyTorch 2.10.0 brings CUDA 12.8 libraries, and TensorFlow 2.19.1, installed without [and-cuda], finds and uses them. Both then run on the GPU in the same process, alongside the Akida toolchain (akida, quantizeml, cnn2snn, onnx2akida). We tested this on Linux with an RTX 3090 and NVIDIA driver 580. TensorFlow is using newer CUDA libraries there than the ones [and-cuda] pins; that worked in our tests, but for long Keras training runs the [cuda] environment remains the tested setup.

If you choose versions yourself, these combinations break:

• tensorflow[and-cuda] with PyTorch 2.10. Both pin nvidia-*-cu12 packages, at different versions, so pip refuses to install them together. Use plain tensorflow alongside PyTorch instead.
• tensorflow[and-cuda] with PyTorch 2.11 or later. Newer PyTorch ships CUDA 13 libraries under different package names, so pip installs both without complaint. But the two sets write the same files, and PyTorch then fails to import (undefined symbol: ncclCommResume).
• PyTorch 2.11 or later with onnx2akida 0.7.0. The default torch.onnx.export needs a newer onnx_ir than onnx2akida allows, so the export fails (module 'onnx_ir' has no attribute 'schemas'). Pass dynamo=False to use the legacy exporter, or stay on PyTorch 2.10.

Trained models

Pretrained weights (.h5, .fbz) live in the repo but are tracked with Git LFS rather than regular git: the binaries are large, so git stores a small text pointer in history and fetches the real file on demand, keeping clones fast.

• Did LFS actually run? If a weight file is only a few hundred bytes and opens as text starting with version https://git-lfs.github.com/spec/v1, you have a pointer, not a model — LFS didn't fetch it. git lfs ls-files shows what LFS is tracking.
• Fixing a pointer-only checkout. Install Git LFS, then pull the real files:

  sudo apt install git-lfs   # linux; see git-lfs.com for other platforms
  git lfs install            # one-time per machine
  git lfs pull               # fetch the real files for this clone

---

Anatomy of a model_zoo example

Every example under model_zoo/ follows the same layout and naming convention, so once you've run one you can find your way around any of them.

What you'll find inside an example folder

Each example is a self-contained folder named after its dataset (e.g. plant_village/), or after its dataset and model when a dataset has, or is likely to have, several models (e.g. imagenet_akidanet/, pascal_voc_yolov2/). arrhythmia_classification/ is a deliberate exception. Files follow an <example>_<role> convention:

File / folder	What it is
<example>_model.py	Model architecture definition
<example>_data.py / _data_loader.py	Dataset download + preprocessing
<example>_train.py + _train.sh	Training pipeline; the .sh runs it in one shot
<example>_eval.py + _eval.sh	Accuracy for float, quantized (QAT) and Akida models
<example>_benchmark.py	Latency and power measurement on real hardware
*_notebook_training.ipynb	Notebook walkthrough of training
*_notebook_evaluation.ipynb	Notebook walkthrough of evaluation
*_notebook_benchmark.ipynb	Notebook for accuracy + on-device benchmarking
colab_setup.py	One-shot environment setup for running the notebooks in Colab
pretrained_models/	Committed weights (via Git LFS)
data/, models/	Populated at runtime; not committed (git-ignored)
docs/	Benchmark plots, dataset mosaics, metrics.json, and the README template
README.md	Generated from docs/README.md.template + docs/metrics.json

Two ways to run every example

• Scripts (.py / .sh) — reproducible command-line runs; the _train.sh / _eval.sh wrappers run the whole pipeline in one command.
• Notebooks (*_notebook_*.ipynb) — the same steps, interactive, each with an Open in Colab badge. On-device power benchmarks read from a physical board and won't run in Colab.

Model weight formats

• .h5 — full-precision (float) Keras model
• _qat.h5 — quantization-aware trained model
• _qat.fbz — converted, Akida-ready model

Not every example has every file. Eval-only examples (e.g. imagenet_akidanet) ship evaluation and benchmark files but no training stage. A few carry extras like configs/ or task-specific preprocessing.

---

Repository Structure

brainchip_devhub/
├── akida1/
│   ├── model_zoo/        # Self-contained training, conversion & evaluation scripts
│   └── notebooks/       # Pedagogic notebooks on key concepts
├── akida2/
│   ├── model_zoo/
│   └── notebooks/
├── akida_pico/
│   ├── model_zoo/
│   └── notebooks/
├── deployment/          # Hardware deployment and benchmarking
│   ├── akida1/
│   ├── akida2/
│   └── akida_pico/
└── concepts/            # Cross-platform guides: how Akida works, optimisation strategies

Each platform's model_zoo/ directory is intentionally self-contained — model definition, training, conversion, and evaluation for each example live together in a single script or small group of related files. This is a deliberate contrast to akida_models, which is structured as a reusable library; here, readability and reproducibility take priority.

---

Community and Support

Hit a problem reproducing an example, or anything else in this repository? Open an issue and say what you ran, what happened, and what hardware you're on.

• Sign up for the BrainChip Developer Hub for tools, the model zoo and Akida Cloud
• Join the BrainChip Discord for discussion and community help
• Read the documentation for MetaTF and the Akida platform
• Subscribe to the newsletter for releases and announcements
• Get in touch with sales to talk about a deployment
• Follow BrainChip on LinkedIn and X

License

Apache 2.0 — see LICENSE.