Programming the FujiNet N: Device: TCP, HTTP, JSON and SIO from BASIC and Assembly

FujiNet's N: device gives an Atari program a network connection through the same OPEN, GET, PUT, STATUS and XIO statements it already uses for disks and printers. The FujiNet Setup Guide shows how to load the NDEV handler, what an N: devicespec looks like, and how to RUN a BASIC program from a web server. This guide is for writing your own network programs: the AUX bytes, reading status, TCP clients and servers, HTTP beyond a simple GET, the built-in JSON parser, and talking to the FujiNet directly over SIO with an interrupt telling you when data has arrived.

What you'll learn: how CIO calls map onto FujiNet SIO commands, how to read DVSTAT, TCP and HTTP patterns that work, JSON queries from BASIC, and the machine-language interface.

What you need: a FujiNet (or FujiNet-PC with Altirra), Atari BASIC with NDEV.COM loaded (it prints FUJINET READY), and MADS for the assembly example.

1. How the N: handler talks to FujiNet

NDEV is a thin CIO handler. Each CIO request becomes an SIO command to device $71, with the unit number in DUNIT. OPEN becomes 'O' ($4F) with your devicespec in a 256-byte buffer. GET and INPUT become 'R' (read), PUT and PRINT become 'W' (write), STATUS becomes 'S', and CLOSE becomes 'C'. Any XIO number the handler doesn't handle itself is passed through as the SIO command byte, with the XIO's two AUX values as DAUX1 and DAUX2. That's why the XIO numbers below are simply ASCII letters or command codes:

XIO SIO command Use
13 'S' Status into DVSTAT (AUX1 selects what)
15 handled locally Flush the write buffer now
44 $2C Set the directory prefix
65 'A' Accept a waiting TCP client
77 'M' HTTP channel mode
80 / 81 'P' / 'Q' Parse JSON / query JSON
90 'Z' Set the PROCEED interrupt interval (ms)
99 'c' Close an accepted client, keep listening
251 / 252 $FB / $FC JSON parameters / channel mode

For commands it doesn't recognise, the handler first asks FujiNet with command $FF which direction the data goes, so new protocol features work without a new handler.

2. OPEN: what AUX1 and AUX2 mean

AUX1 is the usual direction: 4 read, 8 write, 12 read/write. HTTP gives it extra meanings: 4 GET, 6 PROPFIND (a WebDAV directory listing), 8 PUT, 12 GET with header access, 13 POST.

AUX2 controls end-of-line translation, because the Atari uses EOL (155) where the Internet uses CR (13) and LF (10):

AUX2 Incoming Outgoing EOL becomes
0 no translation EOL
1 CR → EOL CR
2 LF → EOL LF (best for Unix servers and JSON APIs)
3 CR/LF → space/EOL CR/LF (Telnet, most text protocols)

AUX2 bit 7 (128) asks for long filenames in directory listings.

For a TCP server, leave out the host: N:TCP://:6502/ listens on port 6502. A UDP devicespec ends in two slashes (N:UDP://host:port//). For UDP, the sender of the last received packet becomes the destination for replies. There's a limit of four simultaneous TCP connections.

3. STATUS and DVSTAT

STATUS #1,ST puts the result code in ST and fills the four DVSTAT bytes at 746–749:

Address Meaning
746, 747 Bytes waiting to be read (low, high)
748 1 = connected, 0 = disconnected (on a listening socket: a client is waiting)
749 Extended error code

XIO 13,#1,n,0,"N:" with n = 1–5 returns the external IP, local IP, gateway, netmask or DNS server as four bytes in 746–749.

Two rules follow from how SIO works. First, a read must not ask for more bytes than are waiting, so check the count before a block read. Second, GET and INPUT block until data arrives. That's handy for keeping two players in step, but deadly in a game loop. PRINT and PUT are buffered: a PRINT ending in EOL is sent at once, but anything else waits until you flush with XIO 15,#1,12,0,"N:".

4. A TCP client

This line-oriented client connects to host:port, prints whatever arrives and sends a line whenever you start typing:

10 REM N: TCP LINE CLIENT
20 DIM H$(80),U$(100),L$(120)
30 PRINT "HOST:PORT";:INPUT H$
40 U$="N:TCP://":U$(LEN(U$)+1)=H$:U$(LEN(U$)+1)="/"
50 TRAP 300:OPEN #1,12,3,U$
60 STATUS #1,ST:BW=PEEK(746)+256*PEEK(747)
70 IF PEEK(748)=0 THEN 300
80 IF BW=0 THEN 110
90 FOR I=1 TO BW:GET #1,C:PRINT CHR$(C);:NEXT I
110 IF PEEK(764)=255 THEN 60
120 INPUT L$:PRINT #1;L$
130 GOTO 60
300 PRINT "CLOSED, ERROR ";PEEK(195):CLOSE #1

