Basic Starter Package - Tutorial #1

copyright, Peter H. Anderson, Dept of EE,

Morgan State University, Baltimore, MD, Nov 25, '97

Note.

The Basic Starter Package includes a number of tutorials. The intent is to teach the user
how to effectively use the Stamp in the context of various applications.

Some may find this first tutorial rather trivial. However, what is trivial to an
experienced user may well be quite useful to a newcomer. The tutorials become
increasingly advanced.

Routines were verified and corrected on Dec 2, '97.

Initial Ouput Routines.

At this point you have assembled the power supply, made the necessary connections
from the serial port cable to the Stamp and have assembled and tested the logic probe.

Lets forge ahead and write some simple programs to flash a a single LED. In doing so, I
hope to get across many of the PBASIC commands in a simple context which is
understandable.

Please refer to Figure #1. Note that this consists of the addition of a single LED from P0
(Terminal 5) on the Stamp to ground. Note that the LEDs supplied with the Basic
Starter package have an integrated 330 Ohm resistor to limit the LED current to
nominally 10 mA.

The idea is to force a logic one on an ouput for a period of time, thus turning the LED
on. And then, output a zero for a period of time, causing the LED to turn off.

Program LED_1.BS2

' LED_1.BS2
'
' Flashes an LED on Output 0 on and off
'
' Peter H. Anderson, MSU, 25 November, '97
'

TOP:

DIR0=1 ' make P0 an output

 OUT0=1 ' turn on the LED
PAUSE 500 ' pause for 500 msecs

OUT0=0 ' turn off the LED

PAUSE 500

GOTO TOP

Note that an "'" indicates that all that follows on the line is a comment. Although not
required, good programmers spend a bit of effort briefly describing the overall operation
of the program and include annotations within the code to give the reader a clear idea of
what the statements are doing.

The word TOP is a label, in this case, a place in the program. Labels can be virtually
anything other than specific key words.

Each of the 16 I/O pins on the Basic Stamp may be configured as an input or as an
output. The Stamp reserves a 16-bit variable DIRS with the state of each bit being used
to confgure that pin as either as an input or an output.

Specific bits, may be selectively configured using the DIRp nomenclature. That is,
DIR0 or DIR7 or DIR15. A one configures the bit as an output. Thus;

DIR0=1 ' make pin 0 an output

DIR7=0 ' make pin 7 an input
The Stamp reserves another 16-bit variable termed OUTS and here again, each of the
specific pins may be addressed using OUTp; e.g., OUT0.

In this case;

OUT0=1 ' copy a one into bit OUT0

OUT0=0 ' copy a zero into bit OUT0
Note that the pin will only assume the designated state if the associated DIR bit is
defined to be an output.

The PAUSE command is pretty obvious. Note that the time is in milliseconds. The
maximum value is 2^16-1 or 65,535. Thus, using the PAUSE, the largest delay one
could achieve is nominally 60.5 seconds.

The GOTO redirects the program flow to the designated label. Thus, in this case, the
program simply loops, continually flashing the LED.

Program LED_2.BS2

' LED_2.BS2
'
' Flashes an LED on Output 0 on and off. Simply another
implementation of
' LED_1.BS2.
'
' Peter H. Anderson, MSU, 25 November, '97
'

OUT CON 1 ' define the word OUT to be the same as 1

 DELAY_TIME CON 500

DIR0=OUT
TOP:

HIGH 0 ' turn on the LED

PAUSE DELAY_TIME' pause for 500 msecs

LOW 0 ' turn off the LED

PAUSE DELAY_TIME

GOTO TOP

Note that a number of changes have been made. However, the program does the same
thing.

The concept of constants has been introduced using the keyword CON. These are
nothing more than constants which are substituted into your code.

In the first program;

DIR0=1
forced pin 0 to be an output. However, I always tend to forget whether it is a zero or a
one and thus I use a standard set of constants that I cut and paste from one program to
another. Thus;
OUT CON 1
simply means, to substitute a "1" where the word OUT appears in the program.

Similarly, substitute 500 wherever the the word DELAY_TIME appears.

Note that the DIR0=1 has been pulled out of the loop, and is now executed only one
time when the program begins. Once the direction of a bit has been defined, there is no
need to continually do so as was done in the first program.

The commands HIGH and LOW followed by the pin number are simply alternative
representations of the OUT command;

HIGH 0 ' same as OUT0 = 1

LOW 0 ' same as OUT0 = 0
Program LED_3.BS2.
' LED_3.BS2
'
' Flashes an LED on Output 0 on and off 50 times
'
' Peter H. Anderson, MSU, 25 November, '97
'

TIMES VAR BYTE

OUT CON 1 ' define the word OUT to be the same as 1

LED CON 0 ' LED is on pin 0
DELAY_TIME CON 500

DIR0=OUT
TOP:

FOR TIMES = 1 TO 50
HIGH LED ' turn on the LED
PAUSE DELAY_TIME ' pause for 500 msecs

LOW LED ' turn off the LED

