RPCortex β81 - Nebula

RPCortex Nebula — v0.8.1-beta3

v0.8.1-beta3 | Codenamed Nebula | β81

quick note, i just made command execution up to 95% faster.

Full feature reference: NebulaDocs

---

Status

Beta. Stable on RP2040, RP2350, and ESP32-S3. Recommended upgrade from beta2.

---

What's New in beta3

Shell — multi-command lines

• Multiple commands can be run on one line with ; as a separator: mkdir /data; cd /data; touch file.txt
• Quote-aware splitting — ; inside single or double quotes is treated as literal text

Shell — new commands

• grep <pattern> <file> — substring search with line numbers and match count; line-by-line for low RAM
• wc <file> — line / word / byte count
• find [dir] [pattern] — recursive file search by name substring (max depth 8)
• sort <file> — alphabetical sort with 8 KB RAM warning
• uniq <file> — consecutive duplicate line filter
• hex <file> [n] — 16-byte-per-row hexdump with address, hex, and ASCII columns
• basename <path> / dirname <path> — path component extraction
• sleep <secs> — pause the shell (supports decimal, e.g. sleep 0.5)
• which <cmd> — shows where a command is defined: built-in, .lp registry entry, or alias
• rawrepl — cleanly exit the OS and return to MicroPython REPL (for Web Installer use)

Shell — performance

• Removed redundant re-inject on every cached command call — saves 6 setattr calls per dispatch

Browser tools

• OS Update page — version picker now driven by releases/updates.json; add new versions to the JSON without touching HTML
• Install page — version picker driven by releases/releases.json; same pattern
• Package Browser — auto-disconnects the device after a successful package install
• Package Browser — each package card now has a Download .pkg button (fetch + blob, no CORS issues)

---

What's New in beta2 (included)

Shell overhaul

• Tab completion with ghost text — partial command names show a dim gray suffix; press Tab to accept
• Shell aliases — alias name=cmd creates session aliases; unalias removes them; bare alias lists all
• Full cursor navigation: left/right arrows, Home/End, Ctrl+A/E, Delete-forward, character insertion mid-line

OS management — from the shell

• update from-file <path> — apply a .rpc update archive while preserving all user data
• factoryreset — wipe users, packages, and logs; OS files untouched; reboots into first-run setup
• reinstall — full OS wipe with optional .rpc auto-install; use when recovery isn't enough

Browser tools

• Web Installer — flash RPCortex from any Chromium browser over USB; no software, no drivers; wipes device before install for a clean slate
• Browser update page — push a .rpc update from a browser tab to a running device; no WiFi, no raw REPL
• Web package browser — install packages from the browser to a running shell over USB; no reboot required

Registry & boot

• Config cached in memory — registry reads no longer touch the filesystem on every call
• Settings.Verbose_Boot — toggle how much POST prints at boot
• Settings.OC_On_Boot — apply stored overclock on every boot automatically
• Log directory auto-created by POST on first boot

Serial file transfer (_xfer)

• Built-in protocol for receiving files from the browser over serial using base64
• Used by the web package browser and update page to push files without leaving the shell

First-run setup

• Official package repo added automatically
• guest account created silently
• Post-update login banner shows the new version after a successful update

Bug fixes (beta2)

• ls no longer changes CWD when given a path argument
• POST beeper crash fixed
• Recovery shell crash in initialization.py fixed
• Startup mode 7 (boot-clock crash) now shows a login notification

Bug fixes (beta3)

• Ctrl+C cancel fixed
• Tab completion ghost-text edge case fixed
• rm recursion fix

---

Installation

Fresh install: Web Installer — flash from your browser, no software needed.

Update from beta2: OS Update page or update from-file /path/to/os.rpc from the shell. User data and settings are preserved.

Manual: Flash MicroPython v1.25+ (v1.28 recommended), copy files, connect at 115200 baud, reboot.

---

Using rawrepl for a fresh install

If RPCortex is already installed and you want a completely fresh flash:

