pico6502 User Manual

The pico6502 is a drop-in replacement for a 6502 CPU in any DIP-40 socketed computer. It plugs directly into the 6502 socket of your vintage computer and — without any modifications to the host board — provides expanded memory, virtual peripherals, and a browser-based management interface over WiFi.

The pico6502 shares its fundamental hardware design with the picoZ80 — the same RP2350B dual-core microcontroller, 8MB PSRAM, 16MB Flash, ESP32 co-processor and SD card slot. The key difference is the bus interface: the pico6502 targets the 6502's dual-phase PHI1/PHI2 clocking scheme and its all memory-mapped peripheral model. Unlike the Z80, the 6502 has no separate I/O address space — all peripherals (VIA, ACIA, etc.) are accessed through the memory map using FUNC blocks.

This manual covers the physical board, initial setup, connecting to a host machine, and using the web interface. For architecture details, configuration reference, and firmware internals see the pico6502 Technical Guide. For the project overview see the pico6502 project page.

Board Overview

The pico6502 PCB (current revision v2.3a, the board proven in the BBC Model B and Apple I, pictured below from both sides) is designed to fit within the footprint of a standard 40-pin DIP package, measuring 52mm × 19mm. All 40 DIP pins emerge from the underside of the board, exactly matching the pin-out of a real 6502, so it drops straight into any 6502 socket without bending or adapting.

The top surface carries all active components. The board height above the socket is within the envelope of a standard IC with a DIP-40 socket fitted underneath, making it compatible with the clearances of most vintage 6502 computers.

pico6502 v2.3a — component side (top): RP2350B, ESP32-S3, USB-C, debug header

pico6502 v2.3a — underside: SD card slot, bus buffers, flash, PSRAM and the DIP-40 pins

Connectors and Indicators

The pico6502 board exposes the following connectors and indicators:

Item	Description
6-pin Debug Header	Located on the board edge. Provides SWD (Serial Wire Debug) access to the RP2350, plus SWO and Reset lines. See Debug Header Pinout below.
USB Port	USB connectivity for firmware flashing via USB mass-storage (BOOTSEL mode) and for USB-UART bridging to the ESP32.
SD Card Slot	Full-size SD card slot managed by the ESP32. Holds `config.json`, ROM images, and any filing system assets.

Debug Header Pinout

The 6-pin header is the primary hardware interface for initial programming and source-level debugging. The pins are numbered from Pin 1 at the end closest to the board edge marker.

Pin	Signal	Function
1	`SWCLK`	Serial Wire Debug clock (ARM SWD)
2	`SWDIO`	Serial Wire Debug data (ARM SWD)
3	`SWO`	Serial Wire Output — optional trace output from RP2350
4	`RESET`	Active-low reset for the RP2350. Pull low to reset.
5	`GND`	Ground reference
6	`3V3`	3.3V supply output (do not use as an input)

NB. Pins 1, 2, and 5 are used for SWD debugging (SWCLK, SWDIO, GND). For initial RP2350 flashing, use BOOTSEL mode by asserting the BOOTSEL signal during power-on — refer to Step 1 in Getting Started. Pin 3 (SWO) is optional and used only when trace output is enabled in the firmware build.

Getting Started

Follow these steps in order the first time you set up a pico6502 board:

Flash the RP2350 bootloader via USB mass-storage mode (BOOTSEL).

Flash the ESP32 firmware via esptool.

Prepare an SD card with config.json and any required ROM images.

Install the pico6502 in the 6502 socket of your host computer.

Power on and wait for the pico6502 to start its WiFi access point.

Connect to the web interface and complete initial configuration.

Step 1 — Flash the RP2350 Bootloader

The RP2350 does not have physical BOOTSEL or Reset buttons on the pico6502 board — these signals are accessible programmatically or via the debug header. To enter the USB mass-storage bootloader:

Do not insert the pico6502 into a host computer yet — connect it to a PC by USB cable only.

