Skip to content

Readme updates #25

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
dmclellandbc merged 2 commits into from
Sep 3, 2026
Merged

Readme updates #25

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
46a7236
updated README: new section, new badges, linking akida 2, community a…
mtorresBrainChip Sep 2, 2026
0cf8256
updated logo so it can work for users with dark mode and light mode
mtorresBrainChip Sep 2, 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
172 changes: 129 additions & 43 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,35 @@
<p align="center">
<img src="docs/assets/0.-BC-dev-hub-LOGO-flicker.svg" alt="BrainChip Dev Hub" width="260"/>
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/0_-BC-dev-hub-LOGO-flicker-dark.svg">
<img src="docs/assets/0_-BC-dev-hub-LOGO-flicker-light.svg" alt="BrainChip Dev Hub" width="260"/>
</picture>
</p>

<p align="center">
<img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License: Apache 2.0"/>
<img src="https://img.shields.io/badge/python-3.10%20%E2%80%93%203.12-blue.svg" alt="Python 3.10 to 3.12"/>
<img src="https://img.shields.io/badge/python-3.10%20%E2%80%93%203.12-blue?logo=python&logoColor=white" alt="Python 3.10 – 3.12"/>
<img src="https://img.shields.io/badge/akida__models-1.14.0-orange.svg" alt="akida_models 1.14.0"/>
<img src="https://img.shields.io/badge/cnn2snn-2.19.x-orange.svg" alt="cnn2snn 2.19.x"/>
<img src="https://img.shields.io/badge/MetaTF-akida%202.19.2-orange.svg" alt="MetaTF (akida 2.19.2)"/>
</p>

<p align="center">
<img src="https://img.shields.io/badge/hardware-AKD2500%20%7C%20AKD1500%20%7C%20AKD1000-orange.svg" alt="Supported hardware: AKD2500, AKD1500, AKD1000"/>
<a href="https://discord.com/invite/9bmd9g52vn"><img src="https://img.shields.io/badge/Discord-Join%20the%20community-5865F2?logo=discord&logoColor=white" alt="Join the BrainChip Discord community"/></a>
<a href="https://shop.brainchipinc.com/"><img src="https://img.shields.io/badge/Shop-BrainChip-blue.svg" alt="BrainChip Shop"/></a>
<a href="https://developer.brainchip.com/signup/"><img src="https://img.shields.io/badge/BrainChip%20Developer%20Hub-Sign%20up-blue.svg" alt="BrainChip Developer Hub - Sign up"/></a>
</p>

# BrainChip Developer Hub

<p align="center">
<a href="https://doc.brainchipinc.com">Docs</a> ·
<a href="#get-akida-hardware">Hardware</a> ·
<a href="#getting-started">Getting Started</a> ·
<a href="#platform-overview">Examples</a> ·
<a href="#community-and-support">Community</a>
<a href="https://doc.brainchipinc.com"><u>Docs</u></a> ·
<a href="#get-akida-hardware"><u>Hardware</u></a> ·
<a href="#getting-started"><u>Getting Started</u></a> ·
<a href="#platform-overview"><u>Examples</u></a> ·
<a href="#repository-structure"><u>Structure</u></a> ·
<a href="#community-and-support"><u>Community</u></a> ·
<a href="#license"><u>License</u></a>
</p>

Resources for developing and deploying AI models on BrainChip Akida neuromorphic processors — training, conversion, evaluation, deployment, and benchmarking.
Expand All @@ -28,7 +42,7 @@ Resources for developing and deploying AI models on BrainChip Akida neuromorphic

