rt-thread_esp-hosted/docs/Linux_based_host/Linux_based_readme.md

Getting Started with Linux based host

• Directory structure for Linux based host is explained here
• Below diagram shows hardware and software block diagram for a typical linux based system built with ESP-Hosted.

• This document explains ESP-Hosted setup and usage. The document is divided in two parts:

  • 1. Quick Start Guide
    

  • This section briefly explains ESP-Hosted setup. One can refer this guide to quickly prepare and test ESP-Hosted solution.

  • 2. ESP-Hosted Comprehensive Guide

  • This section provides in depth information about ESP-Hosted setup, available customization options etc.

1. 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.
• Please refer ESP-Hosted Comprehensive Guide for more details and customization options.

1.1 Hardware Requirements

• Raspberry-Pi model 3 Model B/B+ or Raspberry-Pi 4 model B
• ESP32/ESP32-S2/S3/C2/C3/C6 board
• 8-12 jumper wires of length < 10cm

1.2 Host Setup

Make sure that Raspberry-Pi is equipped with following:

• Linux Kernel Headers are installed

  $ sudo apt update
  $ sudo apt install raspberrypi-kernel-headers
  

• Dependency tools need to be installed on Raspberry-Pi:

  $ sudo apt install git raspi-gpio bluetooth bluez bluez-tools rfkill bluez-firmware pi-bluetooth python3
  

• User access for bluetooth service

  $ sudo usermod -G bluetooth -a $(whoami)
  

• Using released codebase

  • Download pre-built ESP-Hosted firmware release binaries from releases
  • :warning: Make sure that you use Source code (zip) in Assets fold with associated release for host building.

• Using latest master

  • Clone ESP-Hosted code repository

    $ git clone --recurse-submodules <url_of_esp_hosted_repository>
    $ cd esp-hosted
    $ git submodule update --init --recursive
    

  • Please use the exact same git commit for ESP flashing using source code.

1.3 Setup

Prepare connections based on interface requirements and setup host as below.

• Wi-Fi and Bluetooth over SDIO
  • Connection Setup
    • Prepare connections as per section 1.1 Hardware Setup of SDIO setup document
  • Host Software
    • Prepare Raspberry-Pi as per section 1.2 Raspberry-Pi Software Setup of SDIO setup document

    • Compile and load host driver as below:

      $ cd esp_hosted_fg/host/linux/host_control/
      $ ./rpi_init.sh sdio
      

• Wi-Fi and Bluetooth over SPI
  • Connection Setup
    • Prepare connections as per section 1.1 Hardware Setup of SPI Setup document
  • Host Software
    • Prepare Raspberry-Pi as per 1.2 Raspberry-Pi Software Setup of SPI Setup document

    • Compile and load host driver as below:

      $ cd esp_hosted_fg/host/linux/host_control/
      $ ./rpi_init.sh spi
      

