Start here · Tutorial

SolarOS quick start

Install SolarOS, connect a keyboard, and take the first useful steps at the shell. The examples use SolarTerm where board-specific instructions are needed, but the same SolarOS commands work on every supported target.

Install with the Flasher

Open the SolarOS Flasher in Chrome or Edge on a desktop computer. Connect the board with a USB data cable, then:

1. Select the board, flavor, and SolarOS version.
2. Choose Prepare image. The Flasher downloads the selected release and verifies its signed catalog, archive, and factory image.
3. Read and accept the erase warning. Installation replaces everything in the device's internal flash, including settings, Wi-Fi credentials, applications, and internally stored files.
4. Choose Connect and flash, select the board's serial port, and keep the cable connected until installation completes.

If the board does not enter download mode automatically, follow the board-specific instructions shown by the Flasher. The board should restart when installation completes; if it does not, press RESET once or power-cycle it.

Build and flash from source

You need Git, Python 3, PlatformIO Core, and a USB data cable. After installing PlatformIO, make sure pio is on your path:

export PATH="$PATH:$HOME/.platformio/penv/bin"

Clone SolarOS and choose the environment for your board:

git clone https://github.com/nilseuropa/solar_os.git
cd solar_os
pio run -e solar_term

The first build downloads the toolchain and dependencies. Continue when PlatformIO reports SUCCESS.

The Freenove target uses its board-specific rover flavor family:

SOLAR_OS_FLAVOR=rover pio run -e freenove_esp32_wrover_v3

Its 4 MiB flash layout has one factory application slot, so install it through the CH340 serial connection. It does not support on-device OTA updates.

Connect the board and find its serial port:

pio device list

Typical names are /dev/ttyACM0 or /dev/ttyUSB0 on Linux, /dev/cu.usbmodem... on macOS, and COM... on Windows. Flash the environment you built:

pio run -e solar_term -t upload --upload-port <PORT>

For SolarTerm, press PWR once to turn it on. If it is not already in download mode, long-press PWR to turn it off, hold BOOT, press PWR once, and release BOOT when the USB port appears. Keep the cable connected until PlatformIO reports SUCCESS.

The SolarTerm project has the full assembly, build, flash, enclosure, and first-boot notes for that device.

First boot and keyboard pairing

SolarOS uses one board button as KEY. A short press puts the device into light sleep, and another press wakes it. A long press forgets the remembered BLE keyboard and starts pairing again. The short-press action can be changed with power key; the default is light.

1. Boot the device and wait for the SolarOS shell.
2. Turn on the keyboard and put it into its own pairing mode.
3. Hold the board's KEY for about two seconds and release it when the keyboard icon in the status bar changes to its pairing/scanning state. The display shell does not print a pairing message. On a headless board, enter ble pair in the serial shell for visible status instead.
4. Wait for the connection, then type at the shell.

SolarOS remembers one keyboard and reconnects to it on later boots. You can inspect the current state with:

ble status

On the Freenove and DevKitC targets, do not hold BOOT during reset or power-up: GPIO0 low at that time selects the serial download boot mode.

Configure power and battery

SolarOS starts with the balanced power profile. On a portable device, select the battery profile and make sure the short KEY press is enabled:

power profile battery
power key light
power status

The setting is saved in NVS and remains active after a reboot. The profiles make these tradeoffs:

A board can enforce a higher CPU floor for hardware such as video output. Run power status to see the effective frequency and sleep policy.

power profile also restores that profile's default idle timeout. To choose a different display-shell timeout afterward, use power idle <seconds> or power idle off. You can enter light sleep immediately with a short press of KEY or with power sleep in the display shell. Press KEY to wake. Holding KEY for about two seconds is still the separate BLE pairing action. On the Waveshare board, PWR is different: press it once to power on and hold it to power the hardware off.

Waveshare 18650 setup

The Waveshare ESP32-S3-RLCD-4.2 uses one rechargeable 3.7 V 18650 cell. Power the board off before inserting or removing it, match the polarity marked on the holder, and do not use the display as a handhold. If the WRN indicator lights, remove the cell and correct its orientation before connecting USB-C. The CHG indicator turns off when charging is complete.

SolarOS cannot know the capacity printed on your cell. Configure that value, then verify the voltage thresholds used for the percentage estimate and the low-voltage monitor:

battery capacity <RATED_MAH>
battery min_voltage 3.0
battery max_voltage 4.12
battery config
battery status

Replace <RATED_MAH> with the rated capacity printed on the installed cell. SolarOS defaults to 3.0 V for empty/low voltage and 4.12 V for full or external power on this board. Change them only when the cell manufacturer's limits require different values; min_voltage must remain lower than max_voltage.