1. At the shell prompt, run rawrepl
2. The MicroPython REPL (>>>) becomes active in your terminal
3. Open rpc.novalabs.app/install.html in Chrome or Edge
4. Click Connect Device and flash as normal

No need for reinstall or a full wipe — rawrepl simply exits the OS and hands control back to MicroPython.

---

Known Limitations

• MemoryError after heavy use — run freeup; reboot clears completely
• ESP32-S3 temperature reads ~300–450 °C — hardware calibration issue, not a bug
• No real-time clock on base Pico — date shows time since boot epoch
• HTTPS on Pico 1 W needs ~9.5 KB contiguous heap — run freeup first
• WiFi passwords stored plaintext in registry — no secure enclave on this hardware
• Editor requires a real terminal — Thonny REPL won't render it

---

---

Author: dash1101. Issues and PRs welcome.

RPCortex β8X - Nebula

RPCortex Nebula: RPC β8X

v0.8.0-rc | Codenamed Nebula

A CLI operating system for the Raspberry Pi Pico (RP2040 / RP2350) and compatible boards, written entirely in MicroPython. User accounts, WiFi networking, a package manager, a text editor, and a full boot sequence, all on hardware with 264KB of RAM.

---

Status

Stable. Core features are complete and tested. Ships in a clean factory-default state. Confirmed working on RP2040 (Pico W) and ESP32.

Primary interface: serial terminal at 115200 baud (PuTTY recommended)
Thonny's built-in REPL works but has quirks: no arrow key navigation, occasional double-printed input. Use PuTTY for the full experience.

---

What's in v0.8.0-rc

This release covers everything built across the Nebula β8X development cycle, from boot stub to complete OS.

Shell

A colored, interactive prompt (user@nebula:~>) with full cursor navigation. Left/right arrows, Home/End, Delete, and Ctrl+A/E let you edit anywhere in the line. Up/down arrows scroll the last 50 commands.

• Commands are loaded via __import__() for built-ins; they stay in sys.modules permanently after first use. No re-reading or recompiling after a cache clear, which eliminates the memory fragmentation issue that previously crashed reboot and freeup under load.
• MemoryError auto-recovery: the shell clears its cache, compacts the heap, and retries on failure
• reboot, sreboot, freeup, and gc bypass the loader entirely and always work
• Session logging to /Nebula/Logs/latest.log, rotated up to 10 logs
• Recovery shell if the main boot sequence fails
• Shell starts in the user's home directory; ~ shorthand in the prompt

Filesystem

ls, cd, pwd, mkdir, rm, touch, read, head, tail, mv, cp, rename, df, tree, exec

ls shows file type, size, modification timestamp, and name with colored output. cd ~ and cd ~/sub work as expected.

System commands

sysinfo, meminfo, uptime, date, ver, clear, fetch, reboot, sreboot, env, reg, pulse, bench, edit, echo, history, freeup, settings

fetch shows the RPCortex ASCII logo alongside board, CPU, RAM, flash, uptime, and UID. bench runs NebulaMark (integer, float, Mandelbrot, Pi).

Settings panel

settings opens an ANSI box-drawing panel with three sections:

• System: Verbose Boot, Program Execution
• Hardware: Boot Overclock, Beeper, SD Card Support
• Network: WiFi Autoconnect

Title bar shows live CPU frequency, temperature, and free RAM. [1–6] toggle, [r] refresh, [q] quit.

User management

• whoami, mkacct, rmuser, chpswd, logout, exit
• Passwords use salted SHA256, with a unique random salt per account
• Legacy unsalted hashes accepted and upgrade on next password change
• Each account gets /Users/<username>/ created automatically
• guest accepts any password including blank
• Non-root users must verify the target's password before rmuser runs

First-run setup

On first boot a setup wizard runs: sets the root password, creates guest, optionally adds the official package repo. Runs once only.

Networking

WiFi support for any board with a network module: Pico W, Pico 2 W, ESP32.

WiFi: wifi status, wifi scan, wifi connect, wifi disconnect, wifi list, wifi add, wifi forget

Up to 2 networks saved. Autoconnect on boot via Settings.Network_Autoconnect (toggle in settings).

