Parallax TSL1401-DB User manual

®
®
Web Site: www.parallax.com
Forums: forums.parallax.com
Sales: [email protected]
Technical: [email protected]
Office: [phone]
Fax: [phone]
Sales: [phone]
Support: [phone]
Web Site: www.taosi c.com
Sales: sales@taosi c.com
Office: [phone]
Fax: [phone]
© Bue o Systems, I c. • TSL1401-DB (2009.10.01) Page 1 of 52
TSL1401-DB #28317): Linescan Camera Module
Product Overview
General Description
The TSL1401-DB is a daughterboard that provides a TAOS TSL1401R 128-pixel li ear array se sor a d a
le s. It is desig ed to plug i to a motherboard (e.g. MoBoStamp-pe (p/ 28300), MoBoProp (p/ 28303,
i developme t), Propeller Backpack (p/ 28327)) or the DB-Expa der (p/ 28325). This module will
allow its host system to “see” i o e dime sio . Two- dime sio al visio ca also be achieved by movi g
either the subject or the se sor i a directio perpe dicular to the se sor axis.
Features
• Provides visio i o e dime sio with 128-pixel resolutio .
• Three-li e serial i terface with a alog i te sity output for each pixel.
• I cluded 7.9mm le s provides a field of view equal to subject dista ce.
• Plug-compatible with Parallax motherboards.
• Coprocessor driver firmware for the MoBoStamp-pe available for dow load.
• Ca be i terfaced directly to a BASIC Stamp for some fu ctio s.
• O board accessory socket for strobe output or 50/60Hz fluoresce t light sy c i put.
• Ru s from 3.3V or 5V supplies. (5V is eeded for the optio al LED strobe attachme t.)
Applications
• Measure height, width, diameter, thick ess.
• Locate objects, li es, edges, gaps, holes.
• Cou t items; measure co veyor coverage.
• Determi e volume, shape, orie tatio .
• Read simple barcodes.
• Lear the pri ciples of machi e visio .
What’s Included
TSL1401-DB with le s.
What You Need to Provide
• Parallax motherboard, or DB-Expa der with BASIC Stamp a d carrier board (such as the BOE).

© Bue o Systems, I c. • TSL1401-DB (2009.10.01) Page 2 of 52
Introduction
What the Module Sees
The TSL1401R chip is a li ear array (li esca ) se sor. It co sists of a si gle row of 128 photodetectors.
The TSL1401-DB i cludes a le s to form images o the se sor array. What results is somewhat like
peeri g through the arrow crack of a partially ope ed door to see a thi slice of what lies behi d it. The
illustratio below helps to explai the co cept:
TOP VIEW
First Pixel Last Pixel
The output from each observed pixel is a a alog voltage proportio al to light i te sity. The a alog
i te sity curve correspo di g to the image above would look somethi g like this:

