Metadata-Version: 2.4
Name: lynx-sdk
Version: 0.10.2
Summary: Lynx SDK Build System — West-style CLI for embedded projects
Author: Lynx SDK Team
Requires-Python: >=3.10,<3.14
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: bleak (>=0.21)
Requires-Dist: cryptography (>=41.0)
Requires-Dist: kconfiglib (>=14.1)
Requires-Dist: pyserial (>=3.5)
Requires-Dist: pyyaml (>=6.0)
Requires-Dist: textual (>=0.89)
Requires-Dist: tqdm (>=4.64)
Requires-Dist: windows-curses (>=2.0) ; sys_platform == "win32"
Description-Content-Type: text/markdown

# Lynx SDK — 智能照明嵌入式 SDK

基于 Telink RISC-V MCU 的 BLE Mesh 智能照明系统 SDK，集成灯光控制、动态特效引擎、二进制通信协议栈及完整的构建工具链。

## 平台规格

| 项目 | 规格 |
|------|------|
| 目标芯片 | Telink TL321X / TL322X / TL721X / B91 / B92 |
| 主力平台 | TL321X (RISC-V D25F, 48MHz) |
| Flash / RAM | 1MB / 112KB |
| RTOS | FreeRTOS V10.4.2 |
| 构建系统 | CMake + GCC 12.2 (nds32le-elf-mculib-v5) |
| 配置系统 | Kconfig (kconfiglib) |
| CLI 工具 | Python (Poetry) — `lynx` 命令行工具 |

## 目录结构

```
lynx_sdk/
├── lynx_app/              # BLE 基础应用（Telink SDK 示例入口）
├── lynx_fi_app/           # 智能照明应用层固件
│   ├── lynx_lighting/     #   灯光控制子系统（PWM/WS2812/色彩科学/运行时）
│   ├── lynx_dfx/          #   动态特效引擎（13种特效，60FPS）
│   ├── lynx_protocol/     #   二进制通信协议栈（Open-Fi + LYNX CI）
│   ├── lynx_ci/           #   CI 桥接层（Mesh网络桥接/虚拟串口/日志）
│   └── CMakeLists.txt
├── lynx_wireless/          # SDK 核心框架层
│   ├── bsp/               #   板级支持包（加密/Flash映射/Mesh BLE适配）
│   ├── drivers/           #   设备驱动（UART/Counter/VUART HAL）
│   ├── include/           #   公共头文件（API接口定义）
│   │   └── lynx_wireless/  #     蓝牙/驱动/库/日志/移植层/系统
│   ├── lib/               #   通用库（buffer/ring_buf/pipeline/AES/MD5/bcast_vq）
│   ├── platform/          #   平台抽象层
│   ├── port/              #   SoC 移植层（TL321X 实现）
│   ├── stack/             #   BLE Mesh 协议栈
│   │   └── lynx_mesh/     #     Bearer/Config/Network/Proxy/RF/Scheduler/Security
│   ├── subsys/            #   子系统
│   │   ├── at/            #     AT 指令解析器
│   │   ├── ble/gatt/      #     GATT 服务（Mesh Proxy Service）
│   │   ├── event/         #     Mesh 事件定义
│   │   ├── event_bus/     #     事件总线
│   │   ├── lfs/           #     LittleFS 文件系统
│   │   ├── log/           #     日志系统
│   │   ├── mesh_ci/       #     Mesh CI 子系统
│   │   ├── os/            #     OS 抽象层 (FreeRTOS / Baremetal)
│   │   ├── storage/       #     Raw flash 存储（NVS ring journal / object API）
│   │   └── work_queue/    #     工作队列
│   ├── tests/             #     单元测试 (Unity)
│   ├── docs/              #     框架设计文档
│   ├── partitions.csv     #     Flash 分区表
│   └── lynxconfig         #     Kconfig 默认配置
├── lynx_hal/              # Telink BLE SDK HAL
│   └── tl_ble_sdk/        #   芯片驱动（B91/B92/TL321X/TL322X/TL323X/TL721X）
│       ├── drivers/       #     SoC 外设驱动
│       ├── boot/          #     启动链接脚本
│       ├── common/        #     公共工具/类型
│       ├── application/   #     USB/键盘应用
│       ├── 3rd-party/     #     FreeRTOS V5
│       └── algorithm/     #     加密算法
├── scripts/               # CLI 工具 & 构建脚本 (Python, Poetry)
│   └── lynx_sdk/          #   West-style CLI: configure/build/flash/clean/sniffer/tui
├── lynx_sniffer_app/      # S2 Private Protocol Sniffer 固件与协议文档
├── lynx_samples/           # Zephyr-style 示例固件项目
│   └── nvs_test/           #   NVS 存储 KV + Object API 片上测试
├── cmake/                 # 构建系统模块（版本/分区/Kconfig/boilerplate）
├── lynx.yml               # 工作空间配置（工具链/后端/板子/项目）
├── lynx.exe               # CLI 可执行文件
└── docs/                  # 项目文档
    └── README.md          #   本文件
```

