file_service

Example of the component espressif/esp_iris v0.2.0
# Bounded file service

This dual-CDC USB example mounts a wear-levelled FAT filesystem and exports it as
the logical volume `fs`. It enables read, list, mtime, write/hash, mkdir,
delete, and rename. It deliberately does not advertise atomic replacement,
because the example does not assume that property from the FAT VFS.

The custom layout requires a 2 MB or larger flash device. A full flash may
format the `storage` partition; verify the target before flashing.

## Standalone setup

Create this example from the Component Registry, then run the commands below
from its directory:

```bash
idf.py create-project-from-example "espressif/esp_iris=0.2.0:file_service"
cd file_service
```

With a source checkout, change to `ESP-Iris/components/esp_iris/examples/file_service`
from the repository root instead. These application USB examples require an SDK
supporting ESP32-S31; the release matrix uses the pinned IDF 6.2 revision.
After the first build downloads the component, prepare its bundled Gateway:

```bash
python esp_iris.py setup
python esp_iris.py doctor
python esp_iris.py web
```

The launcher uses an isolated cached environment and does not change the IDF
Python environment. Close the Gateway before flashing or monitoring its ports.

## Build and flash

```bash
idf.py \
  -B build-file-service build
idf.py \
  -B build-file-service -p /dev/serial/by-id/<programming-port> flash
```

CDC0 carries text logs and Iris commands; CDC1 carries file data. Stock
`idf.py monitor` can use CDC0 when Gateway releases it. Flash through the
board's ROM download interface.

## Exercise the volume

The Workbench file browser exposes every operation below. The same API can be
driven with `curl` after replacing `DEVICE_ID`:

```bash
BASE=http://127.0.0.1:8443/v2/devices/DEVICE_ID
curl "$BASE/files/volumes"
curl "$BASE/files?volume=fs&path="
curl "$BASE/files/stat?volume=fs&path=README.txt"
curl -o README.txt "$BASE/file?volume=fs&path=README.txt"
curl -H 'Range: bytes=0-15' -o README.prefix \
  "$BASE/file?volume=fs&path=README.txt"
curl -X POST -H 'Content-Type: application/json' \
  -d '{"volume":"fs","path":"demo"}' "$BASE/directories"
curl -X PUT --data-binary @README.txt \
  "$BASE/file?volume=fs&path=demo/upload.txt"
sha256sum README.txt
curl -X POST -H 'Content-Type: application/json' \
  -d '{"volume":"fs","source":"demo/upload.txt","destination":"demo/moved.txt"}' \
  "$BASE/file-rename"
curl -X DELETE "$BASE/file?volume=fs&path=demo/moved.txt"
curl -X DELETE "$BASE/file?volume=fs&path=demo"
```

The upload response contains `sha256`; compare it with the local `sha256sum`
output. Uploads are streamed with strict offsets and SHA-256 verification.
Replacement of an existing file is rejected because this volume omits
`ATOMIC_REPLACE`.

Return to the [example index](../README.md).

To create a project from this example, run:

idf.py create-project-from-example "espressif/esp_iris=0.2.0:file_service"

or download archive (~4.00 KB)