SolarOS 4.13.4 manual · api

Python apps, jobs, and identity API

API overview · Lua apps, jobs, and identity

solaros.identity

Identity functions read the SolarOS user and hostname service.

• user(): return the configured username used by default for SSH and SCP.
• hostname(): return the configured hostname.
• set_user(name): validate and save the username in NVS.
• set_hostname(name): validate and save the hostname in NVS. Reboot before

expecting an already initialized Wi-Fi interface to advertise the new name.

• format(): return user@hostname.

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

Example:

import solaros

print(solaros.identity.format())

solaros.jobs

Job functions control SolarOS background jobs.

• list(): return all jobs.
• count(): return number of jobs.
• status(name): return one job status.
• start(name[, args]): start a job; args is a list or tuple of strings.
• stop(name): stop a job.

Status dictionaries include tick_interval_ms, tick_deadline_ms, tick_last_us, tick_max_us, and tick_deadline_misses in addition to the job state and tick count. worker_stack_bytes is the declared launch-admission requirement and worker_stack_external identifies its memory region. These fields expose the effective cooperative scheduling policy, memory admission, and measured handler execution time.

Example:

import solaros

solaros.jobs.start("ntp-sync", ["60", "pool.ntp.org"])
print(solaros.jobs.status("ntp-sync"))
solaros.jobs.stop("ntp-sync")

solaros.sessions

Session functions create and close foreground shell/app sessions.

• create_shell(port[, term[, cols, rows[, charset]]]): create a port shell session and return its numeric session id.
• create_shell(port, term="auto", cols=80, rows=24, charset="utf8"): keyword 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.

Manual port shell sessions created from scripts do not run /.shell/startup.

Example:

import solaros

try:
    solaros.jobs.stop("slip")
except OSError:
    pass

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"])

solaros.apps

Application functions inspect the built-in foreground app registry.

• list(): return registered apps with name and summary.
• find(name): return one app dictionary or None.

Example:

import solaros

for app in solaros.apps.list():
    print(app["name"], "-", app["summary"])

Longer Example: Status Snapshot

import solaros

solaros.write("SolarOS {}\n".format(solaros.version()))
solaros.write("{}\n".format(solaros.identity.format()))
solaros.write("uptime {}\n".format(solaros.time.uptime()))

battery = solaros.battery.status()
solaros.write("battery {}% {} mV\n".format(battery["percent"], battery["voltage_mv"]))

env = solaros.sensors.environment()
solaros.write("env {:.1f} C {:.1f}%\n".format(env["temperature_c"], env["humidity_percent"]))

wifi = solaros.wifi.status()
solaros.write("wifi {} {}\n".format(wifi["state"], wifi["ip"]))

Quick reference

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