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)

FS Functions​

function mount​

function unmount​

function path​

function open​

function rm​

function rmtree​

function ls​

function copy​

function move​

function exists​

function md5​

function write_file​

function read_file​

function mkdir​

function rmdir​

function rm​

The FileIO class​

class FileIO​

method read​

method read_into​

method write​

method close​

method size​

method tell​

method seek​

method readline​

Examples​

FS Functions

function `mount`

function `unmount`

function `path`

function `open`

function `rm`

function `rmtree`

function `ls`

function `copy`

function `move`

function `exists`

function `md5`

function `write_file`

function `read_file`

function `mkdir`

function `rmdir`

function `rm`

The FileIO class

class `FileIO`

method `read`

method `read_into`

method `write`

method `close`

method `size`

method `tell`

method `seek`

method `readline`

Examples