This page covers Pico Portal OS through 2.1.0. If you're looking for the original standalone portal, see the 1.x reference. Its setup and button mappings are different from the current version.
What changed with 2.x
The original project was an access point and web server. The OS starts with a launcher instead, so the portal is one app among several. I can open a tool, use it, and go back to the menu without rebuilding the device around another script.
This is still MicroPython on a microcontroller. The "OS" part refers to the shell and how the apps fit together. It isn't Linux, and the Pico didn't secretly pick up the memory of a full Raspberry Pi.
The interface has phosphor colors, scanlines, a boot sequence, and a shared navigation scheme. Bottom-left moves up, bottom-right moves down, top-right selects, and top-left goes back. Every menu works the same way.
The hardware is still small
The board is a Raspberry Pi Pico W with 264 KB of SRAM. Both the Pimoroni 1.14-inch Display Pack and 2.0-inch Display Pack are supported, at 240 by 135 and 320 by 240 pixels. They share a display controller, so the OS asks which panel is attached on first boot. The hardware can't identify the glass, and pretending otherwise didn't seem useful.
The choice is saved in config.json. Hold the bottom-left button during boot to open the picker again. The UI reads the selected screen bounds, so the same apps work on both panels.
The small build uses a Pico-UPS-B battery board and the larger build uses a LiPo SHIM. Battery readings depend on which one is installed. USB power masks the cell voltage on the LiPo SHIM build, so the UI doesn't make up a charge percentage while USB is plugged in. Voltage-based percentages are only estimates anyway.
WiFi and Bluetooth tools
WiFi Tools includes access point discovery, signal tracking, Channel Radar, WiFi Analyzer, Network Monitor, mDNS/SSDP discovery, and the local portal. Bluetooth Tools has a BLE discovery view and Sensor Radar, which reads supported temperature and humidity data from advertising packets.
These screens have limits. RSSI measures signal strength, not distance. The WiFi waterfall and channel suggestions use access point scans and counts, not spectrum energy or network throughput. A busy chart doesn't tell me how much data is moving.
The LAN service tool uses standard mDNS and SSDP discovery on whatever network I've joined. The BLE sensor reader listens to broadcasts without pairing. WiFi settings can join a network and reconnect at boot if credentials are saved. Leave them blank and the device stays offline.
The portal now has its own menu
The original Pico Portal still lives under WiFi Tools. Its menu lets me set the AP name and password, choose the local and success pages, and start the server. Templates are in /templates/login/ and /templates/success/.
The demo form logs submitted usernames and passwords to /portal.log.
Apps, games, and things to leave running
Apps includes a dice roller, a stopwatch with recent laps, offline World English Bible excerpts, and US weather by ZIP code. Weather needs WiFi, looks up the ZIP code, then pulls the forecast from Open-Meteo. Everything else works offline.
The Games menu has Breakout, Reflex, Snake, and Tetris. There are also 17 screensavers, including Matrix, Aquarium, Game of Life, a wireframe scene, and a system dashboard. Some of them only simulate terminal or radar activity, but System Monitor and the dashboard use real device telemetry.
Settings handles the display theme, scanlines, text size, screen and LED brightness, clock, regional units, WiFi, and idle screensaver. System Tools collects battery information, filesystem usage, screen tests, and live device details. I mostly use those to figure out whether a problem is the software, the power, or the display.
2.1.0 brought the screen back to my computer
USB screen capture connects the Pico to the Screen Capture tool on this site. In Chrome or Edge, I select the Pico's serial port and save the display as a PNG. Thonny and other serial consoles need to be closed first.
The capture hook streams the framebuffer that's already there. The small display uses RGB332. The larger profile uses indexed P8 when available and falls back to RGB332. Streaming means I don't have to allocate a second full framebuffer on a device that doesn't have much RAM to spare.
Capture interrupts the current app so it can use the MicroPython console. After the transfer, the browser sends a soft reset and the OS starts again. If a capture is canceled or fails, it cleans up the same way. It's one screenshot at a time, not continuous recording.
The companion Image Converter prepares RGB565 image assets and a PNG preview. Device assets and captured framebuffers don't always use the same format, which is easy to forget while editing graphics.
Building and installing the current OS
The Pico Portal repository has the current source and installation guide. Start with Pimoroni's MicroPython firmware for the Pico W, since the display and button modules come from it. Before building, make sure your mpy-cross version matches the MicroPython version in that firmware.
python -m pip install mpy-cross
python -B .scripts/build.py Copy the generated dist/ contents to the Pico root with Thonny or mpremote. The build leaves boot files as source and compiles imported modules to .mpy, which means less work at import time.
Back up config.json before updating, since it holds your saved preferences and WiFi credentials. Old .py files take precedence over matching compiled modules, so a forgotten development file can make a perfectly good update look broken.
Keeping it inside the memory budget
hardware.py keeps hardware access in one place. The shell handles app loading and navigation, and crt.py has the shared drawing helpers. Apps only load when they're needed and get released when they exit. That way I can keep adding features without holding all of them in memory at once.
There are still tradeoffs. The network helper uses plain HTTP for small responses because running TLS alongside the display buffer takes too much memory. Sensor readings and radio features also depend on the board and firmware. I'd rather be upfront about those limits than have the screen claim more than the hardware can do.
If you want to try it, start with the repository's build guide and whichever display you have. If you're coming from an older setup, the 1.x reference has the old details, but use the current instructions for installing.