查看“︁NetHubQuickBringup”︁的源代码

= NetHub Quick Start =

This document is for customers using NetHub for the first time. The goal is to get you to the currently supported bring-up path as quickly as possible.

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

== 1. Start with the Current Support Matrix ==

{| class="wikitable"
|-
! Item !! Current status
|-
| Recommended end-to-end reference path || <code>SDIO</code>
|-
| USB profile || device-side backend implemented with <code>USB ECM + USB ACM</code>
|-
| SPI profile || not implemented
|-
| USER virtual channel || current in-tree end-to-end path is <code>SDIO</code>
|-
| Optional AT control solution || available, but not required for data-only use cases
|-
| 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 new USB device-side backend, focus on the device profile and USB descriptors first
* do not plan on <code>SPI</code> bring-up yet

== 2. Decide Whether You Need Only Data or Data Plus Control ==

NetHub core always focuses on the data plane first.

* data-only products
** keep <code>nethub</code>
** do not depend on <code>ATModule</code>
** host users simply use the exposed netdev path
* data plus AT-style control products
** optionally enable the example composition built around <code>ATModule + bflbwifid + bflbwifictrl</code>

The important boundary is:

* <code>nethub</code> core does not directly depend on <code>ATModule</code>
* <code>ATModule</code> is an optional example control consumer of the NetHub control-path facade

== 3. Choose the Host-Link Profile ==

The profile is selected at build time through exactly one <code>CONFIG_NETHUB_PROFILE_*</code> option.

=== 3.1 SDIO ===

Recommended today.

What you get:

* current in-tree reference data path
* current in-tree host Linux stack
* current in-tree USER virtual-channel path

=== 3.2 USB ===

Use this when you specifically want the device-side USB backend.

Current device-side behavior:

* data path through <code>USB CDC ECM</code>
* control transport plumbing through <code>USB CDC ACM</code>

Current limitation:

* the in-tree host Linux docs and <code>nethub_vchan</code> wrapper are still centered on the SDIO reference path

=== 3.3 SPI ===

Not implemented yet.

== 4. Choose the Wi-Fi Backend ==

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

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

== 6. Important Configuration Switches ==

Main configuration file:

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

Important switches:

* <code>CONFIG_NETHUB=y</code>
* <code>CONFIG_NETHUB_PROFILE_SDIO=y</code>
* <code>CONFIG_NETHUB_PROFILE_USB=y</code>
* <code>CONFIG_NETHUB_PROFILE_SPI=y</code>
** choose exactly one profile per build
* <code>CONFIG_NETHUB_CTRLCHANNEL_USE_ATMODULE=y</code>
** enable the optional example AT control solution
* <code>CONFIG_MR_VIRTUALCHAN=y</code>
** required for the current in-tree SDIO virtual-channel path
* <code>CONFIG_NETHUB_LOWPOWER_ENABLE=y</code>
** currently meaningful only on <code>BL618DG</code>

About <code>CONFIG_NETHUB_AT_USE_VCHAN</code>:

* it still exists in the example configuration
* it is best treated as an example or legacy SDIO control-path switch
* do not document it as the core selector for all NetHub interfaces

Current default example facts:

* <code>CONFIG_NETHUB_PROFILE_SDIO=y</code>
* <code>CONFIG_NETHUB_PROFILE_USB=n</code>
* <code>CONFIG_NETHUB_CTRLCHANNEL_USE_ATMODULE=y</code>
* <code>CONFIG_MR_VIRTUALCHAN=y</code>
* <code>CONFIG_NETHUB_AT_USE_VCHAN=n</code>
* <code>CONFIG_MR_TTY=n</code>

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

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

=== 7.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 is the current 4-bit SDIO reference wiring used by the NetHub SDIO path
* the BSP configures these pins with `GPIO_FUNC_SDH | GPIO_ALTERNATE | GPIO_PULLUP | GPIO_SMT_EN | GPIO_DRV_1`
* if you are doing first bring-up, use this exact mapping first before trying a custom board layout

=== 7.2 Default USB Pins ===

The current USB profile 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/package documentation
* for the current in-tree NetHub reference flow, USB is device-side bring-up work, while the full host reference stack is still centered on SDIO

== 8. Host Bring-Up Guidance ==

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

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

Today that host stack is primarily the <code>SDIO</code> reference flow.

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

== 9. USER Virtual Channel Guidance ==

If you need private application messages between host and device:

* device API: <code>components/net/nethub/include/nethub_vchan.h</code>
* host API: <code>bsp/common/msg_router/linux_host/userspace/nethub/virtualchan/nethub_vchan.h</code>

Current reality:

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

== 10. Low-Power Note ==

<code>CONFIG_NETHUB_LOWPOWER_ENABLE</code> is currently supported only on <code>BL618DG</code>. The example configuration automatically disables it on other chips.

== 11. Where to Go Next ==

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