SolarOS 4.17.7 manual · service

Foreground sessions and applications

A session is a foreground application or shell attached to a display or byte stream. Each display or port has one active view, but can retain several suspended applications. Sessions let you switch away and return without discarding their state.

Inspect and switch

session list
session fg 3
session send 3 wifi status
session close 3

session send ID COMMAND runs a command on an active display shell from any other shell. The command is echoed and added to the target shell's history, and its output stays on the target display. SolarOS refuses the request if the target is an application, is suspended, has a partially typed command, or is the calling shell.

Alt+Tab or Alt+Right switches to the next session on the locally focused display. Alt+Left switches to the previous session. Either Alt key is accepted, including AltGr on compact keyboards. Both directions follow wrapped session-ID order, and the display shell remains in the cycle. session fg explicitly foregrounds its session and moves local input focus to that session's display. Closing an application returns to that display's shell.

On UART, USB CDC, Telnet, and other port shells, press Ctrl+Z to suspend a resumable foreground application and return to the prompt. Run fg to restore the most recently suspended application on that port, or fg ID to restore a specific port-owned session. Ctrl+] still closes the current application. Port sessions never migrate: a command from another shell can foreground or close one, but it changes the application shown on the owning port.

Applications currently remain single-instance across the device. If an app is already retained on another display or port, SolarOS reports its session owner instead of creating a second copy.

SolarOS always keeps at least one interactive shell. exit, close, and session close refuse to close the final remaining display or port shell.

Create another shell

session create shell cdc0 --term auto
session create shell uart0 --term ansi --charset ascii --size 80x25
session create shell lcd0

Use port list or display list to discover real targets first. A manually created port session does not rerun /.shell/startup. A display shell is created on its target without changing local input focus; use session focus when the BLE keyboard or board controls should move to it.

Terminal control and character encoding are separate. --term selects cursor and screen-control behavior. Port shells use --charset utf8 by default; add --charset ascii for DOS or another legacy terminal so TUI line art and symbols are rendered with ASCII fallbacks. The setting does not change framebuffer display sessions.

Start an app on a display

An app can be launched onto a named display from any shell:

session create files display0
session create reader oled0 /manual.md
session create writer display0 /notes.md

The invoking port shell immediately returns to its own prompt. The new app receives input belonging to its display; serial input remains with the serial shell. App arguments use the invoking shell's current directory for the same path-aware apps as a direct launch.

This cross-shell display control remains available while a port shell retains its own applications. session close ID can close either kind of session.

Child applications

Foreground applications can temporarily open another app on the same terminal. Files uses this for Reader, Less, Edit, and View; Playground uses it to run an installed Python or Lua application. The parent is suspended while the child is active. Closing the child resumes the parent. Suspending the child with Ctrl+Z returns to the shell and retains both sessions for later fg.

Local input focus

The locally focused display receives keyboard and board-control input. Touch or browser input may target a particular display. Inspect or change focus:

session focus
session focus oled0

Changing focus does not move or restart an app. On split displays, use Ctrl+Alt+Arrow to move focus in the split's direction. At an edge, focus stays where it is. On independent displays, those shortcuts cycle through targets. Either Alt key works, including AltGr. Plain Ctrl+Arrow remains available to the app.

Quick reference

solaros.sessions.create_shell(port, optional term, cols, rows, charset) returns a session id; close(id) closes it. The Lua options table and Python keyword form also accept charset="utf8" or charset="ascii". Script-created port shells do not run /.shell/startup. solaros.apps.list() includes installed Playground apps, and launch(), open(), and can_open() provide replacement handoff from Python and Lua scripts.