File I/O for internal flash (LittleFS) and SD card
Mount points: /sd/ - SD card (removable, for maps, logs, large files) /fs/ - LittleFS internal flash (for user data) /img/ - Embedded scripts (read-only, compiled into firmware) Script loading uses /scripts/ paths with overlay: SD > FS > embedded. The /img/ mount point is for file browsing; internally maps to /scripts/. Also provides persistent key-value preferences stored in NVS flash.
| Parameter | Description |
|---|---|
| path | File path (prefix /sd/ for SD card) |
| content | Content to append |
-- Append to log file
local timestamp = os.date("%Y-%m-%d %H:%M:%S")
ez.storage.append_file("/sd/log.txt", timestamp .. " System started\n")
-- Factory reset
ez.storage.clear_prefs()
print("All settings reset to defaults")
| Parameter | Description |
|---|---|
| src | Source file path (prefix /sd/ for SD card) |
| dst | Destination file path (prefix /sd/ for SD card) |
-- Backup config to SD card
ez.storage.copy_file("/config.json", "/sd/backup/config.json")
-- Copy from SD to flash
ez.storage.copy_file("/sd/assets/image.bin", "/cache/image.bin")
| Parameter | Description |
|---|---|
| path | Path to check (prefix /sd/ for SD card) |
if ez.storage.exists("/config.json") then
local content = ez.storage.read_file("/config.json")
else
print("Config not found, using defaults")
end
| Parameter | Description |
|---|---|
| path | File path (prefix /sd/ for SD card) |
local size = ez.storage.file_size("/config.json")
if size then
print("Config file is", size, "bytes")
end
local info = ez.storage.get_flash_info()
local free_kb = info.free_bytes / 1024
print(string.format("Flash: %.1f KB free", free_kb))
| Parameter | Description |
|---|---|
| path | Path to check ("/sd/" for SD card, otherwise LittleFS), default "/sd/" |
local sd_free = ez.storage.get_free_space("/sd/")
local flash_free = ez.storage.get_free_space("/")
print(string.format("SD: %d MB, Flash: %d KB free",
sd_free / (1024*1024), flash_free / 1024))
| Parameter | Description |
|---|---|
| key | Preference key (max 15 chars) |
| default | Default value if key not found (optional) |
local brightness = ez.storage.get_pref("brightness", "200")
local volume = ez.storage.get_pref("volume", "80")
local info = ez.storage.get_sd_info()
if info then
local free_mb = info.free_bytes / (1024 * 1024)
print(string.format("SD card: %.1f MB free", free_mb))
end
| Parameter | Description |
|---|---|
| path | Path to check |
if ez.storage.is_embedded("/scripts/boot.lua") then
print("This is a read-only embedded script")
end
if ez.storage.is_sd_available() then
print("SD card ready")
else
print("Please insert SD card")
end
| Parameter | Description |
|---|---|
| json_string | JSON string to parse |
local json = ez.storage.read_file("/config.json")
local config, err = ez.storage.json_decode(json)
if config then
print("Username:", config.username)
else
print("Parse error:", err)
end
| Parameter | Description |
|---|---|
| value | Lua table, string, number, boolean, or nil |
local data = {
name = "Alice",
scores = {95, 87, 92},
settings = {sound = true, level = 5}
}
local json = ez.storage.json_encode(data)
ez.storage.write_file("/save.json", json)
| Parameter | Description |
|---|---|
| path | Directory path (default "/", prefix /sd/ for SD card) |
local files = ez.storage.list_dir("/sd/music")
for _, file in ipairs(files) do
if file.is_dir then
print("[DIR]", file.name)
else
print(file.name, file.size, "bytes")
end
end
| Parameter | Description |
|---|---|
| prefix | Optional path prefix filter (default: list all) |
local scripts = ez.storage.list_embedded("/scripts/ui/screens")
for _, script in ipairs(scripts) do
print(script.path, script.size, "bytes")
end
| Parameter | Description |
|---|---|
| path | Directory path to create (prefix /sd/ for SD card) |
ez.storage.mkdir("/sd/logs")
ez.storage.mkdir("/sd/logs/2024")
| Parameter | Description |
|---|---|
| path | File path (prefix /sd/ for SD card) |
| offset | Byte offset to start reading from (0-based) |
| length | Number of bytes to read (max 1048576 — 1 MB per call) |
-- Read file header(first 16 bytes)
local header = ez.storage.read_bytes("/sd/maps/tiles.bin", 0, 16)
-- Stream a multi-megabyte file in 64KB chunks
local offset = 0
while true do
local chunk = ez.storage.read_bytes("/sd/huge.bin", offset, 65536)
if not chunk or #chunk == 0 then break end
process(chunk); offset = offset + #chunk
end
| Parameter | Description |
|---|---|
| path | Full path of the embedded script (e.g., "/scripts/boot.lua") |
local content = ez.storage.read_embedded("/scripts/boot.lua")
if content then
print("Boot script is", #content, "bytes")
end
| Parameter | Description |
|---|---|
| path | File path (prefix /sd/ for SD card) |
local content = ez.storage.read_file("/config.json")
if content then
local config = ez.storage.json_decode(content)
end
| Parameter | Description |
|---|---|
| path | File path to delete (prefix /sd/ for SD card) |
if ez.storage.remove("/sd/old_backup.json") then
print("Backup deleted")
end
| Parameter | Description |
|---|---|
| key | Preference key to remove |
ez.storage.remove_pref("old_setting")
| Parameter | Description |
|---|---|
| old_path | Current file path |
| new_path | New file path |
-- Rename a file
ez.storage.rename("/temp.txt", "/final.txt")
-- Move to different directory
ez.storage.rename("/downloads/file.txt", "/documents/file.txt")
| Parameter | Description |
|---|---|
| path | Directory path to remove (prefix /sd/ for SD card) |
-- Remove directory contents first, then the directory
for _, file in ipairs(ez.storage.list_dir("/sd/temp")) do
ez.storage.remove("/sd/temp/" .. file.name)
end
ez.storage.rmdir("/sd/temp")
| Parameter | Description |
|---|---|
| key | Preference key (max 15 chars) |
| value | Value to store (string, number, or boolean) |
ez.storage.set_pref("brightness", 200)
ez.storage.set_pref("username", "Alice")
ez.storage.set_pref("gps_enabled", true)
| Parameter | Description |
|---|---|
| path | File path (prefix /sd/ for SD card) |
| content | Content to write (string, can be binary) |
local config = {brightness = 200, volume = 80}
local json = ez.storage.json_encode(config)
ez.storage.write_file("/config.json", json)