The Definition of Done - FujiNetWIFI/fujinet-firmware GitHub Wiki

Or, as my friend Joe Decuir says, "Shoot the engineer; ship the product."

FujiNet can do a lot, and it is very tempting to just keep working on a bring-up until it is perfect. Please don't do this. You'll never get it done. So what IS done?

Simply put, if the things most users use work without crashing, it's ready to release.

This is why it is important to understand as part of a bring-up, what can actually be brought to the system. For the Atari, the core feature set was solidified to:

(in order of usage)

  • The FujiNet Device
  • Disk Drives (D:)
  • Printer (P:)
  • Modem (R:)
  • Network (N:)

That's it. To elaborate further, we can drill into each of these:

The base protocols

The base protocol needs to be determined, and laid out for each bring-up. The purpose here is to map each of the devices mentioned below, and to map the commands they need into something that can be implemented on the target system. The goal here is to implement something that makes sense, and can leverage existing operating system routines.

For the Atari, this is the SIO protocol, which provides:

  • 255 possible device IDs
  • 255 possible command IDs
  • Two 8-bit (or one 16-bit) parameter values
  • Half duplex operation, with the ability to specify payload direction

Each of the devices on the Atari are designed with this in mind.

For the Commodore 64 and family, this is IEC:

IEC is a serial implementation of the IEEE-488 standard

  • All participants are daisy-chained
  • One dedicated controller (the computer) does bus arbitration of up to 31 devices
  • One-to-many: Any participant can send data to any set of participants
  • A device has multiple channels for different functions
  • Data transmission is byte stream-based

* info was taken from PageTable's Bus Overview

For the ADAM this is ADAMNet:

  • Token based, message passing network
  • One node assumes control of the network and passes tokens
  • 15 possible device types
  • Speed of 62.5k
  • Six message types

For the Apple II there are two protocols:

  • SmartPort
  • Disk II

Of those, only SmartPort is able to emulate more than just a disk device. Not every Apple II has a SmartPort chip however (see Apple II & III FujiNet Quickstart Guide.

The FujiNet Device

This, may or may not be directly exposed to the target operating system. The purpose of this device is to provide the support commands required by the CONFIG program, so that disks can be mounted by the Disk drive. On the Atari, this is implemented as SIO device 0x70.

While you can omit commands that aren't available or don't make sense on a given target, for the Atari, you can reference this page: SIO Commands for Device ID $70

Disk Drives (D:)

The purpose of the disk drive emulation is simple, to allow the computer to load software from either local or network storage. This means:

  • Implementing the most common media types, in the Atari's case, this was .ATR, .ATX, and .XEX
  • Reading from those media types
  • Writing to those media types
  • Creating new media images

Since the Atari disk interface deals with fixed sectors, the disk implementation is built around this. It doesn't have to be. Do what makes the most sense to users.

You can see the commands implemented for the disk drive here: https://github.com/FujiNetWIFI/fujinet-platformio/blob/master/lib/device/sio/disk.cpp

Printer (P:)

The printer's only concern is to funnel character data into the printer-emulator code, so that a PDF can be rendered using one of the built-in printers. Ultimately, this involves getting a pointer to the printer emulator and using its process() method to send printer data to it.

  • Implement the appropriate write command. Really, that's it.

Modem (R:)

Because the most common MODEM connection on the Atari was the Atari 850 RS232 interface, we implemented the commands needed to:

  • Initialize the interface (sending over the handler when asked)
  • Set line parameters
  • Enable/disable the modem
  • Process modem commands vs online mode
  • Hook up the modem sniffer
  • Be able to connect to a host using modem and interact with it.

Any additional code that you need to integrate the modem into the system needs to be addressed, the goal is to be able to use the modem with the most common terminal programs (for the Atari, this meant testing with BobTerm, ICE-T, AMODEM, and 850 Express!)

Some systems may not expose a usable way to provide the modem. If not, you can delete the modem.

Network (N:)

The network device is, next to the Fuji device, the most complex device in the system, due to how it needs to dynamically instantiate protocols and handle commands for them. As such, there are more requirements:

It really helps to take an existing network.cpp that's closest to your system, and hollow out each function, implementing one at a time: https://github.com/FujiNetWIFI/fujinet-platformio/blob/master/lib/device/sio/network.cpp

Do not stay working in a corner!

Please, don't work for months off in a corner! FujiNet moves fast, and the code base is constantly being added to. The longer you wait to merge things back in, the harder it will be for you to successfully complete a merge.

So please, once you know your bus strategy will work, bring it into master!

Some final words

Again, it doesn't have to be perfect. We're not writing avionics software, we're making a fun network interface for our humble microcomputers. Focus on the features that users will use, in this order:

  • Disk
  • Printer
  • Modem (and/or)
  • Network

and get the Fuji device up enough so that CONFIG will work.

This will ensure that we can get systems brought-up and not get caught in the never ending spiral of trying to make something perfect, before we release it.

And remember, we're all here to help each other, so don't be afraid to ask dumb questions.

-Thom