Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .claude/agents/steward.md
Original file line number Diff line number Diff line change
Expand Up @@ -203,7 +203,8 @@ The contracts this repository states, and what keeps each one honest:
docs in the same change. A `Known-Issues.md` entry the change fixes is
closed, and a cited `file:line` that moved is drift.
- **The remote protocol.** `docs/ControlComms.md` documents every command and
token, and TeensyROM-Web, TeensyROM-CLI and c64cast depend on it. A command,
token, and Trom API (the engine of the TeensyROM Suite) and c64cast depend on
it. A command,
token, response or timing that changed without the doc is drift, and an
incompatible change not called out in the PR is a finding.
- **Shared layouts.**
Expand Down
3 changes: 2 additions & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -201,7 +201,8 @@ its size, because a one-line change there does the most damage:
defect here can leave a board that needs the program button to recover.
- **The remote protocol:** `SerUSBIO.ino`, `Min_SerUSBIO.ino`, `ServiceTCP.ino`,
`Min_ServiceTCP.ino`, `RemoteControl.ino`. It is a network-facing trust
boundary, and TeensyROM-Web, TeensyROM-CLI and c64cast depend on its format.
boundary, and Trom API (the engine of the TeensyROM Suite) and c64cast depend
on its format.
- **`.github/workflows/`:** the jobs that decide whether a PR may merge and
that build release images.

