Programming the Atari Touch Tablet and Light Pen

Atari GRAPHICS 7 screen with a jagged orange line drawn across it and a two-line text window explaining the stylus and button controls

Joysticks and paddles were not the only things you could plug into an Atari's controller ports. In 1984 Atari sold two drawing devices: the CX77 Touch Tablet with the AtariArtist cartridge, and the CX75 Light Pen with AtariGraphics. Both are easy to read from BASIC once you know how they are wired. The tablet behaves like a pair of paddles, and the light pen uses a pair of position registers inside ANTIC. This guide covers both, with programs you can adapt.

What you'll learn: the history of Atari's tablets and pens, which registers and BASIC functions each uses, how to scale tablet coordinates to the screen, how to calibrate a light pen and why its readings jitter, and how to try all this in an emulator.

What you need: Atari BASIC; a CX77 Touch Tablet or KoalaPad, and/or a light pen with a CRT TV or monitor. Or an emulator: atari800 and Altirra both emulate these devices. Read Reading Joysticks, Paddles and Fire Buttons first if PADDLE and PTRIG are new to you.

1. The hardware

Device Introduced Bundled software How it is read
CX70 Light Pen 1980–81, sold only briefly CX4124 demonstration cassette ANTIC pen registers
CX75 Light Pen January 1984 AtariGraphics cartridge (RX8054), by Gibson Laboratories ANTIC pen registers; tip switch on joystick "up"
CX77 Touch Tablet January 1984 AtariArtist cartridge (RX8053), Island Graphics' Micro Illustrator Two paddle inputs plus three buttons

The CX70 is rare: it was offered for only a few months in early 1981 and some units were marked "Not For Retail Sale". Many third-party pens followed, from makers including Tech Sketch, Edumate, Stack and Koala. On the tablet side, Koala's KoalaPad works the same way as Atari's tablet but reports the vertical position reversed, and the larger PowerPad works on a different principle. Antic's September 1984 graphics survey measured the Atari tablet's drawing area at 6½ by 5 inches and noted that its stylus was the only one with a button on it.

2. Reading the Touch Tablet

The tablet plugs into controller port 1 and uses the port's two potentiometer lines and three of its switch lines. In BASIC:

Read Gives
PADDLE(0) Horizontal position: about 0 at the left to 227 at the right
PADDLE(1) Vertical position: about 0 at the bottom to 227 at the top
PTRIG(0) Left button: 0 while pressed, 1 otherwise
PTRIG(1) Right button: 0 while pressed
STICK(0) 14 while the stylus button is pressed

When nothing touches the surface, both positions read 228. That's the paddle maximum, and it doubles as a "pen up" signal. The buttons are on joystick lines: left on the "left" line, right on the "right" line and the stylus button on "up". That's why the stylus button reads as STICK value 14. The values come from the OS shadow registers PADDL0/PADDL1 (624/625), PTRIG0/PTRIG1 (636/637) and STICK0 (632), which are updated every vertical blank.

Atari's own Using Atari Touch Tablet with BASIC support note warns that 0 and 227 are ideal numbers. The real range may be a little smaller, and readings vary with how fast you move. Note also that the tablet's origin is bottom-left, while BASIC's graphics origin is top-left, so you must flip Y or your picture comes out upside down.

3. A tablet drawing program

This program draws in GRAPHICS 7 (160 × 80 with a text window). It scales the 0–227 tablet range to the screen and flips Y. It joins successive points with DRAWTO so fast strokes don't leave gaps, and it lifts the "pen" whenever the stylus leaves the surface:

10 GRAPHICS 7:SETCOLOR 2,0,0:C=1:COLOR C:P=0
20 PRINT "DRAW WITH THE STYLUS. STYLUS BUTTON:"
30 PRINT "NEXT COLOUR.  LEFT BUTTON: CLEAR."
40 X=PADDLE(0):Y=PADDLE(1)
50 IF STICK(0)=14 THEN C=C+1-3*(C=3):COLOR C:GOSUB 200
60 IF PTRIG(0)=0 THEN GOSUB 200:GOTO 10
70 IF X>227 OR Y>227 THEN P=0:GOTO 40
80 SX=INT(X*159/227):SY=79-INT(Y*79/227)
90 IF P THEN DRAWTO SX,SY:GOTO 40
100 PLOT SX,SY:P=1:GOTO 40
200 IF STICK(0)=14 OR PTRIG(0)=0 THEN 200
210 RETURN
  • Line 70 is the pen-up test. Any reading above 227 means no contact, so P is cleared and the next touch starts a new line instead of joining onto the old one.
  • Line 80 scales X by 159/227 and Y by 79/227, then subtracts Y from 79 to turn the screen the right way up. For GRAPHICS 8 use 319/227 and 159/227 (or 191/227 without the text window).
  • Line 50 cycles through colours 1–3 with the stylus button. Line 200 waits until the button is released, so one press means one step.

Atari's support note used the same approach with fixed factors (0.697 and 0.417 for GRAPHICS 7). The tablet's resolution is finer than GRAPHICS 7 in both directions, so slow strokes look smooth.

AtariArtist pictures in BASIC. The same note gave an undocumented trick. Press INSERT while a picture is on screen in AtariArtist, and it is saved uncompressed to disk as PICTURE, taking 62 sectors. The normal save compresses it into a form only AtariArtist can read. Rename the file from DOS before saving another, because the next INSERT overwrites it.

4. How a light pen works

A light pen doesn't measure anything itself. It contains a light sensor that fires a short pulse when the CRT's electron beam sweeps past the spot it is pointing at. That pulse goes to the trigger pin of the controller port, which on the 800, XL and XE also feeds ANTIC's light-pen input. On the 400 only port 4 is connected this way. At that instant ANTIC copies its beam position counters into two registers:

Register Shadow Meaning
PENH, 54284 ($D40C) LPENH, 564 ($234) Horizontal position in colour clocks (0–227)
PENV, 54285 ($D40D) LPENV, 565 ($235) Vertical position in units of two scan lines (like VCOUNT)

PEEK(564) and PEEK(565) give you the shadows. The registers keep their last values until another pulse arrives, so there's no "pen is away from the screen" value, and they hold garbage after power-up. The CX75's tip switch is wired to the joystick "up" line, so STICK(0)=14 while the tip is pressed against the screen.

The pen sees only bright areas. Very dark pixels may not trip the sensor at all, so draw pen targets in bright colours, or brighten the background. Pens also need a real CRT that draws one field per frame. They don't work on LCDs or on 100/120 Hz televisions.

5. Calibrating and reading a light pen

PENH and PENV don't line up with screen coordinates. Delays in the video path and the pen add an offset that varies between pens and TVs. In the horizontal direction it is about 30–60 colour clocks, enough that PENH can wrap from 227 back to 0 partway across the visible screen. Every serious light-pen program therefore starts with a calibration step; AtariGraphics asks you to point at a short line on its title screen. This program does the same for a text screen:

10 GRAPHICS 0:POKE 752,1:SETCOLOR 2,0,12:SETCOLOR 1,0,0
20 POSITION 2,1:PRINT "POINT THE PEN AT THE + AND PRESS"
30 POSITION 19,11:PRINT "+"
40 IF STICK(0)<>14 THEN 40
50 FOR W=1 TO 30:NEXT W:H0=PEEK(564):V0=PEEK(565)
60 IF STICK(0)=14 THEN 60
70 POSITION 2,1:PRINT "CALIBRATED. MOVE THE PEN AROUND.  "
80 OX=19:OY=11
90 H=PEEK(564):V=PEEK(565):D=H-H0
100 IF D<-114 THEN D=D+228
110 IF D>114 THEN D=D-228
120 X=19+INT(D/4):Y=11+INT((V-V0)/4)
130 X=X*(X>0)*(X<40)+39*(X>39):Y=Y*(Y>2)*(Y<22)+3*(Y<3)+21*(Y>21)
140 IF X<>OX OR Y<>OY THEN POSITION OX,OY:PRINT " ";:POSITION X,Y:PRINT "*";:OX=X:OY=Y
150 POSITION 2,23:PRINT "PENH ";H;"  PENV ";V;"  ";
160 GOTO 90
  • Line 10 makes the background bright (luminance 12) and the text black, so the whole screen is visible to the pen.
  • Lines 40–60 wait for the tip switch, pause briefly, then record the readings for the known position (column 19, row 11). The pause matters. Pressing or releasing a CX75's tip makes the switch bounce, which sends stray trigger pulses that latch random positions. Waiting for the next frame's genuine reading avoids them.
  • Lines 90–110 take the difference from the calibration point and undo the 228-count wrap-around.
  • Line 120 converts to text cells. A GRAPHICS 0 character is 4 colour clocks wide and 8 scan lines (4 PENV units) high.
  • Line 130 clamps the cursor to the screen with boolean arithmetic, and line 140 moves a * marker only when the cell changes.

