Demo 00 — Device discovery

Four layers — PCIe, kernel module, device node, Python runtime — must agree before anything else is worth debugging.

Needs: Raspberry Pi 5 with at least one AKD1500 (M.2) on a carrier, driver installed (guide chapter 05), runtime environment (chapter 06).

Environment: source ~/akida-env/bin/activate.

Run — layer by layer

lspci | grep -i brainchip

Output we got (four M.2 cards behind a switch on bus 0001): 0001:03:00.0 … BrainChip … 0001:04:00.0 … BrainChip … 0001:05:00.0 … BrainChip … 0001:06:00.0 … BrainChip … Nothing here = power or seating. Software cannot fix it.

lsmod | grep akida

akida_pcie with a use count. Missing → bash setup_akida_treiber.sh, reboot.

ls -l /dev/akd1500_*

/dev/akd1500_0 … /dev/akd1500_3. The driver numbers cards in probe order.

dmesg | grep akida-pcie | tail

Per card: Host ddr area: 16777216 bytes and probed (akd1500_N).

python3 -c "import akida; print([str(d) for d in akida.devices()]); print(akida.__version__)"

['PCIe/AKD1500/16MB/0', 'PCIe/AKD1500/16MB/1', 'PCIe/AKD1500/16MB/2', 'PCIe/AKD1500/16MB/3'] and 2.19.3.

Record the baseline

Write the four lines plus uname -r and cat /etc/os-release | head -2 into a file next to the machine. When a kernel update or a cable change breaks something later, this file is the fastest way back — and it is what a bug report needs.

The failure we actually saw (2026-09-20)

[13412.649568] akida-pcie 0001:06:00.0: DMA wait completion timed out
[13432.681705] akida-pcie 0001:06:00.0: DMA wait completion timed out

every few seconds while lspci still listed the card, and chip learning failed with akida.devices(): Error reading at 0xfce00018 len: 4 errno(110): Connection timed out. The card was hung, not gone. Recovery without a reboot:

sudo systemctl stop vorsa
echo 1 | sudo tee /sys/bus/pci/devices/0001:06:00.0/remove
sleep 2
echo 1 | sudo tee /sys/bus/pci/rescan
dmesg | tail -5
sudo systemctl start vorsa

Since build 1.9.36 the same recovery is a button in Status → Hardware, and the card watchdog keeps the line running on the other cards meanwhile (Demo 07).

Proves

That your driver build, your carrier and your runtime agree — the precondition for every other demo.

Does not prove

That a model maps (Demo 02) or that the card stays healthy under load.

Failure modes

Fewer cards in lspci than seated → carrier power/seating. Module missing after apt full-upgrade → kernel changed, DKMS rebuild. akida.devices() empty inside Python but nodes exist → wrong venv (system Python has no akida). Repeating DMA timeouts on the same address → swap cards to separate card from slot.

Time: 2 minutes; 10 with a recovery.