• Wi-Fi over SDIO and Bluetooth over UART

  • Connection Setup
    • Prepare SDIO connections as per section 1.1 Hardware Setup of SDIO setup document
    • Prepare UART connections as per section 1.1 Hardware Setup of UART setup document
  • Host Software
    • Prepare Raspberry-Pi for SDIO operations as per section 1.2 Raspberry-Pi Software Setup of SDIO setup document
    • Prepare Raspberry-Pi for UART operations as per section 1.2 Raspberry-Pi Software Setup of UART setup document

    • Compile and load host driver as below:

      $ cd esp_hosted_fg/host/linux/host_control/
      $ ./rpi_init.sh sdio btuart
      

    • After loading ESP firmware, execute below command to create hci0 interface ```sh $ sudo hciattach -s 921600 /dev/serial0 any 921600 flow

• Wi-Fi over SPI and Bluetooth over UART

  • Connection Setup
    • Prepare connections as per section 1.1 Hardware Setup of SPI Setup document
    • Prepare UART connections as per section 1.1 Hardware Setup of UART setup document
  • Host Software
    • Prepare Raspberry-Pi as per 1.2 Raspberry-Pi Software Setup of SPI Setup document
    • Prepare Raspberry-Pi for UART operations as per section 1.2 Raspberry-Pi Software Setup of UART setup document

    • Compile and load host driver as below:

      $ cd esp_hosted_fg/host/linux/host_control/
      $ ./rpi_init.sh spi btuart
      

    • After loading ESP firmware, execute below command to create hci0 interface

      $ sudo hciattach -s 921600 /dev/serial0 any 921600 flow
      

1.3.1 ESP Firmware Setup

• Download pre-built firmware binaries from releases
• Follow readme.txt from release tarball to flash the ESP binary
• :warning: Make sure that you use Source code (zip) in Assets fold with associated release for host building.

1.3.2 Setup Validation

Once everything is setup and host software and ESP firmware are loaded

• Verify that ethsta0 and ethap0 interfaces are seen on host using following command.

  $ ifconfig -a
  

• Verify that hci0 interface is present using below command

  $ hciconfig
  

• Proceed to section 3. ESP-Hosted Usage Guide to test Wi-Fi and Bluetooth/BLE functionality.

2. ESP-Hosted Comprehensive Guide

Setup is required on two machines. First to setup ESP-Hosted Linux Host driver building on Raspberry Pi Second to create a development environment set-up on your native machine so that you can build the ESP-Hosted firmware and flash it on the ESP chipset. The native machine here refers to your Windows/Linux/Mac desktop/laptop. Although, if you prefer to use the released binaries for ESP firmware, second part of native machine setup can be skipped.

2.1 Linux Host: Development Environment Setup

• This section list downs environment setup and tools needed to make ESP-Hosted solution work with Linux based host.
• If you are using Raspberry-Pi as a Linux host, both section 2.1.1 and section 2.1.2 are applicable.
• If you are using other Linux platform, skip to section 2.1.2

2.1.1 Raspberry-Pi Specific Setup

This section identifies Raspberry-Pi specific setup requirements.

• Linux Kernel Setup

  • We recommend full version Raspberry Pi OS install on Raspberry-Pi to ensure easy driver compilation. 64bit OS is preferred, although 32bit OS is also supported.
  • 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 and run rpi-source to get current kernel headers. Alternatively upgrade/downgrade kernel and reinstall kernel headers.

    $ ls /lib/modules/$(uname -r)/build/  #Note the ending '/'
    

• User previledges

  • Current user needs to be added to bluetooth group to use bluetoothctl without sudo

    $ sudo usermod -G bluetooth -a $(whoami)
    

• Additional Tools

  • Bluetooth Stack and utilities:

    $ sudo apt install pi-bluetooth
    

  • For throughput testing

    $ sudo apt install iperf #for iperf2
    $ sudo apt install iperf3 #for iperf3
    

2.1.2 Additional Setup

• Linux Kernel setup on non Raspberry-Pi

  • Please make sure to use kernel version v4.19 and above. Prior kernel versions may work, but are not tested.
  • Please install kernel headers as those are required for driver compilation.

  • Verify that kernel headers are installed properly by running following command. Failure of this command indicates that kernel headers are not installed correctly.

    $ ls /lib/modules/$(uname -r)/build/  # Note the last '/'
    

• Install following tools on Linux Host machine.

  • Git
  • Python 2.x or 3.x: We have tested ESP-Hosted solution with python 2.7.13 and 3.5.3
  • Bluetooth Stack and utilities: :warning:Note: ESP-Hosted related BR/EDR 4.2 and BLE 4.2 functionalities are tested with bluez 5.43+. Whereas BLE 5.0 functionalities are tested with bluez 5.45+.
    • bluetooth
    • bluez
    • bluez-tools
    • rfkill
    • bluez-firmware
  • We suggest latest stable bluez version to be used. Any other bluetooth stack instead of bluez also could be used.

2.2 ESP-IDF Setup

• If you are going to use released firmware binaries, ESP-IDF setup is not required, please continue with 2.3 ESP-Hosted Code Repository below.
• Follow steps hereon on your native machine (your Windows/Linux/Mac desktop/laptop)
• Note on Windows 11: you can follow these instructions, instead of the following, to setup ESP-IDF and build the esp firmware.
• :warning: 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_fg/esp/esp_driver
  $ cmake .
  

• Set-Up the build environment using

  $ . ./esp-idf/export.sh
  # Optionally, You can add alias for this command in ~/.bashrc for later use
  

2.3 ESP-Hosted Code Repository

Clone esp-hosted repository on Linux host.

$ git clone --recurse-submodules <url_of_esp_hosted_repository>
$ cd esp-hosted
$ git submodule update --init --recursive

Please make sure that ESP and host checkeout to same git commit.

2.4 ESP-Hosted Setup and Load Project

ESP-Hosted solutions supports SDIO and SPI as transport for Wi-Fi and Bluetooth/BLE connectivity. Bluetooth/BLE connectivity is supported over UART as well. Follow below setup guides according to transport layer of your choice.

• Wi-Fi and BT/BLE connectivity Setup over SDIO

• Wi-Fi and BT/BLE connectivity Setup over SPI

• Bluetooth/BLE connectivity Setup over UART

3. ESP-Hosted Usage Guide

Following guide explains how to use ESP-Hosted solution.

• User Guide for ESP-Hosted with Linux Host

4. ESP-Hosted Porting Guide to other Linux Platforms

Following document explains guidelines for porting solution to othe Linux platforms

• Porting Guide