Downloads: wget streams directly to flash (no full-file RAM load), curl fetches to screen, runurl downloads and executes, ping, nslookup.

The HTTP client follows redirects iteratively (no recursion) with a 15-second socket timeout. HTTP and HTTPS both supported.

Package manager

Full package manager. Packages are .pkg files: standard ZIP archives with metadata.

pkg install, pkg remove, pkg list, pkg info, pkg available, pkg search, pkg update, pkg upgrade, pkg repo list/add/remove

• pkg available lists everything in the cached repo index. No query needed.
• Installed commands are live immediately after install
• Removed commands vanish immediately. No reboot either way.
• pkg upgrade compares installed versions against the cache and reinstalls newer ones
• Built-in packages (Launchpad, Editor) show in pkg list and cannot be removed

Repo indexes are JSON files hostable anywhere. repo/make_pkg.py builds .pkg archives from a source directory on your PC. Packages must use ZIP_STORED (no compression); make_pkg.py handles this automatically.

Editor

A full terminal text editor via edit, nano, or vi. Supports find, go-to-line, cut/paste, and save. Requires a real terminal emulator: Thonny REPL won't render it.

Registry

INI-style config at /Nebula/Registry/registry.cfg. Sections: Networks, Hardware, System, Settings, Features, Globals. Created automatically from an embedded template if missing. Read/write with reg get/reg set, or use settings for the common ones.

POST

Every boot:

• Registry check (creates from template if missing)
• CPU arithmetic (float, int, comparison, bitwise)
• RAM test: allocates a verification buffer, writes a pattern, confirms it, then frees. Fast on any platform.
• Clock calibration on first boot: RP2040/RP2350 get 220 MHz as safe max
• Optional boot overclock via Settings.OC_On_Boot
• WiFi check with optional autoconnect
• Beeper init (non-fatal)

Verbose boot is off by default. Enable in settings to see all POST output.

---

Installation

1. Flash MicroPython firmware to your board (v1.20 or newer, v1.27+ recommended)
2. Copy all files from this release to the root of the board's filesystem
3. Connect via serial terminal at 115200 baud
4. Reboot: main.py runs automatically
5. Complete first-run setup and log in

---

Supported hardware

Board	Status
Raspberry Pi Pico 2 W (RP2350 + WiFi)	Recommended
ESP32-S3	Recommended
Raspberry Pi Pico (RP2040)	Supported
Raspberry Pi Pico W (RP2040 + WiFi)	Supported
Raspberry Pi Pico 2 (RP2350)	Supported
ESP32 / ESP32-S2	Supported

---

Known limitations

• MemoryError may occasionally occur in the shell due to heap fragmentation. freeup compacts the heap; reboot clears it fully. Being actively worked on.
• ESP32-S3 temperature sensor reports unrealistic values (typically 300–450 °C) due to hardware calibration differences. Not an RPCortex bug — RP2040/RP2350 temperature is accurate.
• No real-time clock on base Pico: date shows time since boot epoch until RTC is set
• HTTPS on Pico 1 W needs ~9.5 KB contiguous heap: run freeup first if the heap is fragmented
• WiFi passwords stored plaintext in the registry: no secure enclave on this hardware
• The editor requires a real terminal emulator: Thonny REPL won't render it
• /Nebula/Logs/ must be created manually if missing: log writes silently fail otherwise

---

What's next

• Tab completion
• Shell aliases
• SD card support
• Unified user system
• Log directory auto-creation on first boot

---

Author: dash1101. Issues and PRs welcome.

RPC - Fusion

*Introducing RPCortex Fusion

Fusion: Version 0.7.0-alpha of RPCortex

Released: March 2nd, 2025

What is Fusion?

Fusion represents an alpha release of RPCortex, where new features, improvements, and bug fixes are continuously evolving. While many core features are already functional, expect some changes as RPCortex comes to life.

---

What’s the Goal?