| Goal | Where to go |
| --- | --- |
| Train, convert, and evaluate a model | [Akida 1](akida1) · Akida 2 (**COMING SOON**) · Akida Pico (**COMING SOON**) |
| Train, convert, and evaluate a model | [Akida 1](akida1) · [Akida 2](akida2) · 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](#getting-started) |
Expand All @@ -37,13 +51,13 @@ Resources for developing and deploying AI models on BrainChip Akida neuromorphic

## Platform overview

Akida 1 examples are available today; Akida 2 models/examples can be found [here](https://doc.brainchipinc.com/model_zoo_performance.html#akida-2-0-models) in the official docs, and Akida Pico content for this repo is on the way.
Akida 1 and Akida 2 examples are available today; more Akida 2 models can be found [here](https://doc.brainchipinc.com/model_zoo_performance.html#akida-2-0-models) 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](akida1/model_zoo/plant_village) · [Object Detection](akida1/model_zoo/vww) | 🔜 Coming soon | 🔜 Coming soon |
| **Examples in this repo** | [Image Classification (PlantVillage)](akida1/model_zoo/plant_village) · [ImageNet / AkidaNet](akida1/model_zoo/imagenet_akidanet) · [Visual Wake Words](akida1/model_zoo/vww) · [Keyword Spotting](akida1/model_zoo/speech_commands) · [ECG Arrhythmia](akida1/model_zoo/arrhythmia_classification) | [Visual Wake Words](akida2/model_zoo/vww) | 🔜 Coming soon |

---

Expand Down Expand Up @@ -79,48 +93,115 @@ All available through the [BrainChip Shop](https://shop.brainchipinc.com/).

## Getting Started

1. **Install the Akida toolkit** — see the [official installation guide](https://doc.brainchipinc.com).
2. **Pick your platform** — use the table above to find the best fit for your use case. Akida 1 is recommended for now.
3. **Run an example** — each platform directory has self-contained examples you can run immediately.
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](https://git-lfs.com/), so set it up first — otherwise the weight
files arrive as small text pointers. More detail in [Trained models](#trained-models).

```bash
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](#requirements)). `pip install -e .` pulls
the full Python toolkit — TensorFlow and `akida_models` (which brings in the
Akida / MetaTF packages).

```bash
conda create -n brainchip_devhub_env python=3.12 -y
conda activate brainchip_devhub_env
pip install -v -e .
```

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](https://doc.brainchipinc.com). No hardware?
[Akida Cloud](https://shop.brainchipinc.com/) runs models on real silicon remotely.

4. **Pick an example and follow its README.** Browse the
[available examples](#platform-overview) across Akida 1 and Akida 2 and open the
one you want under its `model_zoo/` directory
([`akida1/model_zoo/`](akida1/model_zoo) or [`akida2/model_zoo/`](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`](akida1/model_zoo/plant_village) is a good
first run — the full pipeline goes end-to-end in about 20 minutes.

---

### Requirements

- Python versions: 3.10 to 3.12
This section covers the *why* and the gotchas.

We recommend using your preference of docker or a virtual environment such as `venv` or `conda`.
For example, to create and activate an appropriate virtual environment with `conda`:

```
conda create -n brainchip_devhub_env python=3.12 -y
conda activate brainchip_devhub_env
```

With your container or virtual environment active, all further requirements along with utilities
local to this repository should be installed by running the following at the top level of the
repository (you can check what packages will be installed in the `pyproject.toml` file):

```
pip install -v -e .
```
- **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`](pyproject.toml).
- **No separate toolkit install needed.** The Python toolkit comes from that one command; the [official installation guide](https://doc.brainchipinc.com) is only for the on-device runtime and drivers, which you need to run on real silicon — not for simulation.

### Trained models

Pretrained model weights (`.h5`, `.fbz`, etc.) are stored directly in this repository, tracked with [Git LFS](https://git-lfs.com/) rather than regular git. If you cloned the repo without LFS support, these files will show up as small text pointers instead of real weights.

If `git-lfs` isn't installed on your machine yet, see the official installation instructions for your platform. On a linux machine, one option is
Pretrained weights (`.h5`, `.fbz`) live in the repo but are tracked with [Git LFS](https://git-lfs.com/) 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.

```
sudo apt install git-lfs
```
- **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:
```bash
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
```

With git-lfs available, to pull the actual model files:
---

```
git lfs install # one-time setup per machine
git lfs pull # fetch the real model 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.

<details>
<summary><b>What you'll find inside an example folder</b></summary>

<br>

Each example is a self-contained folder named after its task (e.g. `plant_village/`),
with files following 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.

</details>

---

Expand Down Expand Up @@ -150,9 +231,14 @@ Each platform's [`model_zoo/`](https://github.com/Brainchip-Inc/brainchip_devhub

## Community and Support

- **Bugs and feature requests** — open a [GitHub Issue](../../issues).
- **Reference material and official guides** — see the [BrainChip documentation](https://doc.brainchipinc.com).
- **Discussion and community help** — join the [BrainChip Discord](https://discord.com/invite/9bmd9g52vn).
Hit a problem reproducing an example, or anything else in this repository? [Open an issue](../../issues) and say what you ran, what happened, and what hardware you're on.

- [Sign up for the BrainChip Developer Hub](https://developer.brainchip.com/signup/) for tools, the model zoo and Akida Cloud
- [Join the BrainChip Discord](https://discord.com/invite/9bmd9g52vn) for discussion and community help
- [Read the documentation](https://doc.brainchipinc.com) for MetaTF and the Akida platform
- [Subscribe to the newsletter](https://brainchip.com/newsletter/) for releases and announcements
- [Get in touch with sales](https://brainchip.com/contact/) to talk about a deployment
- Follow BrainChip on [LinkedIn](https://www.linkedin.com/company/7792006) and [X](https://x.com/BrainChip_inc)

## License

Expand Down
Loading