Hold the BOOTSEL signal low (refer to your board's schematic for the test point location).

Apply power to the USB port — the RP2350 starts booting.

Release BOOTSEL promptly after the board enumerates as a USB mass-storage device.

The PC will mount a drive labelled RPI-RP2 (or similar).

Copy Bootloader_<version>.uf2 to the mounted drive. The RP2350 self-flashes and reboots automatically.

After flashing the bootloader, all subsequent RP2350 firmware updates can be performed wirelessly via the web OTA page — you do not need to access the BOOTSEL signal again for normal firmware updates.

Step 2 — Flash the ESP32 Firmware

The ESP32 firmware is flashed using esptool. The procedure is identical to the picoZ80 — see the picoZ80 User Manual — Step 2 for full details. The ESP32 firmware binary is the same for both boards.

Set up the Python environment (once only):

python3 -m venv ./venv/
source ./venv/bin/activate
cd $HOME/esptool

Then flash all four ESP32 firmware components. Adjust PORT to the device node assigned by your OS:

PORT=/dev/ttyUSB0       # Linux — adjust as required
# PORT=/dev/tty.usbmodem141403  # macOS

BINPATH=/path/to/esp32/build

python3 ./esptool.py \
  -p ${PORT} -b 115200 \
  --before default_reset --after hard_reset \
  --chip esp32s3 \
  write_flash \
  --flash_mode dio --flash_size 4MB --flash_freq 80m \
  0x0     ${BINPATH}/bootloader.bin \
  0x8000  ${BINPATH}/partition-table.bin \
  0x9000  ${BINPATH}/ota_data_initial.bin \
  0x10000 ${BINPATH}/sd_card.bin

NB. All subsequent ESP32 firmware updates can be performed via the OTA web page (ota-esp32.htm) once the initial flash is complete.

Step 3 — Prepare the SD Card

The SD card holds the configuration file, ROM images, and web interface assets.

Format requirements:

FAT32 file system.

Any capacity supported by FAT32 (up to 32GB is recommended for reliable formatting).

Minimum required files:

config.json in the SD card root — the main configuration file. See Basic Configuration for a minimal 6502 example.

webfs/ directory — the ESP32 web interface assets. Copy the contents of the webfs/ directory from the project repository to the SD card root.

Optional directories:

Directory	Contents
`ROM/`	ROM images referenced by `config.json` (e.g. BBC Model B OS, BASIC)
`DSK/`	Disk images for future drive emulation drivers

The SD card can be managed through the web File Manager once the pico6502 is running — you can upload ROM images, edit config.json, and create directories from the browser without physically removing the card.

Step 4 — Install in the Host Computer

Safety first: Always power off and unplug the host computer before installing or removing the pico6502. The board operates at 3.3V internally; the DIP-40 pins connect to the 5V host bus through appropriate interface circuitry, but the board must never be inserted or removed while powered.

Installation procedure:

Power off the host computer and discharge any static.

Remove the existing 6502 CPU chip from its DIP-40 socket. A chip extractor tool is recommended to avoid bending pins.

Insert the SD card into the pico6502 SD card slot.

Align the pico6502 with the 6502 socket, ensuring that Pin 1 of the pico6502 (marked with a dot or notch) aligns with Pin 1 of the socket.

Press the pico6502 gently and evenly into the socket. Ensure all 40 pins are seated. Do not force — if resistance is felt, remove and check pin alignment.

Power on the host computer.

BBC Model B: the pico6502 replaces the 6502 in IC1. Leave every other chip in place — the Model B's RAM, ROMs, VIAs and the Tube all stay in use. A PiCoPro or other Tube co-processor may remain fitted. Flash the BBC6502 firmware (the Base6502 model has no BBC driver) and select the BBC-B persona. Apple I / replica: flash the Apple6502 firmware, select the Apple-I persona and choose the AppleI driver in the Configuration GUI (see Using the Apple I Persona). Any other 6502 machine or your own board: use the Open6502 firmware with the Open6502 persona (or the Base6502 persona for a plain passthrough), and fit any chips the board needs as virtual devices.

On first power-on after a fresh firmware install, the ESP32 will start in Access Point mode. The supplied 6502 personas configure the access point as SSID p6502, password p6502p6502, address 192.168.4.4. Connect to this network to access the web interface and complete initial WiFi configuration.

NB. The pico6502 draws power from the 5V supply on the 6502 socket VCC pin. The on-board buck converter delivers 3.3V to all board components. Ensure your host computer's 5V supply can deliver at least 500mA — the pico6502 can draw up to 400mA under peak load (RP2350 at 300MHz with WiFi active).

Step 5 — Power On

Power on the host computer. The pico6502 will boot from the RP2350 bootloader, load the application firmware from Flash, read the configuration from its flash store (a freshly flashed partition with no stored configuration starts with safe defaults — apply a persona from the web interface to populate it), hold the host in reset until its services are up, initialise the memory map, and begin servicing 6502 bus cycles. If a boot hangs at a high core clock the next boot falls back to 150 MHz safe mode so the web interface stays reachable.

The ESP32 boots in parallel and starts the WiFi subsystem. If no saved network credentials are found, the ESP32 will enter Access Point mode automatically.

Step 6 — Connect to the Web Interface

On first boot, connect to the p6502 WiFi access point (password p6502p6502) and navigate to http://192.168.4.4. From the WiFi Manager page, enter your home network credentials. After saving and rebooting the ESP32, the pico6502 will join your network and be accessible at the configured IP address (default http://192.168.1.192).

WiFi Setup

The pico6502 WiFi setup procedure is identical to the picoZ80. The ESP32 co-processor provides WiFi connectivity. On first boot (or when no WiFi credentials have been saved) the ESP32 starts in Access Point (AP) mode.

Connecting in Access Point Mode

On your phone, tablet, or laptop, open the WiFi settings and look for a network named p6502 (or as configured in the esp32.wifi.ssid field of your config.json when in AP mode).

Connect to the p6502 network. The AP password set by the supplied 6502 personas is p6502p6502.

Open a browser and navigate to http://192.168.4.4 — the AP mode address configured by the supplied 6502 personas. The pico6502 web interface will appear.

Navigate to the WiFi Manager page to enter your home network SSID and password.

Click Save & Connect. The ESP32 will reboot and connect to your home network as a client.

Client (Station) Mode

Once configured for client mode, the ESP32 joins your home WiFi network and is reachable at the IP address shown on the Dashboard page. If you set a fixed IP in config.json (recommended for ease of access), navigate directly to:

http://192.168.1.192

Substitute the IP address you configured. If you are using DHCP, find the assigned address from your router's DHCP client list.

The web interface runs entirely in your browser. No additional software is required. The pico6502 web server runs on port 80.

Web Interface

The pico6502 web interface is identical to the picoZ80's — an eight-page Bootstrap 4 application served by the ESP32. All pages are accessible from the navigation bar at the top of each page. The web assets are stored in the webfs/ directory on the SD card. The interface detects the running firmware's CPU: on a pico6502 the Quick Disk menu is hidden, the CMT menu drives the virtual cassette decks (the BBC's UEF deck and the Apple I's ACI), the Floppy menu offers Side A and Side B for each BBC drive, and the Configuration GUI page (configgui.htm) presents the 6502 options — cputype (6502 / 6512 / 65C02 / 65C12), dbeoverride, per-partition core voltage, clock and PSRAM clock, pad drive strength, the memory-map editor, the drivers section with its Bus Engine Tuning panel, the BBC-B machine options and sideways-socket table, the CMT-UEF tape carousel, the BBC-FDC floppy slots, the BBC-MMC card and the BBC-NET Econet settings. The Dashboard's Floppy menu changes the virtual floppy images live.

Dashboard (index.htm)

The Dashboard is the home page of the web interface. It displays real-time system information and provides a quick overview of the pico6502 state.

Information shown on the Dashboard includes:

Firmware Version — the currently running RP2350 firmware version and build date.

ESP32 Version — the ESP32 co-processor firmware version.

Active Partition — which of the two firmware slots (1 or 2) is currently active.

Active Persona — the machine personality currently loaded.

RP2350 Clock — current CPU frequency in MHz.

PSRAM Clock — current PSRAM SPI clock frequency.

WiFi Status — mode (AP or client), SSID, and assigned IP address.

SD Card — whether an SD card is present and the filesystem mount status.

Uptime — time since last reboot.

The Dashboard also provides buttons to reboot the RP2350 and to trigger a configuration reload from the SD card without a full reboot.

Config Editor (config.htm)

The Config Editor page provides an in-browser editor for the config.json file stored on the SD card. The editor features syntax highlighting and basic JSON validation.

To edit the configuration:

Navigate to the Config Editor page.

The current config.json is loaded into the editor automatically.

Make your changes. The editor will highlight syntax errors in red.

Click Save to write the updated file back to the SD card.

Click Apply to apply the new configuration. As on the picoZ80, applying reads config.json from the card, minifies it and stores it in the RP2350's flash together with the core clock and voltage, then reboots; subsequent boots run from the flash copy. The Configuration GUI page offers the same file as a structured form, including the 6502 bus-engine and BBC options — see below.

Changes to the memory map and ROM images take effect on the next RP2350 reset. Note that the pico6502 has no separate I/O map — all peripheral bindings are in the memory array as FUNC blocks. Changes to WiFi settings in the esp32.wifi block take effect on the next ESP32 reboot.

NB. The Config Editor operates directly on the SD card file. It is good practice to keep a backup copy of a working config.json on your PC before making significant changes.

File Manager (filemanager.htm)

The File Manager provides a browser-based view of the SD card contents. You can navigate directories, upload new files (ROM images, disk images), download existing files to your PC, create new directories, and delete files and directories.

Common tasks in the File Manager:

Upload a ROM image — navigate to the ROM/ directory and use the Upload button to transfer the ROM file from your PC.

Backup config.json — click the download icon next to config.json to save a copy to your PC.

Update web assets — navigate to webfs/ and upload replacement HTML/CSS/JS files to update the web interface.

File operations are performed directly on the SD card via the ESP32. Large file uploads may take a few seconds depending on file size and WiFi signal quality.

Persona Selection (personality.htm)

The Persona Selection page allows you to choose which machine personality (persona) the pico6502 presents to the host computer, independently for each firmware partition. Different personas load different memory maps and ROM images from the configuration. The page is CPU-aware — when pico6502 firmware is running it shows only the 6502 personas.

Four 6502 machines are supplied, paired one per partition in every combination (sixteen persona files). Each needs the firmware that carries its driver:

Base6502 — "Vanilla 6502" — a plain 6502 in the socket with nothing virtualised; every bus cycle passes through to the host machine. This is the persona to bring a new board up with. Runs the RP2350 at 150MHz on any 6502 firmware.

Open6502 — "Open / experimenter board" — a board of your own design or a machine without a driver. Describe its memory map and ROMs in the persona and add the peripherals it lacks as virtual devices. Use the Open6502 firmware, which allows the most chips (twelve).

Apple-I — "Apple I / replica" — the Apple I, Replica 1, PE6502 or RC6502 host; the Woz monitor and BASIC run. With the AppleI driver on the Apple6502 firmware the bus engine knows the machine's map, ROMs can be supplied virtually, and the keyboard and display can be a USB serial terminal — see Using the Apple I Persona.

BBC-B — "BBC Model B" — the Model B on its own driver (BBC6502 firmware). Physical passthrough with the machine's knowledge built in, running the RP2350 at 340MHz, plus the virtual sideways sockets, OS socket, Model A RAM, Master mode, persistence, the UEF tape deck, a virtual floppy controller (Intel 8271 or WD1770, for DFS, DDFS and ADFS) with two drives, a virtual MMFS card, and a virtual Econet module that reaches a file server on your LAN over AUN — all described in Using the BBC Model B Persona.

The Open6502 driver (Base6502 and Open6502 personas) loads any configured ROM images into their bank:addr slices, marks bank-0 ROM blocks read-only, and otherwise leaves the address space exactly as the persona's memory array defines it. Selecting a persona writes it to the partition's flash configuration store and reboots the RP2350.

Firmware Updates (OTA)

Firmware for both the RP2350 and the ESP32 can be updated over-the-air (OTA) from the web interface. The procedure is identical to the picoZ80 — see the picoZ80 User Manual — Firmware Updates for full details.

The only difference is the RP2350 firmware binary filename: for the pico6502, the application binary is named Base6502_<version>.bin rather than BaseZ80_<version>.bin.

WiFi Manager (wifimanager.htm)

The WiFi Manager page configures the ESP32 network settings. Changes made here are persisted in the ESP32 NVS (non-volatile storage) and take effect on the next reboot.

Available settings:

WiFi Mode — Access Point (the pico6502 creates its own network) or Client (the pico6502 joins an existing network).

SSID — the network name to create (AP mode) or join (client mode).

Password — the WiFi passphrase.

IP Address / Netmask / Gateway — fixed IP settings for client mode (recommended for consistent access).

DHCP — enable to obtain an address from your router automatically; disable to use the fixed IP settings above.

After saving, click Reboot ESP32 to apply the new settings. The ESP32 will restart and connect using the new configuration. If client mode connection fails (wrong SSID or password), the ESP32 will fall back to Access Point mode after a timeout, allowing you to reconnect and correct the settings.

Basic Configuration

All pico6502 behaviour is controlled by config.json on the SD card. The following is a minimal working configuration for a generic 6502 host with RAM, ROM, and a memory-mapped VIA peripheral. Refer to the Technical Guide — Configuration Reference for a full description of all options.

Key differences from picoZ80: the CPU key is "6502" (not "z80") — like "z80" it is an array indexed by flash partition — and there is no "io" array: all peripherals including the VIA, ACIA, etc. are mapped using FUNC blocks in the "memory" array. Each partition entry also carries "cputype" ("6502" or "6512" — the same processor above the pins, differing only in whether the chip generates its own PHI1/PHI2 clock phases or takes them from the host) and "dbeoverride" (the buffer-enable override of the v2.3 buffered interface; the supplied personas set true), and may carry a "core" object with its own cpufreq / psramfreq / voltage — the Configuration GUI stores a partition's clock and voltage there. cputype also accepts "65C02" and "65C12" for the CMOS instruction set. The configuration is stored in flash when applied and read from there at boot.

{
  "esp32": {
    "core": {
      "device": "6502",
      "mode":   0
    },
    "wifi": {
      "override":  1,
      "wifimode":  "client",
      "ssid":      "YourNetwork",
      "password":  "YourPassword",
      "ip":        "192.168.1.192",
      "netmask":   "255.255.255.0",
      "gateway":   "192.168.1.1",
      "dhcp":      0,
      "webfs":     "webfs",
      "persist":   0
    }
  },
  "rp2350": {
    "core": {
      "cpufreq":   300000000,
      "psramfreq": 133000000,
      "voltage":   1.10
    },
    "6502": [
      {
        "cputype":     "6502",
        "dbeoverride": true,
        "memory": [
          {
            "enable":   1,
            "addr":     "0x0000",
            "size":     "0x8000",
            "type":     "RAM",
            "bank":     0,
            "tcycwait": 0,
            "tcycsync": 0,
            "task":     "",
            "file":     "",
            "fileofs":  0
          },
          {
            "enable":   1,
            "addr":     "0x8000",
            "size":     "0x1000",
            "type":     "FUNC",
            "bank":     0,
            "tcycwait": 0,
            "tcycsync": 0,
            "task":     "VIA",
            "file":     "",
            "fileofs":  0
          },
          {
            "enable":   1,
            "addr":     "0xC000",
            "size":     "0x4000",
            "type":     "ROM",
            "bank":     1,
            "tcycwait": 0,
            "tcycsync": 0,
            "task":     "",
            "file":     "/ROM/basic.rom",
            "fileofs":  0
          },
          {
            "enable":   1,
            "addr":     "0xE000",
            "size":     "0x2000",
            "type":     "ROM",
            "bank":     2,
            "tcycwait": 0,
            "tcycsync": 0,
            "task":     "",
            "file":     "/ROM/os.rom",
            "fileofs":  0
          }
        ],
        "drivers": []
      }
    ]
  }
}

This example maps:

0x0000 – 0x7FFF — 32KB RAM in PSRAM bank 0 (zero page, stack, and general RAM).

0x8000 – 0x8FFF — 4KB FUNC block bound to the VIA virtual device handler — a memory-mapped 6522 VIA peripheral emulation.

0xC000 – 0xFFFF — 8KB BASIC ROM loaded from /ROM/basic.rom on the SD card into PSRAM bank 1.

0xE000 – 0xFFFF — 8KB OS ROM loaded from /ROM/os.rom on the SD card into PSRAM bank 2. The 6502 reset vector at 0xFFFC/0xFFFD must be within this ROM region.

Note that there is no "io" array — the 6502 has no separate I/O address space. All peripheral emulation uses FUNC blocks within the memory map.

Using the Apple I Persona

The Apple6502 firmware adds the AppleI driver for the Apple I and its replicas (Replica 1, PE6502, RC6502 and the like). Flash it and select the Apple-I persona, which already chooses the Apple I (Apple-1) driver with the physical terminal on USB port 2; change the terminal mode in the Configuration GUI. The driver tells the bus engine where the machine's I/O lives ($C000–$DFFF: the ACI cassette card and the keyboard/display PIA) and that the CPU is the only master of its RAM ($0000–$7FFF), so it can read ahead safely. On an original 4K Apple I, set the shadow-write window in Bus Engine Tuning to end at 0x1000.

Terminal. The driver's Terminal selector decides where the keyboard and display are:

Physical (default) — the machine's own keyboard and video terminal; nothing virtual.

Virtual (USB serial) — a virtual 6821 PIA answers at $D010–$D013 and the keyboard and display are a USB serial port on your PC. Use this on a bare board with no keyboard or video section: connect a terminal program to the chosen port and the Woz monitor's \ prompt appears.

Mirror (both) — the real keyboard and display keep working, and a USB serial terminal is joined to both. Characters you type on the PC are served ahead of the physical keyboard, and everything displayed goes to both screens, still paced by the real display. This is the easy way to paste a program listing into the Woz monitor or BASIC.

USB port picks the serial port the terminal uses: Serial A (2, default), Serial B (3) or the printer port (4); avoid one a virtual device already uses. The terminal behaves like an Apple I: letters are folded to upper case, Return is a carriage return, and Backspace or Delete become _, the Apple I's rubout.

ROMs. ROM images (Woz monitor, Integer BASIC, Krusader, the ACI firmware) can be listed in the driver's ROM rows and are served as virtual ROM. A row with only a file and no load address places the image at the top of memory, ending at $FFFF — a 256-byte Woz monitor lands at $FF00. A physical ACI cassette card works as it is, because its addresses pass through to the bus.

Cassette — the Virtual ACI

The Apple I loaded and saved programs on cassette through the ACI (Apple Cassette Interface) card. The pico6502 provides that card virtually, with the tapes held as files on the SD card. In the Configuration GUI, add the Cassette (ACI) interface to the Apple I driver and give it:

ROM — the ACI firmware, a 256-byte image such as roms/apple1/wozaci.rom. It runs at $C100. Leave the row disabled to use a real ACI card's own PROM.

Tape 1–6 — up to six tapes. A .wav or .aif file is a cassette recording: any sample rate, mono or stereo, 8 or 16-bit, even a noisy one digitised from an old tape. Any other file is loaded as raw bytes. Keep them in cmt/apple1/.

Leader — the minimum leader tone in seconds (default 1). There is no need to change it.

Apply and reboot. The Dashboard's CMT menu then lists the tapes in the carousel. Pick one to put it in the deck, use Add Tape to add a file from the SD card, or switch the deck between Virtual (the SD-card tapes) and Real (a physical ACI card's cassette). Then use the cassette exactly as on an Apple I. Enter the ACI monitor with C100R, then type the address range and R to read or W to write. Each R plays the next record on the tape, so an Integer BASIC program, which is two records, loads with 004A.00FFR 0300.0FFFR. Tapes load correctly at any speed, including VIRTUAL Max. When a W finishes, the recording is saved to the SD card as cmt/apple1/ACI_nnn.wav, which plays into a real Apple I, and as ACI_nnn.bin. It is also placed in the deck, so R reads it straight back. From the debug shell, aci shows the deck (tape, record, playback phase), aci rew rewinds, aci next moves to the next tape and aci sel <1-6> picks a tape. Don't enable the virtual cassette while a real ACI card's cassette is in use: the virtual card answers the card's addresses.

