NethubUserManual old：修订间差异

来自Bouffalo Lab Docs
跳转到导航 跳转到搜索
←上一编辑下一编辑→
可视化wikitext
张良​（留言 | 贡献）
105次编辑
无编辑摘要
张良​（留言 | 贡献）
105次编辑
撤销张良（讨论）的修订版本228
标签：撤销
第1行： 第1行：
=Nethub User Manual=
基于BL616C/BL618M/BL618DG/BL616CL 的 Linux 主机通信方案，提供内核模块和用户态控制工具。
基于BL616C/BL618M/BL618DG/BL616CL 的 Linux 主机通信方案，提供内核模块和用户态控制工具。


==目录==
== 目录 ==


* [[#1. 系统架构|1. 系统架构]]
* [[Nethub用户手册#1. 系统架构|1. 系统架构]]
* [[#2. 快速开始|2. 快速开始]]
* [[Nethub用户手册#2. 快速开始|2. 快速开始]]
* [[#3. 开发指南|3. 开发指南]]
* [[Nethub用户手册#3. 开发指南|3. 开发指南]]
* [[#4. 常见问题|4. 常见问题]]
* [[Nethub用户手册#4. 常见问题|4. 常见问题]]


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


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


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


===1.2 数据流向===
=== 1.2 数据流向 ===
 
<syntaxhighlight lang="text">
<syntaxhighlight lang="text">
用户命令：
用户命令：
第46行： 第53行：
</syntaxhighlight>
</syntaxhighlight>


==2. 快速开始==
== 2. 快速开始 ==
 
[[文件:Nethub_sdio_quickstart_demo.gif|center|thumb|NetHub SDIO 快速入门演示]]


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


===2.1 device 的编译和烧录===
[[文件:Nethub_sdio_quickstart_demo.gif]]


=== 2.1 编译和加载内核模块 ===
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# 编译命令形如
cd nethub/
make CHIP=<芯片名称> BOARD=<开发板名称>
./build.sh build
# 如果用的BL616
sudo ./build.sh load
make CHIP=bl616 BOARD=bl616dk
# 如果用的BL616cl
make CHIP=bl616cl BOARD=bl616cldk
# 如果用的BL618dg
make CHIP=bl618dg BOARD=bl618dgdk CPU_ID=ap
</syntaxhighlight>
</syntaxhighlight>


=== 2.2 运行 WiFi 守护进程 ===
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# 烧录命令形如
# 启动守护进程（默认使用 /dev/ttyAT0）
make flash CHIP=<芯片名称> COMX=<串口名称>
sudo ./output/bflbwifid -p /dev/ttyAT0
# 如果用的BL618dg
 
make flash CHIP=bl618dg COMX=/dev/ttyUSB0
# 或查看帮助
sudo ./output/bflbwifid -h
</syntaxhighlight>
</syntaxhighlight>


===2.2 Host 编译加载和测试===
=== 2.3 使用 WiFi 控制工具 ===
 
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# 假设已经将 bsp/common/msg_router/linux_host 复制到host，并在其目录下
# 扫描 AP
cd linux_host/userspace/nethub/
sudo ./output/bflbwifictrl scan


# 编译和加载内核模块
# 连接 AP（无密码）
./build.sh build
sudo ./output/bflbwifictrl connect_ap "SSID"
sudo ./build.sh load
 
# 启动守护进程（默认使用 /dev/ttyAT0）
sudo ./output/bflbwifid -p /dev/ttyAT0


# 连接 AP（有密码）
# 连接 AP（有密码）
sudo ./output/bflbwifictrl connect_ap "SSID" "password"
sudo ./output/bflbwifictrl connect_ap "SSID" "password"
# 查看状态
sudo ./output/bflbwifictrl status
# 断开连接
sudo ./output/bflbwifictrl disconnect
</syntaxhighlight>
</syntaxhighlight>


==3. 开发指南==
== 3. 开发指南 ==


===3.1 系统要求===
=== 3.1 系统要求 ===


* '''内核版本'''：Linux 3.7+（内核模块需要）
* '''内核版本'''：Linux 3.7+（内核模块需要）
第98行： 第102行：


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


===3.2 命令参考===
=== 3.2 命令参考 ===
 
====build.sh 命令====


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


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


===3.3 功能特性===
=== 3.3 功能特性 ===


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


* '''TTY 通信'''：与 WiFi 模块通过串口通信
* '''TTY 通信'''：与 WiFi 模块通过串口通信
第146行： 第158行：
* '''GOTIP 自动配置'''（可选）：收到 IP 后自动配置 Linux 网卡
* '''GOTIP 自动配置'''（可选）：收到 IP 后自动配置 Linux 网卡


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


* '''CLI 接口'''：通过 Unix Socket 与守护进程通信
* '''CLI 接口'''：通过 Unix Socket 与守护进程通信
第152行： 第164行：
* '''状态查询'''：实时显示连接信息
* '''状态查询'''：实时显示连接信息


====GOTIP 自动配置功能（默认启用）====
==== GOTIP 自动配置功能（默认启用） ====
当 WiFi 模块获取 IP 后，会自动：


当 WiFi 模块获取 IP 后，会自动：
# 解析 URC：<code>+CW:GOTIP,IP:xxx,gw:xxx,mask:xxx,dns:xxx</code>
# 解析 URC：<code>+CW:GOTIP,IP:xxx,gw:xxx,mask:xxx,dns:xxx</code>
# 配置网卡：<code>ip addr add</code>、<code>ip route add default</code>
# 配置网卡：<code>ip addr add</code>、<code>ip route add default</code>
第160行： 第172行：


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


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


==== 修改代码后重新编译 ====
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# 只编译 bflbwifictrl
# 只编译 bflbwifictrl
第178行： 第190行：
</syntaxhighlight>
</syntaxhighlight>


====重新加载内核模块====
==== 重新加载内核模块 ====
 
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
sudo ./build.sh unload
sudo ./build.sh unload
第185行： 第196行：
</syntaxhighlight>
</syntaxhighlight>


===3.5 Virtual Channel 私有数据收发===
== 4. 常见问题 ==
 
Virtual Channel 提供了一套独立于 AT 命令的私有数据传输通道，可用于用户自定义应用数据的双向传输。
 
====3.5.1 概述====
 
Virtual Channel 支持三种数据类型：
* '''USER (0x01)'''：用户私有数据（推荐用于用户自定义应用）
* '''AT (0x02)'''：AT 命令数据(todo)
* '''SYSTEM (0x03)'''：系统相关数据(todo)
 
====3.5.2 设备端 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>
 
====3.5.3 Host 端 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>
 
====3.5.4 数据格式说明====
 
'''消息帧格式'''（自动处理，用户无需关心）：
 
<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[]'''：实际用户数据
 
====3.5.5 完整示例====
 
参考以下完整示例代码：
* '''设备端'''：<code>examples/wifi/nethub/app/src/virtualchan/app_vchan.c</code>
* '''Host 端'''：<code>bsp/common/msg_router/linux_host/userspace/nethub/virtualchan/nethub_vchan_app.c</code>
 
====3.5.6 使用限制====
 
{| class="wikitable"
|-
! 项目 !! 限制
|-
| 最大数据长度 || 1500 字节（可配置）
|-
| 传输方式 || 消息包传输（非流式）
|-
| 通信方向 || 双向（设备 ↔ Host）
|}
 
====3.5.7 运行 Virtual Channel 测试程序====
 
<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>
 
==4. 常见问题==
 
===4.1 找不到串口设备===


=== 4.1 找不到串口设备 ===
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# 查看可用串口
# 查看可用串口
第290行： 第208行：
</syntaxhighlight>
</syntaxhighlight>


===4.2 IP 配置后自动消失===
=== 4.2 IP 配置后自动消失 ===
 
'''原因'''：NetworkManager 或 dhcpcd 覆盖了手动配置。
'''原因'''：NetworkManager 或 dhcpcd 覆盖了手动配置。


'''解决'''：
'''解决'''：<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# 禁用 NetworkManager
# 禁用 NetworkManager
sudo systemctl stop NetworkManager
sudo systemctl stop NetworkManager
第305行： 第221行：
</syntaxhighlight>
</syntaxhighlight>


===4.3 查看调试日志===
=== 4.3 查看调试日志 ===
 
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# 查看守护进程日志
# 查看守护进程日志
第318行： 第233行：
</syntaxhighlight>
</syntaxhighlight>


===4.4 编译错误===
=== 4.4 编译错误 ===
 
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# 确保安装必要的开发包
# 确保安装必要的开发包

2026年3月3日 (二) 03:13的版本

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

目录

1. 系统架构

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

1.1 组件说明

相关代码参考 bsp/common/msg_router/linux_host

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

1.2 数据流向

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

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

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

2. 快速开始

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

2.1 编译和加载内核模块

cd nethub/
./build.sh build
sudo ./build.sh load

2.2 运行 WiFi 守护进程

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

# 或查看帮助
sudo ./output/bflbwifid -h

2.3 使用 WiFi 控制工具

# 扫描 AP
sudo ./output/bflbwifictrl scan

# 连接 AP（无密码）
sudo ./output/bflbwifictrl connect_ap "SSID"

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

# 查看状态
sudo ./output/bflbwifictrl status

# 断开连接
sudo ./output/bflbwifictrl disconnect

3. 开发指南

3.1 系统要求

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

3.2 命令参考

build.sh 命令

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

bflbwifictrl 命令

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

3.3 功能特性

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（可在代码中修改）

3.4 代码修改与编译

修改代码后重新编译

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

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

重新加载内核模块

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

4. 常见问题

4.1 找不到串口设备

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

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

4.2 IP 配置后自动消失

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

解决：

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

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

4.3 查看调试日志

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

# 查看内核日志
dmesg -w

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

4.4 编译错误

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

# 树莓派需要安装 32 位兼容库
sudo apt-get install libc6:i386 libstdc++6:i386
检索自“https://docs.bouffalolab.com/index.php?title=NethubUserManual_old&oldid=229”