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:
- Open with AUX2 = 2, so EOLs become LFs.
- Build
{and}withCHR$(123)andCHR$(125). Atari keyboards have no braces, and 125 is the clear-screen code. Setting DSPFLG withPOKE 766,1while printing them shows them instead of clearing the screen. - End the
PRINT #1;BODY$;with a semicolon so no stray EOL is sent. - Flush with
XIO 15. - 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:
NDEVisn'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,. AddXIO 15to 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–$78on 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
- FujiNet wiki — Using the N: Device — FujiNet project
- FujiNet wiki — N: Theory of Operation (DVSTAT layout, PROCEED/interrupt scheme) — FujiNet project
- FujiNet wiki — N-Device Open/Status/Close/Get Record/Put Record, N: AUX2 Values, Error Codes for N: Device — FujiNet project
- FujiNet wiki — SIO Commands for Device IDs $71 to $78; N: SIO commands 'O', 'S', 'R', 'W', 'C', 'A', 'c', 'T', 'Z', 'P', 'Q', $FB, $FC, $FF — FujiNet project
- FujiNet wiki — HTTP Protocol; HTTP Set Channel Mode — FujiNet project
- FujiNet wiki — Using HTTP/S from BASIC; Atari BASIC JSON POST Best Practices — FujiNet project
- FujiNet wiki — N: Game Developer Cheat Sheet; N: TCP Game Examples (Reversi, Light Cycles); A Simple NetCat Program — FujiNet project
- Atari 400/800 OS source listing Rev. A — IRQ dispatch for PROCEED (reads PORTA, JMP (VPRCED), SYIRQB PLA/RTI at $E7B2) — ksquiggle
- Mapping the Atari (revised) — 514 VPRCED, 54018 PACTL, 746-749 DVSTAT, 764 CH, 766 DSPFLG — AtariArchives.org
