Joystick Ports as I/O Lines: Programming the PIA from BASIC and Assembly
The four joystick direction pins on each controller jack are wired to the 6520 PIA (Peripheral Interface Adapter), and every one of them can be switched between input and output by software. That turns the jacks into a small parallel port: eight lines on an XL/XE, sixteen on a 400/800. Hobbyists have used them to drive relays, LEDs, printers and servos since 1982.
The hardware side (pinouts, buffers, relay boards) is covered in the Joystick-Port Interfacing entry in our hardware section. This guide is the software side: how to set the direction of each line, what you read back, what the operating system does to the port behind your back, how to work with single bits in Atari BASIC, and how fast you can toggle a pin from BASIC and from assembly.
What you need: Atari BASIC and, for the last section, MADS. The examples were run in atari800 in XL/XE mode, with a real Atari BASIC revision C ROM and the emulator's built-in AltirraOS (no Atari OS ROM was used). With nothing plugged in, the emulator could only show what the PIA reports, so everything below that involves real hardware is described from the sources, not tested.
1. The registers
| Register | Address | What it does |
|---|---|---|
| PORTA | 54016 / $D300 | jack 1 (bits 0–3) and jack 2 (bits 4–7): data, or direction |
| PORTB | 54017 / $D301 | jacks 3 and 4 on the 400/800. Memory control on XL/XE: leave alone |
| PACTL | 54018 / $D302 | port A control. Bit 2 chooses what PORTA means |
| PBCTL | 54019 / $D303 | port B control |
Each jack's pins 1 to 4 (up, down, left, right) are bits 0 to 3 of its nibble. Pin 6 is the trigger, pins 5 and 9 are the paddle inputs, pin 7 is +5 V and pin 8 is ground. Mapping the Atari gives the recommended load on the +5 V pin as one TTL load at 50 mA.
The PIA keeps two registers behind the one PORTA address: the data direction register (DDRA) and the data register itself. Bit 2 of PACTL chooses between them: 0 selects the direction register, 1 selects data. In the direction register, a 1 bit makes that line an output and a 0 bit makes it an input.
The other PACTL bits matter too. Bits 3–5 drive the cassette motor line (CA2), so the usual values are:
| PACTL value | Meaning |
|---|---|
| 60 ($3C) | data register selected, cassette motor off (the normal state) |
| 56 ($38) | direction register selected, motor off |
| 52 ($34) | data register selected, motor on |
So the recipe is always the same: POKE 54018,56, write the direction byte to 54016, POKE 54018,60. Get the 56 wrong and you may start the tape motor; forget the 60 and your "data" writes keep changing the direction.
2. A first test: outputs you can read back
This program makes jack 1's four lines outputs, leaves jack 2 as inputs, writes some values and reads them back three ways: PORTA itself, and the OS's joystick shadows STICK(0) and STICK(1).
10 REM JACK 1 (BITS 0-3) AS OUTPUTS
20 PACTL=54018:PORTA=54016
30 POKE PACTL,56:POKE PORTA,15:POKE PACTL,60
40 ? "OUT","PORTA","STICK(0)","STICK(1)"
50 FOR V=0 TO 15 STEP 3:POKE PORTA,V:N=3:GOSUB 1000
70 ? V,PEEK(PORTA),STICK(0),STICK(1)
80 NEXT V
90 POKE PACTL,56:? "DDRA=";PEEK(PORTA):POKE PACTL,60
100 POKE PORTA,15:? "HOLD STICK 0 UP..."
110 N=180:GOSUB 1000
120 ? "PORTA=";PEEK(PORTA);" STICK(0)=";STICK(0)
130 END
1000 REM WAIT N FRAMES
1010 FOR F=1 TO N:T=PEEK(20)
1020 IF PEEK(20)=T THEN 1020
1030 NEXT F:RETURN
The results (see the screenshot) show four things:
- PEEK(54016) returns all eight lines. Writing 3 read back as 243: the low nibble is our output, and the high nibble is jack 2's four inputs, all 1 because nothing is plugged in.
- The direction register can be read back. Selecting it again showed DDRA=15.
- STICK(0) follows your outputs. The OS's vertical blank routine copies PORTA into the STICK shadows every frame, whatever the direction of the lines. A program that both drives jack 1 and reads joystick 0 will get its own outputs back.
- An output can be pulled low from outside. With all four outputs set to 1, holding the (emulated) joystick up read back as 254: bit 0 was 0. The Altirra Hardware Reference Manual explains this: on port A, an output bit reads back as the logical AND of what the PIA drives and what the outside world is doing, while on port B an output always reads back as written. That makes port A's read-back a crude check that a line isn't being held low, but it also means you must never plug a joystick into a jack whose lines you are driving as outputs.
The wait loop in lines 1000–1030 counts changes of the frame counter at location 20. Comparing PEEK(20) with a starting value plus a number fails when the counter wraps from 255 to 0, a classic hang.
3. What the OS does to the port
Your program is not alone with the PIA:
- At power-up and on every RESET, the OS writes $38 to PACTL, 0 to the direction register (all inputs) and $3C to PACTL again. The 400/800 OS source does this in its interrupt-handler initialisation, which runs on warm starts as well as cold ones. In our test under AltirraOS, a direction of 15 was back to 0 after pressing RESET, and PACTL read 60. If your outputs must survive RESET, set them up again from your RESET handler (see The RESET Key).
- Every vertical blank, the OS reads PORTA (and PORTB on the 400/800) into STICK0–STICK3 and the paddle-trigger shadows. Reading the data register also clears the PIA's interrupt flags, which only matters if you use the PIA's interrupt lines.
- The cassette and SIO code write PACTL to switch the cassette motor, using $34 and $3C. Both keep bit 2 set, so the direction register isn't touched, but if you are halfway through changing the direction when an interrupt does I/O, things get confused. Do direction changes in one go, and avoid them during disk or cassette I/O.
- The paddle trigger shadows (PTRIG0–3) come from PORTA bits 2, 3, 6 and 7. Programs that read paddle buttons will see your outputs on those bits.
On XL and XE machines PORTB is not a joystick port. It switches the OS ROM, BASIC, the self-test and (on the 130XE) extended memory. Writing to it to "use jacks 3 and 4" will crash the machine.
4. Single bits in Atari BASIC
Atari BASIC has no bitwise AND or OR, so switching one line without disturbing the others needs a little arithmetic. Keep the current output value in a variable rather than reading it back from the port (which may have been pulled low from outside):
10 REM SET AND CLEAR SINGLE OUTPUT BITS
20 PACTL=54018:PORTA=54016:OUT=0
30 POKE PACTL,56:POKE PORTA,15:POKE PACTL,60
40 POKE PORTA,OUT
50 B=0:GOSUB 200:B=2:GOSUB 200:GOSUB 300
60 B=0:GOSUB 250:B=3:GOSUB 200:GOSUB 300
70 B=3:GOSUB 200:GOSUB 300
80 END
200 REM SET BIT B
210 GOSUB 350:IF INT(OUT/P)-2*INT(OUT/(2*P))=0 THEN OUT=OUT+P
220 POKE PORTA,OUT:RETURN
250 REM CLEAR BIT B
260 GOSUB 350:IF INT(OUT/P)-2*INT(OUT/(2*P))=1 THEN OUT=OUT-P
270 POKE PORTA,OUT:RETURN
300 ? "OUT=";OUT;" PINS=";PEEK(PORTA)-240:RETURN
350 P=1:IF B THEN FOR I=1 TO B:P=P+P:NEXT I
360 RETURN
It printed OUT=5 PINS=5 (bits 0 and 2 on), then OUT=12 PINS=12 (bit 0 off, bit 3 on), and setting bit 3 a second time left it at 12. Line 350 builds the power of two by doubling, which is exact, rather than using 2^B, which goes through the floating-point logarithm routines. BASIC XL, Turbo-BASIC XL and Altirra BASIC users can use their & and ! bitwise operators instead.
5. How fast? BASIC against assembly
A loop of POKE PORTA,1:POKE PORTA,0 gave 1,000 pulses in 253 frames, about 237 pulses a second on NTSC. Writing the address as a constant (POKE 54016,1) was slightly slower, 261 frames, because Atari BASIC converts a constant from its stored floating-point form every time. That is fine for relays and lamps, but too slow for anything clocked.
In assembly, a store to $D300 takes four cycles. The program below uses three lines of jack 1 as a synchronous serial port, the kind used by a 74HC595 shift register to drive eight LEDs from three wires: bit 0 is data, bit 1 is the clock (data is taken on its rising edge) and bit 2 is the latch, pulsed after each byte. It does two things:
- Sends a message with logging switched on. After every rising clock edge it reads the pins back, then rebuilds the bytes from the logged data bits and prints them. With nothing connected, this proves the pin sequence, not a real shift register.
- Sends 16,384 bytes without logging and times them.
; Bit-banged serial output on joystick port 1 (PORTA bits 0-2),
; e.g. for a 74HC595 shift register: bit 0 = data, bit 1 = clock,
; bit 2 = latch. The program checks itself by reading the pins back.
RTCLOK = $12
PORTA = $D300
PACTL = $D302
ICCOM = $0342
ICBLL = $0348
CIOV = $E456
PTR = $CB
DATA = %001
CLOCK = %010
LATCH = %100
org $3000
start lda #$38 ; select the data direction register
sta PACTL
lda #$0F ; bits 0-3 (jack 1) out, 4-7 (jack 2) in
sta PORTA
lda #$3C ; back to the data register
sta PACTL
lda #0 ; all outputs low
sta PORTA
lda #$80 ; 1. send a message, logging the pins
sta logon
ldx #0
m1 stx idx
lda msg,x
beq m2
jsr shiftout
ldx idx
inx
bne m1
m2 lda #0
sta logon
jsr say
dta c'READ BACK: ',0
ldx #0 ; rebuild each byte from the logged data
m3 stx idx ; bit at every rising clock edge
lda log,x
cmp #$FF
beq m5
ldy #8
m4 lda log,x
lsr ; data bit into carry
rol tmp
inx
dey
bne m4
stx idx
lda tmp
jsr putc
ldx idx
jmp m3
m5 jsr say ; 2. speed: 64 x 256 bytes, no logging
dta $9B,c'16384 BYTES IN ',0
jsr sync
lda #64
sta pages
ldx #0
s1 stx idx
txa
jsr shiftout
ldx idx
inx
bne s1
dec pages
bne s1
sec
lda RTCLOK+2
sbc t0
tax
lda RTCLOK+1
sbc t0+1
jsr dec5 ; X = low, A = high
jsr say
dta c' FRAMES',$9B,0
lda #$38 ; leave the port as inputs again
sta PACTL
lda #0
sta PORTA
lda #$3C
sta PACTL
jmp *
; ---- send A, most significant bit first, then pulse the latch ----
shiftout ldy #8
sta tmp
sh1 lda #0
asl tmp ; next bit into carry
rol ; ...and into bit 0 (DATA), clock low
sta PORTA
ora #CLOCK ; rising clock edge shifts the bit in
sta PORTA
bit logon
bpl sh2
jsr logpin
sh2 dey
bne sh1
lda #LATCH ; copy the shift register to its outputs
sta PORTA
lda #0
sta PORTA
rts
logpin lda PORTA ; what the pins actually show
and #$0F
ldx logp
sta log,x
inc logp
lda #$FF
sta log+1,x
rts
sync lda RTCLOK+2
sy0 cmp RTCLOK+2
beq sy0
lda RTCLOK+2
sta t0
lda RTCLOK+1
sta t0+1
rts
say pla ; print the string after the JSR
sta PTR
pla
sta PTR+1
sa1 inc PTR
bne sa2
inc PTR+1
sa2 ldy #0
lda (PTR),y
beq sa3
jsr putc
jmp sa1
sa3 lda PTR+1
pha
lda PTR
pha
rts
putc ldx #0
stx ICBLL
stx ICBLL+1
pha
lda #11
sta ICCOM
pla
jmp CIOV
dec5 stx num ; A = high, X = low
sta num+1
ldx #0
dc1 lda #'0'
sta digit
dc2 lda num
sec
sbc p10lo,x
tay
lda num+1
sbc p10hi,x
bcc dc3
sta num+1
sty num
inc digit
bne dc2
dc3 stx savx
lda digit
jsr putc
ldx savx
inx
cpx #5
bne dc1
rts
p10lo dta <10000,<1000,<100,<10,<1
p10hi dta >10000,>1000,>100,>10,>1
msg dta c'HELLO, 74HC595!',0
logon dta 0 ; bit 7 set = log the pins
logp dta 0
idx dta 0
tmp dta 0
pages dta 0
t0 dta a(0)
num dta a(0)
digit dta 0
savx dta 0
log .ds 200
run start
The result:
READ BACK: HELLO, 74HC595!
16384 BYTES IN 00269 FRAMES
That is about 61 bytes per frame, roughly 3,600 bytes or 29,000 clock pulses a second, on a GRAPHICS 0 screen, which is about 120 times as fast as the BASIC loop. Removing the logging test from the inner loop and unrolling it would roughly double that.
Two practical points for real hardware. A 74HC595 is a 5 V CMOS part that the PIA can drive directly in principle, but check the loading rules in the hardware entries before connecting anything, and keep long cables short or buffered. And if a VBI or DLI also writes PORTA, the two writers will fight: keep all writes to the port in one place.
Troubleshooting
- The cassette motor clicks on: you wrote 52 (or another value with bit 3 clear) to PACTL. Use 56 and 60.
- Writes to PORTA seem to change the direction instead: PACTL is still 56. Write 60 after setting the direction.
- Outputs go dead after pressing RESET: the OS made every line an input again. Redo the setup in your RESET handler.
- An output reads back 0 when you wrote 1: something outside is pulling it low (on port A the read-back is ANDed with the pin). Check the wiring, and never leave a joystick plugged into a jack you drive.
- STICK(0) gives strange values in your game: jack 1 is set as outputs, so the VBI is copying your outputs into the shadow.
- The XL/XE crashes when you write PORTB: port B is memory control on those machines.
Further reading
- Ian Chadwick, Mapping the Atari: PORTA (54016), PORTB (54017), PACTL (54018), STICK0–3 (632–635), PTRIG0–7 (636–643) and the controller jack pinout.
- Altirra Hardware Reference Manual, section 2.5 (the PIA, direction registers, read-back behaviour and reset).
- Marshall S. Dubin, "Interfacing Your Atari", in The Creative Atari (Creative Computing, 1983).
- On this site: Joystick-Port Interfacing: the PIA as a Parallel I/O Port, Full 8-Bit Parallel Interface on the Joystick Ports and Driving an RC Servo from the Joystick Port (hardware section); Reading Joysticks, Paddles and Fire Buttons; The RESET Key: Warm Start, Cold Start and Writing RESET-Proof Programs.
Credits
- Picture: The first test program: jack 1 set as outputs. STICK(0) follows whatever the program writes, and holding the joystick up pulls bit 0 low even though the program drives it high. — Program authors; screenshot by the site
- Mapping the Atari — PORTA/PORTB/PACTL/PBCTL (54016-54019), TRIG0 and GRACTL, controller jack pinout (appendix 11) — AtariArchives.org
- Altirra Hardware Reference Manual — 2.5 Peripheral Interface Adapter (PIA) — Avery Lee (Altirra)
- Atari 400/800 OS Rev. A source listing — IHINIT (PIA initialisation), HARDI, VBI stick reading, cassette motor control — ksquiggle
- The Creative Atari — Marshall S. Dubin, Interfacing Your Atari — Marshall S. Dubin; AtariArchives.org
