Bouffalo Lab Docs - 用户贡献 [zh-cn]

DebuggingBouffaloLabChipsWithGDB

2026-04-10T01:05:38Z

张良：

= 通过CKLink调试DVK light开发板 =

==== 通过USB连接到PC ====

[[文件:BL616DVK Light CKLinkLite.jpg| 600像素 | BL616DVKLight_CKLinkLite]]

==== 进行GDB调试 ====

这里以Ubuntu为例，分别运行如下两条命令

<code>DebugServerConsole</code>

<code>riscv64-unknown-elf-gdb *.elf</code>

[[文件:BL616DVKLight_CKLinkLite.gif| BL616DVKLight_CKLinkLite]]

首页

2026-04-09T07:06:24Z

张良：

= Getting Started =

* [https://github.com/bouffalolab/bouffalo_sdk 如何获取SDK]
* [[如何在Ubuntu上搭建编译环境]]
* [[如何在Windows上搭建编译环境]]
* [[如何获取开发板]]
* [[烧录固件到开发板]]
* [[DebuggingBouffaloLabChipsWithGDB|如何调试博流开发板]]

= Bouffalo SDK =
'''BouffaloSDK''' 是 Bouffalo Lab 提供的 IOT 和 MCU 软件开发包，支持博流智能所有系列芯片，也是 '''bl_mcu_sdk''' 和 '''bl_iot_sdk''' 的结合体。

[[文件:BouffaloSDK.png|无框|600x600像素]]

= Peripherals =

{| border="0" cellpadding="10" width="100%"
|-
|width="32%" valign="top" align="left"|
*[[I2S]]
*[[I2C]]
*[[CVBS]]
*[[Watchdog]]
*[[GSM/GPRS]]
*[[Codec]]
*[[PCIe]]
*[[GPIO]]
*[[eMMC]]
|width="32%" valign="top" align="left"|
*[[WiFi]]
*[[LED]]
*[[Serial port]]
*[[PWM]]
*[[SPI]]
*[[USB OTG]]
*[[LCD]]
*[[CPU]]
*[[Network]]
|width="32%" valign="top" align="left"|
*[[Bluetooth]]
*[[HDMI]]
*[[Camera]]
*[[Memory]]
*[[RTC]]
*[[EEPROM]]
*[[MIPI-DSI]]
*[[NPU]]
*[[VPU]]
|}

= Products =
{| border="0" cellpadding="10" width="100%"
|-
|width="50%" valign="top" align="left"|
* [[BL602]]
* [[BL702]]
* [[BL618]]
* [[BL606P]]
|width="50%" valign="top" align="left"|
* [[BL702L]]
* [[BL616]]
|}

= Develop Boards =
* BL602EVB

= Application Notes =
* [[NetHub]]
* [[BL616低功耗开发手册]]
* [[USB Wi-Fi用户手册]]

= Demos =

{| border="0" cellpadding="10" width="100%"
|-
|width="32%" valign="top" align="left"|
*[[Demo:FreeRTOS]]
* [[Demo:wifi sta]]
* [[Demo:boot2_isp]]
* [[Demo:helloworld]]
* [[Demo:smartconfig ble]]
|width="32%" valign="top" align="left"|
*[[Demo:DMA]]
* [[Demo:Btble]]
* [[Demo:coremark]]
* [[Demo:littlefs]]
* [[Demo:posix freertos]]
|width="32%" valign="top" align="left"|
*[[Demo:Flash]]
* [[Demo:Basical case]]
* [[Demo:dsp]]
* [[Demo:cks]]
|}

使用GDB调试

2026-04-09T07:05:28Z

张良：张良移动页面使用GDB调试至DebuggingBouffaloLabChipsWithGDB

#重定向 [[DebuggingBouffaloLabChipsWithGDB]]

DebuggingBouffaloLabChipsWithGDB

2026-04-09T07:05:28Z

张良：张良移动页面使用GDB调试至DebuggingBouffaloLabChipsWithGDB

= 通过CKLink调试DVK light开发板 =

==== 通过USB连接到PC ====

[[文件:BL616DVK Light CKLinkLite.jpg| 600像素 | BL616DVKLight_CKLinkLite]]

==== 进行GDB调试 ====

这里以Ubuntu为例，此时应该可以看到 <code>/dev/ttyACM0</code> 设备（以实际为准）

分别运行如下两条命令

<code>DebugServerConsole</code>

<code>riscv64-unknown-elf-gdb *.elf</code>

[[文件:BL616DVKLight_CKLinkLite.gif| BL616DVKLight_CKLinkLite]]

DebuggingBouffaloLabChipsWithGDB

2026-04-09T07:03:23Z

张良：/* 进行GDB调试 */

DebuggingBouffaloLabChipsWithGDB

2026-04-09T07:02:34Z

张良：

= 通过CKLink调试DVK light开发板 =

==== 通过USB连接到PC ====

[[文件:BL616DVK Light CKLinkLite.jpg| 600像素 | BL616DVKLight_CKLinkLite]]

==== 进行GDB调试 ====

这里以Ubuntu为例，此时应该可以看到 <code>/dev/ttyACM0</code> 设备（以实际为准）
分别运行如下两条命令
<code>DebugServerConsole</code>
<code>riscv64-unknown-elf-gdb *.elf</code>

[[文件:BL616DVKLight_CKLinkLite.gif| BL616DVKLight_CKLinkLite]]

文件:BL616DVK Light CKLinkLite.jpg

2026-04-09T07:00:05Z

张良：BL616DVKLight_CKLinkLite.jpg

== 摘要 ==
BL616DVKLight_CKLinkLite.jpg

DebuggingBouffaloLabChipsWithGDB

2026-04-09T06:58:21Z

张良：

= 通过CKLink调试DVK light开发板 =

==== 通过USB连接到PC ====

[[文件:BL616DVK Light_CKLinkLite.jpg | BL616DVK Light_CKLinkLite]]

==== 进行GDB调试 ====

这里以Ubuntu为例，此时应该可以看到 <code>/dev/ttyACM0</code> 设备（以实际为准）
分别运行如下两条命令
<code>DebugServerConsole</code>
<code>riscv64-unknown-elf-gdb *.elf</code>

[[文件:BL616DVKLight_CKLinkLite.gif| BL616DVKLight_CKLinkLite]]

文件:BL616DVKLight CKLinkLite.gif

2026-04-09T06:57:24Z

张良：BL616DVKLight_CKLinkLite.gif

== 摘要 ==
BL616DVKLight_CKLinkLite.gif

DebuggingBouffaloLabChipsWithGDB

2026-04-09T06:55:42Z

张良：

文件:BL616DVK Light CKLinkLite.jpg.jpg

2026-04-09T06:54:55Z

张良：

BL616DVK Light_CKLinkLite.jpg

DebuggingBouffaloLabChipsWithGDB

2026-04-09T06:49:53Z

张良：创建页面，内容为“ 通过CKLink调试DVK light开发板”

通过CKLink调试DVK light开发板

Windows wsl bringup

2026-04-09T02:22:22Z

张良：

== 1. Build and Flash the Device Firmware ==

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

cd examples/wifi/nethub

''# BL616''
make CHIP=bl616 BOARD=bl616dk

''# BL616CL''
make CHIP=bl616cl BOARD=bl616cldk

''# BL618DG''
make CHIP=bl618dg BOARD=bl618dgdk CPU_ID=ap
Flash example:
cd examples/wifi/nethub
make flash CHIP=bl618dg COMX=/dev/ttyUSB0

make flash CHIP=bl616cl COMX=/dev/ttyUSB0

make flash CHIP=bl616cl COMX=COM5

export PATH=$HOME/work/toolchain_riscv_thead_linux64/bin:$PATH

Windows wsl bringup

2026-04-08T03:49:13Z

张良：/* 1. Build and Flash the Device Firmware */

== 1. Build and Flash the Device Firmware ==

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

cd examples/wifi/nethub

''# BL616''
make CHIP=bl616 BOARD=bl616dk

''# BL616CL''
make CHIP=bl616cl BOARD=bl616cldk

''# BL618DG''
make CHIP=bl618dg BOARD=bl618dgdk CPU_ID=ap
Flash example:
cd examples/wifi/nethub
make flash CHIP=bl618dg COMX=/dev/ttyUSB0

make flash CHIP=bl616cl COMX=/dev/ttyUSB0

make flash CHIP=bl616cl COMX=COM5

git clone git@code.bouffalolab.com:liangzhang/bouffalo_sdk_rel.git

git clone git@code.bouffalolab.com:bouffalo_sw/toolchain_riscv_thead_linux64.git

export PATH=$HOME/work/toolchain_riscv_thead_linux64/bin:$PATH

Windows wsl bringup

2026-04-08T03:45:27Z

张良：/* 2. Build and Flash the Device Firmware */

== 1. Build and Flash the Device Firmware ==
cd examples/wifi/nethub

''# BL616''
make CHIP=bl616 BOARD=bl616dk

''# BL616CL''
make CHIP=bl616cl BOARD=bl616cldk

''# BL618DG''
make CHIP=bl618dg BOARD=bl618dgdk CPU_ID=ap
Flash example:
cd examples/wifi/nethub
make flash CHIP=bl618dg COMX=/dev/ttyUSB0

make flash CHIP=bl616cl COMX=/dev/ttyUSB0

make flash CHIP=bl616cl COMX=COM5

git clone git@code.bouffalolab.com:liangzhang/bouffalo_sdk_rel.git

git clone git@code.bouffalolab.com:bouffalo_sw/toolchain_riscv_thead_linux64.git

export PATH=$HOME/work/toolchain_riscv_thead_linux64/bin:$PATH

Windows wsl bringup

2026-04-08T03:32:53Z

张良：

== 2. Build and Flash the Device Firmware ==
cd examples/wifi/nethub

''# BL616''
make CHIP=bl616 BOARD=bl616dk

''# BL616CL''
make CHIP=bl616cl BOARD=bl616cldk

''# BL618DG''
make CHIP=bl618dg BOARD=bl618dgdk CPU_ID=ap
Flash example:
cd examples/wifi/nethub
make flash CHIP=bl618dg COMX=/dev/ttyUSB0

make flash CHIP=bl616cl COMX=/dev/ttyUSB0

git clone git@code.bouffalolab.com:liangzhang/bouffalo_sdk_rel.git

git clone git@code.bouffalolab.com:bouffalo_sw/toolchain_riscv_thead_linux64.git

export PATH=$HOME/work/toolchain_riscv_thead_linux64/bin:$PATH

Windows wsl bringup

2026-04-08T03:30:36Z

张良：创建页面，内容为“ git clone git@code.bouffalolab.com:liangzhang/bouffalo_sdk_rel.git git clone git@code.bouffalolab.com:bouffalo_sw/toolchain_riscv_thead_linux64.git export PATH=$HOME/work/toolchain_riscv_thead_linux64/bin:$PATH”

git clone git@code.bouffalolab.com:liangzhang/bouffalo_sdk_rel.git

git clone git@code.bouffalolab.com:bouffalo_sw/toolchain_riscv_thead_linux64.git

export PATH=$HOME/work/toolchain_riscv_thead_linux64/bin:$PATH

烧录固件到开发板

2026-04-01T11:00:28Z

张良：/* 查看运行log */

= 如何烧录到DVK light开发板 =

==== 通过USB连接到PC ====

[[文件:BL616DVK Light.jpg | BL616DVK_light | 400px]]

这里以Ubuntu为例，此时应该可以看到 <code>/dev/ttyACM0</code> 设备（以实际为准）

==== 设备进入烧录模式 ====
按住 <code>BOOT</code> 键，trigger 一下 <code>reset</code> 按键，设备即进入烧录模式

==== 编译并烧录 ====
<pre>
cd examples/wifi/sta/wifi_tcp
make CHIP=bl616 BOARD=bl616dk
make flash CHIP=bl616 COMX=/dev/ttyACM0
</pre>

==== 查看运行log ====
通过串口终端查看运行的log即可，默认波特率2M（刚烧录完需要手动按一下Reset按键）

烧录固件到开发板

2026-04-01T10:59:24Z

张良：

烧录固件到开发板

2026-04-01T10:54:39Z

张良：/* 通过USB连接到PC */

= 如何烧录到DVK light开发板 =

==== 通过USB连接到PC ====
[[文件:BL616DVK Light.jpg|缩略图]]
这里以Ubuntu为例，此时应该可以看到 <code>/dev/ttyACM0</code> 设备（以实际为准）

==== 设备进入烧录模式 ====
按住 <code>BOOT</code> 键，trigger 一下 <code>reset</code> 按键，设备即进入烧录模式

==== 编译并烧录 ====
<pre>
cd examples/wifi/sta/wifi_tcp
make CHIP=bl616 BOARD=bl616dk
make flash CHIP=bl616 COMX=/dev/ttyACM0
</pre>

文件:BL616DVK Light.jpg

2026-04-01T10:54:18Z

张良：

BL616DVK_Light

烧录固件到开发板

2026-04-01T10:52:50Z

张良：/* 如何烧录到DVK light开发板 */

= 如何烧录到DVK light开发板 =

==== 通过USB连接到PC ====
这里以Ubuntu为例，此时应该可以看到 <code>/dev/ttyACM0</code> 设备（以实际为准）

==== 设备进入烧录模式 ====
按住 <code>BOOT</code> 键，trigger 一下 <code>reset</code> 按键，设备即进入烧录模式

==== 编译并烧录 ====
<pre>
cd examples/wifi/sta/wifi_tcp
make CHIP=bl616 BOARD=bl616dk
make flash CHIP=bl616 COMX=/dev/ttyACM0
</pre>

烧录固件到开发板

2026-04-01T10:52:06Z

张良：创建页面，内容为“= 如何烧录到DVK light开发板 = # 通过USB连接到PC 这里以Ubuntu为例，此时应该可以看到 <code>/dev/ttyACM0</code> 设备（以实际为准） # 设备进入烧录模式按住 <code>BOOT</code> 键，trigger 一下 <code>reset</code> 按键，设备即进入烧录模式 # 编译并烧录 <pre> cd examples/wifi/sta/wifi_tcp make CHIP=bl616 BOARD=bl616dk make flash CHIP=bl616 COMX=/dev/ttyACM0 </pre>”

= 如何烧录到DVK light开发板 =

# 通过USB连接到PC

这里以Ubuntu为例，此时应该可以看到 <code>/dev/ttyACM0</code> 设备（以实际为准）

# 设备进入烧录模式

按住 <code>BOOT</code> 键，trigger 一下 <code>reset</code> 按键，设备即进入烧录模式

# 编译并烧录

<pre>
cd examples/wifi/sta/wifi_tcp
make CHIP=bl616 BOARD=bl616dk
make flash CHIP=bl616 COMX=/dev/ttyACM0
</pre>

NetHubQuickBringup

2026-03-31T00:14:42Z

张良：Sync NetHub docs from local Markdown

= NetHub Quick Start =

This document is for customers who are using NetHub for the first time. The goal is to help you complete device and host bring-up as quickly as possible.

[[文件:Nethub_sdio_quickstart_demo.gif | NetHub SDIO Quick Start Demo]]

If you only care about the currently available solution, keep these points in mind:

* The current primary path is <code>SDIO</code>
* The device runs <code>Wi-Fi backend (fhost / wl80211) + lwIP</code>
* <code>nethub</code> bridges device-side Wi-Fi capabilities to the host
* The control channel and <code>USER virtual channel</code> both run on the same host link

Active directories:

* device side
** <code>components/net/nethub</code>
** <code>examples/wifi/nethub</code>
* host side
** <code>bsp/common/msg_router/linux_host/kernel</code>
** <code>bsp/common/msg_router/linux_host/userspace/nethub</code>

== 1. Confirm Two Choices Before Bring-Up ==

=== 1.1 Choose the Wi-Fi Backend ===

Default configuration:

* <code>CONFIG_WL80211</code> is disabled
* <code>fhost</code> is used

If you want to switch to <code>wl80211</code>, enable this option in <code>examples/wifi/nethub/defconfig</code>:

<syntaxhighlight lang="makefile">
CONFIG_WL80211=y
</syntaxhighlight>

Notes:

* <code>fhost</code> and <code>wl80211</code> are mutually exclusive
* The current <code>nethub</code> implementation supports both device-side Wi-Fi backends

=== 1.2 Choose the Control Channel ===

device and host settings must match:

{| class="wikitable"
|-
! device configuration !! host startup
|-
| <code>CONFIG_NETHUB_AT_USE_VCHAN=n</code> || <code>./output/bflbwifid</code> or <code>./output/bflbwifid -c tty -p /dev/ttyAT0</code>
|-
| <code>CONFIG_NETHUB_AT_USE_VCHAN=y</code> || <code>./output/bflbwifid -c vchan</code>
|}

The default configuration is:

<syntaxhighlight lang="makefile">
CONFIG_NETHUB_AT_USE_VCHAN=n
</syntaxhighlight>

That means the control channel uses <code>TTY</code> by default.

Additional notes:

* The host side always builds both <code>tty + vchan</code>
* The actual selection happens at <code>bflbwifid</code> runtime

== 2. Build and Flash the Device Firmware ==

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

# BL616
make CHIP=bl616 BOARD=bl616dk

# BL616CL
make CHIP=bl616cl BOARD=bl616cldk

# BL618DG
make CHIP=bl618dg BOARD=bl618dgdk CPU_ID=ap
</syntaxhighlight>

Flash example:

<syntaxhighlight lang="bash">
cd examples/wifi/nethub
make flash CHIP=bl618dg COMX=/dev/ttyUSB0
</syntaxhighlight>

The most relevant bring-up configuration is located in:

* <code>examples/wifi/nethub/defconfig</code>

Common options:

* <code>CONFIG_NETHUB=y</code>
* <code>CONFIG_MR_NETDEV=y</code>
* <code>CONFIG_MR_TTY=y</code>
* <code>CONFIG_MR_VIRTUALCHAN=y</code>
* <code>CONFIG_NETHUB_AT_USE_VCHAN=n</code>

== 3. Build and Start the Host Software ==

=== 3.1 Build ===

<syntaxhighlight lang="bash">
cd bsp/common/msg_router/linux_host/userspace/nethub
./build.sh build
</syntaxhighlight>

Artifacts:

* <code>output/mr_sdio.ko</code>
* <code>output/bflbwifid</code>
* <code>output/bflbwifictrl</code>
* <code>output/libnethub_vchan.a</code>
* <code>output/nethub_vchan_app</code>

=== 3.2 Load the Kernel Module ===

<syntaxhighlight lang="bash">
cd bsp/common/msg_router/linux_host/userspace/nethub
sudo ./build.sh load
</syntaxhighlight>

To unload:

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

=== 3.3 Start the Host Daemon ===

Default TTY mode:

<syntaxhighlight lang="bash">
sudo ./output/bflbwifid
</syntaxhighlight>

Explicit TTY mode:

<syntaxhighlight lang="bash">
sudo ./output/bflbwifid -c tty -p /dev/ttyAT0
</syntaxhighlight>

VCHAN mode:

<syntaxhighlight lang="bash">
sudo ./output/bflbwifid -c vchan
</syntaxhighlight>

== 4. Basic Verification Flow ==

Recommended sequence:

=== 4.1 Check the Current Status ===

<syntaxhighlight lang="bash">
sudo ./output/bflbwifictrl status
</syntaxhighlight>

=== 4.2 Scan APs ===

<syntaxhighlight lang="bash">
sudo ./output/bflbwifictrl scan
</syntaxhighlight>

=== 4.3 Connect to an AP ===

<syntaxhighlight lang="bash">
sudo ./output/bflbwifictrl connect_ap "<ssid>" "<password>"
</syntaxhighlight>

=== 4.4 Check Status Again ===

<syntaxhighlight lang="bash">
sudo ./output/bflbwifictrl status
</syntaxhighlight>

If the connection succeeds, you will usually see:

* the backend is connected
* the Wi-Fi state is <code>CONNECTED</code> or <code>GOTIP</code>
* <code>IP / Gateway / Netmask / DNS</code> after an address is assigned

=== 4.5 Disconnect ===

<syntaxhighlight lang="bash">
sudo ./output/bflbwifictrl disconnect
</syntaxhighlight>

== 5. Common Commands ==

The public CLI surface is fixed to 9 commands:

* <code>connect_ap</code>
* <code>disconnect</code>
* <code>scan</code>
* <code>status</code>
* <code>version</code>
* <code>reboot</code>
* <code>ota</code>
* <code>start_ap</code>
* <code>stop_ap</code>

Examples:

<syntaxhighlight lang="bash">
sudo ./output/bflbwifictrl version
sudo ./output/bflbwifictrl reboot
sudo ./output/bflbwifictrl start_ap "<ssid>" "<password>"
sudo ./output/bflbwifictrl stop_ap
</syntaxhighlight>

== 6. SDIO Hardware Information ==

For the current customer bring-up path, use <code>SDIO</code> directly. <code>USB / SPI</code> still keep architecture skeletons for now and are not the recommended bring-up path.

=== 6.1 Chip Support Matrix ===

{| class="wikitable"
|-
! Interface !! BL616 / BL618 !! BL618DG !! BL616CL
|-
| SDIO || Supported || Supported || Supported
|-
| USB || Planned || Planned || Planned
|-
| SPI || Planned || Planned || Planned
|}

=== 6.2 SDIO Pins ===

{| class="wikitable"
|-
! Pin Function !! BL616 / BL618 !! BL618DG !! BL616CL
|-
| SDIO_DAT2 || GPIO10 || GPIO43 || GPIO6
|-
| SDIO_DAT3 || GPIO11 || GPIO44 || GPIO7
|-
| SDIO_CMD || GPIO12 || GPIO45 || GPIO8
|-
| SDIO_CLK || GPIO13 || GPIO46 || GPIO9
|-
| SDIO_DATA0 || GPIO14 || GPIO47 || GPIO10
|-
| SDIO_DATA1 || GPIO15 || GPIO48 || GPIO11
|}

== 7. USER Virtual Channel ==

If you need to transfer private messages between the host and device, use the <code>USER virtual channel</code>.

Notes:

* The <code>USER</code> channel and the control channel are parallel logical channels
* It is not a separate physical interface; it is a logical channel carried on the current host link

=== 7.1 device-side APIs ===

Header:

* <code>components/net/nethub/include/nethub_vchan.h</code>

Common APIs:

<syntaxhighlight lang="c">
int nethub_vchan_user_send(const void *data, uint16_t len);
int nethub_vchan_user_recv_register(nethub_vchan_recv_cb_t recv_cb, void *cb_arg);
</syntaxhighlight>

=== 7.2 host-side APIs ===

Header:

* <code>bsp/common/msg_router/linux_host/userspace/nethub/virtualchan/nethub_vchan.h</code>

Common APIs:

<syntaxhighlight lang="c">
int nethub_vchan_init(void);
int nethub_vchan_deinit(void);

int nethub_vchan_user_send(const void *data, size_t len);
int nethub_vchan_user_register_callback(nethub_vchan_recv_callback_t callback);

int nethub_vchan_get_state_snapshot(nethub_vchan_state_snapshot_t *snapshot);
</syntaxhighlight>

Typical host-side usage order:

# <code>nethub_vchan_init()</code>
# <code>nethub_vchan_user_register_callback()</code>
# <code>nethub_vchan_user_send()</code>
# Call <code>nethub_vchan_deinit()</code> when finished

If you need to check whether the link is ready, you can optionally query:

* <code>link_state == NETHUB_VCHAN_LINK_UP</code>
** the link is ready for TX/RX
* <code>host_state == NETHUB_VCHAN_HOST_STATE_DEVICE_RUN</code>
** the host has completed the handshake with the device

== 8. Common Issues ==

=== 8.1 <code>bflbwifid</code> Fails to Start ===

Check first:

* whether the device and host control backends match
* whether <code>/dev/ttyAT0</code> exists
* whether <code>mr_sdio.ko</code> has been loaded successfully
* whether the SDIO hardware link is working properly

=== 8.2 <code>connect_ap</code> Succeeds but the Host Has No Network Access ===

Check first:

* whether <code>status</code> has reached <code>GOTIP</code>
* whether <code>mr_eth0</code> has an address
* whether services such as <code>NetworkManager</code> or <code>dhcpcd</code> override the NetHub configuration

Notes:

* <code>build.sh</code> builds userspace with <code>ENABLE_NETIF_AUTO_CONFIG=1</code> by default
* After the device reports <code>GOTIP</code>, the host automatically configures the IP, gateway, and DNS of <code>mr_eth0</code>

=== 8.3 <code>build.sh unload</code> Reports That the Module Is Busy ===

Check first:

* whether <code>bflbwifid</code> is still running
* whether <code>nethub_vchan_app</code> is still running

=== 8.4 How Do I Change the Host-Side Virtual Interface Name <code>mr_eth0</code>? ===

The default host-side virtual network interface name comes from <code>bsp/common/msg_router/linux_host/kernel/netdev/mr_netdev.c</code>:

<syntaxhighlight lang="c">
#define ETH_DRV_NAME "mr_eth%d"
</syntaxhighlight>

The first created interface therefore appears as <code>mr_eth0</code>.

To change the interface name, update <code>ETH_DRV_NAME</code> to the pattern you want. For example:

<syntaxhighlight lang="c">
#define ETH_DRV_NAME "nethub%d"
</syntaxhighlight>

Notes:

* Keep <code>%d</code> if you want Linux to allocate names such as <code>nethub0</code>, <code>nethub1</code>, and so on
* Rebuild the host software after the change and reload the host-side kernel module
* If any local scripts or service configuration still refer to <code>mr_eth0</code>, update them accordingly

TestApi

2026-03-17T11:05:57Z

张良：张良移动页面TestApi至TestApi1：重命名测试页面，统一命名规范

#重定向 [[TestApi1]]

TestApi1

2026-03-17T11:05:57Z

张良：张良移动页面TestApi至TestApi1：重命名测试页面，统一命名规范

== 测试页面 ==

这是一个使用 MediaWiki Action API 创建的测试页面。

创建时间: 2026-03-17

== 功能测试 ==

* Action API 编辑 ✅
* Bot 认证 ✅

== 更新测试 ==

这是追加的内容，测试编辑功能是否正常工作。

更新时间: 刚刚

TestApi2

2026-03-17T11:03:15Z

张良：通过 MCP 工具创建 TestApi2 页面，与 TestApi 形成对比测试

== 高级测试页面 ==

这是通过 MediaWiki API 创建的**第二个**测试页面，与 TestApi 有显著差异。

创建时间: 2026-03-17
页面版本: v2.0

=== API 功能验证 ===

此页面用于验证以下 MediaWiki MCP 功能：

; 页面读取
: 使用 <code>action=query</code> 获取页面内容 ✅

; 页面创建
: 使用 <code>action=edit</code> 创建新页面 ✅

; 格式支持
: Wikitext 格式化测试 ✅

== 数据对比表 ==

{| class="wikitable"
! 特性 !! TestApi !! TestApi2
|-
| 创建方式 || API 编辑 || MCP 工具
|-
| 版本号 || v1.0 || v2.0
|-
| 标题级别 || 二级 || 三级（部分）
|-
| 表格 || 无 || 有
|}

== 额外功能测试 ===

=== 代码块测试 ===

<source lang="python">
def hello_mediawiki():
print("Hello from MediaWiki MCP!")
return True
</source>

=== 列表样式差异 ===

; 有序列表项 1
: 子项描述 A
: 子项描述 B

; 有序列表项 2
: 子项描述 C

== 总结 ==

此页面与 TestApi 的主要差异：

# 使用了更复杂的 wikitext 语法
# 添加了表格展示
# 包含代码高亮示例
# 使用了不同的列表格式
# 页面结构更加层次化

---
''最后更新：通过 MCP 工具自动生成''

TestApi1

2026-03-17T08:49:50Z

张良：追加测试内容

TestApi1

2026-03-17T08:49:50Z

张良：创建 API 测试页面

== 测试页面 ==

这是一个使用 MediaWiki Action API 创建的测试页面。

创建时间: 2026-03-17

== 功能测试 ==

* Action API 编辑 ✅
* Bot 认证 ✅

NetHub

2026-03-17T05:54:34Z

张良：Sync NetHub docs from local Markdown

= NetHub =

NetHub bridges device-side Wi-Fi capabilities to the host.

The current solution targets Wi-Fi SoCs such as <code>BL616 / BL618 / BL616CL / BL618DG</code>, and the recommended bring-up path is currently <code>SDIO</code>.

== Documentation Guide ==

* [[NetHubQuickBringup|NetHubQuickBringup.md]]
** For customers doing first-time bring-up
** Covers key device/host choices, build steps, module loading, AP connection, and common issues
* [[NetHubArchitecture|NetHubArchitecture.md]]
** For developers who need to understand module boundaries and APIs
** Covers device/host layering, public interfaces, and key data flows
* [[NetHubVirtualChannel|NetHubVirtualChannel.md]]
** For customers or application developers who need to transfer private data
** Covers USER channel prerequisites, APIs, and typical usage

== Current Conclusions ==

* The current primary path is <code>SDIO</code>
* The device-side Wi-Fi backend supports <code>fhost / wl80211</code>
* The host control backend is selected at runtime: <code>tty</code> or <code>vchan</code>
* The control channel and <code>USER virtual channel</code> both run on the same host link

== In-Repo Reference Directories ==

* <code>examples/wifi/nethub</code>
* <code>components/net/nethub</code>
* <code>bsp/common/msg_router/linux_host/userspace/nethub</code>

== Local Documentation Source ==

* Markdown documents:
** <code>examples/wifi/nethub/docs/</code>

If you need to publish to the online wiki, use these four Markdown documents as the source.

== Online Wiki ==

* [https://docs.bouffalolab.com/index.php?title=NetHub NetHub]
* [https://docs.bouffalolab.com/index.php?title=NetHubQuickBringup NetHubQuickBringup]
* [https://docs.bouffalolab.com/index.php?title=NetHubArchitecture NetHubArchitecture]
* [https://docs.bouffalolab.com/index.php?title=NetHubVirtualChannel NetHubVirtualChannel]

NetHubQuickBringup

2026-03-17T05:42:10Z

张良：Sync NetHub docs from local Markdown

NetHubVirtualChannel

2026-03-17T05:33:51Z

张良：Sync NetHub docs from local Markdown

= NetHub USER Virtual Channel =

This document describes how to use the NetHub <code>USER virtual channel</code>.

== 1. Concept ==

<code>USER virtual channel</code> is a logical message channel carried on the current host link.

It is not a separate physical interface. It reuses the current <code>SDIO / USB / SPI</code> transport and multiplexes different payload types into separate logical channels.

Commonly used types:

* <code>USER</code>
** private customer or application data
* <code>AT</code>
** host control-plane data
* <code>SYSTEM</code>
** internal system coordination messages

For most customer integrations, only the <code>USER</code> type matters.

== 2. Bring-Up Prerequisites ==

Before using it, confirm:

* device side is built with <code>CONFIG_NETHUB=y</code>
* device side is built with <code>CONFIG_MR_VIRTUALCHAN=y</code>
* host side has already loaded <code>mr_sdio.ko</code>
* the underlying host-device link is already working

Additional notes:

* The <code>USER</code> channel and the control channel are parallel channels
* If the host control plane itself uses <code>vchan</code>, it uses the <code>AT</code> type
* Customer private messages should stay on the <code>USER</code> type

== 3. device-side Interfaces ==

Header:

* <code>components/net/nethub/include/nethub_vchan.h</code>

Common APIs:

<syntaxhighlight lang="c">
int nethub_vchan_user_send(const void *data, uint16_t len);
int nethub_vchan_user_recv_register(nethub_vchan_recv_cb_t recv_cb, void *cb_arg);
</syntaxhighlight>

== 4. host-side Interfaces ==

Header:

* <code>bsp/common/msg_router/linux_host/userspace/nethub/virtualchan/nethub_vchan.h</code>

=== 4.1 Initialization and Cleanup ===

<syntaxhighlight lang="c">
int nethub_vchan_init(void);
int nethub_vchan_deinit(void);
</syntaxhighlight>

=== 4.2 USER Channel ===

<syntaxhighlight lang="c">
typedef void (*nethub_vchan_recv_callback_t)(const void *data, size_t len);

int nethub_vchan_user_send(const void *data, size_t len);
int nethub_vchan_user_register_callback(nethub_vchan_recv_callback_t callback);
</syntaxhighlight>

=== 4.3 Optional State Query ===

If you need to know whether the virtual channel is ready, you can optionally use:

<syntaxhighlight lang="c">
typedef struct {
nethub_vchan_link_state_t link_state;
nethub_vchan_host_state_t host_state;
} nethub_vchan_state_snapshot_t;

int nethub_vchan_get_state_snapshot(nethub_vchan_state_snapshot_t *snapshot);
</syntaxhighlight>

Typical checks:

* <code>link_state == NETHUB_VCHAN_LINK_UP</code>
** the link is ready for TX/RX
* <code>host_state == NETHUB_VCHAN_HOST_STATE_DEVICE_RUN</code>
** the host has completed the handshake with the device

=== 4.4 Optional Link Event Callback ===

If the application wants passive notification when the link goes up or down, it can optionally register:

<syntaxhighlight lang="c">
int nethub_vchan_register_link_event_callback(
nethub_vchan_link_event_callback_t callback,
void *user_data);
</syntaxhighlight>

== 5. Typical Usage Order ==

# <code>nethub_vchan_init()</code>
# <code>nethub_vchan_user_register_callback()</code>
# <code>nethub_vchan_user_send()</code>
# Call <code>nethub_vchan_deinit()</code> when finished

Example:

<syntaxhighlight lang="c">
#include <stdio.h>
#include <string.h>

#include "nethub_vchan.h"

static void user_rx_cb(const void *data, size_t len)
{
printf("recv USER data: %.*s\n", (int)len, (const char *)data);
}

int main(void)
{
const char *msg = "hello from host";

if (nethub_vchan_init() != 0) {
return -1;
}

nethub_vchan_user_register_callback(user_rx_cb);
nethub_vchan_user_send(msg, strlen(msg));

nethub_vchan_deinit();
return 0;
}
</syntaxhighlight>

== 6. Limits and Notes ==

* Maximum payload length per message is <code>1500</code> bytes
* The <code>USER</code> channel is packet-oriented, not a byte stream
* The kernel module must be loaded before use
* If the device side does not enable <code>CONFIG_MR_VIRTUALCHAN</code>, the host-side <code>USER</code> channel will not work
* If host control-plane traffic and <code>USER</code> traffic coexist, do not reuse the <code>AT</code> type for customer private data

== 7. Related Pages ==

* [[NetHubQuickBringup|NetHubQuickBringup.md]]
* [[NetHubArchitecture|NetHubArchitecture.md]]
* [[NetHub|NetHub.md]]

NetHubArchitecture

2026-03-17T05:33:51Z

张良：Sync NetHub docs from local Markdown

= NetHub Architecture Guide =

This document is for developers who need to understand module boundaries and APIs.

== 1. Current Architecture Conclusions ==

* The current physical primary path is <code>SDIO</code>
* <code>USB / SPI</code> still keep backend skeletons and are not recommended bring-up paths for now
* The device-side Wi-Fi backend supports <code>fhost / wl80211</code>
* The control channel and <code>USER virtual channel</code> are logical channels on the current host link, not separate physical interfaces
* The host control backend is selected at runtime: <code>tty</code> or <code>vchan</code>

== 2. Functional Architecture Diagram ==

<pre>
flowchart LR
Host["Host"]
Link["Host Link
current main path: SDIO"]
Data["Data Channel"]
Ctrl["Control Channel"]
User["USER VCHAN"]

subgraph Device["Device"]
subgraph Hub["nethub"]
Bridge["data bridge"]
Filter["hard-coded Wi-Fi RX filter"]
Active["active Wi-Fi selector
STA / AP"]
CtrlPath["ctrlpath"]
Vchan["virtual channel"]
end
Wifi["Wi-Fi backend
fhost / wl80211 + lwIP"]
AT["ATModule"]
end

Host --> Link
Link --> Data
Link --> Ctrl
Link --> User

Data --> Bridge
Bridge --> Active
Active --> Wifi
Wifi --> Filter
Filter --> Bridge

Ctrl --> CtrlPath
CtrlPath --> AT
AT --> Wifi

User --> Vchan
</pre>

From a functional view, <code>nethub</code> mainly does four things:

* maintain the <code>Wi-Fi <-> HostLink</code> data bridge
* use a hard-coded filter to decide whether a packet is <code>local</code>, <code>host</code>, or <code>both</code>
* maintain the currently active Wi-Fi channel, <code>STA / AP</code>
* provide a control channel and an optional <code>USER virtual channel</code> on the same host link

== 3. Technical / API Architecture Diagram ==

<pre>
flowchart TB
App["Application"]

subgraph DevicePublic["device public API"]
DevAPI["nethub.h"]
DevVchan["nethub_vchan.h"]
DevFilter["nethub_filter.h"]
end

subgraph DeviceSide["device side"]
Bootstrap["nethub_bootstrap()"]
Profile["profile select"]
Endpoint["endpoint register"]
Hub["hub lifecycle"]
WifiBridge["Wi-Fi bridge"]
HostBackend["host backend
current main path: sdio"]
end

subgraph HostPublic["host public API"]
HostAPI["bflbwifi.h"]
HostVchan["virtualchan/nethub_vchan.h"]
end

subgraph HostSide["host side"]
CLI["bflbwifictrl"]
IPC["local IPC"]
Daemon["bflbwifid"]
Lib["libbflbwifi"]
Facade["channel facade"]
TTY["tty backend"]
VCHAN["vchan backend"]
Kernel["mr_sdio.ko + msg_router"]
end

App --> DevAPI
App --> DevVchan
App --> DevFilter
App --> HostAPI
App --> HostVchan

DevAPI --> Bootstrap
DevVchan --> HostBackend
DevFilter --> WifiBridge
Bootstrap --> Profile
Bootstrap --> Endpoint
Bootstrap --> Hub
Hub --> WifiBridge
Endpoint --> HostBackend

CLI --> IPC
IPC --> Daemon
Daemon --> Lib
Lib --> Facade
Facade --> TTY
Facade --> VCHAN
TTY --> Kernel
VCHAN --> Kernel
HostVchan --> Kernel
</pre>

== 4. device-side Public Interfaces ==

Headers:

* <code>components/net/nethub/include/nethub.h</code>
* <code>components/net/nethub/include/nethub_vchan.h</code>
* <code>components/net/nethub/include/nethub_filter.h</code>

Core APIs:

* <code>nethub_bootstrap()</code>
* <code>nethub_shutdown()</code>
* <code>nethub_get_status()</code>
* <code>nethub_set_active_wifi_channel()</code>
* <code>nethub_ctrl_upld_send()</code>
* <code>nethub_ctrl_dnld_register()</code>
* <code>nethub_vchan_user_send()</code>
* <code>nethub_vchan_user_recv_register()</code>
* <code>nethub_set_wifi_rx_filter()</code>

Boundary notes:

* <code>nethub_ctrl_*</code> maps to the logical control channel on the host link
* <code>nethub_vchan_user_*</code> maps to the logical <code>USER</code> channel on the host link
* <code>nethub_set_wifi_rx_filter()</code> fully replaces the built-in Wi-Fi RX filter and must be called before <code>nethub_bootstrap()</code>

== 5. host-side Public Interfaces ==

Headers:

* <code>bsp/common/msg_router/linux_host/userspace/nethub/bflbwifictrl/include/bflbwifi.h</code>
* <code>bsp/common/msg_router/linux_host/userspace/nethub/virtualchan/nethub_vchan.h</code>

Control-plane capabilities:

* <code>bflbwifi_ctrl_config_init()</code>
* <code>bflbwifi_ctrl_config_use_tty()</code>
* <code>bflbwifi_ctrl_config_use_vchan()</code>
* <code>bflbwifi_init_ex()</code>
* <code>bflbwifi_get_ctrl_status()</code>
* <code>bflbwifi_sta_connect()</code>
* <code>bflbwifi_sta_disconnect()</code>
* <code>bflbwifi_sta_get_state()</code>
* <code>bflbwifi_scan()</code>
* <code>bflbwifi_get_version()</code>
* <code>bflbwifi_restart()</code>
* <code>bflbwifi_ota_upgrade()</code>
* <code>bflbwifi_ap_start()</code>
* <code>bflbwifi_ap_stop()</code>

USER virtual channel capabilities:

* <code>nethub_vchan_init()</code>
* <code>nethub_vchan_deinit()</code>
* <code>nethub_vchan_user_send()</code>
* <code>nethub_vchan_user_register_callback()</code>
* <code>nethub_vchan_get_state_snapshot()</code>
* <code>nethub_vchan_register_link_event_callback()</code>

== 6. Key Data Flows ==

=== 6.1 <code>connect_ap</code> ===

# The user runs <code>bflbwifictrl connect_ap <ssid> <password></code>
# The CLI sends the command to <code>bflbwifid</code> through local IPC
# The daemon calls <code>libbflbwifi</code>
# <code>libbflbwifi</code> sends control messages through the <code>tty</code> or <code>vchan</code> backend
# The device-side <code>ATModule</code> performs the Wi-Fi control operation
# The device reports responses and state updates, and the host refreshes the state and returns the result

=== 6.2 Data Plane ===

# Host network traffic enters <code>mr_eth0</code>
# The kernel / <code>msg_router</code> communicates with the device over SDIO
# Device-side <code>nethub</code> forwards host data to the currently active Wi-Fi
# After Wi-Fi RX packets pass through the <code>nethub</code> filter, they are handled locally, forwarded to the host, or both

== 7. Recommended Reading Order ==

* First-time bring-up: [[NetHubQuickBringup|NetHubQuickBringup.md]]
* Understanding the <code>USER</code> channel: [[NetHubVirtualChannel|NetHubVirtualChannel.md]]
* Top-level entry: [[NetHub|NetHub.md]]

NetHubQuickBringup

2026-03-17T05:33:43Z

张良：Sync NetHub docs from local Markdown

= NetHub Quick Start =

This document is for customers who are using NetHub for the first time. The goal is to help you complete device and host bring-up as quickly as possible.

<img src="https://docs.bouffalolab.com/images/d/d4/Nethub_sdio_quickstart_demo.gif" alt="NetHub SDIO Quick Start Demo" />

If you only care about the currently available solution, keep these points in mind:

* The current primary path is <code>SDIO</code>
* The device runs <code>Wi-Fi backend (fhost / wl80211) + lwIP</code>
* <code>nethub</code> bridges device-side Wi-Fi capabilities to the host
* The control channel and <code>USER virtual channel</code> both run on the same host link

Active directories:

* device side
** <code>components/net/nethub</code>
** <code>examples/wifi/nethub</code>
* host side
** <code>bsp/common/msg_router/linux_host/kernel</code>
** <code>bsp/common/msg_router/linux_host/userspace/nethub</code>

== 1. Confirm Two Choices Before Bring-Up ==

=== 1.1 Choose the Wi-Fi Backend ===

Default configuration:

* <code>CONFIG_WL80211</code> is disabled
* <code>fhost</code> is used

If you want to switch to <code>wl80211</code>, enable this option in <code>examples/wifi/nethub/defconfig</code>:

<syntaxhighlight lang="makefile">
CONFIG_WL80211=y
</syntaxhighlight>

Notes:

* <code>fhost</code> and <code>wl80211</code> are mutually exclusive
* The current <code>nethub</code> implementation supports both device-side Wi-Fi backends

=== 1.2 Choose the Control Channel ===

device and host settings must match:

{| class="wikitable"
|-
! device configuration !! host startup
|-
| <code>CONFIG_NETHUB_AT_USE_VCHAN=n</code> || <code>./output/bflbwifid</code> or <code>./output/bflbwifid -c tty -p /dev/ttyAT0</code>
|-
| <code>CONFIG_NETHUB_AT_USE_VCHAN=y</code> || <code>./output/bflbwifid -c vchan</code>
|}

The default configuration is:

<syntaxhighlight lang="makefile">
CONFIG_NETHUB_AT_USE_VCHAN=n
</syntaxhighlight>

That means the control channel uses <code>TTY</code> by default.

Additional notes:

* The host side always builds both <code>tty + vchan</code>
* The actual selection happens at <code>bflbwifid</code> runtime

== 2. Build and Flash the Device Firmware ==

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

# BL616
make CHIP=bl616 BOARD=bl616dk

# BL616CL
make CHIP=bl616cl BOARD=bl616cldk

# BL618DG
make CHIP=bl618dg BOARD=bl618dgdk CPU_ID=ap
</syntaxhighlight>

Flash example:

<syntaxhighlight lang="bash">
cd examples/wifi/nethub
make flash CHIP=bl618dg COMX=/dev/ttyUSB0
</syntaxhighlight>

The most relevant bring-up configuration is located in:

* <code>examples/wifi/nethub/defconfig</code>

Common options:

* <code>CONFIG_NETHUB=y</code>
* <code>CONFIG_MR_NETDEV=y</code>
* <code>CONFIG_MR_TTY=y</code>
* <code>CONFIG_MR_VIRTUALCHAN=y</code>
* <code>CONFIG_NETHUB_AT_USE_VCHAN=n</code>

== 3. Build and Start the Host Software ==

=== 3.1 Build ===

<syntaxhighlight lang="bash">
cd bsp/common/msg_router/linux_host/userspace/nethub
./build.sh build
</syntaxhighlight>

Artifacts:

* <code>output/mr_sdio.ko</code>
* <code>output/bflbwifid</code>
* <code>output/bflbwifictrl</code>
* <code>output/libnethub_vchan.a</code>
* <code>output/nethub_vchan_app</code>

=== 3.2 Load the Kernel Module ===

<syntaxhighlight lang="bash">
cd bsp/common/msg_router/linux_host/userspace/nethub
sudo ./build.sh load
</syntaxhighlight>

To unload:

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

=== 3.3 Start the Host Daemon ===

Default TTY mode:

<syntaxhighlight lang="bash">
sudo ./output/bflbwifid
</syntaxhighlight>

Explicit TTY mode:

<syntaxhighlight lang="bash">
sudo ./output/bflbwifid -c tty -p /dev/ttyAT0
</syntaxhighlight>

VCHAN mode:

<syntaxhighlight lang="bash">
sudo ./output/bflbwifid -c vchan
</syntaxhighlight>

== 4. Basic Verification Flow ==

Recommended sequence:

=== 4.1 Check the Current Status ===

<syntaxhighlight lang="bash">
sudo ./output/bflbwifictrl status
</syntaxhighlight>

=== 4.2 Scan APs ===

<syntaxhighlight lang="bash">
sudo ./output/bflbwifictrl scan
</syntaxhighlight>

=== 4.3 Connect to an AP ===

<syntaxhighlight lang="bash">
sudo ./output/bflbwifictrl connect_ap "<ssid>" "<password>"
</syntaxhighlight>

=== 4.4 Check Status Again ===

<syntaxhighlight lang="bash">
sudo ./output/bflbwifictrl status
</syntaxhighlight>

If the connection succeeds, you will usually see:

* the backend is connected
* the Wi-Fi state is <code>CONNECTED</code> or <code>GOTIP</code>
* <code>IP / Gateway / Netmask / DNS</code> after an address is assigned

=== 4.5 Disconnect ===

<syntaxhighlight lang="bash">
sudo ./output/bflbwifictrl disconnect
</syntaxhighlight>

== 5. Common Commands ==

The public CLI surface is fixed to 9 commands:

* <code>connect_ap</code>
* <code>disconnect</code>
* <code>scan</code>
* <code>status</code>
* <code>version</code>
* <code>reboot</code>
* <code>ota</code>
* <code>start_ap</code>
* <code>stop_ap</code>

Examples:

<syntaxhighlight lang="bash">
sudo ./output/bflbwifictrl version
sudo ./output/bflbwifictrl reboot
sudo ./output/bflbwifictrl start_ap "<ssid>" "<password>"
sudo ./output/bflbwifictrl stop_ap
</syntaxhighlight>

== 6. SDIO Hardware Information ==

For the current customer bring-up path, use <code>SDIO</code> directly. <code>USB / SPI</code> still keep architecture skeletons for now and are not the recommended bring-up path.

=== 6.1 Chip Support Matrix ===

{| class="wikitable"
|-
! Interface !! BL616 / BL618 !! BL618DG !! BL616CL
|-
| SDIO || Supported || Supported || Supported
|-
| USB || Planned || Planned || Planned
|-
| SPI || Planned || Planned || Planned
|}

=== 6.2 SDIO Pins ===

{| class="wikitable"
|-
! Pin Function !! BL616 / BL618 !! BL618DG !! BL616CL
|-
| SDIO_DAT2 || GPIO10 || GPIO43 || GPIO6
|-
| SDIO_DAT3 || GPIO11 || GPIO44 || GPIO7
|-
| SDIO_CMD || GPIO12 || GPIO45 || GPIO8
|-
| SDIO_CLK || GPIO13 || GPIO46 || GPIO9
|-
| SDIO_DATA0 || GPIO14 || GPIO47 || GPIO10
|-
| SDIO_DATA1 || GPIO15 || GPIO48 || GPIO11
|}

== 7. USER Virtual Channel ==

If you need to transfer private messages between the host and device, use the <code>USER virtual channel</code>.

Notes:

* The <code>USER</code> channel and the control channel are parallel logical channels
* It is not a separate physical interface; it is a logical channel carried on the current host link

=== 7.1 device-side APIs ===

Header:

* <code>components/net/nethub/include/nethub_vchan.h</code>

Common APIs:

<syntaxhighlight lang="c">
int nethub_vchan_user_send(const void *data, uint16_t len);
int nethub_vchan_user_recv_register(nethub_vchan_recv_cb_t recv_cb, void *cb_arg);
</syntaxhighlight>

=== 7.2 host-side APIs ===

Header:

* <code>bsp/common/msg_router/linux_host/userspace/nethub/virtualchan/nethub_vchan.h</code>

Common APIs:

<syntaxhighlight lang="c">
int nethub_vchan_init(void);
int nethub_vchan_deinit(void);

int nethub_vchan_user_send(const void *data, size_t len);
int nethub_vchan_user_register_callback(nethub_vchan_recv_callback_t callback);

int nethub_vchan_get_state_snapshot(nethub_vchan_state_snapshot_t *snapshot);
</syntaxhighlight>

Typical host-side usage order:

# <code>nethub_vchan_init()</code>
# <code>nethub_vchan_user_register_callback()</code>
# <code>nethub_vchan_user_send()</code>
# Call <code>nethub_vchan_deinit()</code> when finished

If you need to check whether the link is ready, you can optionally query:

* <code>link_state == NETHUB_VCHAN_LINK_UP</code>
** the link is ready for TX/RX
* <code>host_state == NETHUB_VCHAN_HOST_STATE_DEVICE_RUN</code>
** the host has completed the handshake with the device

== 8. Common Issues ==

=== 8.1 <code>bflbwifid</code> Fails to Start ===

Check first:

* whether the device and host control backends match
* whether <code>/dev/ttyAT0</code> exists
* whether <code>mr_sdio.ko</code> has been loaded successfully
* whether the SDIO hardware link is working properly

=== 8.2 <code>connect_ap</code> Succeeds but the Host Has No Network Access ===

Check first:

* whether <code>status</code> has reached <code>GOTIP</code>
* whether <code>mr_eth0</code> has an address
* whether services such as <code>NetworkManager</code> or <code>dhcpcd</code> override the NetHub configuration

Notes:

* <code>build.sh</code> builds userspace with <code>ENABLE_NETIF_AUTO_CONFIG=1</code> by default
* After the device reports <code>GOTIP</code>, the host automatically configures the IP, gateway, and DNS of <code>mr_eth0</code>

=== 8.3 <code>build.sh unload</code> Reports That the Module Is Busy ===

Check first:

* whether <code>bflbwifid</code> is still running
* whether <code>nethub_vchan_app</code> is still running

NetHub

2026-03-17T05:33:43Z

张良：Sync NetHub docs from local Markdown

= NetHub =

NetHub bridges device-side Wi-Fi capabilities to the host.

The current solution targets Wi-Fi SoCs such as <code>BL616 / BL618 / BL616CL / BL618DG</code>, and the recommended bring-up path is currently <code>SDIO</code>.

== Documentation Guide ==

* [[NetHubQuickBringup|NetHubQuickBringup.md]]
** For customers doing first-time bring-up
** Covers key device/host choices, build steps, module loading, AP connection, and common issues
* [[NetHubArchitecture|NetHubArchitecture.md]]
** For developers who need to understand module boundaries and APIs
** Covers device/host layering, public interfaces, and key data flows
* [[NetHubVirtualChannel|NetHubVirtualChannel.md]]
** For customers or application developers who need to transfer private data
** Covers USER channel prerequisites, APIs, and typical usage

== Current Conclusions ==

* The current primary path is <code>SDIO</code>
* The device-side Wi-Fi backend supports <code>fhost / wl80211</code>
* The host control backend is selected at runtime: <code>tty</code> or <code>vchan</code>
* The control channel and <code>USER virtual channel</code> both run on the same host link

== In-Repo Reference Directories ==

* <code>examples/wifi/nethub</code>
* <code>components/net/nethub</code>
* <code>bsp/common/msg_router/linux_host/userspace/nethub</code>

== Local Documentation Source ==

* Markdown documents:
** <code>examples/wifi/nethub/docs/</code>

If you need to publish to the online wiki, use these four Markdown documents as the source.

== Online Wiki ==

* [https://docs.bouffalolab.com/index.php?title=NetHub]
* [https://docs.bouffalolab.com/index.php?title=NetHubQuickBringup]
* [https://docs.bouffalolab.com/index.php?title=NetHubArchitecture]
* [https://docs.bouffalolab.com/index.php?title=NetHubVirtualChannel]

NetHubQuickBringup

2026-03-16T02:37:46Z

张良：Sync NetHub docs from local MediaWiki export

= NetHub 快速上手 =

本文档面向首次接触 NetHub 的客户，目标是尽快完成 device 和 host 的 bringup。

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

== 1. 方案概览 ==

* 当前主路径是 '''SDIO'''
* device 侧运行 <code>Wi-Fi backend（fhost / wl80211）+ lwIP</code>
* <code>nethub</code> 负责把 device 侧 Wi-Fi 能力桥接到 host
* 控制通道和 <code>USER virtual channel</code> 都承载在同一条 host link 上

当前生效目录：

* device 侧
** <code>components/net/nethub</code>
** <code>examples/wifi/nethub</code>
* host 侧
** <code>bsp/common/msg_router/linux_host/kernel</code>
** <code>bsp/common/msg_router/linux_host/userspace/nethub</code>

== 2. Bringup 前先确认两项选择 ==

=== 2.1 选择 Wi-Fi backend ===

默认配置：

* 不打开 <code>CONFIG_WL80211</code>
* 使用 <code>fhost</code>

如果要切到 <code>wl80211</code>，在 <code>examples/wifi/nethub/defconfig</code> 中打开：

<syntaxhighlight lang="make">
CONFIG_WL80211=y
</syntaxhighlight>

说明：

* <code>fhost</code> 和 <code>wl80211</code> 是二选一关系
* 当前 <code>nethub</code> 同时支持这两种 device Wi-Fi backend

=== 2.2 选择控制通道 ===

device 与 host 需要匹配：

{| class="wikitable"
! device 配置
! host 启动方式
|-
| <code>CONFIG_NETHUB_AT_USE_VCHAN=n</code>
| <code>./output/bflbwifid</code> 或 <code>./output/bflbwifid -c tty -p /dev/ttyAT0</code>
|-
| <code>CONFIG_NETHUB_AT_USE_VCHAN=y</code>
| <code>./output/bflbwifid -c vchan</code>
|}

默认配置是：

<syntaxhighlight lang="make">
CONFIG_NETHUB_AT_USE_VCHAN=n
</syntaxhighlight>

即控制通道默认走 <code>TTY</code>。

补充说明：

* host 侧会同时编入 <code>tty + vchan</code>
* 实际选择发生在 <code>bflbwifid</code> 运行时

== 3. 编译并烧录 device 固件 ==

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

# 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">
cd examples/wifi/nethub
make flash CHIP=bl618dg COMX=/dev/ttyUSB0
</syntaxhighlight>

常见关键配置：

* <code>CONFIG_NETHUB=y</code>
* <code>CONFIG_MR_NETDEV=y</code>
* <code>CONFIG_MR_TTY=y</code>
* <code>CONFIG_MR_VIRTUALCHAN=y</code>
* <code>CONFIG_NETHUB_AT_USE_VCHAN=n</code>

== 4. 编译并启动 host 软件 ==

=== 4.1 编译 ===

<syntaxhighlight lang="bash">
cd bsp/common/msg_router/linux_host/userspace/nethub
./build.sh build
</syntaxhighlight>

产物：

* <code>output/mr_sdio.ko</code>
* <code>output/bflbwifid</code>
* <code>output/bflbwifictrl</code>
* <code>output/libnethub_vchan.a</code>
* <code>output/nethub_vchan_app</code>

=== 4.2 加载内核模块 ===

<syntaxhighlight lang="bash">
cd bsp/common/msg_router/linux_host/userspace/nethub
sudo ./build.sh load
</syntaxhighlight>

如需卸载：

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

=== 4.3 启动 host daemon ===

默认 TTY 模式：

<syntaxhighlight lang="bash">
sudo ./output/bflbwifid
</syntaxhighlight>

显式指定 TTY：

<syntaxhighlight lang="bash">
sudo ./output/bflbwifid -c tty -p /dev/ttyAT0
</syntaxhighlight>

VCHAN 模式：

<syntaxhighlight lang="bash">
sudo ./output/bflbwifid -c vchan
</syntaxhighlight>

== 5. 基础验证流程 ==

建议按下面顺序验证：

=== 5.1 查看状态 ===

<syntaxhighlight lang="bash">
sudo ./output/bflbwifictrl status
</syntaxhighlight>

=== 5.2 扫描 AP ===

<syntaxhighlight lang="bash">
sudo ./output/bflbwifictrl scan
</syntaxhighlight>

=== 5.3 连接 AP ===

<syntaxhighlight lang="bash">
sudo ./output/bflbwifictrl connect_ap "<ssid>" "<password>"
</syntaxhighlight>

=== 5.4 再次查看状态 ===

<syntaxhighlight lang="bash">
sudo ./output/bflbwifictrl status
</syntaxhighlight>

如果连接成功，通常可以看到：

* backend 已连接
* Wi-Fi 状态为 <code>CONNECTED</code> 或 <code>GOTIP</code>
* 获取到地址后显示 <code>IP / Gateway / Netmask / DNS</code>

=== 5.5 断开连接 ===

<syntaxhighlight lang="bash">
sudo ./output/bflbwifictrl disconnect
</syntaxhighlight>

== 6. 常用命令 ==

当前公共命令固定为 9 条：

* <code>connect_ap</code>
* <code>disconnect</code>
* <code>scan</code>
* <code>status</code>
* <code>version</code>
* <code>reboot</code>
* <code>ota</code>
* <code>start_ap</code>
* <code>stop_ap</code>

== 7. SDIO 硬件信息 ==

当前客户 bringup 路径建议直接按 <code>SDIO</code> 使用。
<code>USB / SPI</code> 目前仍保留架构骨架，不作为当前推荐 bringup 路径。

=== 7.1 芯片支持情况 ===

{| class="wikitable"
! 接口类型
! BL616 / BL618
! BL618DG
! BL616CL
|-
| SDIO
| 支持
| 支持
| 支持
|-
| USB
| 规划中
| 规划中
| 规划中
|-
| SPI
| 规划中
| 规划中
| 规划中
|}

=== 7.2 SDIO 引脚 ===

{| class="wikitable"
! 功能引脚
! BL616 / BL618
! BL618DG
! BL616CL
|-
| SDIO_DAT2
| GPIO10
| GPIO43
| GPIO6
|-
| SDIO_DAT3
| GPIO11
| GPIO44
| GPIO7
|-
| SDIO_CMD
| GPIO12
| GPIO45
| GPIO8
|-
| SDIO_CLK
| GPIO13
| GPIO46
| GPIO9
|-
| SDIO_DATA0
| GPIO14
| GPIO47
| GPIO10
|-
| SDIO_DATA1
| GPIO15
| GPIO48
| GPIO11
|}

== 8. USER Virtual Channel ==

如果客户需要在 host 与 device 之间传输私有消息，可使用 <code>USER virtual channel</code>。

说明：

* <code>USER</code> 通道和控制通道是并列关系
* 它不是独立物理接口，而是承载在当前 host link 上的逻辑通道

device 侧头文件：

* <code>components/net/nethub/include/nethub_vchan.h</code>

host 侧头文件：

* <code>bsp/common/msg_router/linux_host/userspace/nethub/virtualchan/nethub_vchan.h</code>

更多说明见 [[NetHubVirtualChannel|NetHub USER Virtual Channel]]。

== 9. 常见问题 ==

=== 9.1 <code>bflbwifid</code> 启动失败 ===

优先检查：

* device 和 host 的控制 backend 是否匹配
* <code>/dev/ttyAT0</code> 是否存在
* <code>mr_sdio.ko</code> 是否已经成功加载
* SDIO 硬件链路是否正常

=== 9.2 <code>connect_ap</code> 成功但 host 没有网络 ===

优先检查：

* <code>status</code> 是否已经进入 <code>GOTIP</code>
* <code>mr_eth0</code> 是否已经获取地址
* 系统里的 <code>NetworkManager</code>、<code>dhcpcd</code> 等服务是否覆盖了 NetHub 配置

说明：

* <code>build.sh</code> 默认以 <code>ENABLE_NETIF_AUTO_CONFIG=1</code> 编译 userspace
* device 上报 <code>GOTIP</code> 后，host 会自动配置 <code>mr_eth0</code> 的 IP、网关和 DNS

=== 9.3 <code>build.sh unload</code> 提示模块被占用 ===

优先确认：

* 是否还有 <code>bflbwifid</code> 正在运行
* 是否还有 <code>nethub_vchan_app</code> 正在运行

通常直接执行：

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

脚本会先尝试停止已知持有者，再执行卸载。

== 10. 延伸阅读 ==

* [[NetHubArchitecture|NetHub 架构说明]]
* [[NetHubVirtualChannel|NetHub USER Virtual Channel]]

NetHubQuickBringup

2026-03-16T02:25:42Z

张良：Sync NetHub docs from local MediaWiki export

= NetHub 快速上手 =

本文档面向首次接触 NetHub 的客户，目标是尽快完成 device 和 host 的 bringup。

== 1. 方案概览 ==

* 当前主路径是 '''SDIO'''
* device 侧运行 <code>Wi-Fi backend（fhost / wl80211）+ lwIP</code>
* <code>nethub</code> 负责把 device 侧 Wi-Fi 能力桥接到 host
* 控制通道和 <code>USER virtual channel</code> 都承载在同一条 host link 上

当前生效目录：

* device 侧
** <code>components/net/nethub</code>
** <code>examples/wifi/nethub</code>
* host 侧
** <code>bsp/common/msg_router/linux_host/kernel</code>
** <code>bsp/common/msg_router/linux_host/userspace/nethub</code>

== 2. Bringup 前先确认两项选择 ==

=== 2.1 选择 Wi-Fi backend ===

默认配置：

* 不打开 <code>CONFIG_WL80211</code>
* 使用 <code>fhost</code>

如果要切到 <code>wl80211</code>，在 <code>examples/wifi/nethub/defconfig</code> 中打开：

<syntaxhighlight lang="make">
CONFIG_WL80211=y
</syntaxhighlight>

说明：

* <code>fhost</code> 和 <code>wl80211</code> 是二选一关系
* 当前 <code>nethub</code> 同时支持这两种 device Wi-Fi backend

=== 2.2 选择控制通道 ===

device 与 host 需要匹配：

{| class="wikitable"
! device 配置
! host 启动方式
|-
| <code>CONFIG_NETHUB_AT_USE_VCHAN=n</code>
| <code>./output/bflbwifid</code> 或 <code>./output/bflbwifid -c tty -p /dev/ttyAT0</code>
|-
| <code>CONFIG_NETHUB_AT_USE_VCHAN=y</code>
| <code>./output/bflbwifid -c vchan</code>
|}

默认配置是：

<syntaxhighlight lang="make">
CONFIG_NETHUB_AT_USE_VCHAN=n
</syntaxhighlight>

即控制通道默认走 <code>TTY</code>。

补充说明：

* host 侧会同时编入 <code>tty + vchan</code>
* 实际选择发生在 <code>bflbwifid</code> 运行时

== 3. 编译并烧录 device 固件 ==

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

# 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">
cd examples/wifi/nethub
make flash CHIP=bl618dg COMX=/dev/ttyUSB0
</syntaxhighlight>

常见关键配置：

* <code>CONFIG_NETHUB=y</code>
* <code>CONFIG_MR_NETDEV=y</code>
* <code>CONFIG_MR_TTY=y</code>
* <code>CONFIG_MR_VIRTUALCHAN=y</code>
* <code>CONFIG_NETHUB_AT_USE_VCHAN=n</code>

== 4. 编译并启动 host 软件 ==

=== 4.1 编译 ===

<syntaxhighlight lang="bash">
cd bsp/common/msg_router/linux_host/userspace/nethub
./build.sh build
</syntaxhighlight>

产物：

* <code>output/mr_sdio.ko</code>
* <code>output/bflbwifid</code>
* <code>output/bflbwifictrl</code>
* <code>output/libnethub_vchan.a</code>
* <code>output/nethub_vchan_app</code>

=== 4.2 加载内核模块 ===

<syntaxhighlight lang="bash">
cd bsp/common/msg_router/linux_host/userspace/nethub
sudo ./build.sh load
</syntaxhighlight>

如需卸载：

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

=== 4.3 启动 host daemon ===

默认 TTY 模式：

<syntaxhighlight lang="bash">
sudo ./output/bflbwifid
</syntaxhighlight>

显式指定 TTY：

<syntaxhighlight lang="bash">
sudo ./output/bflbwifid -c tty -p /dev/ttyAT0
</syntaxhighlight>

VCHAN 模式：

<syntaxhighlight lang="bash">
sudo ./output/bflbwifid -c vchan
</syntaxhighlight>

== 5. 基础验证流程 ==

建议按下面顺序验证：

=== 5.1 查看状态 ===

<syntaxhighlight lang="bash">
sudo ./output/bflbwifictrl status
</syntaxhighlight>

=== 5.2 扫描 AP ===

<syntaxhighlight lang="bash">
sudo ./output/bflbwifictrl scan
</syntaxhighlight>

=== 5.3 连接 AP ===

<syntaxhighlight lang="bash">
sudo ./output/bflbwifictrl connect_ap "<ssid>" "<password>"
</syntaxhighlight>

=== 5.4 再次查看状态 ===

<syntaxhighlight lang="bash">
sudo ./output/bflbwifictrl status
</syntaxhighlight>

如果连接成功，通常可以看到：

* backend 已连接
* Wi-Fi 状态为 <code>CONNECTED</code> 或 <code>GOTIP</code>
* 获取到地址后显示 <code>IP / Gateway / Netmask / DNS</code>

=== 5.5 断开连接 ===

<syntaxhighlight lang="bash">
sudo ./output/bflbwifictrl disconnect
</syntaxhighlight>

== 6. 常用命令 ==

当前公共命令固定为 9 条：

* <code>connect_ap</code>
* <code>disconnect</code>
* <code>scan</code>
* <code>status</code>
* <code>version</code>
* <code>reboot</code>
* <code>ota</code>
* <code>start_ap</code>
* <code>stop_ap</code>

== 7. SDIO 硬件信息 ==

当前客户 bringup 路径建议直接按 <code>SDIO</code> 使用。
<code>USB / SPI</code> 目前仍保留架构骨架，不作为当前推荐 bringup 路径。

=== 7.1 芯片支持情况 ===

{| class="wikitable"
! 接口类型
! BL616 / BL618
! BL618DG
! BL616CL
|-
| SDIO
| 支持
| 支持
| 支持
|-
| USB
| 规划中
| 规划中
| 规划中
|-
| SPI
| 规划中
| 规划中
| 规划中
|}

=== 7.2 SDIO 引脚 ===

{| class="wikitable"
! 功能引脚
! BL616 / BL618
! BL618DG
! BL616CL
|-
| SDIO_DAT2
| GPIO10
| GPIO43
| GPIO6
|-
| SDIO_DAT3
| GPIO11
| GPIO44
| GPIO7
|-
| SDIO_CMD
| GPIO12
| GPIO45
| GPIO8
|-
| SDIO_CLK
| GPIO13
| GPIO46
| GPIO9
|-
| SDIO_DATA0
| GPIO14
| GPIO47
| GPIO10
|-
| SDIO_DATA1
| GPIO15
| GPIO48
| GPIO11
|}

== 8. USER Virtual Channel ==

如果客户需要在 host 与 device 之间传输私有消息，可使用 <code>USER virtual channel</code>。

说明：

* <code>USER</code> 通道和控制通道是并列关系
* 它不是独立物理接口，而是承载在当前 host link 上的逻辑通道

device 侧头文件：

* <code>components/net/nethub/include/nethub_vchan.h</code>

host 侧头文件：

* <code>bsp/common/msg_router/linux_host/userspace/nethub/virtualchan/nethub_vchan.h</code>

更多说明见 [[NetHubVirtualChannel|NetHub USER Virtual Channel]]。

== 9. 常见问题 ==

=== 9.1 <code>bflbwifid</code> 启动失败 ===

优先检查：

* device 和 host 的控制 backend 是否匹配
* <code>/dev/ttyAT0</code> 是否存在
* <code>mr_sdio.ko</code> 是否已经成功加载
* SDIO 硬件链路是否正常

=== 9.2 <code>connect_ap</code> 成功但 host 没有网络 ===

优先检查：

* <code>status</code> 是否已经进入 <code>GOTIP</code>
* <code>mr_eth0</code> 是否已经获取地址
* 系统里的 <code>NetworkManager</code>、<code>dhcpcd</code> 等服务是否覆盖了 NetHub 配置

说明：

* <code>build.sh</code> 默认以 <code>ENABLE_NETIF_AUTO_CONFIG=1</code> 编译 userspace
* device 上报 <code>GOTIP</code> 后，host 会自动配置 <code>mr_eth0</code> 的 IP、网关和 DNS

=== 9.3 <code>build.sh unload</code> 提示模块被占用 ===

优先确认：

* 是否还有 <code>bflbwifid</code> 正在运行
* 是否还有 <code>nethub_vchan_app</code> 正在运行

通常直接执行：

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

脚本会先尝试停止已知持有者，再执行卸载。

== 10. 延伸阅读 ==

* [[NetHubArchitecture|NetHub 架构说明]]
* [[NetHubVirtualChannel|NetHub USER Virtual Channel]]

首页

2026-03-13T09:32:45Z

张良：

= Getting Started =

* [https://github.com/bouffalolab/bouffalo_sdk 如何获取SDK]
* [[如何在Ubuntu上搭建编译环境]]
* [[如何在Windows上搭建编译环境]]
* [[如何获取开发板]]
* [[烧录固件到开发板]]

= Bouffalo SDK =
'''BouffaloSDK''' 是 Bouffalo Lab 提供的 IOT 和 MCU 软件开发包，支持博流智能所有系列芯片，也是 '''bl_mcu_sdk''' 和 '''bl_iot_sdk''' 的结合体。

[[文件:BouffaloSDK.png|无框|600x600像素]]

= Peripherals =

{| border="0" cellpadding="10" width="100%"
|-
|width="32%" valign="top" align="left"|
*[[I2S]]
*[[I2C]]
*[[CVBS]]
*[[Watchdog]]
*[[GSM/GPRS]]
*[[Codec]]
*[[PCIe]]
*[[GPIO]]
*[[eMMC]]
|width="32%" valign="top" align="left"|
*[[WiFi]]
*[[LED]]
*[[Serial port]]
*[[PWM]]
*[[SPI]]
*[[USB OTG]]
*[[LCD]]
*[[CPU]]
*[[Network]]
|width="32%" valign="top" align="left"|
*[[Bluetooth]]
*[[HDMI]]
*[[Camera]]
*[[Memory]]
*[[RTC]]
*[[EEPROM]]
*[[MIPI-DSI]]
*[[NPU]]
*[[VPU]]
|}

= Products =
{| border="0" cellpadding="10" width="100%"
|-
|width="50%" valign="top" align="left"|
* [[BL602]]
* [[BL702]]
* [[BL618]]
* [[BL606P]]
|width="50%" valign="top" align="left"|
* [[BL702L]]
* [[BL616]]
|}

= Develop Boards =
* BL602EVB

= Application Notes =
* [[NetHub]]
* [[BL616低功耗开发手册]]
* [[USB Wi-Fi用户手册]]

= Demos =

{| border="0" cellpadding="10" width="100%"
|-
|width="32%" valign="top" align="left"|
*[[Demo:FreeRTOS]]
* [[Demo:wifi sta]]
* [[Demo:boot2_isp]]
* [[Demo:helloworld]]
* [[Demo:smartconfig ble]]
|width="32%" valign="top" align="left"|
*[[Demo:DMA]]
* [[Demo:Btble]]
* [[Demo:coremark]]
* [[Demo:littlefs]]
* [[Demo:posix freertos]]
|width="32%" valign="top" align="left"|
*[[Demo:Flash]]
* [[Demo:Basical case]]
* [[Demo:dsp]]
* [[Demo:cks]]
|}

NetHubQuickBringup

2026-03-13T09:31:34Z

张良：

NetHubQuickBringup

2026-03-13T09:29:39Z

张良：

= NetHub 快速上手 =

本文档面向首次接触 NetHub 的客户，目标是尽快完成 device 和 host 的 bringup。
[[index.php?title=文件:Nethub_sdio_quickstart_demo.gif|链接=文件:Nethub_sdio_quickstart_demo.gif|NetHub SDIO 快速入门演示]]

== 1. 方案概览 ==

* 当前主路径是 '''SDIO'''
* device 侧运行 <code>Wi-Fi backend（fhost / wl80211）+ lwIP</code>
* <code>nethub</code> 负责把 device 侧 Wi-Fi 能力桥接到 host
* 控制通道和 <code>USER virtual channel</code> 都承载在同一条 host link 上

当前生效目录：

* device 侧
** <code>components/net/nethub</code>
** <code>examples/wifi/nethub</code>
* host 侧
** <code>bsp/common/msg_router/linux_host/kernel</code>
** <code>bsp/common/msg_router/linux_host/userspace/nethub</code>

== 2. Bringup 前先确认两项选择 ==

=== 2.1 选择 Wi-Fi backend ===

默认配置：

* 不打开 <code>CONFIG_WL80211</code>
* 使用 <code>fhost</code>

如果要切到 <code>wl80211</code>，在 <code>examples/wifi/nethub/defconfig</code> 中打开：

<syntaxhighlight lang="make">
CONFIG_WL80211=y
</syntaxhighlight>

说明：

* <code>fhost</code> 和 <code>wl80211</code> 是二选一关系
* 当前 <code>nethub</code> 同时支持这两种 device Wi-Fi backend

=== 2.2 选择控制通道 ===

device 与 host 需要匹配：

{| class="wikitable"
! device 配置
! host 启动方式
|-
| <code>CONFIG_NETHUB_AT_USE_VCHAN=n</code>
| <code>./output/bflbwifid</code> 或 <code>./output/bflbwifid -c tty -p /dev/ttyAT0</code>
|-
| <code>CONFIG_NETHUB_AT_USE_VCHAN=y</code>
| <code>./output/bflbwifid -c vchan</code>
|}

默认配置是：

<syntaxhighlight lang="make">
CONFIG_NETHUB_AT_USE_VCHAN=n
</syntaxhighlight>

即控制通道默认走 <code>TTY</code>。

补充说明：

* host 侧会同时编入 <code>tty + vchan</code>
* 实际选择发生在 <code>bflbwifid</code> 运行时

== 3. 编译并烧录 device 固件 ==

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

# 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">
cd examples/wifi/nethub
make flash CHIP=bl618dg COMX=/dev/ttyUSB0
</syntaxhighlight>

常见关键配置：

* <code>CONFIG_NETHUB=y</code>
* <code>CONFIG_MR_NETDEV=y</code>
* <code>CONFIG_MR_TTY=y</code>
* <code>CONFIG_MR_VIRTUALCHAN=y</code>
* <code>CONFIG_NETHUB_AT_USE_VCHAN=n</code>

== 4. 编译并启动 host 软件 ==

=== 4.1 编译 ===

<syntaxhighlight lang="bash">
cd bsp/common/msg_router/linux_host/userspace/nethub
./build.sh build
</syntaxhighlight>

产物：

* <code>output/mr_sdio.ko</code>
* <code>output/bflbwifid</code>
* <code>output/bflbwifictrl</code>
* <code>output/libnethub_vchan.a</code>
* <code>output/nethub_vchan_app</code>

=== 4.2 加载内核模块 ===

<syntaxhighlight lang="bash">
cd bsp/common/msg_router/linux_host/userspace/nethub
sudo ./build.sh load
</syntaxhighlight>

如需卸载：

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

=== 4.3 启动 host daemon ===

默认 TTY 模式：

<syntaxhighlight lang="bash">
sudo ./output/bflbwifid
</syntaxhighlight>

显式指定 TTY：

<syntaxhighlight lang="bash">
sudo ./output/bflbwifid -c tty -p /dev/ttyAT0
</syntaxhighlight>

VCHAN 模式：

<syntaxhighlight lang="bash">
sudo ./output/bflbwifid -c vchan
</syntaxhighlight>

== 5. 基础验证流程 ==

建议按下面顺序验证：

=== 5.1 查看状态 ===

<syntaxhighlight lang="bash">
sudo ./output/bflbwifictrl status
</syntaxhighlight>

=== 5.2 扫描 AP ===

<syntaxhighlight lang="bash">
sudo ./output/bflbwifictrl scan
</syntaxhighlight>

=== 5.3 连接 AP ===

<syntaxhighlight lang="bash">
sudo ./output/bflbwifictrl connect_ap "<ssid>" "<password>"
</syntaxhighlight>

=== 5.4 再次查看状态 ===

<syntaxhighlight lang="bash">
sudo ./output/bflbwifictrl status
</syntaxhighlight>

如果连接成功，通常可以看到：

* backend 已连接
* Wi-Fi 状态为 <code>CONNECTED</code> 或 <code>GOTIP</code>
* 获取到地址后显示 <code>IP / Gateway / Netmask / DNS</code>

=== 5.5 断开连接 ===

<syntaxhighlight lang="bash">
sudo ./output/bflbwifictrl disconnect
</syntaxhighlight>

== 6. 常用命令 ==

当前公共命令固定为 9 条：

* <code>connect_ap</code>
* <code>disconnect</code>
* <code>scan</code>
* <code>status</code>
* <code>version</code>
* <code>reboot</code>
* <code>ota</code>
* <code>start_ap</code>
* <code>stop_ap</code>

== 7. SDIO 硬件信息 ==

当前客户 bringup 路径建议直接按 <code>SDIO</code> 使用。
<code>USB / SPI</code> 目前仍保留架构骨架，不作为当前推荐 bringup 路径。

=== 7.1 芯片支持情况 ===

{| class="wikitable"
! 接口类型
! BL616 / BL618
! BL618DG
! BL616CL
|-
| SDIO
| 支持
| 支持
| 支持
|-
| USB
| 规划中
| 规划中
| 规划中
|-
| SPI
| 规划中
| 规划中
| 规划中
|}

=== 7.2 SDIO 引脚 ===

{| class="wikitable"
! 功能引脚
! BL616 / BL618
! BL618DG
! BL616CL
|-
| SDIO_DAT2
| GPIO10
| GPIO43
| GPIO6
|-
| SDIO_DAT3
| GPIO11
| GPIO44
| GPIO7
|-
| SDIO_CMD
| GPIO12
| GPIO45
| GPIO8
|-
| SDIO_CLK
| GPIO13
| GPIO46
| GPIO9
|-
| SDIO_DATA0
| GPIO14
| GPIO47
| GPIO10
|-
| SDIO_DATA1
| GPIO15
| GPIO48
| GPIO11
|}

== 8. USER Virtual Channel ==

如果客户需要在 host 与 device 之间传输私有消息，可使用 <code>USER virtual channel</code>。

说明：

* <code>USER</code> 通道和控制通道是并列关系
* 它不是独立物理接口，而是承载在当前 host link 上的逻辑通道

device 侧头文件：

* <code>components/net/nethub/include/nethub_vchan.h</code>

host 侧头文件：

* <code>bsp/common/msg_router/linux_host/userspace/nethub/virtualchan/nethub_vchan.h</code>

更多说明见 [[NetHubVirtualChannel|NetHub USER Virtual Channel]]。

== 9. 常见问题 ==

=== 9.1 <code>bflbwifid</code> 启动失败 ===

优先检查：

* device 和 host 的控制 backend 是否匹配
* <code>/dev/ttyAT0</code> 是否存在
* <code>mr_sdio.ko</code> 是否已经成功加载
* SDIO 硬件链路是否正常

=== 9.2 <code>connect_ap</code> 成功但 host 没有网络 ===

优先检查：

* <code>status</code> 是否已经进入 <code>GOTIP</code>
* <code>mr_eth0</code> 是否已经获取地址
* 系统里的 <code>NetworkManager</code>、<code>dhcpcd</code> 等服务是否覆盖了 NetHub 配置

说明：

* <code>build.sh</code> 默认以 <code>ENABLE_NETIF_AUTO_CONFIG=1</code> 编译 userspace
* device 上报 <code>GOTIP</code> 后，host 会自动配置 <code>mr_eth0</code> 的 IP、网关和 DNS

=== 9.3 <code>build.sh unload</code> 提示模块被占用 ===

优先确认：

* 是否还有 <code>bflbwifid</code> 正在运行
* 是否还有 <code>nethub_vchan_app</code> 正在运行

通常直接执行：

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

脚本会先尝试停止已知持有者，再执行卸载。

== 10. 延伸阅读 ==

* [[NetHubArchitecture|NetHub 架构说明]]
* [[NetHubVirtualChannel|NetHub USER Virtual Channel]]

NethubUserManual

2026-03-13T09:26:16Z

张良：张良移动页面NethubUserManual至NethubUserManual old

#重定向 [[NethubUserManual old]]

NethubUserManual old

2026-03-13T09:26:13Z

张良：张良移动页面NethubUserManual至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>

NetHub

2026-03-13T09:19:18Z

张良：创建页面，内容为“= NetHub = NetHub 用于把 device 侧的 Wi-Fi 能力桥接到 host。当前方案面向 <code>BL616 / BL618 / BL616CL / BL618DG</code> 这类 Wi-Fi SoC，当前推荐 bringup 路径为 <code>SDIO</code>。 == 页面导航 == * NetHub 快速上手 ** 面向首次 bringup 的客户 ** 说明 device/host 的关键选择、编译、加载、连接 AP 和常见问题 * NetHub 架构说明 ** 面向需要理解模…”

= NetHub =

NetHub 用于把 device 侧的 Wi-Fi 能力桥接到 host。

当前方案面向 <code>BL616 / BL618 / BL616CL / BL618DG</code> 这类 Wi-Fi SoC，当前推荐 bringup 路径为 <code>SDIO</code>。

== 页面导航 ==

* [[NetHubQuickBringup|NetHub 快速上手]]
** 面向首次 bringup 的客户
** 说明 device/host 的关键选择、编译、加载、连接 AP 和常见问题
* [[NetHubArchitecture|NetHub 架构说明]]
** 面向需要理解模块边界和 API 的开发者
** 说明 device/host 分层、公共接口和关键数据流
* [[NetHubVirtualChannel|NetHub USER Virtual Channel]]
** 面向需要传输私有数据的客户或应用开发者
** 说明 USER 通道的前提、API 和典型使用方式

== 当前结论 ==

* 当前主路径是 <code>SDIO</code>
* device 侧 Wi-Fi backend 支持 <code>fhost / wl80211</code>
* host 控制 backend 运行时二选一：<code>tty</code> 或 <code>vchan</code>
* 控制通道和 <code>USER virtual channel</code> 都承载在同一条 host link 上

== 仓内参考目录 ==

* <code>examples/wifi/nethub</code>
* <code>components/net/nethub</code>
* <code>bsp/common/msg_router/linux_host/userspace/nethub</code>

NetHubVirtualChannel

2026-03-13T09:17:57Z

张良：创建页面，内容为“= NetHub USER Virtual Channel = 本文档描述 NetHub 的 <code>USER virtual channel</code> 用法。 == 1. 概念 == <code>USER virtual channel</code> 是承载在当前 host link 上的逻辑消息通道。它不是独立物理接口，而是复用当前的 <code>SDIO / USB / SPI</code> 链路，把不同类型的数据拆分到不同逻辑通道中。当前常用类型： * <code>USER</code> ** 客户或应用层私有数据 * <code>AT</code> ** hos…”

= NetHub USER Virtual Channel =

本文档描述 NetHub 的 <code>USER virtual channel</code> 用法。

== 1. 概念 ==

<code>USER virtual channel</code> 是承载在当前 host link 上的逻辑消息通道。

它不是独立物理接口，而是复用当前的 <code>SDIO / USB / SPI</code> 链路，把不同类型的数据拆分到不同逻辑通道中。

当前常用类型：

* <code>USER</code>
** 客户或应用层私有数据
* <code>AT</code>
** host 控制面数据
* <code>SYSTEM</code>
** 系统内部协调消息

客户集成时，通常只需要关注 <code>USER</code> 类型。

== 2. bringup 前提 ==

使用前建议确认：

* device 侧已编入 <code>CONFIG_NETHUB=y</code>
* device 侧已编入 <code>CONFIG_MR_VIRTUALCHAN=y</code>
* host 侧已经加载 <code>mr_sdio.ko</code>
* host 与 device 的底层链路已经正常工作

补充说明：

* <code>USER</code> 通道和控制通道是并列关系
* 如果 host 控制面本身走 <code>vchan</code>，它使用的是 <code>AT</code> 类型
* 客户私有消息建议固定使用 <code>USER</code> 类型

== 3. Device 侧接口 ==

头文件：

* <code>components/net/nethub/include/nethub_vchan.h</code>

常用接口：

<syntaxhighlight lang="c">
int nethub_vchan_user_send(const void *data, uint16_t len);
int nethub_vchan_user_recv_register(nethub_vchan_recv_cb_t recv_cb, void *cb_arg);
</syntaxhighlight>

== 4. Host 侧接口 ==

头文件：

* <code>bsp/common/msg_router/linux_host/userspace/nethub/virtualchan/nethub_vchan.h</code>

=== 4.1 初始化与清理 ===

<syntaxhighlight lang="c">
int nethub_vchan_init(void);
int nethub_vchan_deinit(void);
</syntaxhighlight>

=== 4.2 USER 通道 ===

<syntaxhighlight lang="c">
typedef void (*nethub_vchan_recv_callback_t)(const void *data, size_t len);

int nethub_vchan_user_send(const void *data, size_t len);
int nethub_vchan_user_register_callback(nethub_vchan_recv_callback_t callback);
</syntaxhighlight>

=== 4.3 可选状态查询 ===

如果需要判断当前 virtual channel 是否 ready，可选使用：

<syntaxhighlight lang="c">
typedef struct {
nethub_vchan_link_state_t link_state;
nethub_vchan_host_state_t host_state;
} nethub_vchan_state_snapshot_t;

int nethub_vchan_get_state_snapshot(nethub_vchan_state_snapshot_t *snapshot);
</syntaxhighlight>

常用判断：

* <code>link_state == NETHUB_VCHAN_LINK_UP</code>
** 表示链路已可收发
* <code>host_state == NETHUB_VCHAN_HOST_STATE_DEVICE_RUN</code>
** 表示 host 侧已经和 device 完成握手

=== 4.4 可选链路事件回调 ===

如果应用希望在链路 up/down 时被动收到通知，可选注册：

<syntaxhighlight lang="c">
int nethub_vchan_register_link_event_callback(
nethub_vchan_link_event_callback_t callback,
void *user_data);
</syntaxhighlight>

== 5. 典型使用顺序 ==

# <code>nethub_vchan_init()</code>
# <code>nethub_vchan_user_register_callback()</code>
# <code>nethub_vchan_user_send()</code>
# 使用完成后调用 <code>nethub_vchan_deinit()</code>

示例：

<syntaxhighlight lang="c">
#include <stdio.h>
#include <string.h>

#include "nethub_vchan.h"

static void user_rx_cb(const void *data, size_t len)
{
printf("recv USER data: %.*s\n", (int)len, (const char *)data);
}

int main(void)
{
const char *msg = "hello from host";

if (nethub_vchan_init() != 0) {
return -1;
}

nethub_vchan_user_register_callback(user_rx_cb);
nethub_vchan_user_send(msg, strlen(msg));

nethub_vchan_deinit();
return 0;
}
</syntaxhighlight>

== 6. 限制与注意事项 ==

* 单次消息最大长度为 <code>1500</code> 字节
* <code>USER</code> 通道是消息包语义，不是流式字节流
* 使用前必须保证内核模块已经加载
* 如果 device 侧未启用 <code>CONFIG_MR_VIRTUALCHAN</code>，host 侧 <code>USER</code> 通道无法工作
* 如果同时使用 host 控制面和 <code>USER</code> 通道，客户私有数据不要复用 <code>AT</code> 类型

== 7. 相关页面 ==

* [[NetHubQuickBringup|NetHub 快速上手]]
* [[NetHubArchitecture|NetHub 架构说明]]

NetHubQuickBringup

2026-03-13T09:17:37Z

张良：创建页面，内容为“= NetHub 快速上手 = 本文档面向首次接触 NetHub 的客户，目标是尽快完成 device 和 host 的 bringup。 == 1. 方案概览 == * 当前主路径是 '''SDIO''' * device 侧运行 <code>Wi-Fi backend（fhost / wl80211）+ lwIP</code> * <code>nethub</code> 负责把 device 侧 Wi-Fi 能力桥接到 host * 控制通道和 <code>USER virtual channel</code> 都承载在同一条 host link 上当前生效目录： * device 侧 ** <code>compone…”

NetHubArchitecture

2026-03-13T09:16:39Z

张良：创建页面，内容为“= NetHub 架构说明 = 本文档面向需要理解模块边界和 API 的开发者。 == 1. 当前架构结论 == * 当前物理主路径是 '''SDIO''' * <code>USB / SPI</code> 目前仍保留 backend 骨架，不作为当前推荐 bringup 路径 * device 侧 Wi-Fi backend 支持 <code>fhost / wl80211</code> * 控制通道和 <code>USER virtual channel</code> 都是当前 host link 上的逻辑通道，不是独立物理接口 * host 控制 backend 运行…”

= NetHub 架构说明 =

本文档面向需要理解模块边界和 API 的开发者。

== 1. 当前架构结论 ==

* 当前物理主路径是 '''SDIO'''
* <code>USB / SPI</code> 目前仍保留 backend 骨架，不作为当前推荐 bringup 路径
* device 侧 Wi-Fi backend 支持 <code>fhost / wl80211</code>
* 控制通道和 <code>USER virtual channel</code> 都是当前 host link 上的逻辑通道，不是独立物理接口
* host 控制 backend 运行时二选一：<code>tty</code> 或 <code>vchan</code>

== 2. 功能视角架构图 ==

<syntaxhighlight lang="text">
Host
|
| network data / control payload / USER payload
v
Host Link (current main path: SDIO)
|
+-- Data Channel <--> nethub data bridge
+-- Control Channel <-> nethub ctrlpath <-> ATModule
+-- USER VCHAN <-> nethub vchan user path
|
v
Device
|
+-- nethub
| +-- data bridge
| +-- hard-coded Wi-Fi RX filter
| +-- active Wi-Fi selector (STA / AP)
| +-- ctrlpath
| +-- virtual channel
|
+-- Wi-Fi backend (fhost / wl80211) + lwIP
</syntaxhighlight>

从功能上看，<code>nethub</code> 主要做 4 件事：

* 维护 <code>Wi-Fi <-> HostLink</code> 的数据桥接
* 用硬编码 filter 决定报文是 <code>local</code>、<code>host</code>、还是 <code>both</code>
* 维护当前生效的 Wi-Fi 通道选择 <code>STA / AP</code>
* 在同一 host link 上提供控制通道和可选的 <code>USER virtual channel</code>

== 3. 技术/API 视角架构图 ==

<syntaxhighlight lang="text">
Application
|
+-- device public API
| +-- nethub.h
| +-- nethub_vchan.h
| +-- nethub_filter.h
|
+-- host public API
+-- bflbwifi.h
+-- virtualchan/nethub_vchan.h

device side
nethub_bootstrap()
-> profile select
-> endpoint register
-> hub lifecycle
-> Wi-Fi bridge
-> host backend (current main path: sdio)

host side
bflbwifictrl
-> IPC
-> bflbwifid
-> libbflbwifi
-> channel facade
+-- tty backend
+-- vchan backend
-> mr_sdio.ko + msg_router
</syntaxhighlight>

== 4. Device 侧公共接口 ==

头文件：

* <code>components/net/nethub/include/nethub.h</code>
* <code>components/net/nethub/include/nethub_vchan.h</code>
* <code>components/net/nethub/include/nethub_filter.h</code>

核心 API：

* <code>nethub_bootstrap()</code>
* <code>nethub_shutdown()</code>
* <code>nethub_get_status()</code>
* <code>nethub_set_active_wifi_channel()</code>
* <code>nethub_ctrl_upld_send()</code>
* <code>nethub_ctrl_dnld_register()</code>
* <code>nethub_vchan_user_send()</code>
* <code>nethub_vchan_user_recv_register()</code>
* <code>nethub_set_wifi_rx_filter()</code>

边界说明：

* <code>nethub_ctrl_*</code> 对应 host link 上的逻辑控制通道
* <code>nethub_vchan_user_*</code> 对应 host link 上的逻辑 <code>USER</code> 通道
* <code>nethub_set_wifi_rx_filter()</code> 用于完全替换内建 Wi-Fi RX filter，必须在 <code>nethub_bootstrap()</code> 前调用

== 5. Host 侧公共接口 ==

头文件：

* <code>bsp/common/msg_router/linux_host/userspace/nethub/bflbwifictrl/include/bflbwifi.h</code>
* <code>bsp/common/msg_router/linux_host/userspace/nethub/virtualchan/nethub_vchan.h</code>

控制面能力：

* <code>bflbwifi_ctrl_config_init()</code>
* <code>bflbwifi_ctrl_config_use_tty()</code>
* <code>bflbwifi_ctrl_config_use_vchan()</code>
* <code>bflbwifi_init_ex()</code>
* <code>bflbwifi_get_ctrl_status()</code>
* <code>bflbwifi_sta_connect()</code>
* <code>bflbwifi_sta_disconnect()</code>
* <code>bflbwifi_sta_get_state()</code>
* <code>bflbwifi_scan()</code>
* <code>bflbwifi_get_version()</code>
* <code>bflbwifi_restart()</code>
* <code>bflbwifi_ota_upgrade()</code>
* <code>bflbwifi_ap_start()</code>
* <code>bflbwifi_ap_stop()</code>

USER virtual channel 能力：

* <code>nethub_vchan_init()</code>
* <code>nethub_vchan_deinit()</code>
* <code>nethub_vchan_user_send()</code>
* <code>nethub_vchan_user_register_callback()</code>
* <code>nethub_vchan_get_state_snapshot()</code>
* <code>nethub_vchan_register_link_event_callback()</code>

== 6. 关键数据流 ==

=== 6.1 connect_ap ===

# 用户执行 <code>bflbwifictrl connect_ap <ssid> <password></code>
# CLI 通过本地 IPC 把命令发给 <code>bflbwifid</code>
# daemon 调用 <code>libbflbwifi</code>
# <code>libbflbwifi</code> 通过 <code>tty</code> 或 <code>vchan</code> backend 下发控制消息
# device 侧 <code>ATModule</code> 执行 Wi-Fi 控制
# device 侧上报响应和状态，host 侧刷新状态并返回结果

=== 6.2 数据面 ===

# host 网络流量进入 <code>mr_eth0</code>
# kernel/msg_router 通过 SDIO 与 device 通信
# device 侧 <code>nethub</code> 把 host data 转给当前 active Wi-Fi
# Wi-Fi RX 包经过 <code>nethub</code> filter 判断后，决定是本地处理、发给 host，还是两边都处理

== 7. 推荐阅读顺序 ==

* 首次 bringup：[[NetHubQuickBringup|NetHub 快速上手]]
* 理解 <code>USER</code> 通道：[[NetHubVirtualChannel|NetHub USER Virtual Channel]]

NethubUserManual old

2026-03-06T06:24:56Z

张良：

首页

2026-03-04T03:34:22Z

张良：

= Getting Started =

* [https://github.com/bouffalolab/bouffalo_sdk 如何获取SDK]
* [[如何在Ubuntu上搭建编译环境]]
* [[如何在Windows上搭建编译环境]]
* [[如何获取开发板]]
* [[烧录固件到开发板]]

= Bouffalo SDK =
'''BouffaloSDK''' 是 Bouffalo Lab 提供的 IOT 和 MCU 软件开发包，支持博流智能所有系列芯片，也是 '''bl_mcu_sdk''' 和 '''bl_iot_sdk''' 的结合体。

[[文件:BouffaloSDK.png|无框|600x600像素]]

= Peripherals =

{| border="0" cellpadding="10" width="100%"
|-
|width="32%" valign="top" align="left"|
*[[I2S]]
*[[I2C]]
*[[CVBS]]
*[[Watchdog]]
*[[GSM/GPRS]]
*[[Codec]]
*[[PCIe]]
*[[GPIO]]
*[[eMMC]]
|width="32%" valign="top" align="left"|
*[[WiFi]]
*[[LED]]
*[[Serial port]]
*[[PWM]]
*[[SPI]]
*[[USB OTG]]
*[[LCD]]
*[[CPU]]
*[[Network]]
|width="32%" valign="top" align="left"|
*[[Bluetooth]]
*[[HDMI]]
*[[Camera]]
*[[Memory]]
*[[RTC]]
*[[EEPROM]]
*[[MIPI-DSI]]
*[[NPU]]
*[[VPU]]
|}

= Products =
{| border="0" cellpadding="10" width="100%"
|-
|width="50%" valign="top" align="left"|
* [[BL602]]
* [[BL702]]
* [[BL618]]
* [[BL606P]]
|width="50%" valign="top" align="left"|
* [[BL702L]]
* [[BL616]]
|}

= Develop Boards =
* BL602EVB

= Application Notes =
* [[NethubUserManual]]
* [[BL616低功耗开发手册]]
* [[USB Wi-Fi用户手册]]

= Demos =

{| border="0" cellpadding="10" width="100%"
|-
|width="32%" valign="top" align="left"|
*[[Demo:FreeRTOS]]
* [[Demo:wifi sta]]
* [[Demo:boot2_isp]]
* [[Demo:helloworld]]
* [[Demo:smartconfig ble]]
|width="32%" valign="top" align="left"|
*[[Demo:DMA]]
* [[Demo:Btble]]
* [[Demo:coremark]]
* [[Demo:littlefs]]
* [[Demo:posix freertos]]
|width="32%" valign="top" align="left"|
*[[Demo:Flash]]
* [[Demo:Basical case]]
* [[Demo:dsp]]
* [[Demo:cks]]
|}

NethubUserManual old

2026-03-03T04:19:36Z

张良：

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

NethubUserManual old

2026-03-03T03:13:46Z

张良：撤销张良（讨论）的修订版本228

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

== 目录 ==

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

== 1. 系统架构 ==
[[文件:Arch_host_device.png|800px]]

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

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

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

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

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

== 2. 快速开始 ==

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

[[文件:Nethub_sdio_quickstart_demo.gif]]

=== 2.1 编译和加载内核模块 ===
<syntaxhighlight lang="bash">
cd nethub/
./build.sh build
sudo ./build.sh load
</syntaxhighlight>

=== 2.2 运行 WiFi 守护进程 ===
<syntaxhighlight lang="bash">
# 启动守护进程（默认使用 /dev/ttyAT0）
sudo ./output/bflbwifid -p /dev/ttyAT0

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

=== 2.3 使用 WiFi 控制工具 ===
<syntaxhighlight lang="bash">
# 扫描 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
</syntaxhighlight>

== 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 命令 ====
{| 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>
|查看固件版本
|}

=== 3.3 功能特性 ===

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

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

==== 修改代码后重新编译 ====
<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>

== 4. 常见问题 ==

=== 4.1 找不到串口设备 ===
<syntaxhighlight lang="bash">
# 查看可用串口
ls /dev/ttyACM* /dev/ttyUSB*

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

=== 4.2 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>

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

# 查看内核日志
dmesg -w

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

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

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