## 核心架构

```
┌────────────────────────────────────────────────────────────────┐
│                     lynx_fi_app（应用层）                       │
│  lynx_fi_app_main.c — 统一生命周期编排                          │
│  init: light → dfx → ci_bridge                                │
│  loop(10ms): light_task → dfx_task → wd_clear → delay         │
├────────────────────────────────────────────────────────────────┤
│  lynx_lighting    lynx_dfx         lynx_protocol               │
│  灯光控制子系统    动态特效引擎      二进制通信协议栈              │
│  PWM/WS2812       13种特效/60FPS   Open-Fi + LYNX CI           │
│  CCT/HSI色彩      CCT/HSI输出      位级紧凑编码                 │
│  4种工作模式      BCM回调输出       数据驱动编解码               │
├────────────────────────────────────────────────────────────────┤
│                     lynx_wireless（SDK框架层）                    │
│  lynx_mesh栈 │ 驱动(UART/Counter) │ OSAL │ 事件总线 │ AT解析  │
│  Bearer/Net  │ HAL(VUART)        │ Free │ EventBus │ Parser  │
│  Proxy/RF    │ Port(TL321X)      │ RTOS │          │         │
├────────────────────────────────────────────────────────────────┤
│                     lynx_hal（HAL层）                           │
│  Telink tl_ble_sdk — SoC外设驱动 + 启动代码 + FreeRTOS移植     │
└────────────────────────────────────────────────────────────────┘
```

## 三大应用模块

### 1. lynx_lighting — 灯光控制子系统

- **硬件驱动**：双色温PWM(WW/CW)、RGB PWM、WS2812 SPI DMA (70颗LED)、屏幕帧缓冲(7x10)
- **色彩科学**：CCT色温计算(Q10定点)、HSI→RGB转换
- **4种工作模式**：NORMAL(CCT/HSI) / SPECTRA / DFX / PROPRIETARY
- **9种像素光效**：火焰/分流/扫描/时钟/均衡器/贪吃蛇/打砖块/倒计时/心跳
- **Flash持久化**：灯光状态(0xF0000) + 设备配置(0xF1000)，CRC16校验+磨损均衡
- **按键UI**：单击/双击/长按，模式切换

### 2. lynx_dfx — 动态特效引擎

- **13种特效(24子模式)**：蜡烛/电视/闪光/警灯/烟花/灯泡/派对/闪电/云层/频闪/呼吸/焊接/寻灯
- **60FPS帧调度**：函数指针分发表 + 周期帧驱动
- **BCM回调输出**：CCT/HSI数据包 → Open-Fi帧 → Mesh网络
- **协议桥接**：LYNX_CI帧解析 → runtime状态 → 引擎驱动
- **持久化**：16-byte槽位化Flash存储，掉电恢复

### 3. lynx_protocol — 通信协议栈

- **protocol_core**：位操作/CRC8/payload编解码/帧构建解析（数据驱动架构）
- **open_fi_proto**：Open-Fi灯光控制协议（INT/CCT/HSI/IRGB/XY等命令）
- **lynx_ci_proto**：LYNX CI特效协议（DFX_STD/DFX_FADE命令）
- **位级紧凑编码**：41-bit→6B (~40%节省)、81-bit→11B (~42%节省)

## Flash 分区 (TL321X)

| 分区 | 起始地址 | 大小 | 用途 |
|------|---------|------|------|
| bootloader | 0x00000000 | 60KB | 引导程序 |
| iap_param | 0x0000F000 | 4KB | IAP 参数 |
| image_primary | 0x00010000 | 416KB | 主固件 |
| image_secondary | 0x00078000 | 416KB | 备份固件 |
| nv_param | 0x000E0000 | 4KB | NV 参数 |
| fs | 0x000E1000 | 92KB | 文件系统 |

## 构建与使用

### 前置条件

- Python >= 3.10
- Poetry (Python 包管理)
- Telink 工具链 (`nds32le-elf-mculib-v5`)
- CMake >= 3.20

### CLI 工具

