# esp-vfs

**Repository Path**: esp-components/esp-vfs

## Basic Information

- **Project Name**: esp-vfs
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-08-16
- **Last Updated**: 2022-05-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## Espressif VFS Device Bus Solution Overview

* [中文版](./README_CN.md)

ESP-VFS-DEV-BUS is a solution for high-speed peripherals of ESP chips. Its design goal is to provide stable and reliable drivers and provide a set of unified interfaces to the upper layer application. Users can access these peripherals like ordinary files, simplifying the driver development. 


![](docs/_static/vfs_dev_bus.jpg)

The POSIX defines the interface standard for application to access files. The ESP-VFS-DEV-BUS accesses each peripheral as a file. In addition to the basic `open/read/write` interface, it also supports the `select` interface to block and wait til a peripheral event occurs. This mechanism can simplify driver process and reduce the complexity of programming.

Taking the use of SPI slave peripherals as an example, the correspondence between the POSIX interfaces and the ESP-VFS-DEV-BUS library is as the following table:

| Application              | ESP-VFS-DEV-BUS                                              |
| ------------------------ | ------------------------------------------------------------ |
| esp_vfs_dev_spi_register | Register the implementation of the SPI slave related to the POSIX interface |
| open                     | Initialize SPI peripherals, create SPI receive task (used to receive data sent by SPI master) |
| select                   | After SPI receive task receives data, it will cache the data and unblock the `select` function.  |
| read                     | Let the upper layer read the cached data  |
| write                    | Send data via SPI interface |

1. Application calls `esp_vfs_dev_spi_register` to register the use of SPI peripheral. ESP-VFS-DEV-BUS will register the implementation of the POSIX-related interfaces of SPI peripheral. The main work of ESP-VFS-DEV-BUS is to adapt the characteristics of different peripherals to unified POSIX interfaces.

2. After registering the SPI peripheral, the application can call the `open` interface to open it. ESP-VFS-DEV-BUS will initialize the SPI peripheral and create a task to receive data. This task will receive the data sent by the SPI master, buffer it and unblock the `select` in time. 
3. The application is blocked in the `select` function, and it will be unblocked after SPI slave receives the data.
4. The application can read the data by calling `read` function. Since the data may not be read all at once, ESP-VFS-DEV-BUS needs to cache the data first.
5. The application can send data by calling `write` function, but in the SPI protocol, the SPI slave cannot actively send data to SPI master. Therefore, ESP-VFS-DEV-BUS adds an extra pin to notify the SPI master to read data that sent from SPI slave.

### ESP-VFS-DEV-BUS Structure 

The main directory structure of ESP-VFS-DEV-BUS is as follows. 

```
.
├── docs            # documents, including upper-level protocol documents for different peripherals
├── examples        # MCU and ESP device communication examples
│   ├── host        # MCU example
│   │   └── common  # MCU interactive protocol code, needs to be ported to your own MCU platform
│   └── slave       # ESP device example
├── include         # Header files for upper-level applications
├── include_private # Header files for device drivers in the `src` directory
└── src             # ESP device driver code, each peripheral corresponds to a file
```


1. `docs` contains the implementation protocol documents of different peripherals of different ESP chips, and introduces the communication principle and test rate of the peripherals. It is suggested that you can read corresponding documents before adapting the selected peripherals to your own MCU.
2. `examples` contains the test cases of ESP-VFS-DEV-BUS. Since the implementation of peripheral communication requires the cooperation of both host side and slave side, the two directories `host` and `slave` are included in the example. And both of them are required for testing, you need to burn the demos of same peripheral in corresponding directories. The `host` directory also contains the `common` subdirectory. This directory contains the host-side reference code of different peripherals. You can refer to the implementation in this directory when adapting to other MCU platform.
3. `include` contains header files for upper-level applications.
4. `include_private` contains header files used internally by device drivers in the `src` directory.
5. `src` is the implemetations of different peripherals as slaves, and the adaptation of the ESP-VFS-DEV-BUS interfaces.

## User Guide

