Troubleshooting & FAQ

This page collects the problems people most often hit when building and running no-OS, and the questions that come up repeatedly, in one place. It is organized by when the problem shows up — cloning, building, flashing, running — plus a general FAQ at the end.

Each entry points at the guide with the full story: Getting Started for the end-to-end workflow, No-OS Build Guide for per-platform toolchain setup, Configuration Guide for the Kconfig/defconfig system, and Architecture for how the pieces fit together.

Clone and setup

A dependency fails to clone during configure

Symptom: the configure step fails while fetching a library (lwIP, FreeRTOS, mbedTLS, LVGL, ...), or the build later complains about missing headers from one of them.

Cause: the external libraries a project needs are cloned with Git on demand during the CMake configure step. A network, proxy, or interrupted-clone problem leaves the dependency unresolved.

Fix: check your network/proxy and re-run the build; an interrupted clone is retried on the next configure. To point at a local working copy instead of cloning, set NO_OS_DEP_<LIB>_PATH (e.g. NO_OS_DEP_LWIP_PATH). To reuse downloads across builds, set NO_OS_CACHE_DIR to a persistent, version-keyed store. See Configuration Guide for the full resolution order.

The build utility complains it cannot find the repo root

Symptom: no_os_build.py exits with "Could not find no-OS repo root".

Cause: the script locates the repository by walking up for a CMakePresets.json next to a projects/ directory.

Fix: run it from inside your no-OS checkout (cd no-OS first). Invoke it as python tools/scripts/no_os_build.py ... from the repo root, exactly as in Getting Started.

Build

The build utility cannot find the compiler / SDK

Symptom: configure fails because the toolchain or a vendor SDK path cannot be located.

Cause: the vendor SDK is not installed, or its environment variable is not set. The utility auto-detects default install locations, so this usually means a non-standard install path.

Fix: set the environment variable for your platform (see the matching page under No-OS Build Guide for the exact value):

Platform

Environment variable

Points at

Maxim

MAXIM_LIBRARIES

.../MaximSDK/Libraries

STM32

STM32CUBEMX / STM32CUBEIDE

the CubeMX / CubeIDE install

ADuCM3029

CCES_HOME

the CrossCore Embedded Studio install

Xilinx

XILINX_VITIS (set by sourcing Vitis settings64.sh)

the Xilinx Vitis install

A variant/board combination is rejected

Symptom: no_os_build.py build errors that the combination is invalid, or your board/variant is missing.

Cause: not every variant is available on every board — the valid set is discovered from the project's .conf variants and boards/ directory.

Fix: list the valid combinations and pick a row that exists:

python tools/scripts/no_os_build.py list --project iio_demo

The table it prints is the source of truth (see Getting Started, Step 2).

An option I set in a .conf did not take effect

Symptom: you edited a defconfig but the build behaves as before.

Cause: the configuration is resolved at configure time and cached in the build directory.

Fix: rebuild with --clean (or delete the build/ directory) so the configuration is regenerated:

python tools/scripts/no_os_build.py build --project iio_demo --variant iio --board max32650fthr --clean

See Configuration Guide for how the layered defconfigs are merged.

A stale build behaves strangely after switching branches or configs

Symptom: inexplicable build or link errors after changing branch, variant, or options.

Fix: do a clean configure. --clean removes the build directory before configuring; --fresh passes CMake's --fresh to drop CMakeCache.txt and CMakeFiles/ while keeping other artifacts. When in doubt, delete the build/<project>-<variant>-<board> directory and rebuild.

Flash and debug

Nothing to flash / flashing fails

Symptom: --flash does nothing, or the flash step errors.

Causes and fixes:

  • You did not select a probe. --flash requires --probe:

    python tools/scripts/no_os_build.py build --project iio_demo --variant iio --board max32650fthr --probe openocd --flash

  • The board is not powered or the debug probe is not connected. Confirm the USB connection and that the on-board debugger's drivers are installed on the host.

  • For J-Link, ensure pylink-square is installed (see the setup section above).

The build succeeds but the board does nothing

Symptom: firmware flashes but there is no serial output or IIO context.

Checks:

  • Confirm you are opening the right serial device at the right baud rate (see the running section below).

  • Some boards expose several USB serial interfaces; make sure you opened the one the firmware uses.

  • Rebuild with debug info (CMAKE_BUILD_TYPE=Debug) and attach a debugger to confirm main() is reached. The default build type is RelWithDebInfo, so the ELF already contains symbols for debugging.

Run and interact

The IIO tools cannot open the serial port

Symptom: iio_readdev / iio_writedev fail to connect.

Fixes:

  • Verify the device name — ls /dev/ttyUSB* /dev/ttyACM* on Linux, or the COMx name on Windows — and the baud rate in the URI, e.g. serial:/dev/ttyACM0,57600,8n1n.

  • On Linux, add your user to the dialout group to access serial devices without sudo (log out and back in for it to take effect).

  • Make sure no other program (a serial monitor, a previous session) is holding the port open.

See the Interacting with the device steps in Getting Started.

I see trailing bytes or garbage at the end of a capture

Symptom: buffered reads end with unexpected padding or repeated bytes.

Checks: confirm the sample count (-s) and buffer length (-b) match what you expect, and that the channel scan format matches the client's. Behavior that is specific to one board port usually points at that platform's UART/IRQ timing rather than the shared IIO layer — reproduce against another transport or the linux platform to isolate it.

Frequently asked questions

Which branch should I use?

Use main — it is the development branch and carries the newest drivers and fixes.

Do I need real hardware to try no-OS?

Not to get started. The IIO Demo uses software loopback devices, so any supported board reachable over USB is enough — no sensor wiring required. See Getting Started.

Which platforms are supported?

Xilinx, Maxim, STM32, ADuCM3029, Raspberry Pi Pico and linux-userspace, among others. Each has a setup page under No-OS Build Guide, and the platform backends live under drivers/platform/ (see Architecture).

Can the same driver run on a different MCU?

Yes — that is the core design. A driver talks only to the no_os_* abstraction layer, never to a vendor SDK, so moving to another MCU changes only the platform backend selected at configuration time. The mechanism (the platform_ops tables) is described in Architecture.

How do I turn a driver or feature on or off?

Through the Kconfig system: edit the project's .conf defconfig, or use the menuconfig target to browse options interactively. See Configuration Guide.

How do I add support for a new device?

Write a driver against the no_os_* API following the conventions in no-OS drivers guide (init_param/descriptor structures, _init/_remove functions, coding style), then submit it per Contributing to no-OS.

What do the return codes mean?

no-OS functions return standard negative errno values on failure (-EINVAL, -ENOMEM, -ENOSYS, ...); 0 means success. The helpers in include/no_os_error.h (NO_OS_IS_ERR_VALUE, NO_OS_PTR_ERR, ...) test and cast these. There is also a no-OS-specific NO_OS_EOVERRUN for circular-buffer overruns.

Where is the per-function API reference?

In the auto-generated No-OS Doxygen Documentation, which has the exact signature and fields of every no_os_* function and structure.

Where can I ask for help?

On the ADI EngineerZone microcontroller / no-OS forum.

Still stuck?