Skip to content

Latest commit

 

History

History
458 lines (415 loc) · 25.9 KB

setup.md

File metadata and controls

458 lines (415 loc) · 25.9 KB

ESP-Hosted-NG Setup

1 Setup Introduction

1. Software setup

  • This section briefly explains software setup required for esp hosted device and host. Esp hosted device setup is divided into two parts
    • Host software setup This section provides information about installation of required packages for host device
    • ESP Quick start guide This section briefly explains ESP-Hosted setup. One can refer this guide to quickly prepare and test ESP-Hosted solution
    • ESP Comprehensive guide This section provides in depth information about ESP-Hosted setup, available customization options etc. Use Quick start guide for easy setup or Comprehensive guide for customizable setup.

1.1 Host software setup

Make sure that host machine is equipped with following:

  • Linux Kernel Setup

    • We recommend full version Raspbian install on Raspberry-Pi to ensure easy driver compilation.
    • Please make sure to use kernel version v4.19 and above. Prior kernel versions may work, but are not tested.
    • Kernel headers are required for driver compilation. Please install them as:
      $ sudo apt update
      $ sudo apt install raspberrypi-kernel-headers
    • Verify that kernel headers are installed properly by running following command. Failure of this command indicates that kernel headers are not installed correctly. In such case, follow https://github.com/RPi-Distro/rpi-source/wiki and run rpi-source to get current kernel headers. Alternatively upgrade/downgrade kernel and reinstall kernel headers.
      $ ls /lib/modules/$(uname -r)/build/
  • Following tools are required on Raspberry-Pi:

    • Git
    • Raspi-gpio utility
    • bluetooth
    • bluez
    • bluez-tools
    • rfkill
    • bluez-firmware
    • pi-bluetooth
      $ sudo apt install git raspi-gpio bluetooth bluez bluez-tools rfkill bluez-firmware pi-bluetooth
    • We suggest latest stable bluez version to be used. Any other bluetooth stack instead of bluez also could be used.
  • More transport layer specific host software setup can be found here Transport layer configuration

1.2 ESP Quick Start Guide

  • With the help of this guide, one can easily setup and start using ESP-Hosted solution with Raspberry-Pi as a host.
  • This section makes use of pre-built ESP firmware release binaries and default configuration.
  • Pre-built ESP firmware binaries are available on releases.
  • Please download the latest release.
  • Windows user can use ESP Flash Programming Tool to flash the pre-built ESP binaries.
  • Linux or Mac users can use esptool.py to flash the pre-built ESP binaries. To install, please run:
    $ pip install esptool
  • Please browse to desired ESP chipset directory
    $ tar xvf ESP-Hosted-NG-release_1.x.y.tgz
    $ cd ESP-Hosted-NG-release_1.x.y/
    $ cd <esp_chipset>
    $ cd <transport_layer>
  • here,
    • For SDIO
      • <esp_chipset> can be esp32.
      • <transport_layer> can be sdio_only or sdio+uart
    • For SPI
      • <esp_chipset> can be esp32, esp32c3, esp32s3,esp32c2.
      • <transport_layer> can be spi_only or spi+uart
  • Run the flashing command from flashing_cmd.txt file.
  • Follow these steps to setup required configurations for desired transport layer Transport layer configuration

1.3 ESP Comprehensive guide

  • Note on Windows 11: you can follow these instructions to setup ESP-IDF to build the esp firmware.
  • ⚠️ Following command is dangerous. It will revert all your local changes. Stash if need to keep them.
  • Install the ESP-IDF using script
    $ cd esp_hosted/esp_hosted_ng/esp/esp_driver
    $ cmake .
  • This will clone the required esp-idf repository and will setup it up for esp hosted firmware
  • Set-Up the esp firmware build environment using
    $ . ./esp-idf/export.sh
    # Optionally, You can add alias for this command in ~/.bashrc for later use
  • Once the environment is ready for esp firmware to be built follow these steps to setup required configurations for desired transport layer Transport layer configuration

