Quick Start

Get up and running with Nexus in 5 minutes! This guide will help you build and run your first example.

Prerequisites

Before starting, ensure you have:

  • Completed Environment Setup

  • Cloned the Nexus repository

  • All required tools installed

If not, go back to Environment Setup first.

Choose Your Platform

Nexus supports multiple platforms. Choose one to get started:

Native Platform (Recommended for First-Time Users)

  • Runs on your PC (Windows/Linux/macOS)

  • No hardware required

  • Fast iteration and debugging

  • Perfect for learning and testing

STM32F4 Discovery Board

  • Real hardware experience

  • LED blinking and GPIO control

  • UART communication

  • Requires STM32F4DISCOVERY board

We’ll cover both platforms in this guide.

5-Minute Quick Start (Native)

Step 1: Clone Repository

# Clone Nexus
git clone https://github.com/nexus-platform/nexus.git
cd nexus

# Initialize submodules
git submodule update --init --recursive

Step 2: Build

Using Python script (recommended):

# Build for native platform
python scripts/building/build.py

# Or with specific options
python scripts/building/build.py -t release -j 8

Using CMake directly:

# Configure
cmake -B build -DCMAKE_BUILD_TYPE=Release -DNEXUS_PLATFORM=native

# Build
cmake --build build --config Release

Step 3: Run Example

# Run blinky example
./build/applications/blinky/blinky

# Or on Windows
.\build\applications\blinky\Release\blinky.exe

You should see output like:

[INFO] HAL initialized
[INFO] GPIO initialized
[INFO] LED blinking started
LED ON
LED OFF
LED ON
LED OFF
...

Step 4: Run Tests (Optional)

# Run all tests
python scripts/test/test.py

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

Congratulations! You’ve successfully built and run Nexus.

Quick Start for STM32F4

Step 1: Prepare Hardware

  • Connect STM32F4DISCOVERY board via USB

  • Verify ST-Link connection:

# Using OpenOCD
openocd -f interface/stlink.cfg -f target/stm32f4x.cfg

# Or ST-Link utilities
st-info --probe

Step 2: Build for STM32F4

Using Python script:

# Build for STM32F4
python scripts/building/build.py --platform stm32f4 --toolchain arm-none-eabi

Using CMake:

# Configure
cmake -B build-stm32f4 \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/arm-none-eabi.cmake \
    -DNEXUS_PLATFORM=stm32f4

# Build
cmake --build build-stm32f4 --config Release

Step 3: Flash to Board

Using OpenOCD:

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

Using ST-Link utilities:

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

Step 4: Observe Results

You should see the LEDs on the STM32F4DISCOVERY board blinking in sequence:

  • Green LED (PD12)

  • Orange LED (PD13)

  • Red LED (PD14)

  • Blue LED (PD15)

Each LED blinks for 500ms.

Exploring Examples

Nexus includes several example applications:

Blinky Example

Simple LED blinking demonstration.

Location: applications/blinky/

Features:

  • GPIO initialization

  • LED control

  • Delay functions

Run:

# Native
./build/applications/blinky/blinky

# STM32F4 (flash to board)
openocd -f interface/stlink.cfg -f target/stm32f4x.cfg \
    -c "program build-stm32f4/applications/blinky/blinky.elf verify reset exit"

Shell Demo

Interactive command-line interface over UART.

Location: applications/shell_demo/

Features:

  • UART communication

  • Command parsing

  • LED control via commands

  • Button status reading

Run:

# Native
./build/applications/shell_demo/shell_demo

# STM32F4 (requires serial terminal)
# 1. Flash to board
# 2. Connect serial terminal (115200 baud, PA2/PA3)
# 3. Type 'help' to see available commands

Available Commands:

nexus> help
Available commands:
  help     - Show this help message
  led      - Control LEDs (led <color> <on|off|toggle>)
  button   - Read button status
  tick     - Show system tick count
  delay    - Delay for specified milliseconds
  reboot   - Reboot the system

Config Demo

Configuration management system demonstration.

Location: applications/config_demo/

Features:

  • Configuration storage

  • Namespace isolation

  • JSON import/export

  • Binary serialization

Run:

# Native
./build/applications/config_demo/config_demo

# STM32F4 (requires serial terminal)
# Connect serial terminal to see output

FreeRTOS Demo

Multi-tasking with FreeRTOS.

Location: applications/freertos_demo/

Features:

  • Task creation

  • Mutex synchronization

  • Queue communication

  • Software timers

Build with FreeRTOS:

# Configure with FreeRTOS backend
cmake -B build-freertos \
    -DNEXUS_PLATFORM=stm32f4 \
    -DNEXUS_OSAL_BACKEND=freertos \
    -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/arm-none-eabi.cmake

# Build
cmake --build build-freertos

Build Options

Common Build Options

# Debug build
python scripts/building/build.py -t debug

# Release build
python scripts/building/build.py -t release

# Clean build
python scripts/building/build.py -c

# Parallel build (8 jobs)
python scripts/building/build.py -j 8

# Specific platform
python scripts/building/build.py --platform stm32f4

Platform Options

Platform

Description

native

Native platform (Windows/Linux/macOS)

stm32f4

STM32F4 series (Cortex-M4)

stm32h7

STM32H7 series (Cortex-M7)

gd32

GD32 series

OSAL Backend Options

Backend

Description

baremetal

No RTOS (default)

freertos

FreeRTOS integration

rtthread

RT-Thread integration

zephyr

Zephyr RTOS integration

Example Configurations

Native with tests:

cmake -B build \
    -DNEXUS_PLATFORM=native \
    -DNEXUS_BUILD_TESTS=ON \
    -DCMAKE_BUILD_TYPE=Debug

STM32F4 with FreeRTOS:

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

STM32H7 minimal size:

cmake -B build-stm32h7-min \
    -DNEXUS_PLATFORM=stm32h7 \
    -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/arm-none-eabi.cmake \
    -DCMAKE_BUILD_TYPE=MinSizeRel

Debugging

Native Platform

Use your favorite debugger:

GDB:

gdb ./build/applications/blinky/blinky

LLDB:

lldb ./build/applications/blinky/blinky

Visual Studio:

Open solution in Visual Studio and press F5.

VS Code:

Use the built-in debugger with C/C++ extension.

STM32F4 Platform

Using OpenOCD and 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) continue

Using VS Code:

Install Cortex-Debug extension and use provided launch configurations.

See IDE Integration for detailed debugging setup.

Common Issues

Build Fails

Issue: CMake configuration fails

CMake Error: Could not find toolchain file

Solution: Ensure ARM toolchain is installed and in PATH:

arm-none-eabi-gcc --version

Issue: Python module not found

ModuleNotFoundError: No module named 'kconfiglib'

Solution: Install Python dependencies:

pip install -r requirements.txt

Flash Fails

Issue: Cannot connect to ST-Link

Error: libusb_open() failed with LIBUSB_ERROR_ACCESS

Solution (Linux): Add udev rules and user to dialout group:

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

Solution (Windows): Install ST-Link driver from ST website.

Issue: 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"

No Output

Issue: Program runs but no output

Native: Check if stdout is buffered. Add fflush(stdout) or run with -u flag.

STM32F4: Verify UART connection and baud rate (115200).

Next Steps

Now that you’ve built and run your first example:

  1. Project Structure - Understand the codebase organization

  2. First Application - Create your own application

  3. Examples Tour - Explore more complex examples

  4. Tutorials - Follow step-by-step tutorials

See Also