Software/Arduino Core/Reference

Troubleshooting

Symptoms, causes and remedies for build, upload, camera, model, display, audio and connectivity faults.

beginner5 min read

Faults are grouped by the stage at which they appear. The console referred to is the USB serial port; Tools > Debug console > On adds the core's telemetry lines to it.

Build

Symptom	Cause	Remedy
`arm-none-eabi-gcc not found`	The compiler is not on `PATH`	Add the toolchain's `bin` directory and restart the IDE
Toolchain reported as too old	GCC below 11 found first	Remove or reorder the older toolchain on `PATH`
`Python was not found`	No Python 3 on `PATH`	Install Python 3.8 or later
Signing failed	STM32CubeProgrammer not installed in its default location	Install it
Model step fails	ST Edge AI Core missing or not 4.0	Install version 4.0; set `NEURON6_STEDGEAI` for a non-default path
`Too many models`	More than eight pragmas	Remove models
Two models with the same name	Duplicate `name=`	Give one a distinct name
`<lib>.h: No such file` after adding a library	Stale IDE cache	Clear `%LOCALAPPDATA%\Arduino15\cache` once
Image exceeds 1.5 MB	Application too large	Tools > Optimize > Smallest, or remove code

Upload

Symptom	Cause	Remedy
Port does not return after upload	Slow enumeration	Wait ten seconds, retry
Board ignores the 1200 baud touch	Application crashed	Double press reset, then upload
No port at all	Power-only cable or faulty port	Change cable, then double press reset
Weights upload every time	Tools > Model weights set to always	Select "only when changed"

Boot

Symptom	Cause	Remedy
Solid red LED shortly after power up	Error handler entered	Read `[ERRDUMP]` on the console. Usually a memory shortage from a large model with a large camera mode
Red LED blinks n times, power save library linked	Previous run failed in the sleep engine at step n	Consult the library `README` bring-up checklist
`[NeuroN6] No camera sensor declared`	No sensor object at file scope	Expected for a sketch without a camera

Camera

Symptom	Cause	Remedy
No frames; console names the sensor and chip ID	Wrong carrier argument, or sensor not fitted	Match `CARRIER_TFT` or the default to the physical carrier
Picture upside down or mirrored	Orientation	`cfg.mirror_flip = CAMERA_AUTO_FLIP`
`[CAM]` warning about frame rate	Requested rate above the mode's maximum	Expected; the rate is clamped
`[VISION WARN] crop clamped`	Offset crop outside the frame or below the model input size	Adjust `cfg.nn.crop_*`
Display off at XGA or above	Display pipe has no downscaler	Use WVGA or VGA for the panel
Blurred codes or tags never decode	Autofocus off	`cfg.af = AF_CONTINUOUS`
Colour threshold drifts	Automatic white balance	Lock it after settling

Models

Symptom	Cause	Remedy
Boxes misplaced	`cfg.nn.width` and `height` do not match the model	Set them to the model's input size
Boxes skewed near edges	Stretch distortion	`ASPECT_CROP_CENTER`
Detections are noise	Input quantisation symmetric on a 0 to 1 model	Re-export with asymmetric input
Nothing detected, model compiles	Input layout not `[b:1,h:H,w:W,c:3]`	`tools/tflite_input_to_hwc.py`
Stale boxes remain	A slot not republished	`vnd_meta_invalidate_slot()`
One model's boxes missing in a two-model sketch	Wrong model on slot 0	Put the multi-class detector on `VND_META_SLOT_MODEL_0`
Poor detection at 5 MP	Decimation	XGA with centre crop

Display

Symptom	Cause	Remedy
`[VISION WARN] TRANSPORT_LCD selected, but this carrier has no LCD panel`	Not the TFT carrier	Use `TRANSPORT_USB`
Stripes in the Neuro Studio view with the panel on	Bus contention	Lower `cfg.fps`
Sketch graphics flicker with a model running	Two drawers clearing the overlay	Draw from a post-processor callback or use `OVL_CLEAR` then `OVL_Commit()`
Touch not found	Panel held in reset or not fitted	RESET is tied to system reset; check the panel

Audio

Symptom	Cause	Remedy
Microphone level stuck at 0	Clock, MDF or DMA fault	Read `[MICDBG]` top down; the first wrong value locates the fault
No sound	SAI, DMA or amplifier shutdown	`speaker.debugDump()`; `SD(PB6) ODR` must read 1
Spectrum lowest band always lit	DC offset	Handled by `n6_fft_magnitude()`; verify the library version
Audio absent in Neuro Studio while classifying	`mic.streamToNS(false)`	Expected; only one consumer of samples

Connectivity

Symptom	Cause	Remedy
WiFi transport falls back to USB	Library not included, module absent, firmware not flashed or credentials wrong	Check the console message
`localIP()` reads 0.0.0.0	Access point not yet leasing	Wait up to a few seconds
BLE `begin()` fails	Module not loaded	Start the access point first
BLE connection drops immediately	Connection interval too short for once-per-frame polling	Widen the interval and supervision timeout
LTE modem silent	Baud persisted at 921600	`findBaud()`
LTE attaches but no address	APN authentication missing	Supply username and password
OTA manifest fetch fails	Network or server	Check `MayaW476.status()` and the server files

Sensors

Symptom	Cause	Remedy
Sensor not found	Not fitted, or wrong address	Run WireScanner
Sketch stalls with camera and sensors	Long bus claim	Use `n6_i2c_trylock()` for publishers
Thermal camera never boots	I2C traffic during its boot window, or CS floating	Claim the bus around `powerOn()`
Thermal frame rate collapses with a model	CPU contention	`cfg.nn.max_fps` around 22

SD cards

Symptom	Cause	Remedy
Card never initialises	Init clock above 400 kHz	`SPI.setKernelSource(RCC_SPI2CLKSOURCE_HSI)`
Card initialises then fails	Data mode	`SPI.forceDataMode(SPI_MODE3)`
Card latches after a while	Supply dip on flying leads	10 uF and 100 nF at the adapter

Power

Symptom	Cause	Remedy
USB disconnects during a sketch	`sleepStop()`	Expected; use `sleepLight()` when tethered
Current high while idle	Idle task spinning	Link the power save library
Watchdog reset storm	Floating WDI	Pull-downs on WDI and SET1