查看“︁NetHubQuickBringup”︁的源代码

= 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