Virtual Devices

Every pico6502 firmware can fit virtual chips to the host machine — the same catalogue the picoZ80 offers, decoded in memory because the 6502 has no I/O space. Use them to give a bare board a serial port, a timer, a real-time clock, a printer port or a floppy controller without building any hardware, or to add a peripheral the machine never had. Chips are added per partition in the Configuration GUI's Devices section: press Add Device, choose the chip, and give it a memory address clear of the machine's RAM and ROM. Its interrupt is wired to the 6502's /IRQ automatically; the Connections section can rewire it (to cpu.NMI, for example) or join chips to each other. Press Save Configuration; the machine restarts a few seconds later to build the new chips.

Device	What it is	6502 notes
`MC6850`	Serial port (68B50 ACIA)	Bytes travel over a USB serial port on the host PC.
`I8251`	Serial port (8251 USART)	Asynchronous mode over a USB serial port.
`Z80DART`	Dual serial port (Z80 DART)	Two channels over USB serial; the interrupt joins `cpu.IRQ` (no vectored mode on a 6502).
`Z80CTC`	Counter / timer (CTC)	Periodic interrupts and baud rates; interrupt joins `cpu.IRQ`.
`Z80PIO`	Parallel I/O (PIO)	Two 8-bit handshaked ports; interrupt joins `cpu.IRQ`.
`PIT8253`	Interval timer (8253 / 8254)	Three counters, six modes.
`PPI8255`	Parallel interface (8255)	Three 8-bit ports, bit set/reset on port C.
`MSM5832`	Real-time clock	Takes its time from the ESP32 once the network has set it.
`Centronics`	Printer port	Output appears on a dedicated USB serial channel.
`Latch`	Latch / port	A write drives eight wires, a read samples eight wires: banking and control glue.
`SignalPort`	Signal port	Maps eight netlist wires onto one address for test and bridging.
`MC6854`	Econet (68B54 ADLC over AUN/IP)	The Econet engine in device mode; one per board, not alongside the BBC persona’s `BBC-NET` interface.
`WD1770`	Floppy controller (WD1770)	DFS/ADFS images from the SD card; drive, side, density and reset are pins. One per board.
`I8271`	Floppy controller (Intel 8271)	DFS images from the SD card. One per board.