PAUSE DELAY_TIME
DEBUG ?TIMES
NEXT

DEBUG "Done!"

DONE:
GOTO DONE

In this program, the variable TIMES has been declared as a byte (8 bits). Note that a
byte may accommodate the numbers 0 through 255 and in this application where the
highest value is 50, a byte is sufficient. If I desired to flash the LED a 1000 times, the
variable would have been declared as a "word" which is two bytes. A word can
accommodate values from 0 to 65,535.

Note that an additional constant has been defined; LED. Rather than burdening one's
mind with the fact that the LED is on pin 0, this simple idea of a constant permits you to
make that connection just once and then refer to the pin as simply "LED". As we only
are using one lead at this point, the advantage may not be obvious, but it will when we
begin to use many of the 16 inputs and outputs.

Program LED_3 introduces the use of the FOR - NEXT command. In this context, the
commands between the FOR and the NEXT are executed with TIMES equal to 1, and
then with TIMES equal to 2, etc until TIMES is equal to 50. TIMES is then incremented
to 51, which is beyond the upper bound (50) and the program thus breaks from the FOR
loop.

Note that on each pass through the loop, the LED is flashed and, in addition the value of
TIMES is displayed on the terminal using the DEBUG command.

The DEBUG command allows you to print values and text to the terminal. Future
programs will treat this in much greater detail. For the moment;

DEBUG "Hello", CR ' prints Hello followed by a new line

DEBUG DEC TIMES ' prints the value of TIMES is decimal

' not there is no new line

DEBUG "N=", DEC TIMES CR

' prints TIMES=value. For example TIMES=33

DEBUG ?N ' this is a much simpler shorthand for the

above
After breaking from the FOR - NEXT loop, the program displays a "Done" message and
then continually loops doing nothing.

Program LED_4.BS2.
' LED_4.BS2
'
' Flashes an LED on Output 0 on and off 50 times. Uses a subroutine
'
' Peter H. Anderson, MSU, 25 November, '97
'

TIMES VAR BYTE

OUT CON 1 ' define the word OUT to be the same as 1

LED CON 0 ' LED is on pin 0
DELAY_TIME CON 500

DIR0=OUT

TOP:

FOR TIMES = 1 TO 50
GOSUB FLASH
NEXT

DEBUG "Done!"

DONE:
GOTO DONE

FLASH: ' winks LED on and off one time

HIGH LED ' turn on the LED

PAUSE DELAY_TIME ' pause for 500 msecs

TOGGLE LED ' turn off the LED

PAUSE DELAY_TIME
DEBUG ?TIMES
RETURN
Note that the FOR loop is now reduced to simply a "call" or GOSUB to subroutine
FLASH. In the subroutine, the LED is turned on, there is a pause, and then the LED
lead is toggled. That is, as the current state of the LED lead is high, the TOGGLE
results in bringing it low. If it were low, TOGGLE would bring the lead high.

The RETURN statement then causes the program to return to the statement after the
GOSUB.

In calling (GOSUB) a subroutine, the return address is pushed on to a stack. When the
RETURN is executed this return address is pulled from the top of the stack. Fortunately,
this is all hidden from the Stamp user, but the general mechanics are important in
appreciating the following limitations.

A subroutine must be called (GOSUB). You cannot GOTO a subroutine, as with a

GOTO, the return address is not pushed on to the stack. Thus, in executing the
RETURN, whatever junk happens to be on the top of the stack will be pulled and the
program will, in theory, continue at that junk address and your program will not work
properly.
Along the same line, your subroutine must not be in the program flow of other routines.
An example is illustrated in LED_4A.

' LED_4A.BS2 (This routine illustrates a common error. It will not

work).
'
' Flashes an LED on Output 0 on and off 50 times. Uses a subroutine
'
' Peter H. Anderson, MSU, 25 November, '97
'

TIMES VAR BYTE

OUT CON 1 ' define the word OUT to be the same as 1

LED CON 0 ' LED is on pin 0
DELAY_TIME CON 500

DIR0=OUT

TOP:

FOR TIMES = 1 TO 50
GOSUB FLASH
NEXT

FLASH: ' winks LED on and off one time

HIGH LED ' turn on the LED

PAUSE DELAY_TIME ' pause for 500 msecs

TOGGLE LED ' turn off the LED

PAUSE DELAY_TIME
DEBUG ?TIMES
RETURN

DEBUG "Done!"

DONE:
GOTO DONE
Note that this program is wrong. The LED will indeed flash the 50 times. However, on
exiting the FOR - NEXT loop, the program will enter the subroutine. Note that there has
been no call (GOSUB). The LED will again flash (for the 51st time). However, on
executing the RETURN, the top of the stack does not contain a valid return address and
your program will go to off to "never never land".

Finally, you must RETURN from a subroutine. Consider the following very incorrect
routine.

' LED_4B.BS2 (This routine illustrates another common error. It will

not
' work.)
'
' Flashes an LED on Output 0 on and off 50 times. Uses a subroutine
'
' Peter H. Anderson, MSU, 25 November, '97
'