Start the battery monitor so SolarOS tracks the voltage trend and enters light sleep after three consecutive samples at or below min_voltage while the device is running on battery:

job start batmon 60
job status batmon

Jobs do not restart automatically. To monitor the battery after every reboot, run setterm startup to see the selected startup-script path, add job start batmon 60 to that file, and reboot. On the Waveshare board the default path is /flash/.shell/startup; if setterm startup sd is selected, use /sdcard/.shell/startup instead.

Prepare an SD card

An SD card is optional for normal SolarOS operation, but it provides the most useful space for applications, scripts, documents, captures, and the downloadable exact-version manual.

• Format the card as FAT32 on a computer. A single FAT32 partition is the simplest layout.
• Power the SolarOS device off before inserting or removing the card.
• Insert the card and boot the device. Supported boards mount it automatically.

Check the card from the shell:

sd status
df

On SD-backed boards, the card is the default storage shown as / and is also available internally at /sdcard; internal flash remains available at /flash. If the card is detected but not mounted, inspect it and retry:

sd lsblk
sd mount

Set identity and connect to Wi-Fi

Set the user shown in the prompt and the hostname advertised on the network:

identity status
identity user yourname
identity hostname solarterm

The identity is saved in NVS. The user also becomes the default remote username for ssh and scp. Reboot after changing the hostname so that Wi-Fi, DHCP, and network advertisements all use the new value.

Connect to Wi-Fi:

wifi scan
wifi connect YOUR_SSID YOUR_PASSWORD
wifi status

Continue when wifi status shows that the device is connected and has an IP address.

Update the on-device manual

With Wi-Fi connected and the SD card mounted, download the manual published for the exact SolarOS version running on the device:

help update
help status

SolarOS verifies the signed catalog and manual archive before activating it. An interrupted or invalid update leaves the embedded manual available. Run help update again after installing a new firmware version so the external manual matches it.

Navigate the shell

The display shell keeps command history and scrollback, and foreground apps use the same small set of navigation keys:

• Page Up and Page Down move backward and forward through shell

scrollback. In apps, they usually move by a page.

• Up and Down recall earlier and later commands at the shell prompt. In

menus and apps, they usually move the selection or cursor.

• Alt+Tab switches between resumable foreground sessions on display builds.
• CTRL+ALT+DEL exits the active foreground app and returns to the shell.
• Esc cancels or backs out of the current view when an app supports it. At

the shell prompt, it clears the command currently being typed.

Basic usage

Then get oriented:

help
commands
apps
jobs

• help opens the user manual; man TOPIC opens a specific topic.
• commands, apps, and jobs show what is available in the running firmware flavor.
• Tab completes commands and paths.
• In a serial or network shell, use Ctrl+] instead of CTRL+ALT+DEL to exit

a foreground app.

Troubleshooting

The BLE keyboard does not pair

Check the current state:

ble status

If the keyboard was paired with another host or SolarOS has a stale remembered device, reset both sides:

ble forget
ble pair

Put the keyboard back into its own pairing mode immediately before ble pair. Keep it close to the device and make sure it is charged. SolarOS remembers only one keyboard, so pairing a replacement requires forgetting the old one.

The serial port does not appear or upload cannot connect

• Use a known USB data cable and try another port on the computer.
• On SolarTerm, repeat the BOOT/PWR download-mode sequence above.
• Close serial monitors or other programs that may have the port open.
• On Linux, install PlatformIO's udev rules if access is denied.
• If the build configuration is stale, run pio run -e <ENVIRONMENT> -t clean, rebuild, and retry.

Regain access without a working keyboard

On an SD-backed target, a prepared card can connect SolarOS to Wi-Fi and start a temporary remote shell during boot:

• Format an SD card as FAT32.
• At the card root, create a directory named .shell.
• Create .shell/startup with no file extension and these two lines:

wifi connect YOUR_SSID YOUR_PASSWORD
job start telnetd 2323 --password TEMPORARY_PASSWORD

• Insert the card while the device is powered off, then boot it.
• Find the device's IP address in the router's client list and connect with telnet DEVICE_IP 2323.

This recovery path requires a firmware flavor that includes Wi-Fi and the telnetd job. Telnet is unencrypted, including its password, so use it only on a trusted network. Once access is restored, stop it with job stop telnetd and remove the startup file or recovery card. The Wi-Fi and Telnet passwords are also stored as plain text in that file.

On the headless DevKitC target, use its 115200-baud serial shell instead. If neither recovery path is available, re-enter the board's download mode and flash a known-good SolarOS image.

For deeper help, open the SolarOS user manual.