.. _storage_zephyr:

Filesystems and Storage
=======================

Storage modules support virtual filesystem with FAT and littlefs formats, backed by either
Zephyr DiskAccess or FlashArea (flash map) APIs depending on which the board supports.

See `vfs Filesystem Mounting <https://docs.micropython.org/en/latest/library/vfs.html?highlight=vfs#filesystem-mounting>`_.

Automatic Filesystem Mounting
------------------------------

MicroPython on Zephyr automatically attempts to mount available storage at startup:

1. **Flash storage** (if available): Automatically mounted at ``/flash`` using the
   littlefs2 filesystem. If the filesystem doesn't exist, it will be created
   automatically.

2. **Disk storage** (such as SD cards): Automatically detected and mounted at
   ``/<disk_name>`` (e.g., ``/sd`` for SD cards).

3. **Working directory**: The working directory is set to the mounted disk if
   available, otherwise to ``/flash`` if flash storage is available.

4. **Module search path**: The ``sys.path`` is automatically updated to include
   ``/<disk>/lib`` for each mounted disk and ``/flash/lib`` for flash storage.

This automatic mounting is performed by the ``_boot.py`` module at startup. For most
use cases, you don't need to manually mount filesystems.

Disk Access
-----------

The :ref:`zephyr.DiskAccess <zephyr.DiskAccess>` class can be used to access storage devices, such as SD cards.
This class uses `Zephyr Disk Access API <https://docs.zephyrproject.org/latest/reference/storage/disk/access.html>`_ and
implements the `vfs.AbstractBlockDev` protocol.

For use with SD card controllers, SD cards must be present at boot & not removed; they will
be auto detected and initialized by filesystem at boot. Use the disk driver interface and a
file system to access SD cards via disk access (see below).

The available disk names can be accessed via the ``DiskAccess.disks`` attribute, which contains
a tuple of available disk names (e.g., ``('SDHC',)`` or ``('SD',)``).

Example usage of FatFS with an SD card on the mimxrt1050_evk board::

    import vfs
    from zephyr import DiskAccess

    # List available disks
    print(DiskAccess.disks)                 # prints available disk names, e.g., ('SDHC',)

    bdev = DiskAccess('SDHC')               # create block device object using DiskAccess
    vfs.VfsFat.mkfs(bdev)                   # create FAT filesystem object using the disk storage block
    vfs.mount(bdev, '/sd')                  # mount the filesystem at the SD card subdirectory
    with open('/sd/hello.txt','w') as f:    # open a new file in the directory
        f.write('Hello world')              # write to the file
    print(open('/sd/hello.txt').read())     # print contents of the file

Note: In most cases, disks are automatically mounted at startup and manual mounting is not necessary.


Flash Area
----------

The :ref:`zephyr.FlashArea <zephyr.FlashArea>` class can be used to implement a low-level storage system or
customize filesystem configurations. To store persistent data on the device, using a higher-level filesystem
API is recommended (see below).

This class uses `Zephyr Flash map API <https://docs.zephyrproject.org/latest/reference/storage/flash_map/flash_map.html#>`_ and
implements the `vfs.AbstractBlockDev` protocol.

The available flash area names can be accessed via the ``FlashArea.areas`` dictionary, which maps partition
labels to their IDs (e.g., ``{'storage': 1, 'scratch': 4}``).

Example usage with the internal flash on the reel_board or the rv32m1_vega_ri5cy board::

    import vfs
    from zephyr import FlashArea

    # List available flash areas
    print(FlashArea.areas)                          # prints available areas, e.g., {'storage': 1, 'scratch': 4}

    bdev = FlashArea(FlashArea.areas['storage'], 4096)   # create block device object using FlashArea
    vfs.VfsLfs2.mkfs(bdev)                               # create Little filesystem object using the flash area block
    vfs.mount(bdev, '/flash')                            # mount the filesystem at the flash storage subdirectory
    with open('/flash/hello.txt','w') as f:              # open a new file in the directory
        f.write('Hello world')                           # write to the file
    print(open('/flash/hello.txt').read())               # print contents of the file

Note: In most cases, the flash storage partition is automatically mounted at ``/flash`` at startup with
automatic filesystem creation if needed, so manual mounting is not necessary.

For boards such as the frdm_k64f in which the MicroPython application spills into the default flash storage
partition, use the scratch partition by replacing ``'storage'`` with ``'scratch'``.