架构

This document provides a detailed overview of the Nexus platform architecture.

设计原则

Nexus is built on the following design principles:

  1. Separation of Concerns: Each layer has a specific responsibility

  2. Abstraction: Hide implementation details behind clean interfaces

  3. Portability: Minimize platform-specific code in applications

  4. Testability: Design for unit testing and simulation

  5. Resource Efficiency: Optimize for constrained embedded systems

分层架构

┌─────────────────────────────────────────────────────────────┐
│                      Applications                            │
├─────────────────────────────────────────────────────────────┤
│                      Middleware                              │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐           │
│  │  Shell  │ │   Log   │ │  Config │ │  Event  │           │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘           │
├─────────────────────────────────────────────────────────────┤
│                         OSAL                                 │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐           │
│  │  Task   │ │  Mutex  │ │  Queue  │ │  Timer  │           │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘           │
├─────────────────────────────────────────────────────────────┤
│                          HAL                                 │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐           │
│  │  GPIO   │ │  UART   │ │   SPI   │ │   I2C   │           │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘           │
├─────────────────────────────────────────────────────────────┤
│                    Platform / Hardware                       │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐           │
│  │ STM32F4 │ │ STM32H7 │ │  ESP32  │ │  nRF52  │           │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘           │
└─────────────────────────────────────────────────────────────┘

应用层

User applications built on top of Nexus platform. Applications should:

  • Use only public APIs from lower layers

  • Avoid direct hardware access

  • Be portable across supported platforms

中间件层

Common services that provide higher-level functionality:

  • Log Framework: Flexible logging with multiple backends

  • Shell: Command-line interface for debugging

  • Config: Configuration management and persistence

  • Event: Event-driven programming support

See 日志框架 for detailed Log Framework documentation.

OSAL Layer

OS Abstraction Layer provides portable RTOS primitives:

  • Task: Thread/task management

  • Mutex: Mutual exclusion locks

  • Semaphore: Binary and counting semaphores

  • Queue: Message queues for inter-task communication

  • Timer: Software timers

Supported backends:

  • FreeRTOS

  • Native (pthreads for PC simulation)

  • Bare-metal (cooperative scheduling)

See 操作系统抽象层 (OSAL) for detailed OSAL documentation.

HAL Layer

Hardware Abstraction Layer provides unified peripheral APIs:

  • GPIO: General-purpose I/O

  • UART: Serial communication

  • SPI: SPI bus master/slave

  • I2C: I2C bus master/slave

  • Timer: Hardware timers and PWM

  • ADC: Analog-to-digital conversion

See 硬件抽象层 (HAL) for detailed HAL documentation.

平台层

MCU-specific implementations including:

  • Startup code and system initialization

  • Linker scripts

  • Vendor SDK integration

  • Clock and power management

数据流

Application
    │
    ▼
┌─────────────────┐
│   Middleware    │  ← Uses OSAL for threading, HAL for I/O
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│      OSAL       │  ← Uses HAL for timing
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│       HAL       │  ← Uses Platform for hardware access
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│    Platform     │  ← Direct hardware access
└─────────────────┘

依赖规则

Strict dependency rules ensure clean architecture:

  1. Upper layers depend on lower layers (never reverse)

  2. Same-layer components are independent (no horizontal dependencies)

  3. Platform layer is the only layer with hardware access

✅ Application → Middleware → OSAL → HAL → Platform
❌ HAL → Middleware (reverse dependency)
❌ GPIO → UART (horizontal dependency within HAL)

内存管理

Nexus supports multiple memory management strategies:

Static Allocation

All memory allocated at compile time. Suitable for safety-critical systems.

Dynamic Allocation

Runtime memory allocation using malloc/free. More flexible but requires careful management.

Pool Allocation

Fixed-size memory pools for predictable allocation patterns.

Configuration example:

/* Static allocation mode */
#define NEXUS_USE_STATIC_ALLOC  1
#define NEXUS_MAX_TASKS         8
#define NEXUS_MAX_MUTEXES       16

错误处理

All Nexus APIs follow consistent error handling:

/* All functions return status codes */
hal_status_t status = hal_gpio_init(port, pin, &config);
if (status != HAL_OK) {
    /* Handle error */
    LOG_ERROR("GPIO init failed: %d", status);
}

Common status codes:

Status

Description

XXX_OK

Operation successful

XXX_ERROR

General error

XXX_ERROR_PARAM

Invalid parameter

XXX_ERROR_STATE

Invalid state

XXX_ERROR_TIMEOUT

Operation timed out

XXX_ERROR_NO_MEMORY

Memory allocation failed

构建系统

Nexus uses CMake for cross-platform build configuration:

# Select platform
cmake -B build -DNEXUS_PLATFORM=stm32f4

# Enable features
cmake -B build \
    -DNEXUS_PLATFORM=stm32f4 \
    -DNEXUS_BUILD_TESTS=ON \
    -DNEXUS_ENABLE_LOG=ON

Key CMake options:

Option

Description

NEXUS_PLATFORM

Target platform (stm32f4, native)

NEXUS_BUILD_TESTS

Build unit tests

NEXUS_ENABLE_LOG

Enable log framework

NEXUS_ENABLE_COVERAGE

Enable code coverage

下一步