Take the SPI peripheral of ESP32-C3 as an example, the corresponding document is `docs/ESP32_SERIES_SPI_USAGE_CN.md`. The document describes the IO pins required for communication between ESP32-C3 and ESP32, and the maximum speed that the peripheral can achieve under the current driver.

The esp-vfs-dev-bus itself does not specify the esp-idf version, but it is recommended to use the official release version. This guide uses the esp-idf v4.3-beta1 version, and the esp-idf has been installed and configured by default. If your system does not have esp-idf installed, please refer to esp-idf
[Get-Started](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html) to install esp-idf firstly.

First connect ESP32 and ESP32-C3 according to the pin description, and then start to test the `echo_demo`。

**ESP32 Side:**

Execute the following command in the root directory of esp-vfs-dev-bus.

```
$ cd example/host/echo_demo
```

Open the menuconfig:

```
$ idf.py menuconfig
```

In the menuconfig, select platform ESP32-C3 （`Driver platform Configuration-> Select slave platform -> Using ESP32 series(S2/C3)`）。

In `Driver platform Configuration`, you can select standard SPI, or Dual SPI, or Quad SPI mode. 

Build and flash the project into ESP32 module by following command:

```
$ idf.py -p <serial_port> build flash
```

Please set your actual `<serial_port>` in the above command.

**ESP32-C3 Side**

The compilation of ESP32-C3 is similar to the ESP32. First, execute the following command in the esp-vfs-dev-bus root directory to enter the corresponding directory of slave.

```
$ cd example/slave/echo_demo
```

Set target platform to ESP32-C3:

```
$ idf.py set-target esp32c3
```

Open menuconfig:

```
$ idf.py menuconfig
```

In the menuconfig, set the communication interface to be SPI （`Component config -> VFS_DEV_BUS -> communicate device for VFS -> VFS through SPI`）。

In `VFS_DEV_BUS`, select the same mode according to the SPI mode (standard SPI, Dual SPI or Quad SPI) configured in ESP32 side.

Build and flash the project into ESP32-C3 module by following command:

```
$ idf.py -p <serial_port> build flash
```

Please set your actual `<serial_port>` in the above command.

## MCU Side

### Why we need to adapt it on MCU side

Although it is standard POSIX interfaces that the ESP to the upper layer, the MCU still needs to follow a certain protocol when communicating with the ESP. We call it the upper layer interactive protocol. The adaptation of MCU is how to implement the upper layer interactive protocol on your own MCU platform. It is mainly due to the requirements of the peripheral itself. For example, if you choose to communicate via SPI, the SPI master needs to read and write some shared registers to obtain the data length, and an additional handshake line is required to obtain the information actively sent by the slave (ESP device).

### MCU driver abstract interfaces

In order to facilitate the test on MCU side, we also encapsulated the code on the MCU side. The process is shown in the figure below.

![](docs/_static/host_dev.jpg)

MCU calls `host_serial_bus_xxx` function, according to the peripherals opened by `open` function, corresponding interfaces will be called to communicate with the ESP device.

The goal of current MCU implementation is to use the same interfaces to test different peripherals. During your specific MCU adaptation process, you can decide whether to keep it or not according to your actual application.

For the SPI communication of ESP8266, see [ESP8266_SPI_USAGE](docs/ESP8266_SPI_USAGE.md) .

For details about SPI communication of ESP32-x series chips (excluding EPS32), see [ESP32_SERIES_SPI_USAGE](docs/ESP32_SERIES_SPI_USAGE.md) .

### MCU adaptation method

The adaptation of MCU is how to implement the upper layer interactive protocol on your own MCU platform. We provide a host MCU example based on ESP32 as the reference code. The example code is located in the directory `example/common`. You can find the corresponding example code according to the actual driver you choose.

In addition, for each peripheral, corresponding documents are included in the `docs` directory, explaining the implementation of the interactive protocol. It is recommended to read these documents before adapting.

For ESP8266 SPI  , please 

## Supported peripherals 

The current ESP-VFS-DEV-BUS supports following peripherals.

|          | SPI Slave | SDIO slave |
| -------- | --------- | ---------- |
| ESP8266  | √         |            |
| ESP32    |           | √          |
| ESP32-S2 | √         |            |
| ESP32-C3 | √         |            |