```bash
# 构建 Kepler (默认项目)
lynx build --configure

# 构建指定项目
lynx build kepler --configure
lynx build kepler_sniffer --configure

# 仅配置 (不构建)
lynx configure kepler

# 清理构建目录
lynx clean --configure
```

| 选项 | 说明 |
|------|------|
| `project` (位置参数) | 项目名称 (来自 lynx.yml)，默认使用 `defaults.project` |
| `--configure` | 强制重新运行 CMake 配置 + Kconfig |
| `--target` | CMake 构建目标 |
| `--require-cmake-json` | 启用 xxx_cmake.json 检查 (默认关闭) |
| `--define KEY=VALUE` | 覆盖 CMake 定义 |
| `-G, --generator` | CMake 生成器 (Ninja / Unix Makefiles) |

### Sniffer CLI / TUI

```bash
# 构建 S2 sniffer 固件
./lynx.exe build kepler_sniffer

# 自动探测 UART 并进入交互式 sniffer shell
lynx sniffer

# 指定串口执行一次性命令
lynx sniffer hello --port COM7
lynx sniffer set-map --channels 10,22,34,38 --interval-ms 4000 --port COM7
lynx sniffer set-filter --allow-channel 10,22 --min-rssi -90 --port COM7
lynx sniffer start --count 10 --file abc.pcapng --decode lynx-wireless --port COM7
lynx sniffer stats --port COM7

# 打开 Lynx TUI，左侧选择 Sniffer 可使用专用 sniffer 面板
lynx tui
```

`start --file <capture.pcapng>` 会在主机侧写 PCAPNG 文件；设备仍然只发送二进制 sniffer 帧，CLI/TUI 负责把 `EVT_PCAP_PACKET` 中的原始 payload 写入文件，同时继续输出日志。`start --decode lynx-wireless` 会使用内置 Lynx Mesh decoder 把捕获到的 payload 解码为 adv type、地址、seq、TTL、payload CRC 等字段；也可用 `--decode module:function` 或 `--decode path/to/file.py:function` 指定自定义 Python decoder。

### Samples

`lynx_samples/` 包含 Zephyr 风格的示例固件项目，每个示例是独立的可构建项目，拥有自己的 `sample.yml`（通过 `lynx.yml` 的 `project_files:` 引用）。

```bash
# 构建 NVS 测试示例
lynx build nvs_test --configure

# 烧录并运行
lynx flash write nvs_test
```

当前示例：
- `nvs_test` — 片上 NVS 存储测试（KV + Object API），通过调试串口输出结果


```bash
# Kepler — 最小 BLE OTA 测试应用
cmake -B cmake_builds/kepler \
      -DBOARD=tl321x_evk \
      -DCMAKE_TOOLCHAIN_FILE=cmake/toolchain-nds32le-elf.cmake \
      -G "Unix Makefiles" \
      -DCMAKE_MAKE_PROGRAM=<cygwin>/bin/make.exe
cmake --build cmake_builds/kepler

# 输出
cmake_builds/kepler/
├── Kepler        (ELF)
├── Kepler.bin    (二进制固件)
├── Kepler.lst    (反汇编清单)
└── Kepler.map    (链接符号表)
```

### Kconfig 配置

```bash
# 修改配置
poetry run lynx configure

# 或手动编辑
# lynx_wireless/lynxconfig
```

## NVS Raw Flash 存储

`lynx_wireless/subsys/storage/nvs` 提供直接运行在 raw flash 上的轻量 NVS 后端，可作为配置、参数和命名对象的持久化层。应用可以用 `LYNX_NVS_AREA_ROOT_DEFINE` 绑定一个 flash partition，也可以用 `LYNX_NVS_AREA_SUB_REF_DEFINE` 在同一个 partition 内切出多个独立子区，避免把分区表拆得过碎。

NVS 采用 sector ring buffer：`active_sector_offset` 是写入 head，`tail_sector_offset` 是最老的回收候选，记录追加写入且不跨 sector。mount 只扫描/恢复状态，不主动写 sector header；进入空 sector 后，sector header 在第一次写记录前懒写入。Mesh config 已使用 NVS 子区作为后端，典型用法是同一个 ID 反复写入配置结构体，也可以在同一区域内用多个 ID 做 KV 存储。

GC 会先把 RAM index 中的最新有效记录 compact 到一个已擦除目标 sector，再按 Kconfig 策略擦除旧 tail sector，避免 full-area format 行为。当前策略包括：