How many chips fit depends on the firmware:

Firmware	Device tier	Chips	Serial devices	Printer ports
`Open6502`	open-6502	12	6	4
`Base6502`	full-6502	8	4	2
`Apple6502`, `BBC6502`	small	4	1	1

Serial devices appear on the PC as USB serial ports (Serial A and B, ports 2 and 3) and the printer port's output on port 4; the Apple I virtual terminal uses one of the same ports, so give each its own. The debug shell's dev lists the fitted chips and can trace their register accesses, ser shows a serial device and can send or receive text, rtc shows the clock and prn the printer buffer. The step-by-step guide to the Devices and Connections editors, including a worked example and the things to watch for when saving, is in the picoZ80 User Manual; it applies to the pico6502 unchanged, except that addresses are memory addresses and the Z80 DMA and WD1773 are not offered.

Using the BBC Model B Persona

The BBC-B persona is a physical passthrough: your Model B keeps its own RAM, ROMs, VIAs, video and disc hardware, and the pico6502 simply is the 6502 — but one that knows the machine's memory map, which is what lets it run fast, and one that can add hardware the machine does not have. Everything below is set from the Configuration GUI page (the driver panel for the BBC-B driver) or by editing the driver object in config.json.

Clock, Voltage and Speed

The persona ships at 340 MHz / 1.20 V, the proven Model B clock. Voltage headroom is per board: if your unit fails to boot or shows RAM errors at a given clock, raise the core voltage before suspecting anything else (one unit needed ~1.35 V for 330 MHz; 1.30 V hung). A boot that hangs falls back to 150 MHz safe mode on the next attempt so you can always reach the web interface. With the BBC-B driver in its default PHYSICAL mode the Model B runs at 97% of a real 2 MHz 6502 (Elite, steady; Galaxians 97–98%), with every cycle on the real bus. With the vanilla driver on the same machine it runs noticeably more slowly. The bus the Model B sees is byte-identical in both cases — the difference is purely how far ahead the pico6502 may read its own instruction stream, which the driver's knowledge of the I/O window and ROM paging makes safe. For more speed, switch the driver to VIRTUAL mode (below), which runs at more than three times the speed of a real BBC.

PHYSICAL and VIRTUAL Mode

