PET-PC
A Commodore PET–style desk terminal on an ESP32-C6. A clock, the weather, your
Home Assistant lights — and two keys that do whatever you tell them to. It boots
into BASIC, loads the weather from tape, and fills the screen with 10 PRINT
when you leave it alone.
Project page · Quick start · Wiring · 3D-printable case on Printables
- Three keys, one OLED. A 128×64 screen and three mechanical key switches on a
Waveshare ESP32-C6-Zero. No hub, no cloud, no YAML — the box fetches everything
itself and is configured from its own web page.
- Seven screens. PETSCII block clock, a classic clock, weather, a BASIC
READY. prompt, a live program LISTing, Home Assistant, and system status.
- Keys you configure. Each outer key has a press and a hold action: call a
webhook, jump to a screen, toggle a Home Assistant light, run a scene, cycle a
selector.
- Home Assistant, optional. Show sensors and switch lights from the keys,
over HA's REST API with a long-lived token — nothing to install on the HA side.
- Retro all the way down. BASIC boot banner, a
PRESS PLAY ON TAPE sequence
around every weather fetch, CRT wipes and a power-off collapse on the OLED,
and a web page with scanlines and phosphor glow.
- Kind to the OLED. Modest brightness, a night schedule that switches the
panel off, burn-in pixel shift, and a screensaver.
Screens
The centre key steps through them; pick which ones on the web page.
Every weather refresh is loaded from "tape" — then RUN prints the reading:
Screen changes get a scan-line wipe or a vertical-hold roll, and at night the
picture collapses to a line and a dot like a CRT switching off. All of it can be
turned off.
The web page
Everything is set from http://pet-pc.local/ — no app, no reflashing. The page
is a single file in the firmware, so it also works over the device's own hotspot.
- Live — the OLED mirrored in real time, and three virtual keys (click =
press, keep it down = hold).
- Keys — press and hold actions for the outer keys, with Try it buttons.
- Screens, Display — rotation, start screen, screensaver, retro extras,
brightness, night hours, two-colour panel.
- Home Assistant — URL, token, Test connection, and the HOME entities with
their live values.
- Weather & time — location (or use this browser's location), a time-zone
list, the time server.
- Network, System — WiFi, device name, status, settings download, restart.
Every setting explains itself. Save stays disabled until the settings have
loaded, only what you changed is sent (and marked until saved), bad values are
flagged before sending — ?SYNTAX ERROR — and changes that would drop the
connection ask first. Green, amber or white phosphor; CRT effects can be
switched off.
Hardware
| Part | Notes |
|---|
| Waveshare ESP32-C6-Zero | ESP32-C6, 4 MB flash, native USB-C for flashing and serial |
| SSD1306 128×64 I²C OLED (0.96″) | the common 4-pin module, address 0x3C, powered from 3.3 V. Yellow/blue two-colour panels work too: turn on Two-colour panel under Display |
| 3 × MX-style key switches | clicky or tactile suit it best — the switch is the only click there is |
| A PET-style case | the 3D-printable case on Printables (print-ready 3MF + build guide), or any box with three 14 × 14 mm switch cutouts |
No resistors, diodes or matrix: each switch goes from a GPIO to ground and the
firmware turns on the internal pull-ups. The OLED lands on four consecutive
header pins, so one straight 4-wire ribbon connects it.
| Signal | Pin |
|---|
| OLED SCL / SDA | GP0 / GP1 (next to GND and 3V3) |
| Left / centre / right key | GP18 / GP19 / GP20 |
Pin map, wiring diagram, the one-GND workaround and assembly tips:
WIRING.md. A different pin is a one-line change in
board_config.h.
Quick start
You need PlatformIO Core 6.2 or newer
(or the VS Code extension) and a USB-C data cable.
git clone https://github.com/Krasnov777/esp32-pet-pc.git
cd esp32-pet-pc/firmware
pio run -t upload # first build downloads the toolchain; then flashes over USB-C
pio device monitor # optional: the boot log, 115200 baud, same cable
If the board does not show up as a serial port: hold BOOT, tap RST,
release BOOT, and upload again.
First boot. With no WiFi configured, PET-PC opens an open hotspot called
PET-PC-XXXX (the name is on the screen).
- Join it, browse to http://192.168.4.1/, open Network, enter your
WiFi (2.4 GHz), Save. PET-PC restarts and joins your network.
- Browse to http://pet-pc.local/ (or the IP on the System screen).
- Weather & time: pick your time zone and press use this browser's
location (or type it). Keys: set what the outer keys do. Done.
If PET-PC cannot join the network — wrong password, or the router still booting
after a power cut — the hotspot comes back, and while nobody is connected to it
PET-PC retries your network every five minutes.
cp src/secrets.h.example src/secrets.h # optionally set WIFI_SSID / WIFI_PASSWORD, then build and upload
secrets.h is git-ignored. Its WiFi values only seed the first boot; after
that, settings live on the device and are edited from the web page.
src/secrets.h is required. The build fails without it, because it holds
the OTA password and the web UI login (WEB_USER / WEB_PASSWORD, HTTP Basic
auth on every page and /api/* route). Copy src/secrets.h.example and set
long random values.
Updating over WiFi
pio run -e ota -t upload --upload-port <device-ip>
The OTA password is OTA_PASSWORD from secrets.h; platformio.ini reads it
from the environment: export PETPC_OTA_PASSWORD=... before uploading. (Older
builds used the public default pet-pc. Change it if a unit still has that.)
Pass the IP rather than pet-pc.local: espota's .local lookup hangs
on macOS. An upload takes about a minute; settings survive every update.
Keys
| Key | Press | Hold (0.8 s) |
|---|
| Left | your choice | your choice (default: same as press) |
| Centre | next screen · on BASIC: run the next command · on HOME: pick the next switch | refresh the weather · on BASIC: leave · on HOME: toggle the picked switch |
| Right | your choice | your choice (default: same as press) |
The centre key is fixed, so the box always navigates the same way. The outer
keys can:
| Action | For example |
|---|
| Send an HTTP request (POST or GET, http or https) | an ESPHome button (http://desk.local/button/desk_up/press), a Node-RED / n8n flow, an HA webhook |
| Show a screen | hold left → HOME |
| Next / previous screen | the out-of-the-box setting |
| Refresh the weather | |
| Toggle a Home Assistant entity | light.desk_lamp |
| Run a Home Assistant action | an automation, scene or script, light.turn_off, input_select.select_next (cycle through modes): see below |
Running a Home Assistant action. The key sends HA two things: the
Action, which is what to do, and the optional Entity, which is what to
do it to. HA lists automations and scenes as entities, so their IDs go in
Entity, under the action that runs them:
| To run | Action | Entity |
|---|
| an automation | automation.trigger | automation.night_lights |
| a scene | scene.turn_on | scene.movie_time |
| a script | script.night_mode (or script.turn_on) | (empty, or script.night_mode) |
| a built-in action | light.turn_off, cover.open_cover… | light.desk_lamp |
| cycle a selector | input_select.select_next | input_select.house_mode |
automation.night_lights in the Action box does nothing: HA has no action by
that name and answers with an error, so the key shows "failed". The Keys tab
flags it before you save. Only entity_id is sent, no other data, so for a
brightness, colour or anything else with options, wrap it in a script and run
the script.
Anything that goes to the network shows "sending…" on the screen, then the
result.
Home Assistant
- In Home Assistant: your profile → Security → Long-lived access tokens
→ Create token.
- On PET-PC's page, Home Assistant tab: your HA URL with the port (e.g.
http://homeassistant.local:8123; https:// works too), the token, and up to
six entities. Save, then Test connection.
- HOME joins the centre key's screens.
Each entity is a Value — shown as HA reports it, with its unit (21.4C,
612 ppm) — or a Switch — ON/OFF, picked with a centre press and
toggled with a centre hold. The type is suggested from the entity's domain
(light., switch., fan., input_boolean., automation., cover. are
switches); change it to watch a light without being able to toggle it.
PET-PC reads one entity at a time, so each request is small; a full round takes
30 s by default, about one entity a second while HOME is on screen. If HA is
down or refuses the token, the screen says so and PET-PC backs off for a minute.
The token is write-only: the page never shows it again, a blank field keeps
it, and changing the URL clears it — so it is never sent to a server it was not
entered for.
API
The page uses a small JSON API, open to your own scripts too. Every route needs
the web login (HTTP Basic, WEB_USER / WEB_PASSWORD from secrets.h):
| Method | Path | |
|---|
GET | /api/state | settings and live status (the WiFi password and HA token are never included) |
POST | /api/settings | a JSON patch in the same shape — only the keys you send change |
POST | /api/key?key=left|center|right&hold=0|1 | press or hold a key |
POST | /api/mode | next screen |
POST | /api/ha/test | test the saved Home Assistant connection |
POST | /api/reboot | restart |
GET | /shot.bmp | the current screen as a 1-bit BMP |
curl -u admin:<pw> -X POST 'http://pet-pc.local/api/key?key=right' # press the right key
curl -u admin:<pw> -X POST -H 'Content-Type: application/json' \
-d '{"display":{"contrast_day":90}}' http://pet-pc.local/api/settings
Good to know
- The web page and API need a login (HTTP Basic, set in
secrets.h). Requests must be addressed to the device itself (its IP or hostname), and cross-site POSTs are refused. Basic
auth travels in clear text over plain HTTP, so it keeps out casual LAN
clients, not someone sniffing your network. The WiFi password and HA token
are never sent back by the API.
- OTA needs
OTA_PASSWORD from secrets.h; there is no default.
- Give it a non-admin Home Assistant token. The device only reads states
and calls the actions you configure.
- An HTTP action waits up to 4 s for a target that does not answer; the
screen says "sending…" meanwhile.
- OLED care. OLEDs wear with brightness and time. The defaults — day
brightness 70 of 255, panel off from 23:00 to 07:00, a 2 px shift every two
minutes, the screensaver — are there to make the panel last years.
Documentation
- WIRING.md — pin map, wiring diagram, assembly.
- ARCHITECTURE.md — how the firmware is put together: the
loop, rendering, settings and migrations, the web page, how to add a screen.
- CHANGELOG.md — what changed in each version.
- docs/esphome-notes.md — the ESPHome config this
started as, and the traps it had.
Built with
PlatformIO and the
pioarduino ESP32 platform
(Arduino core 3.x), U8g2 for the display,
ArduinoJson, weather from
Open-Meteo (free, no key), and the
PxPlus IBM CGA font by VileR standing
in for the PET's character ROM. The renders use the Cherry MX switch model from
keyswitch-kicad-library
(MIT, © keyswitch-kicad-library contributors).
License
MIT.
PET-PC is an unofficial, independent project. It is not affiliated with, endorsed by or sponsored by Commodore; "PET" is used only to describe the design inspiration, and all trademarks belong to their owners.
