# expCore

**Repository Path**: ccgaofeng/exp-core

## Basic Information

- **Project Name**: expCore
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-05
- **Last Updated**: 2026-03-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EpxCore: Lightweight Embedded Event-Driven Framework

![Status](https://img.shields.io/badge/Status-Active-green)
![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20STM32-blue)
![License](https://img.shields.io/badge/License-MIT-lightgrey)

**EpxCore** 是面向嵌入式系统的事件驱动微内核框架. 基于进程内 Pub/Sub 消息总线, 模仿 MQTT 的 Topic 与通配符语义, 支持 RPC 远程调用, 服务解耦与跨平台运行. 提供 Linux 仿真版, 集成 WebSocket 网关与 Web 可视化调试工具.

---

## 项目目标与适用场景

**目标:** 在资源受限环境下提供事件驱动、服务解耦、可移植的应用框架. 相比裸机轮询或传统 RTOS 任务耦合, 通过 Topic 订阅实现模块解耦, 便于单元测试与功能扩展.

**适用场景:**
- 智能设备/网关固件, 多模块协同
- 需要 Linux 仿真 + Web 调试的开发流程
- 后续移植到 MCU (如 STM32 + FreeRTOS)

---

## 核心架构

EpxCore 采用分层架构, 实现模块解耦:

```mermaid
flowchart TB
    subgraph Layer4 [Layer 4: Services and Gateway]
        KV[KV Store]
        GW[WebSocket Gateway]
        Log[Log Service]
    end
    subgraph Layer3 [Layer 3: Framework]
        App[App Model]
        RPC[RPC]
    end
    subgraph Layer2 [Layer 2: Core Broker]
        Topic[Topic Trie]
        Msg[Zero-copy Msg]
    end
    subgraph Layer1 [Layer 1: OSAL]
        Thread[Thread]
        Mutex[Mutex]
        Queue[Queue]
        Mem[Memory]
    end
    Layer4 --> Layer3
    Layer3 --> Layer2
    Layer2 --> Layer1
```

| 层级 | 说明 |
|------|------|
| **Layer 1: OSAL** | 屏蔽底层差异, 统一线程、互斥锁、队列、内存接口. 支持 Linux (POSIX), 可扩展 FreeRTOS / Bare-Metal. |
| **Layer 2: Core (Broker)** | 基于 Topic Trie 的发布/订阅总线, 支持 `+` (单层) 与 `#` (多层) 通配符, 零拷贝消息传递. |
| **Layer 3: Framework** | App 生命周期管理, 基于 Pub/Sub 的 RPC 机制. |
| **Layer 4: Services & Gateway** | KV 持久化、WebSocket 网关 (零外部依赖)、Log 服务 (规划中). |

---

## 核心概念

- **Topic:** 层级命名, 如 `home/living_room/light/status`. 长度与深度限制见 [epx_config.h](source/expCore/include/epx_config.h) (`EPX_TOPIC_STR_MAX_LEN`, `EPX_TOPIC_MAX_DEPTH`).
- **通配符:** `+` 匹配单层, `#` 匹配剩余层级 (仅允许末尾, 如 `sensor/#`).
- **消息:** 零拷贝、引用计数 (`epx_msg_retain` / `epx_msg_release`), 由 Broker 按订阅分发.
- **RPC 约定:** Request topic `service/method`, Response topic `service/method/reply/`, payload 含 `req_id` 等.

---

## 快速开始

### 1. 环境准备

- Linux (Ubuntu 20.04+ / WSL2), Windows 可用 WSL2 或 MSYS2
- GCC, CMake 3.10+
- Python 3 (用于自动化测试)

### 2. 构建

```bash
mkdir build
cd build
cmake .. -DTARGET_PLATFORM=LINUX -DENABLE_GATEWAY=ON
make -j4
```

**关键选项:**
- `TARGET_PLATFORM`: LINUX (默认) 或 STM32
- `ENABLE_GATEWAY`: 启用 WebSocket 网关与 Web 可视化 (主程序需此选项才能链接)
- `ENABLE_FRAMEWORK`, `ENABLE_RPC`: 默认 ON
- `BUILD_APP`: 指定应用 (如 `apps/smart_light`, `apps/smart_curtain`), 默认 `apps/smart_curtain`

构建采用分层 CMake: 根目录通过 `add_subdirectory(source)` 与 `add_subdirectory(tests)` 组织. `source/` 下包含 `expCore` 与 `component` (如 cJSON), expCore 内各模块在各自目录通过 CMakeLists.txt 管理.

### 3. 运行

```bash
./expCoreMian
```

可执行文件名为 `expCoreMian`. 启用 Gateway 时监听 8080 端口. 未启用 Gateway 时仅本地 Pub/Sub.

### 4. Web 可视化

1. 保持程序运行.

2. 启动 HTTP 服务器:

```bash
cd tools/web_viz
python3 -m http.server 8000
```

3. 浏览器打开 `http://localhost:8000/index.html`.

4. 连接地址输入 `ws://localhost:8080`, 点击 **Connect**.

5. 可查看实时消息流, 发送 JSON 指令控制系统.

---

## 目录结构

```text
exp-core/
├── cmake/                  # CMake 平台/工具链配置 (如 Platform.cmake)
├── source/                 # 源码树
│   ├── component/         # 第三方/公共组件 (如 cJSON)
│   └── expCore/           # 框架本体
│       ├── include/       # 头文件 (osal, core, framework, services, hal)
│       └── src/           # 源代码 (各子目录含 CMakeLists.txt)
│           ├── apps/      # 应用 (smart_light, smart_curtain)
│           ├── osal/      # OSAL 实现: posix (Linux), freertos (STM32)
│           ├── hal/       # HAL 实现: linux, stm32
│           ├── core/      # 核心逻辑
│           ├── framework/ # 框架实现
│           ├── services/  # 服务实现 (log_svc, gateway_svc 等)
│           └── main.c     # 主入口
├── sdk/                    # Python SDK 与自动化测试
│   ├── epx_client.py      # WebSocket 客户端库
│   └── examples/          # 测试脚本 (auto_test.py, cli_tool.py)
├── tools/                  # 辅助工具
│   ├── web_viz/            # Web 可视化前端 (HTML/JS)
│   └── bridge_proxy/       # 桥接/代理工具
├── tests/                  # C 单元测试 (ENABLE_TESTS 时加入)
└── make_sys/              # Makefile 构建系统 (可选)
```

---

## API 与协议

### 分层 API 概览

| 层 | 头文件 | 主要接口 |
|----|--------|----------|
| OSAL | [osal/epx_os_api.h](source/expCore/include/osal/epx_os_api.h) | thread, mutex, queue, mem |
| Core | [core/epx_broker.h](source/expCore/include/core/epx_broker.h) | `epx_sub` / `epx_pub`, `epx_subscribe` / `epx_publish` |
| Core | [core/epx_msg.h](source/expCore/include/core/epx_msg.h) | `epx_msg_new`, `epx_msg_retain`, `epx_msg_release` |
| Core | [core/epx_topic.h](source/expCore/include/core/epx_topic.h) | `epx_topic_subscribe`, `epx_topic_match` |
| Framework | [framework/epx_app_base.h](source/expCore/include/framework/epx_app_base.h) | App 生命周期, `epx_app_register`, `epx_app_manager_start` |
| Framework | [framework/epx_rpc.h](source/expCore/include/framework/epx_rpc.h) | `epx_rpc_call`, `epx_rpc_reply`, `epx_rpc_register` |
| Services | [services/epx_kv.h](source/expCore/include/services/epx_kv.h) | `epx_kv_set`, `epx_kv_get`, `epx_kv_service_start` |
| Services | [services/epx_web_gateway.h](source/expCore/include/services/epx_web_gateway.h) | `epx_web_gateway_start`, `epx_web_gateway_stop` |
| Services | [services/epx_log.h](source/expCore/include/services/epx_log.h) | `EPX_LOG_INFO`, `EPX_LOG_ERR` 等 |

### RPC 与 KV

- **RPC:** Request topic `service_name/method_name`, Response topic `service_name/method_name/reply/`, payload 含 `req_id`.
- **KV:** 通过 RPC 远程修改配置, 持久化到 `./storage/` 目录.
  - Set: `sys/kv/set` -> `{"key": "wifi.ssid", "val": "MyHome"}`
  - Get: `sys/kv/get` -> `{"key": "wifi.ssid"}`

### Gateway 协议

WebSocket 上行为 JSON 帧: `type` (pub, sub, call, reply), `topic`, `payload`. 详见 [sdk/epx_client.py](sdk/epx_client.py) 与 [tools/web_viz](tools/web_viz).

---

## 测试

### 单元测试 (C)

需 `TARGET_PLATFORM=LINUX`. 构建时加 `-DENABLE_TESTS=ON` 以加入 tests 子目录:

```bash
cd build
cmake .. -DTARGET_PLATFORM=LINUX -DENABLE_TESTS=ON
make run_core_tests
```

验证内核逻辑、内存泄漏 (配合 Valgrind).

### 自动化集成测试 (Python)

```bash
pip3 install websocket-client
python3 sdk/examples/auto_test.py
```

验证 WebSocket 网关、RPC 时序及系统稳定性. 连接地址与端口与「快速开始」一致 (默认 `ws://localhost:8080`).

---

## 移植指南

将 EpxCore 移植到 MCU (如 STM32):

1. **平台选择:** `TARGET_PLATFORM=STM32`, 对应 OSAL `freertos`, HAL `stm32`.

2. **配置:** 修改 [epx_config.h](source/expCore/include/epx_config.h): `EPX_CORE_ENABLE`, `EPX_MAX_TOPICS`, `EPX_FRAMEWORK_ENABLE`, `EPX_RPC_ENABLE` 等.

3. **OSAL 实现:** 使用 `source/expCore/src/osal/freertos/` 或新增实现目录. 实现 `epx_os_mutex`, `epx_os_thread` (可映射到 FreeRTOS), `epx_os_malloc` (可映射到 `pvPortMalloc`). 接口清单见 [osal](source/expCore/include/osal) 头文件.

4. **HAL:** 使用 `source/expCore/src/hal/stm32/`, 在 `source/expCore/src/hal/CMakeLists.txt` 中按平台选择.

5. **网关适配:** 将 gateway_svc 与 osal/linux 扩展中的 Socket 替换为 LwIP.

---

## 下一步

- 开发新 App: 参考 [smart_light](source/expCore/src/apps/smart_light/smart_light.c) 或 [smart_curtain](source/expCore/src/apps/smart_curtain/smart_curtain.c).
- 注册 RPC 服务: 使用 `epx_rpc_register`.
- 添加 Topic 约定: 按业务模块命名层级.

---

## 常见问题

- **Web 连不上:** 检查是否以 `-DENABLE_GATEWAY=ON` 编译, 端口 8080 是否被占用, 防火墙设置.
- **链接错误:** 检查 `ENABLE_GATEWAY` / `ENABLE_RPC` 与 main.c 中调用是否匹配.

---

## 许可证与贡献

本项目采用 MIT 许可证.

欢迎提交 Issue 与 Pull Request.

---

## 开发日志

- **v0.5 (Current):** 集成 KV 存储服务与 Python SDK.
- **v0.4:** 新增 WebSocket Gateway 与 Web 可视化.
- **v0.3:** 实现 Application Model 与 RPC 机制.
- **v0.2:** 实现 Broker 核心 Pub/Sub 功能.
- **v0.1:** OSAL 层定义与 Linux 基础移植.