# 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

* [English Version](./README.md)

ESP-VFS-DEV-BUS 组件是 ESP 高速外设的抽象化解决方案，其设计目标是提供稳定可靠的驱动程序，并对外提供统一的接口，用户可以像操作普通文件一样来访问这些外设，简化驱动的开发流程。

其原理如图所示

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

POSIX 标准定义了应用程序访问文件的接口标准。在 ESP-VFS-DEV-BUS 组件中，将每一个外设作为文件进行访问，除了基本的 open/read/write 接口， 还可以使用 select 接口阻塞等待某个外设事件发生，这种机制可简化驱动流程，降低编程的复杂度。

以 SPI slave 外设的使用为例，POSIX 接口与 ESP-VFS-DEV-BUS 库之间的对应关系如下所示：

| Application              | ESP-VFS-DEV-BUS                                              |
| ------------------------ | ------------------------------------------------------------ |
| esp_vfs_dev_spi_register | 注册 POSIX 接口相关的 SPI slave 接口实现                     |
| open                     | 初始化 SPI 外设，创建 SPI 接收 task（用于接收 SPI master 发送的数据） |
| select                   | SPI 接收 task 收到数据后会缓存数据，并解除 select 阻塞       |
| read                     | 将缓存的数据抛给上层                                         |
| write                    | 将数据调用 SPI 发送接口发送                                  |

1. 应用程序调用 esp_vfs_dev_spi_register 注册使用 SPI 外设。ESP-VFS-DEV-BUS 会注册 POSIX 接口相关的 SPI 接口实现，而 ESP-VFS-DEV-BUS 的主要工作是针对不同外设的特点适配成统一的 POSIX 接口 。
2. 应用程序在注册完 SPI 外设后可以调用 open 接口打开， ESP-VFS-DEV-BUS 会初始化 SPI 外设，创建一个接收数据的 task， 这个 task 将会接收 SPI master 发送的数据，缓存并及时解除 select 的阻塞状态。
3. 应用程序阻塞在 select 函数， SPI slave 收到数据后会解除阻塞。
4. 应用程序调用 read 即可以读取数据，因为可能一次不会读完，因此 ESP-VFS-DEV-BUS 需要先缓存数据。
5. 应用程序调用 write 接口可以发送数据，但是在 SPI 协议中， slave 无法主动发送数据，因此，ESP-VFS-DEV-BUS 还加入了一个额外的管脚用于通知 SPI master 读取数据。

### ESP-VFS-DEV-BUS 组织结构

ESP-VFS-DEV-BUS 组件的主要目录结构如下所示

```
.
├── docs            # 文档，包括不同外设的上层协议文档
├── examples        # MCU 和 ESP 设备通信示例
│   ├── host        # MCU 侧示例程序
│   │   └── common  # MCU 侧交互协议代码，需要移植到自己的 MCU 平台
│   └── slave       # ESP 设备侧示例程序
├── include         # 头文件目录，供上层应用使用
├── include_private # 头文件目录，供 src 目录的设备驱动使用
└── src             # ESP 设备驱动代码，每个外设对应一个文件
```

其中：

1. `docs` 目录包含了不同 ESP 芯片的不同外设的实现协议文档，介绍了外设的通信原理，测试速率等。在选定外设适配到自己的 MCU 时首先需要先阅读对应的文档。
2. `examples` 目录下包含了 VFS 的测试用例，因为实现的外设通信需要 host 侧和 slave 侧相互配合才可以完成，因此在 example 下包含了  `host` 和 `slave` 两个目录，在测试时两者需要烧录对应目录下相同的 demo。 `host` 目录下还包含了 `common` 子目录，这个目录中包含了不同外设的 host 侧参考代码，在适配时需要参考此目录下对应外设的实现。
3. `include` 目录下包含了对外的头文件信息。
4. `include_private` 目录下是内部使用的头文件信息。
5. `src` 目录是不同外设作为从机（slave）的具体实现，以及 VFS 接口的适配。

## 使用方法

以使用 ESP32-C3 的 SPI 外设为例，其对应的文档为 `docs/ESP32_SERIES_SPI_USAGE_CN.md` ，文档中说明了 ESP32-C3 与 ESP32 通信所需使用的 IO 管脚，并给出了外设在当前驱动下能达到的最高速率。

esp-vfs-dev-bus 组件本身并没有指定 esp-idf 版本，但是建议采用正式 release 版本，本测试使用 v4.3-beta1 版本，此处默认已经安装和配置好了 IDF，如果系统没有安装 esp-idf， 请参考 esp-idf 的[入门文档](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html)。

首先 ESP32 和 ESP32-C3 按照管脚说明连接在一起，然后开始测试 `echo_demo`。

**ESP32 侧**

在 esp-vfs-dev-bus 根目录下执行以下命令

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

打开配置窗口

```
$ idf.py menuconfig
```

在配置窗口，勾选目标平台为 ESP32-C3 （`Driver platform Configuration-> Select slave platform -> Using ESP32 series(S2/C3)`）。

在 `Driver platform Configuration` 配置项，还可以选择使用标准 SPI， Dual SPI 或者 Quad SPI 模式。

编译并烧录工程

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

其中， <serial_port> 替换为实际的串口号即可。

**ESP32-C3 侧**

ESP32-C3 侧的编译与 ESP32 侧类似，首先在 esp-vfs-dev-bus 根目录下执行以下命令进入 slave 对应目录

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

配置当前平台为 ESP32-C3

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

打开配置窗口

```
$ idf.py menuconfig
```

在配置窗口，选择通信接口为 SPI （`Component config -> VFS_DEV_BUS -> communicate device for VFS -> VFS through SPI`）。

在 `VFS_DEV_BUS` 配置项中，根据 ESP32 配置的 SPI 模式（标准 SPI， Dual SPI 和 Quad SPI）选择相同模式。

编译并烧录工程

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

其中， <serial_port> 替换为实际的串口号。

## MCU 适配

### 为什么需要适配

虽然 ESP 侧对上层是标准的 POSIX 接口，但是 MCU 跟 ESP 通信时同样需要遵循一定的协议，我们把这部分称为上层交互协议。其主要原因是外设本身的要求，如 SPI master 需要读写一些共享寄存器才能获取长度信息，需要额外的 handshake 线来获取 ESP 设备主动发送的信息等。

### MCU 驱动抽象接口

为了便于 MCU 侧的测试，我们同样对 MCU 侧的代码进行了封装。其流程如下图所示：

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

MCU 调用 host_serial_bus_xxx 相关的接口，根据 open 打开的外设，会调用具体的接口与 ESP 设备进行通信。

目前这种方式只是为了使用相同接口测试不同的外设，在具体 MCU 适配过程中，可以根据自己实际应用决定是否保留。

### 适配方法

MCU 的适配工作即如何在自己的平台上实现这层交互协议，我们提供了 ESP32 作为 MCU 的参考代码，代码位于 `example/common` 目录下。可以根据自己选择的驱动去查找对应的代码。

另外，对于每一种外设， `docs` 目录下包含了相应的文档，说明了交互协议的实现原理，在适配之前，建议首先阅读此文档。

对于 ESP8266 的 SPI 通信，请参考： [ESP8266 SPI 使用方法](docs/ESP8266_SPI_USAGE_CN.md) 。

对于 ESP32-x 系列芯片（不包含 EPS32）的 SPI 通信，请参考： [ESP32 series 使用方法](docs/ESP32_SERIES_SPI_USAGE_CN.md) 。

## 支持的设备

目前 VFS_DEV 支持如下外设：

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