查看“︁NetHubQuickBringup”︁的源代码

= NetHub Quick Start =

This document is for customers using NetHub for the first time. The goal is to get you to the current default interface as quickly as possible.

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

== 1. Current Support Matrix ==

{| class="wikitable"
|-
! Item !! Current status
|-
| Default interface || <code>SDIO</code>
|-
| USB interface || device-side backend implemented with <code>USB ECM + USB ACM</code>
|-
| SPI interface || not implemented
|-
| USER virtual channel || default interface is <code>SDIO</code>
|-
| Optional AT control solution || available, but not mandatory
|-
| Low power || currently <code>BL618DG</code> only
|}

Read this table literally:

* if you want the shortest successful path today, choose <code>SDIO</code>
* if you are evaluating the USB interface, focus on the device-side backend and USB descriptors first
* do not plan on <code>SPI</code> bring-up yet

== 2. Main Configuration Switches ==

For most users, the main configuration changes are these:

<syntaxhighlight lang="makefile">
CONFIG_NETHUB_CTRLCHANNEL_USE_ATMODULE =y
CONFIG_NETHUB_LOWPOWER_ENABLE          =y
CONFIG_NETHUB_PROFILE_USB              =n
CONFIG_NETHUB_PROFILE_SDIO             =y
</syntaxhighlight>

Notes:

* the config symbol names still use <code>PROFILE</code>, but they select the active host interface
* set <code>CONFIG_NETHUB_PROFILE_SDIO=y</code> for the current default interface
* set <code>CONFIG_NETHUB_PROFILE_USB=y</code> only when you want to evaluate the USB interface
* <code>CONFIG_NETHUB_CTRLCHANNEL_USE_ATMODULE=n</code> means <code>ATModule</code> will not participate in the build
* <code>CONFIG_NETHUB_LOWPOWER_ENABLE=y</code> is currently meaningful only on <code>BL618DG</code>

Additional current default facts in <code>examples/wifi/nethub/defconfig</code>:

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

== 3. Wi-Fi Backend Selection ==

Default configuration:

* <code>CONFIG_WL80211</code> disabled
* <code>fhost</code> selected

If you want <code>wl80211</code>, enable this 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
* current NetHub supports both device-side Wi-Fi backends

== 4. Device Build and Flash ==

Build:

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

== 5. Hardware Interface Pins ==

The pin tables below are the current default mappings used by the in-tree BSP board helpers.

Reference sources in the repository:

* <code>bsp/board/bl616dk/board_gpio.c</code>
* <code>bsp/board/bl616cldk/board_gpio.c</code>
* <code>bsp/board/bl618dgdk/board_gpio.c</code>

=== 5.1 Default SDIO Pins ===

These are the current <code>board_sdh_gpio_init()</code> mappings used by the BSP.

{| class="wikitable"
|-
! Pin Function !! BL616 / BL618 (<code>bl616dk</code>) !! BL618DG (<code>bl618dgdk</code>) !! BL616CL (<code>bl616cldk</code>)
|-
| <code>SDIO_DAT2</code> || <code>GPIO10</code> || <code>GPIO43</code> || <code>GPIO6</code>
|-
| <code>SDIO_DAT3</code> || <code>GPIO11</code> || <code>GPIO44</code> || <code>GPIO7</code>
|-
| <code>SDIO_CMD</code> || <code>GPIO12</code> || <code>GPIO45</code> || <code>GPIO8</code>
|-
| <code>SDIO_CLK</code> || <code>GPIO13</code> || <code>GPIO46</code> || <code>GPIO9</code>
|-
| <code>SDIO_DAT0</code> || <code>GPIO14</code> || <code>GPIO47</code> || <code>GPIO10</code>
|-
| <code>SDIO_DAT1</code> || <code>GPIO15</code> || <code>GPIO48</code> || <code>GPIO11</code>
|}

Notes:

* this table shows the current default 4-bit SDIO wiring used by the NetHub SDIO data-path
* 1-line mode is also supported; if you use 1-line mode, keep <code>CMD</code>, <code>CLK</code>, and <code>DAT0</code> first
* the BSP configures these pins with <code>GPIO_FUNC_SDH | GPIO_ALTERNATE | GPIO_PULLUP | GPIO_SMT_EN | GPIO_DRV_1</code>

=== 5.2 Default USB Pins ===

The current USB interface uses the board's default USB differential pair.

{| class="wikitable"
|-
! Chip / Board family !! Default USB pins in current BSP !! Current BSP behavior !! Notes
|-
| BL616 / BL618 (<code>bl616dk</code>) || board default USB port path || current BSP enables USB clock in <code>board.c</code>, but does not expose a dedicated <code>board_usb_gpio_init()</code> helper || treat this as the board's fixed default USB routing in the current example
|-
| BL616CL (<code>bl616cldk</code>) || <code>GPIO32</code>, <code>GPIO33</code> || <code>board_usb_gpio_init()</code> configures the pair as analog pins || current BSP documents the pair, not separate <code>DP</code> / <code>DM</code> labels
|-
| BL618DG (<code>bl618dgdk</code>) || <code>GPIO40</code>, <code>GPIO41</code> || <code>board_usb_gpio_init()</code> configures the pair as analog pins || current BSP documents the pair, not separate <code>DP</code> / <code>DM</code> labels
|}

Notes:

* for <code>BL616CL</code> and <code>BL618DG</code>, the BSP helper only tells us the USB pair used by the board, not which pin is <code>D+</code> and which pin is <code>D-</code>
* if you are wiring a custom board and need explicit <code>DP</code> / <code>DM</code> polarity, confirm it from the board schematic or chip or package documentation

== 6. Host Bring-Up Guidance ==

For the current in-tree host Linux stack, use:

* <code>bsp/common/msg_router/linux_host/userspace/nethub/README.md</code>

Today that host stack follows the default <code>SDIO</code> interface.

For USB projects, keep expectations aligned with current code status:

* device-side <code>ECM + ACM</code> backend exists
* host-side transport flattening into the same <code>nethub_vchan</code> behavior as SDIO is not fully documented or aligned in-tree yet

== 7. USER Virtual Channel ==

If you need private application messages between host and device, read:

* [[NetHubVirtualChannel|NetHubVirtualChannel.md]]

Current implementation:

* the current in-tree end-to-end USER virtual channel follows the default <code>SDIO</code> interface
* the public device API is transport-neutral by design
* the in-tree implementation behind it is still SDIO-backed today

== 8. Low-Power Note ==

Low power is currently supported only on <code>BL618DG</code>.

For other chips, <code>examples/wifi/nethub/defconfig</code> automatically turns <code>CONFIG_NETHUB_LOWPOWER_ENABLE</code> off. In practice, you normally keep this option enabled only for <code>BL618DG</code> builds.

== 9. Common Questions ==

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

This question is relevant only when you use the optional host control stack.

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

=== 9.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>

=== 9.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

=== 9.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>

The macro is:

<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

=== 9.5 Can the Host Expose <code>AP</code> and <code>STA</code> at the Same Time? ===

No. Due to the current software implementation, this is not supported yet.

Current behavior:

* the host side exposes only one virtual interface at a time
* the default active Wi-Fi channel is <code>STA</code>

If you need to switch between <code>AP</code> and <code>STA</code>, call <code>nethub_set_active_wifi_channel()</code> directly:

* use <code>NETHUB_CHANNEL_WIFI_AP</code> to switch to <code>AP</code>
* use <code>NETHUB_CHANNEL_WIFI_STA</code> to switch to <code>STA</code>
* the default value is <code>NETHUB_CHANNEL_WIFI_STA</code>

=== 9.6 What Should the Host Side Handle When <code>CONFIG_NETHUB_CTRLCHANNEL_USE_ATMODULE=n</code>? ===

When <code>CONFIG_NETHUB_CTRLCHANNEL_USE_ATMODULE=n</code>, the optional AT-based host control solution is not part of the build.

What you need to handle yourself:

* you need your own private control path to carry required messages between host and device
* this includes, but is not limited to, host netdev link-up handling
* this also includes host-side IP address and netmask configuration

In short, NetHub still provides the data-path, but the host-side control workflow becomes your own responsibility.

=== 9.7 Why Does <code>ifconfig</code> Not Show the Virtual Interface? ===

Check first:

* use a command such as <code>ifconfig -a</code> to list interfaces that are currently down
* find the virtual interface and bring it up manually, for example: <code>sudo ifconfig mr_eth0 up</code>

Notes:

* some Linux systems, including newer Raspberry Pi OS releases, run <code>NetworkManager</code> by default
* because of that, the exact behavior depends on your host environment and may need host-specific analysis

=== 9.8 For Dual-Stack Traffic, Can Users Customize the Filter? Is There Any Difference Between USB and SDIO? ===

Yes. The default configuration already covers most scenarios, but users can still customize the Wi-Fi RX filter if needed.

Important points:

* the filter is not bound to one interface type; there is no special filter split between <code>USB</code> and <code>SDIO</code>
* the current built-in policy is shared by both <code>SDIO</code> and <code>USB</code>
* you can refer to <code>components/net/nethub/profile/nh_profile_sdio.c</code> and <code>components/net/nethub/profile/nh_profile_usb.c</code>; both use the same built-in Wi-Fi RX policy

Default built-in policy reference:

* <code>components/net/nethub/profile/nh_profile_builtin.c</code>
* <code>NH_FILTER_MATCH_8021X</code>: handled locally and not delivered to the host
* <code>NH_FILTER_MATCH_ARP</code>: handled locally and also delivered to the host
* <code>NH_FILTER_MATCH_DHCP4</code>: handled locally
* <code>NH_FILTER_MATCH_ICMP4</code>: handled locally
* other packets: delivered to the host by default

If the default policy does not match your requirement:

* you can call <code>nethub_set_wifi_rx_filter(nethub_wifi_rx_filter_cb_t filter_cb, void *user_ctx)</code> from <code>components/net/nethub/include/nethub_filter.h</code>
* for the callback behavior, refer to <code>nh_filter_apply_policy()</code> in <code>components/net/nethub/core/nh_filter.c</code>
* if you need a more complex policy, it is also fine to contact us directly

=== 9.9 Why Can the Host Not Ping Other Devices on the Same LAN? ===

This is expected with the current default policy.

Reason:

* <code>ICMP</code> packets are handled locally on the device side by default
* they are not delivered to the host by default

So, by default:

* other LAN devices pinging the device can work
* host-side ping visibility to other LAN devices is not part of the default behavior

== 10. Where to Go Next ==

* overall entry: [[NetHub|NetHub.md]]
* architecture: [[NetHubArchitecture|NetHubArchitecture.md]]
* USER virtual channel: [[NetHubVirtualChannel|NetHubVirtualChannel.md]]