[esp-hosted.git] / docs / Linux_based_host / Linux_based_readme.md

# Getting Started with Linux based host

Below diagram shows hardware and software block diagram for a typical linux based system built with ESP-Hosted.

![ESP-Hosted linux based design](./linux_hosted_design.png)

This document explains ESP-Hosted setup and usage. The document is divided in two parts:
* [Quick Start Guide](#1-quick-start-guide)  
	This section briefly explains ESP-Hosted setup. One can refer this guide to quickly prepare and test ESP-Hosted solution,

* [ESP-Hosted Comprehensive Guide](#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](#2-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 board
* 8-12 jumper wires of 10cm length

### 1.2 Host Setup
Make sure that Raspberry-Pi is equipped with following:
* Linux Kernel Headers are installed
	```sh
	$ sudo apt update
	$ sudo apt install raspberrypi-kernel-headers
	```
* Following tools are installed on Raspberry-Pi:
	* Git
	* Raspi-gpio utility
	* bluetooth
	* bluez
	* bluez-tools
	* rfkill
	* bluez-firmware
	* pi-bluetooth
	```sh
	$ sudo apt install git raspi-gpio bluetooth bluez bluez-tools rfkill bluez-firmware pi-bluetooth
	```
* Python Requirement
	* Python 2.x or 3.x
		```sh
		$ sudo apt install python
		 or
		$ sudo apt install python3
		```
	* Protobuf
		```sh
		$ pip install protobuf
		 or
		$ pip3 install protobuf
		```
* Clone ESP-Hosted code repository
	```
	$ git clone --recurse-submodules <url_of_esp_hosted_repository>
	$ cd esp-hosted
	$ git submodule update --init --recursive
	```
* Download pre-built ESP-Hosted firmware release binaries from [releases](https://github.com/espressif/esp-hosted/releases)


### 1.3 Setup

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

* **Wifi and Bluetooth over SDIO**
	* Connection Setup
		* Prepare connections as per section [1.1 Hardware Setup](SDIO_setup.md#11-hardware-setup) of [SDIO setup document](SDIO_setup.md)
	* Host Software
		* Prepare Raspberry-Pi as per section [1.2 Raspberry-Pi Software Setup](SDIO_setup.md#12-raspberry-pi-software-setup) of [SDIO setup document](SDIO_setup.md)
		* Compile and load host driver as below:
			```sh
			$ cd host/linux/host_control/
			$ ./rpi_init.sh sdio
			```
* **Wifi and Bluetooth over SPI**
	* Connection Setup
		* Prepare connections as per section [1.1 Hardware Setup](SPI_setup.md#11-hardware-setup) of [SPI Setup document](SPI_setup.md)
	* Host Software
		* Prepare Raspberry-Pi as per [1.2 Raspberry-Pi Software Setup](SPI_setup.md#12-raspberry-pi-software-setup) of [SPI Setup document](SPI_setup.md)
		* Compile and load host driver as below:
			```sh
			$ cd host/linux/host_control/
			$ ./rpi_init.sh spi
			```
* **Wifi over SDIO and Bluetooth over UART**
	* Connection Setup
		* Prepare SDIO connections as per section [1.1 Hardware Setup](SDIO_setup.md#11-hardware-setup) of [SDIO setup document](SDIO_setup.md)
		* Prepare UART connections as per section [1.1 Hardware Setup](UART_setup.md#11-hardware-setup) of [UART setup document](UART_setup.md)
	* Host Software
		* Prepare Raspberry-Pi for SDIO operations as per section [1.2 Raspberry-Pi Software Setup](SDIO_setup.md#12-raspberry-pi-software-setup) of [SDIO setup document](SDIO_setup.md)
		* Prepare Raspberry-Pi for UART operations as per section [1.2 Raspberry-Pi Software Setup](UART_setup.md#12-raspberry-pi-software-setup) of [UART setup document](UART_setup.md)
		* Compile and load host driver as below:
			```sh
			$ cd 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
			```

#### 1.3.1 ESP Firmware Setup
* Flash pre-built binaries as below.
```sh
$ esptool.py -p <serial_port> -b 960000 --before default_reset --after hard_reset \
write_flash --flash_mode dio --flash_freq 40m --flash_size detect 0x8000 \
esp_hosted_partition-table_<esp_peripheral>_<interface_type>_v<release_version>.bin 0x1000 \
esp_hosted_bootloader_<esp_peripheral>_<interface_type>_v<release_version>.bin 0x10000 \
esp_hosted_firmware_<esp_peripheral>_<interface_type>_v<release_version>.bin

Where,
	<serial_port>    : serial port of ESP peripheral
	<esp_peripheral> : esp32/esp32s2
	<interface_type> : sdio/spi/sdio_uart
	<release_version>: 0.1,0.2 etc
```

#### 1.3.2 Setup Validation
Once everything is setup and and host software and ESP firmware are loaded
* Verify that `ethsta0` and `ethap0` interfaces are seen on host using following command.
	```sh
	$ ifconfig -a
	```
* Verify that hci0 interface is present using below command
	```sh
	$ hciconfig
	```
* Proceed to section [3. ESP-Hosted Usage Guide](#3-esp-hosted-usage-guide) to test Wi-Fi and Bluetooth/BLE functionality.


# 2. ESP-Hosted Comprehensive Guide

### 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](#211-raspberry-pi-specific-setup) and [section 2.1.2](#212-additional-setup) are applicable.
* If you are using other Linux platform, skip to [section 2.1.2](#212-additional-setup)

#### 2.1.1 Raspberry-Pi Specific Setup
This section identifies Raspberry-Pi specific setup requirements.

* 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:
	```sh
	$ 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/notro/rpi-source/wiki and run rpi-source to get current kernel headers. Alternatively upgrade/downgrade kernel and reinstall kernel headers.
	```sh
	$ ls /lib/modules/$(uname -r)/build
	```

* Additional Tools
	* Raspi-gpio utility:
		```sh
		$ sudo apt install raspi-gpio
		```
	* Bluetooth Stack and utilities:
		```sh
		$ sudo apt install pi-bluetooth
		```

#### 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.
	```sh
	$ ls /lib/modules/$(uname -r)/build
	```

* 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
	* Protobuf:  
	  :warning:`Note: We have tested ESP-Hosted solution with Protobuf version >= 3.13.0`
		```
		$ pip install protobuf
		or
		$ pip3 install protobuf
		```
	* Bluetooth Stack and utilities:  
	  :warning:`Note: We have tested ESP-Hosted solution with bluez 5.43 and 5.45`
		* bluetooth
		* bluez
		* bluez-tools
		* rfkill
		* bluez-firmware

### 2.2 ESP-IDF Setup
:warning:`Note: ESP-IDF is needed to compile ESP-Hosted firmware source. Skip this step if you are planning to use pre-built release binaries.`  

ESP-IDF release version to be used for ESP peripherals are

| ESP peripheral | ESP-IDF release |
|:----:|:----:|
| ESP32 | release v4.0 |
| ESP32-S2 | release v4.2 |

Clone appropriate ESP-IDF version as per your ESP peripheral. The control path between Linux host and ESP peripheral is based on `protobuf`. For that, corresponding stack layer, `protocomm` from ESP-IDF is used. Run following command in ESP-IDF directory to make `protocomm_priv.h` available for control path.
```
$ git mv components/protocomm/src/common/protocomm_priv.h components/protocomm/include/common/
```

### 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
```

### 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](SDIO_setup.md)

* [Wi-Fi and BT/BLE connectivity Setup over SPI](SPI_setup.md)

* [Bluetooth/BLE connectivity Setup over UART](UART_setup.md)


# 3. ESP-Hosted Usage Guide

Following guide explains how to use ESP-Hosted solution.
* [User Guide for ESP-Hosted with Linux Host](./Getting_started.md)


# 4. ESP-Hosted Porting Guide to other Linux Platforms

Following document explains guidelines for porting solution to othe Linux platforms
* [Porting Guide](./porting_guide.md)
Commit	Line	Data
374f085e	1	# Getting Started with Linux based host
f8091577 YM	2
	3	Below diagram shows hardware and software block diagram for a typical linux based system built with ESP-Hosted.
	4
	5	![ESP-Hosted linux based design](./linux_hosted_design.png)
	6
374f085e MM	7	This document explains ESP-Hosted setup and usage. The document is divided in two parts:
	8	* [Quick Start Guide](#1-quick-start-guide)
	9	This section briefly explains ESP-Hosted setup. One can refer this guide to quickly prepare and test ESP-Hosted solution,
f8091577	10
374f085e MM	11	* [ESP-Hosted Comprehensive Guide](#2-esp-hosted-comprehensive-guide)
	12	This section provides in depth information about ESP-Hosted setup, available customization options etc.
	13
	14	# 1. Quick Start Guide
	15	* With the help of this guide, one can easily setup and start using ESP-Hosted solution with Raspberry-Pi as a host.
	16	* This section makes use of pre-built ESP firmware release binaries and default configuration.
	17	* Please refer [ESP-Hosted Comprehensive Guide](#2-esp-hosted-comprehensive-guide) for more details and customization options.
	18
	19	### 1.1 Hardware Requirements
	20	* Raspberry-Pi model 3 Model B/B+ or Raspberry-Pi 4 model B
	21	* ESP32 board
	22	* 8-12 jumper wires of 10cm length
	23
	24	### 1.2 Host Setup
	25	Make sure that Raspberry-Pi is equipped with following:
	26	* Linux Kernel Headers are installed
	27	```sh
	28	$ sudo apt update
	29	$ sudo apt install raspberrypi-kernel-headers
	30	```
	31	* Following tools are installed on Raspberry-Pi:
	32	* Git
	33	* Raspi-gpio utility
	34	* bluetooth
	35	* bluez
	36	* bluez-tools
	37	* rfkill
	38	* bluez-firmware
	39	* pi-bluetooth
	40	```sh
	41	$ sudo apt install git raspi-gpio bluetooth bluez bluez-tools rfkill bluez-firmware pi-bluetooth
	42	```
	43	* Python Requirement
	44	* Python 2.x or 3.x
	45	```sh
	46	$ sudo apt install python
	47	or
	48	$ sudo apt install python3
	49	```
	50	* Protobuf
	51	```sh
	52	$ pip install protobuf
	53	or
	54	$ pip3 install protobuf
	55	```
	56	* Clone ESP-Hosted code repository
	57	```
	58	$ git clone --recurse-submodules <url_of_esp_hosted_repository>
	59	$ cd esp-hosted
	60	$ git submodule update --init --recursive
	61	```
	62	* Download pre-built ESP-Hosted firmware release binaries from [releases](https://github.com/espressif/esp-hosted/releases)
	63
	64
	65	### 1.3 Setup
	66
	67	Prepare connections based on interface requirements and setup host as below.
	68
	69	* Wifi and Bluetooth over SDIO
	70	* Connection Setup
	71	* Prepare connections as per section [1.1 Hardware Setup](SDIO_setup.md#11-hardware-setup) of [SDIO setup document](SDIO_setup.md)
	72	* Host Software
	73	* Prepare Raspberry-Pi as per section [1.2 Raspberry-Pi Software Setup](SDIO_setup.md#12-raspberry-pi-software-setup) of [SDIO setup document](SDIO_setup.md)
	74	* Compile and load host driver as below:
75	```sh
76	$ cd host/linux/host_control/
77	$ ./rpi_init.sh sdio
78	```
79	* Wifi and Bluetooth over SPI
80	* Connection Setup
81	* Prepare connections as per section [1.1 Hardware Setup](SPI_setup.md#11-hardware-setup) of [SPI Setup document](SPI_setup.md)
82	* Host Software
83	* Prepare Raspberry-Pi as per [1.2 Raspberry-Pi Software Setup](SPI_setup.md#12-raspberry-pi-software-setup) of [SPI Setup document](SPI_setup.md)
84	* Compile and load host driver as below:
85	```sh
86	$ cd host/linux/host_control/
87	$ ./rpi_init.sh spi
88	```
89	* Wifi over SDIO and Bluetooth over UART
90	* Connection Setup
91	* Prepare SDIO connections as per section [1.1 Hardware Setup](SDIO_setup.md#11-hardware-setup) of [SDIO setup document](SDIO_setup.md)
92	* Prepare UART connections as per section [1.1 Hardware Setup](UART_setup.md#11-hardware-setup) of [UART setup document](UART_setup.md)
93	* Host Software
94	* Prepare Raspberry-Pi for SDIO operations as per section [1.2 Raspberry-Pi Software Setup](SDIO_setup.md#12-raspberry-pi-software-setup) of [SDIO setup document](SDIO_setup.md)
95	* Prepare Raspberry-Pi for UART operations as per section [1.2 Raspberry-Pi Software Setup](UART_setup.md#12-raspberry-pi-software-setup) of [UART setup document](UART_setup.md)
96	* Compile and load host driver as below:
97	```sh
98	$ cd host/linux/host_control/
99	$ ./rpi_init.sh sdio btuart
100	```
101	* After loading ESP firmware, execute below command to create `hci0` interface
102	```sh
103	$ sudo hciattach -s 921600 /dev/serial0 any 921600 flow
104	```
105
106	#### 1.3.1 ESP Firmware Setup
107	* Flash pre-built binaries as below.
108	```sh
109	$ esptool.py -p <serial_port> -b 960000 --before default_reset --after hard_reset \
110	write_flash --flash_mode dio --flash_freq 40m --flash_size detect 0x8000 \
111	esp_hosted_partition-table_<esp_peripheral>_<interface_type>_v<release_version>.bin 0x1000 \
112	esp_hosted_bootloader_<esp_peripheral>_<interface_type>_v<release_version>.bin 0x10000 \
113	esp_hosted_firmware_<esp_peripheral>_<interface_type>_v<release_version>.bin
114
115	Where,
116	<serial_port> : serial port of ESP peripheral
117	<esp_peripheral> : esp32/esp32s2
118	<interface_type> : sdio/spi/sdio_uart
119	<release_version>: 0.1,0.2 etc
120	```
121
122	#### 1.3.2 Setup Validation
123	Once everything is setup and and host software and ESP firmware are loaded
124	* Verify that `ethsta0` and `ethap0` interfaces are seen on host using following command.
125	```sh
126	$ ifconfig -a
127	```
128	* Verify that hci0 interface is present using below command
129	```sh
130	$ hciconfig
131	```
132	* Proceed to section [3. ESP-Hosted Usage Guide](#3-esp-hosted-usage-guide) to test Wi-Fi and Bluetooth/BLE functionality.
133
134
135	# 2. ESP-Hosted Comprehensive Guide
136
137	### 2.1 Linux Host: Development Environment Setup
138	* This section list downs environment setup and tools needed to make ESP-Hosted solution work with Linux based host.
139	* If you are using Raspberry-Pi as a Linux host, both [section 2.1.1](#211-raspberry-pi-specific-setup) and [section 2.1.2](#212-additional-setup) are applicable.
140	* If you are using other Linux platform, skip to [section 2.1.2](#212-additional-setup)
141
142	#### 2.1.1 Raspberry-Pi Specific Setup
143	This section identifies Raspberry-Pi specific setup requirements.
f8091577	144
950e0ba1	145	* Linux Kernel Setup
374f085e MM	146	* We recommend full version Raspbian install on Raspberry-Pi to ensure easy driver compilation.
	147	* Please make sure to use kernel version `v4.19` and above. Prior kernel versions may work, but are not tested.
	148	* Kernel headers are required for driver compilation. Please install them as:
950e0ba1 MM	149	```sh
950e0ba1 MM	150	$ sudo apt update
374f085e	151	$ sudo apt install raspberrypi-kernel-headers
950e0ba1	152	```
374f085e	153	* 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/notro/rpi-source/wiki and run rpi-source to get current kernel headers. Alternatively upgrade/downgrade kernel and reinstall kernel headers.
950e0ba1 MM	154	```sh
	155	$ ls /lib/modules/$(uname -r)/build
	156	```
f8091577	157
374f085e MM	158	* Additional Tools
374f085e MM	159	* Raspi-gpio utility:
950e0ba1	160	```sh
374f085e	161	$ sudo apt install raspi-gpio
950e0ba1	162	```
374f085e	163	* Bluetooth Stack and utilities:
950e0ba1	164	```sh
374f085e	165	$ sudo apt install pi-bluetooth
950e0ba1 MM	166	```
950e0ba1 MM	167
374f085e MM	168	#### 2.1.2 Additional Setup
	169	* Linux Kernel setup on non Raspberry-Pi
	170	* Please make sure to use kernel version `v4.19` and above. Prior kernel versions may work, but are not tested.
	171	* Please install kernel headers as those are required for driver compilation.
	172	* Verify that kernel headers are installed properly by running following command. Failure of this command indicates that kernel headers are not installed correctly.
	173	```sh
	174	$ ls /lib/modules/$(uname -r)/build
	175	```
	176
	177	* Install following tools on Linux Host machine.
	178	* Git
	179	* Python 2.x or 3.x: We have tested ESP-Hosted solution with python 2.7.13 and 3.5.3
	180	* Protobuf:
	181	:warning:`Note: We have tested ESP-Hosted solution with Protobuf version >= 3.13.0`
950e0ba1 MM	182	```
	183	$ pip install protobuf
	184	or
	185	$ pip3 install protobuf
	186	```
374f085e MM	187	* Bluetooth Stack and utilities:
	188	:warning:`Note: We have tested ESP-Hosted solution with bluez 5.43 and 5.45`
	189	* bluetooth
	190	* bluez
	191	* bluez-tools
	192	* rfkill
	193	* bluez-firmware
950e0ba1	194
374f085e MM	195	### 2.2 ESP-IDF Setup
374f085e MM	196	:warning:`Note: ESP-IDF is needed to compile ESP-Hosted firmware source. Skip this step if you are planning to use pre-built release binaries.`
950e0ba1	197
374f085e	198	ESP-IDF release version to be used for ESP peripherals are
950e0ba1 MM	199
	200	\| ESP peripheral \| ESP-IDF release \|
	201	\|:----:\|:----:\|
	202	\| ESP32 \| release v4.0 \|
	203	\| ESP32-S2 \| release v4.2 \|
	204
	205	Clone appropriate ESP-IDF version as per your ESP peripheral. The control path between Linux host and ESP peripheral is based on `protobuf`. For that, corresponding stack layer, `protocomm` from ESP-IDF is used. Run following command in ESP-IDF directory to make `protocomm_priv.h` available for control path.
	206	```
374f085e	207	$ git mv components/protocomm/src/common/protocomm_priv.h components/protocomm/include/common/
950e0ba1 MM	208	```
950e0ba1 MM	209
374f085e	210	### 2.3 ESP-Hosted Code Repository
950e0ba1 MM	211	Clone esp-hosted repository on Linux host.
	212	```
	213	$ git clone --recurse-submodules <url_of_esp_hosted_repository>
	214	$ cd esp-hosted
	215	$ git submodule update --init --recursive
	216	```
	217
374f085e	218	### 2.4 ESP-Hosted Setup and Load Project
950e0ba1 MM	219
	220	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.
	221
	222	* [Wi-Fi and BT/BLE connectivity Setup over SDIO](SDIO_setup.md)
	223
	224	* [Wi-Fi and BT/BLE connectivity Setup over SPI](SPI_setup.md)
	225
	226	* [Bluetooth/BLE connectivity Setup over UART](UART_setup.md)
	227
	228
374f085e	229	# 3. ESP-Hosted Usage Guide
950e0ba1 MM	230
	231	Following guide explains how to use ESP-Hosted solution.
	232	* [User Guide for ESP-Hosted with Linux Host](./Getting_started.md)
374f085e MM	233
	234
	235	# 4. ESP-Hosted Porting Guide to other Linux Platforms
	236
	237	Following document explains guidelines for porting solution to othe Linux platforms
	238	* [Porting Guide](./porting_guide.md)