Translation mode 3 turns the server's CR/LF into EOL and sends your EOL as CR/LF. Line 90 reads only the bytes that STATUS reported, so it never blocks. Line 110 checks CH (764) for a keypress before committing to INPUT.

For a server, open N:TCP://:6502/ with AUX1 12, wait until PEEK(748) becomes 1, then XIO 65,#1,12,0,"N:" to accept the client. FujiNet's Reversi and Light Cycles BASIC examples work exactly this way, sending moves as PRINT #2;X;",";Y;",";TRIG and reading them with INPUT #2,X,Y,TRIG. XIO 99 drops the current client but keeps listening.

5. HTTP beyond GET

Open with AUX1 12 (or 13 for POST), then switch the channel between modes with XIO 77. The second AUX value picks the mode:

XIO 77,#1,12,3,"N:":REM SET HEADERS: EACH PRINT SENDS "Key: Value"
XIO 77,#1,12,1,"N:":REM COLLECT HEADERS: PRINT THE NAMES YOU WANT BACK
XIO 77,#1,12,2,"N:":REM GET HEADERS: PERFORMS THE REQUEST, INPUT READS THEM
XIO 77,#1,12,0,"N:":REM BODY: INPUT READS THE BODY
XIO 77,#1,13,4,"N:":REM POST DATA: PRINT WRITES THE REQUEST BODY

The request is only sent when you first read in GET HEADERS or BODY mode. A header line needs exactly one space after the colon. With PUT (AUX1 8) everything you write is buffered and sent when you CLOSE, so check for an error on the CLOSE itself.

