LittleFS Commands#

Simplicity Commander supports initializing and manipulating instances of LittleFS filesystem binary files using the commander littlefs commands. LittleFS is an open-source lightweight filesystem designed for microcontrollers, with features including power-loss resilience and flash wear leveling mechanisms.

For all littlefs commands where a LittleFS instance can be provided using the --infile option, the option can be omitted to instead let Commander extract the LittleFS instance from the device's flash. By default, Commander will look for the LittleFS instance in the device's main flash region, however a search start address or range can be specified using the --address or --range options, respectively.

When working with LittleFS instances off-device, Commander needs to be aware of certain device-specific details. The --device option is therefore required for all littlefs commands when a LittleFS instance is provided to Commander using the --infile option.

Initialize an Empty LittleFS Instance#

Initializing an empty LittleFS instance is done using the littlefs init command. The size of the instance must be specified by either setting the start address and the size using the --address and --size options, or by providing the range using the --range option. The LittleFS instance can be stored in .bin, .hex and .s37 file formats.

Command Line Syntax

$ commander littlefs init --outfile <filename> --device <device> [--address <address> --size <size> --range <address1:address2>]

Command Line Input Example

$ commander littlefs init --outfile lfs.hex --device SiWG917M111MGTBA --address 0x02100000 --size 0x40000

This command line initializes an empty LittleFS instance for an SiWG917 device, starting from address 0x02100000 with a size of 262144 bytes, and stores the instance in the file 'lfs.hex'.

Command Line Output Example

Empty LittleFS instance initialized and written to lfs.hex
DONE

Get Information About a LittleFS Instance#

Using the littlefs info command, information about the LittleFS instance can be retrieved. This information includes metadata about the LittleFS instance, as well as statistics about the storage use.

Command Line Syntax

$ commander littlefs info [--infile <filename> --device <device>]

Command Line Input Example

$ commander littlefs info --infile lfs.hex -dSiWG917M111MGTBA

This command line parses the LittleFS instance 'lfs.hex' and displays information about the instance to the console.

Command Line Output Example

Reading LittleFS instance from lfs.hex...
Parsing file lfs.hex...
LittleFS disk version  : 2.1
Block size (B)         : 4096
Max filename length (B): 255
Max filesize (B)       : 2147483647
Max attribute size (B) : 1022
Blocks in use          : 2/64 (3.13 %)
Storage used           : 128/262144 (0.05 %)
DONE

Dump a LittleFS Instance From Device#

Extracting a LittleFS instance from a device flash or from an application binary can be done using the littlefs dump command. If the --infile option is omitted, Commander will search for the LittleFS instance in the connected device's main flash. If the --infile option is provided, Commander will instead look for the LittleFS instance in the provided binary file.

Note: The LittleFS instance must be aligned to the start of a flash page/block.

Command Line Syntax

$ commander littlefs dump --outfile <filename> [--infile <filename> --device <device>]

Command Line Input Example

$ commander littlefs dump --outfile lfs.s37 --infile application.s37 --device SiWG917M111MGTBA

This command line parses the input file 'application.s37', extracts the LittleFS instance and saves it to the output file 'lfs.s37'.

Command Line Output Example

Reading LittleFS instance from application.s37...
Parsing file application.s37...
LittleFS instance written to lfs.s37.
DONE

List Contents in a LittleFS Instance#

Listing the files in a LittleFS instance can be done using the littlefs list command. The file sizes are printed with each file in the directory tree.

Command Line Syntax

$ commander littlefs list [--infile <filename> --device <device>]

Command Line Input Example

$ commander littlefs list --infile lfs.hex --device SiWG917M111MGTBA

This command line lists the files in the LittleFS instance 'lfs.hex'.

Command Line Output Example

Reading LittleFS instance from lfs.hex...
Parsing file lfs.hex...
Filesystem contents:
 /
 |  test-output/
 |  |  log.txt (132 B)
 |  lib/
 |  |  beep.mp3 (3827 B)
DONE

Add Files to a LittleFS Instance#