The BBC-B driver's Type setting in the Configuration GUI chooses where the Model B's RAM lives:

Mode	Where the CPU’s RAM lives	Speed	Use it for
`PHYSICAL` (default)	On the BBC, every cycle on the real bus	97% of a real 2 MHz 6502 (Elite, steady; Galaxians 97–98%)	Maximum fidelity: the machine sees exactly what a 6502 would do.
`VIRTUAL`	Inside the pico6502; only screen memory is written through to the BBC	Paced to a real 2 MHz BBC, or more than three times its speed unpaced (304–344% on average, peaks above 350%)	Speed, or authentic timing with the bus out of the way.

In VIRTUAL mode the pico6502 keeps the machine's 32K of RAM itself and writes only the screen memory through to the BBC, following the screen through MODE changes and scrolling. At power-on it also copies the OS ROM and the sideways ROMs from the machine into virtual sockets, so they run from the pico6502 too. Sideways RAM and empty sockets stay on the machine. Choose the Speed:

Real (default) — the speed of a real BBC, including the slower 1 MHz accesses to the VIAs, the sound chip and the other slow devices, so games, music and keyboard handling behave as on the original.

Max — as fast as the pico6502 can go. The clock, timers and screen refresh still run in real time, so the OS stays correct, but games that are not locked to the screen run too fast to play.

There are no in-between speeds: the RP2350 does not have the headroom to hold a fixed multiple of the BBC's speed steadily, so the choice is authentic or flat out. If a ROM board in the machine pages itself by writing to its own address space, keep it on the machine: untick ROM capture, or give that socket "capture": false. In PHYSICAL mode, Timing locked (default) holds the CPU to the BBC's clock, and free lets it run unpaced. The debug shell's bbc virt reports the mode, the captured ROMs, the screen region being written through and the 1 MHz accesses charged; bbc virt verify compares the BBC's screen memory with the pico6502's copy.

Sideways ROM / RAM Sockets

The Model B has four physical sideways sockets addressed as ROMSEL banks 0–15. The Sideways ROM / RAM Sockets table in the Configuration GUI lets you populate any of the sixteen banks virtually from PSRAM: tick RAM for 16K of writable sideways RAM, or browse the SD card for a 16K ROM image. An enabled virtual socket overrides whatever is physically in that bank — the usual way to add MMFS, a language ROM or a toolkit without opening the machine. Put the image in roms/bbc/ on the card and select it; Offset picks a 16K ROM out of a larger image (a 128K Master MegaROM in the MOS 3.20 layout). The OS socket row virtualises the MOS itself over $C000–$FFFF — the I/O area always passes through to the real hardware. Save chooses where a RAM socket's contents (and the virtual CMOS) are kept: on the SD card (default), in the pico6502's flash, or nowhere.

The UEF Virtual Cassette Deck