© Bue o Systems, I c. • TSL1401-DB (2009.10.01) Page 3 of 52
Here, you ca see ot o ly the edges of the bagel a d the hole i the middle, but also the i te sity
variatio s caused by the seeds a d herbs o its surface.
The overall width (field of view) see by the TSL1401-DB, usi g the i cluded 7.9mm le s, is
approximately equal to the subject dista ce. So, for example, if the module is 1 meter away from the
subject, it will see a li ear slice of the subject that’s 1 meter wide a d 1/128
th
of a meter high.
Focusi g the TSL1401-DB’s le s is accomplished by screwi g it i or out. Whe screwed almost all the
way i , dista t subjects will be i focus. To focus o closer subjects, the le s eeds to be screwed out a
bit. O ce proper focus is achieved, it may be ecessary to secure the le s from vibratio by wrappi g
tape arou d the le s bezel a d le s holder barrel. If the le s is screwed i far e ough, a small O-ri g
s apped i to the crevice betwee the le s bezel a d le s holder barrel will serve the same purpose.
Note: The use of a thread locker (e.g. Loc-Tite) or a y cya oacrylic adhesive (e.g. Super Glue) is ot
recomme ded ear le s eleme ts, as the fumes ca destroy a y optical coati gs that may be
prese t.
If you are usi g the TSL1401-DB with a Parallax MoBoStamp-pe, you ca use the PC-hosted mo itor
program, described later i this docume t, as a aid to focusi g.
Interface and Basic Operation
Refer to the schematic o the last page of this docume t for the TSL1401-DB’s pi out, a d to TAOS’s
TSL1401R-LF datasheet (available from www.taosi c.com) for the se sor chip’s particulars. For ormal
operatio (i.e. without exter al strobi g or sy ci g), there are o ly three sig als that eed to be
co sidered: SI (digital output to the se sor: begi s a sca /exposure), CLK (digital output to the se sor:
latches SI a d clocks the pixels out), a d AO (a alog pixel i put from the se sor: 0 – Vdd, or tri-stated if
beyo d pixel 128). The TSL1401 datasheet describes these sig als i detail, so that descriptio wo ’t be
repeated here, except as it relates to the BASIC Stamp.
If you are usi g the TSL1401-DB with Parallax’s DB-Expa der (p/ 28325), the pi correspo de ces are
as follows:
TSL1401R Pin DB-Expander Pin
AO A
SI B
CLK C
The TSL1401R is a light-i tegrati g device. It’s a bit like photographic film i that regard: the lo ger you
expose it, the brighter the resulti g image. Also, like film, it ca saturate, such that if exposed too lo g,
everythi g – eve the darkest subjects – will look completely white. The exposure time (also called
“i tegratio time”) is the time i terval betwee SI pulses. (Well, actually, the exposure does ’t really
begi u til 18 clocks after SI; but it’s ofte co ve ie t to ig ore that detail if those clocks occur quickly
e ough.) Duri g each exposure, all the pixels eed to be clocked out of the device to prepare it for the
ext exposure. However, the exposure i terval for each pixel begi s a d e ds with the SI pulse, ot with
the mome t it’s clocked out, as with some other se sors. Therefore, all the pixels get exposed
simulta eously, a d the acquired image represe ts the same i terval i time for each of them.
There are two ways to acquire images with the TSL1401R: co ti uous a d o e-shot. I co ti uous
imagi g, the SI pulses occur i a steady stream, with 129 or more pixel clocks i betwee , duri g each
exposure i terval. To acquire a image, you eed to wait for the ext SI pulse time before clocki g out

© Bue o Systems, I c. • TSL1401-DB (2009.10.01) Page 4 of 52
the pixels that co stitute the image. These pixels will represe t the light received duri g the previous
exposure i terval. Waveforms illustrati g this method are show below:
Tri-
Stated
Tri-
Stated
Tri-
Stated
1 2 3 4 5 6 7 8 9 10 . . . 129 1 2 3 4 5 6 7 8 9 10 . . . 129
SI
CLK
AO
Clock out scan n-1
Integrate scan n
Clock out scan n
Integrate Scan n+1
I o e-shot imagi g, the TSL1401R is left idle u til it’s time to s ap a picture. The SI clocked i , a d
128 pixels are rapidly clocked out a d discarded. The you simply wait u til the desired exposure time
(si ce the SI pulse) has elapsed a d pulse SI agai . At this poi t, you ca clock out the pixels resulti g
from the timed exposure. Here is a sample waveform:
Tri-
Stated
Tri-
Stated
Tri-
Stated
1 129 1 2 3 4 5 6 7 8 9 10 . . . 129
SI
CLK
AO
Clock out garbage
Integrate scan Clock out scanIDLE IDLE
I all the discussio that follows, we will be usi g o e-shot imagi g.

