+ 
+
-
+
+
- 
+ 
+ 
+ 
+
+ 
+ 
+ 
- Docs · - Hardware · - Getting Started · - Examples · - Community + 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. @@ -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) | @@ -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 | --- @@ -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. + +