Documentation

Getting Started

What you need:

• Raspberry Pi Pico, Pico W, Pico 2, or a compatible ESP32 board
• MicroPython firmware v1.20 or newer (v1.27+ recommended)
• A serial terminal at 115200 baud — PuTTY on Windows, minicom or screen on Linux/macOS

Installation

1. Flash MicroPython to your board
2. Copy all files from the repo to the root of the board's filesystem
3. Connect your serial terminal at 115200 baud
4. Reboot — main.py starts automatically on power-up

First boot

A setup wizard runs on first boot:

1. You set the root password (the administrator account)
2. You choose whether to enable verbose boot (detailed POST messages on each startup)
3. A guest account is created automatically — it accepts any password including blank

The official package repo is added automatically. Run pkg update after first boot to fetch the package list.

After that, log in and you're at the shell prompt. The wizard only runs once.

Boot Sequence

main.py
  └── Core/post.py              POST: hardware checks, registry, WiFi
       └── Core/initialization.py   reads startup mode, runs login loop
            └── Core/launchpad.py   launchpad_init -- the interactive shell

If initialization fails, recovery_init() starts an unauthenticated shell so you can diagnose the problem. The recovery shell has access to all the same commands.

The Shell

The shell prompt format is:

username@nebula:~>
username@nebula:~/docs>
username@nebula:/Core>

~ is shorthand for the user's home directory (/Users/<username>/). The shell starts there on login. cd ~ and bare cd both return home.

Keyboard shortcuts

Characters are inserted at the cursor position — you can edit anywhere in the line, not just at the end.

Command loading

Built-in commands (sys_fs, sys_sys, sys_net, sys_user, wifi, settings) are loaded via __import__() and live in sys.modules permanently. After a cache clear they reload for free — no re-reading or recompiling. Package-installed commands use a separate exec-based path.

Critical commands

reboot, sreboot, freeup, and gc are implemented as inline functions that bypass the loader entirely. They always work regardless of heap state.

Heap management

The RP2040 has 264 KB of RAM. After loading several commands or running HTTPS requests, the heap may become fragmented — gc.mem_free() can show 90 KB free while a MemoryError still occurs, because no single contiguous block is large enough for a new allocation. Run freeup to compact the heap. The shell also automatically retries after a cache clear on MemoryError.

Filesystem Commands

System Commands

pulse subcommands

OS Management

These commands manage the OS itself — updates, factory reset, and full reinstall.

update from-file

Extracts a .rpc release archive to the running OS:

update from-file /path/to/os.rpc

• Preserves /Users/, /Nebula/ (accounts, WiFi credentials, package config)
• Sets a crash sentinel before writing files — if the device loses power mid-update, the sentinel is detected on the next boot
• Reboots automatically on success; shows "Now running RPCortex vX.Y.Z" at next login

factoryreset

Soft reset — restores the OS to a clean first-run state while keeping core files intact:

factoryreset

• Restores registry defaults
• Wipes all user accounts and home directories
• Removes non-builtin packages
• Clears logs
• Prompts CONFIRM before proceeding
• Reboots into the first-run setup wizard

reinstall

Full OS wipe — deletes everything and writes a self-contained reinstall stub:

reinstall                      # wipe and show Web Installer instructions
reinstall /path/to/os.rpc      # wipe and stage .rpc for auto-install on boot

• Deletes /Core/, /Packages/, /Nebula/, /Users/
• Writes a minimal stub as /main.py that extracts /update.rpc on the next boot
• Prompts WIPE before proceeding
• If a .rpc path is given, it is staged as /update.rpc and extracted automatically on the next boot

User Management

Account details

• Profiles stored in /Nebula/Registry/user.cfg as CSV
• Each account gets /Users/<username>/ created on account creation
• Passwords stored as salted SHA256 — unique salt per account
• guest uses the NOPASS marker — any password, including blank, is accepted
• root is created during first-run setup and is the administrator account

Networking

WiFi works on any board with a network module: Pico W, Pico 2 W, and most ESP32 variants.

WiFi commands

Up to 2 networks can be saved. Enable autoconnect on boot:

reg set Settings.Network_Autoconnect true

Or toggle it in settings.

Download commands

Both HTTP and HTTPS are supported. The client follows redirects iteratively with a 15-second socket timeout.

Package Manager

Packages are .pkg files: standard ZIP archives with a package.cfg metadata file inside.

Package metadata (package.cfg)

Commands

Commands installed by packages are available immediately after install. They vanish immediately after removal. No reboot required either way.

Quick start

pkg repo add http://rpc.novalabs.app/repo/index.json
pkg update
pkg available
pkg install HelloWorld

Repo index format

Repos are JSON files hosted anywhere (GitHub raw URLs work):

{
  "name": "My Repo",
  "packages": [
    {
      "name": "HelloWorld",
      "ver": "1.0.0",
      "author": "dash1101",
      "desc": "Sample package",
      "url": "https://..."
    }
  ]
}

Building packages

repo/make_pkg.py is a PC-side script that builds a .pkg from a source directory:

python make_pkg.py MyPackage/

Packages must use ZIP_STORED (no compression) — make_pkg.py handles this automatically. If you build with a standard ZIP tool using deflate, install will fail unless the target firmware has zlib.

Full package development guide →

Web Tools

Three browser-based tools let you interact with a connected device over USB — no WiFi, no raw REPL required. All use the Web Serial API (Chromium-based browsers: Chrome, Edge).

