PBASIC Programming
Program Structure
Humans often think of computers and microcontrollers as smart devices and yet, they will do nothing without a specific set of instructions. This set of instructions is called a program. It is our job to write the program. Stamp programs are written in a programming language called PBASIC, a Parallax-specific version of the BASIC (Beginners All-purpose Symbolic Instruction Code) programming language. BASIC is very popular because of its simplicity and English-like syntax. A working program can be as simple as a list of statements. Like this:
statement1 statement2 statement3 END
Comments
Comments are included in a program for readability and notes. These statements are not loaded into the microcontroller and do not take up any program space. Each comment starts with an apostrophe. Comments can be on lines by themselves, or to the right of PBASIC programming statements. Heres an example of using comments:
' Program 1: LED ' This program lights up an LED ' Hardware Setup: ' Active-low LED connected to Stamp Pin P7 HIGH 7 PAUSE 500 LOW 7 END ' Turn LED on ' for half second ' Turn LED off
Capitalization
PBASIC is not case-sensitive. PBASIC keywords, variables, and constants can be entered in either upper or lower case, with no change in meaning.
debug DEBUG DeBuG Debug Hello Hello Hello Hello VAR Byte All these commands are interpreted the same
counter counter = 1 Counter = 1 COUNTER = 1
All these variable names are interpreted the same
The DEBUG Statement
DEBUG outputdata {, outputdata}
DEBUG "Hello World!"
Output: Hello World!
DEBUG "Hello World!" DEBUG "and Hello again
Output: Hello World!and Hello again
DEBUG "Hello World!", CR DEBUG "and Hello again
Output: Hello World! and Hello again
DEBUG "Hello World!", CR, and hello again
Output: Hello World! and Hello again
DEBUG CR, CR, Hello World, CR, and hello again
Output: Hello World! and Hello again
Debug Control Characters
CR CLS HOME BELL BKSP TAB Carriage Return Clear screen, cursor positioned in upper left Moves cursor to upper left corner but doesnt clear screen Makes a sound Backspace Tab
Variables
Variable Sizes
The BASIC Stamp supports four variable types. For the most efficient use of the Stamps memory, a variable should be defined based on program requirements. Using a Word variable, for example, when the value will never exceed 15 is an inefficient use of the Stamps variable memory space.
Type Bit Nib Byte Word Bits 1 4 8 16 Range 0 .. 1 0 .. 15 0 .. 255 0 .. 65,535
Variable Declaration
Variables must be declared before they can be used in a program. All variable declarations are usually placed together at the top of a program. To declare a variable, enter the name of the variable, the keyword VAR, and the size of the variable. Heres an example of declaring several variables:
flag counter status VAR VAR VAR Bit Nib Byte
Printing Variables using DEBUG
x x = 65 DEBUG DEBUG DEBUG DEBUG DEBUG DEBUG VAR Byte
Shorthand to print x = , value, CR ASCII value! Decimal Indicated Binary, starts with % sign Indicated Hex, starts with $ sign Printing variables along with text DEBUG The temperature is , DEC x, degrees, CR
Printing variables, CR ? x x, CR DEC x, CR IBIN x, CR IHEX x, CR
Debug Formatters
? DEC IHEX IBIN STR ASC Note: Shorthand notation. Prints var = <value>, CR Decimal Indicated hexadecimal Indicated binary String from BYTEARRAY ASCII The default is ASCII! To print a number, you must include a formatter.
Using Variables
x y result x = 25 y = 2 result = x y DEBUG "x y = ", DEC result, CR result = x / y DEBUG "x / y = ", DEC result, CR result = x + y * 10 DEBUG "x + y * 10 = ", DEC result, CR ' Subtraction ' Division ' Order of operations VAR VAR VAR Byte Byte Byte
Output: x y = 23 x / y = 12 x + y * 10 = 14
Constants
Constants are values that cannot change during the execution of program. Named constants will usually assist the reader in understanding the nature of the program and, in many cases, assist the original programmer that has set the program aside for some time. The value of a constant can only be changed by editing the source code.
Constant Declaration
Named constants must be declared before they can be used in a program. All constant declarations are usually placed together at the top of a program. To declare a constant, enter the name of the constant, the keyword CON, and the value of the constant. Heres an example of declaring several constants:
MaxTemp MidPoint CON CON 212 750
Using Constants
ScaleFactor degreeF CON VAR 100 Byte
degreeF = degreeF / ScaleFactor
Declaring Pin Numbers as Constants
One very useful application of constants is to stand for BASIC Stamp pin numbers. This practice makes a program more understandable. For example, suppose we have an LED connected to the BASIC Stamp's pin number P8, and a servo motor connected to pin number P12. Instead of using the numerals "8" and "12" throughout the program, we can declare them as constants.
Led Servo CON CON 8 12 ' LED is connected to Pin P8 ' Servo motor connected to Pin P12
Branching Redirecting the Flow of a Program
A branching command is one that causes the flow of the program to change from its linear path. In other words, when the program encounters a branching command, it will, in almost all cases, not be running the next [linear] line of code. The program will usually go somewhere else. There are two categories of branching commands: unconditional and conditional. PBASIC has two commands, GOTO and GOSUB that cause unconditional branching. Heres an example of an unconditional branch using GOTO:
GOTO and Labels
Greeting: DEBUG "Hello World!", CR PAUSE 500 GOTO Greeting
We call this an unconditional branch because it always happens. GOTO redirects the program to another location. The location is specified as part of the GOTO command and is called an address. Remember that addresses start a line of code and are followed by a colon (:). Youll frequently see GOTO at the end of the main body of code, forcing the program statements to run again. Conditional branching will cause the program flow to change under a specific set of circumstances. The simplest conditional branching is done with IF-THEN construct. The PBASIC IF-THEN construct is different from other flavors of BASIC. In PBASIC, THEN is always followed by a valid program address (other BASICs allow a variety of programming statements to follow THEN). If the condition statement evaluates as TRUE, the program will branch to the address specified. Otherwise, it will continue with the next line of code.
IF-THEN
General format:
Start: statement 1 statement 2 statement 3 IF condition THEN Start
The statements will be run and then the condition is tested. If it evaluates as TRUE, the program will branch back to the line called Start. If the condition evaluates as FALSE, the program will continue at the line that follows the IF-THEN construct.
IF condition THEN label
IF (controlVar = 0) THEN Label_0 IF (controlVar = 1) THEN Label_1 IF (controlVar = 2) THEN Label_2
Looping Running Code Again and Again GOTO LOOP
Looping causes sections of the program to be repeated. Looping often uses unconditional and conditional branching to create the various looping structures. Heres an example of unconditional looping:
Greeting: DEBUG "Hello World!", CR PAUSE 500 GOTO Greeting
By using GOTO the statements are unconditionally repeated, or looped. By using IF-THEN, we can add a conditional statement to the loop. The next few examples are called conditional looping. The loops will run under specific conditions. Conditional programming is what gives microcontrollers their smarts.
CONDITIONAL LOOPING WITH IF-THEN
Label: statement 1 statement 2 statement 3 IF condition THEN Label
With this loop structure, statements will be run so long as the condition evaluates as TRUE. When the condition is evaluated as FALSE, the program will continue at the line following the IF-THEN statement. Its important to note that in the previous listing the statements will always run at least once, even if the condition is FALSE.
FOR-NEXT LOOP
The final example of conditional looping is the programmed loop using the FOR-NEXT construct.
FOR controlVar = startVal TO endVal STEP stepSize statement 1 statement 2 statement 3 NEXT
The FOR-NEXT construct is used to cause a section of code to execute (loop) a specific number of times. FOR-NEXT uses a control variable to determine the number of loops. The size of the variable will determine the upper limit of loop iterations. For example, the upper limit when using a byte-sized control variable would be 255.
counter PAUSE 250
VAR
Nib ' let DEBUG window open
FOR counter = 1 TO 5 DEBUG "Loop Number: ", DEC counter DEBUG " Hello World!", CR PAUSE 500 NEXT
Output: Loop Number: Loop Number: Loop Number: Loop Number: Loop Number:
1 2 3 4 5
Hello Hello Hello Hello Hello
World! World! World! World! World!
The STEP option of FOR-NEXT is used when the loop needs to count increments other than one. If, for example, the loop needed to count even numbers, the code would look something like this:
FOR controlVar = 2 TO 20 STEP 2 statement 1 statement 2 statement 3 NEXT
Subroutines Reusable Code that Saves Program Space
The final programming concept well discuss is the subroutine. A subroutine is a section of code that can be called (run) from anywhere in the program. GOSUB is used to redirect the program to the subroutine code. The subroutine is terminated with the RETURN command. RETURN causes the program to jump back to the line of code that follows the calling GOSUB command.
GOSUB and RETURN
PAUSE 250 Main: GOSUB Hello GOSUB Goodbye END Hello: DEBUG "Hello there!", CR RETURN Goodbye: DEBUG "Bye now!", CR RETURN
BASIC Stamp Memory
The BASIC Stamp has two kinds of memory; RAM (for variables used by your program) and EEPROM (for storing the program itself). EEPROM may also be used to store long-term data in much the same way that desktop computers use a hard drive to hold both programs and files. An important distinction between RAM and EEPROM is this: RAM loses its contents when the BASIC Stamp loses power; when power returns, all RAM locations are cleared to 0s. EEPROM retains the contents of memory, with or without power, until it is overwritten (such as during the program-downloading process or with a WRITE instruction.)
The BS2, BS2e, BS2sx and BS2p have 32 bytes of Variable RAM space. Of these, the first six bytes are reserved for input, output, and direction control of the I/O pins. The remaining 26 bytes are available for general-purpose use as variables.
I/O Registers
Occupy first 3 words RAM (6 bytes) 16-bit registers (Stamp has 16 I/O pins) Are all initialized to zero All pins set to inputs by default
Names of I/O Registers
INS OUTS DIRS Shows state of I/O pins regardless whether input or output Write values into here to make pin high (1) or low (0) 0=Input, 1 = Output
Reserved Names for Referring to I/O Registers
INS REGISTER Name IN0 - IN15 INA, INB, INC, IND INL, INH INS INS REGISTER REFERENCE 15 14 13 12 INA INB INC IND INL INH INS Size Bit Nibble Byte Word 11 10 9 8 7 6 5 4 3 2 1 0
OUTS REGISTER Name OUT0 OUT15 OUTA, OUTB, OUTC, OUTD OUTL, OUTH OUTS
Size Bit Nibble Byte Word 10 9 8 7 6 5 4 3 2 1 0
OUTS REGISTER REFERENCE 15 14 13 12 11 OUTA OUTB OUTC OUTD OUTL OUTH OUTS DIRS REGISTER 0 = INPUT, 1 = OUTPUT Name DIR0 .. DIR15 DIRA, DIRB, DIRC, DIRD DIRL, DIRH DIRS
Size Bit Nibble Byte Word 10 9 8 7 6 5 4 3 2 1 0
DIRS REGISTER REFERENCE 15 14 13 12 11 DIRA DIRB DIRC DIRD DIRL DIRH DIRS
To Specify a Pin as Output
Since all pins default to inputs, you must specify which pins you wish to use as outputs. There are a number of ways to do this: 1. Use DIRS register Write a "1" for "Output"
DIRS = %00110000000000000000 DIR4 = 1 ' Outputs: 13, 12 ' Outputs: 4
2. Use OUTPUT keyword
OUTPUT 7 ' Outputs: 7
3. Use HIGH or LOW keywords These set the direction, and write a value
HIGH 5 LOW 3 ' ' Specifies that pin P5 is an output, and sets it high Specifies that pin P3 is an output, and sets it low
4. Use keywords that do it for you No need to use OUTPUT or DIRS first FREQOUT, PULSOUT, SEROUT, ...
Examples of I/O Register Usage
DIRS = %0011000000000000 if (IN1 = 1) THEN Do_Something ' Outputs: 13, 12
Aliases
An alias is an alternate name for an existing variable. One of the most useful applications of aliases is to create alternate names for the Stamp's built-in variable names used for input and output. This can greatly increase a program's readability and understandability. To declare an alias, enter the alias, the keyword VAR, and the name of the existing variable. Heres an example of creating two aliases, called "btn" and "LED", which refer to BASIC Stamp pins P7 and P8, respectively.
btn LED VAR VAR IN7 OUT8 ' name (alias) the input ' name (alias) the output
