Nexus Embedded Platform

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

✨ Key Features

Core Layers

🔧 Hardware Abstraction Layer (HAL) - Unified hardware interface with Kconfig-based compile-time configuration
⚙️ OS Abstraction Layer (OSAL) - Support for FreeRTOS, RT-Thread, Zephyr, and bare-metal
� Framework Layer - Config management, logging, shell, and initialization systems

Development Experience

🌐 Cross-platform Development - Windows, Linux, macOS with native simulation
🧪 Comprehensive Testing - 1539+ tests with 100% code coverage for native platform
📚 Bilingual Documentation - Complete English and Chinese documentation
🛠️ Python Build Tools - Cross-platform scripts for build, test, and format
⚡ Kconfig Configuration - Compile-time configuration system for all peripherals

Advanced Features

🔒 Security - Secure boot, TLS 1.3, hardware crypto acceleration (planned)
☁️ Cloud Integration - AWS IoT, Azure IoT, Alibaba Cloud (planned)
🤖 TinyML - TensorFlow Lite Micro support for edge AI (planned)

🎯 Supported Platforms

Platform	Status	Peripherals	RTOS Support
Native	✅ Production	Full simulation for testing	Bare-metal, FreeRTOS
STM32F4	✅ Production	GPIO, UART, SPI, I2C, ADC, PWM, Timer, DMA, CAN	Bare-metal, FreeRTOS
STM32H7	🚧 In Progress	+ TrustZone, Crypto, Ethernet	Bare-metal, FreeRTOS
GD32	🚧 In Progress	GPIO, UART, SPI, I2C	Bare-metal
ESP32	📋 Planned	+ WiFi, BLE, Touch	FreeRTOS
nRF52	📋 Planned	+ BLE, NFC, Crypto	FreeRTOS, Zephyr

🚀 Quick Start

Prerequisites

All Platforms:

CMake 3.21+
Git
Python 3.8+ (for build scripts and Kconfig)

For Native Build (Testing):

Windows: Visual Studio 2019+ or MSVC Build Tools
Linux: GCC 9+ or Clang 10+
macOS: Xcode Command Line Tools (Clang 12+)

For ARM Cross-Compilation:

ARM GCC Toolchain 10.3+ (arm-none-eabi-gcc)
Download: https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain

For Documentation:

Doxygen 1.9+
Python packages: pip install sphinx breathe sphinx_rtd_theme

Dependency Management

Nexus uses Git submodules for vendor libraries (CMSIS, HAL drivers, FreeRTOS, GoogleTest). The build system automatically initializes required dependencies, but you can also manage them manually:

Automatic (Recommended):

# One-command setup - automatically detects platform from .config
./scripts/setup_deps.sh                          # Linux/macOS
scripts\setup_deps.bat                           # Windows

# Or specify platform explicitly
./scripts/setup_deps.sh --platform=stm32 --series=f4
./scripts/setup_deps.sh --platform=native

Manual:

# Initialize all submodules (not recommended, ~2GB)
git submodule update --init --recursive

# Initialize only what you need (recommended)
# For STM32F4 development:
git submodule update --init vendors/arm/CMSIS_5
git submodule update --init vendors/st/cmsis_device_f4
git submodule update --init vendors/st/stm32f4xx_hal_driver

# For native testing:
git submodule update --init ext/googletest

# For FreeRTOS:
git submodule update --init ext/freertos

CMake Auto-initialization:

The build system automatically initializes missing submodules during configuration. If you encounter dependency errors, run:

./scripts/setup_deps.sh --platform=stm32 --series=f4

See Dependency Management Guide for advanced usage.

Automatic Build (Recommended)

The easiest way to build is using the automatic build scripts with Kconfig:

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

# Install Kconfig tool
pip install kconfiglib

# Configure and build in one command
# Windows
scripts\build.bat --config

# Linux/macOS
./scripts/build.sh --config

# In menuconfig:
# 1. Select Platform Configuration → STM32 Platform (or Native Platform)
# 2. Select Toolchain Configuration → ARM GCC (or GCC/Clang/MSVC for native)
# 3. Select Build Configuration → Debug/Release
# 4. Save with 'S' and exit

