NethubUserManual old：修订间差异

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


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


* [[Nethub用户手册#1. 系统架构|1. 系统架构]]
* [[#1. 系统架构|1. 系统架构]]
* [[Nethub用户手册#2. 快速开始|2. 快速开始]]
* [[#2. 快速开始|2. 快速开始]]
* [[Nethub用户手册#3. 开发指南|3. 开发指南]]
* [[#3. 开发指南|3. 开发指南]]
* [[Nethub用户手册#4. 常见问题|4. 常见问题]]
* [[#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 与守护进程通信
|-
|-
|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 数据流向 ===
===1.2 数据流向===
 
<syntaxhighlight lang="text">
<syntaxhighlight lang="text">
用户命令：
用户命令：
第53行： 第46行：
</syntaxhighlight>
</syntaxhighlight>


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


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


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


=== 2.1 编译和加载内核模块 ===
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
cd nethub/
# 编译命令形如
./build.sh build
make CHIP=<芯片名称> BOARD=<开发板名称>
sudo ./build.sh load
# 如果用的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>


# 或查看帮助
===2.2 Host 编译加载和测试===
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. 开发指南==


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


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


'''兼容性说明'''：
'''兼容性说明'''：
* ✅ 用户空间程序（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>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>connect_ap &#x3C;SSID&#x3E; [密码]</code>
| <code>scan</code> || 扫描附近 AP
|连接到 AP
|-
|-
|<code>disconnect</code>
| <code>connect_ap <SSID> [密码]</code> || 连接到 AP
|断开连接
|-
|-
|<code>status</code>
| <code>disconnect</code> || 断开连接
|查看连接状态
|-
|-
|<code>version</code>
| <code>status</code> || 查看连接状态
|查看固件版本
|-
| <code>version</code> || 查看固件版本
|}
|}


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


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


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


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


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


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


'''注意事项'''：
'''注意事项'''：
* 部分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
第190行： 第178行：
</syntaxhighlight>
</syntaxhighlight>


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


== 4. 常见问题 ==
===3.5 Virtual Channel 私有数据收发===
 
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">
# 查看可用串口
# 查看可用串口
第208行： 第290行：
</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
第221行： 第305行：
</syntaxhighlight>
</syntaxhighlight>


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


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

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

Nethub User Manual

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

目录

1. 系统架构

主机-设备架构图

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

1.1 组件说明

组件 类型 说明
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. 快速开始

NetHub SDIO 快速入门演示

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

2.1 device 的编译和烧录

# 编译命令形如
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

2.2 Host 编译加载和测试

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

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

3.5 Virtual Channel 私有数据收发

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

3.5.1 概述

Virtual Channel 支持三种数据类型：

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

3.5.2 设备端 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);

3.5.3 Host 端 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);

3.5.4 数据格式说明

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

+----------+-----------+-------+--------+
| 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[]：实际用户数据

3.5.5 完整示例

参考以下完整示例代码：

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

3.5.6 使用限制

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

3.5.7 运行 Virtual Channel 测试程序

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

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=228”