Start here

SolarOS quick start

Build and flash 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.

Build and flash

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 waveshare_esp32_s3_rlcd_4_2

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 waveshare_esp32_s3_rlcd_4_2 -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 long press forgets the remembered BLE keyboard and starts pairing again.

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 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

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.