SolarOS

SolarOS is a small ESP32 operating environment for pocket terminals, reflective displays, serial consoles, and low-power embedded tools. It provides a shell, foreground applications, background jobs, storage, networking, hardware services, Python, and Lua.

User manual

The SolarOS User Manual is the canonical source for:

• the documentation browsed on GitHub;
• the signed on-device help tree and man;
• the native agent's SolarOS reference;
• the generated documentation on solar-os.eu.

It contains the complete command, application, job, board, expansion, Python, Lua, package, and workflow documentation. Edit the topic in doc/manual/; do not maintain a separate device or website copy.

Build

SolarOS uses PlatformIO with ESP-IDF through the pioarduino Espressif32 platform:

pio run -e solar_term
pio run -e freenove_esp32_s3_display_4_0
pio run -e cl_32
pio run -e t_lora_pager
pio run -e t_deck_plus
pio run -e waveshare_esp32_s3_sim7670g_4g
pio run -e elecrow_crowpanel_esp32_s3_4_2_epaper
pio run -e odroid_go
pio run -e freenove_esp32_wrover_v3
pio run -e esp32_devkitc_v4_wrover
pio run -e ttgo_vga32_v14
pio run -e esp32_s3_devkitc1_n16r8
pio run -t upload
pio device monitor -b 115200

The default build uses the full firmware flavor, except the 4 MB VGA32 target, which defaults to rover. For a smaller image or an explicit override:

SOLAR_OS_FLAVOR=core pio run -e solar_term
SOLAR_OS_FLAVOR=writerdeck pio run -e elecrow_crowpanel_esp32_s3_4_2_epaper
SOLAR_OS_VGA_MODE=320x200 pio run -e ttgo_vga32_v14
SOLAR_OS_VGA_MODE=320x240 pio run -e ttgo_vga32_v14

For an interactive board, update-layout, group, build, and flash workflow, run:

python3 scripts/os_builder.py

The VGA32 target supports build-time 640x480 (default), 640x400, 320x240, and 320x200 VGA modes through SOLAR_OS_VGA_MODE.

See Boards and hardware targets and Firmware packages and flavors for the complete build and target reference.

PlatformIO builds from one checkout are serialized on POSIX hosts to protect shared ESP-IDF component state. Windows prints a warning because POSIX file locking is unavailable; do not run concurrent builds from the same checkout.

Developer references

• Stream, control, parameter, and OSC binding model
• Service concurrency contract
• Memory and task-admission policy
• OTA release schema
• Manual generation and signed refresh

Contributing

SolarOS follows the principle "Everything you need. Nothing you don't." Changes to the upstream firmware must elevate the supported hardware and provide clear value to SolarOS users in general. A feature existing in a personal fork does not by itself make that feature a candidate for the upstream firmware.

• Applications: User and community applications should normally be written in Python or Lua and distributed through the SolarOS Playground. The scripting bindings exist so applications can use native SolarOS services without becoming part of the firmware. A native application is accepted only at the maintainer's discretion when it benefits the wider SolarOS community and complies with SolarOS architecture, resource, package, interface, documentation, and testing policies.
• Board support: Support for additional boards is welcome. The contributor is responsible for validating and maintaining support for boards outside the maintainer's primary hardware targets. Pull requests must include build results and hardware-in-the-loop test evidence from the actual board; a successful compile alone is not hardware validation.
• Expansion drivers: Support for additional expansion hardware is welcome under the same conditions. The driver must use the SolarOS driver, service, resource, capability, and package boundaries, and the contributor is responsible for hardware-in-the-loop testing and ongoing regression validation on the actual device.

Keep each pull request focused on one feature and base it on the current upstream branch. Acceptance is decided case by case; contributors should discuss large native applications, new boards, and expansion drivers before investing in a substantial implementation.

Architecture

src/apps/       foreground applications
src/jobs/       background job implementations
src/services/   shared OS services and runtime policy
src/shell/      shell command implementations
src/drivers/    low-level hardware drivers
boards/         TOML board profiles and expansion-driver catalog
scripts/        board-profile generation and desktop configuration tools
packages/       package and flavor catalog
doc/manual/     canonical user manual for GitHub, device, agent, and website
doc/            developer contracts and documentation-system design

Third-party software

SolarOS is licensed under the Apache License 2.0. It also includes the third-party software below under each project's own license. Copyright, attribution, patent, and license notices supplied with these components remain applicable and must be preserved in redistributions.

The SolarOS ports and local adaptations of minimp3, stb_image, U8g2, and libwebp were integrated by nilseuropa.