# opc_framework

**Repository Path**: Fuhua-Chen/opc_framework

## Basic Information

- **Project Name**: opc_framework
- **Description**: 一个可用于RTOS、协程、裸机环境的oopc框架，该框架由AI构建
- **Primary Language**: C
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-20
- **Last Updated**: 2026-07-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OPC (Object-Oriented Peripheral Control) Framework

OPC 是一个专为 MCU 平台设计的开源、轻量级、高度模块化的通用 C 语言开发框架。它通过在 C99 标准下实现面向对象编程 (OOP) 范式，为嵌入式开发提供了极其优雅、可复用和易维护的代码结构。

## ✨ 核心特性

- **C 语言面向对象 (OOPC)**
  利用宏定义安全地在 C 语言中实现了类 (`CLASS`)、继承 (`EXTENDS`) 和多态虚拟函数表 (`VTABLE`)，让底层设备驱动像 C++ 一样高度解耦。
- **操作系统抽象层 (OSAL)**
  一份代码即可无缝运行在裸机 (Bare-metal)、FreeRTOS、RT-Thread、CMSIS RTOS2 (RTX5)、ARM RTX v4、RTX-Tiny、Zephyr、Azure RTOS ThreadX、OpenHarmony LiteOS 等不同环境下，包含互斥锁、信号量、线程等抽象封装。
- **无栈协程模拟器 (Stackless Coroutine)**
  内建轻量级协程支持 (`opc_co.h`)，在裸机下也能完美实现非阻塞式的多任务并发。
- **发布-订阅 事件系统 (Pub/Sub Event)**
  提供松耦合的跨模块事件通信总线功能，无需复杂的全局变量即可完成模块间交互。
- **统一抽象的硬件接口 (HAL/Porting)**
  统一的 `opc_device` 抽象派生出 UART/GPIO/I2C/SPI 等具体设备，物理层 (Porting) 与逻辑层严格隔离。
- **高度模块化与系统裁剪**
  支持 CMake + Kconfig 进行系统能力裁剪。对外仅暴露唯一伞状头文件 `opc.h`，智能识别开启的特性。
- **平台自动绑定 (Auto Port Binding)**
  框架根据 Kconfig 中的平台配置（`CONFIG_OPC_PLATFORM_PY32` / `CONFIG_OPC_PLATFORM_STM32` 等），在设备创建时自动完成底层 SDK 接口的绑定映射。应用层无需显式调用任何 `opc_port_xxx_attach()`，一套 API 通吃所有平台。
- **环形缓冲区 (Ring Buffer)**
  高效无锁环形缓冲区，用于 UART RX/TX 缓冲、DMA 数据流等场景，支持覆盖写入模式。
- **延迟工作队列 (Work Queue)**
  ISR 安全地将耗时操作推迟到主循环执行，单生产者/单消费者无锁设计。
- **CRC 校验**
  内置 CRC8/16/32 查表法实现，用于通信协议帧校验、固件完整性检查。
- **软件定时器 (Software Timer)**
  支持单次、周期和 N 次触发模式，裸机和所有 RTOS 下统一 API。

## 📂 目录结构