Adding files to a LittleFS instance is done using the littlefs add command. Singular files may be added using the --file option, whereas directories can be added using the --dir option. If any directories are specified, Commander will traverse those directories and recursively add all contained files and subdirectories, maintaining the directory structure in the resulting LittleFS instance.

All filenames/paths provided to Commander must be relative to the current working directory of Commander.

Command Line Syntax

$ commander littlefs add --outfile <filename> [--infile <filename> --device <device>] [--file <filename> --dir <directory>]

Command Line Input Example

$ commander littlefs add --outfile lfs.hex --infile lfs-empty.hex --device SiWG917M111MGTBA --file src/index.html --dir icons

This command line adds the file 'index.html' and the directory 'icons' (along with any contained files and subdirectories) to the LittleFS instance in 'lfs-empty.hex' and stores the updated LittleFS instance in 'lfs.hex'.

Command Line Output Example

Reading LittleFS instance from lfs-empty.hex...
Parsing file lfs-empty.hex...
Added file: /icons/templates/template.png
Added file: /icons/header.jpeg
Added file: /icons/ok.ico
Added file: /icons/thumbnail.png
Added file: /src/index.html
LittleFS instance written to lfs.hex.
DONE

Remove Files From a LittleFS Instance#

Removing files from a LittleFS instance is done using the littlefs remove command. Singular files may be removed using the --file option, whereas directories can be removed using the --dir option. If any directories are specified, Commander will traverse those directories and recursively remove all contained files and subdirectories.

All filenames/paths provided to Commander must be absolute with respect to the LittleFS instance's root directory, /.

Command Line Syntax

$ commander littlefs remove --outfile <filename> [--infile <filename> --device <device>] [--file <filename> --dir <directory>]

Command Line Input Example

$ commander littlefs remove --outfile lfs-new.hex --infile lfs.hex --device SIWG917M111MGTBA --file /src/index.html --dir /icons

This command line removes the file 'index.html' and the directory 'icons' (along with any contained files and subdirectories) from the LittleFS instance in 'lfs.hex' and stores the updated LittleFS instance in 'lfs-new.hex'.

Command Line Output Example

Reading LittleFS instance from lfs.hex...
Parsing file lfs.hex...
Removed file: /icons/templates/template.png
Removed directory: /icons/templates
Removed file: /icons/header.jpeg
Removed file: /icons/ok.ico
Removed file: /icons/thumbnail.png
Removed directory: /icons
Removed file: /src/index.html
LittleFS instance written to lfs-new.hex.
DONE

Extract Files From a LittleFS Instance#

Extracting files from a LittleFS instance is done using the littlefs extract command. Singular files may be extracted using the --file option, whereas directories can be extracted using the --dir option. If any directories are extracted, Commander will traverse those directories and recursively extract all files and subdirectories.

All filenames/paths provided to Commander must be absolute with respect to the LittleFS instance's root directory, /.

The destination folder of the extracted files is specified using the --dest option. If you want the extracted files to be compressed and placed in a zip file, the --zip option can be used in place of the --dest option.

If only singular files (using the --file option) are being extracted, the individual files' paths will be ignored upon extraction, placing the files directly in the destination specified by the --dest/--zip option.

If no files or directories are specified, Commander will extract all the files in the LittleFS instance.

Note: Zip file compression functionality requires Microsoft PowerShell version 5.0 or above on Windows, and the zip and unzip system utilities on Linux/Mac

Command Line Syntax

$ commander littlefs extract [--infile <filename> --device <device>] [--file <filename> --dir <directory> --dest <directory> --zip <filename>]

Command Line Input Example

$ commander littlefs extract --infile lfs.hex --device SiWG917M111MGTBA --zip items.zip

This command line extracts all the files in the LittleFS instance 'lfs.hex', compresses the files and stores them in a zip archive at 'items.zip'.

Command Line Output Example

Reading LittleFS instance from lfs.hex...
Parsing file lfs.hex...
Zip archive created at "/Users/username/Desktop/items.zip".
DONE