SolarOS 4.6.8 documentation
User manual.
These are the same canonical Markdown topics shown on GitHub, embedded in SolarOS, opened by help/man, and used by the native agent reference tool.
Native SolarOS agentConfigure and use the resumable LLM agent and its typed toolsAgent service and tool referenceProvider contract, typed tools, policy, resource bounds, and roadmapagent applicationNative Responses/Chat-Completions LLM client and SolarOS agent control plane. It streams model text directly to the active shell and exposes typed system-status, storage-listing, job-listing, display-discovery, and optional Python/Lua execution tools. agent tools shows risk, policy, and runtime availability.aplay applicationPlay audio files through the board audio output. WAV and MP3 are supported when the audio package is compiled and the board has audio hardware.arecord applicationRecord microphone input to a WAV file. This requires the audio package and board microphone hardware.calc applicationScientific calculator and function plotter. On a graphical display, calc opens an expression list beside a Cartesian plot. From UART, USB CDC, Telnet, or any other text-only shell, the same command opens a scientific REPL without the plot pane. calc --text forces that REPL even when graphics are available.chat applicationTwo-pane provider-neutral conversation client. The left pane lists gateway and radio conversations, the right pane shows bounded shared history, and the bottom line is the message/command input. It opens and remains useful offline; network or radio transport jobs connect independently.clock applicationFull-screen graphical seven-segment clock, alarm countdown, and stopwatch.com applicationSerial terminal for a bidirectional byte-stream port. Display-keyboard or port-shell input is forwarded to the selected port, and received bytes are drawn in the active terminal. The port may be a UART or a virtual port such as a peer-bound SolarOS Link stream.contacts applicationProvider-neutral address book for gateway and MeshCore identities. Contacts can carry multiple provider endpoints while retaining trust independently for each endpoint. A signed MeshCore advert creates a discovered endpoint: the signature proves possession of the advertised key, not the human identity behind it.curl applicationHTTP client for quick text downloads and diagnostics. It can print response data to the terminal or save it to a file.edit applicationText editor for files on mounted storage. It supports cursor navigation, selection, clipboard operations, text-size changes, and syntax highlighting for known source files. The editor supports files up to 256 KiB on boards with PSRAM and 32 KiB on boards without PSRAM. Use hexedit for binary files.email applicationReceive-only IMAPS client for the configured mailbox. The app shows the provider-specific message list while every newly synchronized message is also published to the universal inbox and its shared status-bar unread counter.files applicationFile manager inspired by Midnight Commander. Its normal mode provides two panes for copy, move, delete, and launch workflows on mounted storage. Launcher mode provides a minimal single-pane application menu suitable for a startup script.gameboy applicationExperimental original Game Boy (DMG) emulator for the Waveshare ESP32-S3-RLCD-4.2 and the full-PAL Freenove ESP32-WROVER v3.0 target. It is included in the retro and rover-retro flavors. The application loads a user-supplied ROM into PSRAM, renders its four shades as a 320x288 dithered image, and writes battery-backed cartridge RAM beside the ROM as a .sav file. Game Boy Color-only ROMs and ROMs larger than 4 MiB are rejected.help applicationForeground browser for the package-aware SolarOS manual. The foldable tree groups the topics compiled for the current firmware and shows whether it is using the embedded copy or a verified downloaded revision.hexedit applicationTwo-pane binary editor for files on mounted storage. Each row shows a file offset, hexadecimal bytes, and their synchronized printable ASCII view. The number of bytes per row adapts to the terminal width. It uses the same 256 KiB PSRAM and 32 KiB internal-memory limits as edit.inbox applicationUniversal incoming-message browser for pages, chat notifications, mail, and other background producers. It reads the same shared inbox that supplies the status-bar unread count. Messages and read state survive reboot in the bounded /.inbox/messages.bin store; the service retains at most 64 entries and keeps the file below 32 KB even when internal flash is the only storage.invaders applicationGraphical arcade shooter.io applicationInteractive expansion I/O manager. Its default Layout view presents the board's connectors in their physical arrangement, followed by the existing pin, named-bus, and resource-claim views. It uses the same ownership and validation services as the gpio, i2c, spi, uart, onewire, and expansion commands.less applicationTerminal pager for text files. It preserves original text layout and is useful for quick file inspection.logic applicationOn-device logic analyzer waveform viewer. It displays the latest capture made by the shared logic analyzer service or the SUMP job. With pin arguments it makes a new local capture before opening the viewer.lua applicationEmbedded Lua runtime. It can run an interactive REPL or execute .lua scripts from storage. Lua scripts can use SolarOS service bindings when the selected firmware includes the corresponding packages.notes applicationMarkdown-backed checklist and category manager. It stores unchecked and checked items and supports one level of category folding.playground applicationBrowse the configured community catalog as a foldable category tree, search applications, and install, update, uninstall, or run Python and Lua scripts.plot applicationGraphical plotter for DAQ CSV files and live scalar streams. It is compatible with CSV generated by the daq job.python applicationEmbedded MicroPython runtime. It can run an interactive REPL, .py scripts, or .mpy files from storage. Python scripts can use SolarOS service bindings when the selected firmware includes the corresponding packages.reader applicationGraphical document reader for plain text, Markdown, and EPUB. It remembers reading position and zoom per opened file when storage is available.scp applicationSCP file transfer over SSH. It supports password or key authentication through the shared SSH transport and host lookup/known-host storage. When user@ is omitted, SCP uses the NVS-backed SolarOS identity user.sheet applicationCSV viewer for small data tables. It is intended as a companion to daq logs and simple spreadsheet-like inspection.ssh applicationInteractive SSH client. It supports password and key authentication, known hosts, hostname lookup through /.ssh/hosts, UTF-8 text, VT-style controls, and remote full-screen terminal applications. When user@ is omitted, SSH uses the NVS-backed SolarOS identity user.telnet applicationTelnet client for classic TCP terminal sessions. It supports basic Telnet option negotiation, terminal type reporting, window size reporting, and raw mode.view applicationGraphical image viewer. It supports the image formats compiled into the current firmware, including common PNG/JPEG/GIF/WebP paths and automatic animated GIF playback when the media package is enabled.web applicationSimple graphical web browser for lightweight HTML pages. It shares document and image rendering infrastructure with reader where possible.writer applicationResumable graphical Markdown editor for PSRAM display boards. Inactive blocks are formatted like reader; the block containing the cursor and every block touched by a selection show their exact Markdown source. edit remains the portable text editor for port shells and boards without graphics or PSRAM.Application referenceUsage, controls, and examples for every foreground applicationBoards and hardware targetsSupported boards, capabilities, porting structure, and validationNamed runtime busesCreate and use resource-owned I2C, SPI, UART, OneWire, and PS/2 busesadc commandShow ADC service status.agent commandOpen a new native LLM agent TUI or make one unsaved foreground request.apps commandList registered foreground apps compiled into the firmware.audio commandShow audio state, global speaker level, tone queue, and active synth telemetry.battery commandShow voltage, estimated charge, power source, config, and monitor trend.ble commandShow BLE keyboard state.board commandPrint board ID, name, and capabilities.cat commandPrint a small text file.cd commandChange current shell directory.clear commandClear the active shell terminal.close commandClose a display app, display shell, or retained port app, or stop a port shell session. The final interactive shell cannot be closed.commands commandList built-in shell commands.contacts commandOpen the searchable provider-neutral contact browser.cp commandCopy a file or matched set.daq commandPrint DAQ usage.date commandShow or set the local date.df commandShow free space on mounted storage volumes.disk commandShow persistent-storage status.display commandList drawable display targets, draw a test pattern, or change driver-specific display settings.dpad commandShow ADC D-pad pins, raw values, zones, and calibration thresholds.email commandOpen the receive-only email app.engine commandPrint or reset generic engine utilization counters for CPU/SIMD-style backends and vector bulk operations.exit commandClose the current UART, USB CDC, or telnet shell when another interactive shell remains.expansion commandShow expansion capabilities, named buses and leases, connector resources, active devices, and resource claims.fg commandResume a display session or a port-owned app on its owning terminal. Without an ID, restore the calling port shell's most recently suspended app.gateway commandShow gateway configuration, connection state, and traffic counters.gpio commandList board GPIOs with free, releasable, or fixed pin policy.help commandBrowse the package-aware manual or manage its signed exact-version SD copy.humidity commandRead the board humidity sensor when available.i2c commandShow every named I2C bus, or one selected bus.identity commandShow the configured user and hostname.inbox commandOpen the universal incoming-message browser.job commandShow one job or all jobs.jobs commandList registered jobs and their state.joystick commandShow joystick axes, raw values, direction, and thresholds.led commandInspect or control the built-in status LED when available.link commandList active SolarOS Link instances and their queue/protocol counters.log commandShow runtime log ring status.ls commandList files. Hidden files are shown only with -a; sizes are human-readable with -h.man commandRead or search the package-aware SolarOS manual.mem commandPrint heap status; policy also shows allocation-class counters, guarded fallback limits, and the last tagged failure.meshcore commandShow MeshCore identity, radio, packet, delivery, duplicate, memory, and stack state.messages commandShow bounded-store, persistence, drop, and live provider state.mkdir commandCreate directories.mqtt commandMQTT/MQTTS client.mv commandRename or move a file or matched set.neopixel commandList attached WS2812/NeoPixel strips.netscan commandScan TCP ports on one host or a capped IPv4 range.ntp commandSync the wall clock from NTP.nvs commandShow the default NVS partition size, entry usage, and namespace count.onewire commandShow every registered named 1-Wire bus, or one selected bus.ota commandShow running and configured OTA state.outbox commandList pending outbound messages. Sent and failed messages remain in conversation history, not Outbox.ping commandSend ICMP echo requests. Without count, ping runs until app-exit.pkg commandPrint compiled package groups and build units.pocsag commandShow POCSAG receiver configuration, counters, correction statistics, and RSSI.port commandList byte-stream ports.power commandInspect and configure power policy.pwm commandShow PWM state.radio commandOpen the packet-radio TUI with live status and editable common config.ramfs commandList PSRAM-backed volatile filesystem mounts.reboot commandRestart the board.rm commandRemove files. -f allows directories; -rf removes directories recursively.session commandList display sessions, port shells, and retained port-owned application sessions with their owner.sessions commandList display app sessions, display shell sessions, and port shell sessions.setterm commandConfigure terminal/input preferences. Without arguments, opens the display TUI when available.sh commandRun a simple SolarOS shell script from storage.sleep commandEnter explicit light sleep.spi commandShow every named SPI bus, or one selected bus.sshkey commandShow default SSH key status.status commandPrint a compact system status summary.stream commandList timestamped data streams.temperature commandRead the board temperature sensor when available.time commandShow or set the local time.top commandPrint FreeRTOS task resource information when available.uart commandShow the default uart0 or a selected named UART bus.unzip commandList or extract a ZIP archive.uptime commandPrint elapsed time since boot.version commandPrint the SolarOS version and firmware flavor.watch commandRepeat another shell command until Esc, q, or the app-exit key is pressed.wifi commandOpen the Wi-Fi display TUI when launched from the display shell.xfer commandSend or receive files over a byte-stream port.zip commandCreate a ZIP archive. -0 stores without compression.Shell command referenceComplete syntax, behavior, and examples for built-in shell commandsCompatibility I/O modulesUse the legacy single-bus I2C, SPI, UART, and OneWire APIsExpansion drivers and attached devicesDiscover, attach, and detach package-gated expansion devicesExpansion hardware referenceResource rules, workflows, drivers, bindings, and wiring examplesGPIO, ADC, PWM, and LED APIsUse runtime-safe digital and analog expansion pinsBrowsing and refreshing documentationBrowse the manual and refresh its signed Markdown pagesDevice identityRead and configure the NVS-backed user and hostnamebatmon jobBattery monitor. It periodically samples battery voltage, maintains a smoothed trend, estimates power state, and can request light sleep when the configured minimum voltage is reached.bridge jobBidirectional byte bridge between two byte-stream ports, or between one byte-stream port and an active SolarOS Link instance.chatd jobLocal SolarOS chat gateway server. It is useful for testing the chat app or for small trusted local networks.daq jobData acquisition job. It captures scalar streams to timestamped CSV, or one byte stream directly to a raw file.displayd jobAuthenticated HTTP display and remote control. It has two modes:email-sync jobReceive-only IMAPS mailbox polling job. It fetches mail into the provider-local email app and publishes each new message to the universal inbox.gateway-sync jobBackground synchronizer for the gateway messaging provider. Start and stop it explicitly, using the same lifecycle as email-sync:gpio-keys jobMaps runtime-safe GPIO inputs to SolarOS keyboard presses. The job configures each pin as an input with its internal pull-up enabled, treats a low level as pressed, and applies the same 25 ms debounce used by fixed board buttons. Each debounced transition publishes a generic SolarOS key press or release. Held keys use the system repeat rate configured by setterm keyrate.httpd jobStatic HTTP file server for a folder on mounted storage.log jobRuntime SolarOS log follower. It mirrors log entries to a byte-stream port or appends them to a file.meshcore jobNon-forwarding MeshCore companion provider for Contacts and Messages.ntp-sync jobNetwork time synchronization job. It updates the SolarOS wall clock from NTP and also updates the hardware RTC when the board provides one.pocsag jobPOCSAG pager receiver job. It configures a registered packet radio for a continuous POCSAG byte stream, frames successive 64-byte batches, filters pages to one receiver identity code (RIC), decodes alphanumeric or numeric payloads, and publishes completed messages to the universal inbox.ps2-keyboard jobReceives keyboard scan-code set 2 from an exclusive named PS/2 bus and publishes press and release transitions through the generic SolarOS input service.radio-link jobPacket-radio adapter for the transport-independent SolarOS Link service.slip jobIPv4 SLIP gateway on a byte-stream port. This is intended for retro machines, headless boards, and serial networking experiments.sump jobSUMP-compatible logic analyzer server on cdc0. It claims the CDC port and uses the shared logic analyzer service for acquisition. PulseView and sigrok can connect with the OpenBench Logic Sniffer/SUMP serial driver.telnetd jobRemote Telnet shell server. The listener is a background job; each accepted connection is attached to its own normal SolarOS port-shell session.Background jobsInspect and control bounded background workersBackground job referenceConfiguration, ownership, and examples for every background jobSolarOS LinkPacket messaging, reliable virtual serial ports, and the radio-link adapterLua graphics APIDraw through SolarOS displays from LuaLua API referenceComplete Lua service API, conventions, and examplesLua text user-interface APIBuild terminal applications from LuaAudio, keyboard input, and clipboard APIsUse installed media and input servicesMeshCore companion messagingSecure direct and shared-group messages over a claimed packet radioMessaging, contacts, and credential securityProvider-neutral messaging identities, trust, persistence, and secret handlingWi-Fi, MQTT, and network APIsConnect, inspect, and communicate over installed network servicesSolarOS manualFind commands, applications, jobs, scripting APIs, and hardware conceptsFirmware packages and flavorsUnderstand package ownership, groups, flavors, and custom buildsPlaygroundBrowse, install, uninstall, and run community Python and Lua applicationsPython graphics APIDraw through SolarOS displays from MicroPythonPython API referenceComplete MicroPython service API, conventions, and examplesPython text user-interface APIBuild terminal applications from MicroPythonSolarOS scripting conventionsWrite cooperative Python and Lua programs against SolarOS servicesForeground sessions and applicationsCreate shells and inspect resumable foreground applicationsSSH identity keysInspect, share, generate, and remove the default SSH key pairStorage and shell pathsUse SolarOS volumes, files, directories, and shell-style pathsTime, battery, and environment APIsRead clocks, battery state, temperature, and humidity