# The script automatically:
# - Detects the correct CMake preset from your configuration
# - Configures CMake with the right toolchain
# - Builds the project

See Toolchain Auto-Selection Guide for details.

Build for Native (Host Testing)

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

# Method 1: Using Python script (recommended, cross-platform)
python scripts/building/build.py

# Method 2: Using CMake Presets (CMake 3.21+)
cmake --preset native-debug      # Debug build
cmake --build --preset native-debug

cmake --preset native-release    # Release build
cmake --build --preset native-release

# Method 3: Using CMake directly
cmake -B build -DCMAKE_BUILD_TYPE=Release -DNEXUS_PLATFORM=native
cmake --build build --config Release

# Run tests
python scripts/test/test.py
# Or: ctest --test-dir build -C Release --output-on-failure

Build for STM32F4

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

# Method 2: Using CMake Presets (CMake 3.21+)
cmake --preset stm32f4-debug     # Debug build
cmake --build --preset stm32f4-debug

cmake --preset stm32f4-release   # Release build
cmake --build --preset stm32f4-release

# Method 3: Using CMake directly
cmake -B build-stm32f4 \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/arm-none-eabi.cmake \
    -DNEXUS_PLATFORM=stm32f4

cmake --build build-stm32f4 --config Release

# Output: build-stm32f4/applications/blinky/blinky.elf

Build Options

Option	Default	Description
`NEXUS_PLATFORM`	`native`	Target platform: `native`, `stm32f4`, `stm32h7`, `gd32`, `esp32`, `nrf52`
`NEXUS_OSAL_BACKEND`	`baremetal`	OSAL backend: `baremetal`, `freertos`, `rtthread`, `zephyr`
`NEXUS_BUILD_TESTS`	`ON`	Build unit tests (native only)
`NEXUS_BUILD_EXAMPLES`	`ON`	Build example applications
`NEXUS_ENABLE_COVERAGE`	`OFF`	Enable code coverage analysis
`CMAKE_BUILD_TYPE`	`Debug`	Build type: `Debug`, `Release`, `MinSizeRel`, `RelWithDebInfo`

CMake Presets

The project includes CMakePresets.json for standardized configurations:

# List available presets
cmake --list-presets

# Use a preset
cmake --preset native-debug
cmake --build --preset native-debug

# Common presets:
# - native-debug: Native platform debug build
# - native-release: Native platform release build
# - stm32f4-debug: STM32F4 debug build
# - stm32f4-release: STM32F4 release build

📖 First Project

Create a simple LED blink application:

#include "hal/nx_factory.h"
#include "osal/osal.h"

int main(void)
{
    /* Initialize OSAL and HAL */
    osal_init();
    nx_hal_init();

    /* Get GPIO device (Port A, Pin 5) */
    nx_gpio_write_t* led = nx_factory_gpio_write('A', 5);
    if (!led) {
        return -1;
    }

    /* Configure as output (done via Kconfig at compile-time) */
    led->set_mode(led, NX_GPIO_MODE_OUTPUT_PP);

    /* Blink loop */
    while (1) {
        led->toggle(led);
        osal_task_delay(500);  /* 500ms delay */
    }

    /* Cleanup (never reached) */
    nx_factory_gpio_release((nx_gpio_t*)led);
    nx_hal_deinit();
    return 0;
}

Configure via Kconfig

# In your project's Kconfig or defconfig

# Enable GPIO Port A Pin 5
CONFIG_HAL_GPIO_A_5=y
CONFIG_HAL_GPIO_A_5_MODE=OUTPUT_PP
CONFIG_HAL_GPIO_A_5_PULL=NONE
CONFIG_HAL_GPIO_A_5_SPEED=LOW
CONFIG_HAL_GPIO_A_5_LEVEL=LOW

📁 Project Structure

