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. A guest account is created automatically — it accepts any password including blank
3. You're offered the option to add the official package repo

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

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

Two browser-based tools for interacting with a connected device over USB. Both use the Web Serial API (Chrome/Edge 89+).

Web Installer

Flash MicroPython and copy RPCortex to a board directly from your browser using raw REPL mode. No software to install. Requires a bare MicroPython device (not a running RPCortex shell).

Package Browser

Browse the package repo and install packages to a connected board via raw REPL. No WiFi required on the device.

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 overclock: if Settings.OC_On_Boot = true, POST applies Hardware.Max_Clock via machine.freq() on every boot.
• Verbose boot: Settings.Verbose_Boot = false by default. POST only prints warnings and errors. Enable it to see all informational messages.
• Crash sentinel: POST writes 6 to Settings.Startup before clock calibration and clears it on success. If the device crashes mid-calibration, the next boot detects the 6 and disables clocking.

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 must exist. Create it manually if log writes fail:

mkdir /Nebula/Logs

Hardware & Performance

Overclocking

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

pulse oc 220       # overclock to 220 MHz for this session
pulse oc 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
• Editor requires a real terminal — Thonny REPL won't render it
• Log directory — /Nebula/Logs/ is not created automatically; log writes silently fail if it's missing
• Dual user store — usrmgmt.py (active) and regedit.py (unused legacy XOR store) are separate; unification is planned
• No tab completion — planned
• SD card support — registry key exists, implementation pending

RPCortex Nebula v0.8.0-rc4  •  by dash1101