2. Transport layer configuration

  • This section will provide all required configuration to be made for required desired transport layer.
  • Hardware requirements
    1. 8-12 jumper wires of length < 10cm.
    2. ESP32, ESP32 C3, ESP32 S3, ESP32 C2 board.
    3. Raspberry-Pi 3 model B/B+ or Raspberry-Pi 4 model B
  • This is section is divided into following transport layers.
    1. SPI configuration Wi-Fi and Bluetooth over SPI
    2. SDIO configuration Wifi and bluetooth over SDIO
    3. SDIO/SPI + Uart configuration Wi-Fi over SDIO and Bluetooth over UART

2.1 SPI configuration

Wi-Fi and Bluetooth over SPI

Supported Targets ESP32 ESP32-S2 ESP32-S3 ESP32-C2 ESP32-C3 ESP32-C6
  • Hardware setup
    • In this setup, ESP board acts as a SPI peripheral and provides Wi-Fi capabilities to host. Please connect ESP board to Raspberry-Pi with jumper cables as mentioned below. Please use short jumper cables to ensure signal integrity. Raspberry Pi should be powered with correct incoming power rating. ESP can be powered through PC using micro-USB/USB-C cable.

    • Pin Connections

      Raspberry-Pi Pin ESP32 ESP32-S2/S3 ESP32-C2/C3/C6 Function
      24 IO15 IO10 IO10 CS0
      23 IO14 IO12 IO6 SCLK
      21 IO12 IO13 IO2 MISO
      19 IO13 IO11 IO7 MOSI
      25 GND GND GND Ground
      15 IO2 IO2 IO3 Handshake
      13 IO4 IO4 IO4 Data Ready
      31 EN RST RST ESP32 Reset
    • Raspberry-Pi pinout can be found here!

    • Optionally, Add external pull-up of min 10k Ohm on CS line just to prevent bus floating

    • In case of ESP32-S3, For avoidance of doubt, You can power using UART port

  • Raspberry-Pi Setup
    • The SPI master driver is disabled by default on Raspberry-Pi OS. To enable it add following commands in /boot/config.txt file
      dtparam=spi=on
      dtoverlay=disable-bt
      
    • In addition, below options are set as the SPI clock frequency in analyzer is observed to be smaller than expected clock. This is RaspberryPi specific issue.
      core_freq=250
      core_freq_min=250
      
    • Please reboot Raspberry-Pi after changing this file.
  • Setting up the environment and getting started
    • Host environment setup

      • Execute following commands in root directory of cloned ESP-Hosted repository on Raspberry-Pi
        $ cd esp_hosted/esp_hosted_ng/host/
        $ bash rpi_init.sh spi <ap_support>
      • add ap_support if you want to use interface as access point.
      • This script compiles and loads host driver on Raspberry-Pi. It also creates network interface wlanX which is used as a control interface for Wi-Fi on ESP peripheral
    • For esp firmware if you are using ESP Quick start guide

      • Please flash the required binaries using with command mentioned in flashing_cmd.txt within desired transport configuration folder as explained in ESP Quick start guide.
      • Use minicom or any similar terminal emulator with baud rate 115200 to fetch esp side logs on UART
        $ minicom -D <serial_port>
      • serial_port is device where ESP chipset is detected. For example, /dev/ttyUSB0
    • For esp firmware if you are using ESP Comprehensive guide.

      • Set up the esp-idf environment as mentioned in ESP Comprehensive guide
      • To configure slave chip set environment
        $ cd esp_hosted/esp_hosted_ng/esp/esp_driver/network_adapter
        $ rm -rf sdkconfig build
        $ idf.py set-target <esp_chipset>
        
      • For SPI, <esp_chipset> could be one of esp32, esp32s2, esp32s3, esp32c2, esp32c3, esp32c6.
      • Execute following command to configure the project
        $ idf.py menuconfig
        
      • This will open project configuration window. To select SPI transport interface, navigate to Example Configuration -> Transport layer -> SPI interface -> select and exit from menuconfig.
      • For ESP32-C3, select chip revision in addition. Navigate to Component config → ESP32C3-Specific → Minimum Supported ESP32-C3 Revision and select chip version of ESP32-C3.
      • Use below command to compile and flash the project. Replace <serial_port> with ESP peripheral's serial port.
        $ idf.py -p <serial_port> build flash
        
      • Collect the firmware log using
        $ idf.py -p <serial_port> monitor
        
  • Checking the Setup
    • On successful flashing and host driver installation, you should see following entry in ESP log:
      [   77.877892] Features supported are:
      [   77.877901]   * WLAN
      [   77.877906]   * BT/BLE
      [   77.877911]     - HCI over SPI
      [   77.877916]     - BLE
      
  • Once the one of ESP-Hosted-NG mode is set-up, proceed to how to use Wi-Fi and Bluetooth over this setup

