tom-seddon / beeblink

A file storage system for the BBC Micro

BeebLink

A file storage system for the BBC Micro. Make your PC do something useful for a change: have it act as a file server for your BBC.

No more swapping discs, no more noisy drives, no more 31 file limit, file access is very fast, and it's super-easy to share BBC files with your PC.

If you've got multiple BBCs, they can all connect at once and share files.

"Action" screen grabs

BeebLink also has experimental support for the Electron.

Installing the server

Windows

Get the latest release from https://github.com/tom-seddon/beeblink/releases/latest. Download the Windows zip and unzip it somewhere.

macOS

Get the latest release from https://github.com/tom-seddon/beeblink/releases/latest. Download the macOS zip and unzip it somewhere.

The macOS version is not notarized. To bypass any Gatekeeper dialogs: open Terminal, change to the folder to which you unzipped the server, and run the following command:

xattr -dr com.apple.quarantine beeblink-server bindings.node prebuilds/darwin-x64+arm64/node.napi.node

Linux

Follow the build instructions to build the server.

You can build the ROM yourself, or get a prebuilt copy from the Windows or macOS release: https://github.com/tom-seddon/beeblink/releases/latest (you can use either; they are equivalent, though not currently bit-identical)

Setting up the Beeb

You'll need a BBC B/B+/Master 128, ideally with some kind of EEPROM module or battery-backed write-protectable sideways RAM - it's no fun having to reload the ROM each time you power on, or have it zapped by careless programs!

