Skip to content

Filesystem

Each Zerynth hardware features an internal flash of at least 16 MB, part of which is reserved for an internal filesystem. The filesystem module is also capable of handling SD cards formatted with FAT.

The internal filesystem is based on LittleFS, that guarantees wear leveling, bad block detection, and resistance to corruption from power loss or crashes.

The internal filesystem is automatically mounted to /zerynth root at startup.

The internal filesystem can also be automatically formatted and loaded with files or folders when running a project. It can be done by simply adding a resources folder into the Zerynth project. All the contents of the folder are packed and transferred into the internal filesystem together with the firmware.

Note

In general the fs module do not write immediately to the underlying support. Write operations are guaranteed to be finalized either when the file is close or when an explicit synchronization is manually requested.

FS Functions

The fs module provides many functions for mounting and managing a filesystem. It also provide classes for streamlining operation on files.

function mount

mount(prefix, what=INTERNAL, spiclk=2000000)

Mounts a storage device.

  • prefix: The path to use as mountpoint

  • what: The device to mount. Valid values:

  • INTERNAL: for on-borad flash memory.
  • SD: for MicroSD card. Only FAT filesystem is supported.

  • spiclk: The clock in Hz for the SPI bus where the MicroSD is attached to.

Can raise:

  • FSNoSuchMountpointError
  • FSCantMountError
  • FSNoMoreMountpointsError
  • FSFileAlreadyExistsError
  • FSFileDoesNotExistError

All of the above have IOError as parent.

function unmount

unmount(prefix)

Unmount a storage device.

  • prefix: The mountpoint to unmount.

function path

path(*args)
Creates a path with the correct format composing the given *args.

  • *args is any number of consecutive strings that will be used to create the path.

Returns a string with the new path.

function open

open(path, mode)

Opens or create a file at path.

  • path is a string (following chosen low-level filesystem driver format).

  • mode is a string composed by one or more of the following characters:

  • 'r' open for reading (default)

  • 'w' open for writing, truncating the file first
  • 'a' open for writing, appending to the end of the file if it exists
  • 'b' binary mode
  • '+' open a disk file for updating (reading and writing)

Return an instance of FileIO or raises IOError.

function rm

rm(path)
Removes a file on a given path.

  • path is a string (following chosen low-level filesystem driver format).

function rmtree

rmtree(path)
Removes a directory and all subdirectories and files.

  • path is a string (following chosen low-level filesystem driver format).

function ls

ls(path)
Lists directory contents of a given path.

  • path is a string (following chosen low-level filesystem driver format).

Returns a dictionary of the contents with the following format { "entry_name": "type",}. type can be "d" if the entry is a directory or "-" if it is a file.

function copy

copy(src, dest)
Creates a copy of the src file in the dest path.

  • src is a string with the source file path (following chosen low-level filesystem driver format).

  • dest is a string with the destination file path (following chosen low-level filesystem driver format).

function move

move(src, dest)
Moves the src file in the dest path.

  • src is a string with the source file path (following chosen low-level filesystem driver format).

  • dest is a string with the destination file path (following chosen low-level filesystem driver format).

function exists

exists(src)
Returns True if the specified src path exists. False otherwise.

  • src is a string with the source file path (following chosen low-level filesystem driver format).

function md5

md5(src)
Calculates the MD5 hash of a file.

  • src is a string with the source file path (following chosen low-level filesystem driver format).

Returns a 32 byte string with the calculated MD5 hash.

function write_file

write_file(path, content)
Writes content on a specified file on path. This functions opens the file in "w+", writes content and closes the file.

  • path is a string (following chosen low-level filesystem driver format).

  • content is a string with the file content to write.

function read_file

read_file(path)
Reads all the content of a file on path. This function opens the file in "r", reads all its content and closes the file.

  • path is a string (following chosen low-level filesystem driver format).

Returns a string with the content of the file.

function mkdir

mkdir(path)
Creates a directory.

  • path: is a string referring to the directory to be created.

function rmdir

rmdir(path)
Remove a directory.

  • path: is a string referring to the directory to be removed.

function rm

rm(path)

Remove a file.

  • path is a string referring to the file to be removed.

The FileIO class

class FileIO

FileIO(path, mode = 'r')

Main class to handle files.

  • path is a string (following chosen low-level filesystem driver format)

  • mode is a string composed by one or more of the following characters:

  • 'r' open for reading (default)

  • 'w' open for writing, truncating the file first
  • 'a' open for writing, appending to the end of the file if it exists
  • 'b' binary mode
  • '+' open a disk file for updating (reading and writing)

method read

read(n_bytes = -1)

Read up to size bytes from the object and return them. As a convenience, if size is unspecified or -1, the whole file is read.

Return type can be string or bytes depending on chosen mode.

An empty string or an empty bytes object indicate end of file.

method read_into

read_into(buf, ofs=0, sz=0)

Read bytes from file into buf starting from offset ofs and reading sz bytes.

Return type can be string or bytes depending on chosen mode.

An empty string or an empty bytes object indicate end of file.

Raise IOError if ofs or sz generates overflow.

method write

write(to_w, sync = False)

Write to_w object (string or bytes) to the stream and return the number of characters written.

  • sync parameter allows to write changes to disk immediately, without waiting for close call.

method close

close()

Close file

method size

size()

Return file size in bytes

method tell

tell()

Return the current stream position.

method seek

seek(offset, whence=SEEK_SET)

Move the current position to offset bytes with respect to whence.

whence can be:

  • SEEK_SET: start of file
  • SEEK_CUR: current position
  • SEEK_END: end of file

method readline

readline(max_len=256, end="\r\n", with_end=True):

Read until newline or EOF and return a single string. The maximum length of the line is defined by max_len. The characters to be used as end of line are in end. The line end character is returned by default together with the line but this behavior can be controlled by the with_end parameter. If the stream is already at EOF, an empty string is returned.

Examples

The internal filesystem is always mounted at boot and ready to be used. Put a test.txt file inside the resources folder of a project and test the following.

import fs

while True:

    # read an existing file in read mode
    f = fs.open("/zerynth/test.txt", "r")
    # read it all and print it
    print(f.read()) 
    # close the file
    f.close()

    # create a new file and read it back
    f = fs.open("/zerynth/test02.txt","w")
    f.write("first row: test 01\n")
    f.write("second row: test 02\n")
    f.close()

    f = fs.open("/zerynth/test02.txt", "r")
    print(f.read())
    f.close()

    sleep(5000)

Filesystem can also be used on SD cards by simply mounting them.

import fs

while True:
    # mount the sd card under /sd on a 10 MHz SPI bus
    fs.mount("/sd", fs.SD, 10000000)

    # read an existing file
    try:
        f = fs.open("/sd/test.txt", "r")
        print(f.read())
        f.close()
    except Exception as e:
        print("Can't read /sd/test.txt")

    # create a new file and read it back
    f = fs.open("/sd/test02.txt","w")
    f.write("first row: test 01\n")
    f.write("second row: test 02\n")
    f.close()

    f = fs.open("/sd/test02.txt","r")
    print(f.read())
    f.close()

    # Unmount the sd card
    fs.unmount("/sd")

    sleep(5000)