Frequently Asked Questions¶

Common questions and answers about Nexus.

General Questions¶

What is Nexus?¶

Nexus is a professional embedded software development platform designed for building reliable, secure, and portable embedded applications across multiple MCU platforms.

Key Features:

  • Hardware Abstraction Layer (HAL)

  • OS Abstraction Layer (OSAL)

  • Framework components (Log, Shell, Config)

  • Multi-platform support (STM32, GD32, Native)

  • Comprehensive testing (1539+ tests)

  • Complete documentation (English and Chinese)

Who should use Nexus?¶

Nexus is ideal for:

  • Embedded developers who want portable code across platforms

  • Teams who need consistent coding standards

  • Students learning embedded systems

  • Hobbyists building embedded projects

  • Companies developing commercial products

What platforms does Nexus support?¶

Currently Supported:

  • Native (Windows/Linux/macOS) - for testing

  • STM32F4 series (Cortex-M4)

In Progress:

  • STM32H7 series (Cortex-M7)

  • GD32 series

Planned:

  • ESP32 series

  • nRF52 series

Is Nexus free?¶

Yes, Nexus is open source under the MIT License. You can use it freely in commercial and non-commercial projects.

Installation and Setup¶

What tools do I need?¶

Required:

  • CMake 3.16+

  • Git

  • Python 3.8+

  • C compiler (GCC, Clang, or MSVC)

For ARM targets:

  • ARM GCC Toolchain 10.3+

  • OpenOCD or J-Link (for debugging)

Optional:

  • Doxygen (for documentation)

  • Sphinx (for user guides)

See Environment Setup for detailed installation instructions.

How do I install the ARM toolchain?¶

Windows:

choco install gcc-arm-embedded

Or download from https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain

Linux:

sudo apt install gcc-arm-none-eabi

macOS:

brew install --cask gcc-arm-embedded

Why can’t CMake find the ARM toolchain?¶

Solution: Ensure the toolchain is in your PATH:

# Verify installation
arm-none-eabi-gcc --version

# If not found, add to PATH
export PATH=$PATH:/path/to/gcc-arm-none-eabi/bin

Building and Compilation¶

How do I build for native platform?¶

# Using Python script
python scripts/building/build.py

# Or using CMake
cmake -B build -DNEXUS_PLATFORM=native
cmake --build build

How do I build for STM32F4?¶

# Using Python script
python scripts/building/build.py --platform stm32f4 --toolchain arm-none-eabi

# Or using CMake
cmake -B build-stm32f4 \
    -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/arm-none-eabi.cmake \
    -DNEXUS_PLATFORM=stm32f4
cmake --build build-stm32f4

Build fails with “nexus_config.h not found”¶

Cause: Configuration header not generated.

Solution: Generate configuration:

python scripts/kconfig/generate_config.py --default --output nexus_config.h

Or copy a defconfig:

cp platforms/native/defconfig .config
python scripts/kconfig/generate_config.py --config .config --output nexus_config.h

Build fails with “undefined reference”¶

Cause: Missing library or incorrect link order.

Solution: Check CMakeLists.txt and ensure all required libraries are linked:

target_link_libraries(my_app PRIVATE
    nexus_hal
    nexus_osal
    nexus_platform
)

How do I enable code coverage?¶

cmake -B build \
    -DNEXUS_PLATFORM=native \
    -DNEXUS_ENABLE_COVERAGE=ON \
    -DCMAKE_BUILD_TYPE=Debug
cmake --build build
ctest --test-dir build

# Generate report (Linux/macOS)
bash scripts/coverage/run_coverage_linux.sh

Flashing and Debugging¶

How do I flash to STM32F4?¶

Using OpenOCD:

openocd -f interface/stlink.cfg -f target/stm32f4x.cfg \
    -c "program build-stm32f4/applications/blinky/blinky.elf verify reset exit"

Using st-flash:

st-flash write build-stm32f4/applications/blinky/blinky.bin 0x8000000

Flash verification failed¶

Solution: Erase flash before programming:

openocd -f interface/stlink.cfg -f target/stm32f4x.cfg \
    -c "init" -c "reset halt" -c "flash erase_sector 0 0 last" -c "exit"

How do I debug with GDB?¶

Terminal 1 (OpenOCD):

openocd -f interface/stlink.cfg -f target/stm32f4x.cfg

Terminal 2 (GDB):

arm-none-eabi-gdb build-stm32f4/applications/blinky/blinky.elf
(gdb) target remote localhost:3333
(gdb) monitor reset halt
(gdb) load
(gdb) break main
(gdb) continue

Configuration¶

How do I configure peripherals?¶

Use Kconfig configuration:

  1. Copy platform defconfig:

cp platforms/stm32/defconfig_stm32f4 .config

  1. Edit .config to enable peripherals:

CONFIG_HAL_GPIO=y
CONFIG_HAL_UART=y
CONFIG_HAL_SPI=y

  1. Generate header and build:

python scripts/kconfig/generate_config.py --config .config --output nexus_config.h
cmake --build build

How do I use menuconfig?¶

Linux/macOS only:

pip install kconfiglib
python scripts/kconfig/generate_config.py --menuconfig

Navigate with arrow keys, press Enter to select, Space to toggle, Q to quit and save.

How do I change UART baud rate?¶

Edit .config:

CONFIG_HAL_UART_1_BAUDRATE=115200

Or in code:

