NetHubArchitecture

NetHub 架构说明

本文档面向需要理解模块边界和 API 的开发者。

1. 当前架构结论

• 当前物理主路径是 SDIO
• USB / SPI 目前仍保留 backend 骨架，不作为当前推荐 bringup 路径
• device 侧 Wi-Fi backend 支持 fhost / wl80211
• 控制通道和 USER virtual channel 都是当前 host link 上的逻辑通道，不是独立物理接口
• host 控制 backend 运行时二选一：tty 或 vchan

2. 功能视角架构图

Host
  |
  | network data / control payload / USER payload
  v
Host Link (current main path: SDIO)
  |
  +-- Data Channel   <--> nethub data bridge
  +-- Control Channel <-> nethub ctrlpath <-> ATModule
  +-- USER VCHAN      <-> nethub vchan user path
  |
  v
Device
  |
  +-- nethub
  |    +-- data bridge
  |    +-- hard-coded Wi-Fi RX filter
  |    +-- active Wi-Fi selector (STA / AP)
  |    +-- ctrlpath
  |    +-- virtual channel
  |
  +-- Wi-Fi backend (fhost / wl80211) + lwIP

从功能上看，nethub 主要做 4 件事：

• 维护 Wi-Fi <-> HostLink 的数据桥接
• 用硬编码 filter 决定报文是 local、host、还是 both
• 维护当前生效的 Wi-Fi 通道选择 STA / AP
• 在同一 host link 上提供控制通道和可选的 USER virtual channel

3. 技术/API 视角架构图

Application
  |
  +-- device public API
  |    +-- nethub.h
  |    +-- nethub_vchan.h
  |    +-- nethub_filter.h
  |
  +-- host public API
       +-- bflbwifi.h
       +-- virtualchan/nethub_vchan.h

device side
  nethub_bootstrap()
    -> profile select
    -> endpoint register
    -> hub lifecycle
    -> Wi-Fi bridge
    -> host backend (current main path: sdio)

host side
  bflbwifictrl
    -> IPC
    -> bflbwifid
    -> libbflbwifi
    -> channel facade
       +-- tty backend
       +-- vchan backend
    -> mr_sdio.ko + msg_router

4. Device 侧公共接口

头文件：

• components/net/nethub/include/nethub.h
• components/net/nethub/include/nethub_vchan.h
• components/net/nethub/include/nethub_filter.h

核心 API：

• nethub_bootstrap()
• nethub_shutdown()
• nethub_get_status()
• nethub_set_active_wifi_channel()
• nethub_ctrl_upld_send()
• nethub_ctrl_dnld_register()
• nethub_vchan_user_send()
• nethub_vchan_user_recv_register()
• nethub_set_wifi_rx_filter()

边界说明：

• nethub_ctrl_* 对应 host link 上的逻辑控制通道
• nethub_vchan_user_* 对应 host link 上的逻辑 USER 通道
• nethub_set_wifi_rx_filter() 用于完全替换内建 Wi-Fi RX filter，必须在 nethub_bootstrap() 前调用

5. Host 侧公共接口

头文件：

• bsp/common/msg_router/linux_host/userspace/nethub/bflbwifictrl/include/bflbwifi.h
• bsp/common/msg_router/linux_host/userspace/nethub/virtualchan/nethub_vchan.h

控制面能力：

• bflbwifi_ctrl_config_init()
• bflbwifi_ctrl_config_use_tty()
• bflbwifi_ctrl_config_use_vchan()
• bflbwifi_init_ex()
• bflbwifi_get_ctrl_status()
• bflbwifi_sta_connect()
• bflbwifi_sta_disconnect()
• bflbwifi_sta_get_state()
• bflbwifi_scan()
• bflbwifi_get_version()
• bflbwifi_restart()
• bflbwifi_ota_upgrade()
• bflbwifi_ap_start()
• bflbwifi_ap_stop()

USER virtual channel 能力：

• nethub_vchan_init()
• nethub_vchan_deinit()
• nethub_vchan_user_send()
• nethub_vchan_user_register_callback()
• nethub_vchan_get_state_snapshot()
• nethub_vchan_register_link_event_callback()

6. 关键数据流

6.1 connect_ap

1. 用户执行 bflbwifictrl connect_ap <ssid> <password>
2. CLI 通过本地 IPC 把命令发给 bflbwifid
3. daemon 调用 libbflbwifi
4. libbflbwifi 通过 tty 或 vchan backend 下发控制消息
5. device 侧 ATModule 执行 Wi-Fi 控制
6. device 侧上报响应和状态，host 侧刷新状态并返回结果

6.2 数据面

1. host 网络流量进入 mr_eth0
2. kernel/msg_router 通过 SDIO 与 device 通信
3. device 侧 nethub 把 host data 转给当前 active Wi-Fi
4. Wi-Fi RX 包经过 nethub filter 判断后，决定是本地处理、发给 host，还是两边都处理

7. 推荐阅读顺序

• 首次 bringup：NetHub 快速上手
• 理解 USER 通道：NetHub USER Virtual Channel