查看“︁NethubUserManual old”︁的源代码

=Nethub User Manual=

基于BL616C/BL618M/BL618DG/BL616CL 的 Linux 主机通信方案，提供内核模块和用户态控制工具。

==系统架构==

[[文件:Arch_host_device.png|800px|center|thumb|主机-设备架构图]]

'''说明'''：当前控制通道通过 tty 传输，后续将支持通过 VirtualChannel 传输 AT 命令。

===组件说明===

{| class="wikitable"
|-
! 组件 !! 类型 !! 说明
|-
| bflbwifictrl || 用户态 || 命令行工具，通过 Unix Socket 与守护进程通信
|-
| bflbwifid || 用户态 || 守护进程，负责设备通信和 WiFi 连接管理
|-
| libbflbwifi || 用户态 || 静态库，提供 WiFi 控制 API
|-
| nethub_vchan_app || 用户态 || VirtualChannel 通信程序，提供私有数据通道（消息包传输，非流式）
|-
| mr_sdio.ko || 内核态 || 内核驱动模块，支持 SDIO 接口
|}

===数据流向===

<syntaxhighlight lang="text">
用户命令：
bflbwifictrl → bflbwifid → libbflbwifi → /dev/ttyAT → 内核驱动 → 设备

URC事件：
设备 → 内核驱动 → /dev/ttyAT → bflbwifid → 解析处理 → 网卡配置

工作流程：
加载内核模块 → 启动守护进程 → TTY 通信建立 → 准备就绪
</syntaxhighlight>

==快速开始==

[[文件:Nethub_sdio_quickstart_demo.gif|center|NetHub SDIO 快速入门演示]]

本演示展示了完整的操作流程：编译 → 加载内核模块 → 启动守护进程 → WiFi 连接 → 网络通信 → 消息收发。

===设备端编译和烧录===

<syntaxhighlight lang="bash">
cd examples/wifi/nethub

# 编译命令形如
make CHIP=<芯片名称> BOARD=<开发板名称>
# 如果用的BL616
make CHIP=bl616 BOARD=bl616dk
# 如果用的BL616cl
make CHIP=bl616cl BOARD=bl616cldk
# 如果用的BL618dg
make CHIP=bl618dg BOARD=bl618dgdk CPU_ID=ap
</syntaxhighlight>

<syntaxhighlight lang="bash">
# 烧录命令形如
make flash CHIP=<芯片名称> COMX=<串口名称>
# 如果用的BL618dg
make flash CHIP=bl618dg COMX=/dev/ttyUSB0
</syntaxhighlight>

===主机端编译和测试===

<syntaxhighlight lang="bash">
# 假设已经将 bsp/common/msg_router/linux_host 复制到host，并在其目录下
cd linux_host/userspace/nethub/

# 编译和加载内核模块
./build.sh build
sudo ./build.sh load

# 启动守护进程（默认使用 /dev/ttyAT0）
sudo ./output/bflbwifid -p /dev/ttyAT0

# 连接 AP（有密码）
sudo ./output/bflbwifictrl connect_ap "SSID" "password"
</syntaxhighlight>

==开发指南==

===系统要求===

* '''内核版本'''：Linux 3.7+（内核模块需要）
* '''架构'''：x86_64、ARMv7（树莓派）、ARMv8（树莓派 4/5）
* '''依赖'''：gcc、make、libc、pthread

'''兼容性说明'''：
* ✅ 用户空间程序（bflbwifid/bflbwifictrl）：无内核版本限制
* ✅ 内核模块（mr_sdio.ko）：支持 Linux 3.7+
* ✅ 已测试：Linux raspberrypi 6.12.25+rpt-rpi-v8

===命令参考===

====build.sh 命令====

{| class="wikitable"
|-
! 命令 !! 说明
|-
| <code>build</code> || 编译内核模块、virtualchan 和 bflbwifictrl
|-
| <code>clean</code> || 清理所有编译产物
|-
| <code>load</code> || 加载内核模块 <code>mr_sdio.ko</code>
|-
| <code>unload</code> || 卸载内核模块
|}

====bflbwifictrl 命令====

{| class="wikitable"
|-
! 命令 !! 说明
|-
| <code>scan</code> || 扫描附近 AP
|-
| <code>connect_ap <SSID> [密码]</code> || 连接到 AP
|-
| <code>disconnect</code> || 断开连接
|-
| <code>status</code> || 查看连接状态
|-
| <code>version</code> || 查看固件版本
|}

===功能特性===

====bflbwifid（守护进程）====

* '''TTY 通信'''：与 WiFi 模块通过串口通信
* '''AT 协议'''：解析和封装 AT 指令
* '''状态管理'''：维护 WiFi 连接状态
* '''Unix Socket'''：提供 IPC 通信接口
* '''GOTIP 自动配置'''（可选）：收到 IP 后自动配置 Linux 网卡

====bflbwifictrl（命令行工具）====

* '''CLI 接口'''：通过 Unix Socket 与守护进程通信
* '''简洁易用'''：提供常用 WiFi 操作命令
* '''状态查询'''：实时显示连接信息

====GOTIP 自动配置功能（默认启用）====

当 WiFi 模块获取 IP 后，会自动：
# 解析 URC：<code>+CW:GOTIP,IP:xxx,gw:xxx,mask:xxx,dns:xxx</code>
# 配置网卡：<code>ip addr add</code>、<code>ip route add default</code>
# 配置 DNS：写入 <code>/etc/resolv.conf</code>