© Bue o Systems, I c. • TSL1401-DB (2009.10.01) Page 5 of 52
Operation with the BASIC Stamp
This sectio explai s how to use the TSL1401-DB directly with a BASIC Stamp. If you have the
MoBoStamp-pe BASIC Stamp 2pe motherboard, you ca skip this sectio a d proceed to the sectio
titled “Operatio with the MoBoStamp-pe”.
Connection
The followi g illustratio shows how to co ect the TSL1401-DB to a BASIC Stamp, usi g Parallax’s
Board of Educatio a d a DB-Expa der board:
Vdd
Vin
Vss
P15
P14
P13
P12
P11
P10
P9
P8
P7
P6
P5
P4
P3
P2
P1
P0
The sig al pi outs a d port usage show above are co siste t with the examples to follow i this sectio .
You ca also use the DB-Exte sio Cable (p/ 500-28301) to separate the TSL1401-DB from the DB-
Expa der board if you eed to.
Image Acquisition
The output of the TSL1401R is a a alog sig al, but the BASIC Stamp does ot have a alog i put
capability (except via RCTIME, which is ’t fast e ough to read 128 pixels). How, the , is it possible to use
this device with a BASIC Stamp? We do it by co ecti g the AO sig al directly to o e of the Stamp’s
digital i puts. Whe do e this way, the BASIC Stamp will threshold the a alog i put. A ythi g over about
2 volts will read as a 1; a ythi g u der, as a 0. By treati g the sig al this way, it’s possible to i put a
stri g of 1s a d 0s that represe t light a d dark portio s of the “sce e” bei g recorded. A complete
sca , the , would require 128 bits of data (i.e. 16 bytes, or 8 words), which the BASIC Stamp ca
accommodate ha dily.
O ce these bits have bee read i , it’s possible to a alyze “features” of the sce e by looki g for groups
of light a d dark pixels. For example, if you wa ted to measure the width of a light object agai st a dark
backgrou d, you could read i the image, the cou t the umber of “1” bits i the data. Likewise, if you
wa ted se se the edge of a “web” (e.g. paper i a paper mill) to keep the web o track, you would look
for the first occurre ce of a light or dark pixel i each sca .

© Bue o Systems, I c. • TSL1401-DB (2009.10.01) Page 6 of 52
The followi g PBASIC code fragme t (take from the complete program template show later i this
sectio ) ca be used to read a si gle sca from the TSL1401-DB. It co sists of five li es of code, which
are show a d discussed i dividually:
SHIFTOUT SI, CLK, 0, [1\1]
SI a d CLK are defi ed i the larger program’s preamble as PINs a d co ect to like- amed ports o
the TSL1401-DB. This stateme t clocks out SI as a si gle bit of sy chro ous serial data, which starts a
ew exposure i terval.
PWM CLK, 128, 1
We wa t to clock through all 128 pixels as fast as possible, si ce we’re just timi g a exposure here, ot
readi g data. The PW stateme t fits the bill perfectly. The 128 i this stateme t is the duty cycle
(50%), ot the umber of pulses. The umber of pulses is give by the 1, which represe ts the le gth of
time to output the PWM sig al. For the BS2, this is omi ally 1mS. (Actually it’s more like 1.2mS a d
co sists of about 150 cycles.)
PULSOUT SI, exp >> 1 MIN 1016 - 1016
This stateme t sets the exposure time. exp ca be either a co sta t or a variable a d represe ts the
le gth of the exposure i microseco ds. The reaso for usi g PULSOUT i stead of PAUSE, say, is that
the timi g resolutio is so much fi er. A d the reaso for se di g the pulse o SI is that it’s ot used for
a ythi g else dur g this time, a d, so lo g as we do ’t clock the pulse with CLK the se sor chip is
u affected. The value subtracted from the pulse width (1016) represe ts the timi g overhead from the
PBASIC program, mi us the start-of-i tegratio delay to the 18
th
clock i the PW stateme t. This
mea s that the mi imum exposure time will be about 2.032mS.
Note: Timi gs for BASIC Stamps other tha the BS2 will vary, a d the value subtracted will eed to
be adjusted accordi gly.
SHIFTOUT SI, CLK, 0, [1\1]
This clocks out the SI pulse agai to e d the exposure a d begi actual data readout.
SHIFTIN AO, CLK, LSBP E, [pdata(0)\16, pdata(1)\16, pdata(2)\16, pdata(3)\16]
SHIFTIN A0, CLK, LSBP E, [pdata(4)\16, pdata(5)\16, pdata(6)\16, pdata(7)\16]
These two stateme ts read 128 bits of thresholded pixel data from the AO pi i to a eight-positio
word array, declared pdata word(8), least-sig fica t bits first. Doi g it “i li e” like this is faster tha
doi g it i a loop.
Here are the waveforms from the above acquisitio routi e, with the various sectio s a otated:
Tri-
Stated
Tri-
Stated
Tri-
Stated
1 129 1 2 3 4 5 6 7 8 9 10 . . . 129
SI
CLK
AO
SHIFTOUT SHIFTOUT
SHIFTI 16 x 8
PWMOUT PULSOUT
IDLE IDLE
150
2V Input Threshold
Thresholded Data

