SolarOS 4.17.7 manual · api

Lua board, apps, jobs, and identity API

API overview · Python board, apps, jobs, and identity

`solaros.board`

solaros.board.info() returns a new table with the configured board information:

Field	Value
`id`	Stable board ID, such as `solar_term`.
`name`	Human-readable board name.
`module`	Module name, or an empty string when unspecified.
`capabilities`	Array of capability names, such as `wifi`, `gpio`, and `psram`.
`psram_bytes`	Declared PSRAM capacity in bytes; `0` on boards without PSRAM.

These are build-time board properties, not a hardware probe or a list of installed firmware packages. Optional service bindings still depend on the firmware flavor. PSRAM capacity is not the current free heap. The board API is available whenever Lua is included, including headless script runners.

local board = solaros.board.info()
print(board.id, board.name)
for _, capability in ipairs(board.capabilities) do
    print(capability)
end

`solaros.identity`

solaros.identity: user, hostname, set_user, set_hostname, format

`solaros.jobs`

solaros.jobs: list, count, status, start, stop

`solaros.sessions`

solaros.sessions: create_shell, close

`solaros.apps`

solaros.apps: list, find, launch, open, can_open

list([include_playground]) includes installed Playground apps by default and returns name, id, title, summary, kind, and runtime. Playground launch names use playground:<id>; pass false to list only native apps.

launch(name[, args]) and open(path_or_url) replace the current script app, so a successful handoff does not return. args is an array of strings without the app name. can_open(path_or_url) reports support for local file extensions and HTTP(S) URLs. find(name) continues to inspect the native registry.

When the launched app exits, the completed interpreter session closes and control returns to the shell.

Identity

solaros.identity.user() and hostname() return the NVS-backed device identity. set_user(name) and set_hostname(name) validate and persist new values. Reboot before expecting an already initialized Wi-Fi interface to advertise a changed hostname.

SSH and SCP use the identity user as their default remote username when user@host is not supplied.

Existing /.solar/user and /.solar/hostname files are imported once when their corresponding NVS keys are absent.

Jobs

solaros.jobs.list() and solaros.jobs.status(name) return the effective tick_interval_ms and tick_deadline_ms plus tick_last_us, tick_max_us, and tick_deadline_misses runtime telemetry. worker_stack_bytes is the declared launch-admission requirement and worker_stack_external identifies its memory region. Job control is available through start(name[, args]) and stop(name).

Sessions

solaros.sessions creates manual port shell sessions and closes sessions by id. Script-created port shells do not run /.shell/startup.

create_shell(port[, term[, cols, rows[, charset]]]): create a port shell and return its numeric session id.
create_shell(port, {term="auto", cols=80, rows=24, charset="utf8"}): table-options form for the same call. Use charset="ascii" for legacy terminals.
close(session_id): close a display/app session or stop a port shell session; closing the final interactive shell is refused.

Example:

local solaros = require("solaros")

pcall(function()
    solaros.jobs.stop("slip")
end)

local sid = solaros.sessions.create_shell(
    "uart0", {term = "ansi", cols = 80, rows = 25, charset = "ascii"}
)
-- later:
solaros.sessions.close(sid)
solaros.jobs.start("slip", {"uart0", "115200"})

Quick reference

Use solaros.identity, solaros.jobs, solaros.sessions, solaros.apps for apps, jobs, and identity. See man lua for runtime conventions and service availability.