(If upgrading: you're advised to run the same version of ROM and server, though the server does try to support older ROMs at least well enough to allow *CAT and RTOOL to work. Newer ROM + older server on the other hand is not supported.)

You can connect BBC and PC using a Tube USB serial adapter or a UPURS cable.

Tube USB serial adapter

See https://stardot.org.uk/forums/viewtopic.php?f=8&t=14849. You'll need the full kit with the PLD.

Connect the Tube serial board to the BBC's Tube connector, connect any second processor to the Tube serial board, use the jumper to select Comms mode, and connect the device to your PC.

If using Windows, you'll need to tweak one of the device settings.

If you've got some way of getting files to your BBC already, copy the appropriate ROM image from the zip and load it on your BBC; otherwise, use the bootstrap process, and get the file that way.

UPURS cable

See https://www.retro-kit.co.uk/UPURS/. You'll also need a FTDI FT232 USB serial adapter. Connect UPURS cable to BBC's user port connector and USB serial adapter, connect USB serial adapter to PC.

If using Windows, you'll need to tweak one of the device settings.

If using macOS 10.15 Catalina, you'll need to install the FTDI virtual COM port driver. UPURS BeebLink does not currently work on macOS 11 Big Sur - apologies.

There's no bootstrap process for the UPURS cable. Use the UPURS tools to get beeblink_upurs_fe60.rom copied onto your BBC.

There are some notes about using BeebLink with the UPURS cable.

Setting up the Electron (experimental!)

Electron support is experimental! DIY required

You'll need an Electron with Plus 1 (or equivalent - I'm uing an Acorn Plus 1) and Advanced Plus 5 (or equivalent - I'm using the Retro Hardware New AP5).

You'll need a Tube USB serial adapter (see above). The PLD needs reprogramming with the .jed file here: https://gist.github.com/tom-seddon/07d9f2942590899044a161edd5fe891a, and please also note the instructions there. (The reprogrammed PLD will be fully compatible with BBC B, B+ and Master as well.)

Once set up, Connect the Tube serial board to the AP5's Tube connector, use the jumper to select Comms mode, and connect the device to your PC.

If using Windows, you'll need to tweak one of the device settings.

There's not currently a bootstrap process for the Electron. I used my Master to get the appropriate ROM image onto a cartridge, then plugged the cartridge into the Electron.

Electron support is experimental! DIY required

Use

See the filing system docs for some info about how to use it.

The server docs have some additional information about useful command line options, and a few notes about sharing files between BBC and PC.

If you also use TubeHost, you can access your TubeHost files via BeebLink.

If you use git, some notes on git interop.

Building it yourself

This repo has submodules. Clone it with --recursive:

git clone --recursive https://github.com/tom-seddon/beeblink/

Or, after cloning, use git submodule from inside the working copy to set the submodules up:

git submodule init
git submodule update

master is the branch used to build the latest release, so it should be good. wip/tom is for whatever I'm working on currently, and will probably work pretty well. Other branches are undocumented and probably only temporary.

After switching branch, you'll need to do a git submodule update.

How to build the server.

How to build the ROM.

Problems?

Please file a GitHub issue or post in the StarDot BeebLink thread if you run into any difficulties!

Licence

Copyright (C) 2018-2023 by Tom Seddon

Licence: GPL v3

---

Build status:

Pre-release build status:

beeblink's Issues

Stunt Car Racer save game error

Save game fails, even though it should succeed. Suspect this is OSFILE returning a non-zero value in A.

Go through that stardot thread and figure out what's the FS is actually supposed to do here.

Files are never removed from .gitattributes

Probably not a big deal in practice, but it's a bit rubbish that it doesn't...

The check for non-existent files has to be careful not to remove anything added by hand.

• Ignore anything with wildcards or path separators? BeebLink never adds those
• Tag BeebLink entries with a comment (on the same line? Can you do that?) so it's unambiguous?
• Simply mandate that BeebLink owns the .gitattributes file in a drive's folder, and such files are not hand-editable?

*.0 doesn't cat drive 0

Gives Bad dir error. Probably an artefact of fiddling around with this stuff with an ADFS-type filing system in mind...

Configurable UPURS receive buffer size

The UPURS receive routine receives up to 70 bytes at a time. So during transfers the system sits with IRQs disabled for at least 6 ms at a time.

Would be nice if you could tweak this value, trading throughput for more time spent with IRQs enabled.

This has to be done on the Beeb end, of course. There's not many config bits left, so there might just have to be two modes for this.

Don't do `*SPEEDTEST` timing on the BBC itself

Get the server to do it. Checking TIME is no good for links that need IRQs disabling for long periods.

This would have simplified some of the Tube Serial code, too (though there's probably no point fixing it now).

*RENAME doesn't update gitattributes?

100% CPU after unplugging FTDI device

Seems pretty reliably the case on OS X... would be nice if there was some Tube serial hot-plug support.

*BLSELFUPDATE writes to $FE34 on Electron

It probably shouldn't! Fix this as part of the Electron pass.

(Though according to http://mdfs.net/Docs/Comp/Electron/Techinfo.htm, $FEx4 is the tape data shift register, so it's probably benign...)

Master 128 LIBFS

The Master 128 has this LIBFS thing, that I've never, ever used...

Invalid .inf

If the .inf file is invalid, is this situation equivalent to no .inf file at all? Should the BBC see the file?

*VOL is a bit slow

Not ideal for *VOL. Actively a bit annoying with the ::VOLUME:FILE syntax.

Maintain mapping of volume names to paths.

Use the mapping for non-ambiguous volume names. If key not found, rebuild and try again; if path not found, rebuild and produce error.

Rebuild mapping for *VOLBROWSER, *VOLS or ambiguous volume names.

Over-general ZP usage

A lot of the ROM routines use the zp,x addressing mode, so that the parameters can be placed anywhere. Now that things have settled down (and print_server_string, send_response_n and recv_response are never called with FS inactive...) the locations can probably mostly be made fixed.

*LIST, *TYPE, *DUMP

Treat them as ordinary FS commands via OSFSC, and do them on the server. Doesn't matter on the Master; if there's a DFS, it probably provides them; if BLFS is the only FS, they probably won't be missed much with tape or ROM filing systems.

Get rid of act as DFS mode?

The *DISC options are handy, but I've yet to find a need for act-as-DFS mode.

Remove it?

Write protect ABR

Every now and again the ABR seems to start up write-enabled, or become somehow write-enabled.

It would be good if the ROM could auto-write-protect itself, ideally as often as possible (e.g., every service call...), to protect against this.

Probably just have this as a build-time option.

Ugly Challenger nonsense

From the manual:

when using Opus DDOS/Challenger, do a *CAT of the disk before embarking on a *READ/*WRITE, so that the Opus FS can auto-detect the density. You may get spurious disk fault errors otherwise

Yuck!

Should do this automatically (somehow).

Latency timer probably isn't reset when re-opening device

Feels like *TYPE and *DUMP become predictably slow!

Sample output after sleeping laptop:

Found 1523/1524 writeable git-controlled volumes.
HTTP server listening on 127.0.0.1, port 48875
Setting FTDI latency timer for /dev/tty.usbserial-FT4AHAA3 to 1ms.
/dev/tty.usbserial-FT4AHAA3: serving. (verbose=false, data-verbose=(in: false, out: false), sync-verbose=false)
Setting FTDI latency timer for /dev/tty.usbserial-A97DYC34 to 1ms.
/dev/tty.usbserial-A97DYC34: serving. (verbose=false, data-verbose=(in: false, out: false), sync-verbose=false)
Finished scanning for BASIC files.
/dev/tty.usbserial-FT4AHAA3: connection closed due to error: Error: ENXIO: no such device or address, read
/dev/tty.usbserial-A97DYC34: connection closed due to error: Error: ENXIO: no such device or address, read
/dev/tty.usbserial-A97DYC34: serving. (verbose=false, data-verbose=(in: false, out: false), sync-verbose=false)
/dev/tty.usbserial-FT4AHAA3: serving. (verbose=false, data-verbose=(in: false, out: false), sync-verbose=false)

Shouldn't it do the latency timers again?!

Add Pro Micro /dev wildcard to makefile

It is supposed to be there already! - but maybe I forgot to commit from Linux...

*MOVE from BLFS to ADFS doesn't work

Files come out the right size, but the contents are junk.

Linux build stuff

• fix ctags-exuberant/exuberant-ctags
• figure out exact list of apt-get dependencies. So far: avrdude, gcc-avr, avr-libc, libusb-dev, libudev-dev

ROM version string

ROM version string should include git commit info as well as build time and date. Make it do whatever it is the CI build process to get this stuff - and I think this might add a -dirty suffix as well, when appropriate?

The version string is going to become enormous, so the ROM will probably need a *BLVERSION UTILS command, or new HELP entry, or something.

Magic Mushrooms "Channel" error

http://www.bbcmicro.co.uk/game.php?id=2487

Craps out if extracted to a folder with extract_ssd.

SSD written to floppy disc runs fine on DFS.

*WRITE zero page

*WRITE seems to work and everything, on the Master at least, but:

                ; restore DFS/ADFS workspace.
                ldy #31
-
                lda (write_image_temp),y
                sta $b0,y       ;abs,y
                dey
                bpl -

write_image_temp is $b2, or thereabouts! - so how does this even work, and do I actually even want to know the answer anyway?

(Save (write_image_temp) on the stack? Only save/restore $c0...$cf? - etc., etc.)

Pro Micro/serial output issue

1. Use Pro Micro board
2. Run server with --avr-verbose
3. Run *SPEEDTEST on the BBC

Result: board soon does a reset, then restarts in a non-functional state that requires a manual reset to fix. BBC of course then gets stuck.

The issue seems to be the _delay_us calls in serial_ch...

Adding more USB_USBTask calls makes no difference. Watchdog timer appears to be disabled correctly.

Use current settings with ::

DFS uses current dir when drive (but no dir) is specified as part of the name, so maybe BLFS should do that too?

Reusing the current drive seems a step too far - but maybe it would be OK?

Check bootstrap process

Failure report from here: https://stardot.org.uk/forums/viewtopic.php?f=53&t=15605&start=30#p236714

(Perhaps there's something better that could be done about the bootstrapping anyway? The current stuff isn't pointless, but it would be nicer if it were a 2-3 line program that was just a FOR loop that could read N bytes from the serial port, then just cat/TYPE something to the COM port on the PC...)

*SHUT

Should handle ROM reason code $26.

Master manual:

NAUG:

Slow transfer mode

Tube Serial transfer is super fast - sometimes too fast. Needs an option to slow it down. You might use this for debugging.

`Locked` in .inf should mean locked

Currently the server only handles L or l, but Locked appears to be valid.

As produced by https://github.com/sweharris/MMB_Utils/blob/14c1dd9a93c210af778d4e791f3b6d03d6ae03bc/BeebUtils.pm#L899

Files with 0-byte .inf

Make lack of metadata obvious from the *INFO (etc.) output?

At least, have something like ADFS error $93 Won't (which ADFS raises when you try to *RUN a file with a load address of $ffffffff).

Printing large strings with UPURS

e.g., *DUMP or *VOLS (with lots of volumes).

The Beeb has a tendency to get stuck.

Press BREAK and all seems well again.

BeverlyHillsCop doesn't work

Bad response after the Tynesoft splash screen.

BLFS then stops working, but a Ctrl+Break fixes it.

*WRITE syntax

*WRITE syntax BRK is missing its last char. Truncated because it's too long, presumably?

Is the size too conservative?

Could get more chars by starting right at $100... think DFS/ADFS do this, so what could possibly go wrong? Check this.

*BUILD

Treat as an FS command via OSFSC - same rationale as for the other ones. Then it can claim the NMI area and use that as the input buffer.

Doubt this would work on the Master (e.g., *BUILD -DISC-!BOOT...), so lucky the Master's MOS has *BUILD built in.

Update copyright dates as appropriate

FSTEST fails with ReCoMini6502

Typically gets stuck in the OSFILE update test. Looks like it receives the first page of data, and then gets stuck, presumably waiting for the status byte.

I'm sure this used to work?!

Bisect time...

Manage .gitattributes

It would be nice if the server could set up a suitable .gitattributes in the volume folders - one that treats everything as binary - so git doesn't start treating BBC files as text.

It could also detect and tag BBC BASIC programs, for when using BBCBasicToText as a git diff driver.

Reduce AVR logging

The serial logging isn't free (115,200 baud = ~1ms per ~12 chars?) so it might be useful to disable it.

Toggling this at runtime with a USB control transfer (controlled by a server command line option) should be fine.

Volumes with no drives

If you use OS X Finder to unzip a ZIP file that's just got inf files in the root, you get a folder with those files in. Would be nice to be able to use that folder as a volume as-is.

Treat those are the files in that volume, and have them appear as the files for all possible drives? Add them to the list of files for drive 0 files, if there is a drive 0?

e.g., https://www.stairwaytohell.com/electron/dfs/SAF/Aardvark-Frak-elk-SAF.zip

Prefix for * commands

Add an optional command prefix, so you can issue * commands that would otherwise get stolen by a higher-priority ROM?

T1 PB7 stuff

Regarding

beeblink/rom/beeblink.s65

Line 1854 in 0788f28

; Also disable T1-controlled PB7 output (which makes a

- it turns out that you can read the T1 PB7 output via IRB (see, e.g., https://stardot.org.uk/forums/viewtopic.php?f=4&t=16081&p=221576#p221333), as used by at least Snapper-V1 and Planetoid.

So maybe it's not just a simple error, and Superman and Beverly Hills Cop could in fact be using it for something...

Either way, it's probably actually worth restoring the old settings.

(This then means that prepare_via has to store the old value somewhere, and via_deactivate has to restore it. While booking zero page for this, sort out #3. Also, fix up the wayward naming, and make sure via_deactivate is called from everywhere necessary...)

Remove LUFA submodule

Remove AVR handling code from server

It's currently needed for the b2 support, but that could be fixed, one way or another...

Model B Elite problems

If you have a DFS installed as well as BeebLink, Acornsoft Elite (http://www.stairwaytohell.com/bbc/archive/diskimages/Acornsoft/Elite.zip) needs a disk present in drive 0.

It does an OSWORD $7f when switching from docked to flight:

4281 : 8D 94 42 : STA 4294       : 4 : A=4B X=0A Y=00 SP=CC N=0 V=0 D=0 I=0 Z=0 C=0
4284 : 20 7A 0D : JSR 0D7A       : 6 : A=4B X=0A Y=00 SP=CA N=0 V=0 D=0 I=0 Z=0 C=0
0D7A : CE 9A 0D : DEC 0D9A       : 6 : A=4B X=0A Y=00 SP=CA N=0 V=0 D=0 I=0 Z=1 C=0
0D7D : CE 94 0D : DEC 0D94       : 6 : A=4B X=0A Y=00 SP=CA N=0 V=0 D=0 I=0 Z=0 C=0
0D80 : 20 89 0D : JSR 0D89       : 6 : A=4B X=0A Y=00 SP=C8 N=0 V=0 D=0 I=0 Z=0 C=0
0D89 : A9 7F    : LDA #7F        : 2 : A=7F X=0A Y=00 SP=C8 N=0 V=0 D=0 I=0 Z=0 C=0
0D8B : A2 92    : LDX #92        : 2 : A=7F X=92 Y=00 SP=C8 N=1 V=0 D=0 I=0 Z=0 C=0
0D8D : A0 0D    : LDY #0D        : 2 : A=7F X=92 Y=0D SP=C8 N=0 V=0 D=0 I=0 Z=0 C=0
0D8F : 4C F1 FF : JMP FFF1       : 3 : A=7F X=92 Y=0D SP=C8 N=0 V=0 D=0 I=0 Z=0 C=0

Not sure what can be done about this!

There may be other issues too...

10-character file name limit

The BLFS file name limit is 10 characters, because why not? (10 was chosen because it's the limit for CFS, RFS and ADFS.) But is this going to cause a significant problem with anything?

File name wild cards

When loading a file with OSFILE 255, or opening one with OSFIND for read only, it would be useful to be able to use wildcards when the result would be unambiguous.

As with the :: volume syntax, a Bad name error (with a more meaningful message) would be raised if the name matches more than one file.

Multiple firmware versions

#11 means there'd be multiple versions of the ROM. Fix up build process to support this.

Should also do this for the firmware as well. In principle:

• set the output name to beeblink-$(BOARD) in the Makefile
• derive pin assignments (etc.) from whatever the #define equivalent of $(BOARD) is
• fiddle around until the Makefile builds for all known boards each time (wich shouldn't be a bother... the compilation is pretty quick. The slow part is always dfu-programmer)

*DRIVES

List drives in current volume. Show title and boot option for each.

FFFFFFFF...

If the protocol goes wrong during development, the end result is usually that the AVR and the BBC end up with conflicting DDR settings. Eventually the AVR starts reading again, and reads nothing but FFs, which it dutifully passes on. The server then dies because it tries to create a buffer of -1 bytes. It can surely do better than this.

OSWORD $7f-a-like

To support development of stuff like, e.g., https://github.com/kieranhj/stnicc-beeb, there ought to be a way to get an OSWORD $7f-like sector access API that can somehow access sector data from a .ssd image. Then you can use BeebLink to test code that uses this API.

Handle OSWORD $7f? Then existing software can make use of this, unmodified.

Also handle OSWORD $6f (or whatever), treating it exactly the same way, so that it's easy to test on the Master, where the DFS in a higher-priority socket. You need a separate build of your program, or use OSARGS to check for BeebLink specifically - probably OK for testing.

To decide which .ssd file to access: look in volume folder, find .ssd there, and use that. Multiple .ssd files there, or no .ssd files = disc fault, or maybe a brk. That ought to be convenient enough for testing. Maybe some mechanism like .volume or whatever if you really must have multiple .ssd files.

For bonus points, a .dsd file in drive 0 (say) would cover both drive 0 and drive 2. Don't forget to check there's no .ssd file in drive 2...

Workflow is then:

1. build code
2. put Beeb files + .inf files in BeebLink volume, so they can be tested with Shift+Break
3. create .ssd file for distribution
4. copy .ssd file to BeebLink volume

So, changes to an existing build process should be minimal. Steps 1-3 will be part of any build process, and step 4 is just a single copy/cp.