© Bue o Systems, I c. • TSL1401-DB (2009.10.01) Page 7 of 52
You ca use DEBUG to display the acquired pixels, as i the followi g program fragme t. (A somewhat
fa cier versio is give i the complete program later i this sectio .)
FO i = 0 TO 7
DEBUG BIN16 pdata(i) EV 16
NEXT
The variable i ca be declared as a NIBble. The reaso for the REV is because the data were read i
LSB first, but DEBUG’s BIN formatter displays data SB-first. So we eed to reverse the order of the
bits to get a accurate picture of the pixel order. O e might well ask why we did ’t just read the data i
MSB first to begi with. After all, SHIFTIN, ca do that just as easily. The a swer lies i the image
a alysis routi es to follow.
Image Analysis
A alyzi g a li esca image to extract useful i formatio from it i volves two major operatio s: pixel
cou ti g, a d pixel a d edge locatio . The PBASIC subrouti es that perform these operatio s treat the
origi al array of eight words as a array of 128 bits, each bit correspo di g to a si gle pixel. Bit 0 is the
first pixel read; bit 127, the last. (This mappi g is why the pixels eeded to be read i LSB first.) Here’s
how the word a d bit arrays are declared:
pdata VA Word(8)
pixels VA pdata.BIT0
Cou ti g light or dark pixels withi a give ra ge is simple. Here’s the code that does it:
CountPix:
cnt = 0 'Initialize count.
IF (lptr <= rptr AND rptr <= 127) THEN 'Valid range?
FO i = lptr TO rptr ' Yes: Loop over desired range.
IF (pixels(i) = which) THEN cnt = cnt + 1 ' Add to count when pixel matches.
NEXT
ENDIF
ETU N
cnt ca be declared as a byte, si ce it will ever exceed 128. lptr a d rptr are also bytes that ca ra ge
from 0 to 127, i clusive. They i dicate the ra ge over which the cou ti g occurs. which is a bit variable
that i dicates whether to cou t dark pixels (0) or light pixels (1). Cou ti g pixels is ha dy for computi g
a object’s area – either i o e sca , or cumulatively over multiple sca s for two-dime sio al objects
passi g u der the camera o a co veyor.
Locati g the first occurre ce of a dark or light pixel withi a give ra ge is ’t much harder:
FindPix:
IF (found = 1 AND lptr <= rptr AND rptr <= 127) THEN
'Still looking & within bounds?
IF (dir = FWD) THEN ' Yes: Search left-to-right?
FO lptr = lptr TO rptr ' Yes: Loop forward.
IF (pixels(lptr) = which) THEN ETU N ' eturn on match.
NEXT
ELSE
FO rptr = rptr TO lptr ' No: Loop backward.
IF (pixels(rptr) = which) THEN ETU N ' eturn on match.
NEXT
ENDIF
ENDIF

