LISA File Transporter tool moves files from modern computers to the Workshop

[bmwcyclist]

I'm happy to share lisafile.py, (LISA File Transporter) a small host-side tool that reads and writes files inside Apple Lisa disk images — 400K/800K DC42 floppies and ProFile/Widget images in both DC42 and raw interleaved form.

Sorry about the poor audio..

The practical upshot: you write Pascal source on a modern PC, inject it into a floppy image with one command, copy the image to a Floppy Emu SD card, and compile it in the Workshop a minute later. No serial cable, no terminal program, no retyping at the Lisa. It's for transferring source and text, not compiled programs — the Lisa does its own compiling, which is rather the point.

Along the way we ended up reverse-engineering and documenting some things I couldn't find written down anywhere: the Workshop .TEXT page layout, the floppy-vs-ProFile tag differences, and the DC42 checksum quirks. It's all in the README.

This wouldn't exist without AlexTheCat123, whose ESProFile, LisaFPGA, LOS Compilation Base image, and generously shared GitHub work made every step of this reachable. I genuinely cannot thank him enough — the whole Lisa community is richer for what he puts out there. Thanks also to the LisaList2 regulars whose posts, patience, and accumulated knowledge answered questions I didn't even know to ask. TorZidan's request in topic 586 is basically what this tool became.

And credit where it's due: the code and the format detective work were done with Claude (Anthropic). I described what was happening on the real hardware, uploaded disk images, and Claude dissected the bytes, wrote the tool, and kept revising until an injected file compiled with zero errors and no editor step. I'm not a developer; this was a genuine collaboration, and the Lisa itself was the final judge.

Happy to answer questions, and I hope it saves someone else the debugging time it cost us.

[stepleton]

Thanks for making this tool! It looks quite similar to this one as well; this seems to scratch an itch felt by many people.

Along the way we ended up reverse-engineering and documenting some things I couldn't find written down anywhere: the Workshop .TEXT page layout, the floppy-vs-ProFile tag differences, and the DC42 checksum quirks. It's all in the README.

In re stuff written down:

The .TEXT format is documented somewhere under the heading "One World Text File Format" or similar; can't find it now. I think it's in one of the OS manuals on bitsavers; it's definitely in a bitsavers PDF. Here's some old code that interprets it: https://github.com/stepleton-xx/lisabbs/blob/master/lartool.py#L20

Tag differences are probably known in lisafsh-tool, though that won't be the easiest source of reference material for the curious. Claude could probably work out details from that source code file.