nexus/
├── hal/                    # Hardware Abstraction Layer
│   ├── include/hal/        #   Public API headers
│   ├── src/                #   Common implementations
│   ├── docs/               #   Complete documentation (EN/CN)
│   └── Kconfig             #   HAL configuration options
├── osal/                   # OS Abstraction Layer
│   ├── include/osal/       #   Public API headers
│   ├── adapters/           #   RTOS adapters (baremetal, freertos, rtthread)
│   ├── docs/               #   Complete documentation (EN/CN)
│   └── Kconfig             #   OSAL configuration options
├── framework/              # High-level frameworks
│   ├── config/             #   Configuration management system
│   ├── log/                #   Logging system
│   ├── shell/              #   Command shell
│   └── init/               #   Initialization framework
├── platforms/              # Platform-specific implementations
│   ├── native/             #   Host simulation (Windows/Linux/macOS)
│   ├── stm32/              #   STM32 family (F4, H7)
│   ├── gd32/               #   GigaDevice GD32
│   ├── esp32/              #   Espressif ESP32
│   ├── nrf52/              #   Nordic nRF52
│   └── Kconfig             #   Platform configuration
├── applications/           # Example applications
│   ├── blinky/             #   LED blink example
│   ├── shell_demo/         #   Command shell demo
│   ├── config_demo/        #   Configuration system demo
│   └── freertos_demo/      #   FreeRTOS integration demo
├── tests/                  # Comprehensive test suite (1539+ tests)
│   ├── hal/                #   HAL unit and property tests
│   ├── osal/               #   OSAL tests
│   ├── config/             #   Config framework tests
│   ├── log/                #   Log framework tests
│   ├── shell/              #   Shell framework tests
│   ├── init/               #   Init framework tests
│   └── integration/        #   Integration tests
├── docs/                   # Documentation
│   ├── api/                #   Doxygen API documentation
│   ├── sphinx/             #   User guides (EN/CN)
│   └── requirements/       #   Requirements and design docs
├── scripts/                # Build and utility scripts
│   ├── building/           #   Build scripts (Python/Bash/Batch)
│   ├── test/               #   Test scripts
│   ├── tools/              #   Format, clean, docs scripts
│   └── coverage/           #   Coverage analysis scripts
├── cmake/                  # CMake modules
│   ├── modules/            #   Helper functions
│   └── toolchains/         #   Cross-compilation toolchains
├── vendors/                # Vendor SDKs and libraries
│   ├── st/                 #   STMicroelectronics
│   ├── espressif/          #   Espressif
│   ├── nordic/             #   Nordic Semiconductor
│   └── arm/                #   ARM CMSIS
├── ext/                    # External dependencies
│   ├── freertos/           #   FreeRTOS kernel
│   └── googletest/         #   Google Test framework
└── .github/workflows/      # CI/CD pipelines
    ├── build.yml           #   Multi-platform build
    ├── test.yml            #   Unit tests with coverage
    └── docs.yml            #   Documentation deployment

📚 Documentation

Online Documentation

Visit our comprehensive documentation site: nexus-platform.github.io/nexus

English: https://nexus-platform.github.io/nexus/en/
中文: https://nexus-platform.github.io/nexus/zh_CN/
API Reference: https://nexus-platform.github.io/nexus/api/

Build Documentation Locally

# Install dependencies
pip install sphinx breathe sphinx_rtd_theme

# Build all documentation (API + User Guides)
python scripts/tools/docs.py

# Or build separately:

# API documentation (Doxygen)
doxygen Doxyfile

# User guides (Sphinx)
cd docs/sphinx
sphinx-build -b html . _build/html/en                    # English
sphinx-build -b html -D language=zh_CN . _build/html/cn  # Chinese

Module Documentation

Each module has comprehensive documentation:

HAL (Hardware Abstraction Layer)

📖 Overview
👤 User Guide - Complete API usage and examples
🏗️ Design Document - Architecture and implementation
🧪 Testing Guide - Test strategy and cases
🔧 Porting Guide - How to port to new platforms
🔍 Troubleshooting - Common issues and solutions

OSAL (OS Abstraction Layer)