Add the CMT-UEF interface to the BBC-B driver and fill its six-slot tape carousel from the SD card (cmt/; plain or gzipped .uef). On the BBC, use the tape exactly as you would a real one: *TAPE, then LOAD "", CHAIN "" or *RUN. The deck plays the tape through a virtual 6850 ACIA at real 1200 or 300 baud, so loading takes as long as it did in 1982 and Searching / Loading messages appear normally. The real motor relay still clicks because the control writes pass through to the machine. SAVE "NAME" records the transmitted stream into a new UEF on the card, named from the file's own block header. From the debug shell, bbc tape sel <n>, bbc tape next and bbc tape rew select and rewind tapes, bbc tape on|off engages the deck and bbc tape trace shows the ACIA traffic; the Dashboard's CMT menu lists the carousel, selects a tape, adds one from the SD card and switches the deck between Virtual and Real (the BBC's own cassette port).

Floppy Drives — the Virtual 8271 or WD1770

Add the BBC-FDC interface to the BBC-B driver and the pico6502 becomes the machine's floppy controller: the filing-system ROM already in the machine (or loaded into a virtual socket) sees a controller with two drives, and disc images on the SD card take the place of real discs. A real controller and real drives may stay fitted — the virtual controller never passes its commands to the bus and takes over the /NMI line, so the physical chip is simply out of the picture while the interface is enabled. Choose the chip to suit the filing system you want to run:

Intel 8271 (default) — the Model B's own controller at $FE80, for Acorn DFS 0.90 / 1.20 and the Watford and Solidisk 8271 DFS ROMs. Single-density DFS discs only.

WD1770 — the double-density controller fitted by the later upgrade boards, which the ADFS and DFS 2.2x / DDFS ROMs need. Select the board the ROM was written for, because each wires its drive-control latch differently: the Acorn 1770 upgrade board (latch $FE80, chip $FE84 — Acorn DFS 2.2x, ADFS 1.3x, Solidisk and Watford DDFS), the Watford Electronics 1770 board (same addresses, its own latch layout — Watford DDFS 1.50), or the Master 128's on-board controller (latch $FE24, chip $FE28 — DFS 2.24/2.45 and ADFS 1.50 from a Master MOS image). "Auto" picks the Master board when Master mode is on and the Acorn board otherwise.

Each drive has two sides, and each side comes from a file:

.ssd — a single-sided image. On its own in the Side A slot it gives a single-sided disc: DFS drive 0 (or 1) works and the other side answers "sector not found", exactly as a real single-sided disc does.

Two .ssd files, one per side — put the second single-sided image in the Side B slot and the two are combined into one double-sided disc: Side A is DFS drive 0, Side B is DFS drive 2 (drives 1 and 3 for the second drive). This is how many archives ship a double-sided disc, as a pair of files such as ACORN3_A.ssd and ACORN3_B.ssd.

.dsd — a double-sided DFS image; both sides come from the one file and the Side B slot is left empty.

ADFS images (WD1770 only) — .adf holds an ADFS S or M disc (one side, 40 or 80 tracks) or an L disc stored side after side (640K); .adl holds an L disc with the sides interleaved. These are ADFS drives :0 and :1. Double-density DFS (DDFS / DDOS) images are the DDS (one side) and DDD (both sides) kinds, with 16 or 18 sectors per track decided by the file size.

MMB disc — mmb/BEEB.MMB:3 picks disc 3 out of an MMB bundle for a side, so an MMB library can be used through DFS as well as through MMFS.

Set the chip, board and images in the Configuration GUI (the interface's four slots are labelled Drive 0 · Side A, Drive 0 · Side B, Drive 1 · Side A and Drive 1 · Side B, each with a kind selector: Auto by extension and size, SSD, DSD, MMB, ADF, ADL, DDS or DDD), or change images while the machine is running from the Dashboard's Floppy menu, which offers the same four entries, the kind selector and Eject. Writes are held in a cache and written back to the image file a moment after the last update, so SAVE, *COPY, *FORMAT and ADFS directory operations work as on a real disc. The interface's speed option selects unthrottled transfers (default) or the mechanical spin-up, seek, settle and rotation timing of a real drive, for software that times the disc. Images live in dsk/ on the card. From the debug shell, bbc fdc reports the controller and drives, bbc fdc <drive> <file|eject> [A|B] [ssd|dsd|mmb|adf|adl|dds|ddd] changes a side and bbc fdc trace on logs the controller's commands.

MMFS — the Virtual MMC Card

MMFS is the popular filing system that serves hundreds of DFS discs from an MMB file on an SD card plugged into the BBC's user port. Add the BBC-MMC interface and the pico6502 provides that card virtually: the MMB on the pico6502's own SD card (default mmb/BEEB.MMB) is presented to the MMFS ROM as BEEB.MMB on a FAT16 card behind the User VIA, and the unmodified MMFS ROM (the user-port, non-turbo build) runs against it. Load the MMFS ROM into a virtual sideways socket (see Sideways ROM / RAM Sockets) and nothing need be plugged into the machine at all; a physical MMFS card may stay fitted, because the virtual card's user-port traffic never reaches the real port. Everything else on the User VIA — the printer port, timers and interrupts — passes through to the real chip. Use MMFS exactly as usual: *DIN, *DCAT, *DBOOT and so on, with writes going back into the MMB. bbc mmc in the debug shell shows the card state and bbc mmc trace on logs the SPI commands.

Econet — the Virtual Network Module

Add the BBC-NET interface and the BBC gains an Econet module without a module, a clock box or a cable: the pico6502 provides the 68B54 ADLC at $FEA0 and the station-number links at $FE18 that the network filing system ROMs expect, and carries the traffic over its own WiFi or USB network link as AUN — Acorn Universal Networking, Acorn's encapsulation of Econet packets in UDP datagrams on port 32768. AUN is what BeebEm and RISC OS machines speak, so any AUN file server on your LAN can serve the BBC; two are bundled with the pico6502 (see Running an Econet File Server below). A real Econet module may stay fitted — it is never clocked and its registers are never written while the interface is enabled.

You need an NFS or ANFS ROM in the machine — NFS 3.60 (DNFS 1.20), ANFS 4.18 or, in Master mode, the MOS's own ANFS 4.25 — fitted physically or loaded into a virtual sideways socket. Then set, in the Configuration GUI's BBC-NET panel:

Station — your Econet station number, 1–253. Leave it at 0 to take the low byte of the pico6502's IP address, the classic AUN rule (192.168.1.180 is station 180) that aund relies on.

Fileserver — the IP address (and optional port) of the file server. Empty means <your subnet>.254:32768.

FS station — the file server's Econet station, 254 by convention.

AUN port — the UDP port the pico6502 listens on, 32768 normally; change it only when a file server or emulator on the same machine already uses it.

Apply the configuration and reboot. On the BBC:

*NET                 select the network filing system (Master: *CONFIGURE FILE <bank>, or *NET)
*I AM SYST           log in (the bundled servers create SYST with no password)
*CAT                 catalogue; LOAD, SAVE, CHAIN, *INFO, *DIR, *BYE work as on a real network

In Master mode the station and file-server numbers are also written into the virtual CMOS, so *CONFIGURE FS is not needed. The debug shell's bbc net reports the interface — frames sent and received, UDP datagrams in and out, acknowledgements, timeouts and the reply latency — and bbc net trace on logs every ADLC register access and frame.

Running an Econet File Server (aund / PiEconetBridge)

Two proven open-source AUN daemons are bundled in the firmware source tree under tools/econet/, with their upstream sources kept verbatim so they build straight from this tree on any Linux host (a PC, a Raspberry Pi, a VM — the server must simply be reachable from the pico6502 over the LAN):

aund — Ben Harris's AUN / Econet file server for Unix (BSD licence; the extended fork by Steve Inglis). Serves one directory tree as a Level 3 style file server to BBC NFS/ANFS and RISC OS clients, with users, passwords and access rights. Small and simple: choose it when you want a file server and nothing else.

econet-hpbridge — the user-space bridge, file server and print server of Chris Royle's PiEconetBridge (GPLv3), built here without the Raspberry Pi Econet HAT: in its IP-only mode it is a pure AUN file server and bridge on any PC. Richer: several discs, Level 4 features, printing, and trunks to join a real Econet elsewhere. Its DYNAMIC network allocates a station to the pico6502 automatically.

Quick start — a file server in one command

# Once: the build tools and libraries (Debian/Ubuntu shown;
# Fedora: gcc make autoconf automake flex libxcrypt-devel openssl-devel)
sudo apt install build-essential autoconf automake flex libcrypt-dev libssl-dev

cd <root>/projects/tzpuPico
tools/econet/fileserver.sh start        # builds econet-hpbridge if needed, then serves
tools/econet/fileserver.sh status       # pid, the configuration it runs with, recent log
tools/econet/fileserver.sh log          # follow the log
tools/econet/fileserver.sh stop

The script runs the bundled PiEconetBridge file server in IP-only mode as Econet station 254 on UDP port 32768 (the AUN standard and the pico6502's default), serving tools/econet/fileserver/fsroot. On first start it creates the disc directory 0PICO6502; the server then creates its own Passwords, Configuration and Groups files there with the system user SYST and no password. Files you copy into fileserver/fsroot/0PICO6502/ appear on the BBC, and files the BBC saves appear there as plain files. The generated configuration, pid file and log live in fileserver/run/. Options: --bind IP (serve on one address), --port N, --root DIR (another disc directory), --fg (run in the foreground with the log on the terminal; Ctrl-C stops it).

Then, in the pico6502's Configuration GUI, enable BBC-NET on the BBC partition with station 0 (or a number of your choice), network 0, Fileserver <this host's IP>:32768 and FS station 254; apply, reboot, and on the BBC type *NET, *I AM SYST, *CAT.

Building the daemons yourself

tools/econet/build.sh            # both  -> tools/econet/bin/aund and tools/econet/bin/econet-hpbridge
tools/econet/build.sh aund       # or one of: aund | hpbridge
tools/econet/build.sh clean

build.sh checks for the compilers and libraries it needs and names the package to install when one is missing. aund is built with autotools (its configure script is regenerated for your automake) and libcrypt for password hashing; econet-hpbridge is a plain make of the bridge and its file server, with the HAT-specific utilities left out.

Running aund

# examples/aund.conf: serves /srv/econetfs as station 254
#   root /srv/econetfs
#   fsstation 254
#   opt4 2
#   typemap name \.bas$ ffb        (Acorn file types for suffixes)
sudo mkdir -p /srv/econetfs
tools/econet/bin/aund -c tools/econet/examples/aund.conf -d     # -d = debug, foreground
# or copy the file to /etc/aund.conf and run tools/econet/bin/aund

aund uses the classic AUN rule — a client's station number is the low byte of its IP address — so no station table is needed; leave the pico6502's station at 0. Users are created with aund's password file (see aund/aund.passwd.5), or run it with the null user module for an open server. Keep these servers on your own LAN: the Econet file-server protocol predates any notion of network security.

Running econet-hpbridge by hand

# examples/econet-hpbridge.cfg: IP-only file server as AUN station 1.254
#   FILESERVER ON 1.254 PATH /srv/econetfs
#   EXPOSE HOST 1.254 ON PORT *:32768
#   DYNAMIC 2 AUTOACK
sudo mkdir -p /srv/econetfs/0PIBRIDGE          # one directory per disc: 0<NAME>, 1<NAME> ...
tools/econet/bin/econet-hpbridge -l -c tools/econet/examples/econet-hpbridge.cfg

The bridge creates its Passwords, Configuration and Groups files in the disc directory on first start (user SYST, no password); PIFSTOOL in PiEconetBridge/FS/ and the project's own documentation cover users, discs and the print server. Verified with NFS 3.60, ANFS 4.18 and the Master's ANFS 4.25: *I AM, *CAT, *INFO, SAVE/LOAD, *BYE.

Hosts with more than one address

A server with two network cards or bridged VM adapters answers from its primary address, and the pico6502 attributes a reply to a station by its source address. The address in the BBC-NET interface must therefore be the one the server answers from: either configure that primary address on the pico6502, or start the server bound to the address you configured (fileserver.sh start --bind 192.168.1.210). A mismatch shows in the pico6502's boot log as BBC NET: datagram from a.b.c.d:32768 - not the configured fileserver.

Model A, Master Mode and Persistence

Model A RAM — on a 16K Model A, overlays 16K of virtual RAM at $4000–$7FFF so the OS sees a 32K machine. Useful for program and data space; because the video ULA fetches the screen from the host's own DRAM, how a Model A displays a Model-B-sized screen in that window is still to be verified on hardware.

Master mode — gives a Model B the BBC Master 128's memory model: 20K LYNNE shadow screen, 8K HAZEL and 4K ANDY with the ACCCON register virtualised, a virtual CMOS/RTC, and the 65C12 instruction set switched on. It expects a MOS 3.x image in the OS socket (set the offset for a MegaROM). The Master's DFS and ADFS banks (9 and 13) are only preset from the MegaROM when something provides the Master's 1770 controller — enable the BBC-FDC interface with chip WD1770 and board Master 128 (or set Preset disc ROMs to force them) — otherwise bank 13 is left to the machine's own filing ROM, matching the Master's FILE 13 CMOS default. This mode is implemented and under test; treat it as experimental.

Persist — sd (default), flash or off for the virtual CMOS and sideways RAM.

Bus Engine Tuning

Each 6502 driver panel in the Configuration GUI has a Bus Engine Tuning section. For the BBC-B driver the defaults are already the proven Model B values (I/O window $FC00–$FEFF, shadow-write window $0000–$7FFF, ROMSEL at $FE30, burst depth 3), and you should leave the fields empty — an empty field keeps the driver's default and only the keys you set are written. The panel exists so a machine without a driver of its own can still be told its I/O window and paging register and gain the same speed, and so a particular machine can be made more conservative (a smaller burst depth, pipeline or serve switched off) if it misbehaves.

ICE (Debug Shell)

The pico6502 firmware includes the same integrated debug shell (ICE) as the picoZ80, built into the _DBGSH firmware variants. It is reached over the board's USB connection as a serial (CDC) port — connect with any terminal program (e.g. minicom, screen, picocom) and press Enter for the * prompt. The shell is CPU-neutral: the commands are shared with the picoZ80, with the 6502 presenting the 68 commands that apply to it — 69 on the BBC6502 firmware, which adds bbc. Only the Z80's I/O-port commands, its DMA command and its stall monitor are absent, because the 6502 has no I/O address space. The virtual-device commands (dev, sig, ctc, pio, ser, rtc, prn) work as on the picoZ80.

Registers and Execution Control

regs — display the 6502 register file: A, X, Y, S (stack, page $01nn), PC, and the status register P with its flags shown as the string NV-BDIZC, plus the IRQ/NMI line states, halted flag and cycle count.

set — modify a register; flags can be set positionally by letter (from NV-BDIZC) or as a hex value.

step — single-step instructions; break — manage breakpoints; go — resume execution.

dis — disassemble memory. Every opcode disassembles — the table is generated from the emulation core's own decode logic, and undocumented opcodes are shown with a * prefix (e.g. *KIL, *ISC); with a 65C02/65C12 selected the CMOS instructions are shown. disdesc toggles a plain-English description beside each mnemonic.

next — step over a JSR; cpustat — instructions and emulated cycles per second against the host clock (call it twice); cpuprof — where the time goes, per instruction class.

asm — one-line assembler accepting the disassembler's own output verbatim, all 13 addressing modes, and $hex, 0x, trailing-h, %binary and decimal operand forms.

dm / wm — display / write memory. Address arguments take a base prefix (e.g. dis p 0xFF00 6).

Board Bring-Up Diagnostics

These commands answer the first questions asked of a new or misbehaving board, and were the instruments of the BBC Model B bring-up:

busdiag — one snapshot of every socket signal plus the address and data buses. On a board that has never run, this shows immediately whether the socket is alive.

busdiag clk — measures the PHI0 input and the returned PHI1_IN/PHI2_IN phases and compares them. The v2.3 board routes the clock phases outward and back on separate paths, so this command tells a dead buffer apart from a dead clock — exactly the distinction the earlier v2.2 board could not make.

busdiag watch [n] — n rapid snapshots in succession, to catch signals that move.

busprobe <addr> [count] — reads one address repeatedly and reports which data lines are unstable — the quickest way to find a marginal buffer or a voltage that is too low for the clock.

busverify <addr> <len> [passes] — re-reads a range (safe on ROM) and flags flaky reads and any difference between opcode-fetch and data-read cycles; memtest <addr> <len> tests host RAM, and memtest decay checks that it holds its contents over time.

busstate — the live state of the PIO bus engine, for when the machine has stopped and you need to know whether the bus or the CPU stopped first.

writestrobes, iopark, readsettle, readphase, buspipe ... — live A/B switches for the bus engine's behaviour. The defaults are the proven ones; these exist for diagnosing a new host, and a change made here lasts until the next reboot.

piodbg — dumps the state of the PIO state machines driving the bus.

The same commands run in the pico6502sim simulator, whose floating bus reads 0xFF everywhere — directly comparable with a dead board's output, so you always have a known-good reference to diff against.

Troubleshooting

Board appears dead / nothing on the bus

Use the debug shell — flash a _DBGSH firmware variant, connect over USB and run busdiag for a snapshot of every socket signal, then busdiag clk to check the clock phases. On the v2.3 board the clock's separate outward and return paths let this distinguish a dead buffer from a dead clock. See Board Bring-Up Diagnostics.

Compare against the simulator — the same commands in the pico6502sim simulator show what a floating (disconnected) bus looks like: every read returns 0xFF. Matching output on hardware means the socket, buffers or DBE gating deserve attention rather than the firmware.

Check dbeoverride — if the buffered interface is tri-stated the host sees an open bus. The supplied personas set dbeoverride to true; verify the setting matches whether your host drives the socket's DBE pin.

Host computer does not boot

Check orientation — ensure Pin 1 of the pico6502 aligns with Pin 1 of the socket. Inserting the board backwards will damage both the pico6502 and the host computer.

Check seating — remove the pico6502 and reinsert, ensuring all 40 pins are fully seated and none are bent under the board.

Check the configuration — the pico6502 runs from the configuration stored in its flash when a persona or config.json was last applied. A freshly flashed partition has none: apply a persona from the web interface. If the stored configuration is malformed the RP2350 will not initialise the memory map and the host will see an open bus. The 6502 reset vector must be in a valid ROM region.

Confirm firmware is flashed — try connecting the pico6502 via USB (without inserting in the host) and verify the board enumerates on the PC.

Check host power supply — the pico6502 can draw up to 400mA from the 5V rail. Some vintage computers have marginal power supplies; check the 5V rail voltage under load with a multimeter.

No banner or random RAM errors at power-on — raise the core voltage for the configured clock (Configuration GUI, partition core settings), or lower the clock. Voltage headroom differs between boards. busprobe on a RAM address shows marginal data lines directly. If the board has fallen back to 150 MHz safe mode after a hung boot the Dashboard shows it.

First CTRL+BREAK ignored, or a reset vectoring into $0D00 — fixed in firmware from v1.964 (debounced /RES with the reset sequence run after release; NMI edge seeding at reset). Update the firmware.

PiCoPro / Tube banner missing characters, then a dead keyboard — the I/O chase (on by default from late September 2026) prevents side-effect registers being re-decoded by an address held across idle cycles. Check buspipe stats shows iochase on; update the firmware if the command is absent.

Games run slowly — the BBC-B driver must be selected (not the Open6502 driver of the Base6502 or Open6502 personas); the shell's cpustat shows whether the emulated rate has dropped. Check the Bus Engine Tuning fields are empty (driver defaults) or sensible.

MMFS does not see its disc — needs the ROMSEL paging barrier that the BBC-B driver declares; on an older firmware or with the paging keys overridden, lower burstspec or restore the defaults. With the virtual MMFS card, check the BBC-MMC interface is enabled and its MMB file exists on the pico6502's SD card; bbc mmc shows whether the ROM has initialised the card.

DFS reports "Disk fault" or "Drive not ready"; ADFS reports "Disc not found" or "Bad FS map" — with the virtual floppy controller, first check that the chip and board match the filing-system ROM: an ADFS or DFS 2.2x ROM needs the WD1770 on the board it was written for (Acorn, Watford or Master 128 — the latches differ), while DFS 0.90/1.20 needs the 8271. Then check the image path and kind in the Floppy menu or interface slots: an ADFS image needs the ADF or ADL kind, a double-density DFS image DDS or DDD. A single-sided image gives "sector not found" on drives 2/3 by design; put the second side's image in the Side B slot to make the disc double-sided. A two-sided image belongs in a Side A slot with Side B empty. bbc fdc lists the controller and what is mounted; bbc fdc trace on shows the commands the ROM issues.

"No reply from station 254" or "Not listening" — check the file server is running (fileserver.sh status) and reachable from the pico6502's network, that the pico6502's AUN port (32768) is not in use by something else, and that the Fileserver address is the one the server actually answers from (multi-homed hosts: see Running an Econet File Server). bbc net shows whether datagrams are arriving and from where; "No reply" with replies arriving means they are attributed to another station. "Line jammed" means the ROM never saw the line idle — check the interface is enabled and the ROM is an NFS/ANFS build.

Apple I tape does not load — check that the Cassette (ACI) interface is enabled with the ACI firmware as its ROM, and that the tape file exists. Read the range the program was saved from; an Integer BASIC program needs both of its records (004A.00FFR 0300.0FFFR). aci in the shell shows which tape and record the deck is on; aci rew starts the tape again.

Tape does not load — the CMT-UEF interface must be enabled in the driver and the tape slot must point at an existing file in cmt/; bbc tape trace in the shell shows whether the MOS is reading the virtual ACIA. SAVE requires firmware from 2 October 2026 or later.

Cannot connect to the web interface

Check WiFi mode — on first boot or after a factory reset the ESP32 starts in AP mode. Connect to the p6502 WiFi network first (password p6502p6502), then navigate to http://192.168.4.4.

Check configured IP address — if client mode is configured with a fixed IP, verify the IP matches your network subnet.

Check the SD card is present — the web assets in webfs/ on the SD card are required. Without the SD card the web server cannot serve any pages.

Check the webfs directory — confirm the webfs/ directory exists on the SD card and contains the HTML/CSS/JS files from the project repository.

Factory reset WiFi — if credentials are lost, re-flash the ESP32 firmware to clear NVS settings and start fresh.

SD card not recognised

Ensure the SD card is formatted as FAT32. NTFS, exFAT, and FAT16 are not supported.

Try a different SD card — some high-capacity or high-speed cards can have compatibility issues with the ESP32 SPI SD interface.

Cards up to 32GB are well supported. Very large cards (>32GB) may require special formatting.

Re-seat the SD card — remove and reinsert to ensure good contact.

ROM images not loading / 6502 crashes at reset

Verify the file path in config.json exactly matches the file location on the SD card (paths are case-sensitive).

Confirm the ROM image file is present on the SD card — use the File Manager to browse to the expected location.

Check the reset vector — the 6502 reads the reset vector from addresses 0xFFFC and 0xFFFD on power-up. Both addresses must fall within a ROM or RAM block in your memory map. If they fall in an unmapped or PHYSICAL region the 6502 will jump to a random address and crash.

Check the fileofs value — an incorrect offset will load garbage data into the ROM bank.

Verify the size field in the memory map entry is not larger than the ROM image file.

OTA update fails

Ensure you are uploading a .bin file (not a .uf2) for RP2350 OTA updates.

Ensure the binary was built for the pico6502 target (Base6502) — do not upload a picoZ80 binary to the pico6502.

Ensure you are uploading to the inactive slot to preserve the working firmware.

If the OTA update fails or results in a non-booting partition, the bootloader will keep the previous active slot running — repeat the upload process.

For ESP32 OTA failures, re-flash via esptool using the USB connection.

Reference Sites

Resource	Link
pico6502 project page	/pico6502/
pico6502 Technical Guide	/pico6502-technicalguide/
picoZ80 project page	/picoz80/
picoZ80 User Manual	/picoz80-usermanual/
RP2350 Datasheet	datasheets.raspberrypi.com
Pico SDK Documentation	raspberrypi.github.io/pico-sdk-doxygen
ESP32-S3 Technical Reference	docs.espressif.com
MOS 6502 Datasheet	westerndesigncenter.com
X (Twitter) project preview	engineerswork1

Wireless Regulatory Notice

This device incorporates an ESP32-S3-PICO-1 wireless module that transmits in the 2.4 GHz ISM band, making it an intentional radiator under radio-frequency regulations worldwide (including FCC Part 15 Subpart C in the United States, and the Radio Equipment Directive 2014/53/EU in the European Union).

Although the ESP32-S3-PICO-1 module itself carries pre-existing regulatory certifications (FCC, CE, and others), those module-level certifications do not automatically extend to a finished product that incorporates the module. The pre-certified module exemption permits individual hobbyists to build a limited number of devices for personal, experimental, or educational use without obtaining separate equipment authorisation.

Important Limitations

Assembled devices must not be sold, offered for sale, gifted, or otherwise distributed to third parties unless the finished product has been independently tested and granted its own equipment authorisation (e.g. FCC ID, CE marking with a Notified Body assessment) in the relevant jurisdiction.

Building this project for personal use in limited quantities is generally permitted under hobbyist and experimental-use provisions (e.g. FCC § 15.23), provided the device does not cause harmful interference.

Regulatory requirements vary by country. Builders outside the United States should consult their national radio-frequency authority for applicable rules.

Builder’s Responsibility
It is the builder’s sole responsibility to ensure that any device constructed from these designs complies with all applicable radio-frequency regulations in their jurisdiction. The author provides these designs for personal, educational, and hobbyist use and makes no representation that a device built from them satisfies the regulatory requirements for commercial distribution.

pico6502 User Manual