NethubUserManual old：修订间差异

来自Bouffalo Lab Docs
跳转到导航 跳转到搜索
←上一编辑
可视化wikitext
张良​（留言 | 贡献）
105次编辑
撤销张良（讨论）的修订版本228
标签：撤销
张良​（留言 | 贡献）
105次编辑
小 张良移动页面NethubUserManual至NethubUserManual old
 
（未显示同一用户的2个中间版本）
第1行： 第1行：
=Nethub User Manual=
基于BL616C/BL618M/BL618DG/BL616CL 的 Linux 主机通信方案，提供内核模块和用户态控制工具。
基于BL616C/BL618M/BL618DG/BL616CL 的 Linux 主机通信方案，提供内核模块和用户态控制工具。


== 目录 ==
==系统架构==


* [[Nethub用户手册#1. 系统架构|1. 系统架构]]
[[文件:Arch_host_device.png|800px|center|thumb|主机-设备架构图]]
* [[Nethub用户手册#2. 快速开始|2. 快速开始]]
* [[Nethub用户手册#3. 开发指南|3. 开发指南]]
* [[Nethub用户手册#4. 常见问题|4. 常见问题]]


== 1. 系统架构 ==
'''说明'''：当前控制通道通过 tty 传输，后续将支持通过 VirtualChannel 传输 AT 命令。
[[文件:Arch_host_device.png|800px]]


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


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


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


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


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


[[文件:Nethub_sdio_quickstart_demo.gif]]
===设备端编译和烧录===


=== 2.1 编译和加载内核模块 ===
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
cd nethub/
cd examples/wifi/nethub
./build.sh build
 
sudo ./build.sh load
# 编译命令形如
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>


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


# 或查看帮助
===主机端编译和测试===
sudo ./output/bflbwifid -h
</syntaxhighlight>


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


# 连接 AP（无密码）
# 编译和加载内核模块
sudo ./output/bflbwifictrl connect_ap "SSID"
./build.sh build
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.1 系统要求 ===
===系统要求===


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


'''兼容性说明'''：
'''兼容性说明'''：
* ✅ 用户空间程序（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 命令参考 ===
===命令参考===
 
====build.sh 命令====


==== build.sh 命令 ====
{| class="wikitable"
{| class="wikitable"
!命令
!说明
|-
|-
|<code>build</code>
! 命令 !! 说明
|编译内核模块、virtualchan 和 bflbwifictrl
|-
|-
|<code>clean</code>
| <code>build</code> || 编译内核模块、virtualchan 和 bflbwifictrl
|清理所有编译产物
|-
|-
|<code>load</code>
| <code>clean</code> || 清理所有编译产物
|加载内核模块 <code>mr_sdio.ko</code>
|-
|-
|<code>unload</code>
| <code>load</code> || 加载内核模块 <code>mr_sdio.ko</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>
| <code>connect_ap <SSID> [密码]</code> || 连接到 AP
|连接到 AP
|-
|-
|<code>disconnect</code>
| <code>disconnect</code> || 断开连接
|断开连接
|-
|-
|<code>status</code>
| <code>status</code> || 查看连接状态
|查看连接状态
|-
|-
|<code>version</code>
| <code>version</code> || 查看固件版本
|查看固件版本
|}
|}


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


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


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


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


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


==== 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>
第172行： 第155行：


'''注意事项'''：
'''注意事项'''：
* 部分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 代码修改与编译 ===
===代码修改与编译===
 
====修改代码后重新编译====


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


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


== 4. 常见问题 ==
===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>
 
==常见问题==
 
===找不到串口设备===


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


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


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


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


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

2026年3月13日 (五) 09:26的最新版本

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 快速入门演示
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
检索自“https://docs.bouffalolab.com/index.php?title=NethubUserManual_old&oldid=237”