Web Installer

Flash MicroPython and copy RPCortex to the board directly from your browser. No software to install.

Package Browser

Browse and install packages while the device is running the shell. Files are pushed via the _xfer serial protocol. One-click install, no reboot needed, no WiFi required on the device.

OS Update

Update RPCortex from a browser tab while the shell is running. Load a .rpc archive from your computer or pick a version from the server. The page reads the archive with JSZip, skips user data paths, pushes each file via _xfer, and sends reboot when done.

Editor

The built-in terminal editor is invoked with:

edit myfile.py
nano /Core/somefile.py
vi                         # scratch buffer, no file

Controls

Settings Panel

Run settings to open an interactive panel:

┌───────────────────────────────────────────────────────────────┐
│  RPCortex Settings               125 MHz  27.4C  92 KB      │
├───────────────────────────────────────────────────────────────┤
│                                                              │
│  SYSTEM                                                      │
│  [1] Verbose Boot         : OFF                              │
│  [2] Program Execution    : ON                               │
│                                                              │
│  HARDWARE                                                    │
│  [3] Boot Overclock       : OFF                              │
│  [4] Beeper               : OFF                              │
│  [5] SD Card Support      : OFF                              │
│                                                              │
│  NETWORK                                                     │
│  [6] WiFi Autoconnect     : ON                               │
│                                                              │
│  [1-6] toggle   [r] refresh   [q] quit                       │
│                                                              │
└───────────────────────────────────────────────────────────────┘

[1–6] toggle the setting. [r] refreshes the display. [q] exits.

Settings reference

Registry

The registry lives at /Nebula/Registry/registry.cfg as a plain INI file. It's created from an embedded template on first boot if missing.

[Settings]

[Hardware]

[Networks]

WiFi credentials for up to 2 saved networks. Keys are created dynamically when you save a network.

[Features]

Shell access

reg get Settings.OC_On_Boot        # read a key
reg set Settings.OC_On_Boot true   # write a key
env                                 # dump all sections
env Settings                        # dump one section

POST

POST runs on every boot before the login prompt. It prints status for each check and stops if a critical check fails.

• Boot clock: if Settings.OC_On_Boot = true, POST reads Hardware.Boot_Clock (falls back to Hardware.Max_Clock) and applies it via machine.freq(). A crash sentinel (7) is written before the clock is applied — if the device crashes here, boot clock is disabled automatically on the next boot.
• Verbose boot: Settings.Verbose_Boot = false by default. POST only prints warnings and errors. Enable it to see all informational messages.
• Crash sentinels: 6 is written before clock calibration, 7 before applying the boot clock. If the device crashes during either, the sentinel disables the relevant feature on the next boot.

Session Logging

Every session is logged to /Nebula/Logs/latest.log. The log captures everything printed through the OS output functions (ok, info, warn, error, fatal).

Log rotation on each boot:

latest.log -> log_1.log -> log_2.log -> ... -> log_9.log (dropped)

Up to 10 logs are kept. The /Nebula/Logs/ directory is created automatically by POST on first boot. You don't need to create it manually.

Hardware & Performance

Overclocking

RPCortex detects the CPU's safe clock range on first boot. For RP2040/RP2350 the stored max is 220 MHz.

pulse set 220      # set CPU to 220 MHz for this session
pulse set 240      # overclock beyond safe default (warning shown)
pulse boot on      # apply on every boot
settings           # toggle via settings panel

Manual overclock beyond 220 MHz is allowed. A warning is shown but the clock is set to whatever you specify. The RP2040 is generally stable up to around 240–250 MHz with the right flash timing.

NebulaMark

bench runs the NebulaMark suite: integer ops, floating-point ops, Mandelbrot iteration, and Pi approximation. Results are printed as calculation times in milliseconds.

Heap and fragmentation

freeup clears the command cache and runs garbage collection. Use it before heavy network operations or when you get a MemoryError despite apparent free RAM. meminfo shows the current heap state.

Supported Hardware

MicroPython v1.20 or newer  •  4 MB flash recommended  •  256 KB+ RAM  •  Serial terminal at 115200 baud

Security

• Passwords use salted SHA256. Each account has a unique random salt, so rainbow tables don't apply. Accounts created before v0.8.0-rc used unsalted SHA256 and upgrade on the next password change.
• WiFi credentials are stored in plaintext in registry.cfg. There is no secure storage mechanism on this hardware.
• Home directories provide logical separation at /Users/<username>/. There is no kernel-enforced permission model.

Known Limitations

• MemoryError in the shell — may occur after heavy use due to heap fragmentation. Run freeup to compact the heap. If it persists, reboot clears it. Being actively worked on.
• ESP32-S3 temperature sensor — the onboard temperature sensor on ESP32-S3 is not calibrated in the same way as the RP2040. fetch will show unrealistic values (typically 300–450 °C). This is a hardware/firmware limitation, not a bug in RPCortex. RP2040/RP2350 temperature is accurate.
• No real-time clock on base Pico — date shows time since boot epoch until the RTC is set manually
• HTTPS on Pico 1 W — TLS needs ~9.5 KB contiguous heap; run freeup first if the heap is fragmented
• WiFi passwords stored plaintext — no secure enclave on this hardware
• Editor requires a real terminal — Thonny REPL won't render it
• No tab completion — planned
• SD card support — registry key exists, implementation pending

RPCortex Nebula v0.8.1-beta2  •  by dash1101