Pico W to 6522 VIA Network Bridge & 65C02 Network DOS

This project brings modern networking to classic 6502‑based computers. A Raspberry Pi Pico W acts as a smart peripheral connected through a 65C22 VIA, translating the 6502’s parallel bus operations into WiFi, TCP/IP, and filesystem requests. The result is a full Network DOS for the 65C02 — complete with file management, transient applications, BASIC integration, and internet‑powered utilities.

The repository also includes a full 65C02 computer emulator that runs on a standard Raspberry Pi Pico (RP2040). This emulator presents RAM, ROM, ACIA, and a 6522 VIA, allowing the Pico W bridge to interact with it exactly as if it were talking to real hardware. With two inexpensive Picos, you can develop and test the entire system without a physical 65C02 machine.

📘 Documentation

👉 User & Developer Guide
👉 Technical Notes & Status

---

Who Is This For?

This project is designed for:

• 6502 and retro‑computing enthusiasts who want to extend classic hardware with modern networking.
• Homebrew computer builders exploring how to integrate WiFi, TCP/IP, and remote filesystems into a 65C02 system.
• Educators and hobbyists learning how to design a DOS, shell, or smart‑peripheral architecture.
• Firmware and embedded developers interested in clean, reproducible workflows across C and 6502 assembly.

If you're building a 65C02 machine, experimenting with VIA‑based I/O, or curious how to graft the internet onto an 8‑bit CPU, this project is for you.

---

Key Features

• Smart Peripheral Bridge: Pico W abstracts WiFi, TCP/IP, and file I/O behind a simple 6522 VIA interface.
• Network DOS: A ROM‑resident shell providing file management (LS, CD, MKDIR, RM), file transfer (UPLOAD, DOWNLOAD), and execution.
• Thin Client Architecture: Utilities like MAN, NEWS, WEATHER, and GAMES are transient .BIN files loaded from the server on demand.
• MSBASIC Integration: LOAD and SAVE programs directly over the network.
• Robust Protocol: Hardened handshake with atomic “Ghost Byte” protection for reliable 6522 bus transfers.
• Internet Services: NTP time, weather, news headlines, trivia, and more — all from the 6502 command line.

---

Command Summary

• File System: DIR/LS, CD, MKDIR, RMDIR, DEL/RM, COPY, RENAME, TOUCH
• Transfer: UPLOAD, DOWNLOAD, TYPE, HEX, APPEND
• Execution: RUN, BRUN, BLOAD
• Network: WIFI (scan/connect/save), PING, INFO, DATE, TIME
• Apps: MAN, WEATHER, NEWS, TRIVIA, PLAY
• System: MEM, CLS, HELP, REBOOT, EXIT, DEMO

For full details, see STATUS.md.

---

Project Architecture

1. 6502 Network DOS (6502_SOFTWARE/)

Written in ca65 assembly. Provides:

• the standalone NETDOS> shell
• the relocatable network driver (network.lib)
• MSBASIC integration for network file access
• transient command loader and runtime

2. Pico W Bridge Firmware (FIRMWARE/)

C firmware for the Pico W that:

• listens on the 6522 bus
• performs WiFi, TCP/IP, and filesystem operations
• returns results to the 6502 in a deterministic, cycle‑safe way

3. Pico 6502 Emulator (EMULATOR/)

C firmware for a standard Pico that emulates:

• 65C02 CPU
• RAM/ROM
• ACIA
• 6522 VIA

The compiled 6502 ROM is injected via eater.h.

4. Build System & Tools (build.sh, TOOLS/)

Unified build system that:

• compiles all 6502 assembly
• builds both Pico firmwares
• injects ROM images
• flashes devices
• builds transient .BIN commands

---

Directory Structure

• / — Build script, Makefile, top‑level docs
• 6502_SOFTWARE/ — All 65C02 assembly
  • LIB/ — Network driver
  • SHELL/ — Network DOS shell
  • SHELL/commands/ — Transient commands
  • INTEGRATIONS/MSBASIC/ — BASIC integration
• EMULATOR/ — Pico‑based 65C02 emulator
• FIRMWARE/ — Bridge firmware for real hardware
• TOOLS/ — Build helpers
• DOCS/ — Manuals, technical notes, milestones

---

Unified Build System

The build.sh script automates the entire workflow.

Prerequisites

• cc65 toolchain
• picotool
• ARM GCC toolchain & Pico SDK

Usage

# Interactive build menu
./build.sh

# Build and flash the standalone Network DOS Shell
./build.sh shell

# Build and flash the MSBASIC integration
./build.sh basic

# Build and flash the dedicated Bridge firmware
./build.sh firmware

# Build transient command binaries (.BIN)
# NOTE: Run "./build.sh shell" first to generate cmd_shell.lbl
./build.sh commands

# Clean all build artifacts
./build.sh clean

---

Why This Exists

The goal of this project is to explore what happens when classic 8‑bit design meets modern networking. The 65C02 is a remarkably capable CPU, and the 6522 VIA provides a clean, deterministic interface for bridging eras. By pairing a Pico W with a 65C02 system, this project demonstrates how vintage hardware can access WiFi, NTP, HTTP APIs, remote filesystems, and more — all through a simple, well‑defined parallel protocol.

---

Contributing

Contributions are welcome!

You can open:

• Issues — bug reports, feature requests, questions
• Pull Requests — code contributions
• Discussions — design ideas, architecture questions, community chat

Please keep contributions consistent with the project’s goals:

• Clean, maintainable code
• Reproducible builds
• Clear documentation
• Respect for 6502 constraints and design philosophy

All contributions must be licensed under the MIT License.

---

Credits & Attribution

This project was created and is maintained by Donald Moran.

Acknowledgements:

• Microsoft BASIC: Adapted from the reverse-engineered source for the 6502.
• Raspberry Pi Pico SDK: Used for the bridge firmware.
• Pico-6502 Emulator: Heavily modified fork of jfoucher/pico-6502.
• 6502 Emulation Core: Derived from a Code Golf StackExchange answer.

If you use this code in your own 6502 computer, emulator, firmware, or educational project, attribution is appreciated. A link back to this repository helps others discover the work and keeps the community growing.

---

License

This project is released under the MIT License.
See the LICENSE file for details.