TIMES VAR BYTE

 OUT CON 1 ' define the word OUT to be the same as 1
LED CON 0 ' LED is on pin 0
DELAY_TIME CON 500

DIR0=OUT

TOP:
FOR TIMES = 1 TO 50
GOSUB FLASH
AGAIN:
NEXT

DEBUG "Done!"

DONE:
GOTO DONE

FLASH: ' winks LED on and off one time

HIGH LED ' turn on the LED

PAUSE DELAY_TIME ' pause for 500 msecs

TOGGLE LED ' turn off the LED

PAUSE DELAY_TIME
DEBUG ?TIMES
GOTO AGAIN ' !!!!!!!!!! wrong!

In ths incorrect routine, the FLASH routine is called with a GOSUB and the return
address is pushed on to the top of the stack. However, at the conclusion of the FLASH
routine, I have erroneously used a GOTO. Thus, the return address is not pulled off the
top of the stack. The routine is again called, but there is no corresponding pull in the
subroutine. Thus, the stack is growing and growing and eventually, your program will
stop working.

In summary, when using subroutines, be certain that the only way the program enters
the subroutine is with a GOSUB. No GOTOs and no "walk-ins" as illustrated in routine
LED_4B. Be certain to use a RETURN to go back to the calling program.

Note that in program LED_4, the DEBUG ?TIMES was included in the subroutine to
make a point. All variables in PBASIC are global. That is, the variables are known to all
subroutines.

Program LED_5.BS2.

Consider rolling a die. This generates a random number in the range of 1 to 6. Roll a
second die, generating a second number. Sum them and wink the LED that number of
times. This might be used as a rather expensive and inferior replacement for rolling dice
as in playing Monopoly, Parchesi and other less redeeming games of chance. I say all of
this with tongue in cheek, but the routine helps to make a number of points.

' LED_5.BS2
'
' Flashes an LED on Output 0 on and off the number of times "rolled"
by
' two dice.
'
' Peter H. Anderson, MSU, 25 November, '97
'

DIE_1 VAR BYTE ' first DIE

DIE_2 VAR BYTE ' second DIE
DICE VAR BYTE ' total

R VAR WORD ' random number in range 0-65,535

TIMES VAR BYTE ' flash counter

OUT CON 1 ' define the word OUT to be the same as 1

LED CON 0 ' LED is on pin 0
DELAY_TIME CON 500

DIR0=OUT

TOP:

LOW LED ' be sure the LED is off

RANDOM R ' R is now 0 - 65,535

DIE_1 = (R // 6) + 1 ' roll first die
RANDOM R
DIE_2 = (R // 6) + 1 ' roll the second

DICE = DIE_1 + DIE_2

GOSUB WINK ' wink LED DICE times

DEBUG "Done!"

DONE:
GOTO DONE

WINK: ' flashes LED DICE times

FOR TIMES=1 TO DICE

GOSUB FLASH
NEXT
RETURN

FLASH: ' winks LED on and off one time

HIGH LED ' turn on the LED

PAUSE DELAY_TIME ' pause for 500 msecs

TOGGLE LED ' turn off the LED

PAUSE DELAY_TIME

RETURN
The RANDOM command generates a number in the range of 0 - 65,535 and places the
result in variable R. Note that R has been declared as a word to accommodate this.

The "//" is the mod operator. Somewhere back in junior high, you probably had such
exercises as 12323 divided by 6 = 2053 with a remainder of 5. The mod operation is
simply the remainder. Thus R // 6 generates a number in the range of 0 to 5. Adding one
gives a random number in the range of 1 to 6.

This operation is performed twice to provide values for DIE_1 and DIE_2. The results
are summed (DICE) and subroutine WINK is called which in turn calls subroutine
FLASH, DICE times.

Note that in this example, the FOR loop takes a variable.

There is a flaw in this program in that it will always produce the same "random"
numbers. The command RANDOM takes the arguement, in this case variable R and
operates on it so as to produce a pseudo random number. In this program, the initial
value of R is 0 and thus the RANDOM command will always produce the same random
R, and thus DIE_1 will always be the same. This value of R is then used to calculate
another value of R, but it will also always be the same and thus DIE_2 will always be
the same. None too practical, but I like the program as it shows the use of the
RANDOM function, the mod operator, nested subroutines and the use of a variable in a
FOR-NEXT loop.

This problem of lack of randomness can be corrected by intializing R to some random

value. A common technique is to use time and this will be presented in a future tutorial.

Summary.

All of this has used only one LED which is none too interesting.

However, I am hopeful you have an appreciation for the direction control DIRS, and
controlling the direction of a specific bit (DIR0). You know how to define a constant
using CON, how to declare a variable using VAR and the difference between a byte and
a word. You should know what a label is. All outputs are referred to as OUTS, but a
specific bit may be referenced as OUT0. The commands GOTO, FOR-NEXT, HIGH,
LOW, TOGGLE and PAUSE have been treated. The commands GOSUB and RETURN
have been discussed and hopefully you appreciate the mechanics of subroutines.