📖 Overview
👤 User Guide - Tasks, synchronization, memory
🏗️ Design Document - RTOS adapter architecture
🧪 Testing Guide - Unit and integration tests
🔧 Porting Guide - Adapt to new RTOS
🔍 Troubleshooting - Debugging tips

Framework Modules

⚙️ Config System - Configuration management
📝 Log System - Logging framework
💻 Shell System - Command shell
🚀 Init System - Initialization framework

🛠️ Development

Using Python Scripts (Recommended)

# Build
python scripts/building/build.py                 # Debug build
python scripts/building/build.py -t release      # Release build
python scripts/building/build.py -c              # Clean build
python scripts/building/build.py -j 8            # Parallel build (8 jobs)

# Test
python scripts/test/test.py                      # Run all tests
python scripts/test/test.py -f "GPIO*"           # Filter tests
python scripts/test/test.py -v                   # Verbose output
python scripts/test/test.py --xml report.xml     # Generate XML report

# Format code
python scripts/tools/format.py                   # Format all code
python scripts/tools/format.py --check           # Check formatting only

# Clean
python scripts/tools/clean.py                    # Clean build artifacts

# Generate documentation
python scripts/tools/docs.py                     # Build all docs

Code Style

This project follows strict coding standards:

C Standard: C11
C++ Standard: C++17 (tests use C++20)
Line Length: 80 characters maximum
Indentation: 4 spaces (no tabs)
Naming: snake_case for functions and variables
Comments: Doxygen with backslash style (\brief, \param)

Format code before committing:

python scripts/tools/format.py

Doxygen Comment Style

Use backslash style for Doxygen comments:

/**
 * \file            nx_gpio.h
 * \brief           GPIO device interface definition
 * \author          Nexus Team
 */

/**
 * \brief           Get GPIO device with write capability
 * \param[in]       port: GPIO port ('A'-'K')
 * \param[in]       pin: GPIO pin number (0-15)
 * \return          GPIO write interface pointer, NULL on failure
 */
nx_gpio_write_t* nx_factory_gpio_write(char port, uint8_t pin);

Running Tests

# Using Python script (recommended)
python scripts/test/test.py                      # All tests
python scripts/test/test.py -f "GPIO*"           # Specific suite
python scripts/test/test.py -l unit              # By label
python scripts/test/test.py -v                   # Verbose

# Using CTest directly
cd build
ctest -C Release --output-on-failure             # All tests
ctest -C Release -R "GPIO*"                      # Specific suite
ctest -C Release -L unit                         # By label
ctest -C Release -j8                             # Parallel (8 jobs)

Test Statistics

Current test suite contains:

Total Tests: 1539+ tests
HAL Tests: ~400 tests (unit + property-based)
OSAL Tests: ~200 tests
Config Tests: ~300 tests
Log Tests: ~130 tests
Shell Tests: ~400 tests
Init Tests: ~15 tests
Integration Tests: ~40 tests

Code Coverage

Generate code coverage reports:

# Linux/WSL
cd scripts/coverage
./run_coverage_linux.sh

# Windows (PowerShell)
cd scripts\coverage
.\run_coverage_windows.ps1

# View report
# Linux: xdg-open ../../coverage_html/index.html
# Windows: start ..\..\coverage_report\html\index.html

Target: 100% code coverage for native platform HAL implementations.

🔄 CI/CD

GitHub Actions workflows automatically run on every push and pull request:

Workflow	Description	Triggers
ci.yml	Unified continuous integration pipeline	Push, PR
build-matrix.yml	Multi-platform build testing (Windows, Linux, macOS, ARM)	Push, PR
docs-build.yml	Build and deploy documentation to GitHub Pages	Push to main
quality-checks.yml	Code quality validation and static analysis	Push, PR
performance.yml	Performance benchmarking and regression testing	Push to main, Manual
release.yml	Automated release process and artifact publishing	Tag push

Modular Architecture

The CI/CD system uses a modular architecture with reusable actions:

Reusable Actions in .github/actions/:
- setup-build/ - Common build environment setup
- Shared across multiple workflows for consistency