hal_uart_config_t config = {
    .baudrate = 115200,
    /* ... */
};
hal_uart_init(HAL_UART_1, &config);

Development¶

How do I create a new application?¶

  1. Create directory:

mkdir applications/my_app
cd applications/my_app

  1. Create CMakeLists.txt:

add_executable(my_app main.c)
target_link_libraries(my_app PRIVATE nexus_hal nexus_platform)

  1. Create main.c:

#include "hal/hal.h"

int main(void) {
    hal_system_init();
    /* Your code */
    return 0;
}

  1. Add to applications/CMakeLists.txt:

add_subdirectory(my_app)

See First Application for detailed guide.

How do I add a new command to shell?¶

static int cmd_handler(int argc, char* argv[]) {
    shell_printf("My command executed\n");
    return 0;
}

static const shell_command_t cmd_def = {
    .name = "mycommand",
    .handler = cmd_handler,
    .help = "My custom command",
    .usage = "mycommand [args]",
    .completion = NULL
};

/* Register command */
shell_register_command(&cmd_def);

How do I use logging?¶

#include "log/log.h"

/* Initialize logging */
log_init(NULL);

/* Log messages */
LOG_ERROR("Error: %d", error_code);
LOG_WARN("Warning: %s", warning_msg);
LOG_INFO("Info: %d", value);
LOG_DEBUG("Debug: %s", debug_info);

How do I use FreeRTOS?¶

Build with FreeRTOS backend:

cmake -B build-freertos \
    -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/arm-none-eabi.cmake \
    -DNEXUS_PLATFORM=stm32f4 \
    -DNEXUS_OSAL_BACKEND=freertos
cmake --build build-freertos

Use OSAL APIs:

#include "osal/osal.h"

void my_task(void* arg) {
    while (1) {
        /* Task work */
        osal_task_delay(1000);
    }
}

int main(void) {
    osal_init();
    osal_task_create(my_task, "my_task", 512, NULL, 1, NULL);
    osal_start_scheduler();
    return 0;
}

Testing¶

How do I run tests?¶

# Using Python script
python scripts/test/test.py

# Or using CTest
cd build
ctest --output-on-failure

How do I run specific tests?¶

# Filter by name
python scripts/test/test.py -f "GPIO*"

# Or with CTest
ctest -R "GPIO*"

How do I add unit tests?¶

Create test file in tests/:

#include <gtest/gtest.h>
#include "hal/gpio.h"

TEST(GPIO, Init) {
    hal_gpio_config_t config = {/* ... */};
    EXPECT_EQ(HAL_OK, hal_gpio_init(HAL_GPIO_PORT_A, 5, &config));
}

Add to tests/CMakeLists.txt:

add_executable(my_tests test_my_module.cpp)
target_link_libraries(my_tests PRIVATE gtest_main nexus_hal)
add_test(NAME MyTests COMMAND my_tests)

Troubleshooting¶

Program doesn’t run on hardware¶

Check:

  1. Flash successful? Verify with st-info --probe

  2. Correct start address? STM32F4 uses 0x08000000

  3. Power supply adequate? Check voltage and current

  4. Reset after flashing? Press reset button or power cycle

No serial output¶

Check:

  1. Correct baud rate? Default is 115200

  2. Correct pins? STM32F4 UART2 uses PA2 (TX), PA3 (RX)

  3. TX/RX swapped? Try swapping connections

  4. Ground connected? Ensure common ground

Build is slow¶

Solutions:

  1. Use parallel build:

cmake --build build -j 8

  1. Use ccache (Linux/macOS):

sudo apt install ccache
export CC="ccache gcc"
export CXX="ccache g++"

  1. Disable tests if not needed:

cmake -B build -DNEXUS_BUILD_TESTS=OFF

Out of memory on embedded target¶

Solutions:

  1. Reduce heap size in Kconfig

  2. Use static allocation instead of dynamic

  3. Reduce buffer sizes

  4. Disable unused features

  5. Use MinSizeRel build type:

cmake -B build -DCMAKE_BUILD_TYPE=MinSizeRel

Getting Help¶

Where can I get help?¶

How do I report a bug?¶

  1. Check if issue already exists

  2. Create new issue on GitHub

  3. Include: * Nexus version * Platform (STM32F4, native, etc.) * Build configuration * Steps to reproduce * Expected vs actual behavior * Error messages and logs

How do I request a feature?¶

  1. Check if feature already requested

  2. Create feature request on GitHub Discussions

  3. Describe: * Use case * Proposed solution * Alternatives considered * Additional context

How do I contribute?¶

See Contributing for contribution guidelines.

Quick steps:

  1. Fork repository

  2. Create feature branch

  3. Make changes

  4. Add tests

  5. Update documentation

  6. Submit pull request

Contributing¶

Can I contribute examples?¶

Yes! We welcome example contributions. See Contributing for guidelines.

Can I port Nexus to a new platform?¶

Yes! See Porting Guide for porting guide.

Can I add support for a new RTOS?¶

Yes! See osal/docs/PORTING_GUIDE.md for OSAL porting guide.

License¶

What license does Nexus use?¶

Nexus is licensed under the MIT License. You can use it freely in commercial and non-commercial projects.

Can I use Nexus in commercial products?¶

Yes, the MIT License allows commercial use without restrictions.

Do I need to open source my application?¶

No, the MIT License does not require you to open source your application code.

Next Steps¶