查看“︁NetHubArchitecture”︁的源代码

= NetHub Architecture Guide =

This document is for developers who need to understand module boundaries and APIs.

== 1. Current Architecture Conclusions ==

* The current physical primary path is <code>SDIO</code>
* <code>USB / SPI</code> still keep backend skeletons and are not recommended bring-up paths for now
* The device-side Wi-Fi backend supports <code>fhost / wl80211</code>
* The control channel and <code>USER virtual channel</code> are logical channels on the current host link, not separate physical interfaces
* The host control backend is selected at runtime: <code>tty</code> or <code>vchan</code>

== 2. Functional Architecture Diagram ==

<pre>
flowchart LR
    Host["Host"]
    Link["Host Link
current main path: SDIO"]
    Data["Data Channel"]
    Ctrl["Control Channel"]
    User["USER VCHAN"]

    subgraph Device["Device"]
        subgraph Hub["nethub"]
            Bridge["data bridge"]
            Filter["hard-coded Wi-Fi RX filter"]
            Active["active Wi-Fi selector
STA / AP"]
            CtrlPath["ctrlpath"]
            Vchan["virtual channel"]
        end
        Wifi["Wi-Fi backend
fhost / wl80211 + lwIP"]
        AT["ATModule"]
    end

    Host --> Link
    Link --> Data
    Link --> Ctrl
    Link --> User

    Data --> Bridge
    Bridge --> Active
    Active --> Wifi
    Wifi --> Filter
    Filter --> Bridge

    Ctrl --> CtrlPath
    CtrlPath --> AT
    AT --> Wifi

    User --> Vchan
</pre>

From a functional view, <code>nethub</code> mainly does four things:

* maintain the <code>Wi-Fi &lt;-&gt; HostLink</code> data bridge
* use a hard-coded filter to decide whether a packet is <code>local</code>, <code>host</code>, or <code>both</code>
* maintain the currently active Wi-Fi channel, <code>STA / AP</code>
* provide a control channel and an optional <code>USER virtual channel</code> on the same host link

== 3. Technical / API Architecture Diagram ==

<pre>
flowchart TB
    App["Application"]

    subgraph DevicePublic["device public API"]
        DevAPI["nethub.h"]
        DevVchan["nethub_vchan.h"]
        DevFilter["nethub_filter.h"]
    end

    subgraph DeviceSide["device side"]
        Bootstrap["nethub_bootstrap()"]
        Profile["profile select"]
        Endpoint["endpoint register"]
        Hub["hub lifecycle"]
        WifiBridge["Wi-Fi bridge"]
        HostBackend["host backend
current main path: sdio"]
    end

    subgraph HostPublic["host public API"]
        HostAPI["bflbwifi.h"]
        HostVchan["virtualchan/nethub_vchan.h"]
    end

    subgraph HostSide["host side"]
        CLI["bflbwifictrl"]
        IPC["local IPC"]
        Daemon["bflbwifid"]
        Lib["libbflbwifi"]
        Facade["channel facade"]
        TTY["tty backend"]
        VCHAN["vchan backend"]
        Kernel["mr_sdio.ko + msg_router"]
    end

    App --> DevAPI
    App --> DevVchan
    App --> DevFilter
    App --> HostAPI
    App --> HostVchan

    DevAPI --> Bootstrap
    DevVchan --> HostBackend
    DevFilter --> WifiBridge
    Bootstrap --> Profile
    Bootstrap --> Endpoint
    Bootstrap --> Hub
    Hub --> WifiBridge
    Endpoint --> HostBackend

    CLI --> IPC
    IPC --> Daemon
    Daemon --> Lib
    Lib --> Facade
    Facade --> TTY
    Facade --> VCHAN
    TTY --> Kernel
    VCHAN --> Kernel
    HostVchan --> Kernel
</pre>

== 4. device-side Public Interfaces ==

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>

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

Boundary notes:

* <code>nethub_ctrl_*</code> maps to the logical control channel on the host link
* <code>nethub_vchan_user_*</code> maps to the logical <code>USER</code> channel on the host link
* <code>nethub_set_wifi_rx_filter()</code> fully replaces the built-in Wi-Fi RX filter and must be called before <code>nethub_bootstrap()</code>

== 5. host-side Public Interfaces ==

Headers:

* <code>bsp/common/msg_router/linux_host/userspace/nethub/bflbwifictrl/include/bflbwifi.h</code>
* <code>bsp/common/msg_router/linux_host/userspace/nethub/virtualchan/nethub_vchan.h</code>

Control-plane capabilities:

* <code>bflbwifi_ctrl_config_init()</code>
* <code>bflbwifi_ctrl_config_use_tty()</code>
* <code>bflbwifi_ctrl_config_use_vchan()</code>
* <code>bflbwifi_init_ex()</code>
* <code>bflbwifi_get_ctrl_status()</code>
* <code>bflbwifi_sta_connect()</code>
* <code>bflbwifi_sta_disconnect()</code>
* <code>bflbwifi_sta_get_state()</code>
* <code>bflbwifi_scan()</code>
* <code>bflbwifi_get_version()</code>
* <code>bflbwifi_restart()</code>
* <code>bflbwifi_ota_upgrade()</code>
* <code>bflbwifi_ap_start()</code>
* <code>bflbwifi_ap_stop()</code>

USER virtual channel capabilities:

* <code>nethub_vchan_init()</code>
* <code>nethub_vchan_deinit()</code>
* <code>nethub_vchan_user_send()</code>
* <code>nethub_vchan_user_register_callback()</code>
* <code>nethub_vchan_get_state_snapshot()</code>
* <code>nethub_vchan_register_link_event_callback()</code>

== 6. Key Data Flows ==

=== 6.1 <code>connect_ap</code> ===

# The user runs <code>bflbwifictrl connect_ap &lt;ssid&gt; &lt;password&gt;</code>
# The CLI sends the command to <code>bflbwifid</code> through local IPC
# The daemon calls <code>libbflbwifi</code>
# <code>libbflbwifi</code> sends control messages through the <code>tty</code> or <code>vchan</code> backend
# The device-side <code>ATModule</code> performs the Wi-Fi control operation
# The device reports responses and state updates, and the host refreshes the state and returns the result

=== 6.2 Data Plane ===

# Host network traffic enters <code>mr_eth0</code>
# The kernel / <code>msg_router</code> communicates with the device over SDIO
# Device-side <code>nethub</code> forwards host data to the currently active Wi-Fi
# After Wi-Fi RX packets pass through the <code>nethub</code> filter, they are handled locally, forwarded to the host, or both

== 7. Recommended Reading Order ==

* First-time bring-up: [[NetHubQuickBringup|NetHubQuickBringup.md]]
* Understanding the <code>USER</code> channel: [[NetHubVirtualChannel|NetHubVirtualChannel.md]]
* Top-level entry: [[NetHub|NetHub.md]]