CI Status

✅ All platforms build successfully
✅ 1539+ tests passing
✅ Code coverage > 95%
✅ Documentation builds successfully
✅ Quality checks passing

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

Development environment setup
Code style guidelines
Testing requirements (all contributions must include tests)
Pull request process
Documentation guidelines

Quick checklist before submitting a PR:

Code follows style guidelines (python scripts/tools/format.py)
All tests pass (python scripts/test/test.py)
New code has corresponding tests
Documentation is updated
Commit messages follow conventional commits

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🌟 Community

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: Online Docs
Changelog: CHANGELOG.md

🗺️ Roadmap

v0.1.0 (Current)

✅ HAL core functionality (GPIO, UART, SPI, I2C, ADC, PWM, CAN)
✅ OSAL core functionality (tasks, synchronization, memory)
✅ Framework modules (Config, Log, Shell, Init)
✅ STM32F4 platform support
✅ Native platform for testing
✅ Kconfig configuration system
✅ Comprehensive testing (1539+ tests)
✅ Complete bilingual documentation

v0.2.0 (Planned)

🚧 STM32H7 platform support
🚧 GD32 platform support
🚧 DMA advanced features
🚧 Low-power management
🚧 Enhanced security features

v1.0.0 (Future)

📋 ESP32 platform support
📋 nRF52 platform support
📋 Cloud integration (AWS IoT, Azure IoT)
📋 TinyML support
📋 Secure boot implementation

🙏 Acknowledgments

Thanks to all contributors who have helped make Nexus better!

Special thanks to:

FreeRTOS team for the excellent RTOS
Google Test team for the testing framework
Doxygen and Sphinx teams for documentation tools

Made with ❤️ by the Nexus Team

Building the future of embedded systems, one commit at a time.

Name		Name	Last commit message	Last commit date
Latest commit History 330 Commits
.github		.github
.kiro/steering		.kiro/steering
.vscode		.vscode
applications		applications
cmake		cmake
docs		docs
ext		ext
framework		framework
hal		hal
osal		osal
platforms		platforms
scripts		scripts
tests		tests
vendors		vendors
.clang-format		.clang-format
.clang-format-dirs		.clang-format-dirs
.clang-tidy		.clang-tidy
.config		.config
.config.old		.config.old
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitmodules		.gitmodules
CHANGELOG.md		CHANGELOG.md
CHANGELOG_CN.md		CHANGELOG_CN.md
CMakeLists.txt		CMakeLists.txt
CMakePresets.json		CMakePresets.json
CONTRIBUTING.md		CONTRIBUTING.md
CONTRIBUTING_CN.md		CONTRIBUTING_CN.md
Doxyfile		Doxyfile
Kconfig		Kconfig
LICENSE		LICENSE
README.md		README.md
README_CN.md		README_CN.md
codecov.yml		codecov.yml
nexus_config.h		nexus_config.h
pytest.ini		pytest.ini
requirements.txt		requirements.txt
setup.py		setup.py

Folders and files

Latest commit

History

Repository files navigation

Nexus Embedded Platform

✨ Key Features

Core Layers

Development Experience

Advanced Features

🎯 Supported Platforms

🚀 Quick Start

Prerequisites

Dependency Management

Automatic Build (Recommended)

Build for Native (Host Testing)

Build for STM32F4

Build Options

CMake Presets

📖 First Project

Configure via Kconfig

📁 Project Structure

📚 Documentation

Online Documentation

Build Documentation Locally

Module Documentation

HAL (Hardware Abstraction Layer)

OSAL (OS Abstraction Layer)

Framework Modules

🛠️ Development

Using Python Scripts (Recommended)

Code Style

Doxygen Comment Style

Running Tests

Test Statistics

Code Coverage

🔄 CI/CD

Modular Architecture

CI Status

🤝 Contributing

📄 License

🌟 Community

🗺️ Roadmap

v0.1.0 (Current)

v0.2.0 (Planned)

v1.0.0 (Future)

🙏 Acknowledgments

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages