Skip to content

README.md

Latest commit

 

History

History
177 lines (122 loc) · 6.44 KB

README.md

File metadata and controls

177 lines (122 loc) · 6.44 KB
Raw

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.