2.2 SDIO configuration

Wi-Fi and Bluetooth over SDIO

Supported Targets ESP32 ESP32-C6
  • Hardware setup

    • In this setup, ESP board acts as a SDIO peripheral and provides Wi-Fi capabilities to host. Please connect ESP board to Raspberry-Pi with jumper cables as mentioned below. Raspberry Pi should be powered with correct incoming power rating. ESP can be powered through PC using micro-USB/USB-C cable.

    • Pin connections

      Raspberry-Pi Pin ESP32 Pin ESP32-C6 Pin Function
      13 IO13+pull-up IO23+pull-up DAT3
      15 IO14 IO19 CLK
      16 IO15+pull-up IO18+pull-up CMD
      18 IO2+pull-up IO20+pull-up DAT0
      22 IO4+pull-up IO21+pull-up DAT1
      31 EN ESP Reset
      37 IO12+pull-up IO22+pull-up DAT2
      39 GND GND GND
    • Raspberry-Pi pinout can be found here!

    • As SDIO faces signal integrity issues over jumper wires, we strongly recommend to Design PCB boards with above connections. If that is not possible. Use good quality extremely small (smaller than 5cm) jumper wires, all equal length. Join all possible grounds interconnected to lower noise. Add at least, 10k Ohm external pull-up resistors on 5 lines: CMD, DAT0-4. We use 51k Ohm resistors in our set-up.

  • Raspberry-Pi Setup

    • 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
      dtoverlay=disable-bt
      
    • Please reboot Raspberry-Pi after changing this file.
  • Setting up the environment and getting started

    • Host environment setup

      • As ESP32 & ESP32C6, both support SDIO, Let host know which slave chipset is being used by changing ESP_SLAVE_CHIPSET in esp_hosted_ng/host/rpi_init.sh as:
        ESP_SLAVE_CHIPSET="esp32"
        or
        ESP_SLAVE_CHIPSET="esp32c6"
      • Execute following commands in root directory of cloned ESP-Hosted repository on Raspberry-Pi
        $ cd esp_hosted/esp_hosted_ng/host/
        $ bash rpi_init.sh sdio <ap_support>
      • add ap_support if you want to use interface as access point.
      • This script compiles and loads host driver on Raspberry-Pi. It also creates network interface wlanX which is used for Wi-Fi in host.
    • For esp firmware if you are using ESP Quick start guide

      • Please flash the required binaries using with command mentioned in flashing_cmd.txt within desired transport configuration folder as explained in ESP Quick start guide.
      • Use minicom or any similar terminal emulator with baud rate 115200 to fetch esp side logs on UART
        $ minicom -D <serial_port>
      • serial_port is device where ESP chipset is detected. For example, /dev/ttyUSB0
    • For esp firmware if you are using ESP Comprehensive guide.

      • Set up the esp-idf environment as mentioned in ESP Comprehensive guide
      • To configure slave chip set environment
        $ cd esp_hosted/esp_hosted_ng/esp/esp_driver/network_adapter
        $ rm -rf sdkconfig build
        $ idf.py set-target <esp_chipset>
        
      • For SDIO, <esp_chipset> could is esp32, esp32c6.
      • Execute following command to configure the project
        $ idf.py menuconfig
        
      • This will open project configuration window. To select SDIO transport interface, navigate to Example Configuration -> Transport layer -> SDIO interface -> select and exit from menuconfig.
      • Use below command to compile and flash the project. Replace <serial_port> with ESP peripheral's serial port.
        $ idf.py -p <serial_port> build flash
        
      • Collect the firmware log using
        $ idf.py -p <serial_port> monitor
        
  • Checking the Setup

    • On successful flashing and host driver installation, you should see following entry in ESP log:
      [   77.877892] Features supported are:
      [   77.877901]   * WLAN
      [   77.877906]   * BT/BLE
      [   77.877911]     - HCI over SDIO
      [   77.877916]     - BT/BLE dual mode
      
  • Once the one of ESP-Hosted-NG mode is set-up, proceed to how to use Wi-Fi and Bluetooth over this setup

