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.

Wi-Fi backend + lwIP
       |
       v
     nethub
  +-----------+
  | data path |
  | filter    |
  | ctrlpath  |
  | vchan     |
  +-----------+
       |
       v
host-link profile
(SDIO / USB / SPI)

Important boundary:

• nethub core does not directly depend on ATModule
• ATModule is an optional example consumer of the NetHub control path

2. Current Support Matrix

Area	SDIO	USB	SPI
Device-side profile	yes	yes	yes
Device-side data path	yes	yes, through USB ECM	no
Device-side control transport plumbing	yes	yes, through USB ACM	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
Recommended today	yes	evaluation only	no

3. Device-Side Layers

Public headers:

• components/net/nethub/include/nethub.h
• components/net/nethub/include/nethub_vchan.h
• components/net/nethub/include/nethub_filter.h

Internal layers:

• bootstrap/
• core/
• profile/
• backend/wifi/
• backend/host/sdio/
• backend/host/usb/
• backend/host/spi/

Main public APIs:

• nethub_bootstrap()
• nethub_shutdown()
• nethub_get_status()
• nethub_set_active_wifi_channel()
• nethub_ctrl_upld_send()
• nethub_ctrl_dnld_register()
• nethub_vchan_user_send()
• nethub_vchan_user_recv_register()
• nethub_set_wifi_rx_filter()

4. Data Plane

The data plane is the main NetHub function.

host payload -> host-link backend -> nethub -> active Wi-Fi endpoint
Wi-Fi RX     -> nethub filter     -> local / host / both

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:

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

That facade is implemented per profile.

Current interpretation:

• SDIO: implemented in-tree
• USB: device-side ACM transport plumbing implemented
• SPI: not implemented

Optional AT solution:

• CONFIG_NETHUB_CTRLCHANNEL_USE_ATMODULE=y
  • example enables ATModule plus host bflbwifid / bflbwifictrl
• CONFIG_NETHUB_CTRLCHANNEL_USE_ATMODULE=n
  • data-plane-only products can omit the example control chain

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

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

API intent:

• stable logical message API across host-link types

Current backend reality:

• the in-tree implementation is still SDIO-backed
• the host userspace nethub_vchan library is also SDIO-based today
• therefore the current end-to-end USER virtual-channel story is the SDIO reference path

7. Host-Side Optional Stack

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

bflbwifictrl -> bflbwifid -> libbflbwifi -> tty or vchan backend

Notes:

• this is not required for NetHub data-plane-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 BL618DG only.

The example configuration automatically disables CONFIG_NETHUB_LOWPOWER_ENABLE on other chips.

9. Recommended Reading

• NetHub.md
• NetHubQuickBringup.md
• NetHubVirtualChannel.md