1. Revise and Revamp: A complete overhaul of the Hyperion codebase for better performance, stability, and user experience.
2. Optimize and Fine-tune: Making the system faster, more memory efficient, and more reliable.
3. Improve commands: Instead of focusing on a GUI, I will try to make the actual core better so that having a GUI would make sense later on.

---

New Features, Updates, and Enhancements

File Management

• New File System API: Complete rewrite for better performance and stability.

---

Fusion Features & Improvements

✅ "Work in progress, will likely appear in the final release."
🟨 "Under development, may not make it into this release, but possibly a future one."
🟦 "(Concept) Not going to be in final release, or potential future releases."

• ✅ *Many Hyperion Features
• ✅ Modular Program Launching System
• ✅ Boosted Command Execution Speed
• ✅ Updated CLI Shell
• ✅ Code Efficiency Enhancements
• ✅ User Management: Multiple users, each locked behind their own encrypted password.
• ✅ System Diagnostics: Inbuilt tools for troubleshooting and monitoring.
• ✅ Interface API: Access to core components like LEDs, buzzers, serial ports, TFT displays, joysticks, buttons, and touchscreens.
• ✅ Flash Memory File System: Optimized file system for flash memory.
• ✅ Core Clock Modification: Control the device's clock speed for performance improvements.
• ✅ Improved User Experience: Sleeker, more intuitive UI/UX for a better experience.

---

Recovery Mode & Backup Tools

• Recovery Mode: A toolset for handling system recovery.
• User Registry & Folder: A user-specific registry for easy management of user files and preferences.

---

For Developers

RPCortex Fusion introduces new tools for building, testing, and deploying applications:

• Launchpad: A tool to manage program execution, making sure all rules like API and user management are followed.

Documentation

---

Installation Instructions

1. Make sure you have Micro Python installed on your Raspberry Pi Pico.
2. Copy all Fusion files to the root directory of your device.
3. Reboot your device, and RPCortex Fusion will launch automatically.

---

Recommended Specifications

• Device: Raspberry Pi Pico 2 W @ 200 MHz

---

A little note, I do realize that some of this info in not accurate, and misleading. In the next release of RPC I'll try my best to make this all make more sense.
This release is an alpha release, and is missing some Hyperion features. This release should be seen more as a concept release / pre-release that isn't fully finished. I am hoping that v1.0 has the features and capabilities that I hoped for this version to have...

RPC - Hyperion

Codename Hyperion

Hyperion is the definitive version of RPCortex. It's the one that sets the bar for future releases.
Hyperion is setting the new standard for RPCortex. Things will be going through a redesign, and we are skipping v0.3.5 in favor of just pushing everything out in a single stable-ish release.

Changelog, Updates, and Features:

File management:

Internal Flash Support will be added so that micro controllers like the Pico-(w) 1/2's files can be accessed
Many familiar commands like cat, dir, mkdir, rmdir, del, write, help, chdir, cd, ls, cd, touch, pwd, etc. will all be added.

I/O

All will be documented when released:
Hyperion can be run from Serial and a TFT Display.
WiFi Support has been added for the RP2040, and RP2350 with a custom made driver.

External Features

Morse Code on Beeper, LED, Serial, and TFT
Macro buttons that can be bonded to run specific actions
Interface API for developers (not finished)

HyperionOS

✅ TFT Display Support: Display API with interchangeable drivers.
✅ Joystick Functionality: Interface API for joystick control.
✅ Button Functionality: Interface API for buttons.
✅ Beeper Functionality: Interface API for the onboard beeper.
✅ WiFi Functionality: Networking support (Connect, Scan, Download, Serve, dnslookup, ping, ifconfig, etc.)
✅ Serve Function: Program to host files over IP and port.
✅ Flash Memory File System: FS API for file management.
✅ Serial Support: String input and output via serial interface.
✅ User Profiles: Basic user management system.
✅ OS Verification: Planned feature for file integrity checks.
✅ System Redundancy: System files are locked so no accidental OS deletions.
✅ Kill running process with CTRL+C

Documentation

Testing Config:

