Publish the reproducible Sound Lab and FPGA Colour Lab sources
This commit is contained in:
commit
88254d7e24
27 files changed
+4574
No files matched your search
@@ -0,0 +1,161 @@
|
||||
# Sound Lab — diagnostic disk
|
||||
|
||||
Sound Lab is a standalone, keyboard-driven CoCo program for comparing the Tandy
|
||||
Speech/Sound Cartridge in VCC Plus, on a real CoCo, and eventually in the research
|
||||
FPGA core. It does **not** change VCC Plus's speech/sound implementation. This
|
||||
first disk provides a useful listening baseline; [coverage](COVERAGE.md) identifies
|
||||
the larger diagnostic specification's remaining work explicitly.
|
||||
|
||||
## Start here
|
||||
|
||||
Keep `SOUNDLAB.DSK` as an unchanged master. Make a **writable copy** for each test
|
||||
environment. The disk is ordinary single-sided Disk BASIC: 35 tracks, 18 sectors
|
||||
per track, 256 bytes per sector, 161,280 bytes in total. No cartridge ROM is in
|
||||
the disk or delivery archive.
|
||||
|
||||
1. Use a 64-KiB-or-larger CoCo, Disk BASIC, a Speech/Sound Cartridge and **normal
|
||||
CPU speed**. Start with low speaker volume. In VCC Plus, use Disk BASIC with
|
||||
the Speech/Sound Cartridge configured. Do not use an OS-9 preset.
|
||||
2. Insert the writable disk in **FD0**, then type `DOS` and press Return.
|
||||
Alternatively type `RUN"SOUNDLAB"`. The supplied BASIC loader uses `PCLEAR1`
|
||||
and `CLEAR32` before loading the machine-language program at `$1600`.
|
||||
Do not bypass that setup with a bare `LOADM` in an arbitrary existing session.
|
||||
3. Choose the platform, CoCo model and NTSC/PAL setting. These are descriptions,
|
||||
**not automatic cartridge detection**. Confirm your own physical cartridge,
|
||||
MPI arrangement and speaker path separately. The program does not switch MPI
|
||||
banks or enable double-speed mode.
|
||||
4. Choose **D** to save reports to the writable FD0 copy, or **M** for screen-only
|
||||
operation. Use the diagnostic disk, never an important software/data disk.
|
||||
5. Start **1 — Meet the Robot**. The brief showcase includes a greeting, a tone,
|
||||
rising notes, a chord, noise, a small original tune and a spaceport voice.
|
||||
**2** selects more guided examples. **3** requires explicit confirmation for
|
||||
the larger engineering set. **4** runs a case ID from the manifest.
|
||||
|
||||
Disk loading and simultaneous cartridge use require compatible hardware routing,
|
||||
usually a Multi-Pak plus disk controller. Do not hot-swap powered cartridges to
|
||||
work around a single cartridge slot. Screen-only mode suppresses report disk I/O;
|
||||
it does not invent a new way to load the program.
|
||||
|
||||
## Listen, repeat and recover
|
||||
|
||||
Read the listening prompt, then press **Return** to play (or **X** for the menu).
|
||||
Each result waits for your response:
|
||||
|
||||
| Key | Meaning |
|
||||
| --- | --- |
|
||||
| H | Heard the expected example |
|
||||
| W | Heard something wrong |
|
||||
| N | No sound |
|
||||
| U | Unsure |
|
||||
| R | Record this attempt and repeat the example |
|
||||
| S | Skip |
|
||||
| T | Add a short note, then choose a result |
|
||||
| X | Return to the menu; also interrupts bounded playback waits |
|
||||
|
||||
The first five allophone addresses are **pauses**: silence is intentional.
|
||||
Three AY tone channels mix to mono; they are not three stereo positions. A saved
|
||||
`AUTO=OBSERVED` describes register/timing observations, not successful listening.
|
||||
Only your response supplies `HUMAN=HEARD`. Test timing is in video-frame ticks;
|
||||
PAL/NTSC, polling overhead and firmware latency prevent treating it as calibrated
|
||||
audio duration. Analog tolerances remain `MEASURE_BASELINE`.
|
||||
|
||||
Sound Lab resets the cartridge at each case's beginning to establish a consistent
|
||||
timer/buffer baseline. It records that prelude separately from the vector bytes.
|
||||
It sends the documented stop-both command after each case, or resets after an
|
||||
interrupted/unfinished packet or timeout. The cartridge's stored buffers are
|
||||
diagnostic scratch space. **Q** saves the final report, resets the cartridge and
|
||||
returns to BASIC with the saved PIA audio routing restored. It leaves the CPU
|
||||
speed and MPI selection alone. The loader's text mode/graphics-page allocation
|
||||
is part of this standalone program, not a preserved running CoCo application.
|
||||
|
||||
## Reports
|
||||
|
||||
The program reserves unused `SND0001.TXT`, `SND0002.TXT`, … filenames. Existing
|
||||
reports are never intentionally replaced. It flushes observations **between**
|
||||
cases, not during sound playback. The small CoCo RAM log rolls into additional
|
||||
numbered files; retain **all** of them. The displayed attempt number is a session
|
||||
sequence and distinguishes repeats and later re-selection of the same case.
|
||||
|
||||
Keep the disk inserted during a session. Before updating a checkpoint, the
|
||||
program checks the saved file's bytes against its prior checkpoint. A changed or
|
||||
swapped file is refused with error250. Disk errors leave the current RAM log
|
||||
available: use **5** to page/photograph it, or **6** to retry saving after fixing
|
||||
the original media problem. A partially failed physical write may require keeping
|
||||
the RAM photographs rather than retrying over an uncertain file. Do not swap a
|
||||
different disk into the open report. No formatting or repair is attempted.
|
||||
|
||||
In screen-only mode, a full log pauses before the next case. Photograph its
|
||||
pages before explicitly choosing **C** to clear it for another report segment.
|
||||
**X** keeps it and returns to the menu. There is no silent log eviction.
|
||||
|
||||
Safely save/eject the disk in VCC Plus, or transfer the physical disk image using
|
||||
your normal hardware workflow. Work from a saved host copy:
|
||||
|
||||
```sh
|
||||
python3 host/soundlab_reports.py extract MYTEST.DSK --output extracted
|
||||
python3 host/soundlab_reports.py convert extracted/SND0001.TXT \
|
||||
--output readable --manifest SOUNDLAB-manifest.json
|
||||
```
|
||||
|
||||
See [host report instructions](host/README.md) for comparison and JSON/CSV/HTML
|
||||
exports. Keep the original modified DSK, raw TXT files, manifest and any WAVs or
|
||||
photographs. The pristine disk hash changes when reports are saved; this is
|
||||
expected and does not invalidate the original build receipt.
|
||||
|
||||
Optional [WAV analysis](audio/README.md) accepts manually marked intervals and
|
||||
measures signal levels, clipping and qualified isolated-tone estimates. It never
|
||||
relabels measurements as human listening or analog hardware acceptance.
|
||||
|
||||
## Rebuild and validate
|
||||
|
||||
In the VCC Plus repository:
|
||||
|
||||
```sh
|
||||
python3 examples/sound-lab/build.py
|
||||
python3 -m unittest discover -s examples/sound-lab/tests -v
|
||||
```
|
||||
|
||||
For the isolated real-ROM run, use the retained core library and explicit private
|
||||
ROM folder (these inputs are never copied into the delivery):
|
||||
|
||||
```sh
|
||||
python3 examples/sound-lab/check.py \
|
||||
--core .build/371-release-native/Build/Products/Release/libVCCCore.a \
|
||||
--roms platforms/macos/LocalResources/ROMs
|
||||
```
|
||||
|
||||
The default output is `.build/sound-lab`. An exported project accepts explicit
|
||||
`--toolchain /path/to/Toolchain --output /path/to/new-build` arguments. Use the
|
||||
bundled VCC Plus toolchain, **CMOC0.1.101**, with its matching LWTools, SSC and
|
||||
public-domain `decbfile` libraries. The supported driver uses ordinary Disk BASIC
|
||||
ROM services; no separately licensed standalone disk driver is copied here.
|
||||
Python is only a build/reporting dependency on the host, not on the CoCo.
|
||||
|
||||
`SOUNDLAB-manifest.json` binds the short guest build ID and vector CRCs to full
|
||||
source/artifact SHA-256 hashes. `SHA256SUMS` covers the BIN, BASIC loader and DSK.
|
||||
The host BASIC source uses LF; its disk member uses the disk writer's explicit
|
||||
leading-CR and CR line-ending conversion. Both forms contain the same loader.
|
||||
The compiler's `$7A00` limit and retained map check ordinary memory bounds. The
|
||||
text-only guest uses the otherwise unused, `PCLEAR1`-reserved PMODE page at
|
||||
`$0E00–$13FF` as a1536-byte log. Compiled assembly is checked for one actual
|
||||
`LDB $FF7E` per status-reader call. Ready and completion loops have elapsed-tick
|
||||
and independent iteration limits.
|
||||
|
||||
The [native runner](native/run.cpp) boots the disk through actual Disk BASIC and
|
||||
FD502 emulation with existing private local ROM inputs. It does not launch or
|
||||
operate the user's app. The build receipt records what was tested. Physical CoCo
|
||||
listening, physical disk behavior and future FPGA acceptance remain separate.
|
||||
|
||||
## Sources and license
|
||||
|
||||
Sound Lab guest, generator, original vectors, host utilities and tests are
|
||||
GPL-3.0-or-later, like the VCC Plus SDK. The tiny DOS bootstrap retains Pierre
|
||||
Sarrazin's public-domain attribution. CMOC library/dependency notices remain in
|
||||
the toolchain distribution; this project does not redistribute the compiler or
|
||||
private firmware. The delivery's `COPYING` is the GPL license text.
|
||||
|
||||
[Packet/source notes](vectors/PROTOCOL.md) cite a downloaded, hashed OCR/typeset
|
||||
reproduction of Tandy's original publication. It is not a photographic scan.
|
||||
The diagnostic bytes are newly authored; manual PDFs and ROM contents are not
|
||||
included in the disk or source archive. No checksum establishes redistribution
|
||||
rights or proof of hardware fidelity.
|
||||
Reference in new issue
Block a user