```text
opc/
├── core/                # 核心组件库
│   ├── opc_oopc.h       # C 语言面向对象宏 (CLASS, EXTENDS, VTABLE)
│   ├── opc_list.h       # 双向链表
│   ├── opc_mem.h/.c     # 内存管理
│   ├── opc_log.h/.c     # 日志系统 (支持重定向到任意设备)
│   ├── opc_event.h/.c   # 发布-订阅事件系统
│   ├── opc_co.h/.c      # 无栈协程调度器
│   ├── opc_ringbuf.h/.c # 环形缓冲区 (RX/TX 通用)
│   ├── opc_workq.h/.c   # 延迟工作队列 (ISR→主循环)
│   ├── opc_crc.h/.c     # CRC8/16/32 校验
│   ├── opc_utils.h      # 通用工具宏
│   ├── opc_version.h    # 版本信息
│   └── opc_state.h      # 轻量状态机 (可选)
├── devices/             # 抽象设备层
│   ├── opc_device.h/.c  # 设备基类与虚函数表
│   ├── opc_uart.h/.c    # UART 设备 (内置 RX/TX ringbuf)
│   ├── opc_gpio.h/.c    # GPIO 设备
│   ├── opc_i2c.h/.c     # I2C 设备
│   ├── opc_spi.h/.c     # SPI 设备
│   ├── opc_timer.h/.c   # 软件定时器 (单次/周期/N次)
│   └── opc_usb.h/.c     # USB transport 设备抽象
├── components/          # 组件与服务层 (参与构建)
│   ├── CMakeLists.txt
│   └── opc/
│       └── services/
│           ├── ota/
│           │   ├── opc_ota.h/.c
│           │   ├── partition/
│           │   │   └── opc_partition.h/.c
│           │   └── backends/
│           │       ├── flash_internal/
│           │       │   └── opc_flash_internal.h/.c
│           │       └── flash_qspi/
│           │           └── opc_flash_qspi.h/.c
│           ├── debug/
│           │   └── opc_debug.h/.c
│           └── usb/
│               └── opc_usb_service.h/.c
├── osal/                # 操作系统抽象层
│   ├── opc_osal.h       # OS抽象API (互斥锁、信号量、线程)
│   ├── osal_baremetal.c # 裸机实现
│   ├── osal_freertos.c  # FreeRTOS实现
│   ├── osal_rtthread.c  # RT-Thread实现
│   ├── osal_cmsis_rtos2.c # CMSIS RTOS2 (RTX5) 实现
│   ├── osal_rtx.c       # ARM RTX v4 (CMSIS-RTOS v1) 实现
│   ├── osal_rtx_tiny.c  # ARM RTX-Tiny 实现
│   ├── osal_zephyr.c    # Zephyr RTOS 实现
│   ├── osal_threadx.c   # Azure RTOS ThreadX 实现
│   └── osal_liteos.c    # OpenHarmony LiteOS 实现
├── port/                # 硬件移植层 (需用户根据实际芯片与外设实现)
│   ├── stm32/           # STM32 LL/HAL 库适配
│   ├── esp32/           # ESP-IDF 适配
│   └── mock/            # 仅供PC端开发与测试的模拟移植层
│       ├── opc_port_mock.h/.c
│       └── (支持 UART/GPIO/I2C/SPI 全 Mock)
├── opc.h                # 对外暴露的唯一伞状保护头文件
├── CMakeLists.txt       # 工程顶级构建脚本 (含框架库目标)
├── tools/               # 构建系统与一键工具链 (menuconfig, build 等)
├── projects/           # 应用工程
│   ├── CMakeLists.txt   # 通过 OPC_APP_NAME 动态加载子应用
│   ├── PY32-LED-TEST/   # LED 闪烁示例应用
│   └── <app>/tests/     # 工程内测试代码，与应用一起维护
│   │   ├── main.c
│   │   ├── CMakeLists.txt
│   │   ├── opc_config
│   │   └── opc_config.h
│   └── EDQ202-B/        # 产品应用
│       ├── main.c
│       ├── CMakeLists.txt
│       ├── opc_config
│       └── opc_config.h
├── Kconfig              # 框架裁剪配置菜单
```

## 🧭 分层约定

当前仓库采用下面这套职责边界：

- `core/`: 框架基础设施，只放事件、内存、日志、ringbuf、workq、CRC、协程这类通用能力。
- `devices/`: 通用硬件抽象，只回答“这是什么设备、如何统一访问”。
- `components/opc_services/`: 功能服务层，只回答“框架对外提供什么能力”。
- `components/opc_services/*/backends/`: 某个 service 的可替换具体实现，不单独提升为全局平级层。
- `port/`: 平台与芯片适配层，只做硬件落地，不承载 service 语义。

以 OTA 为例，分层关系是：

```text
service (opc_ota)
  -> backend (opc_flash_internal / opc_flash_qspi)
    -> device (opc_qspi)
      -> port (stm32 / py32 / mock / esp32)
```

这套结构的目标是让 `service` 作为主语，`backend` 作为它的从属实现，避免把带业务语义的模块混入 `devices/` 或 `core/`。

## MI01V2_BL 当前范围

- `MI01V2_BL` 当前只保留 USB 维护与 OTA 入口，不再继续规划 WiFi / 蓝牙 OTA。
- 当前内部 Flash 布局固定为 `bootloader 112KB + metadata 16KB`，因此该项目下没有可用于内部应用镜像的剩余 internal flash 分区。
- 对 `MI01V2_BL` 而言，当前可用的应用升级目标是外部 QSPI XIP A/B 分区。
- 当前能力、边界与未完成项可参考 [docs/mi01v2-bl-capabilities.md](docs/mi01v2-bl-capabilities.md)。

## 🛠️ 构建系统与工具链 (Tools)

OPC Framework 提供了一套原生跨平台的集成工具链（类似于 ESP-IDF），所有工具脚本均存放在 [`tools/` 目录](tools/README.md) 中。

### 环境初始化与使用

