查看“︁NetHubArchitecture”︁的源代码

= NetHub Architecture =

This document summarizes the current NetHub architecture across the device-side module, the optional host control stack, and the current support limits.

== 1. High-Level Model ==

NetHub runs on the device and bridges already-available Wi-Fi capability onto one selected host-link profile.

<syntaxhighlight lang="text">
Wi-Fi backend + lwIP
       |
       v
     nethub
  +-----------+
  | data-path |
  | filter    |
  | ctrlpath  |
  | vchan     |
  +-----------+
       |
       v
host-link profile
(SDIO / USB / SPI)
</syntaxhighlight>

Important boundary:

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

== 2. Current Support Matrix ==

{| class="wikitable"
|-
! Area !! SDIO !! USB !! SPI
|-
| Device-side profile || yes || yes || yes
|-
| Device-side data-path || yes || yes, through <code>USB ECM</code> || no
|-
| Device-side control transport plumbing || yes || yes, through <code>USB ACM</code> || no
|-
| Current in-tree host Linux reference path || yes || not yet the main reference path || no
|-
| End-to-end USER virtual channel || yes || not yet aligned in-tree || no
|-
| Current default interface || yes || no || no
|}

== 3. Device-Side Layers ==

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

Internal layers:

* <code>bootstrap/</code>
* <code>core/</code>
* <code>profile/</code>
* <code>backend/wifi/</code>
* <code>backend/host/sdio/</code>
* <code>backend/host/usb/</code>
* <code>backend/host/spi/</code>

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

== 4. Data-Path ==

The data-path is the main NetHub function.

<syntaxhighlight lang="text">
host payload -> host-link backend -> nethub -> active Wi-Fi endpoint
Wi-Fi RX     -> nethub filter     -> local / host / both
</syntaxhighlight>

Device-side Wi-Fi is already owned by the Wi-Fi backend. NetHub mainly wires the host-link side to that Wi-Fi backend.

== 5. Control Path ==

NetHub exposes a stable control-path facade:

<syntaxhighlight lang="c">
int nethub_ctrl_upld_send(uint8_t *data_buff, uint32_t data_size);
int nethub_ctrl_dnld_register(nethub_ctrl_rx_cb_t dnld_cb, void *cbpri_arg);
</syntaxhighlight>

That facade is implemented per profile.

Current interpretation:

* <code>SDIO</code>: implemented in-tree
* <code>USB</code>: device-side ACM transport plumbing implemented
* <code>SPI</code>: not implemented

Main build-time switches related to this area:

* <code>CONFIG_NETHUB_CTRLCHANNEL_USE_ATMODULE=y</code>
** the example enables <code>ATModule</code> plus host <code>bflbwifid / bflbwifictrl</code>
* <code>CONFIG_NETHUB_CTRLCHANNEL_USE_ATMODULE=n</code>
** <code>ATModule</code> does not participate in the build

<code>CONFIG_NETHUB_AT_USE_VCHAN</code> should be documented carefully as an example or legacy SDIO control-path convention, not as a finished transport-wide selector.

== 6. Virtual Channel ==

NetHub also exposes a logical virtual-channel API:

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

API intent:

* stable logical message API across host-link types

Current backend reality:

* the in-tree implementation is still SDIO-backed
* the host userspace <code>nethub_vchan</code> library is also SDIO-based today
* therefore the current end-to-end USER virtual-channel story follows the default <code>SDIO</code> interface

== 7. Host-Side Optional Stack ==

When the optional AT control solution is used, the typical host-side stack is:

<syntaxhighlight lang="text">
bflbwifictrl -> bflbwifid -> libbflbwifi -> tty or vchan backend
</syntaxhighlight>

Notes:

* this stack is not required for NetHub data-path-only products
* the in-tree host Linux reference stack is still centered on the SDIO path

== 8. Low-Power Scope ==

Current low-power support is <code>BL618DG</code> only.

The example configuration automatically disables <code>CONFIG_NETHUB_LOWPOWER_ENABLE</code> on other chips.

== 9. Recommended Reading ==

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