SolarOS 4.13.4 manual · app

Playground

playground is the catalog browser for community Python and Lua applications. It downloads one catalog from the configured repository and presents its categories as a foldable tree. Applications are scripts and assets, not firmware packages.

Start the browser:

playground
playground search QUERY...
playground install APP-ID [auto|flash|sd]
playground run APP-ID [ARG...]
playground delete
playground reload
playground refresh
playground storage [flash|sd]

Opening the TUI loads the saved local catalog without accessing the network. Press r in the tree, or run playground refresh, to download and save the current catalog. Run playground reload to explicitly reload the saved copy. Press / to search names, descriptions, authors, tags, and categories.

playground delete recursively deletes the catalog and every installed Playground application from the configured storage target, then clears the loaded catalog from memory. It retains the configured source and storage preferences. It also removes the legacy hidden .solar/playground directory when present.

The same operations are available directly from the shell. search prints matching catalog IDs, runtimes, names, and installation markers. install downloads and verifies one ID to the configured filesystem, or to an explicit flash or sd target. The omitted and auto targets both use the persistent Playground storage setting. run resolves the installed manifest and launches its Python or Lua runtime directly; it does not need the catalog to be loaded and does not create a Playground session. Additional arguments after the application ID are passed to Python through sys.argv or to Lua through arg. For example:

playground run qr-share --file /notes/wifi.txt

Every valid installed application also becomes a command named by its ID. For example, installing qr-share makes this equivalent:

qr-share --file /notes/wifi.txt

Playground rebuilds these aliases automatically in the managed /.shell/playground file after installation, update, uninstall, bulk deletion, and service initialization. User aliases in /.shell/alias take precedence; native firmware commands and applications cannot be replaced by a Playground alias. Use playground run APP-ID if an application ID has such a collision.

--file PATH is the canonical optional convention for a Playground script's primary input file. After --file, Tab completes filesystem paths. This also works through a multi-token alias such as run playground run.

After the catalog is loaded, Tab completes application IDs for install and installed IDs for run without keeping a second catalog list in memory. The generated direct commands participate in normal command completion even when the catalog is not loaded.

Opening the Playground TUI never accesses the network automatically. It shows the catalog saved by the last successful refresh. Press r or run playground refresh when you explicitly want to download the current catalog.

Application markers:

• [ ] is available but not installed.
• [I] is installed at the catalog version.
• [U] has an update available.
• [!] cannot run on this board or firmware.

Select an application and press i to install or update it directly from the catalog tree. Press u to uninstall an installed application after confirmation. The same actions are available after pressing Enter or Right for details; r runs an installed copy.

The catalog and default application installations live on the persistent storage target. Without a saved preference, Playground selects SD when it is mounted and flash otherwise. Inspect or change the setting with:

playground storage
playground storage flash
playground storage sd

The saved catalog lives at:

<configured-filesystem>/playground/catalog.json
<configured-filesystem>/playground/catalog.source

Installed files live on the selected filesystem:

<filesystem>/playground/python/APP-ID/
<filesystem>/playground/lua/APP-ID/

SD installations take precedence when the same application also exists in flash. Changing the storage setting does not migrate an existing catalog or installed applications. Refresh the catalog after changing it. When sd is configured, the SD card must be mounted to load or refresh the catalog and to install applications.

Sources and safety

The default catalog is generated by github.com/nilseuropa/solar_os_playground. Use a compatible fork by setting either its GitHub repository URL or the URL of its generated dist/catalog.json:

playground source
playground source https://github.com/example/solar_os_playground
playground source https://example.invalid/path/dist/catalog.json
playground source reset

GitHub repository URLs resolve to main/dist/catalog.json. The chosen source is stored in NVS. Each archive is checked against the exact size and SHA-256 digest declared by the downloaded catalog before installation. Installation is staged and replaces the prior version only after extraction and entry-file validation.

Playground applications are not sandboxed. Once started, they have the normal permissions of the SolarOS Python or Lua runtime. Only use repositories and applications whose maintainers you trust.

An active Playground script is a normal foreground Python or Lua application. It can use solaros.input to receive touch, mouse, and joystick events routed to its session; a script launched by a headless source runner cannot receive that foreground event stream.

Controls

• Up/Down, Page Up/Page Down, Home/End: navigate.
• Enter, Space, Left, Right: fold categories or open details.
• /: search the current catalog.
• r: refresh in the tree, or run from details.
• i: install or update the selected application from the tree or details.
• u: uninstall the selected application from the tree or details, after confirmation.
• Esc: cancel or go back in nested views; exit from the catalog tree.
• q or the app-exit key: exit.

Quick reference

Run playground to browse the configured catalog. Use / to search, Enter for details, i to install, u to uninstall, and r to run. Refresh with r in the tree or playground refresh; use playground reload to load the saved catalog without a network request. Use playground source [URL|reset] to inspect or change the catalog source, and playground storage [flash|sd] to choose persistent catalog and application storage. Packages are hash-checked but scripts are not sandboxed. Shell automation can use playground search QUERY, playground install ID [auto|flash|sd], playground run ID [ARG...], and playground delete. Installed IDs are also automatic shell commands backed by /.shell/playground. Active scripts can read foreground pointer and axis events through solaros.input.