-# Hosted solution with ESP32
-This project adds a capability to use ESP32 as a communication processor for Wi-Fi connectivity with an external host. This uses a subset of AT command-set for control path and uses a separate connection (currently supported on SDIO) for data path. The ESP32 provides a simple interface to the host to provide ethernet interface that can transmit and receive 802.3 frames. This allows the TCP/IP and higher level protocol stack to run on the host. The project provides ESP32 side firmware, example Linux driver and protocol description. This can directly be used with Linux based hosts or can easily be ported to other MCUs with available open protocol description.
-
-# Setup
-Currently we support ESP32 WROVER-Kit with Raspberry-Pi (3 Model B+, 4 Model B) for evaluation with Raspbian operating system.
-
-## Hardware Setup / Connections
-Please connect ESP32 board to Raspberry-Pi with jumper cables as mentioned below. It may be good to use small length cables to ensure signal integrity.
-
-| RPi Pin | ESP32 Pin | Function |
-|:-------:|:---------:|:--------:|
-| 13 | IO13 | DAT3 |
-| 15 | IO14 | CLK |
-| 16 | IO15 | CMD |
-| 18 | IO2 | DAT0 |
-| 22 | IO4 | DAT1 |
-| 37 | IO12 | DAT2 |
-| 39 | GND | GND |
-
-Power ESP32 and Raspberry Pi separately with a power supply that provide sufficient power. ESP32 can be powered through PC using micro-USB cable.
-
-## Raspberry-Pi Software Setup
-We recommend full version Raspbian install on Raspberry-Pi to ensure easy driver compilation. In addition for driver compilation, kernel headers are required. Please install them as:
-```sh
-$ sudo apt update
-$ sudo apt-get install raspberrypi-kernel-headers
-```
-By default, the SDIO pins of Raspberry-pi are not configured and are internally used for built-in Wi-Fi interface. Please enable SDIO pins by appending following line to _/boot/config.txt_ file
-```
-dtoverlay=sdio,poll_once=off
-```
-Please reboot Raspberry-Pi after changing this file.
-
-## ESP32 Setup
-On ESP32 either use pre-provided hosted mode firmware binary or if you have source, compile the app against ESP-IDF 3.3 release by running command as `make SILENCE=0 ESP_AT_PROJECT_PLATFORM=esp32_at_core`. Program the WROVER-KIT using standard flash programming procedure with
-```sh
-$ make flash
-```
-
-## Checking the Setup
-Once ESP32 has a valid firmware and booted successfully, you should be able to see successful enumeration on Raspberry Pi side as:
-```sh
-$ dmesg
-[ 769.531080] mmc1: queuing unknown CIS tuple 0x01 (3 bytes)
-[ 769.541087] mmc1: queuing unknown CIS tuple 0x1a (5 bytes)
-[ 769.545546] mmc1: queuing unknown CIS tuple 0x1b (8 bytes)
-[ 769.547832] mmc1: queuing unknown CIS tuple 0x80 (1 bytes)
-[ 769.547928] mmc1: queuing unknown CIS tuple 0x81 (1 bytes)
-[ 769.548023] mmc1: queuing unknown CIS tuple 0x82 (1 bytes)
-[ 769.549804] mmc1: queuing unknown CIS tuple 0x80 (1 bytes)
-[ 769.549900] mmc1: queuing unknown CIS tuple 0x81 (1 bytes)
-[ 769.550000] mmc1: queuing unknown CIS tuple 0x82 (1 bytes)
-[ 769.550195] mmc1: new SDIO card at address 0001
-```
-Once the module is inserted, you should see ethap0 and ethsta0 interfaces using _ifconfig_ command.
-
-# Protocol Definition
-TBD
-
-## How to Run scripts on Raspberry-Pi(rpi)
-There is `esp_at` folder in which "AT commands" python library is present. User can make use of python functions to get access of wifi functionalities of ESP32.
-
-first run `./rpi_init.sh` to compile and insert ESP32 host driver on rpi. This script also creates /dev/esps0 which is used as WLAN control interface.
-
-There are three python script for station connect to AP, station disconnect from AP and softAP configuration.
-
-1. `station_connect.py` is a python script which configure ESP32 in `station mode`, connects rpi to external AP with credentials user has provided. Also it ups the station interface and run DHCP client. User should provide parameters like ssid, password, mac address of AP(user can set mac address as 0 if doesnt want to set).
----
-Note: This script should run in bash
+# ESP-Hosted
----
-```
-ex.
-python3 station_connect.py 'xyz' 'xyz123456' '0'
-```
-2. station_disconnect.py is a python script to disconnect ESP32 station from AP.
-
-```
-python3 station_disconnect.py
-```
-3. softap_config.py is a python script for configure ESP32 softAP mode. User should provide parameters like ssid, password(password length should be 8~64 bytes ASCII), channel ID (It can be any number between 1 to 11), encryption method (0 : OPEN, 2: WPA_PSK, 3:WPA2_PSK, 4: WPA_WPA2_PSK), max connection count( number of Stations to which ESP32 SoftAP can be connected, within the range of [1, 10]) and ssid hidden (it can set to 1 if softAP shouldnt broadcast its ssid else 0). max connection count and ssid hidden parameters are optional user can set this filed to 0.
-
-```
-ex. python3 softap_config.py 'xyz' 'xyz123456' 1 3 4 0
-```
----
-Note: To start data connection, user needs to setup a DHCP server on rpi or set static IP address for AP interface i.e. ethap0
+Espressif launched this solution in 2020 and since then it helped many IoT enthusiast, developers, OEMs to offload their host's connectivity burden to ESP chipsets. Applications developed using this solution includes but not limited to Bluetooth headphones, Bluetooth speakers, smart door locks, smart vacuum cleaners, video streaming applications and many more.
+
+
+
+## Introduction
+
+ESP-Hosted is an open source solution that provides a way to use ESP board as a communication co-processor. This solution provides wireless connectivity (network and BT/BLE) to the host, allowing it to communicate with other devices.
+
+It leverages Wi-Fi and Bluetooth capabilities of ESP board to the host, helping it to be a smart device.
+
+
+
+## Overview
+
+Following is the broader level block diagram that depicts where ESP-Hosted fits in the entire system. Detailed block diagram is available in subsequent sections.
+
+* As it can be seen in the diagram, host needs to be equipped with TCP/IP stack and Bluetooth/BLE stack.
+* The host driver of ESP-Hosted, registers a network and HCI interface in host operating system.
+* The host driver is responsible for transferring of network and HCI packets to and from host operating system
+* ESP firmware application runs on ESP board and it facilitates communication between host software and ESP wifi and Bluetooth/BLE controller
+
+
+
+
+
+
+
+## Variants
+
+The ESP-Hosted presents two variants of the solution as below. The differentiation factor here is the type of network interface presented to host and the way Wi-Fi on ESP board is configured/controlled. Both the variants have their respective host and firmware software.
+
+
+
+#### ESP-Hosted-NG
+
+This is a Next-Generation ESP-Hosted specifically designed for a sophisticated hosts that run Linux operating system. This variant of the solution takes more standard approach while providing a network interface to the host. This allows usage of standard Wi-Fi applications such as wpa_supplicant to be used with ESP chipsets.
+
+This solution offers following:
+
+* 802.11 network interface which is a standard Wi-Fi interface on Linux host
+* Configuration of Wi-Fi is supported through standard cfg80211 interface of Linux
+* A standard HCI interface
+
+This variant is available in <a href="https://github.com/espressif/esp-hosted/tree/ESP-Hosted_MCU_Host" target="_blank" rel="noopener">master</a> branch on <a href="https://github.com/espressif/esp-hosted" target="_blank" rel="noopener">github repository</a>.
+
+Please proceed with the [detailed documentation](docs/README.md) for setup and usage instructions.
+
+
+
+> #### ESP-Hosted
+>
+> :warning: Your current branch doesn't have this variant
+
+> This is a first generation ESP-Hosted solution. This is a variant provides a simple 802.3 (Ethernet) network interface to the host. Thought process behind this solution is to keep the host software simple while providing suite of connectivity features.
+> In order to achieve this, the host is presented with following:
+>
+> * A simple 802.3 network interface which essentially is an Ethernet interface
+> * A light weight control interface to configure Wi-Fi on ESP board
+> * A standard HCI interface
+
+> Although this variant supports Linux host, the simple nature of this solution makes it ideal to be used with MCU hosts which do not have complex communication interfaces such as Ethernet, Wi-Fi, BT/BLE etc.
+> This variant is available in <a href="https://github.com/espressif/esp-hosted/tree/ESP-Hosted_MCU_Host" target="_blank" rel="noopener">ESP-Hosted_MCU_Host</a> branch on <a href="https://github.com/espressif/esp-hosted" target="_blank" rel="noopener">github repository</a>.
---
+
+
+
+## ESP-Hosted vs ESP-Hosted-NG
+
+Now that we offer two variants of this solution, it could cause a little confusion. This section will try to explains similarities and differences in both the variants and help you make a choice.
+
+#### Similarities
+
+- Both versions share the same aim, to conveniently use ESP's Wi-Fi and Bluetooth/BLE capabilities from host
+
+- Both versions aim to support same set of ESP chipsets and same set of transports like SPI/SDIO/UART for connectivity needs
+
+#### Key Differences
+
+- ESP-Hosted supports both Linux and MCU hosts. ESP-Hosted-NG supports only Linux host.
+- ESP-Hosted exposes 802.3 network interface (Ethernet) to the host. Where as, ESP-Hosted-NG exposes 802.11 interface (Wi-Fi).
+- ESP-Hosted uses custom control path to configure Wi-Fi as opposed to ESP-Hosted-NG which uses standard nl80211/cfg80211 configuration.
+
+#### Our Recommendation
+
+* If you are using MCU host, you do not have choice but to use ESP-Hosted
+* If you are using Linux host, we recommend ESP-Hosted-NG since it takes a standard approach which makes it compatible with widely used user space applications/services such as wpa_supplicant, Network Manager etc.
+
+
+
+Following table summarizes this entire discussion.
+
+| Category | ESP-Hosted | ESP-Hosted-NG |
+| :--------------------------------------- | :----------------------- | :------------------------ |
+| Features Supported | 802.11 b/g/n, BT/BLE | 802.11 b/g/n, BT/BLE |
+| Network Interface Type (exposed to host) | 802.3 Ethernet Interface | 802.11 Wi-Fi interface |
+| Wi-Fi Configuration mechanism | Custom control interface | nl80211/cfg80211 |
+| Station Interface | Supported (ethsta0) | Supported (espsta0) |
+| SoftAP interface | Supported (ethap0) | To be supported in future |
+| HCI Interface | Supported | Supported |
+| Transport Layer | SDIO, SPI, UART | SDIO, SPI, UART |
+| Recommended Host Type | MCU Host | Linux Host |
+
+
+
projects / esp-hosted.git / blobdiff