FujiNet Documents NetSIO, Its Bridge Between Atari Emulators and a Virtual FujiNet

On 23 April 2025 the FujiNet project published FEP-003: NetSIO Protocol on its wiki, credited to Andrew Diller and Jan Krupa, with input from Mozzwald and TCH. It is a formal write-up of the protocol that lets an emulated Atari talk to a software FujiNet over the network, so you can use FujiNet features such as TNFS disk images, N: networking and the CONFIG program without the hardware.

What NetSIO is

NetSIO carries the Atari's SIO bus over UDP: both the data bytes and the control signals. Each message is a single UDP datagram that starts with a one-byte ID. Examples:

  • 0x01 / 0x02: a single data byte or a block of up to 512 bytes
  • 0x11 / 0x10: the SIO command line asserted or released
  • 0x21 / 0x20: cassette motor on/off. Proceed and Interrupt lines have their own messages.
  • 0x80: a baud-rate change, for high-speed SIO
  • 0xC1–0xC7: connection management (connect, ping, alive) and a credit system for flow control
  • 0xFE / 0xFF: the emulated Atari did a warm or cold reset

The trickiest part is timing. A real Atari expects a peripheral's ACK within 850 µs to 16 ms of the last byte of a write. NetSIO's sync request/response messages solve this: the emulator pauses the emulated Atari after sending the checksum byte and resumes it only when FujiNet's answer arrives, so network latency never shows up as an SIO timeout.

How it is wired today

The emulator side traditionally goes through a bridge. Altirra loads a custom device file, netsio.atdevice, which talks to the Python NetSIO hub (netsio-hub.py, from the fujinet-emulator-bridge project). The hub translates to NetSIO datagrams for FujiNet-PC, the desktop build of the firmware, on UDP port 9997. A companion wiki guide shows how to run two Altirra + FujiNet-PC pairs side by side on one computer (the second pair moved to ports 9986/9987), which is handy for testing networked multiplayer games. It also explains how to run Altirra under Wine on macOS or Linux, with fast boot turned off so the FujiNet CONFIG disk can load.

The FEP also lists direct NetSIO support in atari800, in two C89 forks of the emulator (dillera/atari800 and mozzwald/atari800), with no Python hub in between. Its notes describe hooking SIO_PutByte() and SIO_SwitchCommandFrame() and recommend running atari800 with SIO patch emulation turned off (-nopatchall), so that command frames go out over the wire rather than through the emulator's SIO shortcut.

Why it matters

A precise, published protocol means other emulator authors can add native FujiNet support, instead of everyone depending on the Python hub. It is also what makes the FujiNet virtual machine possible: a ready-made VirtualBox image with Altirra, FujiNet-PC and the NetSIO bridge already set up. With that, a developer can write and test FujiNet software, or someone can just try FujiNet, without buying anything.

Where to find it

FEP-003 and the Altirra set-up guide are on the FujiNet wiki (fujinet.online/wiki). The NetSIO hub and Altirra device file are in the FujiNet emulator-bridge and fujinet-pc-launcher releases on GitHub, and FujiNet-PC nightly builds are on the fujinet-firmware releases page.

Credits