This project has been tested and ran and programmed off of the following:
Raspberry Pi Pico-W: Dev-kit for RPCortex
Breakout Board Kit
Thonny on Windows 11: Programming environment

Installation

• Download the latest stable release of MicroPython
• Boot your chosen device in boot loader mode and add the MicroPython.uf2 file to its root directory.
• Download Thonny), or similar Python editor that gives file access
• Download RPC.Hyperion.zip
• Extract RPC.Hyperion
• Using Thonny and its file viewer, copy the main.py and Hyperion folder to the root directory of your device
• Once copied, reboot and everything should be installed.

Minimum Requirements:

Display and Serial Support:
rp2040 powered device with preferably 264kb+ ram
Serial Only:
esp32-s3 devices.
Networking:
Pico-W

Support for more hardware configurations are coming soon, hopefully in v1.0

RPCortex v0.3.5-a

RPCORTEX Version: v0.3.5-a

Be expecting this release to launch sometime next month. I'm taking a little break and working on making my workflow more efficient for RPCortex!!!

As of now, the external flash support is not working in my favor...
Internal will come after because some commands I want to add rely on external.

This will probably be one of the most important releases. That's why its 0.3.5 instead of 0.3.0
The reason of that is:

Changelog

v0.4.0-alpha

Release date: 2024, Late March - Early April
❌Some multi threading support
❌Force quit active command / program via serial. To do this, send (kill -SIGINT)

v0.3.5-alpha

