NethubUserManual old

Nethub User Manual

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

系统架构

主机-设备架构图

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

组件说明

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

数据流向

用户命令：
bflbwifictrl → bflbwifid → libbflbwifi → /dev/ttyAT → 内核驱动 → 设备

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

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

快速开始

NetHub SDIO 快速入门演示

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

设备端编译和烧录

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

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

主机端编译和测试

# 假设已经将 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"

开发指南

系统要求

• 内核版本：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 命令

命令	说明
build	编译内核模块、virtualchan 和 bflbwifictrl
clean	清理所有编译产物
load	加载内核模块 mr_sdio.ko
unload	卸载内核模块

bflbwifictrl 命令

命令	说明
scan	扫描附近 AP
connect_ap <SSID> [密码]	连接到 AP
disconnect	断开连接
status	查看连接状态
version	查看固件版本

功能特性

bflbwifid（守护进程）

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

bflbwifictrl（命令行工具）

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

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

当 WiFi 模块获取 IP 后，会自动：

1. 解析 URC：+CW:GOTIP,IP:xxx,gw:xxx,mask:xxx,dns:xxx
2. 配置网卡：ip addr add、ip route add default
3. 配置 DNS：写入 /etc/resolv.conf

注意事项：

• 部分host需要禁用 NetworkManager：sudo systemctl disable --now NetworkManager
• 需要禁用 dhcpcd：sudo systemctl disable --now dhcpcd
• 默认网卡名为 mr_eth0（可在代码中修改）

代码修改与编译

修改代码后重新编译

# 只编译 bflbwifictrl
cd bflbwifictrl
make clean && make

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

重新加载内核模块

sudo ./build.sh unload
sudo ./build.sh load

Virtual Channel 私有数据收发

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

概述

Virtual Channel 支持三种数据类型：

• USER (0x01)：用户私有数据（推荐用于用户自定义应用）
• AT (0x02)：AT 命令数据(todo)
• SYSTEM (0x03)：系统相关数据(todo)

设备端 API

参考文件：components/net/nethub/transport/sdio/sdio_virtualchan/virtualchan.h

核心 API：

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);

主机端 API

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

核心 API：

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);

数据格式说明

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

+----------+-----------+-------+--------+
| data_type| reserved  | len   | data[] |
| 1 byte   | 1 byte    | 2 bytes| N bytes|
+----------+-----------+-------+--------+

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

完整示例

参考以下完整示例代码：

• 设备端：examples/wifi/nethub/app/src/virtualchan/app_vchan.c
• 主机端：bsp/common/msg_router/linux_host/userspace/nethub/virtualchan/nethub_vchan_app.c

使用限制

项目	限制
最大数据长度	1500 字节（可配置）
传输方式	消息包传输（非流式）
通信方向	双向（设备 ↔ Host）

运行测试程序

# 编译（在 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                         # 查看帮助

常见问题

找不到串口设备

# 查看可用串口
ls /dev/ttyACM* /dev/ttyUSB*

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

IP 配置后自动消失

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

解决：

# 禁用 NetworkManager
sudo systemctl stop NetworkManager
sudo systemctl disable NetworkManager

# 禁用 dhcpcd
sudo systemctl stop dhcpcd
sudo systemctl disable dhcpcd

查看调试日志

# 查看守护进程日志
tail -f /var/log/bflbwifi.log

# 查看内核日志
dmesg -w

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

编译错误

# 确保安装必要的开发包
sudo apt-get install build-essential libc-dev-i386

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