查看“︁NetHubQuickBringup”︁的源代码

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