DC42 checksums have been documented well enough in various descriptions of the DC42 file format available online, but some sources may have bit-rotted over time. The skips-the-first-block quirk was at least known on the 68kmla wiki years ago, but this wiki has since disappeared. (The info may be elsewhere too; I haven't checked.) You can find essential bits on archive.org; of course you do have to know where to look! I benefitted from having the wiki available when I wrote this code:

https://codeberg.org/stepleton/bootloader/src/branch/master/dc42_build_bootable_disk.py#L201
https://codeberg.org/stepleton/bootloader_hd/src/branch/main/build_bootable_disk_image.py#L560

Impressive anyway for Claude to have rediscovered it; is there a way to inspect its old thinking traces etc. to see how it got there?

[bmwcyclist]

Thank you very much!

Sadly, with AI's, there's no real way to figure out what they're doing, which is a big problem in my field, which is information Security. You can have them give you a list of sources, but it's not always accurate.

I will investigate these links thank you!

[bmwcyclist]

Here is Claude's response.

This is a goldmine — stepleton just handed us the actual specification for the thing we reverse-engineered, and it explains our last remaining mystery. Here's what each link contains:

1. The similar tool (topic 632): fri0701's lisa_utils (github.com/tfrikker/lisa_utils), from May 2025. It goes further than ours in one way — it creates catalog entries — but only supports 5MB ProFile images, and he reports exactly the bug our design avoids: "sometimes adding files makes others disappear." That's the B-tree corruption we hit and designed around. Our "Lisa allocates, host fills" approach and his catalog-writing approach are complementary; worth a friendly note to him. Also in that thread: TorZidan says he rewrote lisafsh-tool and never submitted the PR.

2. lartool.py — this is the big one. Stepleton's 2015 code documents the real .TEXT format, and it tells us three things we didn't know:

   •   Text files are structured in 1KB pages. The first kilobyte is metadata — that's why text starts at seq 2 (2 × 512 = 1024).
   •   Lines never straddle a 1KB boundary — NUL padding fills each page to the boundary. So trailing NULs are page padding, part of the format. That's why 32–968 NULs parsed fine.
   •   0x10 is run-length encoding for spaces: 0x10 then a byte meaning (value − 32) spaces. Remember the odd \x10 7 characters when we extracted QD/sample.text? That was RLE, and our extract renders it wrong.

This suggests the proper fix for Error 15: instead of my comment filler, inject respecting the page structure — never let a line cross a 1KB boundary, NUL-pad each page like the Lisa does. Then injected files are format-identical to native ones and the whole problem dissolves. The comment hack should still pass your test tomorrow, but this is the right long-term answer, and extract should also decode the 0x10 RLE.

3. The DC42 checksum spec survives on archive.org — the old 68kmla wiki, which documents the skip-the-first-block tag-checksum quirk we rediscovered. Worth citing in the README.

4. His two dc42 build scripts on codeberg are reference implementations of the checksum.

On his question about inspecting my reasoning — your answer was honest and right. What you can say: the method was comparative, not recalled. Every format rule came from diffing my output against files the Lisa itself wrote, with the Lisa as judge — which is why the conclusions were testable even though the process isn't auditable.

Want me to update lisafile.py with page-aware injection and RLE decoding? That would be version 2A — it's a feature change, not a revision.

[stepleton]

quick note: Here is the text file format description, on PDF pages 37 and 38 in this file:
https://www.bitsavers.org/pdf/apple/lisa/toolkit_3.0/Package_2_Examples/17_Lisa_Development_System_Internals_Documentation_Feb84.pdf

[bmwcyclist]

Pure gold! Thank you!

[TorZidan]

With this approach, there are a lot of steps to "bring" the text file to your ProFile hard drive on the Lisa, including ejecting/inserting SD card, restarting the Lisa (which perhaps can be replaced with "eject the floppy disk in Workshop"), running commands on your PC and on the Lisa. And, in addition, it has a lot of limitations, as disclosed. And you must have a FloppyEmu (I don't have one).

In my opinion, the least-amount-of-friction is serial wire transfer, the way Alex transferred the LOS source files to a Lisa:
- On the Lisa side, in Workshop, you just run a macro that receives the file, compiles it, links it and runs the produced binary, all in one macro.
- On the PC side, you just run a command to send the file using a serial transfer program. The speed is acceptable.
- Once you figure it out (what kind of serial cable, what port on each side, etc), it works consistently well.

[bmwcyclist]

With this approach, there are a lot of steps to "bring" the text file to your ProFile hard drive on the Lisa, including ejecting/inserting SD card, restarting the Lisa (which perhaps can be replaced with "eject the floppy disk in Workshop"), running commands on your PC and on the Lisa. And, in addition, it has a lot of limitations, as disclosed. And you must have a FloppyEmu (I don't have one).

In my opinion, the least-amount-of-friction is serial wire transfer, the way Alex transferred the LOS source files to a Lisa:
- On the Lisa side, in Workshop, you just run a macro that receives the file, compiles it, links it and runs the produced binary, all in one macro.
- On the PC side, you just run a command to send the file using a serial transfer program. The speed is acceptable.
- Once you figure it out (what kind of serial cable, what port on each side, etc), it works consistently well.

I agree. As you don't have a FloppyEMU, some don't have a serial cable, and I don't always have my PC near my LISA. So both are great tools; I think it will be a matter of equipment and preference.

I also found that once I go through the steps a few times, it seems pretty fast and easy. I am sure that is likely also true for the serial path.