| Kconfig | 行为 |
|---------|------|
| `CONFIG_LYNX_NVS_GC_ONE_SECTOR` | 每次 GC 最多擦除 1 个旧 sector |
| `CONFIG_LYNX_NVS_GC_TWO_SECTOR` | 每次 GC 最多擦除 2 个旧 sector |
| `CONFIG_LYNX_NVS_GC_HALF` | 每次 GC 最多擦除 area sector 数的一半 |
| `CONFIG_LYNX_NVS_GC_QUARD` | 每次 GC 最多擦除 area sector 数的四分之一 |

Host NVS 回归测试会在四种 GC 策略下运行同一套 simulated flash 用例。

## SoC 支持

| SoC | 架构 | 状态 |
|-----|------|------|
| TL321X | RISC-V D25F | 主力平台，完整支持 |
| TL322X | RISC-V | 支持 |
| TL721X | RISC-V | 支持 |
| B91 | RISC-V | 支持 |
| B92 | RISC-V | 支持 |

## 模块依赖关系

```
lynx_fi_app (应用固件)
  ├── lynx_lighting (静态库: light)
  │     ├── lynx_protocol/open_fi_proto (协议编解码)
  │     ├── FreeRTOS
  │     └── Telink SDK
  ├── lynx_dfx (静态库: dfx)
  │     ├── lynx_lighting
  │     ├── lynx_protocol/lynx_ci_proto
  │     └── lynx_protocol/open_fi_proto
  └── lynx_ci (CI桥接层)
        ├── lynx_wireless/stack/lynx_mesh (BLE Mesh栈)
        └── lynx_wireless/subsys (AT/EventBus/OSAL)

lynx_wireless (SDK框架)
  ├── stack/lynx_mesh (BLE Mesh协议栈)
  ├── drivers (UART/Counter/VUART)
  ├── subsys (AT/Event/EventBus/LFS/Log/OS/Storage/WorkQueue)
  ├── lib (buffer/ring_buf/pipeline/crypto)
  └── port/tl321x (SoC移植实现)

lynx_hal (HAL层 — Telink tl_ble_sdk)
```

## 关键编译选项

| 选项 | 说明 |
|------|------|
| `-fno-lto` | 禁用LTO，避免light_init等符号被消除 |
| `-fshort-wchar` | 16位wchar |
| `-ffunction-sections -fdata-sections` | 支持链接时优化 |
| `LYNX_LIGHTING_ENABLE` | 集成模式开关(ON=虚拟串口, OFF=物理UART) |
| `CONFIG_SOC_TL321X` | SoC选择 |

## 文档索引

| 文档 | 路径 |
|------|------|
| 灯光子系统 | [lynx_fi_app/lynx_lighting/README.md](lynx_fi_app/lynx_lighting/README.md) |
| DFX特效引擎 | [lynx_fi_app/lynx_dfx/README.md](lynx_fi_app/lynx_dfx/README.md) |
| 通信协议栈 | [lynx_fi_app/lynx_protocol/README.md](lynx_fi_app/lynx_protocol/README.md) |
| 框架架构设计 | [lynx_wireless/docs/lynx-fixture-architecture.md](lynx_wireless/docs/lynx-fixture-architecture.md) |
| 框架模块说明 | [lynx_wireless/docs/lynx-fixture-modules.md](lynx_wireless/docs/lynx-fixture-modules.md) |
| 构建系统 | [lynx_wireless/docs/lynx-fixture-build-system.md](lynx_wireless/docs/lynx-fixture-build-system.md) |
| BLE Bearer RF 分离设计 | [lynx_wireless/docs/ble-bearer-rf-split-design.md](lynx_wireless/docs/ble-bearer-rf-split-design.md) |
| VUART与灯光子系统 | [lynx_wireless/docs/vuart-and-light-subsys-guide.md](lynx_wireless/docs/vuart-and-light-subsys-guide.md) |
| S2 Sniffer 快速启动指南 | [docs/lynx-cli/Lynx Sniffer Quick Start Guide.zh-CN.md](docs/lynx-cli/Lynx%20Sniffer%20Quick%20Start%20Guide.zh-CN.md) |
| Storage Framework 设计 | [docs/Lynx Storage Framework.md](docs/Lynx%20Storage%20Framework.md) |
| NVS Storage Framework 设计 | [docs/Lynx NVS Storage Framework.md](docs/Lynx%20NVS%20Storage%20Framework.md) |
| NVS 测试示例 | [lynx_samples/nvs_test/](lynx_samples/nvs_test/) |
| 层职责设计 | [lynx_wireless/docs/layer-responsibility-design.md](lynx_wireless/docs/layer-responsibility-design.md) |

## License

Apache License 2.0 (Telink SDK 部分)