2.3 SDIO/SPI + Uart configuration

Wi-Fi over SDIO/SPI and Bluetooth over UART

Supported Chipsets ESP32 ESP32-C2 ESP32-C3 ESP32-S3 ESP32-C6
4 line UART supported yes no yes yes no
2 line UART supported yes yes yes yes yes
  • In this section, ESP chipset provides a way to run Bluetooth/BLE over UART interface.

  • This section is divided in two parts

  • Wi-fi over SPI and Bluetooth over UART

    • Supported targets ESP32, ESP32S3, ESP32C3, ESP32C2, ESP32C6
    • Please follows these steps first to setup esp device in SPI mode SPI configuration
  • Wi-fi over SDIO and Bluetooth over UART

    • Supported targets ESP32, ESP32C6
    • Please follows these steps first to setup esp device in SDIO mode SDIO configuration
  • Hardware Uart setup

    • Pin Connections

    • Four line setup

      Raspberry-Pi Pin Function Raspberry-Pi Pin ESP32 ESP32-S3 ESP32-C3 ESP32 Pin Function
      RX 10 IO5 IO17 IO5 TX
      TX 8 IO18 IO18 IO18 RX
      CTS 36 IO19 IO19 IO19 RTS
      RTS 11 IO23 IO20 IO8 CTS
    • Two line setup

      Raspberry-Pi Pin Function Raspberry-Pi Pin ESP32-C2 ESP32-C6 ESP Function
      RX 10 IO5 IO5 TX
      TX 8 IO18 IO12 RX
    • Raspberry-Pi pinout can be found here!

    • In case you wish to reduce number of hardware lines, you may consider SPI_only or SDIO_only transports, where Wi-Fi and Bluetooth traffic is multiplexed on same bus and no need of extra UART pins. UART pin numbers are configurable. If you want to switch from 4 line UART mode to 2 lines, hardware flow control need to be turned off.

    • Use good quality small (smaller than 10cm) jumper wires, all equal length

  • Raspberry-Pi Setup

    • By default, the UART pins on Raspberry-Pi are in disabled state. In order to enable UART and setup it for bluetooth connection, follow below steps.
      1. Enable UART pins and disable in built bluetooth on Raspberry-Pi by appending following lines to /boot/config.txt file
        enable_uart=1
        dtoverlay=disable-bt
        
      2. Remove following from /boot/cmdline.txt. Leave everything else untouched.
        console=serial0,115200
        
        e.g. If /boot/cmdline.txt is as below:
        $ cat /boot/cmdline.txt
        dwc_otg.lpm_enable=0 console=tty1 console=serial0,115200 root=PARTUUID=5c2c80d1-02 rootfstype=ext4 elevator=deadline fsck.repair=yes rootwait quiet splash plymouth.ignore-serial-consoles spidev.bufsiz=32768
        
        Then after removal of above mentioned arguments, it should look as below:
        $ cat /boot/cmdline.txt
        dwc_otg.lpm_enable=0 console=tty1 root=PARTUUID=5c2c80d1-02 rootfstype=ext4 elevator=deadline fsck.repair=yes rootwait quiet splash plymouth.ignore-serial-consoles spidev.bufsiz=32768
        
      3. Disable hciuart on Raspberry-Pi
        $ sudo systemctl disable hciuart
        
    • Please reboot Raspberry-Pi after changing this file.
  • Setting up the environment and getting started

    • Host environment setup
      • Execute following commands in root directory of cloned ESP-Hosted repository on Raspberry-Pi
        $ cd esp_hosted/esp_hosted_ng/host/
        $ bash rpi_init.sh <transport> <bt_over_uart> <ap_support>
      • transport can take value sdio or spi. Defaults to sdio
      • bt_over_uart can take value btuart or btuart_2pins.
      • add ap_support if you want to use interface as access point.
      • ⚠️ Note:
      • For ESP32-C2, 2 pin UART (TX & RX only) is supported. So btuart_2pins should be used for ESP32-C2.
      • For other chipsets, btuart should be used, where 4 pin UART (TX, RX, CTS, RTS) is used.
    • For esp firmware if you are using ESP Quick start guide
      • Please flash the required binaries using with command mentioned in flashing_cmd.txt within desired transport configuration folder as explained in ESP Quick start guide.
      • Use minicom or any similar terminal emulator with baud rate 115200 to fetch esp side logs on UART
        $ minicom -D <serial_port>
      • serial_port is device where ESP chipset is detected. For example, /dev/ttyUSB0
    • For esp firmware if you are using ESP Comprehensive guide.
      • Set up the esp-idf environment as mentioned in ESP Comprehensive guide

      • To configure slave chip set environment

        $ cd esp_hosted/esp_hosted_ng/esp/esp_driver/network_adapter
        $ rm -rf sdkconfig build
        $ idf.py set-target <esp_chipset>
        
      • For SDIO, <esp_chipset> could is esp32, for SPI it will could be esp32, esp32s3, esp32c3.

      • Execute following command to configure the project

        $ idf.py menuconfig
        
      • Set ESP-Hosted transport

        • ESP32
          • Select transport either SDIO or SPI
          • Navigate to Example Configuration -> Transport layer select SDIO interface or SPI interface, whichever expected
        • ESP32-C3/S3
          • SPI is automatically selected. Nothing to be done, skip to next step
      • Set Bluetooth over UART

        • ESP32 / ESP32-C3/S3
          • navigate to Component config -> Bluetooth -> Bluetooth controller -> HCI mode, select UART(H4)
      • Set UART baud rate

        • Default HCI over baud rate is 921600. In case need to change,
        • ESP32
          • Navigate and change using Component config -> Bluetooth -> Bluetooth controller -> HCI UART(H4) Options -> UART Baudrate for HCI
        • ESP32-C3/S3
          • Navigate and change using Component config -> Example Configuration -> UART Baudrate for HCI
      • Additional settings

        • ESP32-C3
          • Select chip revision in addition. Navigate to Component config → ESP32C3-Specific → Minimum Supported ESP32-C3 Revision and select chip version of ESP32-C3.
      • Build and flash the project. Replace <serial_port> with ESP peripheral's serial port.

        $ idf.py -p <serial_port> build flash
  • Post Setup

    • After setting up host and loading ESP firmware, execute below command to create hci0 interface

      $ sudo hciattach -s <baud_rate> /dev/serial0 any <baud_rate> flow
    • <baud_rate> should match UART baud rate while flashing ESP peripheral (Default: 921600)

    • For ESP32

      • Check CONFIG_BT_HCI_UART_BAUDRATE parameter in esp_hosted_ng/esp/esp_driver/network_adapter/sdkconfig
      • Alternatively baud rate could be located using idf.py menuconfig at, Component config -> Bluetooth -> Bluetooth controller -> HCI UART(H4) Options -> UART Baudrate for HCI
    • For ESP32-C3/S3

      • Check CONFIG_EXAMPLE_HCI_UART_BAUDRATE parameter in esp_hosted_ng/esp/esp_driver/network_adapter/sdkconfig
      • Alternatively baud rate could be located using idf.py menuconfig at, Component config -> Example Configuration -> UART Baudrate for HCI
    • Check if UART is setup correctly

      $ hciconfig
      

      Should list the hci interface with bus as 'UART' and interface should be 'UP'

  • Points to note

    • Restart HCI on every reloading of kernel module
    • Remove and reattach HCI over UART
      $ hciconfig -a
      $ sudo killall hciattach
      $ sudo hciattach -s <baud_rate> /dev/serial0 any <baud_rate> flow
      $ hciconfig -a
    • <baud_rate> should match UART baud rate while flashing ESP peripheral
  • Once the one of ESP-Hosted-NG mode is set-up, proceed to how to use Wi-Fi and Bluetooth over this setup

3. Troubleshoot Setup Problems

After following above steps, the host software should be loaded fine. Bootup event from ESP should already would have sent and Host should have received it.

If Bootup event is not recieved in host dmesg as sample log above, please try following:

  • Please check your connections to be firm
  • Try with smaller wires
  • Check correct Pull-Ups are in place
  • If using different host than Raspberry-Pi, please check porting guide
  • Check Troubleshoot Guide for further details

4. Points to note

  • This solution is tested BR/EDR(Classic BT) 4.2 and BLE 4.2 functionalities with BlueZ 5.43+.
  • We suggest to use the latest stable BlueZ release.