diff --git a/README.md b/README.md index 80983fd..311376e 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,12 @@ Enables Espressif WiFi capabilities on remote targets (without native WiFi suppo This repository contains components and utilities related to esp-wifi-remote. +## Overview + +esp-wifi-remote provides transparent WiFi connectivity for ESP chipsets through external hardware, maintaining full compatibility with the standard `esp_wifi` API. This enables WiFi functionality on ESP32-P4, ESP32-H2, and other WiFi-less chipsets by routing API calls to a connected WiFi-capable device. + +The solution supports multiple backend communication protocols and can also provide additional WiFi interfaces on WiFi-capable ESP32 chips for applications requiring dual wireless connectivity. + ## esp-wifi-remote [![Component Registry](https://components.espressif.com/components/espressif/esp_wifi_remote/badge.svg)](https://components.espressif.com/components/espressif/esp_wifi_remote) @@ -21,3 +27,7 @@ This repository contains components and utilities related to esp-wifi-remote. [![Component Registry](https://components.espressif.com/components/espressif/wifi_remote_over_at/badge.svg)](https://components.espressif.com/components/espressif/wifi_remote_over_at) [wifi_remote_over_at](https://github.com/espressif/esp-wifi-remote/tree/main/components/wifi_remote_over_at/README.md) + +## esp-hosted + +The recommended backend solution for esp-wifi-remote is [esp-hosted](https://github.com/espressif/esp-hosted), providing optimal performance (up to 50Mbps TCP throughput), mature integration, and comprehensive support for ESP32-based host-slave communication. diff --git a/components/esp_wifi_remote/.cz.yaml b/components/esp_wifi_remote/.cz.yaml index 9893ad6..00cc9a4 100644 --- a/components/esp_wifi_remote/.cz.yaml +++ b/components/esp_wifi_remote/.cz.yaml @@ -3,6 +3,6 @@ commitizen: bump_message: 'bump(wifi_remote): $current_version -> $new_version' pre_bump_hooks: python ../../ci/changelog.py esp_wifi_remote tag_format: wifi_remote-v$version - version: 0.16.1 + version: 0.16.2 version_files: - idf_component.yml diff --git a/components/esp_wifi_remote/CHANGELOG.md b/components/esp_wifi_remote/CHANGELOG.md index 0ebfbaa..177a89b 100644 --- a/components/esp_wifi_remote/CHANGELOG.md +++ b/components/esp_wifi_remote/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [0.16.2](https://github.com/espressif/esp-wifi-remote/commits/wifi_remote-v0.16.2) + +### Bug Fixes + +- Update READMEs with latest description ([798e6f0](https://github.com/espressif/esp-wifi-remote/commit/798e6f0)) +- Minor update per v5.4 changes ([7df45ba](https://github.com/espressif/esp-wifi-remote/commit/7df45ba)) + ## [0.16.1](https://github.com/espressif/esp-wifi-remote/commits/wifi_remote-v0.16.1) ### Bug Fixes diff --git a/components/esp_wifi_remote/README.md b/components/esp_wifi_remote/README.md index f15c9db..f3ad33f 100644 --- a/components/esp_wifi_remote/README.md +++ b/components/esp_wifi_remote/README.md @@ -2,9 +2,13 @@ [![Component Registry](https://components.espressif.com/components/espressif/esp_wifi_remote/badge.svg)](https://components.espressif.com/components/espressif/esp_wifi_remote) -The `esp_wifi_remote` component is designed to extend WiFi functionality to ESP chipsets that lack native WiFi support. By simply adding a dependency to this component from your project, you gain access to WiFi capabilities via the WiFi-remote menuconfig and standard `esp_wifi` interface. +The `esp_wifi_remote` component provides transparent WiFi connectivity for ESP chipsets through external hardware, maintaining full `esp_wifi` API compatibility. -Moreover, `esp_wifi_remote` can be utilized on ESP chipsets that do support native WiFi, providing an additional WiFi interface through the `esp_wifi_remote` API. +### Use Cases + +**Non-WiFi ESP Chips**: Enables WiFi functionality on ESP32-P4, ESP32-H2 and other WiFi-less chipsets by routing `esp_wifi` calls to external WiFi hardware. + +**Additional WiFi Interface**: On WiFi-capable ESP32 chips, provides dual WiFi interfaces - local `esp_wifi` and remote `esp_wifi_remote` for applications requiring multiple wireless connections. To employ this component, a slave device -- capable of WiFi connectivity -- must be connected to your target device in a specified manner, as defined by the transport layer of [`esp_hosted`](https://github.com/espressif/esp-hosted). @@ -12,8 +16,40 @@ Functionally, `esp_wifi_remote` wraps the public API of `esp_wifi`, offering a s Notably, `esp_wifi_remote` heavily relies on a specific version of the `esp_wifi` component. Consequently, the majority of its headers, sources, and configuration files are pre-generated based on the actual version of `esp_wifi`. -It's important to highlight that `esp_wifi_remote` does not directly implement the RPC calls; rather, it relies on dependencies for this functionality. Presently, only esp_hosted is supported to provide the RPC functionality required by esp_wifi_remote. +It's important to highlight that `esp_wifi_remote` does not directly implement the RPC calls; rather, it relies on dependencies for this functionality. + +## Terminology + +- **Backend Solution**: Communication layer handling transport of WiFi commands, events, and data between host and slave devices (e.g., esp-hosted, eppp, AT-based implementations) +- **Host-side**: Device running your application code (e.g., ESP32-P4, ESP32-H2, or ESP32 with WiFi) +- **Slave-side**: WiFi-capable device providing actual WiFi hardware and functionality + +## Backend Solutions + +`esp_wifi_remote` supports multiple backend solutions for RPC communication: + +- **`esp_hosted`** (recommended): Plain text channels for WiFi API calls/events and Ethernet frames for data. Best performance and maturity. +- **`wifi_remote_over_eppp`**: SSL/TLS encrypted connection with PPP link. Suitable when encryption is required. +- **`wifi_remote_over_at`**: AT commands via esp-modem. Limited functionality but uses standard protocols. + +### Performance Comparison + +| Backend Solution | Max TCP Throughput | Use Case | +|---------------------|-------------------|----------| +| esp_hosted | ~50Mbps | High-performance applications | +| wifi_remote_over_eppp | ~20Mbps | Encrypted communication | +| wifi_remote_over_at | ~2Mbps | Standard AT protocol compatibility | + +## WiFi Configuration + +Configure remote WiFi identically to local WiFi via Kconfig. Options use `WIFI_RMT_` prefix instead of `ESP_WIFI_`: + +``` +CONFIG_ESP_WIFI_TX_BA_WIN → CONFIG_WIFI_RMT_TX_BA_WIN +CONFIG_ESP_WIFI_AMPDU_RX_ENABLED → CONFIG_WIFI_RMT_AMPDU_RX_ENABLED +``` +> **Note**: Some configuration options are compile-time only. Manual slave-side configuration and rebuild required for consistency. ## Dependencies on `esp_wifi` diff --git a/components/esp_wifi_remote/idf_component.yml b/components/esp_wifi_remote/idf_component.yml index da65fd6..612d51f 100644 --- a/components/esp_wifi_remote/idf_component.yml +++ b/components/esp_wifi_remote/idf_component.yml @@ -1,4 +1,4 @@ -version: 0.16.1 +version: 0.16.2 url: https://github.com/espressif/esp-wifi-remote description: Utility wrapper for esp_wifi functionality on remote targets dependencies: diff --git a/components/wifi_remote_over_eppp/README.md b/components/wifi_remote_over_eppp/README.md index 8dace14..3c660bc 100644 --- a/components/wifi_remote_over_eppp/README.md +++ b/components/wifi_remote_over_eppp/README.md @@ -1,5 +1,56 @@ -# EPPP based implementation of Wi-Fi remote APIs +# WiFi Remote over EPPP -:warning: This component should be only used with `esp_wifi_remote` +[![Component Registry](https://components.espressif.com/components/espressif/wifi_remote_over_eppp/badge.svg)](https://components.espressif.com/components/espressif/wifi_remote_over_eppp) -This component has no public API, it only provides alternative (strong) definitions of `esp_wifi_remote` functions. +EPPP-based backend implementation for `esp_wifi_remote`, providing encrypted WiFi connectivity through PPP link with SSL/TLS authentication. + +## Overview + +This component implements the backend communication layer for `esp_wifi_remote` using the [eppp-link](https://github.com/espressif/esp-protocols/tree/master/components/eppp_link) component. It creates a secure point-to-point connection between host and slave devices, enabling WiFi functionality on non-WiFi ESP chipsets. + +![EPPP Architecture Diagram](eppp.webp) + +## Key Features + +- **SSL/TLS Encryption**: Mutual authentication for secure communication of WiFi commands and events +- **PPP Protocol**: Standard point-to-point protocol with IP address assignment to both devices +- **Network Address Translation**: Slave device routes host packets to WiFi network +- **Cross-Platform Compatibility**: Works with non-ESP32 targets using standard PPP protocols + +## Architecture + +**Communication Channels:** +- **Control Path**: SSL/TLS encrypted connection for WiFi API calls and events +- **Data Path**: Plain text peer-to-peer connection using IP packets + +**Network Stack:** +- Both host and slave devices run full TCP/IP stacks +- Host device operates behind NAT (slave-side network address translation) +- Ethernet frames can be enabled for improved performance when NAT limitations are acceptable + +## Performance + +- **Maximum TCP Throughput**: ~20Mbps +- **Use Case**: Applications requiring encrypted host-slave communication +- **Trade-offs**: NAT limitations may affect external network visibility + +## Use Cases + +Ideal for scenarios requiring: +- **Encrypted Communication**: Especially when transmitting WiFi credentials +- **Standard Protocols**: Integration with `pppd` on Linux systems +- **Non-ESP32 Targets**: Cross-platform compatibility with standard networking protocols +- **Security-Conscious Applications**: Mutual SSL/TLS authentication requirements + +## Configuration + +Configure through `esp_wifi_remote` component with `wifi_remote_over_eppp` selected as backend. WiFi settings use `WIFI_RMT_` prefix instead of `ESP_WIFI_`. + +> **Note**: Some configuration options are compile-time only. Ensure slave-side configuration matches host settings. + +## Dependencies + +- [`esp_wifi_remote`](https://github.com/espressif/esp-wifi-remote/tree/main/components/esp_wifi_remote) +- [`eppp-link`](https://github.com/espressif/esp-protocols/tree/master/components/eppp_link) + +:warning: **Important**: This component should only be used with `esp_wifi_remote`. It provides alternative implementations of `esp_wifi_remote` functions with no public API of its own. diff --git a/components/wifi_remote_over_eppp/eppp.webp b/components/wifi_remote_over_eppp/eppp.webp new file mode 100644 index 0000000..bdf55cf Binary files /dev/null and b/components/wifi_remote_over_eppp/eppp.webp differ