For JSON POSTs from Atari BASIC, five rules matter:

  1. Open with AUX2 = 2, so EOLs become LFs.
  2. Build { and } with CHR$(123) and CHR$(125). Atari keyboards have no braces, and 125 is the clear-screen code. Setting DSPFLG with POKE 766,1 while printing them shows them instead of clearing the screen.
  3. End the PRINT #1;BODY$; with a semicolon so no stray EOL is sent.
  4. Flush with XIO 15.
  5. Switch to body mode (XIO 77,#1,…,0) and INPUT the response.

6. The JSON parser

FujiNet can download a JSON document, parse it in its own memory, and hand you individual values. That spares the Atari from parsing text at all:

10 REM FETCH AND QUERY A JSON DOCUMENT
20 DIM R$(120),Q$(40)
30 TRAP 200
40 OPEN #1,12,3,"N:HTTPS://jsonplaceholder.typicode.com/users/1"
50 XIO 252,#1,12,1,"N:":REM JSON CHANNEL MODE
60 XIO 80,#1,12,0,"N:":REM PARSE THE BODY
70 FOR I=1 TO 3:READ Q$
80 XIO 81,#1,12,0,Q$:REM QUERY ONE VALUE
90 INPUT #1,R$:PRINT Q$(4);": ";R$
100 NEXT I
110 CLOSE #1:END
120 DATA N:/name,N:/email,N:/address/city
200 PRINT "ERROR ";PEEK(195):CLOSE #1

Queries are paths starting with /, written as a devicespec (N:/address/city). Each answer is read like a line of text. XIO 251,#1,1,10,"N:" changes the line ending the parser puts after each value (here LF). For large answers, read with a GET loop rather than INPUT, to avoid error 137 (truncated record).

7. Talking SIO directly

From machine code or C you can skip NDEV and fill the device control block (DDEVIC at $0300) yourself:

Command DCOMND DSTATS Buffer / length DAUX1 / DAUX2
Open 'O' $4F $80 256-byte devicespec mode / translation
Status 'S' $53 $40 DVSTAT, 4 bytes 0
Read 'R' $52 $40 buffer, n bytes n (low/high)
Write 'W' $57 $80 buffer, n bytes n (low/high)
Close 'C' $43 $00 none (flush first) 0

If an operation fails, SIO returns 144 (device error), and the real reason is in DVSTAT+3 after a Status command. Common codes: 138 timeout, 165 bad devicespec, 170 not found, 200 connection refused, 201 network unreachable, 202 connection timed out, 204 connection reset, 207 not connected.

8. Letting FujiNet interrupt you

Polling Status every frame wastes SIO time. FujiNet is wired to the SIO PROCEED line and asserts it to say it has something for you, repeating at an interval of 100 ms by default. You can change the interval with command 'Z' (XIO 90,#1,20,0,"N:" sets 20 ms). PROCEED reaches the CPU as a PIA interrupt. Bit 0 of PACTL (54018, $D302) enables it, and the OS jumps through VPRCED (514–515, $0202). The OS IRQ code has already pushed A and read PORTA to clear the interrupt flag, so a handler only has to set a flag and finish with PLA/RTI:

; FujiNet N: polling driven by the SIO PROCEED interrupt (MADS)
VPRCED  = $0202         ; proceed-line IRQ vector
DVSTAT  = $02EA         ; 4-byte status buffer
DDEVIC  = $0300         ; start of the 12-byte device control block
SIOV    = $E459
PACTL   = $D302         ; PIA port A control, bit 0 = proceed IRQ enable

        org $2000

; --- install the handler ---------------------------------------
install lda PACTL
        and #$FE        ; mask the proceed IRQ while we change the vector
        sta PACTL
        lda #<proceed
        sta VPRCED
        lda #>proceed
        sta VPRCED+1
        lda #0
        sta trip
        lda PACTL
        ora #1          ; enable it again
        sta PACTL
        rts

; --- the handler: the OS has pushed A and cleared the PIA flag ---
proceed lda #1
        sta trip        ; "FujiNet has something for us"
        lda PACTL
        and #$FE        ; no more proceed IRQs until we have serviced it
        sta PACTL
        pla
        rti

; --- call this from your main loop ----------------------------------
poll    lda trip
        beq done        ; nothing new: no SIO traffic at all
        ldx #11
copys   lda statdcb,x   ; 'S' status: bytes waiting -> DVSTAT
        sta DDEVIC,x
        dex
        bpl copys
        jsr SIOV
        lda DVSTAT+1
        bne cap         ; 256 or more waiting: take 255 this time
        lda DVSTAT
        beq ack         ; nothing waiting after all
        bne setlen
cap     lda #255
setlen  sta readdcb+8   ; DBYT low
        sta readdcb+10  ; DAUX1 = byte count as well
        ldx #11
copyr   lda readdcb,x   ; 'R' read the waiting bytes into BUF
        sta DDEVIC,x
        dex
        bpl copyr
        jsr SIOV
ack     lda #0
        sta trip
        lda PACTL
        ora #1          ; re-arm the proceed interrupt
        sta PACTL
done    rts

statdcb dta $71,1,'S',$40,a(DVSTAT),$0F,0,a(4),0,0
readdcb dta $71,1,'R',$40,a(buf),$0F,0,a(0),0,0
trip    dta 0
buf     .ds 256

Open the connection first, with CIO or an 'O' SIO call, then JSR install and call poll once per pass of your main loop. Before your program exits, put the original vector back (VPRCED normally points at a PLA/RTI pair at $E7B2) and clear PACTL bit 0. The FujiNet netcat examples in C and assembly use the same scheme.

Troubleshooting

  • ERROR 130 on OPEN: NDEV isn't loaded. ERROR 138: FujiNet didn't answer at all.
  • ERROR 144: look at PEEK(749) after a STATUS for the real code (165 bad devicespec, 170 unknown host or file, 200–207 network problems).
  • Program freezes: an INPUT or GET with nothing waiting. Check PEEK(746) first, or loop on STATUS.
  • Server sees nothing until you press RETURN: your PRINT ended with ; or ,. Add XIO 15 to flush.
  • POST rejected: wrong translation (use AUX2 = 2), a stray EOL after the body, or the screen-clear character instead of }.
  • ERROR 137 on INPUT: the line is longer than your string. Use bigger strings or a GET loop.

Further reading

  • FujiNet wiki: Using the N: Device, N: Theory of Operation, HTTP Protocol, HTTP Set Channel Mode, Using HTTP/S from BASIC, Atari BASIC JSON POST Best Practices, N: Game Developer Cheat Sheet and A Simple NetCat Program.
  • The SIO command pages for devices $71–$78 on the same wiki, with C examples for cc65.
  • Mapping the Atari by Ian Chadwick: DVSTAT (746–749), VPRCED (514) and PACTL (54018).
  • Our guides FujiNet Setup Guide, FujiNet for Game Developers, SIO Explained and CIO and IOCBs: How Atari Input/Output Really Works.

Credits