11 — Troubleshooting
Every symptom in this table was seen on our bench. Cause and fix are what actually worked.
OUR OBSERVATIONEvent 2026-09-27Published 2026-09-27SE Inspect build 1.9.37
Read the footer first: build string (is this the code you deployed?), camera (resolution and fps), segments (nW mF +kN D…: watershed pieces, fitted frames, added, detector boxes).
Camera
| Symptom | Cause | Fix |
|---|---|---|
Black frames; Camera frontend has timed out in journalctl |
loose CSI ribbon | reseat both ends, reboot, chapter 04 proof |
vcgencmd: ioctl_set_msg failed, camera gone after a reboot |
VideoCore firmware mailbox — damaged SD card | new card, chapter 10 rebuild |
simplejpeg: numpy.dtype size changed |
numpy ≥ 2 in ~/akida-env |
pip install "numpy<2" |
| Image right but dark/unsharp in one zone | automatics fighting, or focus on the other zone's distance | Camera strip: Sharp once, then More → fix exposure/gain; per-zone camera choice |
| Zone frame does not rotate with the image | zone bound to the other camera | only zones on the main camera rotate; redraw |
Cards
| Symptom | Cause | Fix |
|---|---|---|
lspci shows fewer cards than seated |
power/seating on the carrier | reseat, check carrier supply |
lsmod empty, nodes missing |
driver not built for this kernel | bash setup_akida_treiber.sh, reboot |
DMA wait completion timed out every ~5 s; learning fails with errno(110) |
one card hung, link up | Status → Hardware → Reset card, or manual remove/rescan (chapter 05); recurring on one address → swap cards |
akida.devices() empty in Python but nodes exist |
wrong environment | source ~/akida-env/bin/activate |
| Chip learning: "Karte N antwortet nicht" | as above during fit |
reset card, repeat learning |
Recognition and segmentation
| Symptom | Cause | Fix |
|---|---|---|
| Labels/prints recognised instead of the whole card | global background colour vs. lens vignetting (threshold rose to ~31) | local belt model (≥ 1.9.33) plus empty-belt reference |
| Glare spots become parts | single-frame reference, flicker | re-record the empty belt (16 frames, noise map, ≥ 1.9.35); polariser or diffuse light |
| Belt texture/edge becomes parts | zone includes the belt edge; reference taken with the belt stopped | redraw zone; record the empty belt while running |
| Everything is "unknown" | negative class contains empty-belt photos; or confidence threshold too high | delete empty negatives (the learning dialog lists them); lower the threshold; add poses |
| Two touching parts become one | segmentation merges | the hole signature and watershed handle most cases; else learn the parts separately and check the touching scene after each new class |
| "Knappe Entscheidung" (close call) shown | two classes within 12 points on one part | add distinguishing poses, or accept "unknown" as the honest answer |
Learning
| Symptom | Cause | Fix |
|---|---|---|
| "7 of 25 negative photos show only empty background and were NOT learned" | empty negatives | delete them; negatives are for real foreign parts |
| Photos come from the image centre, not from the learning window | learning-zone view was open (photos come from zones A/B then) | close Learning zones; ≥ 1.9.37 uses zones only when the view is open |
| "Kein Lernfoto gespeichert — in keiner Lernzone war ein Teil freistellbar" | poison guard refused empty crops | put the part in the zone; check the zone camera |
Line, belt, arm
| Symptom | Cause | Fix |
|---|---|---|
| Belt never starts | line inactive; recognition not OK (belt refuses to run blind); Single mode waiting for a named part | Line start; check footer/attention block; switch to Flow |
| "Band lief, aber nichts hat die Abholzone erreicht" (45 s) | part fell off or pickup zone misplaced | redraw pickup zone |
| "Unbekanntes Teil in der Abholzone — Band gestoppt" | unknown at pickup (safety rule) | remove the part by hand or learn it; the line resumes when the zone is free |
| Relay clicks but belt does not run / runs permanently | jumper L instead of H; NC used instead of NO | jumper H, NO contact (chapter 03) |
Arm: /dev/ttyACM0: No such file or directory |
Arduino not connected to the Pi 5, charge-only cable, or ttyUSB0 |
ls /dev/ttyACM* /dev/ttyUSB*, lsusb; set VORSA_ARM_PORT |
| Arm: "Erst Referenzfahrt (HOME)" | not homed since power-up | Robot arm → Motors on → HOME |
| Arm: "Programm 'Holen' fehlt — nur quittiert" | pick sequence not taught | teach points, save program "Holen" |
| Arm homes into the wrong direction | HOME_PLUS/DIR_INV for this axis |
flip in the sketch, reflash |
UI
| Symptom | Cause | Fix |
|---|---|---|
| Footer shows an old build | service not restarted / browser cache | systemctl restart vorsa, Ctrl+Shift+R |
| Feeds flicker | old build (< 1.9.31) | update: rAF-bundled drawing, double-buffered feeds |
| Header icons jump around | old build (< 1.9.36) | update: fixed tile-header layout |
When you report a problem, attach: build string, journalctl -u vorsa -n 100, dmesg | tail -50, the OS/kernel/driver/akida versions from chapter 04, and a screenshot of Status → Hardware.