© Bue o Systems, I c. • TSL1401-DB (2009.10.01) Page 8 of 52
found = 0 'Didn't look or nothing found.
ETU N ' eturn.
found is a bit variable that should be i itialized to 1 for the search to comme ce a d i dicates whe the
subrouti e retur s whether the desired pixel has bee fou d (0 = o; 1 = yes). lptr a d rptr have the
same mea i g as i the cou ti g routi e, except that o e or the other ca get moved to the locatio of
the fou d pixel. Combi ed with the cumulative effect that found has, this make it easier to perform a
whole stri g of searches. dir is a bit variable that i dicates which e d of the (lptr, rptr) ra ge to start
the search from. You ca predefi e the co sta ts FWD (= 0, “left_to_right”) a d BKWD (= 1, “right-to-
left”) to assig to dir to make your programs more readable. which, as with the cou ti g routi e,
i dicates what ki d of pixel to look for. You ca predefi e co sta ts for which as well (DRK = 0; BRT =
1) for readability.
Whe FindPix retur s, found will i dicate whether the desired pixel was located, a d either lptr (if dir
= FWD) or rptr (if dir = BKWD) will poi t to the fou d pixel locatio .
Sometimes, it’s ecessary to locate a edge i stead of just a pixel. A light edge , for example is o e that
begi s with a dark pixel, the tra sisitio s to a light o e. The FindPix routi e ca be used to fi d edges,
too, by looki g for the first pixel opposite of the edge you’re seeki g, the the ext pixel after that that
matches the edge value. The routi e to do it is:
FindEdge:
which = 1 - which 'Look for opposite kind of pixel first.
GOSUB FindPix
which = 1 - which 'THEN look for desired pixel.
GOSUB FindPix
ETU N
Locati g pixels a d edges is ha dy for fi di g objects i a field of view a d measuri g their “exte ts”. A
object’s exte t i cludes its outside bou daries a d everythi g i betwee , regardless of pixel i te sity.
For example, i the bagel illustratio , the bagel’s exte t would i clude the hole, while its area (obtai ed
by cou ti g bright pixels) would ot.
Here is a complete program which i corporates all the routi es described above (a d the some). It
acquires images a d locates bright objects, computi g both their exte ts a d areas. You ca also use it
as a template for your ow programs.
' =========================================================================
'
' File...... TSL1401_scan.bs2
' Purpose... Image capture and processing demo using the TSL1401-DB
' Author.... Phil Pilgrim, Bueno Systems, Inc.
' E-mail....
' Started... 11 July 2007
' Updated...
'
' {$STAMP BS2}
' {$PBASIC 2.5}
'
' =========================================================================
' -----[ Program Description ]---------------------------------------------
' This program demonstrates image capture and processing using the
' TSL1401-DB (Parallax p/n 28317). It continuously acquires and displays
' images from the TSL1401 sensor chip. It then locates both left and right

© Bue o Systems, I c. • TSL1401-DB (2009.10.01) Page 9 of 52
' bright edges, displaying them graphically using DEBUG. Finally it
' computes both the area and extent of the object found.
' -----[ evision History ]------------------------------------------------
' -----[ I/O Definitions ]-------------------------------------------------
ao PIN 0 'TSL1401 's analog output (threhsolded by Stamp).
si PIN 1 'TSL1401 's SI pin.
clk PIN 2 'TSL1401 's CLK pin.
' -----[ Constants ]-------------------------------------------------------
D K CON 0 'Value assignd to "which" for dark pixels.
B T CON 1 'Value assigned to "which" for bright pixels.
FWD CON 0 'Value assigned to "dir" for left-to-right search.
BKWD CON 1 'Value assigned to "dir" for right-to-left search.
' -----[ Variables ]-------------------------------------------------------
VariableName VA Byte ' What is variable for?
pdata VA Word(8) 'Pixel data, as acquired LSB first from sensor.
pixels VA pdata.BIT0 '128-bit pixel array mapped onto pdata.
exp VA Word 'Exposure (integration) time in 2uSec units.
lptr VA Byte 'Left pixel pointer for count and find operations.
rptr VA Byte ' ight pixel pointer for count and find operations.
i VA Byte 'General-purpose index.
cnt VA Byte ' esult of pixel-count routine.
which VA Bit 'Indicates seeking D K or B T pixels/edges.
dir VA Bit 'Indicates direction of search (FWD or BKWD).
found VA Bit 'Indicates pixels found (= 1), or not found (= 0).
' -----[ Program Code ]----------------------------------------------------
' NOTE: This code assumes that DEBUG will wrap after 128 characters,
' regardless of the DEBUG window width. Later versions of DEBUG
' may not do this, and you will have to add C s where needed.
exp = 8333 'Set exposure time to 8333uSec (1/120th sec).
DEBUG HOME 'Go to home position on DEBUG screen.
GOSUB DispHdr 'Display the pixel location header.
DO 'Begin the scan-and-process loop.
GOSUB GetPix 'Obtain a pixel scan.
DEBUG C S XY, 0, 2 'Move to column 0, row 2.
GOSUB DispPix 'Display the pixels here.
lptr = 0 : rptr = 127: which = B T : dir = FWD : found = 1
'Initialize parameters for find.
GOSUB FindEdge 'Find first dark-to-light edge going L-> .
dir = BKWD 'Switch directions.
GOSUB FindEdge 'Find first dark-to-light edge going L<- .
DEBUG CL EOL 'Clear the next line.
IF found THEN 'Both edges found?
DEBUG C S X, (lptr - 1), "_|" 'Yes: Display left edge.
DEBUG C S X, rptr, "|_" ' Display right edge.
GOSUB CountPix ' Compute area (light pixel count).
DEBUG C , C , "Area = ", DEC cnt,' Display area ...
" Extent = ", DEC rptr - lptr + 1, CL EOL '... and extent of object.
ELSE 'No: Display failure message.
DEBUG C , C , "No object found.", CL EOL
ENDIF

© Bue o Systems, I c. • TSL1401-DB (2009.10.01) Page 10 of 52
LOOP
END
' -----[ Subroutines ]-----------------------------------------------------
' -----[ GetPix ]----------------------------------------------------------
' Acquire 128 thresholded pixels from sensor chip.
' exp is the exposure time in microseconds.
GetPix:
SHIFTOUT si, clk, 0, [1\1] 'Clock out the SI pulse.
PWM clk, 128, 1 ' apidly send 150 or so CLKs.
PULSOUT si, exp >> 1 MIN 1016 – 1016 'Wait for remaining integration time.
SHIFTOUT si, clk, 0, [1\1] 'Clock out another SI pulse.
' ead 8 words (128 bits) of data.
SHIFTIN ao, clk, LSBP E, [pdata(0)\16, pdata(1)\16, pdata(2)\16, pdata(3)\16]
SHIFTIN ao, clk, LSBP E, [pdata(4)\16, pdata(5)\16, pdata(6)\16, pdata(7)\16]
ETU N
' -----[ DispHdr ]---------------------------------------------------------
' Display a header to aid in identifying pixel positions.
DispHdr:
FO i = 0 TO 12 'Display tens digits.
DEBUG DEC i DIG 0
IF i < 12 THEN DEBUG " " ELSE DEBUG C
NEXT
FO i = 0 TO 127 'Display ones digits.
DEBUG DEC i // 10
NEXT
ETU N
' -----[ DispPix ]---------------------------------------------------------
' Display 128 pixels: light pixels as "1"; dark, as "_".
DispPix:
FO i = 0 TO 127
IF pixels(i) THEN DEBUG "1" ELSE DEBUG "."
NEXT
ETU N
' -----[ FindEdge ]--------------------------------------------------------
' Find the first edge within the range lptr through rptr, in the direction
' given by dir and of the type indicated by which (0 = light-to-dark;
' 1 = dark-to-light).
FindEdge:
which = 1 - which 'Look for opposite kind of pixel first.
GOSUB FindPix
which = 1 - which 'Then look for desired pixel,
' by falling through to FindPix.
' -----[ FindPix ]---------------------------------------------------------