SolarOS 4.17.7 manual · api

SolarOS Python API

SolarOS embeds MicroPython as the python foreground application. It can run an interactive REPL or execute .py and .mpy files from storage.

python
python /apps/demo.py arg1 arg2

Scripts receive their arguments through sys.argv. Script output is drawn in the SolarOS terminal. The active shell's app-exit key exits the REPL or requests KeyboardInterrupt while code is running.

The native module is called solaros:

import solaros

solaros.write("SolarOS " + solaros.version() + "\n")

API topics

Open a topic below, or use its ID with man on the device, for example man python.network. Service availability depends on the board and flavor.

Conventions

Most mutating functions return None on success and raise OSError("ESP_ERR_...") on service failure. Query functions return strings, integers, booleans, dictionaries, or lists.

Supported language features include f-strings, sets, properties, descriptors, enumerate(), filter(), reversed(), memoryview, and frozenset. The importable runtime modules are array, binascii, cmath, collections, errno, gc, hashlib, io, json, math, micropython, random, struct, and sys.

Python integers support the signed 64-bit range. SolarOS service values such as file sizes, timestamps, counters, and storage capacities use integers throughout that range. An unsigned native value above 9223372036854775807 is returned as a decimal string instead of losing precision.

input(), execfile(), and upstream extmod modules outside this selected set remain disabled. Use the typed solaros service APIs instead.

The selected modules include json.loads() and json.dumps(), hexadecimal and Base64 conversions in binascii, SHA-256 in hashlib, and the usual non-cryptographic random helpers. Use hashlib for hashing; random is not suitable for security-sensitive values.

Functions that accept file paths use SolarOS shell-style paths. / means the default storage mount; internally this resolves to the active storage mount point.

Service availability

Python requires PSRAM. Optional solaros modules appear only when their services are included in the firmware. Check pkg and board on your device; the topic table above links to each service's requirements and examples. For an optional module, test availability before using it:

import solaros

if hasattr(solaros, "wifi"):
    print(solaros.wifi.status())

Vision, inference, and pipelines need their own packages; adding Python alone does not enable them. See Packages and flavors.

Top-Level Helpers

• solaros.write(text): write text to the SolarOS terminal.
• solaros.version(): return the SolarOS firmware version string.
• solaros.should_exit(): return True when the app is being asked to stop.
• solaros.tick_interval([ms]): get or set the foreground event-pump interval in milliseconds. Pass 0 to restore the 25 ms default.
• solaros.battery_status(): shortcut for solaros.battery.status() when battery support is compiled.
• solaros.wifi_status(): compact Wi-Fi status shortcut when Wi-Fi support is compiled.
• solaros.environment(): shortcut for solaros.sensors.environment() when environmental sensor support is compiled.

For example, solaros.tick_interval(5) lets a foreground Python app drain terminal, TUI, and graphics events at a best-effort 5 ms cadence. It does not schedule or preempt Python code, and it is not a hard-real-time timer. The setting lasts for the current foreground Python app only; headless script jobs cannot change it.

Raw SSH/SCP session handles are unavailable in scripts. Use the ssh and scp applications for remote access and file transfers.

Quick reference

Import solaros and use its service tables for storage, time, networking, hardware, jobs, sessions, input, TUI, and graphics. Foreground pointer and axis events use solaros.input sources, read, clear, and status; keyboard characters use solaros.tui.getch(). APIs return None or raise OSError as documented. Long-running programs must yield cooperatively and release opened buses, graphics targets, and other resources in finally.