Expand Down
8 changes: 4 additions & 4 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@ Thanks for your interest in TeensyROM! The project is maintained by one person (
Smith / Sensorium Embedded) in spare time, and a growing group of regular contributors
now sends a steady stream of pull requests: features, IO handlers, extensions, docs and
tooling, alongside the separate
[TeensyROM-Web](https://github.com/MetalHexx/TeensyROM-Web)/[CLI](https://github.com/MetalHexx/TeensyROM-CLI)
tools. Each release's notes credit the people whose work went into it. Reviewing,
[TeensyROM Suite](https://github.com/MetalHexx/TeensyROM-Suite)
apps. Each release's notes credit the people whose work went into it. Reviewing,
hardware testing and releasing still go through one person, so this doc covers what to
expect on timing (see [Review and release timing](#review-and-release-timing)) and how to
help your contribution land on the first pass.
Expand Down Expand Up @@ -92,8 +92,8 @@ release rather than rejected outright, but flagging it up front saves a review c
- **The external protocol is a stable surface other people's projects depend on.**
[docs/ControlComms.md](docs/ControlComms.md) documents the USB/Ethernet remote command
protocol, and the cartridge register map it's built on is relied on by downstream
projects — [TeensyROM-Web](https://github.com/MetalHexx/TeensyROM-Web),
[TeensyROM-CLI](https://github.com/MetalHexx/TeensyROM-CLI), and
projects — [Trom API](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/trom-api.md),
the engine of the TeensyROM Suite, and
[c64cast](https://github.com/kfox/c64cast) (which uses TR+'s Remote DMA feature). If your
change alters register meanings, command formats, or timing those tools rely on, call it
out explicitly in the PR — a silent break there breaks someone else's project, not just
Expand Down
7 changes: 4 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@
* **Internet interface**: Connect to a [Telnet BBS](docs/Ethernet_Usage.md) or use the integrated [web browser](docs/Browser_Usage.md) to surf/search/download
* **Remote Control** your C64 using
* [NFC Launch System](docs/NFC_Loader.md): The feel of old school cartridges combined with [instant loading](https://www.youtube.com/watch?v=iNfQx2gx0hA)
* The feature rich (and cross-platform) [TeensyROM-Web](https://github.com/MetalHexx/TeensyROM-Web) and [Command Line Interface](https://github.com/MetalHexx/TeensyROM-CLI)
* [TeensyROM Suite](https://github.com/MetalHexx/TeensyROM-Suite) (cross-platform): [Trom UI](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/trom-ui.md) with its [DJ Mixer](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/dj-mixer.md), [Trom Terminal](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/trom-terminal.md), the [Trom Agent](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/trom-agent.md) AI companion, and [Trom API](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/trom-api.md) for your own tools
* SID File Player with voice muting and speed control
* Bitmap Picture viewer, Text/PETSCII viewer, Custom BASIC Commands, Autolaunch, *and more*
* Lots of games, utilities, pics, and music built-in: no external media required to get started!
Expand Down Expand Up @@ -59,7 +59,7 @@ Compatible with C64 and C128 machines/variants, NTSC and PAL supported.
* USB thumb Drive
* SD card
* Teensy Internal Flash Memory
* Transfer directly from PC using [TeensyROM-Web](https://github.com/MetalHexx/TeensyROM-Web) (cross-platform, recommended) or the [TeensyROM UI](https://github.com/MetalHexx/TeensyROM-UI) (Windows desktop)
* Transfer directly from your computer using [Trom UI](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/trom-ui.md#copy-files-to-your-cart) (drag and drop, or watch folders), [Trom Terminal](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/trom-terminal.md#copy-files) or [Trom Agent](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/trom-agent.md) from the [TeensyROM Suite](https://github.com/MetalHexx/TeensyROM-Suite)
* See supported file details [here](https://github.com/SensoriumEmbedded/TeensyROM/blob/main/docs/General_Usage.md#loading-files-and-emulating-roms)
* [NFC Loading system](docs/NFC_Loader.md) available to quickly select/load with NFC tags.
### **MIDI in/out via USB Host connection:**
Expand Down Expand Up @@ -116,6 +116,7 @@ Compatible with C64 and C128 machines/variants, NTSC and PAL supported.
* MIDI ASID Demo: Stream .SID & .MIDI files directly to your C64/SID
* Web Browser and internet file download demo
* SID Player and Picture viewer demo
* **[SID DJ on Commodore 64 (ft. TeensyROM)](https://youtu.be/PjhqYkmsScg)**: SID tunes mixed live on real C64s in the Trom UI [DJ Mixer](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/dj-mixer.md), plus a [Scratch / Beat Juggle](https://youtu.be/xoJBOEPB5IY) preview

## Compatibility
* TeensyROM compatability has been fully validated on **many** different NTSC **and** PAL machines: C64, C64C, SX-64, and C128 as well as modern reproductions such as the C64U, Ultimate 64, EVO64, Mega65 (r5 and higher), and Reloaded MKII
Expand All @@ -136,7 +137,7 @@ The Teensy 4.1 is slightly "overclocked" to 816MHz from FW in this design. Per t

## Inspiration and Thank-Yous:
* [**Heather S**](https://www.instagram.com/dalliancecreations/): Loving wife, continuous encourager, saintly patience
* [**MetalHexx**](https://github.com/MetalHexx): Big picture ideas, remote controls via [TeensyROM Web](https://github.com/MetalHexx/TeensyROM-Web), [UI](https://github.com/MetalHexx/TeensyROM-UI) and [CLI](https://github.com/MetalHexx/TeensyROM-CLI), testing, friendship
* [**MetalHexx**](https://github.com/MetalHexx): Big picture ideas, remote control via the [TeensyROM Suite](https://github.com/MetalHexx/TeensyROM-Suite), testing, friendship
* [**Kelly Fox**](https://github.com/kfox): TR+ contributions ([Host Extensions](docs/TR_Host_Extensions.md), build system and much more), [c64cast](https://github.com/kfox/c64cast)
* [**John Swiderski**](https://github.com/ziggystar12) of Mean Hamster Software: [MPE](https://meanhamster.com/games/mpe-power-engine), the first TR Host Extension, and the inspiration behind them
* [**Paul Harker aka LessPaul**](https://github.com/LessPaul): Freezer cartridge contributions (Action Replay, Retro Replay, Final Cartridge III, Super Snapshot V5)
Expand Down
7 changes: 6 additions & 1 deletion docs/ASID_Player.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ Here are a few ASID sources which can be used to stream to your C64/SID. See det
|**[SID Factory II](https://blog.chordian.net/sf2/)**|Win/Mac/Linux|Cross-platform SID music editor with ASID output ([beta branch](https://github.com/Chordian/sidfactory2/tree/asid-support))|
|**[ASIDXP](https://elektron.se/support-downloads/sidstation#resources)**|Win/Mac|Stream SID files directly from your local hard drive|
|**[SIDPlay](http://www.sidmusic.org/sidplay/mac/)**|Mac|Stream from your local hard drive with visualizations, etc|
|**[Trom UI DJ Mixer](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/dj-mixer.md)**|Win/Mac/Linux/Pi|Play and mix SID tunes live on one or two C64s: beat-match, loop, cue and scratch|

## USB/TeensyROM Setup
* Connect USB cable from a MIDI Host/computer to the USB Type B Micro Device port on the Teensy module.
Expand Down Expand Up @@ -100,7 +101,7 @@ Once the Frame Timer is turned on, the buffer size can be selected with `b` (sma
* Select the "EMU" tab, in the ASID box, enable output of "Synth V1" and your "TeensyROM-xxxxxxxx" as the destination
* Using more than one TeensyROM with ChipSynth C64? See [Using more than one TeensyROM](#using-more-than-one-teensyrom) above, extra instances need to run as the standalone application rather than inside the same DAW.
* There are many things you can do with this great program, purchasing will unlock the 10 minute limit per use.
* You can use the [TeensyROM CLI tool](https://github.com/MetalHexx/TeensyROM-CLI) to tweak the Chipsynth presets to work better with ASID.
* You can use [Trom Terminal](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/trom-terminal.md#generate-asid-presets-for-chipsynth) to make ASID-friendly copies of your Chipsynth presets.
* Be sure to leave the Frame timer **off** as ChipSynth does not send data in frames.
* Here's a [demo video](https://www.youtube.com/watch?v=-Xs3h59-dOU) showing some of the capabilities
* **SID Factory II** for cross-platform SID music editing/playing
Expand All @@ -120,6 +121,10 @@ Once the Frame Timer is turned on, the buffer size can be selected with `b` (sma
* Click "Play"
* The playback should be emanating from your C64/128!
* You can play with the frequency to adjust the playback tempo if needed.
* **Trom UI DJ Mixer** to play and mix SID tunes live on one or two C64s
* Install the [TeensyROM Suite](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/getting-started.md) and connect a TeensyROM by USB for each deck you play
* Open the [DJ Mixer](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/dj-mixer.md) in Trom UI, in a browser with MIDI support, and allow MIDI access
* Pick the TeensyROM each deck plays through; the mixer starts each one's ASID Player with a click

<br>

Expand Down
2 changes: 1 addition & 1 deletion docs/Architecture/Comms-Protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ Binary, token-based request/response protocol over USB Serial or Ethernet TCP (p
- Commands split into "always-available" (work even while TR is busy — reset, launch, version, DMA memory access, C64 pause) vs "conditionally-available" (return `FailToken` + `"Busy!"` if not idle — file ops, SID commands, most UI commands). While the ASID Player runs, Ping and file ops are also accepted over USB serial (TCP doesn't answer then: the player turns off the Ethernet interrupt); ASID playback can pause while one runs
- Firmware-mode-aware: minimal-boot firmware only accepts a restricted command subset — see [Teensy-Firmware.md](Teensy-Firmware.md#minimalboot-vs-full-firmware)
- Implemented Teensy-side in `Source/Teensy/SerUSBIO.ino` (serial) and `Source/Teensy/ServiceTCP.ino` (Ethernet, routes into the same parser)
- Several independent third-party client implementations exist (TeensyROM-UI, TeensyROM-Web, TeensyROM-CLI, trterm, c64cast) — see the project table in `docs/ControlComms.md`
- Several independent third-party client implementations exist (Trom API, the engine of the TeensyROM Suite; trterm; c64cast) — see the project table in `docs/ControlComms.md`

<br>

Expand Down
24 changes: 15 additions & 9 deletions docs/C64_Ultimate_Enhancements.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ Much like the hardware synthesizer TherapSID, TeensyROM implements the ASID prot

- Stream SID tunes from [DeepSID](https://deepsid.chordian.net/) with multi-SID support
- Control the SID chip as a synthesizer using [ChipSynth C64](https://plogue.com/products/chipsynth-c64.html) from Plogue.
- Play and mix SID tunes live on one or two C64s with the [DJ Mixer](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/dj-mixer.md) in Trom UI

For more information: [ASID Player Guide](/docs/ASID_Player.md)

Expand All @@ -41,17 +42,21 @@ For more information: [NFC Loader Guide](/docs/NFC_Loader.md)

## Modern UI Control

TeensyROM apps feature a mashup of modern and retro. By leveraging modern computing power and memory, they unlock instant search, indexing, and random selection across massive file collections—capabilities impossible on vintage hardware alone:
[TeensyROM Suite](https://github.com/MetalHexx/TeensyROM-Suite) is a mashup of modern and retro. By leveraging modern computing power and memory, it unlocks instant search, indexing, and random selection across massive file collections—capabilities impossible on vintage hardware alone:

- **Modern Web Interfaces**: Browse and launch your entire game and media library from any computer via WiFi, Ethernet, or USB
- **Live Video Integration**: Watch your C64 gameplay with large array of authentic CRT emulation effects (Web only)
- **Complete Media Management**: Search, filter, transfer files, create playlists and track favorites across all storage devices
- **Advanced Playback Control**: Shuffle mode, auto-play, progress tracking, and support for multi-device DJ setups
- **Cross-Platform Support**: Apps available for Windows, macOS, and Linux
- **Your Library, Anywhere**: Browse, search and launch every game, demo, SID and image from any computer, phone or tablet on your network, with your TeensyROM on USB or Ethernet
- **Stream It**: Shuffle and auto-play hands-free across all your storage, with favorites, play history and [audio on your phone](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/trom-ui.md#mobile-audio-streaming)
- **Live Video Integration**: Watch your C64 in the browser with a large array of authentic [CRT effects](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/trom-ui.md#video-and-crt-emulation)
- **[DJ Mixer](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/dj-mixer.md)**: One or two C64s become decks: beat-match, loop, cue and scratch SID tunes live, with every note from a real SID chip. Watch the [Mix Preview](https://youtu.be/PjhqYkmsScg) and [Scratch / Beat Juggle](https://youtu.be/xoJBOEPB5IY)
- **[Copy Files](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/trom-ui.md#copy-files-to-your-cart) and [Watch Folders](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/trom-ui.md#watch-folders)**: Drag and drop files, folders and archives onto several TeensyROMs at once, or let a folder on your computer send whatever lands in it
- **[Themes](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/trom-ui.md#themes)**: Recolor the TeensyROM's own menu, on one TeensyROM or all
- **AI Companion**: [Trom Agent](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/trom-agent.md) helps you explore your collection, play mixes, and troubleshoot your setup with [Virtual Travis](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/trom-agent.md#the-setup-doctor)
- **Cross-Platform Support**: Windows, macOS, Linux, and Raspberry Pi
- **Featured Apps**:
- [Web UI / HTTP API](https://github.com/MetalHexx/TeensyROM-Web) **New App!** (Cross-platform)
- [CLI App](https://github.com/MetalHexx/TeensyROM-CLI) (Cross-platform)
- [Desktop App](https://github.com/MetalHexx/TeensyROM-UI) (Windows Only)
- [Trom UI](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/trom-ui.md): the web app, home of the DJ Mixer
- [Trom Terminal](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/trom-terminal.md): a BBS-style menu plus one-line commands for your scripts
- [Trom Agent](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/trom-agent.md): your AI companion, as a plugin for your AI coding agent
- [Trom API](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/trom-api.md): the engine behind them all, open to your own tools
- [TR Transfer/Control App](https://github.com/SensoriumEmbedded/TRWinApp) (Windows Only)

## Serial / TCP API
Expand All @@ -62,6 +67,7 @@ TeensyROM exposes a comprehensive command protocol over USB Serial or TCP/Ethern
- **File Operations**: Upload, download, copy, delete, and directory listing capabilities across SD and USB storage
- **Playback Control**: Remote file launching, SID player control (pause, speed, voice muting, sub-tune selection)
- **Device Management**: System commands including reset, ping, version info, firmware checks, and DMA control
- **HTTP API**: [Trom API](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/trom-api.md#build-your-own-tools) wraps the protocol in an HTTP API with an OpenAPI spec, so your tools can launch files, search your library, copy files and set themes from any language

## Image Launcher Support

Expand Down
5 changes: 2 additions & 3 deletions docs/ControlComms.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,8 @@ The sections below detail the physical/transport connection options, advanced be
The protocol is also currently implemented in several control projects, for reference:
|Project name/Link|Developer|Description|
|:--|:--:|:--|
|**[TeensyROM-UI](https://github.com/MetalHexx/TeensyROM-UI)** |[MetalHexx](https://github.com/MetalHexx)|Windows based UI with media exploration, uses all available commands|
|**[TeensyROM-Web](https://github.com/MetalHexx/TeensyROM-Web)** |[MetalHexx](https://github.com/MetalHexx)|Cross-platform web based version with stand-alone API server|
|**[TeensyROM-CLI](https://github.com/MetalHexx/TeensyROM-CLI)** |[MetalHexx](https://github.com/MetalHexx)|Cross-platform CLI version|
|**[Trom API](https://github.com/MetalHexx/TeensyROM-Suite/blob/main/docs/trom-api.md)** |[MetalHexx](https://github.com/MetalHexx)|Engine of the TeensyROM Suite: speaks this protocol over USB serial and TCP, and serves it as an HTTP API with an OpenAPI spec|
|**[TeensyROM Suite](https://github.com/MetalHexx/TeensyROM-Suite)** |[MetalHexx](https://github.com/MetalHexx)|Trom UI (web, with the DJ Mixer), Trom Terminal and Trom Agent, all built on Trom API|
|**[c64cast](https://github.com/kfox/c64cast/)** |[Kelly Fox](https://github.com/kfox) |Python project to stream video/audio to the C64 via the TR+|
|**[TRWinApp](https://github.com/SensoriumEmbedded/TRWinApp)** |[SensoriumEmbedded](https://github.com/SensoriumEmbedded)|Very basic command implementation, used for test/development|
|**[TeensyROMControl](https://github.com/SensoriumEmbedded/TeensyROMControl)** |[SensoriumEmbedded](https://github.com/SensoriumEmbedded)|Library for TeensyROM control from a microcontroller|
Expand Down
Loading
Loading