Release date: 2024, Mid March - Late March
❌Download commands for pico-w
❌RGB LED support
❌Morse LED
❌Button Macro support (ONLY 1 AS OF NOW)
❌Joystick support for GUI APPS!!! (None as of now, but v1.0.0-rc will have some I'm sure, as well as touch support.)

v0.3.0-a

❌ Some apps/cmds which include:
ls/dir
❌ Improvments on file system, and commands
🟨 External flash support

v0.2.5-a

❌ Internal flash fs (NO LS/DIR)
🟨 Some apps/cmds which include:
cat, dir, mkdir, rmdir, del, write, help, chdir, cd

Previous Versions

✅ ALL THE COLORS!!!
✅ Print drivers can print without line now
✅ Morse code with beeper
✅ More stable, Display and System
✅ Easier to setup
✅ On the fly setup for some objects
✅ Clear screen for TFT
✅ Print command
✅ beep command
✅ More stable display adapter
✅ Concept display adapter
✅ Concept command executer
✅ An idea of what the future of RPC will look like

RPCortex v0.2.0-a

RPCORTEX Version: v0.2.0-a

Well, we got some new stuff!!

Installation

1. Download this release of RPCortex.
2. Connect your RP2040 device to your computer while holding the (boot sel) button.
3. Open the (rpc[ver].ino) in Arduino IDE, and install TFT_eSPI in the library manager.
4. Assign the variables according to your display
5. Only do the TFT_eSPI steps if you have a TFT display, otherwise everything will be done in serial. You will have to modify the code and remove anything referencing the TFT_eSPI.
6. Configure the file to your likings
7. Select Pico as your device.
8. Press upload!

Features

Terminal CLI

• RPCortex currently is a CLI, but in the future, I plan to add a GUI with a desktop window manager, similar to some linux repos

Display Support

• Custom-made drivers to support TFT displays.
• Support for communication thru serial at 230400baud

Getting Started

To get started with RPCortex, follow the installation steps mentioned below. Once installed, explore the built-in features and customize your experience.

• Get connected via ST7796 display, Serial(9600 baud), and HDMI coming one day.
• SD/TF CARD SUPPORT IS NOT ACTIVE AS OF NOW, should be in the future though.
• Follow the setup process
• Enjoy!

Usage

TFT Displays

Please be sure to configure your display according to the User_Setup.h file. You can find this in the Arduino folder, then libraries, then TFT_eSPI, and open User_Setup.h
In this file you can setup your TFT display. Currently, this code is built around the ST7796 display, so results may vary
otherwise, you can choose the pins in the #defines and add one of the following display defines according to your display.

//#define ILI9341_DRIVER // Generic driver for common displays
//#define ILI9341_2_DRIVER // Alternative ILI9341 driver, see Bodmer/TFT_eSPI#1172
//#define ST7735_DRIVER // Define additional parameters below for this display
//#define ILI9163_DRIVER // Define additional parameters below for this display
//#define S6D02A1_DRIVER
//#define RPI_ILI9486_DRIVER // 20MHz maximum SPI
//#define HX8357D_DRIVER
//#define ILI9481_DRIVER
//#define ILI9486_DRIVER
//#define ILI9488_DRIVER // WARNING: Do not connect ILI9488 display SDO to MISO if other devices share the SPI bus (TFT SDO does NOT tristate when CS is high)
//#define ST7789_DRIVER // Full configuration option, define additional parameters below for this display
//#define ST7789_2_DRIVER // Minimal configuration option, define additional parameters below for this display
//#define R61581_DRIVER
//#define RM68140_DRIVER
#define ST7796_DRIVER
//#define SSD1351_DRIVER
//#define SSD1963_480_DRIVER
//#define SSD1963_800_DRIVER
//#define SSD1963_800ALT_DRIVER
//#define ILI9225_DRIVER
//#define GC9A01_DRIVER

Changelog

This release is mainly just a concept. A place to test things. Nothing here will be in the final v1.0.0-rc, but hey I'm getting there.

• v0.2.5-a

🟨 Internal flash fs (NO LS/DIR)
🟨 Some apps/cmds which include:
cat, dir, mkdir, rmdir, del, write, help, chdir, cd

• v0.2.0-a

✅ ALL THE COLORS!!!
✅ Print drivers can print without line now
✅ Morse code with beeper
✅ More stable, Display and System
✅ Easier to setup
✅ On the fly setup for some objects
✅ Clear screen for TFT
✅ Print command

• v0.1.5-a

✅ beep command
✅ More stable display adapter

• v0.1.0-a

✅ Concept display adapter
✅ Concept command executer
✅ An idea of what the future of RPC will look like

License

RPCortex v0.2.0-a is licensed under the MIT License.

RPCortex v0.1.0-a

Version: v0.1.0-a

Ver 0.1.0-a, this is akward. This release is really just a proof of concept so that I can get something out here.
DO NOT expect anything to really work smoothly, or at all in some cases.
I apologize in advance for anyone trying to read the code ❤️.

Installation

1. Download this release of RPCortex.
2. Connect your RP2040 device to your computer while holding the (boot sel) button.
3. Open the (rpc[ver].ino) in Arduino IDE, and install TFT_eSPI in the library manager.
4. Find the Arduino folder, usually in Documents, open the TFT_eSPI folder and open User_Setup.h
5. Only do the TFT_eSPI steps if you have a TFT display, otherwise everything will be done in serial. You will have to modify the code and remove anything referencing the TFT_eSPI.
6. Configure the file to your likings
7. Select Pico as your device.
8. Press upload!

Features

Terminal CLI

• RPCortex currently is a CLI, but in the future, I plan to add a GUI with a desktop window manager, similar to some linux repos

Display Support

• Custom-made drivers to support TFT displays.
• Support for communication thru serial at 230400baud

Getting Started

To get started with RPCortex, follow the installation steps mentioned below. Once installed, explore the built-in features and customize your experience.

• Upload (rpc[ver].ino) to rp2040 device
• Get connected via ST7796 display, Serial(9600 baud), and HDMI coming one day.
• SD/TF CARD SUPPORT IS NOT ACTIVE AS OF NOW, should be in the future though.
• Follow the setup process
• Enjoy!

Usage

TFT Displays

Please be sure to configure your display according to the User_Setup.h file. You can find this in the Arduino folder, then libraries, then TFT_eSPI, and open User_Setup.h
In this file you can setup your TFT display. Currently, this code is built around the ST7796 display, so results may vary

Release Notes

This release is mainly just a concept. A place to test things. Nothing here will be in the final v1.0.0-rc, but hey I'm getting there.

License

RPCortex v0.1.0-a is licensed under the MIT License.