打开终端，执行以下命令使工具链在当前终端生效：
- **Windows PowerShell**: `. .\tools\scripts\export.ps1`
- **Windows CMD**: `tools\scripts\export.bat`
- **Linux/macOS**: `source tools/scripts/export.sh`

随后即可在任何目录使用全局命令 `opc`：

#### 工程管理
```bash
opc creat my_app         # 创建新应用工程 (自动生成配置和模板)
opc use my_app           # 切换到指定应用
opc use                  # 查看当前激活的应用
opc list                 # 列出所有可用应用
```

#### 配置与编译
```bash
opc menuconfig           # 图形化配置 (Kconfig)，自动生成 opc_config.h 到应用目录
opc build                # 编译当前激活的应用
opc clean                # 清理构建产物
```

#### 烧录与运行
```bash
opc flash                # 烧录固件
opc monitor              # 串口监视器

# 组合使用
opc build flash monitor  # 一键构建、烧录并监视串口
opc creat app build      # 创建并立即编译
```

> 详情请查阅 **[工具链使用指南 (tools/scripts/README.md)](tools/scripts/README.md)**。

## 🚀 快速上手 (Quick Start)

### 1. 创建应用工程

```bash
# 初始化环境
. .\tools\scripts\export.ps1

# 创建新应用
opc creat my_project

# 配置平台和驱动
opc menuconfig
```

### 2. 编写业务代码

在 `projects/my_project/main.c` 中：

```c
#include "opc.h"

// ── 定时器回调 ──
void on_tick(opc_timer_t *t, void *arg) {
    OPC_LOGI("Tick! remaining: %d", (int)opc_timer_get_remaining(t));
}

int main(void) {
    // 1. 初始化核心系统
    opc_mem_init();
    opc_event_init();
    opc_log_init();
    opc_co_init();

    // 2. 创建设备——框架根据 Kconfig 自动完成平台绑定
    opc_uart_config_t cfg = { .baud_rate = 115200, .data_bits = 8 };
    opc_uart_t *uart = opc_uart_create("uart1", &cfg);
    opc_device_t *dev = (opc_device_t *)uart;

    opc_device_init(dev);
    opc_device_open(dev, OPC_DEVICE_OFLAG_RDWR);
    opc_log_set_output_device(dev);  // 日志输出到串口

    // 3. UART 自动缓冲 (RX ringbuf + TX ringbuf)
    //    Port 层 ISR: opc_uart_feed_rx(uart, data, len)
    //    应用层按需读取: opc_uart_read_rxbuf(uart, buf, len)

    // 4. 软件定时器: 每 500ms 触发, 共 10 次
    opc_timer_t *t = opc_timer_create("demo", 500, on_tick, NULL, 10);
    opc_timer_start(t);

    // 5. 主循环
    OPC_LOGI("--- %s ---", OPC_FULL_NAME);
    while (1) {
        opc_event_loop();    // 事件处理
        opc_co_run();        // 协程调度
        opc_workq_run();     // 延迟工作队列
    }
    return 0;
}
```

> **无需显式调用 `opc_port_xxx_attach()`！** 框架根据 Kconfig 在 `create()` 内部自动完成平台 SDK 绑定。

### 3. 编译与运行

```bash
opc build                # 编译
opc flash monitor        # 烧录并监视
```

### 4. 使用 CMake 直接构建 (可选)

如果您不使用 `opc` 命令行工具，也可以直接通过 CMake 构建：

```bash
mkdir build && cd build
cmake .. -DOPC_APP_NAME=my_project
cmake --build .
```

## 🛠 配置系统 Kconfig 

框架使用 Kconfig 进行可视化裁剪，每个应用拥有独立的 `opc_config` 配置文件。通过 `opc menuconfig` 修改配置后，自动生成 `opc_config.h` 到应用目录下，CMake 根据其中的宏变量（如 `CONFIG_OPC_USING_UART`）自动屏蔽未开启特性的代码链接，精确控制产物体积。

```bash
opc menuconfig           # 图形化配置当前激活的应用
```

配置项包括：
- **目标平台**: STM32 / ESP32 / PY32 / Mock
- **MCU 型号**: 具体芯片型号
- **核心选项**: 动态内存、断言、协程、状态机
- **编译器选项**: 优化级别 (O0~O3, Os, Og)、C 库选择 (newlib-nano / newlib)
- **OS 选择**: Bare-metal / FreeRTOS / RT-Thread / CMSIS-RTOS2 / Zephyr / ThreadX / LiteOS
- **驱动开关**: UART / GPIO / I2C / SPI / Timer

---
*Powered by OPC*