Expect some jitter. Atari's pens are steady vertically but less so horizontally: ±1 colour clock is normal, and on XL/XE machines the CX75 can jump by up to about 6 colour clocks. That's why text-cell resolution, or averaging several readings, works far better than trying to hit single pixels.

Machine-language programs that need to know whether the pen sees anything often watch the trigger itself. Its pulse lasts only about 9–10 microseconds, too short for BASIC's STRIG to catch. Setting bit 2 of GRACTL (53277) makes GTIA latch the trigger inputs until the bit is cleared, so a vertical-blank routine can notice the pulse.

6. Trying it today

  • atari800 has -mouse touch (Atari Touch Tablet), -mouse koala (KoalaPad), -mouse pen (light pen) and -mouse gun (light gun), with -mouseport choosing the port. In pen mode the left mouse button acts as the pen switch. Both programs above were run this way, and the screenshot comes from the tablet emulation.
  • Altirra emulates tablets, pads, light pens and light guns, including the Stack Lightpen, and has an interactive tool for recalibrating the light-pen offset. Its Hardware Reference Manual documents the CX75's real-world timing in detail.
  • Real hardware: the tablet needs no special display. A light pen needs a CRT. Wipe the screen first, and adjust brightness and contrast if dark areas don't register.

Software that supports the Atari tablet ranges from AtariArtist and Diamond Paint to the Contiki package and Simon Trew's early-1990s games, which use his Multi-Mouse Touch Tablet Driver.

Troubleshooting

  • The tablet draws upside down. Flip Y: SY=MAXY-INT(Y*MAXY/227). A KoalaPad needs the opposite flip from an Atari tablet.
  • Lines join across the screen. You aren't checking for 228 (stylus lifted). Reset your "pen down" flag when either position is above 227.
  • ERROR 141 (cursor out of range). The scaled value exceeded the screen. Check the scaling factors against the graphics mode and clamp the result.
  • The light pen reads nothing. On a 400 it must be in port 4. On any machine the screen area under the pen must be bright enough, and the display must be a CRT.
  • The cursor jumps when you press or release the tip. That's switch bounce latching false positions. Ignore readings for a moment around each change of the switch, as line 50 does.
  • The cursor is offset or jumps from one side to the other. Recalibrate, and handle the 227→0 wrap of PENH as in lines 100–110.

Further reading

  • Using Atari Touch Tablet with BASIC (Atari Consumer Product Service, DEMOPAC #1, 1984): reading the tablet from BASIC, scaling factors and loading AtariArtist pictures.
  • The Atari Touch Tablet with AtariArtist Software Owner's Guide and Atari Light Pen and AtariGraphics Owner's Guide (Atari, 1983–84).
  • Mapping the Atari by Ian Chadwick (revised edition, COMPUTE! Books, 1985): locations 564–565, 624–639 and 54284–54285.
  • Antic, September 1984: David Duberman's computer graphics product survey, comparing the Atari Touch Tablet, KoalaPad and PowerPad.
  • Altirra Hardware Reference Manual by Avery Lee, Chapter 7: light pens and guns, the CX75 and the Stack Lightpen.
  • On this site: Reading Joysticks, Paddles and Fire Buttons.

Credits