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

Cannot connect to ST-Link ¶

Windows: Install ST-Link driver from https://www.st.com/en/development-tools/stsw-link009.html

Linux: Add udev rules and user to dialout group:

sudo usermod -a -G dialout $USER
# Log out and log back in

macOS: Should work out of the box. If not, try:

brew install libusb

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:

Copy platform defconfig:

cp platforms/stm32/defconfig_stm32f4 .config

Edit .config to enable peripherals:

CONFIG_HAL_GPIO=y
CONFIG_HAL_UART=y
CONFIG_HAL_SPI=y

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?¶

Create directory:

mkdir applications/my_app
cd applications/my_app

Create CMakeLists.txt:

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

Create main.c:

#include "hal/hal.h"

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

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:

Flash successful? Verify with st-info --probe
Correct start address? STM32F4 uses 0x08000000
Power supply adequate? Check voltage and current
Reset after flashing? Press reset button or power cycle

No serial output ¶

Check:

Correct baud rate? Default is 115200
Correct pins? STM32F4 UART2 uses PA2 (TX), PA3 (RX)
TX/RX swapped? Try swapping connections
Ground connected? Ensure common ground

LEDs don't blink ¶

Check:

Correct pins? STM32F4 Discovery uses PD12-PD15
GPIO initialized? Check initialization code
Power supply? Ensure adequate power
Code running? Check with debugger

Build is slow ¶

Solutions:

Use parallel build:

cmake --build build -j 8

Use ccache (Linux/macOS):

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

Disable tests if not needed:

cmake -B build -DNEXUS_BUILD_TESTS=OFF

Out of memory on embedded target ¶

Solutions:

Reduce heap size in Kconfig
Use static allocation instead of dynamic
Reduce buffer sizes
Disable unused features
Use MinSizeRel build type:

cmake -B build -DCMAKE_BUILD_TYPE=MinSizeRel

Getting Help ¶

Where can I get help?¶

Documentation: https://nexus-platform.github.io/nexus/
GitHub Issues: https://github.com/nexus-platform/nexus/issues
GitHub Discussions: https://github.com/nexus-platform/nexus/discussions
Email: support@nexus-platform.org (if available)

How do I report a bug?¶

Check if issue already exists
Create new issue on GitHub
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?¶

Check if feature already requested
Create feature request on GitHub Discussions
Describe: * Use case * Proposed solution * Alternatives considered * Additional context