ddb65536/simplemesh-global

SimpleMesh 全局框架（Global）

最重要约束

接到修改/新增需求时，先判断是否与 doc/0_architecture.md 及本 skill 的模块划分一致；若有偏离，先简要说明架构上的影响，再确认是否按该方式实现。

实现目的（必须遵守）

1. Controller 模式：只做策略 + MQTT 收发。不直接连 hostapd、不连 system_monitor/backhaul；不持有 WiFi/系统/回传的底层数据源。输入输出均为 MQTT。
2. Agent 模式：负责本机状态采集 + 状态机 + MQTT。数据源：ubus+hostapd（WiFi）、system_monitor（系统）、backhaul（回传）。状态机：init → connecting → connected → online。具体约束见 Agent skill。
3. Controller 设备：可同时运行 controller 与 agent（同进程双角色）；agent 仅负责本机上报与状态。
4. Agent 设备：只运行 agent 模式；不实现 controller 逻辑。
5. I/O 多路复用：使用 libubox (uloop)，不得使用 libuv。MQTT、Unix socket、定时器均通过 uloop 接入。
6. MQTT 主题与报文：以 doc/1_mqtt_topic.md 为准（ap/topology_query、ap/topology_report、HEARTBEAT 等）。

入口与配置

• 入口：src/main_uloop.c。解析 -m controller|agent|both、-b、-p；启动 uloop；可选同时跑 controller + agent。
• 配置：broker/port 未传 -b/-p 时从 UCI /etc/config/simplemesh 的 simplemesh.global 读取（mqtt_broker、mqtt_port）。mode（controller/agent/both）仅从 UCI simplemesh.global.mode 读取，用于 both 模式判断（见 Agent skill）。

Both 模式（UCI）

• both 模式：表示 controller 设备双模式；Agent 将 backhaul 视为已连，不依赖实际回传。判断方式：UCI simplemesh.global.mode='both'；由 config_load_simplemesh() 填充 struct simplemesh_uci_config.mode，Agent 在 init 时据此设 is_both_mode。不得在 agent 内依赖命令行 -m both 做 backhaul 逻辑。

文件/模块映射（概览）

| 职责 | 路径 | |------------|------| | 入口、-m | src/main_uloop.c | | Agent 状态机 | src/agent_sm.c、agent_sm.h → 见 Agent skill | | Controller | src/controller.c、controller.h → 见 Controller skill | | 硬件/系统通用 | src/platform/system_api.c、system_api.h：设备 MAC、接口等通用参数；init_device_info 供 Controller 与 Agent 共用；新增硬件或系统级读取统一放此处。 | | UCI 配置 | src/platform/config_uci.c、config_uci.h（global：broker、port、mode；wifi；backhaul） | | MQTT/报文 | src/transport/mqtt_client.c、mesh_mqtt.c、mqtt_topics.h | | 周期任务 | src/main_task.c、main_task.h（controller/agent 共用） | | 日志 | src/log_simple.c、log_simple.h |

修改/新增时的约束（通用）

• 定时/重连：使用 uloop_timeout 或 main_task，不用 libuv timer。
• Socket 事件：使用 uloop_fd_add，不用 libuv poll。
• MQTT 主题：在 transport/mqtt_topics.h 或 doc/1_mqtt_topic.md 中定义；实现与文档一致。
• 角色边界：Controller 逻辑不加 hostapd/system_monitor/backhaul；Agent 逻辑按状态机与数据源放置，见各自 skill。
• 硬件/系统通用：获取设备 MAC、接口信息等硬件或系统通用参数统一放在 platform/system_api.c，通过 init_device_info 等接口供 Controller/Agent 共用；不把“读网卡 MAC”等通用逻辑放在 backhaul（backhaul 只做回传连接状态、STA 等）。

参考

• doc/0_architecture.md
• doc/1_mqtt_topic.md
• Agent 专用：.cursor/skills/simplemesh/agent/SKILL.md
• Controller 专用：.cursor/skills/simplemesh/controller/SKILL.md