'''注意事项'''：
* 部分host需要禁用 NetworkManager：<code>sudo systemctl disable --now NetworkManager</code>
* 需要禁用 dhcpcd：<code>sudo systemctl disable --now dhcpcd</code>
* 默认网卡名为 <code>mr_eth0</code>（可在代码中修改）

===代码修改与编译===

====修改代码后重新编译====

<syntaxhighlight lang="bash">
# 只编译 bflbwifictrl
cd bflbwifictrl
make clean && make

# 或使用 build.sh 编译所有
cd ..
./build.sh build
</syntaxhighlight>

====重新加载内核模块====

<syntaxhighlight lang="bash">
sudo ./build.sh unload
sudo ./build.sh load
</syntaxhighlight>

===Virtual Channel 私有数据收发===

Virtual Channel 提供了一套独立于 AT 命令的私有数据传输通道，可用于用户自定义应用数据的双向传输。

====概述====

Virtual Channel 支持三种数据类型：
* '''USER (0x01)'''：用户私有数据（推荐用于用户自定义应用）
* '''AT (0x02)'''：AT 命令数据(todo)
* '''SYSTEM (0x03)'''：系统相关数据(todo)

====设备端 API====

'''参考文件'''：<code>components/net/nethub/transport/sdio/sdio_virtualchan/virtualchan.h</code>

'''核心 API'''：

<syntaxhighlight lang="c">
int nethub_vchan_user_send(const void *data, uint16_t len);
int nethub_vchan_user_recv_register(virtualchan_dnld_cb_t dnld_cb, void *cb_arg);
typedef int (*virtualchan_dnld_cb_t)(void *arg, uint8_t *data_buff, uint16_t data_size);
</syntaxhighlight>

====主机端 API====

'''参考文件'''：<code>bsp/common/msg_router/linux_host/userspace/nethub/virtualchan/nethub_vchan.h</code>

'''核心 API'''：

<syntaxhighlight lang="c">
int nethub_vchan_init(void);
int nethub_vchan_user_send(const void *data, size_t len);
int nethub_vchan_user_register_callback(nethub_vchan_recv_callback_t callback);

/* 回调函数类型定义 */
typedef void (*nethub_vchan_recv_callback_t)(const void *data, size_t len);
</syntaxhighlight>

====数据格式说明====

'''消息帧格式'''（自动处理，用户无需关心）：

<pre>
+----------+-----------+-------+--------+
| data_type| reserved  | len   | data[] |
| 1 byte   | 1 byte    | 2 bytes| N bytes|
+----------+-----------+-------+--------+
</pre>

* '''data_type'''：数据类型（USER=0x01, AT=0x02, SYSTEM=0x03）
* '''reserved'''：保留字段（固定为 0）
* '''len'''：用户数据长度
* '''data[]'''：实际用户数据

====完整示例====

参考以下完整示例代码：
* '''设备端'''：<code>examples/wifi/nethub/app/src/virtualchan/app_vchan.c</code>
* '''主机端'''：<code>bsp/common/msg_router/linux_host/userspace/nethub/virtualchan/nethub_vchan_app.c</code>

====使用限制====

{| class="wikitable"
|-
! 项目 !! 限制
|-
| 最大数据长度 || 1500 字节（可配置）
|-
| 传输方式 || 消息包传输（非流式）
|-
| 通信方向 || 双向（设备 ↔ Host）
|}

====运行测试程序====

<syntaxhighlight lang="bash">
# 编译（在 nethub 目录下）
cd virtualchan
make

# 运行测试程序
sudo ./nethub_vchan_app

# 在程序中使用命令
nethub_vchan> send user hello              # 发送 ASCII 字符串
nethub_vchan> send user hex 0102030405     # 发送十六进制数据
nethub_vchan> test flow 100 512            # 流量测试（100个包，每包512字节）
nethub_vchan> test mtu 1024                # MTU测试（发送1024字节）
nethub_vchan> status                       # 查看统计信息
nethub_vchan> help                         # 查看帮助
</syntaxhighlight>

==常见问题==

===找不到串口设备===

<syntaxhighlight lang="bash">
# 查看可用串口
ls /dev/ttyACM* /dev/ttyUSB*

# 添加用户到 dialout 组（避免每次都用 sudo）
sudo usermod -aG dialout $USER
# 然后重新登录
</syntaxhighlight>

===IP 配置后自动消失===

'''原因'''：NetworkManager 或 dhcpcd 覆盖了手动配置。

'''解决'''：
<syntaxhighlight lang="bash">
# 禁用 NetworkManager
sudo systemctl stop NetworkManager
sudo systemctl disable NetworkManager

# 禁用 dhcpcd
sudo systemctl stop dhcpcd
sudo systemctl disable dhcpcd
</syntaxhighlight>

===查看调试日志===

<syntaxhighlight lang="bash">
# 查看守护进程日志
tail -f /var/log/bflbwifi.log

# 查看内核日志
dmesg -w

# 守护进程前台运行（查看实时输出）
sudo ./output/bflbwifid -p /dev/ttyAT0 --foreground
</syntaxhighlight>

===编译错误===

<syntaxhighlight lang="bash">
# 确保安装必要的开发包
sudo apt-get install build-essential libc-dev-i386

# 树莓派需要安装 32 位兼容库
sudo apt-get install libc6:i386 libstdc++6:i386
</syntaxhighlight>