28123

BASIC Stamp Syntax and Reference Manual Version 2.2 Warranty Parallax Inc. warrants its products against defects in materials and workmanship for a period of 90 days from receipt of product. If you discover a defect, Parallax Inc. will, at its option, repair or replace the merchandise, or refund the purchase price. Before returning the product to Parallax, call for a Return Merchandise Authorization (RMA) number. Write the RMA number on the outside of the box used to return the merchandise to Parallax. Please enclose the following along with the returned merchandise: your name, telephone number, shipping address, and a description of the problem. Parallax will return your product or its replacement using the same shipping method used to ship the product to Parallax. 14-Day Money-Back Guarantee If, within 14 days of having received your product, you find that it does not suit your needs, you may return it for a full refund. Parallax Inc. will refund the purchase price of the product, excluding shipping/handling costs. This guarantee is void if the product has been altered or damaged. See the Warranty section above for instructions on returning a product to Parallax. Copyrights and Trademarks This documentation is copyright 1994-2005 by Parallax Inc. By downloading or obtaining a printed copy of this documentation or software you agree that it is to be used exclusively with Parallax products. Any other uses are not permitted and may represent a violation of Parallax copyrights, legally punishable according to Federal copyright or intellectual property laws. Any duplication of this documentation for commercial uses is expressly prohibited by Parallax Inc. Duplication for educational use is permitted, subject to the following Conditions of Duplication: Parallax Inc. grants the user a conditional right to download, duplicate, and distribute this text without Parallax’s permission. This right is based on the following conditions: the text, or any portion thereof, may not be duplicated for commercial use; it may be duplicated only for educational purposes when used solely in conjunction with Parallax products, and the user may recover from the student only the cost of duplication. This text is available in printed format from Parallax Inc. Because we print the text in volume, the consumer price is often less than typical retail duplication charges. BASIC Stamp, Stamps in Class, Board of Education, Boe-Bot, Todder, SumoBot, and SX-Key are registered trademarks of Parallax, Inc. If you decide to use registered trademarks of Parallax Inc. on your web page or in printed material, you must state that “(registered trademark) is a registered trademark of Parallax Inc.” upon the first appearance of the trademark name in each printed document or web page. HomeWork Board, Parallax, and the Parallax logo are trademarks of Parallax Inc. If you decide to use trademarks of Parallax Inc. on your web page or in printed material, you must state that “(trademark) is a trademark of Parallax Inc.”, “upon the first appearance of the trademark name in each printed document or web page. Other brand and product names are trademarks or registered trademarks of their respective holders. ISBN #1-928982-32-8 Errata While great effort is made to assure the accuracy of our texts, errors may still exist. If you find an error, please let us know by sending an email to editor@parallax.com. We continually strive to improve all of our educational materials and documentation, and frequently revise our texts. Occasionally, an errata sheet with a list of known errors and corrections for a given text will be posted to our web site, www.parallax.com. Please check the individual product page’s free downloads for an errata file. Disclaimer of Liability Parallax Inc. is not responsible for special, incidental, or consequential damages resulting from any breach of warranty, or under any legal theory, including lost profits, downtime, goodwill, damage to or replacement of equipment or property, or any costs of recovering, reprogramming, or reproducing any data stored in or used with Parallax products. Parallax Inc. is also not responsible for any personal damage, including that to life and health, resulting from use of any of our products. You take full responsibility for your BASIC Stamp application, no matter how life-threatening it may be. Access Parallax via Internet We maintain very a active web site for your convenience. These may be used to obtain software, communicate with members of Parallax, and communicate with other customers. Access information is shown below: Web: General e-mail: Tech. e-mail: http://www.parallax.com info@parallax.com support@parallax.com Internet BASIC Stamp Discussion List We maintain active web-based discussion forums for people interested in Parallax products. These lists are accessible from www.parallax.com via the Support → Discussion Forums menu. These are the forums that we operate from our web site: • • • • • • • BASIC Stamps – This list is widely utilized by engineers, hobbyists and students who share their BASIC Stamp projects and ask questions. ® Stamps in Class – Created for educators and students, subscribers discuss the use of the Stamps in Class curriculum in their courses. The list provides an opportunity for both students and educators to ask questions and get answers. Parallax Educators –Exclusively for educators and those who contribute to the development of Stamps in Class. Parallax created this group to obtain feedback on our curricula and to provide a forum for educators to develop and obtain Teacher’s Guides. Translators – The purpose of this list is to provide a conduit between Parallax and those who translate our documentation to languages other than English. Parallax provides editable Word documents to our translating partners and attempts to time the translations to coordinate with our publications. Robotics – Designed exclusively for Parallax robots, this forum is intended to be an open dialogue for a robotics enthusiasts. Topics include assembly, source code, expansion, and manual updates. The BoeBot®, Toddler®, SumoBot®, HexCrawler and QuadCrawler robots are discussed here. SX Microcontrollers and SX-Key – Discussion of programming the SX microcontroller with Parallax ® rd assembly language SX – Key tools and 3 party BASIC and C compilers. Javelin Stamp – Discussion of application and design using the Javelin Stamp, a Parallax module that is ® programmed using a subset of Sun Microsystems’ Java programming language. Supported Hardware, Firmware and Software This manual is valid with the following software and firmware versions: BASIC Stamp Model BASIC Stamp 1 BASIC Stamp 2 BASIC Stamp 2e BASIC Stamp 2sx BASIC Stamp 2p BASIC Stamp 2pe BASIC Stamp 2px Firmware 1.4 1.0 1.1 1.1 1.4 1.1 1.0 Windows Interface 2.2 2.2 2.2 2.2 2.2 2.2 2.2 The information herein will usually apply to newer versions but may not apply to older versions. New software can be obtained free on web site (www.parallax.com). If you have any questions about what you need to upgrade your product, please contact Parallax. Credits Authorship and Editorial Review Team: Jeff Martin, Jon Williams, Ken Gracey, Aristides Alvarez, and Stephanie Lindsay; Cover Art: Jen Jacobs; Technical Graphics, Rich Allred; with many thanks to everyone at Parallax Inc. Contents PREFACE ...................................................................... 5 INTRODUCTION TO THE BASIC STAMP ..................................... 7 BASIC STAMP MODEL COMPARISON TABLE .........................................................................8 BASIC STAMP 1 HARDWARE .............................................................................................10 BASIC STAMP 2 HARDWARE .............................................................................................13 BASIC STAMP 2E HARDWARE ...........................................................................................15 BASIC STAMP 2SX HARDWARE .........................................................................................17 BASIC STAMP 2P HARDWARE ...........................................................................................19 BASIC STAMP 2PE HARDWARE .........................................................................................21 BASIC STAMP 2PX HARDWARE .........................................................................................23 GUIDELINES AND PRECAUTIONS .........................................................................................25 BASIC STAMP PROGRAMMING CONNECTIONS ....................................................................27 QUICK START GUIDE ....................................................... 29 USING THE BASIC STAMP EDITOR........................................ 35 THE PROGRAMMING ENVIRONMENT ....................................................................................35 COMPILER DIRECTIVES ......................................................................................................43 SPECIAL FUNCTIONS .........................................................................................................46 SETTING PREFERENCES ....................................................................................................55 ADVANCED COMPILATION TECHNIQUES ..............................................................................68 FEATURES FOR DEVELOPERS.............................................................................................75 BASIC STAMP ARCHITECTURE............................................ 81 RAM ORGANIZATION (BS1)...............................................................................................81 RAM ORGANIZATION (BS2, BS2E, BS2SX, BS2P, BS2PE) .................................................82 DEFINING AND USING VARIABLES .......................................................................................84 The Rules of Symbol Names ......................................................................................86 Defining Array Variables .............................................................................................87 Aliases and Variable Modifiers ...................................................................................89 CONSTANTS AND COMPILE-TIME EXPRESSIONS ...................................................................94 NUMBER REPRESENTATIONS..............................................................................................96 ORDER OF OPERATIONS ..................................................................................................102 INTEGER MATH RULES .....................................................................................................103 UNARY OPERATORS ........................................................................................................105 Absolute Value (ABS) ...............................................................................................105 Cosine (COS) ...........................................................................................................106 Decoder (DCD) .........................................................................................................106 BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 1 Contents Negative (-)...............................................................................................................106 Encoder (NCD) .........................................................................................................107 Sine (SIN) .................................................................................................................107 Square Root (SQR) ..................................................................................................108 BINARY OPERATORS .......................................................................................................109 Add (+)......................................................................................................................109 Subtract (-)................................................................................................................110 Multiply (*).................................................................................................................110 Multiply High (**).......................................................................................................111 Multiply Middle (*/) ....................................................................................................112 Divide (/) ...................................................................................................................113 Modulus (//)...............................................................................................................113 Arctangent (ATN)......................................................................................................114 Hypotenuse (HYP)....................................................................................................115 Minimum (MIN) .........................................................................................................115 Maximum (MAX).......................................................................................................116 Digit (DIG).................................................................................................................117 Shift Left () .........................................................................................................117 Reverse (REV) .........................................................................................................118 And (&) .....................................................................................................................118 Or (|) .........................................................................................................................118 Xor (^).......................................................................................................................119 And Not (&/)..............................................................................................................120 Or Not (|/)..................................................................................................................120 Xor Not (^/) ...............................................................................................................121 BASIC STAMP COMMAND REFERENCE ................................. 123 PBASIC LANGUAGE VERSIONS .......................................................................................123 CATEGORICAL LISTING OF COMMANDS .............................................................................124 SYNTAX CONVENTIONS....................................................................................................128 AUXIO...........................................................................................................................129 BRANCH.......................................................................................................................133 BUTTON .......................................................................................................................137 COMPARE....................................................................................................................141 CONFIGPIN ..................................................................................................................143 COUNT .........................................................................................................................149 DATA ............................................................................................................................153 DEBUG .........................................................................................................................159 DEBUGIN......................................................................................................................171 DO...LOOP....................................................................................................................175 Page 2 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com Contents DTMFOUT.....................................................................................................................179 EEPROM.......................................................................................................................183 END...............................................................................................................................187 EXIT ..............................................................................................................................189 FOR…NEXT .................................................................................................................191 FREQOUT.....................................................................................................................199 GET...............................................................................................................................203 GOSUB .........................................................................................................................209 GOTO............................................................................................................................213 HIGH .............................................................................................................................215 I2CIN.............................................................................................................................217 I2COUT.........................................................................................................................225 IF…THEN......................................................................................................................231 INPUT ...........................................................................................................................243 IOTERM ........................................................................................................................247 LCDCMD.......................................................................................................................249 LCDIN ...........................................................................................................................257 LCDOUT .......................................................................................................................263 LET................................................................................................................................269 LOOKDOWN.................................................................................................................271 LOOKUP .......................................................................................................................277 LOW..............................................................................................................................281 MAINIO .........................................................................................................................283 NAP...............................................................................................................................285 ON.................................................................................................................................289 OUTPUT .......................................................................................................................293 OWIN ............................................................................................................................295 OWOUT ........................................................................................................................303 PAUSE..........................................................................................................................311 POLLIN .........................................................................................................................313 POLLMODE ..................................................................................................................319 POLLOUT .....................................................................................................................325 POLLRUN .....................................................................................................................331 POLLWAIT....................................................................................................................335 POT...............................................................................................................................339 PULSIN .........................................................................................................................343 PULSOUT .....................................................................................................................347 PUT...............................................................................................................................351 PWM .............................................................................................................................355 RANDOM ......................................................................................................................359 RCTIME ........................................................................................................................363 READ ............................................................................................................................369 BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 3 Contents RETURN .......................................................................................................................375 REVERSE.....................................................................................................................377 RUN ..............................................................................................................................381 SELECT...CASE ...........................................................................................................387 SERIN ...........................................................................................................................393 SEROUT .......................................................................................................................415 SHIFTIN ........................................................................................................................431 SHIFTOUT ....................................................................................................................435 SLEEP ..........................................................................................................................441 SOUND .........................................................................................................................445 STOP ............................................................................................................................447 STORE..........................................................................................................................449 TOGGLE.......................................................................................................................455 WRITE ..........................................................................................................................459 XOUT............................................................................................................................465 APPENDIX A: ASCII CHART .............................................. 471 APPENDIX B: RESERVED WORDS ........................................ 473 APPENDIX C: CONVERSION FORMATTERS ............................. 477 APPENDIX D: BASIC STAMP SCHEMATICS ............................. 481 Page 4 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com Preface Thank you for purchasing a Parallax BASIC Stamp® microcontroller module. We have done our best to produce several full-featured, easy to use development systems for BASIC Stamp microcontrollers. Depending on the Starter Kit you purchased, your BASIC Stamp model, development board and other contents will vary. This manual is written for the latest available BASIC Stamp modules and software as of February 2005. As the product-line evolves, new information may become available. It is always recommended to visit the Parallax web site, www.parallax.com, for the latest information. This manual is intended to be a complete reference manual to the architecture and command structure of the various BASIC Stamp models. This manual is not meant to teach BASIC programming or electrical design; though a person can learn a lot by paying close attention to the details in this book. If you have never programmed in the BASIC language or are unfamiliar with electronics, it would be best to locate one or more of the books listed on the following page for assistance. All are available, either to order or to download, from www.parallax.com. Books available in Adobe’s PDF format are published for free download on the Parallax web site or on the CD-ROM which ships with our different Starter Kits. Books available in print may be purchased directly from Parallax or other distributors. In addition, there are hundreds of great examples available on the Parallax CD and web site (www.parallax.com). Also, Nuts & Volts Magazine (www.nutsvolts.com / 1-800-783-4624) is a national electronic hobbyist's magazine that features monthly articles featuring BASIC Stamp applications. This is an excellent resource for beginners and experts alike! BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 5 Preface Book What’s a Microcontroller? Robotics with the Boe-Bot IR Remote for the Boe-Bot Basic Analog and Digital Applied Sensors Understanding Signals Industrial Control Elements of Digital Logic The Microcontroller Application Cookbook Volumes 1 and 2 Al’s “World Famous” Stamp Project of the Month Anthology The Nuts and Volts of BASIC Stamps Volumes 1, 2, 3, 4, and 5 StampWorks Stamp 2 Communication and Control Projects Programming and Customizing the BASIC Stamp Computer BASIC Stamp 2p Part # 28123 Author and Publisher Andy Lindsay; Parallax Inc.; ISBN 1-928982-02-6 28125 Andy Lindsay; Parallax Inc.; ISBN 1-928982-03-4 70016 Andy Lindsay; Parallax Inc.; ISBN 1-928982-31-X 28129 Andy Lindsay; Parallax Inc.; ISBN 1-928982-04-2 28127 Tracy Allen, PhD.; Parallax Inc.; ISBN 1928982-21-2 28119 Doug Pientak; Parallax Inc.; (With Full Kit) ISBN 1-928982-23-9 27341 Marty Hebel / Will Devenport; Parallax Inc.; ISBN 1-928982-08-5 70008 John Barrowman; Parallax Inc.; ISBN 1928982-20-4 Vol. 1&2: 28113 Matt Gilliland; Woodglen Press; Vol. 2: 28112 ISBN 0-616-11552-7 and 0-972-01590-6 70013 Al Williams; Parallax Inc.; ISBN 1-928982-25-5 Vol. 4: 70010 Jon Williams, Scott Edwards and Lon Vol. 5: 70015 Glazner; Parallax, Inc.; ISBN 1-928982-10-7, 1-928982-11-5, 1-928982-17-4, 1-928982-24-7 and 1-928982-30-1 27220 Jon Williams; Parallax, Inc.; ISBN 1-928982-07-7 70004 Thomas Petruzzellis; McGraw-Hill; ISBN 0-071411-97-6 27956 Scott Edwards; McGraw-Hill; ISBN 0-071371-92-3 70001 Claus Kuehnel and Klaus Zahnert; Parallax, Inc.; ISBN 1-928982-19-0 Page 6 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com Availability PDF In Print Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes No Yes Portions Yes Yes (all) Yes (Vol 4 and Vol 5) Yes Yes No Yes No Yes Yes No 1: Introduction to the BASIC Stamp Welcome to the wonderful world of BASIC Stamp® microntrollers. BASIC Stamp microcontrollers have been in use by engineers and hobbyists since we first introduced them in 1992. As of November 2004, Parallax customers have put well over three million BASIC Stamp modules into use. Over this 12-year period, the BASIC Stamp line of controllers has evolved into six models and many physical package types, explained below. General Operation Theory BASIC Stamp modules are microcontrollers (tiny computers) that are designed for use in a wide array of applications. Many projects that require an embedded system with some level of intelligence can use a BASIC Stamp module as the controller. Each BASIC Stamp comes with a BASIC Interpreter chip, internal memory (RAM and EEPROM), a 5-volt regulator, a number of general-purpose I/O pins (TTL-level, 0-5 volts), and a set of built-in commands for math and I/O pin operations. BASIC Stamp modules are capable of running a few thousand instructions per second and are programmed with a simplified, but customized form of the BASIC programming language, called PBASIC. PBASIC Language We developed PBASIC specifically for the BASIC Stamp as a simple, easy to learn language that is also well suited for this architecture, and highly optimized for embedded control. It includes many of the instructions featured in other forms of BASIC (GOTO, FOR...NEXT, IF...THEN…ELSE) as well as some specialized instructions (SERIN, PWM, BUTTON, COUNT and DTMFOUT). This manual includes an extensive section devoted to each of the available instructions. Hardware At the time of this writing, there are currently seven models of the BASIC Stamp; the BS1, BS2, BS2e, BS2sx, BS2p, BS2pe, and the BS2px. The tables below are provided to easily compare their specifications, followed by diagrams that detail the various package types of these modules. Schematics for the SIP/DIP packages of all models can be found in Appendix D. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 7 Introduction to the BASIC Stamp BASIC Stamp Model Comparison Table Products BS1 BS2 BS2e Environment 0º - 70º C (32º - 158º F) ** 0º - 70º C (32º - 158º F) ** 0º - 70º C (32º - 158º F) ** Microcontroller Microchip PIC16C56a Microchip PIC16C57c Ubicom SX28AC Processor Speed 4 MHz 20 MHz 20 MHz Program Execution Speed ~2,000 instructions/sec. ~4,000 instructions/sec ~4,000 instructions/sec RAM Size 16 Bytes (2 I/O, 14 Variable) 32 Bytes (6 I/O, 26 Variable) 32 Bytes (6 I/O, 26 Variable) Scratch PadRam N/A N/A 64 Bytes EEPROM (Program) Size 256 Bytes, ~80 instructions 2K Bytes, ~500 instructions 8 x 2K Bytes, ~4,000 inst Number of I/O Pins 8 16 + 2 Dedicated Serial 16 + 2 Dedicated Serial Voltage Requirements 5 - 15 vdc 5 - 15 vdc 5 - 12 vdc Current Draw@ 5 volts 1 mA Run, 25 µA Sleep 3 mA Run, 50 µA Sleep 25 mA Run, 200 µA Sleep Source/Sink Current per I/O 20 mA / 25 mA 20 mA / 25 mA 30 mA / 30 mA Source/Sink Current per unit 40 mA / 50 mA 40 mA / 50 mA per 8 I/O pins 60 mA / 60 mA per 8 I/O pins PBASIC Commands* 32 42 45 PC Interface Serial (w/BS1 Serial Adapter) Serial (9600 baud) Serial (9600 baud) Windows Text Editor Stampw.exe (v2.1 and up) Stampw.exe (v1.04 and up) Version * PBASIC Command count totals include PBASIC 2.5 commands on all BS2 models. ** See below for industrial rated module information. Industrial-Rated BASIC Stamp Modules Some BASIC Stamp models come in Industrial-rated versions, with an environmental temperature tolerance range of -40°C to +85°C . Contact the Parallax Sales Team directly for the latest information regarding industrial-rated product availability and specifications. Page 8 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com Stampw.exe (v1.096 and up) 1: Introduction to the BASIC Stamp BS2sx BS2p24 BS2p40 BS2pe BS2px 0º - 70º C (32º - 158º F) ** 0º - 70º C (32º - 158º F) ** 0º - 70º C (32º - 158º F) ** 0º - 70º C (32º - 158º F) ** 0º - 70º C (32º - 158º F) ** Ubicom SX28AC Ubicom SX48AC Ubicom SX48AC Ubicom SX48AC Ubicom SX48AC 50 MHz 20 MHz Turbo 20 MHz Turbo 8 MHz Turbo 32 MHz Turbo ~6000 instructions/sec. ~19,000 instructions/sec. ~10,000 instructions/sec. ~12,000 instructions/sec. ~12,000 instructions/sec. 32 Bytes (6 I/O, 26 Variable) 38 Bytes (12 I/O, 26 Variable) 38 Bytes (12 I/O, 26 Variable) 38 Bytes (12 I/O, 26 Variable) 38 Bytes (12 I/O, 26 Variable) 64 Bytes 128 Bytes 128 Bytes 128 Bytes 128 Bytes 8 x 2K Bytes, ~4,000 inst. 8 x 2K Bytes, ~4,000 inst. 8 x 2K Bytes, ~4,000 inst. 16 x 2K Bytes (16 K for source) 8 x 2K Bytes, ~4,000 inst. 16 + 2 Dedicated Serial 16 + 2 Dedicated Serial 32 + 2 Dedicated Serial 16 + 2 Dedicated Serial 16 + 2 Dedicated Serial 5 - 12 vdc 5 - 12 vdc 5 - 12 vdc 5 - 12 vdc 5 - 12 vdc 60 mA Run, 500 µA Sleep 40 mA Run, 350 µA Sleep 40 mA Run, 350 µA Sleep 15 mA Run, 150 µA Sleep 55 mA Run, 450 µA Sleep 30 mA / 30 mA 30 mA / 30 mA 30 mA / 30 mA 30 mA / 30 mA 30 mA / 30 mA 60 mA / 60 mA per 8 I/O pins 60 mA / 60 mA per 8 I/O pins 60 mA /60 mA per 8 I/O pins 60 mA / 60 mA per 8 I/O pins 60 mA / 60 mA per 8 I/O pins 45 61 61 61 63 Serial (9600 baud) Serial (9600 baud) Serial (9600 baud) Serial (9600 baud) Serial (19200 baud) Stampw.exe (v1.091 and up) Stampw.exe (v1.1 and up) Stampw.exe (v1.1 and up) Stampw.exe (v1.33 and up) Stampw.exe (v2.2 and up) Phone: (916) 624-8333 Toll free in the US or Canada: 1-888-512-1024 Email: sales@parallax.com BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 9 Introduction to the BASIC Stamp BASIC Stamp 1 Figure 1.1: BASIC Stamp 1 (Rev B) (Stock# BS1-IC). Figure 1.2: BASIC Stamp 1 OEM (Rev. A) (Stock# 27295). Page 10 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 1: Introduction to the BASIC Stamp Figure 1.3: BASIC Stamp 1 (Rev Dx) (Stock# 27100). The BASIC Stamp 1 is available several physical packages. The BS1-IC (Figure 1.1) uses surface mount components to fit in a small 14-pin SIP package. The preassembled BASIC Stamp 1 OEM (Figure 1.2) features an easier-to-trace layout meant to aid customers who wish to integrate the BASIC Stamp 1 circuit directly into their design (as a lower-cost solution). The BASIC Stamp 1 Rev. Dx (simply called the Rev. Dx), see Figure 1.3, includes a prototyping area suitable for soldering electronic components. These three packages are functionally equivalent, except that the Rev. Dx does not have an available reset pin. In addition to the packages shown, there are prototyping boards available that feature a surface mounted BS1 and programming cable connector. Please check www.parallax.com → Products → Development Boards for product descriptions. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 11 Introduction to the BASIC Stamp Pin Name 1 VIN 2 VSS 3 4 PCO PCI 5 VDD 6 RES 7-14 P0-P7 Description Unregulated power in: accepts 5.5 - 15 VDC (6-40 VDC on BS1-IC rev. b), which is then internally regulated to 5 volts. May be left unconnected if 5 volts is applied to the VDD (+5V) pin. System ground: connects to BS1 Serial Adapter ground for programming. PC Out: 4800 baud serial output (TTL level) to PC. PC In: 4800 baud serial input (TTL level) from PC. 5-volt DC input/output: (Also called +5V) if an unregulated voltage is applied to the VIN pin, then this pin will output 5 volts. If no voltage is applied to the VIN pin, then a regulated voltage between 4.5V and 5.5V should be applied to this pin. Reset input/output: goes low when power supply is less than approximately 4.2 volts, causing the BASIC Stamp to reset. Can be driven low to force a reset. This pin is internally pulled high and may be left disconnected if not needed. Do not drive high. General-purpose I/O pins: each can sink 25 mA and source 20 mA. However, the total of all pins should not exceed 50 mA (sink) and 40 mA (source). See the "BASIC Stamp Programming Connections" section on page 27 for more information on the required programming connections between the PC and the BASIC Stamp. Page 12 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com Table 1.1: BASIC Stamp 1 Pin Descriptions. 1: Introduction to the BASIC Stamp BASIC Stamp 2 Figure 1.4: BASIC Stamp 2 (Rev. G) (Stock# BS2-IC). Figure 1.5: BASIC Stamp 2 OEM (Rev. A2) (Stock# 27290 assembled, or #27291 in kit form). The BASIC Stamp 2 is available in several physical packages. The BS2-IC (Figure 1.4) uses surface mount components to fit in a small 24-pin DIP package. The BASIC Stamp 2 OEM (Figure 1.5) features an easier-to-trace layout meant to aid customers who wish to integrate the BASIC Stamp 2 circuit directly into their design (as a lower-cost solution). The BASIC BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 13 Introduction to the BASIC Stamp Stamp 2 OEM is available in either an assembled form or a kit form. These three packages are functionally equivalent. In addition to the dual-inline and OEM packages, there are prototyping boards available that feature a surface mounted BS2. Please check www.parallax.com → Products → Development Boards for product descriptions. Pin Name 1 SOUT 2 SIN 3 ATN 4 VSS 5-20 P0-P15 21 VDD 22 RES 23 VSS 24 VIN Description Serial Out: connects to PC serial port RX pin (DB9 pin 2 / DB25 pin 3) for programming. Serial In: connects to PC serial port TX pin (DB9 pin 3 / DB25 pin 2) for programming. Attention: connects to PC serial port DTR pin (DB9 pin 4 / DB25 pin 20) for programming. System ground: (same as pin 23) connects to PC serial port GND pin (DB9 pin 5 / DB25 pin 7) for programming. General-purpose I/O pins: each can sink 25 mA and source 20 mA. However, the total of all pins should not exceed 50 mA (sink) and 40 mA (source) if using the internal 5-volt regulator. The total per 8-pin groups (P0 – P7 or P8 – 15) should not exceed 50 mA (sink) and 40 mA (source) if using an external 5-volt regulator. 5-volt DC input/output: if an unregulated voltage is applied to the VIN pin, then this pin will output 5 volts. If no voltage is applied to the VIN pin, then a regulated voltage between 4.5V and 5.5V should be applied to this pin. Reset input/output: goes low when power supply is less than approximately 4.2 volts, causing the BASIC Stamp to reset. Can be driven low to force a reset. This pin is internally pulled high and may be left disconnected if not needed. Do not drive high. System ground: (same as pin 4) connects to power supply’s ground (GND) terminal. Unregulated power in: accepts 5.5 - 15 VDC (6-40 VDC on BS2IC Rev. e, f, and g), which is then internally regulated to 5 volts. Must be left unconnected if 5 volts is applied to the VDD (+5V) pin. See the "BASIC Stamp Programming Connections" section on page 27 for more information on the required programming connections between the PC and the BASIC Stamp. Page 14 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com Table 1.2: BASIC Stamp 2 Pin Descriptions. 1: Introduction to the BASIC Stamp BASIC Stamp 2e Figure 1.6: BASIC Stamp 2e (Rev. B) (Stock# BS2E-IC). The BASIC Stamp 2e is available in the above 24-pin DIP package. Table 1.3: BASIC Stamp 2e Pin Descriptions. Pin Name 1 SOUT 2 SIN 3 ATN 4 VSS 5-20 P0-P15 21 VDD 22 RES 23 VSS 24 VIN Description Serial Out: connects to PC serial port RX pin (DB9 pin 2 / DB25 pin 3) for programming. Serial In: connects to PC serial port TX pin (DB9 pin 3 / DB25 pin 2) for programming. Attention: connects to PC serial port DTR pin (DB9 pin 4 / DB25 pin 20) for programming. System ground: (same as pin 23) connects to PC serial port GND pin (DB9 pin 5 / DB25 pin 7) for programming. General-purpose I/O pins: each can source and sink 30 mA. However, the total of all pins should not exceed 75 mA (source or sink) if using the internal 5-volt regulator. The total per 8-pin groups (P0 – P7 or P8 – 15) should not exceed 100 mA (source or sink) if using an external 5-volt regulator. 5-volt DC input/output: if an unregulated voltage is applied to the VIN pin, then this pin will output 5 volts. If no voltage is applied to the VIN pin, then a regulated voltage between 4.5V and 5.5V should be applied to this pin. Reset input/output: goes low when power supply is less than approximately 4.2 volts, causing the BASIC Stamp to reset. Can be driven low to force a reset. This pin is internally pulled high and may be left disconnected if not needed. Do not drive high. System ground: (same as pin 4) connects to power supply’s ground (GND) terminal. Unregulated power in: accepts 5.5 - 12 VDC (7.5 recommended), which is then internally regulated to 5 volts. Must be left unconnected if 5 volts is applied to the VDD (+5V) pin. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 15 Introduction to the BASIC Stamp See the "BASIC Stamp Programming Connections" section on page 27 for more information on the required programming connections between the PC and the BASIC Stamp. Page 16 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 1: Introduction to the BASIC Stamp BASIC Stamp 2sx Figure 1.7: BASIC Stamp 2sx (Rev. E) (Stock# BS2sx-IC) Figure 1.8: BASIC Stamp 2sx OEM (Rev. A2) (Stock# 27294) The BASIC Stamp 2sx is available in the above two physical packages. The BS2sx-IC (Figure 1.7) uses surface mount components to fit in a small 24-pin DIP package. The preassembled BASIC Stamp 2sx OEM (Figure 1.8) features an easier-to-trace layout meant to aid customers who wish to integrate the BASIC Stamp 2sx circuit directly into their design (as a lower-cost solution). The BASIC Stamp 2sx OEM is available in assembled form only. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 17 Introduction to the BASIC Stamp Pin Name 1 SOUT 2 SIN 3 ATN 4 VSS 5-20 P0-P15 21 VDD 22 RES 23 VSS 24 VIN Description Serial Out: connects to PC serial port RX pin (DB9 pin 2 / DB25 pin 3) for programming. Serial In: connects to PC serial port TX pin (DB9 pin 3 / DB25 pin 2) for programming. Attention: connects to PC serial port DTR pin (DB9 pin 4 / DB25 pin 20) for programming. System ground: (same as pin 23) connects to PC serial port GND pin (DB9 pin 5 / DB25 pin 7) for programming. General-purpose I/O pins: each can source and sink 30 mA. However, the total of all pins should not exceed 75 mA (source or sink) if using the internal 5-volt regulator. The total per 8-pin groups (P0 – P7 or P8 – 15) should not exceed 100 mA (source or sink) if using an external 5-volt regulator. 5-volt DC input/output: if an unregulated voltage is applied to the VIN pin, then this pin will output 5 volts. If no voltage is applied to the VIN pin, then a regulated voltage between 4.5V and 5.5V should be applied to this pin. Reset input/output: goes low when power supply is less than approximately 4.2 volts, causing the BASIC Stamp to reset. Can be driven low to force a reset. This pin is internally pulled high and may be left disconnected if not needed. Do not drive high. System ground: (same as pin 4) connects to power supply’s ground (GND) terminal. Unregulated power in: accepts 5.5 - 12 VDC (7.5 recommended), which is then internally regulated to 5 volts. Must be left unconnected if 5 volts is applied to the VDD (+5V) pin. See the "BASIC Stamp Programming Connections" section on page 27 for more information on the required programming connections between the PC and the BASIC Stamp. Page 18 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com Table 1.4: BASIC Stamp 2sx Pin Descriptions 1: Introduction to the BASIC Stamp BASIC Stamp 2p Figure 1.9: BASIC Stamp 2p24 (Rev. C) (Stock# BS2p24-IC) This module is identical in function to the BS2p40-IC, except that it has 16 I/O pins. Figure 1.10: BASIC Stamp 2p40 (Rev. B) (Stock# BS2p40-IC) This module is identical in function to the BS2p24-IC, except that it has 32 I/O pins. The BASIC Stamp 2p is available in the above two physical packages. Both packages use surface mount components to fit in a small package. The BS2p24-IC (Figure 1.9) is a 24-pin DIP package. The BS2p40-IC (Figure 1.10) is a 40-pin DIP package. Both packages are functionally equivalent accept that the BS2p40 has 32 I/O pins instead of 16. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 19 Introduction to the BASIC Stamp Pin Name 1 SOUT 2 SIN 3 ATN 4 VSS 5-20 P0-P15 {21-36} X0-X15 21 {37} VDD 22 {38} RES 23 {39} VSS 24 {40} VIN Description Serial Out: connects to PC serial port RX pin (DB9 pin 2 / DB25 pin 3) for programming. Serial In: connects to PC serial port TX pin (DB9 pin 3 / DB25 pin 2) for programming. Attention: connects to PC serial port DTR pin (DB9 pin 4 / DB25 pin 20) for programming. System ground: (same as pin 23 on BS2p24, or pin 39 on BS2p40) connects to PC serial port GND pin (DB9 pin 5 / DB25 pin 7) for programming. General-purpose I/O pins: each can source and sink 30 mA. However, the total of all pins (including X0-X15, if using the BS2p40) should not exceed 75 mA (source or sink) if using the internal 5-volt regulator. The total per 8-pin groups (P0 – P7, P8 – 15, X0 – X7 or X8 – X15) should not exceed 100 mA (source or sink) if using an external 5-volt regulator. (BS2p40 Only!) Auxiliary Bank of General-purpose I/O pins: each can source and sink 30 mA. However, the total of all pins (including P0 – P15) should not exceed 75 mA (source or sink) if using the internal 5-volt regulator. The total per 8-pin groups (P0 – P7, P8 – 15, X0 – X7 or X8 – X15) should not exceed 100 mA (source or sink) if using an external 5-volt regulator. 5-volt DC input/output: if an unregulated voltage is applied to the VIN pin, then this pin will output 5 volts. If no voltage is applied to the VIN pin, then a regulated voltage between 4.5V and 5.5V should be applied to this pin. Reset input/output: goes low when power supply is less than approximately 4.2 volts, causing the BASIC Stamp to reset. Can be driven low to force a reset. This pin is internally pulled high and may be left disconnected if not needed. Do not drive high. System ground: (same as pin 4) connects to power supply’s ground (GND) terminal. Unregulated power in: accepts 5.5 - 12 VDC (7.5 recommended), which is then internally regulated to 5 volts. Must be left unconnected if 5 volts is applied to the VDD (+5V) pin. See the "BASIC Stamp Programming Connections" section on page 27 for more information on the required programming connections between the PC and the BASIC Stamp. Page 20 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com Table 1.5: BASIC Stamp 2p Pin Connections 1: Introduction to the BASIC Stamp Basic Stamp 2pe Figure 1.11: BASIC Stamp 2pe (Rev. B) (Stock# BS2pe-IC) The BASIC Stamp 2pe is available in the above 24-pin DIP physical package. Table 1.6: BASIC Stamp 2pe Pin Descriptions. Pin Name 1 SOUT 2 SIN 3 ATN 4 VSS 5-20 P0-P15 21 VDD 22 RES 23 VSS 24 VIN Description Serial Out: connects to PC serial port RX pin (DB9 pin 2 / DB25 pin 3) for programming. Serial In: connects to PC serial port TX pin (DB9 pin 3 / DB25 pin 2) for programming. Attention: connects to PC serial port DTR pin (DB9 pin 4 / DB25 pin 20) for programming. System ground: (same as pin 23), connects to PC serial port GND pin (DB9 pin 5 / DB25 pin 7) for programming. General-purpose I/O pins: each can source and sink 30 mA. However, the total of all pins should not exceed 75 mA (source or sink) if using the internal 5-volt regulator. The total per 8-pin groups P0 – P7 or P8 – 15 should not exceed 100 mA (source or sink) if using an external 5-volt regulator. 5-volt DC input/output: if an unregulated voltage is applied to the VIN pin, then this pin will output 5 volts. If no voltage is applied to the VIN pin, then a regulated voltage between 4.5V and 5.5V should be applied to this pin. Reset input/output: goes low when power supply is less than approximately 4.2 volts, causing the BASIC Stamp to reset. Can be driven low to force a reset. This pin is internally pulled high and may be left disconnected if not needed. Do not drive high. System ground: (same as pin 4) connects to power supply’s ground (GND) terminal. Unregulated power in: accepts 5.5 - 12 VDC (7.5 recommended), which is then internally regulated to 5 volts. Must be left unconnected if 5 volts is applied to the VDD (+5V) pin. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 21 Introduction to the BASIC Stamp See the "BASIC Stamp Programming Connections" section on page 27 for more information on the required programming connections between the PC and the BASIC Stamp. Page 22 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 1: Introduction to the BASIC Stamp Basic Stamp 2px Figure 1.12: BASIC Stamp 2px (Rev. A) (Stock# BS2px-IC) The BASIC Stamp 2px is available in the above 24-pin DIP physical package. Table 1.7: BASIC Stamp 2px Pin Descriptions. Pin Name 1 SOUT 2 SIN 3 ATN 4 VSS 5-20 P0-P15 21 VDD 22 RES 23 VSS 24 VIN Description Serial Out: connects to PC serial port RX pin (DB9 pin 2 / DB25 pin 3) for programming. Serial In: connects to PC serial port TX pin (DB9 pin 3 / DB25 pin 2) for programming. Attention: connects to PC serial port DTR pin (DB9 pin 4 / DB25 pin 20) for programming. System ground: (same as pin 23), connects to PC serial port GND pin (DB9 pin 5 / DB25 pin 7) for programming. General-purpose I/O pins: each can source and sink 30 mA. However, the total of all pins should not exceed 75 mA (source or sink) if using the internal 5-volt regulator. The total per 8-pin groups P0 – P7 or P8 – 15 should not exceed 100 mA (source or sink) if using an external 5-volt regulator. 5-volt DC input/output: if an unregulated voltage is applied to the VIN pin, then this pin will output 5 volts. If no voltage is applied to the VIN pin, then a regulated voltage between 4.5V and 5.5V should be applied to this pin. Reset input/output: goes low when power supply is less than approximately 4.2 volts, causing the BASIC Stamp to reset. Can be driven low to force a reset. This pin is internally pulled high and may be left disconnected if not needed. Do not drive high. System ground: (same as pin 4) connects to power supply’s ground (GND) terminal. Unregulated power in: accepts 5.5 - 12 VDC (7.5 recommended), which is then internally regulated to 5 volts. Must be left unconnected if 5 volts is applied to the VDD (+5V) pin. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 23 Introduction to the BASIC Stamp See the "BASIC Stamp Programming Connections" section on page 27 for more information on the required programming connections between the PC and the BASIC Stamp. Page 24 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 1: Introduction to the BASIC Stamp Guidelines and Precautions When using the BASIC Stamp, or any IC chip, please follow the guidelines below. 1. 2. 3. Be alert to static sensitive devices and static-prone situations. a. The BASIC Stamp, like other IC’s, can be damaged by static discharge that commonly occurs touching grounded surfaces or other conductors. Environmental conditions (humidity changes, wind, static prone surfaces, etc) play a major role in the presence of random static charges. It is always recommended to use grounding straps and anti-static or static dissipative mats when handling devices like the BASIC Stamp. If the items above are not available, be sure to touch a grounded surface after you have approached the work area and before you handle static sensitive devices. Verify that all power is off before connecting/disconnecting. a. If power is connected to the BASIC Stamp or any device it is connected to while inserting or removing it from a circuit, damage to the BASIC Stamp or circuit could result. Verify BASIC Stamp orientation before connection to development boards and other circuits. a. Like other IC’s, the BASIC Stamp should be inserted in a specific orientation in relation to the development board or circuit. Powering the circuit with an IC connected backwards will likely damage the IC and/or other components in the circuit. Most IC’s have some form of a “pin 1 indicator” as do most IC sockets. This indicator usually takes the form of a dot, a half-circle, or the number 1 placed at or near pin 1 of the device. The BS1-IC has a “1” and a half-circle indicator on the backside of the module. Additionally, Figure 1.1 above indicates the pin numbering and labels. All BS2 series modules have a half-circle indicator on the topside of the module (see Figure 1.13). This indicates that pin number one is the first pin counterclockwise from the notch. The socket that accepts this 24-pin module also BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 25 Introduction to the BASIC Stamp has a half-circle or notch on one end, indicating the correct orientation. See Figure 1.14 for other examples. Pin 1 Reference Notch (pin 1 indicator) 23 2 4 5 Reference Notch Figure 1.13: Pin 1 Indicators BS2-IC shown in the correct orientation in relation to a 24-pin socket. 24 1 3 Insert pin 1 here Rev G Note: The Half-Circle indicator is also known as a Reference Notch 22 21 20 6 19 7 18 8 17 9 16 10 15 11 14 12 13 “Dot” (Pin 1 indicator) Insert pin 1 here “1” printed on PC board (Pin 1 indicator) 1 Page 26 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com Figure 1.14: Additional Examples of Pin 1 Indicators (chip and socket shown in the correct orientation in relation to each other) 1: Introduction to the BASIC Stamp BASIC Stamp Programming Connections We suggest using a Parallax development board and cable for programming BASIC Stamp modules. When these items are not available, you may create your own board by duplicating the following diagrams with your own circuits and cables. Be very careful to follow these diagrams closely; it is quite common for programming problems with the BASIC Stamp to be a result of a poorly made custom cable or programming connections on your applications board. With the programming connections for all the BS2 models, it is possible to reverse a couple of wires and still get positive results using some of the "connection" tests our Tech. Support team tries and yet you still will not be able to communicate with the BASIC Stamp. It is vital that you check your connections with a meter and verify the pin numbering to avoid problems like this. Figure 1.15: BS1 Programming Connections with BS1 Serial Adapter Note: Though it is not shown, power must be connected to the BS1 to program it. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 27 Introduction to the BASIC Stamp Figure 1.16: Programming and Run-time Communication Connections for all BS2 models. Note: Though it is not shown, power must be connected to the BASIC Stamp to program it. Also, the programming connections are the same for the BS2p40. Page 28 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 2: Quick Start Guide Quick Start Introduction This chapter is a quick start guide to connecting the BASIC Stamp to the PC and programming it. Without even knowing how the BASIC Stamp functions, you should be able to complete the exercise below. This exercise assumes you have a BASIC Stamp and an appropriate development board. For the latest Parallax development board selection and documentation, go to www.parallax.com → Products → Development Boards. For a more detailed introduction to the BASIC Stamp Editor software, see Chapter 3. Equipment Needed • • • • BASIC Stamp module Compatible carrier board and programming cable Power supply (wall mount or battery) rated for your carrier board PC running Windows® 2000/XP, with o Quantity of RAM recommended for the OS o 3 MB of hard drive space o CD-ROM drive or Internet access o Available port compatible with your carrier board and cable (serial or USB) Connecting and Downloading 1) If the BASIC Stamp isn't already plugged into your development board, insert it into the socket. Refer to Figure 1.13 and Figure 1.14 on page 26 to make sure that you orient it correctly. For a complete listing of Parallax development boards for the various BASIC Stamp modules, go to www.parallax.com and look for Development Boards on the Products menu. 2) If you are using a Parallax development board, follow the directions that came with it to connect the board to the appropriate port in your computer. Figure 2.1 below shows the proper sequence for setting up with a BS1 and a BS1 Carrier Board. Figure 2.2 on page 31 shows the proper sequence to connect any BS2. Note: if you are using your own BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 29 Quick Start Guide development board or a breadboard, carefully follow the Programming Connections guidelines on page 27 before proceeding. Figure 2.1: BS1-IC, BS1 Carrier Board, and BS1 Serial Adapter 1) Insert the BASIC Stamp module into its socket, being careful to orient it properly. 2) Connect the 9-pin female end of the serial cable to an available serial port on your computer, then attach the male end to the BS1 Serial Adapter, Note: you cannot us a null modem cable. 3) Plug the BS1 Serial Adapter into the programming header on the BS1 Carrier Board. 4) Plug a 9 volt battery into the 9 VDC battery clip. Page 30 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 2: Quick Start Guide Alkaline Battery Powercell Figure 2.2: BS2-IC and Board of Education 1) Insert the BASIC Stamp module into its socket, being careful to orient it properly. 3 2) Connect the 9-pin female end of the serial cable to an available serial port on your computer, and then connect the male end to the Board of Education. Note: you cannot use a null modem cable. 4 or 15 14 Vdd 13 12 6-9VDC 9 Vdc Battery Red Black X4 Pwr STA MPS C LA SS 3) Plug in the 6-9 V 300mA centerpositive power supply into the barrel jack. in TM 1 Sout Sin ATN Vss P0 P1 P2 P3 P4 P5 P6 P7 OR 4) Plug a 9 volt battery into the 9 VDC battery clip. U1 Vin Vss Rst Vdd P15 P14 P13 P12 P11 P10 P9 P8 Vss P1 P3 P5 P7 P9 P11 P13 P15 Vin Vss P0 P2 P4 P6 P8 P10 P12 P14 Vdd X1 Reset Vin Vss X3 P15 P14 P13 P12 P11 P10 P9 P8 P7 P6 P5 P4 P3 P2 P1 P0 X2 0 2 Vdd X5 1 2 www.stampsinclass.com Board of Education © 2000-2003 1 3) Install and run the BASIC Stamp Editor software. a) If using the Parallax CD, go to the Software → BASIC Stamp → Windows section to locate the latest version. Click the Install button and follow the prompts to install and run. b) If using the Parallax website, go to www.parallax.com → Downloads → Basic Stamp Software and look in the Software for Windows section for the latest version. Click the Download icon and follow the prompts to install and run. c) Test your PC’s connection to the BASIC Stamp by selecting Run → Identify from the menu bar, as shown in Figure 2.3. If the BASIC Stamp module is not found, check your power and cable connections and retry. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 31 Quick Start Guide Figure 2.3: Test your PC connection to the BASIC Stamp. Select Run → Identify Verify that the BASIC Stamp was detected on one of the COM ports. 4) Enter a $STAMP Directive into the Editor window by clicking on the toolbar icon for the BASIC Stamp module you are using. (Hold the cursor over the icons for flyover help labels.) The example below shows the Stamp Directive that would be inserted for the BS2. ' {$STAMP BS2} 5) Enter a $PBASIC Directive into the Editor window with the toolbar icon. For a BS1, you must use PBASIC 1.0. All BS2 series modules can use PBASIC 2.0 or 2.5. The command set differences between PBASIC 2.0 and 2.5 are covered in Chapter 5. Figure 2.4: Entering the $STAMP and $PBASIC directives from the toolbar The examples shown would be used for programming a BS2 module in PBASIC 2.5 Click on the icon that corresponds to your BASIC Stamp model to automatically place the $STAMP directive in your program. Click on the icon for the PBASIC language version that is compatible with your BASIC Stamp model. You should now see both a $STAMP directive and $PBASIC directive on your PC screen: ' {$STAMP BS2} ' {$PBASIC 2.5} a) Note: These directives may be typed in from the keyboard, but failure to type this line properly may cause the editor to fail to recognize your BASIC Stamp during the next step. Page 32 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 2: Quick Start Guide 6) Type the line DEBUG “Hello World!” below the compiler directives: ' {$STAMP BS2} ' {$PBASIC 2.5} DEBUG "Hello World!" 7) Download this program into the BASIC Stamp. You may select Run → Run from the menu bar, press CTRL-R from the keyboard, or click on the Run ► icon on the toolbar. Figure 2.5: To run your program, you may use the task bar menu or the Run icon. Selecting Run → Run Using the Run toolbar icon a) If the program is typed correctly, a progress bar window should appear (perhaps very briefly) showing the download progress. Then a Debug Terminal window should appear and display "Hello World!" Figure 2.6: Debug Terminal displaying program output b) If there is a syntax error in the program, the editor will highlight the text in question and display an error message. Review the error, fix the code and then try downloading again. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 33 Quick Start Guide c) If the error reported a connection problem with the BASIC Stamp, make sure the first line of code indicates the proper module name and verify the programming cable connections, module orientation (in the socket) and that it is properly powered, then try downloading again. 8) Congratulations! You've just written and downloaded your first BASIC Stamp program! The "Hello World!" text that appeared on the screen was sent from the BASIC Stamp, back up the programming cable, to the PC. Page 34 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 3: Using the BASIC Stamp Editor Introducing the BASIC Stamp Editor This section describes the BASIC Stamp Editor for Windows version 2.2. This software supports all 7 BASIC Stamp modules available as of February 2005, and all 3 versions of the PBASIC programming language, PBASIC 1.0, PBASIC 2.0, and PBASIC 2.5. The Programming Environment The BASIC Stamp Windows Editor, shown in Figure 3.1, was designed to be easy to use and mostly intuitive. Those that are familiar with standard Windows software should feel comfortable using the BASIC Stamp Windows Editor. Figure 3.1: BASIC Stamp Windows Editor. THE EDITOR WINDOW. The editor window consists of the main edit pane with an integrated explorer panel to its left, as shown above. THE MAIN EDIT PANE. The main edit pane can be used to view and modify up to 16 different source code files at once. Each source code file that is loaded into the BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 35 Using the BASIC Stamp Editor editor will have its own tab at the top of the page labeled with the name of the file, as seen in Figure 3.2. The full file path of the currently displayed source code appears in the title bar. Source code that has never been saved to disk will default to “Untitled#”; where # is an automatically generated number. A user can switch between source code files by simply pointing and clicking on a file’s tab or by pressing Ctrl+Tab or Ctrl+Shift+Tab while the main edit pane is active. Figure 3.2: Example Editor Tabs. Shown with 6 separate files open; Title Bar shows current code’s file path. The status of the active source code is indicated in the status bar below the main edit pane and integrated explorer panel. The status bar contains information such as cursor position, file save status, download status and syntax error/download messages. The example in Figure 3.3 indicates that the source code tokenized successfully. Figure 3.3: Status Bar beneath the Main Edit Pane. Each editor pane can be individually split into two views of the same source code. This can be done via the Split button on the toolbar, pressing Ctrl-L, or clicking and dragging the top or bottom border of the editor pane with the mouse. Once split, the top and bottom edit controls allow viewing of different areas of the same source code; this can be handy when needing to keep variable declarations or a particular routine in view while modifying a related section of code elsewhere. Note that the Split button and Ctrl+L shortcut act like a toggle function, splitting or un-splitting the edit pane. Page 36 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com SPLIT WINDOW VIEW. 3: Using the BASIC Stamp Editor Figure 3.4: The Split Edit Pane Feature displaying the beginning and end of a long program at the same time. SYNTAX HIGHLIGHTING. NOTE: a complete list of reserved words can be found in Appendix B. Within the edit pane, BASIC Stamp source code files are displayed with syntax highlighting. Syntax Highlighting applies designated colors and character case (upper, lower, capitalized) to reserved words in the PBASIC language . This happens automatically as you type. Table 3.1 shows the default syntax highlighting settings for each syntax element. If you copy and paste a program into a blank edit pane, select Run → Syntax Check or click on the toolbar checkmark icon to activate the syntax highlighting in that file. The syntax highlighting settings can be changed or customized via the Preferences → Editor Appearance tab; for details see the Setting Preferences section which begins on page 55. Source code can be printed to paper with the active syntax highlighting (and in color if using a color printer). BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 37 Using the BASIC Stamp Editor Syntax Element Command Comment Constant -Binary Constant - Decimal Constant - Hexadecimal Constant – Predefined Constant – String Operators Declaration Directive, Conditional Compile Directive, Editor Directive, Target module Input/Output Formatter Selection Search match Variable modifier Variable – predefined Variable, type Text Color Blue Green Default Default Default Purple Red Default Default Gray(Bold) Teal (Bold) Teal (Bold) Navy White on Navy Lime on black Default Purple Default Character Case Upper Case No Change No Change No Change No Change Upper case No Change Upper case Upper Case Upper case Upper case Upper case Upper case No change No change Upper case Upper case Capitalize Automatic line numbers can be enabled or disabled via the “Show Line Numbers” checkbox on the Preferences → Editor Appearance tab. Line numbers, when enabled, appear in a gutter (the gray area on the left of the edit pane as shown in Figure 3.5). When printing, the line numbers may be included if desired. Table 3.1: Syntax Highlighting Defaults for the PBASIC Scheme. NOTE: The default edit pane has a white background with black characters. AUTOMATIC LINE NUMBERING. Figure 3.5: Automatic Line Numbering appears in the gutter to the left of the edit pane. Yellow Bookmarks are visible on lines 5 and 9. Bookmarks can be enabled or disabled via the “Show Bookmarks” checkbox on the Preferences → Editor Appearance tab. The bookmarks appear in the gutter as small numbered icons, providing a way to mark lines or sections of code that you need to navigate to quickly or repeatedly. You can define up to nine bookmarks by clicking on the gutter where you want one placed, or by pressing Ctrl+B when the cursor is on the desired line. You can instantly navigate to any defined bookmark by pressing Ctrl+(#) (where # can be the 1 through 9 keys) or by selecting Go To Page 38 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com BOOKMARKS. 3: Using the BASIC Stamp Editor Bookmark from either the Edit menu or from the shortcut menu (rightclick) in the edit pane. EDITING YOUR CODE. Table 3.2: Keyboard Shortcuts for Editing and Navigation Functions. You can navigate through and edit your code in the edit pane with keyboard shortcuts, most of which will be familiar to Windows users. Shortcut Key Ctrl+A Ctrl+B Ctrl+(#) Ctrl+C Ctrl+F Ctrl+L Ctrl+N Ctrl+V Ctrl+X Ctrl+Y Ctrl+Shift+Y Ctrl+Z Ctrl+Shift+Z Tab Shift+Tab F3 F4 Ctrl+F4 Ctrl+Home Ctrl+End Ctrl+PageUp Ctrl+PageDown Ctrl+CursorUp Ctrl+CursorDown F5 Editing and Navigation Functions Function Select all text in current source code Set or clear bookmark on current source code line Go to bookmark #, where # can be 1 through 9 Copy selected text to the clipboard Find or replace text Split or un-split edit pane Insert line Paste text from clipboard to selected area Cut selected text to the clipboard Delete current line of code Delete from cursor to end of current line Undo last action (unlimited) Redo last action (unlimited) Indent block (Inserts tab or space characters) Outdent block (Deletes tab or space characters) Find text again Replace current found selection Perform replace and find next Jump to top of file Jump to end of file Jump to top of screen Jump to bottom of screen Move source view up one line without moving cursor Move source view down one line without moving cursor Open Preferences window Some editing functions, specifically Cut, Copy, Paste, and Find/Replace, can also be accessed from the edit pane’s shortcut menu (by right-clicking in the edit pane). THE FIND/REPLACE WINDOW. The Find/Replace window allows you to set several search parameters. Match whole or partial words, match case, and match with wildcard options can be used singly or together. You can begin your search at the cursor or at the top or bottom of the selection or the entire file, and search in the forward (downward) or backward (upward) direction. You may replace a single instance of a given item or all instances at once. Recent BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 39 Using the BASIC Stamp Editor Find and Replace items are saved in the Find: and Replace: field’s dropdown lists. Figure 3.6: The Find/Replace Window. The Find/Replace window will stay visible when using the Find Next and Replace options for quick and convenient source code editing. Using the Replace All function, however, will close the Find/Replace window and perform the designated find/replace operation. The integrated explorer panel to the left of the main edit pane is divided in to four portions: the Recent, Directory, File and Filter lists. The upper portion is the Recent list, a drop-down list of default, favorite, and recently visited directories. If you select a directory from the Recent list drop down field, the integrated explorer will automatically navigate to that directory. The button to the left of the Recent list allows you to limit the Directory list display below it to only the directories that are in the Recent list. This makes it easy to find your commonly used source code directories among a large set of directories and local and network hard drives. The Recent list button behaves like a toggle switch: 1) selecting it switches to the “Show Recent folders only” mode, 2) selecting it again switches back to the “Show all folders” mode. Page 40 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com THE INTEGRATED EXPLORER PANEL. 3: Using the BASIC Stamp Editor Figure 3.7: The Integrated Explorer Panel’s Recent list (top), Directory list (middle), and File list (bottom). THE DIRECTORY LIST. The Directory list, right below the Recent list, displays drives and directories in a hierarchical tree fashion. If a directory is selected, the Folders list displays the files in that directory. THE FILE LIST. The File list, below the Directory list, displays all the files in the selected directory that match the selected filter (from the Filter list at the bottom. see Figure 3.8). You can select one or more files from this list and doubleclick, or drag-and-drop them over the editor pane, to open those files. OPEN FROM... AND SAVE TO... OPTIONS. You may also open files with the Open From... option by selecting File → Open From, or by pressing Ctrl+Shift+O. This allows quick access to any directory for the default and favorite directories set within Preferences (see page 60) as well as any recently used directory. The Save To... option works similarly; select File → Save To or press Ctrl+Shift+S. These features can be very helpful if you organize your files in many different directories. THE FILTERS LIST. The Filter list at the bottom of the explorer panel (Figure 3.8), is a dropdown list of file extension filters to apply to the File list. It works just like the “Save as type:” field of a standard Open or Save dialog. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 41 . Using the BASIC Stamp Editor Figure 3.8: The Filter List found at the bottom of the Integrated Explorer Panel. The BASIC Stamp Editor automatically associates BASIC Stamp source code file types (.bs1, .bs2, .bse, .bsx, .bsp, .bpe, and .bpx) with itself. This feature can be configured through automatic prompts or through the Preferences → Files & Directories tab. Also, when using any Explorershell for file browsing, right-clicking on a BASIC Stamp source code file provides you with an Open With Stamp Editor option. The integrated explorer panel can be resized via the vertical splitter bar that separates it and the edit pane. The Directory list and File list can be resized via the horizontal splitter bar that separates them. The integrated explorer can also be hidden or shown via the Explorer toolbar button, by pressing Ctrl+E, or by resizing it to zero width using the vertical splitter bar. Table 3.3 lists keyboard shortcuts for several file functions. File Functions Shortcut Key Ctrl+E Ctrl+L Ctrl+O Ctrl+Shift+O Ctrl+S Ctrl+Shift+S Ctrl+P Ctrl+Tab Ctrl+Shift+Tab Function Show/hide explorer panel Show/hide split view in edit pane Open a source code file into edit pane Open a source code file from a recent directory into edit pane Save current source code file to its current location on disk Save current source code file to a recent directory on disk Print current source code Switch to next open file page Switch to previous open file page Page 42 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com Table 3.3: Keyboard Shortcuts for File Functions. 3: Using the BASIC Stamp Editor Compiler Directives COMPILER DIRECTIVES . The BASIC Stamp Editor supports all of the BASIC Stamp models, and all versions of the PBASIC programming language. Compiler directives must be placed in each program to indicate the desired BASIC Stamp model and language version. In addition, it is sometimes useful to target a given program to a particular communication port. The Directive menu contains options for setting the $STAMP, $PBASIC, and $PORT directives. Since the $STAMP and $PBASIC directives are used most often, they are most easily inserted or modified with the toolbar buttons, as shown in Figure 3.9. Figure 3.9: Toolbar icons make it easy to insert or modify $STAMP and $PBASIC directives directly in your program. THE $STAMP DIRECTIVE. FORMAT OF THE $STAMP DIRECTIVE. A $STAMP directive is required in each PBASIC program. The editor determines which BASIC Stamp model to target for compiling and downloading based on this directive. Any code that is missing the $STAMP directive, but whose filename contains a known BASIC Stamp extension (.bs1, .bs2, .bse, .bsx, .bsp, .bpe, .bpx) will be recognized by that extension and an appropriate $STAMP directive will be added automatically when you run, tokenize, view the memory map or download the program. If there is no file extension present, an error message will prompt you to enter a $STAMP directive. You may choose to manually type the $STAMP directive into the program from the keyboard. This line should be entered into your code on a line by itself, usually near the top. Note that the directive appears on a comment line, as indicated by the apostrophe ('). ' ' ' ' ' ' ' {$STAMP {$STAMP {$STAMP {$STAMP {$STAMP {$STAMP {$STAMP BS1} BS2} BS2e} BS2sx} BS2p} BS2pe} BS2px} 'This 'This 'This 'This 'This 'This 'This indicates indicates indicates indicates indicates indicates indicates to to to to to to to use use use use use use use a a a a a a a BASIC BASIC BASIC BASIC BASIC BASIC BASIC Stamp Stamp Stamp Stamp Stamp Stamp Stamp 1 module 2 module 2e module 2sx module 2p module 2pe module 2px module BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 43 Using the BASIC Stamp Editor If you choose to type the $STAMP directive, care must be taken, or it will not be recognized. The directive itself must be enclosed in curly braces, {…}, not parentheses (...) or square brackets [...]. There should not be any spaces between the dollar sign ($) and the word STAMP; however, the directive may contain additional spaces in certain other areas. For example: ' { $STAMP BS2 EXTRA SPACES ARE ALLOWED IN CERTAIN AREAS. } -- or -' {$STAMP BS2} -- and -' {$STAMP BS2 } are all acceptable variations. However: ' {$ STAMP BS2} -- and -' {$STAMPBS2} are not acceptable and will be ignored. If one of the above two lines were entered into the source code, the editor would ignore it and, instead, rely on the extension of the filename to determine the appropriate model. The $STAMP directive is read and acted upon by the BASIC Stamp Windows Editor any time a source code file is loaded, tokenized, downloaded (run) or viewed in the Memory Map. In some cases you may wish to write a program that can run on multiple BASIC Stamp models. In this case, conditional compile directives can be employed that will cause the editor to determine which Basic Stamp model is detected, and then download only those program elements applicable to that model. Many of the demo programs in Chapter 5 use this technique. To read about conditional compilation, see the Advanced Compilation Techniques section which begins on page 68. PROGRAMS FOR MULTIPLE BASIC STAMP MODELS – CONDITIONAL COMPILE. The $PBASIC directive allows you to indicate which version of the PBASIC language to use. At the time of this printing, the options are 1.0, 2.0 and 2.5. If no $PBASIC directive is present in the program, version 1.0 is assumed for BS1 module source code, and version 2.0 is assumed for THE $PBASIC DIRECTIVE. Page 44 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 3: Using the BASIC Stamp Editor any BS2 model source code. A $PBASIC directive is required to use version 2.5, which is compatible with all BS2 models. PBASIC 2.5 has enhanced syntax options for several commands, as well as some additional commands not available in PBASIC 2.0. Table 3.4 shows the number of PBASIC commands that are available in each version of the PBASIC language, on each BASIC Stamp model. Details about the syntax differences among the three versions of PBASIC are denoted by icons in the margins of Chapters 4 and 5; also refer to Table 5.1 on page 124 and individual command syntax descriptions. Table 3.4: Number of Available Commands for each BASIC Stamp Model with each version of the PBASIC language . PBASIC 1.0 PBASIC 2.0 PBASIC 2.5 BS1 32 - BS2 37 42 BS2e 40 45 BS2sx 40 45 BS2p 56 61 BS2pe 56 61 BS2px 58 63 A categorical listing of all PBASIC commands is included at the beginning of Chapter 5, followed by detailed descriptions of each command in alphabetical order. Note that the syntax-highlighting feature of the BASIC Stamp Editor will also adjust to the language version indicated by the $PBASIC directive. The best way to select the $PBASIC directive is to use the toolbar icons, as was shown in Figure 3.9. Like the $STAMP directive, you must use care if you choose to type it in by hand. The syntax is: ' {$PBASIC 1.0} ' {$PBASIC 2.0} ' {$PBASIC 2.5} 'Default when a BASIC Stamp 1 module is detected 'Default when any BASIC Stamp 2 module is detected 'Required for PBASIC 2.5 command set & enhanced syntax If you try to run a program that contains command syntax specific to PBASIC 2.5 without including the corresponding compiler directive, you will probably get an error message. In this case, insert a $PBASIC 2.5 directive and try running the program again. THE $PORT DIRECTIVE. The optional $PORT directive allows you to indicate a specific PC communications port through which to download a program to a BASIC Stamp module. The syntax is as follows: ' {$PORT COM#} where # is a valid port number. When any PBASIC program containing this directive is downloaded, all other ports will be ignored. This directive is especially convenient when using two of the same BASIC Stamp models BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 45 Using the BASIC Stamp Editor (such as two BS2s) on two ports and you have two different PBASIC programs to download (one to each BS2). Without this directive, developing and downloading in this case would be a tedious task of always answering the "which BASIC Stamp?" prompt. The $PORT directive can be automatically inserted or modified by selecting the appropriate port from the Directive → Port menu. The COM ports listed in the Directive → Port menu are automatically updated any time a change is made to the exiting computer hardware or to the available ports list. See the Setting Preferences section which begins on page 55 for more information. Special Functions The Identify function will identify which BASIC Stamp model, if any, is detected on any available communications port. This information is displayed in the Identification window (Figure 3.10), which can greatly aid in troubleshooting your connection to your BASIC Stamp module. Activate this function by selecting Run → Identify, by pressing Ctrl-I, or pressing F6. THE IDENTIFICATION FUNCTION . Figure 3.10: The Identification Window. The Port column shows the available ports (those that the BASIC Stamp Editor is trying to access). You can modify the available Port List by clicking on the Edit Port List button. Modifying this list only affects which ports the BASIC Stamp Editor tries to use; it does not affect which serial ports are installed on your computer. It is recommended that you delete all known modem ports and any problematic ports from this list. Page 46 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 3: Using the BASIC Stamp Editor The Device Type column shows the model of BASIC Stamp found on the respective port. For example, in Figure 3.10 above, the BASIC Stamp Editor found a BS2 on COM port 1 and a BS2sx on COM port 4. The Version column displays the firmware version number of the BASIC Stamp module that was found. NOTE: when using a BS1 Serial Adapter, the Loopback column of the Identification window should always indicate “No”. The Loopback column indicates whether or not a loopback connection was found on the port. The loopback connection is created by BASIC Stamp development boards, such as the Board of Education, across serial port pins 6 and 7 (of a DB9). A “Yes” in this column is an indication that the serial port and serial cable are properly connected to a BASIC Stamp development board. Note that the Loopback column should always indicate “No” when using a BS1 Serial Adapter, regardless of whether or not the adapter is properly connected to a BASIC Stamp development board. The Echo column indicates whether or not a communication echo was detected on the port’s transmit and receive pins (pins 2 and 3). All BASIC Stamp 2 models create this echo naturally, even without power. BASIC Stamp 1 modules do not create this echo. A “Yes” in this column is an indication that the serial port and serial cable are properly connected to a BASIC Stamp 2 (or higher) module, and if using a BASIC Stamp development board, it’s an indication that the module is properly connected to the development board. For all BASIC Stamp 2 models, the Loopback and Echo columns are great for doing some simple connection diagnosis when using a serial port. For example, a Yes in both columns indicates the serial port and serial cable are properly connected and that the BASIC Stamp is properly inserted into its socket. See Table 3.5 below. Note that the Loopback column does not give reliable results when using a USB to serial adapter, or a USB-based development board. Usually this is not an error, and the Loopback status can simply be ignored. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 47 Using the BASIC Stamp Editor Loopback Echo Yes Yes Yes No No Yes No No Interpretation Serial port and serial cable properly connected. BASIC Stamp properly inserted into socket. If no BASIC Stamp is detected, it is probably because the BASIC Stamp is not connected to power. Other causes could be: 1) low battery, 2) Reset pin of BASIC Stamp is connected to Vdd (it should be left disconnected), 3) the BASIC Stamp is damaged or 4) there is some other type of communication error (software or hardware). Serial port and serial cable properly connected to the development board. BASIC Stamp improperly inserted into socket (i.e.: inserted backwards or not inserted at all). Serial port and serial cable may be improperly connected, or you may not be using a standard BASIC Stamp development board. The Echo indicates there may be a BASIC Stamp properly connected to the port (the Loopback is not required for successful connection) or there may be another device connected to the serial port. Serial port and serial cable are not properly connected, or not connected at all, to the BASIC Stamp 2 (and higher) modules. Could also be an indication of a serial port hardware/software problem. When using a BS1 Serial Adapter, this Loopback and Echo is normal and expected. Selecting the “Ignore BS1 Modules unless downloading BS1 source code” checkbox at the bottom of the Identification window optimizes identification speed. All BS2 models can be identified very quickly. For BASIC Stamp 1 modules, the identification process can take as much as five seconds per communications port. Since the Identification function checks all available serial ports for any possible model of BASIC Stamp, the five-second timeout for BS1’s can be very inconvenient, especially if you are not using a BS1. Table 3.5: Using Loopback and Echo to troubleshoot your serial port (DB9) connection. NOTE: When using a USB port, the Loopback column does not give reliable results. Usually this is not an error and the Loopback status can be ignored. SPEED UP IDENTIFICATION WITH THE “IGNORE BS1 MODULES” CHECKBOX. When this checkbox is checked, the Identification function will not attempt to locate BS1 modules, and thus saves time. If, however, you are downloading BASIC Stamp 1 code, the Download function will attempt to locate BS1 modules regardless of the setting of this checkbox. This feature can also be found and modified via the Preferences → Editor Operation tab. Like the Identification function, the Download function provides information to help guide you through the downloading process. After entering the desired source code in the editor window, you may run it in one of three ways: select Run → Run, press Ctrl+R on the keyboard, or click on the “►” toolbar icon. This will tokenize and download the code Page 48 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com THE DOWNLOAD FUNCTION . 3: Using the BASIC Stamp Editor to the BASIC Stamp module (assuming the code is correct and the BASIC Stamp is properly connected). The Download Progress window looks similar to the Identify window with the exception of the additional Download Status progress bar, and the indicator LED by the port transmitting the data. Figure 3.11: The Download Progress Window. If any errors occur, such as communication failure or inability to detect a BASIC Stamp module, you will be prompted appropriately. One possible error occurs when the BASIC Stamp your PBASIC program is targeting does not appear to be connected to the PC (see Figure 3.12). This may be caused, for example, by opening up a BASIC Stamp 1 program (usually has a .bas or .bs1 extension) and trying to download it to a BASIC Stamp 2 module, instead. Figure 3.12: A Download Error message. When this happens, you’ll be prompted to correct the situation, quickly done by clicking on the BS2 button (if you really intended to download to the BS2 in the first place). Keep in mind that programs written for one BASIC Stamp model may not function properly on a different BASIC Stamp model. Click on the More Info button for more detail. NOTE: If you select the BS2 button, as in this example, the editor will modify the BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 49 Using the BASIC Stamp Editor $STAMP directive in the program, notify you of this change and what it means, and then will try to download to the BS2. Another possibility is having two or more of the same BASIC Stamp model connected to the PC. In this case, the editor will prompt you for clarification as to which BASIC Stamp module you want to download to. In this case using a $PORT directive in your code will save you some tedium in repeatedly responding to such prompts. The BASIC Stamp Editor also features a Memory Map that displays the layout of the current PBASIC program. Type Ctrl+M, or press F7, to activate this window. MEMORY MAP FUNCTION. When you activate the Memory Map, the editor will check your program for syntax errors and, if the program’s syntax is okay, will present you with a color-coded map of the RAM and EEPROM. You’ll be able to tell at a glance how much memory you have used and how much remains. Figure 3.13: Memory Map for Demo Program DATA.bs2. The Memory Map is divided into two sections, the RAM map and the EEPROM map. The RAM map shows how much of each register has been allotted to program variables. The RAM legend details how much is used by I/O Pins, Word, Byte, Nibble and Bit variables, and how much is unused. Page 50 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com THE RAM MAP. 3: Using the BASIC Stamp Editor THE EEPROM MAP. The EEPROM map is shown in two scales. The main view is the detailed EEPROM map, which displays the data in hexadecimal format in each location. The condensed EEPROM map is the vertical region on the left that shows a small-scale view of the entire EEPROM; the red square over it corresponds to the scroll bar handle in the detailed EEPROM map and indicates the portion of the EEPROM that is currently visible in the detailed EEPROM map. Checking the Display ASCII checkbox switches the detailed EEPROM display from hexadecimal to ASCII. In this program, the textual data can be read right off the EEPROM map when using this option. Two important points to remember about this map are: 1) it only indicates how your program will be downloaded to the BASIC Stamp module; it does not "read" the BASIC Stamp memory, and 2) for all BS2 models, fixed variables like B3 and W1 and any aliases do not show up on the memory map as memory used. The editor ignores fixed variables when it arranges automatically allocated variables in memory. Remember, fixed and allocated variables can overlap. THE DEBUG TERMINAL. The Debug Terminal window provides a convienent display for data received from a BASIC Stamp during run-time, and also allows for the transmission of characters from the PC keyboard to the BASIC Stamp. The Debug Terminal is automatically opened and configured when a PBASIC program, containing a DEBUG command, is downloaded. You can manually open a Debug Terminal one of three ways: select Run → Debug → New, press Ctrl+D on the keyboard, or click on the Debug Terminal toolbar button. Up to four (4) Debug Terminals can be open at once (on four different ports) and all can be left open while editing and downloading source code. Figure 3.14 below shows the demo program DEBUG_DEBUGIN.bs2 in the edit pane, and the Debug Terminal that opens when this program is run. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 51 Using the BASIC Stamp Editor Figure 3.14: Demo program using the Debug Terminal The text in the Debug Terminal’s Receive pane (blue area) prompts the user to enter a number into the Transmit pane (white area) . After typing the number 10 and pressing Enter, the Receive pane displays the number in decimal, hexadecimal, and binary format as dictated by the program (Figure 3.15). Figure 3.15: Debug Terminal output after entering a number. The fields across the top of the Debug Terminal window allow configuration of the communication port settings. These fields will be automatically configured and disabled if the Debug Terminal was Page 52 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com PORT SETTINGS AND STATUS. 3: Using the BASIC Stamp Editor automatically opened by the editor, however, if manually opened, these fields will be enabled to allow manual configuration. The signal status LEDs turn bright green when activity on the indicated port line is detected. The signal checkboxes (DTR and RTS) can be selected to set or clear the respective output line on the port. The Echo Off checkbox (bottom of window) causes the Receive pane to throw away the characters that arrive in the port’s receive buffer immediately after transmitting characters from the transmit buffer. This produces a cleaner Receive pane display for interactive programs such as the example above. Keep in mind, however, that this feature does not verify that the character it throws away is actually a match to a character that was just transmitted (because data collisions on the port can cause echoed characters to be garbled). You should only use the Echo Off feature in situations where it is required, as it may result in a strange display in certain applications. KEYBOARD SHORTCUTS FOR CODING FUNCTIONS. Table 3.6: Coding Function Keyboard Shortcuts. There are keyboard shortcuts for several coding functions, some of which are unique to the BASIC Stamp Editor. Shortcut Key(s) Ctrl+J F6 or Ctrl+I F7 or Ctrl+T F8 or Ctrl+M F9 or Ctrl+R F11 or Ctrl+D F12 Ctrl+1, Ctrl+2, Ctrl+3, Ctrl+4 Ctrl+` ESC HELP FILES. Coding Functions Function Show code templates. Identify BASIC Stamp firmware. Perform a syntax check on the code and display any error messages. Open Memory Map window. Tokenize code, download to the BASIC Stamp and open Debug window if necessary. Open a new Debug window. Switch to next window (Editor, Debug #1, Debug #2, Debug #3 or Debug #4) Switch to Debug Terminal #1, Debug Terminal #2, etc. if that Terminal window is open. Switch to Editor window. Close current window. The BASIC Stamp Editor includes searchable, indexed help files. Access Help by selecting Help → Contents or Help → Index. Context sensitive help (highlighting a word in the editor and pressing F1 key) is also supported. The help file can remain open in a separate window while using the BASIC Stamp Editor; simply press Alt+Tab to toggle back and forth between the editor and the Help window. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 53 Using the BASIC Stamp Editor Figure 3.16: The Help file contains the complete PBASIC syntax documentation. The current help files contain the entire PBASIC syntax documentation. In addition, the example demo code programs that appear after most command descriptions in Chapter 5 are automatically placed in default directories during the BASIC Stamp Editor v2.2 installation. These programs can be accessed via hyperlinks within the help file. NOTE: The BASIC Stamp Editor Help file requires Microsoft's HTML Help utility and Internet Explorer 4.0 or above (IE 6.0 recommended). The proper version of HTML Help is included with Windows 2000 and Windows XP. On other versions of Windows you may have to install or upgrade your HTML Help utility to properly view the Stamp Editor’s on-line help. The HTML Help upgrade program (hhupd.exe) is included as part of the BASIC Stamp Editor setup program and the editor will automatically prompt you to run it if it determines you need to upgrade. You can download the latest version of Internet Explorer from Microsoft’s web site at www.microsoft.com. Page 54 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com HELP FILES REQUIRE MICROSOFT’S HTML HELP UTILITY. 3: Using the BASIC Stamp Editor TIP OF THE DAY. The Tip of the Day function displays a new message each time you run the BASIC Stamp Editor. There are many useful tips, and you may browse through them any time with the Next Tip and Previous Tip buttons. You may also use the Edit Tips option to change the contents of any tip. All tips are contained in a single file, named Stamp_Tips.txt, that is stored in the editor’s installation directory, usually a path similar to C:\Program Files\Parallax Inc\Stamp Editor v2.2. Figure 3.17: Tip of the Day #24. You can turn this feature off by unchecking the Show Tips on Startup box at the bottom of the window. To access it again, choose Help → Tip of the Day from the menu bar. Setting Preferences The BASIC Stamp Editor allows the user to set preferences for the appearance and operation of many aspects of the application. Select Edit → Preferences, press F5 or click on the Preferences toolbar button to open the Preferences window, where you will see these options organized under 6 tabs. Each tab has a Restore Defaults button in case you make a royal mess of things. EDITOR APPEARANCE PREFERENCES. Under the Editor Appearance tab (Figure 3.18), you can set the font size in the edit pane. The other text attributes, such as background and foreground color, character case, and bold, italic and underline, are controlled by the Syntax Highlighting scheme. There are 3 predefined schemes, and you may also create a custom scheme. Please note that the BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 55 Using the BASIC Stamp Editor preferences are specific to the editor, and are not saved as part of any BASIC Stamp program that you may have open while setting preferences. Figure 3.18: The Editor Appearance Tab under Edit → Preferences. The default font size for the edit pane is 10 point, but there are 12 fixed options ranging from 8 to 40 point. The Editor Font size setting and all the other text attribute settings under this tab will not affect the text in the Debug Terminal. The default scheme is the “PBASIC” scheme, with the syntax highlighting text attributes described above in Table 3.1. The “plain text” scheme is just that – the default foreground and background for all entered text, with no other attributes applied. The “simple” scheme is the same as the “plain text” scheme, except comments appear in green. Both the plain text and simple schemes use the PBASIC scheme defaults for selected text. Page 56 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com SYNTAX HIGHLIGHTING SCHEMES. 3: Using the BASIC Stamp Editor CUSTOMIZED SYNTAX HIGHLIGHTING. To create a custom scheme, select a default scheme you wish to modify, and click on the Copy Scheme button. Then, select (highlight) an element within the Syntax Element list, and apply new Text Attributes with the checkboxes and drop-down menus to the right. As you try various text attributes and color combinations, the Show Preview Example checkbox lets you audition your custom scheme without closing the Preferences window. The BASIC Stamp Editor supports one custom scheme at a time. It can be modified indefinitely, but it cannot be copied. If you again copy a default scheme, you will be asked to confirm that you wish to overwrite your current custom scheme. Under this tab, you will also find checkboxes that allow you to show or hide bookmarks, line numbers, the overwrite cursor, and the toolbar. EDITOR OPERATION PREFERENCES. AUTO INDENTING / UNINDENTING. TAB CHARACTER. Under the Editor Operation tab (Figure 3.19), you may set preferences for automatic indentation and tab behavior. The Auto Indent on Enter option makes it easy to indent nested loops to make code easier to read. The Auto Unindent option enables quick reversal of an indented line by simply using the backspace key, provided that the cursor is to the left of the first character on the line. The editor lets you choose whether a tab character or spaces are inserted into source code whenever you press the Tab key. The default setting, insert space characters upon Tab key presses, is recommended because it enforces the intended formatting regardless of what editor you use to view the code later. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 57 Using the BASIC Stamp Editor In addition to the actual character used for the Tab key, there are three behaviors of tabbing employed by the editor: Smart Tabs, Fixed Tabs and Fixed plus Smart Tabs. TAB BEHAVIOR. Figure 3.19: The Editor Operation Tab under Edit → Preferences. Smart Tabs (Figure 3.20) cause the tab key to move the cursor to a position that is aligned with the nearest break between words in nearby lines above the current line. It has the effect of providing a somewhat intuitive, auto adjusting behavior based entirely on how you have aligned previous lines. SMART TABS. Fixed Tabs (Figure 3.21) cause the tab key to move the cursor to the position indicated by the Fixed Tab Positions field. If the position is already beyond the end of the Fixed Tab Positions list, it moves by a multiple of the distance between the last two positions in that list. For example, with Fixed Tabs set, the default Fixed Tab Positions list will FIXED TABS. Page 58 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 3: Using the BASIC Stamp Editor make the Tab key move the cursor to positions, 3, 5, 7, 9 and 11, then afterwards, 13, 15, 17, 19, etc. (a multiple of two (11 – 9 = 2) after the last listed position. FIXED PLUS SMART TABS. The last option is a mixture of the first two, Fixed plus Smart Tabs (Figure 3.22); it is the default and recommended setting. Fixed plus Smart Tabs will cause the tab key to move the cursor to the position indicated by the Fixed Tab Positions field, or if the position is already beyond the end of that list, it reverts to Smart Tabs behavior. This setting, combined with a carefully configured Fixed Tab Positions field, allows for a fixed level of indenting on the left side of the source code (for executable code blocks), with very flexible indenting to the right of executable code (for comments that appear to the right of code). The default settings provide a quick, single-key method of indenting up to five (5) levels of executable code and easy alignment of multiple lines of comments to the right of that code. Figure 3.20: Smart Tabs. Figure 3.21: Fixed Tabs. Figure 3.22: Fixed plus Smart Tabs. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 59 Using the BASIC Stamp Editor The Fixed Tab Positions list is used to provide a list of desired fixed tab positions (used with Fixed Tabs or Fixed plus Smart Tabs options). The list can be a single number, or a list of comma separated numbers in ascending order. The allowable range is 2 to 512 and the list size is virtually unlimited. When multiple values are entered, the difference between the last two values will be used to set tab positions beyond the last position. For example, in the default list, the last two positions are 9 and 11; resulting in further tab positions of 13, 15, 17, etc. (multiples of 2 after the last specified position). Since source code is usually indented by multiples of two (2) spaces, the default list of 3, 5, 7, 9 and 11 is recommended. THE FIXED TAB POSITIONS LIST. The Default Com Port setting allows you to specify which COM port to download through. If you specify a specific port here, the Identification window will report that it is “ignoring” other known ports. This can be selectively overridden by placing a $PORT directive in the program. If this setting is left on “AUTO”, the default, the editor will open and scan all known ports for the correct BASIC Stamp. The button to the right, labeled ‘...’, opens the a window allowing the known port list to be edited. Modifying the known port list only affects which ports the BASIC Stamp Editor tries to use; it does not affect which serial ports are installed on your computer. It is recommended that you delete all known modem ports and any problematic ports from this list. DEFAULT COM PORT. For an explanation of the Default Project Download Modes, see Table 3.7 on page 70. This is part of a discussion on BASIC Stamp Projects in the Advanced Compilation Techniques beginning on page 68, below. Selecting the “Ignore BS1 Modules unless downloading BS1 source code” checkbox optimizes identification speed by attempting to locate BS1 modules only if you are downloading BASIC Stamp 1 code. This feature can also be activated via the Identification or Download window. Under the Files and Directories tab (Figure 3.23), you can set preferences for saving and accessing files, as well as automatically creating backup copies. Page 60 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com THE FILES AND DIRECTORIES TAB. 3: Using the BASIC Stamp Editor Figure 3.23: The Files and Directories Tab under Edit → Preferences. BACKUP COPY. Check the “Create backup copy” option to cause the editor to automatically create a backup copy of any file that is being re-saved under the same name. The backup file will be stored in the same directory and named the same as the existing file, but with a .bak extension appended to the existing extension. For example, “test.bs2” becomes “test.bs2.bak” and then the new file called “test.bs2” is created from the source code being saved. Note: the .bak files will not appear in the integrated explorer’s file window unless you change the Filter list to show All Files (*.*). FILE ASSOCIATIONS. BASIC Stamp source code file types (.bs1, .bs2, .bse, .bsx, .bsp, .bpe, .bpx) can be associated with the BASIC Stamp Editor. Check the “Verify at startup” option to have the editor verify the proper associations each time it is started. The “Associated files launch into” option changes the way Windows behaves when you open BASIC Stamp source code from any Explorer-shell. Choosing “Single Editor” causes all programs to open up BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 61 Using the BASIC Stamp Editor into a single BASIC Stamp Editor, including an editor that is already running. The “Multiple Editors” option will cause a new BASIC Stamp Editor to open each time you open an associated BASIC Stamp file from any Explorer-shell. Also, by associating BASIC Stamp source code with the editor, Windows will provide an “Open With Stamp Editor” option when right-clicking on that source code from any Explorer-shell. OPEN WITH STAMP EDITOR OPTION. The “New file template” field allows you to specify a file to load each time the File → New function is selected. The file will be loaded into the new edit page, but the name will be set to “Untitled#”; where # is an automatically generated number. This feature provides a convenient way to start every new source code project with a specified code template of your choosing. Note that once this feature is set, you may hold down the Shift key while selecting File → New, or clicking the New File toolbar button, to suppress the loading of the code template and thus end up with a blank edit page. NEW FILE TEMPLATE FEATURE. The “Upon startup, initial directory is” field affects what directory is initially selected in the integrated explorer and the Open and Save As dialog boxes when the editor is started. The default is “Last Used,” meaning the initial directory will be that which was most recently used by the editor. If this setting is changed to “Set Via Shortcut” the editor will initially view the directory indicated by the “Start in” field of the Windows shortcut that launched the editor. The other options include the default module directories and favorite directories. INITIAL DIRECTORY ON STARTUP. The Module Directories list contains a list of module-specific directories that are called the “default module directories.” Upon installation of the BASIC Stamp Editor software, the PBASIC source code examples in this text are copied to the installation folder and organized into appropriate subfolders. If the default installation folder is used during software installation, the source code files will be copied to a path similar to: C:\Program Files\Parallax Inc\Stamp Editor 2.2\BS1, BS2, BS2sx..., etc. The BASIC Stamp Editor automatically sets its default directories to point to these source code examples, making them immediately available via the File → Open From… and File → Save To... menus as well as the Recent list in the integrated explorer panel. MODULE DIRECTORIES. Page 62 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 3: Using the BASIC Stamp Editor You may use the Clear and Browse… buttons under the Module Directories list to select new default directory locations for each model of BASIC Stamp. These new folders will then appear as options when you use the File → Open From... and File → Save To... menus as well as the Recent list in the integrated explorer panel. Note that if you are upgrading from a previous version of the BASIC Stamp Editor and you have set your own default directories, they will not be replaced with the new source code example directories. Upon opening the editor, only default directory options that are blank will be redirected to the source code examples. FAVORITE DIRECTORIES. The Favorite Directories list allows you to add and delete folder locations that will appear as additional options in the File → Open From... and File → Save To... menus as well as the Recent list in the integrated explorer. It works in a similar way as the Module Directories list; however, you can set your own descriptive names for those folders. DEBUG APPEARANCE PREFERENCES. Under the Debug Appearance tab (Figure 3.24) you can set the color and size of the various Debug Terminal elements; settings apply to all the Debug Terminal windows at once. A Debug Terminal itself can be resized and/or moved by simply clicking and dragging the window; each window’s size and position is remembered even after closing the editor. THE CHOOSE... BUTTONS. The Choose… buttons allow you to change the background and font color of both the Transmitter and Receiver panes, independently. The font size of both panes can be changed to one of 8 sizes: 6, 8, 10, 12, 14, 18, 24, and 36. The Debug Terminal font size is independent of the font size in the main editor window. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 63 Using the BASIC Stamp Editor Figure 3.24: The Debug Appearance Tab under Edit → Preferences. The “Wrap Text to” field gives two options, Pane and Page. Wrapping to Pane is the default, and causes text to wrap at the right edge of the Receiver pane, reflecting the current visible size that the user happens to have set for the Debug Terminal’s window. Wrapping to Page, however, causes text to wrap at a specific line width, regardless of the user’s current Debug Terminal window size. The “Page width (characters)” field is enabled when wrap mode is set to Page. The default page width is 32, characters and the range is 32 to 128. Note: wrapping to page can be handy to maintain formatting of formatted tabular information, but could lead to information being displayed off the edge of the Receive pane if the Debug Terminal is sized too small. TEXT WRAPPING IN THE DEBUG TERMINAL. The maximum Receive pane buffer size is defined in terms of lines. It can be set to any power of two between 256 and 8192; 1024 is the default. Data received by the Debug Terminal is maintained in this buffer for display on MAXIMUM BUFFER SIZE. Page 64 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 3: Using the BASIC Stamp Editor the screen. If the default is used, for example, you could receive 1024 lines worth of text from a BASIC Stamp, and still be able to scroll back and view the first line that was received. Upon receiving the 1025th line of text, the first line of text is pushed out of the buffer and is lost for good, making the first visible line in the Receive pane actually be the 2nd line of text that was received. Larger buffer sizes consume more PC memory (256 * buffer_size * Number_of_Open_Debug_Terminals bytes), so it is best to set it only as high as you need it for your application. The Tab size can be adjusted as well, anywhere from 3 to 16 character spaces. The default is 8. Keep in mind that most people don’t change this value, so writing code that relies on a particular setting other than 8 may display improperly on other user’s Debug Terminals. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 65 Using the BASIC Stamp Editor Under the Debug Function tab (Figure 3.25), checkboxes allow enabling or disabling of special processing for 16 different control characters. The default is for all 16 control characters to be processed, but you may disable one or more of them if you are using the Debug Terminal to view data coming from a device other than a BASIC Stamp. DEBUG FUNCTION PREFERENCES. Figure 3.25: The Debug Function Tab under Edit → Preferences. For example, a device that sends out a 0 to indicate something other than Clear Screen will cause unintentional clearing of the Receive pane; unchecking the checkbox for “(0) = Clear Screen” will prevent this from happening. Page 66 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 3: Using the BASIC Stamp Editor DEBUG PORT PREFERENCES. Under the Debug Port tab (Figure 3.26), each of the four (4) Debug Terminal’s default COM port settings may be configured separately. These settings are only used when the Debug Terminal is manually opened. Figure 3.26: The Debug Port Tab under Edit → Preferences. You may assign a specific COM port from the available drop-down list; this list can be changed by clicking on the (...) button to the right. Note that any Debug Terminals that are opened automatically after a PBASIC program is downloaded will always default to the COM port and settings used during download. If NONE is selected as the COM port, the manually opened Debug Terminal will not open any port upon startup, so you will have to manually select the desired COM port from the Debug Terminal window each and every time you open that Debug Terminal. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 67 Using the BASIC Stamp Editor Advanced Compilation Techniques For BS2e, BS2sx, BS2p, BS2pe and BS2px modules, each editor page can be a separate project, or part of a single project. A project is a set of up to eight files that should all be downloaded to the BASIC Stamp for a single application. Each of the files within the project is downloaded into a separate "program slot". Only the BASIC Stamp 2e, 2sx, 2p, 2pe, and 2px modules support multi-file projects. INTRODUCTION TO BASIC STAMP PROJECTS. For BASIC Stamp projects (consisting of multiple programs), the $STAMP directive has an option to specify additional filenames. The syntax below demonstrates this form of the $STAMP directive: USING THE $STAMP DIRECTIVE TO DEFINE MULTI-FILE PROJECTS. ' { $STAMP BS2e, file2, file3, …, file8 } Use this form of the $STAMP directive if a project, consisting of multiple files, is desired. This form of the directive must be entered only into the first program (to be downloaded into program slot 0). The file2, file3, etc. items should be the actual name (and optionally the path) of the other files in the project. File2 refers to the program that should be downloaded into program slot 1, file3 is the program that should be downloaded into program slot 2, etc. If no path is given, the filename is given the path of program 0 when loading them into the editor. Up to seven filenames can be included, bringing the total to eight files in the project all together. Upon loading, tokenizing, running or viewing program 0 in the Memory Map, the editor will read the $STAMP directive, determine if the indicated files exist, will load them if necessary and change their captions to indicate the project they belong to and their associated program number. After the directive is tokenized properly, and all associated files are labeled properly, tokenizing, running or viewing any program in the Memory Map will result in that program’s entire project being tokenized, downloaded or viewed. When program #0 of a multi-file project is opened from diskette, the entire project will be loaded (all referenced files) as well. When a file that is part of a multi-file project is closed, the entire project (all the associated files) will be closed as well. Page 68 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 3: Using the BASIC Stamp Editor EASY STEPS TO CREATING MULTI-FILE PROJECTS. To create a project consisting of multiple files, follow these steps: 1. 2. Create the first file in the editor and save it (we'll call it Sample.bsx). This will be the program that is downloaded into program slot 0. Create at least one other file in the editor and save it also (we'll call it NextProgram.bsx). Note: At this point the editor tabs will be: 0:Sample.bsx and 0:NextProgram.bsx. indicating that there are two unrelated files open "Sample.bsx" and "NextProgram.bsx" and each will be downloaded into program slot 0. 3. Go back to the first program and enter or modify the $STAMP directive using the project format. Use "NextProgram" as the File2 argument. For example: ' {$STAMP 4. BS2sx, NextProgram.bsx} Then tokenize the code by pressing F7 or selecting Run → Check Syntax from the menu. At this point, the BASIC Stamp Editor will see the $STAMP directive and realize that this file (Sample.bsx) is the first file in a project and that the second file should be NextProgram.bsx. It will then search for the file on the hard drive (to verify its path is correct), will see that it is already loaded, and then will change the editor tabs to indicate the project relationship. At this point the editor tabs will be: 0:Sample.bsx and [Sample] 1:NextProgram.bsx. indicating that there are two related files open; "Sample.bsx" and "NextProgram.bsx". NextProgram.bsx belongs to the "Sample" project and it will be downloaded into program slot 1 and Sample.bsx will be downloaded into program slot 0. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 69 Using the BASIC Stamp Editor The editor has the ability to treat projects as one logical unit and can download each of the associated source code files at once. In order to minimize download time for large projects a Project Download Mode is available in the Preferences window. The available modes are: “Modified” (the default), “All” or “Current” and are explained below. This item only affects download operations for the BS2e, BS2sx, BS2p and BS2pe. See Table 3.7. Download Mode Modified (default) All Current Function This mode will cause only the source code files that were modified since the last download to be downloaded next time. If no files have been modified since the last download, or the entire project has just been loaded into the editor, all the files will be downloaded next time. This mode decreases the delay during downloading projects and should help speed development and testing. This mode will cause all the source code files to be downloaded each time. This will be noticeably slow with large projects. This mode will cause only the current source code file to be downloaded, ignoring all the others. This mode can be helpful, but can lead to development errors if you forget to download a required program. PROJECT DOWNLOAD MODES. Table 3.7: Project Download Modes. Regardless of the download mode selected, the programs will be downloaded into the program slot indicated in their tab. Some source code may be suitable for multiple uses but requires changing a set of constants as needed for each case. For example, you may want to run the same program on a BS2 and a BS2sx, but the resolution of timesensitive commands is different, requiring slight code modifications. Several conditional compile directives exist in PBASIC 2.5 to assist with this situation. Table 3.8 lists the available directives. Directive #DEFINE #IF...#THEN...#ELSE #SELECT...#CASE #ERROR Function Allows the programmer to create custom symbols for use within conditional compilation control structures. Evaluate Condition and, if it is True, compile the statement(s) following #THEN, otherwise compile the statements following #ELSE. Evaluate Expression and then conditionally compile a block of code based on comparison to Condition(s). If no conditions are found True and a #CASE ELSE block is included, the #CASE #ELSE code statements will compiled. Allows the programmer to create a custom error dialog. Page 70 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com CONDITIONAL COMPILE DIRECTIVES. Table 3.8: Conditional Compile Directives. NOTE: These directives require PBASIC 2.5. 3: Using the BASIC Stamp Editor Lets look at the syntax and examples for each conditional compile directive. For an explanation of syntax conventions, see page 128. #DEFINE SYNTAX. #DEFINE Symbol { = Value } #DEFINE allows the programmer to create custom, compile-time, symbols for use within conditional compile control structures. • Symbol is a unique symbol name that will optionally represent a Value. • Value is an optional constant/expression specifying the value of Symbol. If the value parameter is omitted, Symbol is defined as true (-1). Example: ' {$PBASIC 2.5} #DEFINE DebugMode #IF DebugMode #THEN DEBUG "Debugging." STOP In the example above, the #DEFINE statement defines DebugMode to be “true” (-1), since there is no Value argument provided. The second line is another conditional compile statement, #IF…#THEN (see below for more information) which evaluates the state of DebugMode, determines it is true and then allows the following DEBUG statement to be compiled into the program. The last line, STOP, is compiled into the program afterwards. The result of compiling this example is a program with only two executable statements, DEBUG "Debugging", CR and STOP. The real power of this example, however, is more obvious when you comment out, or remove, the #DEFINE line. Look at the next example, below: ' {$PBASIC 2.5} ' #DEFINE DebugMode #IF DebugMode #THEN DEBUG "Dubugging." STOP Here we commented out the #DEFINE line, effectively removing that line from the program. This means that the symbol DebugMode will be undefined, and undefined conditional compile symbols are treated as BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 71 Using the BASIC Stamp Editor False (0). Upon compiling this example, the #IF…#THEN statement will evaluate DebugMode, which is False (because it is undefined) and then will not allow the DEBUG statement to be compiled. Only the STOP command will be compiled into the program in this example. This is a very powerful feature for quickly removing many DEBUG statements (or other statements) from a program when you’re done developing it, but leaving the possibility of re-enabling all those statements should further maintenance be required at a later time. The optional Value argument can be used, for example, to select modes of operation: ' {$PBASIC 2.5} #DEFINE SystemMode = 2 #IF SystemMode = 1 #THEN HIGH 1 #ELSE LOW 1 #ENDIF In the example above, the first line defines SystemMode to be equal to 2. The #IF…#THEN statement evaluates the state of SystemMode, determines it is 2, so the condition is false, and then it skips the statement after #THEN and allows the statement following #ELSE to be compiled into the program. Note, conditional compile directives are evaluated just before the program is compiled, so variables and named constants cannot be referenced within a conditional compile definition. Compile-time symbols created with #DEFINE can, however, be referenced by conditional compile commands. #IF Condition(s) #THEN Statement(s) { #ELSE Statement(s) } #ENDIF Page 72 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com #IF...#THEN SYNTAX. 3: Using the BASIC Stamp Editor #IF…#THEN is a conditional compile structure similar to the run-time IF…THEN command except that, at compile time, #IF…#THEN evaluates Condition(s) and, if it is True, compiles the Statement(s) following #THEN, otherwise it compiles the Statement(s) following #ELSE. • Condition is a statement that can be evaluated as True or False during compile-time. • Statement is any valid PBASIC instruction. Example: ' {$PBASIC 2.5} ' set Baud for 9600-N81 #IF ($STAMP = BS2sx) OR ($STAMP = BS2p) #THEN Baud CON 16624 #ELSE #IF ($STAMP = BS2px) Baud CON 16780 #ELSE Baud CON 16468 #ENDIF #ENDIF In this example, the constant Baud is set to an appropriate value for the BASIC Stamp that is specified in the $STAMP directive (not shown). This code will work with the BS2, BS2e, BS2sx, BS2p, BS2pe, and BS2px. One important thing to note is that the $STAMP directive is used here as a compile-time symbol, as if it were defined by #DEFINE. The compiler treats all the editor directives, $STAMP, $PBASIC and $PORT as “defined” compile-time symbols set equal to the respective value used in their declaration. At the time of this writing, using $PBASIC in this fashion is pointless since the conditional-compile directives are only supported in PBASIC 2.5, and would cause an error if compiled in any other version of the language. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 73 Using the BASIC Stamp Editor #SELECT...#CASE SYNTAX. #SELECT Expression #CASE Condition(s) Statement(s) { #CASE Condition(s) Statement(s) #CASE #ELSE Statement(s) } #ENDSELECT #SELECT…#CASE is a conditional compile structure similar to the runtime SELECT…CASE command except that, at compile time, #SELECT…#CASE evaluates Expression and then conditionally compiles a block of code based on comparison to Condition(s). If no Conditions are found to be True and a #CASE #ELSE block is included, the Statement(s) in the #CASE #ELSE block will be compiled. • Expression is a statement that can be evaluated as True or False during compile-time. • Condition is a statement, that when compared to Expression, can be evaluated as True or False. Multiple conditions within the same CASE can be separated by commas ( , ). • Statement is any valid PBASIC instruction. Example: ' {$PBASIC 2.5} #SELECT $STAMP #CASE BS2, BS2e, BS2sx GOSUB LCD_Write #CASE #ELSE LCDOUT LCDpin, cmd, [char] #ENDSELECT This example checks the $STAMP directive at compile-time and either compiles GOSUB LCD_Write - or – LCDOUT LCDpin, cmd, [char] into the program. Page 74 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 3: Using the BASIC Stamp Editor #ERROR SYNTAX. #ERROR Message #ERROR displays a compile-time error. This allows the programmer to flag fatal errors during compilation. • Message is the error message string, enclosed in quotes. Example: ' {$PBASIC 2.5} #DEFINE I2CReady = (($STAMP = BS2p) OR ($STAMP = BS2pe) OR ($STAMP = BS2px)) #IF NOT I2CReady #THEN #ERROR "BS2p, BS2pe, or BS2px is required for this program." #ENDIF When compiled, this example will cause the editor to halt compilation and display the dialog below if you attempt to compile for a BASIC Stamp model other than the BS2p, BS2pe, or BS2px: Figure 3.27: Custom Error Message using the #ERROR directive. Features for Developers The BASIC Stamp Editor has several features that are designed to support the needs of developers. Note: when installing the BASIC Stamp editor, you can instruct the installer to include additional developer resources by selecting the “Custom” option from the “Setup Type” prompt. GENERATE OBJECT CODE FEATURE. The Generate Object Code feature allows you to tokenize a PBASIC program and save it to a file in the tokenized form. This allows you to send your BASIC Stamp object code (the actual binary data that is downloaded to the BASIC Stamp module) to other people without having to reveal your PBASIC source code. If you are a developer who has BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 75 Using the BASIC Stamp Editor customers using BASIC Stamp-based products, you can release firmware updates to them in this manner. Object code can be saved as a separate .obj file (downloadable with the StampLoader.exe program) or as a single executable (integrated with the StampLoader.exe inside of it). The single executable method provides a simpler way to pass your firmware update on to your customers. Any syntactically correct PBASIC source code can be used with the Generate Object Code feature; this includes BS1 and BS2 code as well as BS2e, BS2sx, BS2p, BS2pe, and BS2px code that is either a single file or a multi-file project. Note: The original DOS-based software for the BS1 included a directive called BSAVE; when used it would cause the software to generate an object file. In the BASIC Stamp Windows Editor, the Generate Object Code feature replaces and enhances the BSAVE feature; the reserved word BSAVE is still accepted in BS1 source code, but is simply ignored. Old BS1 object code saved via the BSAVE option is not compatible with the StampLoader.exe program so you must regenerate the object file using the BASIC Stamp Windows Editor. If you don’t have the StampLoader.exe program, it can be automatically generated for you by selecting the second output file option, “Object Code and Stamp Loader”, in the Generate Object Code window. Additionally, firmware, product, company and related info can be embedded in the object code or single executable file for your customers to view before downloading. Page 76 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 3: Using the BASIC Stamp Editor Figure 3.28: The Generate Object Code Window. In the example above, we chose to generate a single executable with custom names and messages as shown. Then we clicked the Generate… button (which prompted us for a file name) and the file was created. When a user runs the file we just generated, they see a screen similar to the figure below: Figure 3.29: Example customized StampLoader.exe file. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 77 Using the BASIC Stamp Editor Another feature of interest to some developers is the BASIC Stamp Editor’s Command Line interface. This interface provides for command line, batch file or third-party driven control of the editor. The Stampw.exe program is a Win32 application that can be run through any standard method. When run with the command-line options, however, it provides special features that developers and product manufacturing managers may find useful. While this program can be run from a command prompt on a Windows system, it will not work on a DOS-only system. The Stampw.exe supports redirection of its input and output via the standard pipe mechanisms. If its output is redirected via the commandline (ex: Stampw.exe myfile.bs2 > Test1.txt) the designated output file, Test1.txt in this case, will be created and various information about the processing of the source file will be stored there. This information directly reflects the information available on the GUI prompts, interactions with the user and downloading status. This feature can be combined with the /NoDebug and /NoPrompts switches for various levels of GUI interaction with the user; including completely hidden operation. The following is the syntax of the BASIC Stamp Editor’s command-line switches. Stampw.exe {/Com#} {{/ReadOnly} source_file} Stampw.exe {/Com#} /Download {/Updates}{/NoDebug}{/NoPrompts} source_file > output_file Stampw.exe {/Com#} /Identify {/NoPrompts} > output_file Stampw.exe /Tokenize source_file > output_file Stampw.exe /Pipe master_file Stampw.exe /Help Table 3.9 gives a function description for each command-line switch. Page 78 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com COMMAND LINE INTERFACE. 3: Using the BASIC Stamp Editor Table 3.9: Command Line Switches Command /Com# /ReadOnly /Identify /Tokenize /Download /Updates /NoDebug /NoPrompts /Pipe master_file /Help Function Specify com port (serial port) to download to. # is a valid com port number. NOTE: must be one word, i.e.: Com2 indicates com port 2. Open source_file in read-only mode. The Ctrl key acts as a download key when in read-only mode. Requires source_file argument. This command option is not available if double-piped communication is established. Identify BASIC Stamp modules on COM ports. Requires redirection to output_file. Tokenize source code. No prompts will be displayed. Requires source_file argument and redirection to output_file. Tokenize source code, and download it (if tokenization successful). Requires source_file argument and redirection to output_file. Provides program slot number (if applicable) and download-percentagecomplete status updates during download. No Debug Terminal opens after downloading (even if code contains DEBUGs) and COM port is immediately closed after downloading. This option requires /Download switch. Note: This switch will have no effect if Debug Terminal is already open from a previous operation. No screen prompts at all (except for Debug Terminal). This option requires /Download switch. Start up master_file (must be .exe) and establish bi-directional communication pipes (double-piped communication) for master-programcontrolled execution. Stampw.exe remains open until master_file breaks pipe. This command option is not available once double-piped communication is established. Display command-line help. This command option is not available if doublepiped communication is established. When the output of the BASIC Stamp Editor is piped to a file or a master program, it displays all of its messages in a specific, predefined format. Each message has a unique 3-digit number. Detailed information about the use of command-line options, including a table of all messages with their ID numbers, can be found in the “What’s New in Stamp.exe” document included with the typical installation of the Stamp Editor. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 79 Using the BASIC Stamp Editor Page 80 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 4: BASIC Stamp Architecture – Memory Organization BASIC Stamp Architecture Introduction This chapter provides detail on the architecture (RAM usage) and math functions of the BS1, BS2, BS2e, BS2sx, BS2p, BS2pe, and BS2px. The following icons will appear to indicate where there are differences among the various BASIC Stamp models: One or more of these icons indicates the item applies only to the BS1, BS2, BS2e, BS2sx, BS2p, BS2pe, or BS2px respectively. All 2 If an item applies to the all of the models in the BS2 family, this icon is used. 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. MEMORY ORGANIZATION An important distinction between RAM and EEPROM is this: • • RAM ORGANIZATION (BS1) THE INPUT/OUTPUT VARIABLES. 1 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 BS1 has 16 bytes (8 words) of RAM space arranged as shown in Table 4.1 The first word, called PORT, is used for I/O pin control. It consists of two bytes, PINS and DIRS. The bits within PINS correspond to each of the eight I/O pins on the BS1. Reading PINS effectively reads the I/O pins directly, returning an 8-bit set of 1's and 0's corresponding to the high and low state of the respective I/O pin at that moment. Writing to PINS will store a high or low value on the respective I/O pins (though only on pins that are set to outputs). The second byte of PORT, DIRS, controls the direction of the I/O pins. Each bit within DIRS corresponds to an I/O pin's direction. A high bit (1) BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 81 BASIC Stamp Architecture – Memory Organization sets the corresponding I/O pin to an output direction and a low bit (0) sets the corresponding I/O pin to an input direction. The remaining words (W0 – W6) are available for general-purpose use. Each word consists of separately addressable bytes and the first two bytes (B0 and B1) are bit addressable as well. You may assign other names (symbols) to these RAM registers as shown in section "Defining and Using Variables", below. When the BS1 is powered up, or reset, all memory locations are cleared to 0, so all pins are inputs (DIRS = %00000000). Also, if the PBASIC program sets all the I/O pins to outputs (DIRS = %11111111), then they will initially output low, since the output latch (PINS) is cleared to all zeros upon power-up or reset, as well. Word Name PORT W0 W1 W2 W3 W4 W5 W6 Byte Names PINS DIRS B0 B1 B2 B3 B4 B5 B6 B7 B8 B9 B10 B11 B12 B13 Bit Names PIN0 – PIN7 DIR0 – DIR7 BIT0 – BIT7 BIT8 – BIT15 Special Notes I/O pins; bit addressable. I/O pins directions; bit addressable. Bit addressable. Bit addressable. Table 4.1: BS1 RAM Organization. Note: There are eight words, consisting of two bytes each for a total of 16 bytes. The bits within the upper two words are individually addressable. Used by GOSUB instruction. Used by GOSUB instruction. The BS2, BS2e, and BS2sx models have 32 bytes of Variable RAM space arranged as shown in Table 4.2. 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. The BS2p, BS2pe, and BS2px models have an extra set of INS, OUTS, and DIRS registers for a total of 38 bytes of variable RAM. These are “shadow” registers that are switched in and out of the memory map with the AUXIO, MAINIO, and IOTERM commands. While this feature exists in Page 82 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com RAM ORGANIZATION. 4: BASIC Stamp Architecture – Memory Organization the variable RAM for these models, only the BS2p40 module has the extra 16 I/O pins for which this feature is intended. THE INPUT/OUTPUT VARIABLES. The word variable INS is unique in that it is read-only. The 16 bits of INS reflect the state of I/O pins P0 through P15. It may only be read, not written. OUTS contains the states of the 16 output latches. DIRS controls the direction (input or output) of each of the 16 I/O pins. A 0 in a particular DIRS bit makes the corresponding pin an input and a 1 makes the corresponding pin an output. So if bit 5 of DIRS is 0 and bit 6 of DIRS is 1, then I/O pin 5 (P5) is an input and I/O pin 6 (P6) is an output. A pin that is an input is at the mercy of circuitry outside the BASIC Stamp; the BASIC Stamp cannot change its state. A pin that is an output is set to the state indicated by the corresponding bit of the OUTS register. When the BASIC Stamp is powered up, or reset, all memory locations are cleared to 0, so all pins are inputs (DIRS = %0000000000000000). Also, if the PBASIC program sets all the I/O pins to outputs (DIRS = %1111111111111111), then they will initially output low, since the output latch (OUTS) is cleared to all zeros upon power-up or reset, as well. Table 4.2: RAM Organization for all BS2 models. NOTE: There are 16 words, of two bytes each for a total of 32 bytes*. All bits are individually addressable through variable modifiers; the bits within the upper three words are also individually addressable though the pre-defined names shown. All registers are word, byte, nibble and bit addressable. *The BS2p, BS2pe, and BS2px have an additional set of INS, OUTS, and DIRS registers that are switched in and out of the memory map in place of the main INS, OUTS, and DIRS registers by using AUXIO, MAINIO, and IOTERM. Only the BS2p40 has the required extra I/O pins this feature is intended for. Word Name INS* OUTS* DIRS* W0 W1 W2 W3 W4 W5 W6 W7 W8 W9 W10 W11 W12 Byte Names INL, INH OUTL, OUTH DIRL, DIRH Nibble Names INA, INB INC, IND OUTA, OUTB OUTC, OUTD DIRA, DIRB DIRC, DIRD Bit Names IN0 – IN7 IN8 – IN15 OUT0 – OUT7 OUT8 – OUT15 DIR0 – DIR7 DIR8 – DIR15 Special Notes Input pins Output pins I/O pin direction control B0, B1 B2, B3 B4, B5 B6, B7 B8, B9 B10, B11 B12, B13 B14, B15 B16, B17 B18, B19 B20, B21 B22, B23 B24, B25 BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 83 BASIC Stamp Architecture – Memory Organization The INS variable always shows the state of the I/O pins themselves, regardless of the direction of each I/O pin. We call this, "reading the pins". If a pin was set to an input mode (within DIRS) and an external circuit connected the I/O pin to ground, the corresponding bit of INS would be low. If a pin was set to an output mode and the pin's state was set to a high level (within OUTS), the corresponding bit of INS would be high. If, however, that same pin was externally connected directly to ground, the corresponding bit of INS would be low; since we're reading the state of the pin itself and the BASIC Stamp cannot override a pin that is driven to ground or 5 volts externally. Note: The last example is an error, is a direct short and can cause damage to the BASIC Stamp! Do not intentionally connect output pins directly to an external power source or you risk destroying your BASIC Stamp. To summarize: DIRS determines whether a pin’s state is set by external circuitry (input, 0) or by the state of OUTS (output, 1). INS always matches the actual states of the I/O pins, whether they are inputs or outputs. OUTS holds bits that will only appear on pins whose DIRS bits are set to output. SUMMARY OF THE FUNCTION OF DIRS, INS AND OUTS. In programming the BASIC Stamp, it’s often more convenient to deal with individual bytes, nibbles or bits of INS, OUTS and DIRS rather than the entire 16-bit words. PBASIC has built-in names for these elements, shown in Table 4.2. Here's an example of what is described in Table 4.2. The INS register is 16bits (corresponding to I/O pins 0 though 15). The INS register consists of two bytes, called INL (the Low byte) and INH (the High byte). INL corresponds to I/O pins 0 through 7 and INH corresponds to I/O pins 8 though 15. INS can also be thought of as containing four nibbles, INA, INB, INC and IND. INA is I/O pins 0 though 3, INB is I/O pins 4 though 7, etc. In addition, each of the bits of INS can be accessed directly using the names IN0, IN1, IN2… IN5. The same naming scheme holds true for the OUTS and DIRS variables as well. As Table 4.2 shows, the BASIC Stamp module’s memory is organized into 16 words of 16 bits each. The first three words are used for I/O. The remaining 13 words are available for use as general-purpose variables. Page 84 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com PREDEFINED "FIXED" VARIABLES. 4: BASIC Stamp Architecture – Defining Variables 2 The 40-pin BS2p uses the first three words for I/O even though it has twice as many I/O pins. This is done with the AUXIO, MAINIO, and IOTERM commands, which effectively switch the auxiliary I/O registers in and out of the INS, OUTS, and DIRS locations. Just like the I/O variables, the general-purpose variables have predefined names: W0 through W12 and B0 through B25. B0 is the low byte of W0; B1 is the high byte of W0; and so on through W12 (B24=low byte, B25=high byte). Unlike I/O variables, there’s no reason that your program variables have to be stuck in a specific position in the BASIC Stamp’s physical memory. A byte is a byte regardless of its location. And if a program uses a mixture of variables of different sizes, it can be difficult to logically dole them out or allocate storage. p More importantly, mixing fixed variables with automatically allocated variables (discussed in the next section) is an invitation to bugs. A fixed variable can overlap an allocated variable, causing data meant for one variable to show up in another! The fixed variable names (of the generalpurpose variables) are only provided for power users who require absolute access to a specific location in RAM. We recommend that you avoid using the fixed variables in most situations. Instead, let PBASIC allocate variables as described in the next section. The editor software will organize your storage requirements to make optimal use of the available memory. Before you can use a variable in a PBASIC program you must declare it. All 2 “Declare” means letting the BASIC Stamp know that you plan to use a variable, what you want to call it, and how big it is. Although PBASIC does have predefined variables that you can use without declaring them first (see previous sections), the preferred way to set up variables is to use the directive SYMBOL (for the BS1) or VAR (for all BS2 models). Here is the syntax for a variable declaration: DEFINING AND USING VARIABLES (VAR). 1 1 SYMBOL name = RegisterName -- or -All 2 name VAR Size where name is the name by which you will refer to the variable, RegisterName is the "fixed" name for the register and size indicates the BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 85 BASIC Stamp Architecture – Defining Variables number of bits of storage for the variable. NOTE: The top example is for the BS1 and the bottom example is for all BS2 models. There are certain rules regarding symbol names. Symbols must start with a letter or underscore, can contain a mixture of letters, numbers, and underscore (_) characters, and must not be the same as PBASIC reserved words, or labels used in your program. Additionally, symbols can be up to 32 characters long. See Appendix B for a list of PBASIC reserved words. PBASIC does not distinguish between upper and lower case, so the names MYVARIABLE, myVariable, and MyVaRiAbLe are all equivalent. THE RULES OF SYMBOL NAMES. For the BS1, the register name is one of the predefined "fixed" variable names, such as W0, W1, B0, B1, etc. Here are a few examples of variable declarations on the BS1: 1 SYMBOL SYMBOL SYMBOL 1 temporary = W0 counter = B1 result = B2 ' value can be 0 to 65535 ' value can be 0 to 255 ' value can be 0 to 255 The above example will create a variable called temporary whose contents will be stored in the RAM location called W0. Also, the variable counter will be located at RAM location B1 and result at location B2. Note that temporary is a word-sized variable (because that's what size W0 is) while the other two are both byte-sized variables. Throughout the rest of the program, we can use the names temporary, counter, and result instead of W0, B1 and B2, respectively. This makes the code much more readable; it's easier to determine what counter is used for than it would be to figure out what the name B1 means. Please note that counter resides at location B1, and B1 happens to be the high byte of W0. This means than changing counter will also change temporary since they overlap. A situation like this usually is a mistake and results in strange behavior, but is also a powerful feature if used carefully. For all BS2 models, the Size argument has four choices: 1) Bit (1 bit), 2) Nib (nibble; 4 bits), 3) Byte (8 bits), and 4) Word (16 bits). Here are some examples of variable declarations on the BS2 models: All 2 mouse cat dog rhino All 2 VAR VAR VAR VAR BIT NIB BYTE WORD ' ' ' ' Value Value Value Value can can can can be be be be 0 0 0 0 or to to to 1. 15. 255. 65535. Page 86 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 4: BASIC Stamp Architecture – Defining Arrays The above example will create a bit-sized variable called mouse, and nibble-sized variable called cat, a byte-sized variable called dog and a word-sized variable called rhino. Unlike in the BS1, these variable declarations don't point to a specific location in RAM. Instead, we only specified the desired size for each variable; the BASIC Stamp will arrange them in RAM as it sees fit. Throughout the rest of the program, we can use the names mouse, cat, dog and rhino to set or retrieve the contents of these variables. A variable should be given the smallest size that will hold the largest value that will ever be stored in it. If you need a variable to hold the on/off status (1 or 0) of switch, use a bit. If you need a counter for a FOR…NEXT loop that will count from 1 to 100, use a byte. And so on. If you assign a value to a variable that exceeds its size, the excess bits will be lost. For example, suppose you use the byte variable dog, from the example above, and write dog = 260 (%100000100 binary). What will dog contain? It will hold only the lowest 8 bits of 260: %00000100 (4 decimal). DEFINING ARRAYS. All 2 On all BS2 models, you can also define multipart variables called arrays. An array is a group of variables of the same size, and sharing a single name, but broken up into numbered cells, called elements. You can define an array using the following syntax: name VAR Size(n) where name and Size are the same as described earlier. The new argument, (n), tells PBASIC how many elements you want the array to have. For example: myList VAR Byte(10) ' Create a 10-byte array. Once an array is defined, you can access its elements by number. Numbering starts at 0 and ends at n-1. For example: myList(3) = 57 DEBUG ? myList(3) This code will display "myList(3) = 57" on the PC screen. The real power of arrays is that the index value can be a variable itself. For example: BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 87 BASIC Stamp Architecture – Defining Arrays myBytes idx VAR VAR Byte(10) Nib ' Define 10-byte array ' Define 4-bit var FOR idx = 0 TO 9 myBytes(idx) = idx * 13 NEXT ' Repeat with idx = 0, 1, 2...9 ' Write idx * 13 to each cell FOR idx = 0 TO 9 DEBUG ? myBytes(idx) NEXT STOP ' Repeat with idx = 0, 1, 2...9 ' Show contents of each cell If you run this program, DEBUG will display each of the 10 values stored in the elements of the array: myBytes(0) = 0*13 = 0, myBytes(1) = 1*13 = 13, myBytes(2) = 2*13 = 26 ... myBytes(9) = 9*13 = 117. A word of caution about arrays: If you’re familiar with other BASICs and have used their arrays, you have probably run into the “subscript out of range” error. Subscript is another term for the index value. It is out-of-range when it exceeds the maximum value for the size of the array. For instance, in the example above, myBytes is a 10-cell array. Allowable index numbers are 0 through 9. If your program exceeds this range, PBASIC will not respond with an error message. Instead, it will access the next RAM location past the end of the array. If you are not careful about this, it can cause all sorts of bugs. If accessing an out-of-range location is bad, why does PBASIC allow it? Unlike a desktop computer, the BASIC Stamp doesn’t always have a display device connected to it for displaying error messages. So it just continues the best way it knows how. It’s up to the programmer (you!) to prevent bugs. Clever programmers, can take advantage of this feature, however, to perform tricky effects. Another unique property of PBASIC arrays is this: You can refer to the 0th cell of the array by using just the array’s name without an index value. For example: myBytes VAR myBytes(0) = 17 DEBUG ? myBytes(0) DEBUG ? myBytes Byte(10) ' Define 10-byte array ' Store 17 to 0th cell ' Display contents of 0th cell ' Also displays 0th cell Page 88 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com All 2 4: BASIC Stamp Architecture – Aliases and Modifiers This feature is how the "string" capabilities of the DEBUG and SEROUT command expect to work. A string is simply a byte array used to store text. See "Displaying Strings (Byte Arrays)" in the DEBUG command description on page 166 for more information. An alias is an alternative name for an existing variable. For example: ALIASES AND VARIABLE MODIFIERS. 1 SYMBOL SYMBOL cat tabby = B0 = cat ' Create a byte-sized variable ' Create alias for cat Byte cat ' Create a byte-sized variable ' Create alias for cat -- or -All 2 cat tabby VAR VAR In this example, tabby is an alias to the variable cat. Anything stored in cat shows up in tabby and vice versa. Both names refer to the same physical piece of RAM. This kind of alias can be useful when you want to reuse a temporary variable in different places in your program, but also want the variable’s name to reflect its function in each place. Use caution, because it is easy to forget about the aliases; during debugging, you might end up asking ‘How did that value get here?!’ The answer is that it was stored in the variable’s alias. All 2 On all the BS2 models, an alias can also serve as a window into a portion of another variable. This is done using "modifiers." Here the alias is assigned with a modifier that specifies what part to reference: rhino head tail VAR VAR VAR Word rhino.HIGHBYTE rhino.LOWBYTE ' A 16-bit variable ' Highest 8 bits of rhino ' Lowest 8 bits of rhino Given that example, if you write the value %1011000011111101 to rhino, then head would contain %10110000 and tail would contain %11111101. Table 4.3 lists all the variable modifiers. PBASIC 2.0 and 2.5 lets you apply these modifiers to any variable name and to combine them in any fashion that makes sense. For example, it will allow: rhino eye VAR VAR Word ' A 16-bit variable rhino.HIGHBYTE.LOWNIB.BIT1 ' A bit BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 89 BASIC Stamp Architecture – Aliases and Modifiers Symbol LOWBYTE HIGHBYTE BYTE0 BYTE1 LOWNIB HIGHNIB NIB0 NIB1 NIB2 NIB3 LOWBIT HIGHBIT BIT0 BIT1 BIT2 BIT3 BIT4 … BIT7 BIT8 … Bit15 Definition low byte of a word high byte of a word byte 0 (low byte) of a word byte 1 (high byte) of a word low nibble of a word or byte high nibble of a word or byte nib 0 of a word or byte nib 1 of a word or byte nib 2 of a word nib 3 of a word low bit of a word, byte, or nibble high bit of a word, byte, or nibble bit 0 of a word, byte, or nibble bit 1 of a word, byte, or nibble bit 2 of a word, byte, or nibble bit 3 of a word, byte, or nibble bits 4 though 7 of a word or byte bits 8 through 15 of a word The common sense rule for combining modifiers is that they must get progressively smaller from left to right. It would make no sense to specify, for instance, the low byte of a nibble, because a nibble is smaller than a byte! And just because you can stack up modifiers doesn’t mean that you should unless it is the clearest way to express the location of the part you want get at. The example above might be improved: rhino eye VAR VAR Word rhino.BIT9 ' A 16-bit variable ' A bit Although we’ve only discussed variable modifiers in terms of creating alias variables, you can also use them within program instructions: rhino head VAR VAR Word rhino.HIGHBYTE rhino = 13567 DEBUG ? head DEBUG ? rhino.HIGHBYTE STOP ' A 16-bit variable ' Highest 8 bits of rhino ' Display alias variable head ' rhino.HIGHBYTE works too Modifiers also work with arrays. For example: myBytes VAR Byte(10) myBytes(0) = $AB DEBUG HEX ? myBytes.LOWNIB(0) DEBUG HEX ? myBytes.LOWNIB(1) ' Define 10-byte array ' Hex $AB into 0th byte ' Show low nib ($B) ' Show high nib ($A) Page 90 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com Table 4.3: Variable Modifiers for all BS2 models. All 2 4: BASIC Stamp Architecture – Aliases and Modifiers If you looked closely at that example, you probably thought it was a misprint. Shouldn’t myBytes.LOWNIB(1) give you the low nibble of byte 1 of the array rather than the high nibble of byte 0? Well, it doesn’t. The modifier changes the meaning of the index value to match its own size. In the example above, when myBytes() is addressed as a byte array, it has 10 byte-sized cells numbered 0 through 9. When it is addressed as a nibble array, using myBytes.LOWNIB(), it has 20 nibble-sized cells numbered 0 through 19. You could also address it as individual bits using myBytes.LOWBIT(), in which case it would have 80 bit-sized cells numbered 0 through 79. What if you use something other than a “low” modifier, say myBytes.HIGHNIB()? That will work, but its effect will be to start the nibble array with the high nibble of myBytes(0). The nibbles you address with this nib array will all be contiguous, one right after the other, as in the previous example. myBytes VAR Byte(10) myBytes(0) = $AB myBytes(1) = $CD DEBUG HEX ? myBytes.HIGHNIB(0) DEBUG HEX ? myBytes.HIGHNIB(1) ' Define 10-byte array. ' ' ' ' Hex $AB into 0th byte Hex $CD into next byte Show high nib of cell 0 ($A) Show next nib ($D) This property of modified arrays makes the names a little confusing. If you prefer, you can use the less-descriptive versions of the modifier names; BIT0 instead of LOWBIT, NIB0 instead of LOWNIB, and BYTE0 instead of LOWBYTE. These have exactly the same effect, but may be less likely to be misconstrued. You may also use modifiers with the 0th cell of an array by referring to just the array name without the index value in parentheses. It’s fair game for aliases and modifiers, both in VAR directives and in instructions. THE MEMORY MAP On all BS2 models, if you’re working on a program and wondering how much variable space you have left, you can use the Memory Map feature of the editor (CTRL-M). See the "Memory Map" section of Chapter 3 on page 50. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 91 BASIC Stamp Architecture – Scratch Pad RAM The BS2e, BS2sx, BS2p, BS2pe, and BS2px have some additional RAM called Scratch Pad RAM. The BS2e and BS2sx have 64 bytes of Scratch Pad RAM (0 to 63) and the BS2p, BS2pe, and BS2px have 136 bytes of Scratch Pad RAM (0-135). Scratch Pad RAM can only be accessed with the GET and PUT commands and cannot have variable names assigned to it. Table 4.4 shows the layout of all SPRAM registers. Notice that the highest locations in Scratch Pad RAM (location 63 in the BS2e and BS2sx, locations 127-135 in the BS2p, BS2pe, and BS2px) are special-purpose, read-only locations that always contain special run-time information. For example, the lowest nibble of location 63 (BS2e and BS2sx) or 127 (BS2p, BS2pe, and BS2px) contains the number of the currently running program slot. This is handy for programs that need to know which program slot they exist in. In the BS2p, BS2pe, and BS2px, the high nibble of location 127 holds the slot designated for READ and WRITE; see the STORE command on page 449 for more information. Page 92 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com SCRATCH PAD RAM 4: BASIC Stamp Architecture – Scratch Pad RAM Table 4.4: Layout of SPRAM Registers. NOTE: Scratch Pad RAM can only be accessed with the GET and PUT commands. Scratch Pad RAM cannot have variable names assigned to it. Location 0...62 64..126 BS2e and BS2sx General Purpose RAM Bits 0-3: Active program slot number. n/a 127 n/a 128 n/a 129 n/a 130 n/a 131 n/a 132 n/a 133 n/a 134 n/a 135 n/a 63 BS2p, BS2pe and BS2px General Purpose RAM General Purpose RAM General Purpose RAM Bits 0-3, Active program slot #. Bits 4-7, program slot for READ and WRITE operations. Polled input trigger status of Main I/O pins 0-7 (0 = not triggered, 1 = triggered). Polled input trigger status of Main I/O pins 8-15 (0 = not triggered, 1 = triggered). Polled input trigger status of Auxiliary I/O pins 0-7 (0 = not triggered, 1 = triggered). Polled input trigger status of Auxiliary I/O pins 8-15 (0 = not triggered, 1 = triggered). Bits 0-3: Polled-interrupt mode, set by POLLMODE Bits 0-2: Polled-interrupt “run” slot, set by POLLRUN. Bit 0: Active I/O group; 0 =Main I/O, 1 = Auxiliary I/O. Bit 0: Polled-output status (set by POLLMODE); 0 = disabled, 1= enabled. Bit 1: Polled-input status; 0 = none defined, 1 = at least one defined. Bit 2: Polled-run status (set by POLLMODE); 0 = disabled, 1 = enabled. Bit 3: Polled-output latch status; 0 = real-time mode, 1 = latch mode. Bit 4: Polled-input state; 0 = no trigger, 1 = triggered. Bit 5: Polled-output latch state; 0 = nothing latched, 1 = signal latched. Bit 6: Poll-wait state; 0 = No Event, 1 = Event Occurred. (Cleared by POLLMODE only). Bit 7: Polling status; 0 = not active, 1 = active. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 93 BASIC Stamp Architecture – Constants and Expressions Suppose you’re working on a program called “Three Cheers” that flashes LEDs, makes hooting sounds, and activates a motor that crashes cymbals together, all in sets of three. A portion of your PBASIC program might contain something like: CONSTANTS AND COMPILE-TIME EXPRESSIONS. 1 All 2 FOR counter = 1 TO 3 GOSUB Make_Cheers NEXT ... FOR counter = 1 TO 3 GOSUB Blink_LEDs NEXT ... FOR counter = 1 TO 3 GOSUB Crash_Cymbals NEXT The numbers 1 and 3 in the code above are called constants. They are constants because, while the program is running, nothing can happen to change those numbers. This distinguishes constants from variables, which can change while the program is running. Constants are not limited to the decimal number system; PBASIC allows you to use several numbering systems. See “Number Representations” on page 96. You can assign names to constants in a fashion similar to how variables are declared. On a BS1, it is identical to variable declarations. For all BS2 models, use the CON directive. Here is the syntax: SYMBOL Name = ConstantValue CON ConstantValue DEFINING AND USING CONSTANTS (CON). 1 -- or -Name Page 94 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com All 2 4: BASIC Stamp Architecture – Constants and Expressions Once created, named constants may be used in place of the numbers they represent. For example: 1 SYMBOL Cheers = 3 ' Number of cheers. FOR counter = 1 TO Cheers GOSUB Make_Cheers NEXT -- or -All 2 Cheers CON 3 ' Number of cheers. FOR counter = 1 TO Cheers GOSUB Make_Cheers NEXT That code works exactly the same as the corresponding FOR…NEXT loop in the previous example. The editor software substitutes the number 3 for the symbol named Cheers throughout your program. Like variables, labels and instructions, constant names are not case sensitive; CHEERS, and ChEErs are identical to Cheers. Using named constants does not increase the amount of code downloaded to the BASIC Stamp, and it often improves the clarity of the program. Weeks after a program is written, you may not remember what a particular number was supposed to represent—using a name may jog your memory (or simplify the detective work needed to figure it out). Named constants also have another benefit. Suppose the “Three Cheers” program had to be upgraded to “Five Cheers.” In the original example you would have to change all of the 3s to 5s. Search and replace would help, but you might accidentally change some 3s that weren’t numbers of cheers, too. However, if you had made smart use of a named constant, all you would have to do is change 3 to 5 in one place, the constant's declaration: 1 SYMBOL Cheers = 5 ' Number of cheers. -- or -All 2 Cheers CON 5 ' Number of cheers. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 95 BASIC Stamp Architecture – Number Representations Now, assuming that you used the constant Cheers wherever your program needed ‘the number of cheers,’ your upgrade would be done. On all BS2 models, you can take this idea a step further by defining constants with expressions; groups of math and/or logic operations that the editor software solves (evaluates) at compile-time (the time right after you start the download and before the BASIC Stamp starts running your program). For example, suppose the “Cheers” program also controls a pump to fill glasses with champagne. Perhaps the number of glasses to fill is always twice the number of cheers, minus 1 (another constant): All 2 Cheers Glasses All 2 CON CON 5 Cheers*2-1 ' # of cheers ' # of glasses As you can see, one constant can be defined in terms of another. That is, the number glasses depends on the number cheers. The expressions used to define constants must be kept fairly simple. The editor software solves them from left to right, and doesn’t allow you to use parentheses to change the order of evaluation. The operators that are allowed in constant expressions are shown in Table 4.5. Operator Symbol + * / > & | ^ Description Add Subtract Multiply Divide Shift Left Shift Right Logical AND Logical OR Logical XOR Table 4.5: Operators allowed in constant expressions for all BS2 models. The BASIC Stamp, like any computer, excels at math and logic. However, being designed for control applications, the BASIC Stamp does math a little differently than a calculator or spreadsheet program. This section will help you understand BASIC Stamp numbers, math, and logic. RUN-TIME MATH AND LOGIC. In your programs, you may express a number in various ways, depending on how the number will be used and what makes sense to you. By default, the BASIC Stamp recognizes numbers like 0, 99 or 62145 as being in our NUMBER REPRESENTATIONS. Page 96 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 1 All 2 4: BASIC Stamp Architecture – Number Representations everyday decimal (base-10) system. However, you may also use hexadecimal (base-16; also called hex) or binary (base-2). Since the symbols used in decimal, hex and binary numbers overlap (e.g., 1 and 0 are used by all; 0 through 9 apply to both decimal and hex) the editor software needs prefixes to tell the numbering systems apart, as shown below: 99 $1A6 %1101 ' Decimal (no prefix) ' Hex (prefix ‘$’ required) ' Binary (prefix ‘%’ required) The BASIC Stamp also automatically converts quoted text into ASCII codes, and allows you to apply names (symbols) to constants from any of the numbering systems. For example: 1 SYMBOL SYMBOL SYMBOL SYMBOL LetterA Cheers Hex128 FewBits = = = = "A" 3 $80 %1101 ' ASCII code for A (65) -- or -- HEX TO BCD CONVERSION All 2 LetterA Cheers Hex128 FewBits All 2 Binary Coded Decimal (BCD) is a way to encode decimal digits that is easier to display or manipulate in some devices. Each digit of the decimal number (0 – 9) requires 4 bits (a nibble) to encode. For this reason, a BCD byte is always two decimal digits and a BCD word is always four decimal digits. The BASIC Stamp does not support BCD natively, however, because of the way that BCD is encoded the BS2 models’ hexadecimal prefix, and Conversion Formatters can be used as a shortcut for most BCD input/output operations as long as the digits used do not exceed valid decimal digits (0 – 9). For example: BCDValue DEBUG HEX CON CON CON CON "A" 3 $80 %1101 CON ' ASCII code for A (65) $4096 BCDValue The first line creates a symbol, BCDValue, that contains the binary form of the hexadecimal value $4096, which means the upper nibble contains the binary value for the decimal digit 4, the next nibble is 0, the next nibble is 9 BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 97 BASIC Stamp Architecture – Number Representations and the last nibble is 6; this corresponds exactly to the BCD form of the decimal number 4096. The second line in the above example uses the HEX Conversion Formatter within the DEBUG command (see DEBUG, page 159) to output the BCD value 4096 to the Debug Terminal. The HEX Conversion Formatter can also be used for input operations to convert a decimal value to BCD, as long as that decimal value is no greater than 2 digits for a Byte-sized variable or 4 digits for a Word-sized variable. For more information on constants, see the section "Constants and Compile-Time Expressions", above. With all BS2 models, some of the math or logic operations in a program are solved by the BASIC Stamp. The editor software solves operations that define constants before the program is downloaded to the BASIC Stamp. The preprocessing that takes place before the program is downloaded is referred to as “compile-time.” WHEN IS RUN-TIME? All 2 All 2 After the download is complete, the BASIC Stamp starts executing your program; this is referred to as “run-time.” At run-time the BASIC Stamp processes math and logic operations involving variables, or any combination of variables and constants. Because compile-time and run-time expressions appear similar, it can be hard to tell them apart. A few examples will help: result VAR Byte ' Compile-time assignment Cheers Glasses OneNinety NotWorking CON CON CON CON 3 Cheers * 2 - 1 100 + 90 3 * result ' ' ' ' Compile-time Compile-time Compile-time ERROR: Variables not allowed here ' ' ' ' ' Run-time Run-time "100 + 90" solved at compile-time OneNinety + 1 solved at run-time 100 + 90 solved at run-time result = Glasses result = 99 + Glasses result = OneNinety + 1 result = 100 + 90 Notice that the last example is solved at run-time, even though the math performed could have been solved at compile-time since it involves two constants. If you find something like this in your own programs, you can save some program space in the EEPROM by converting the run-time Page 98 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 4: BASIC Stamp Architecture – PIN Symbols expression 100+90 into a compile-time expression like OneNinety CON 100+90. To sum up: compile-time expressions are those that involve only constants; once a variable is involved, the expression must be solved at run-time. That’s why the line “NotWorking CON 3 * result” would generate an error message. The CON directive works only at compile-time and result is a variable; variables are not allowed in compile-time expressions. DEFINING AND USING PINS WITH THE PIN DIRECTIVE. Now we know now to create variables and constants (with VAR and All 2 CON) but there is a third option if you’re using PBASIC 2.5; pin-type symbols (with PIN). PIN is like VAR and CON put together and represents an I/O pin. There are some situations where it is handy to refer to a pin using a variable (like IN2 or OUT2) and also as a constant (2, in this case). The PIN directive lets you define a context-sensitive symbol representing an I/O pin. Depending on where and how this pin-type symbol is used determines whether it is treated as an I/O pin input variable, and I/O pin output variable or as a constant representing the pin number. Let’s explore a simple example to see where this is useful. It is common practice to define constants for any number used in many places so that changing that number doesn’t create a maintenance hassle later on. If we were to use a constant symbol to represent an I/O pin, we might do something like this: ' {$PBASIC 2.5} signal INPUT CON 1 signal ' constant-type symbol representing I/O 1 ' set signal pin to input Wait: IF signal = 0 THEN Wait ' wait until signal pin = 1 Here we define signal to represent our desired I/O pin, then we use the INPUT command to set it to the input direction and later we check the state of the signal pin and loop (wait) while it is equal to logic 0. This code has a common bug, however; the INPUT command works as expected, because its Pin argument requires a number representing the I/O pin, but BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 99 BASIC Stamp Architecture – PIN Symbols the Condition argument in the IF…THEN statement will always evaluate to false because signal is a constant equal to 1, and “1 = 0” is false. What the user really meant to happen is something like: IF IN1 = 0 THEN Wait because IN1 is the input variable representing the current state of I/O pin 1. This situation is perfect for the PIN directive: ' {$PBASIC 2.5} All signal PIN 1 ' pin-type symbol representing I/O 1 INPUT ' set signal pin to input signal Wait: IF signal = 0 THEN Wait ' wait until signal = 1 We only changed one thing in this code: the CON directive was changed to PIN. Now signal is a context-sensitive symbol that will be treated as a constant or as a variable depending on where it is used. In the INPUT command signal is used as the Pin argument, and since that argument requires a number representing the pin number, signal is treated as a constant equal to 1. In the IF…THEN statement, signal is compared to another value (which implies that what signal represents is expected to change at run-time; i.e.: signal’s value is “variable”) so signal is treated as a variable equal to the input variable for the defined pin (IN1 in this case). As another example, consider the following code: ' {$PBASIC 2.5} signal CON OUTPUT signal signal = 1 2 ' constant-type symbol representing I/O 2 ' set signal pin to output ' set signal high Here, again, this is a common bug; the OUTPUT command will work as expected, but the signal = 1 statement generates a syntax error at compiletime. Why the error? This is an assignment statement, meant to assign the value 1 to the item on the left, but the item on the left is a constant, not a variable, so it can not be changed at run-time. What the user was thinking when writing this was: OUT2 = 1 which sets the value of the output variable representing I/O pin 2 to logical 1 (high). Here’s the solution: Page 100 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 2 4: BASIC Stamp Architecture – PIN Symbols All 2 ' {$PBASIC 2.5} signal PIN 2 OUTPUT signal signal = 1 ' pin-type symbol representing I/O 2 ' set signal pin to output ' set signal high The OUTPUT command treats signal as a constant equal to 2 and the signal = 1 statement treats signal as a variable equal to the output variable for the defined pin (OUT2 in this case). You might be wondering why “signal = 0” in the IF…THEN statement of our first example treats signal as the input variable IN1 and yet “signal = 1” in our last example treats signal as the output variable OUT2. The distinction is that the first example is a comparison and the second example is an assignment. Comparisons need to “read” expressions and then evaluate the comparison while assignments need to read expressions and then “write” the results. Since signal is to the left of the equal sign (=) in our assignment statement, it must be a variable we can write to, thus it must be treated as OUT2, in this case. What happens if our pin-type symbol is to the right of the equal sign in an assignment statement? Example: All 2 ' {$PBASIC 2.5} signal1 signal2 PIN PIN 1 2 INPUT signal1 OUTPUT signal2 signal2 = signal1 ' pin-type symbol representing I/O 1 ' pin-type symbol representing I/O 2 ' set signal1 pin to input ' set signal2 pin to output ' set signal2 pin to signal1 pin’s state In this case signal2 is treated as OUT2 and signal1 is treated as IN1; left side must be written to and right side must be read from. If a pin-type symbol is used in a command, but not in the Pin argument of that command, it will be treated as an input variable (i.e.: INx). NOTE: It is very rare that you’ll need to use a pin-type symbol in this way. The following is a summary of behaviors and uses of pin-type symbols. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 101 BASIC Stamp Architecture – PIN Symbols PIN_Symbol behaves like a constant: 1. when used in a command’s Pin argument. Example: OUTPUT 2. PIN_Symbol when used in the index of an array. Example: myArray(PIN_Symbol) = 25 PIN_Symbol behaves like an input variable (INx): 1. when used in a command’s non-Pin argument that expects to read a variable/constant/expression. Example: DEBUG BIN PIN_Symbol 2. when used in a command’s Condition argument. Example: IF PIN_Symbol = 1 THEN… 3. when used to the right of the equal sign (=) in an assignment statement. Example: ex: myVariable = PIN_Symbol + 1 PIN_Symbol behaves like an output variable (OUTx): 1. when used in a command’s non-Pin argument that expects to write a result to a variable. Example: LOOKUP index, [0, 1, 1, 0, 1], PIN_Symbol 2. when used to the left of the equal sign (=) in an assignment statement. Example: PIN_Symbol = 1 Let’s talk about the four basic operations of arithmetic: addition (+), subtraction (-), multiplication (*), and division (/). You may recall that the order in which you do a series of additions and subtractions doesn’t affect the result. The expression 12+7-3+22 works out the same as 22-3+12+7. However, when multiplication or division are involved, it’s a different story; 12+3*2/4 is not the same as 2*12/4+3. In fact, you may have the urge to put parentheses around portions of those equations to clear things up. Page 102 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com BASIC ARITHMETIC OPERATIONS 1 All 2 4: BASIC Stamp Architecture – Order of Operations The BASIC Stamp solves math problems in the order they are written: from left to right. The result of each operation is fed into the next operation. So to compute 12+3*2/4, the BASIC Stamp goes through a sequence like this: ORDER OF OPERATIONS. 12 + 3 = 15 15 * 2 = 30 30 / 4 = 7 Since the BASIC Stamp performs integer math (whole numbers only) 30 / 4 results in 7, not 7.5. We’ll talk more about integers in the next section. Some other dialects of BASIC would compute that same expression based on their precedence of operators, which requires that multiplication and division be done before addition. So the result would be: 3*2=6 6/4=1 12 + 1 = 13 Once again, because of integer math, the fractional portion of 6 / 4 is dropped, so we get 1 instead of 1.5. All INTEGER MATH. 1 The BS1 does not allow parenthesis in expressions. Unfortunately, all expressions have to be written so that they evaluate as intended strictly from left to right. 2 All BS2 models, however, allow parentheses to be used to change the order of evaluation. Enclosing a math operation in parentheses gives it priority over other operations. To make the BASIC Stamp compute the previous expression in the conventional way, you would write it as 12 + (3*2/4). Within the parentheses, the BASIC Stamp works from left to right. If you wanted to be even more specific, you could write 12 + ((3*2)/4). When there are parentheses within parentheses, the BASIC Stamp works from the innermost parentheses outward. Parentheses placed within parentheses are called “nested parentheses." The BASIC Stamp performs all math operations by the rules of positive integer math. That is, it handles only whole numbers, and drops any fractional portions from the results of computations. The BASIC Stamp handles negative numbers using two's complement rules. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 103 BASIC Stamp Architecture – Math and Operators All BS2 models can interpret twos complement negative numbers correctly in DEBUG and SEROUT instructions using formatters like SDEC (for signed decimal). In calculations, however, it assumes that all values are positive. This yields correct results with two’s complement negative numbers for addition, subtraction, and multiplication, but not for division. The standard operators we just discussed: +, - ,* and / all work on two values; as in 1 + 3 or 26 * 144. The values that operators process are referred to as arguments. So we say that the add, subtract, multiply and divide operators take two arguments. All 2 UNARY AND BINARY OPERATORS. Operators that take two arguments are called “binary” operators, and those that take only one argument are called “unary” operators. Please note that the term “binary operator” has nothing to do with binary numbers; it’s just an inconvenient coincidence that the same word, meaning ‘involving two things’ is used in both cases. The minus sign (-) is a bit of a hybrid. It can be used as a binary operator, as in 8-2 = 6, or it can be used as a unary operator to represent negative numbers, such as -4. Unary operators take precedence over binary operators; the unary operation is always performed first. For example, on all BS2 models, SQR is the unary operator for square root. In the expression 10 - SQR 16, the BASIC Stamp first takes the square root of 16, then subtracts it from 10. Most of the descriptions that follow say something like “computes (some function) of a 16-bit value.” This does not mean that the operator does not work on smaller byte or nibble values, but rather that the computation is done in a 16-bit workspace. If the value is smaller than 16 bits, the BASIC Stamp pads it with leading 0s to make a 16-bit value. If the 16-bit result of a calculation is to be packed into a smaller variable, the higher-order bits are discarded (truncated). Keep this in mind, especially when you are working with two’s complement negative numbers, or moving values from a larger variable to a smaller one. For example, look at what happens when you move a two’s complement negative number into a byte (rather than a word): Page 104 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com NOTES ABOUT THE 16-BIT WORKSPACE. 4: BASIC Stamp Architecture – Math and Operators, ABS All 2 value VAR Byte value = - 99 DEBUG SDEC ? 1 All 2 value ' Show signed decimal result (157) We expected -99 to be displayed but what we got was 157. How did -99 become 157? Let’s look at the bits: 99 is %01100011 binary. When the BASIC Stamp negates 99, it converts the number to 16 bits %0000000001100011, and then takes the two’s complement, %1111111110011101. Since we’ve asked for the result to be placed in an 8bit (byte) variable, the upper eight bits are truncated and the lower eight bits stored in the byte: %10011101. Now for the second half of the story. DEBUG’s SDEC modifier (for all BS2 models) expects a 16-bit, two’s complement value, but we've only given it a byte to work with. As usual, it creates a 16-bit value by padding the leading eight bits with 0s: %0000000010011101. And what’s that in signed decimal? 157. To fix this problem, always store values that are intended to be signed into a word-sized variable. Table 4.1 lists the available Unary Operators. Note: the BS1 only supports negative (-). UNARY OPERATORS. Table 4.1: Unary Operators. Note: the BS1 only supports the negative (-) unary operator. Operator ABS COS DCD ~ NCD SIN SQR ABSOLUTE VALUE: ABS All 2 Description Returns absolute value Returns cosine in twos complement binary radians n 2 -power decoder Inverse Negative Priority encoder of a 16-bit value Returns sine in twos complement binary radians Returns square root of value Supported By: All except BS1 All except BS1 All except BS1 All except BS1 All All except BS1 All except BS1 All except BS1 The Absolute Value operator (ABS) converts a signed (two’s complement) 16-bit number to its absolute value. The absolute value of a number is a positive number representing the difference between that number and 0. For example, the absolute value of -99 is 99. The absolute value of 99 is also 99. ABS works on two’s complement negative numbers. Examples of ABS at work: BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 105 BASIC Stamp Architecture – COS, DCD, ~, result VAR Word result = -99 ' ' ' ' DEBUG SDEC ? result DEBUG SDEC ? ABS result Put -99 ...(2's Display Display into result complement format) as a signed # as a signed # The Cosine operator (COS) returns the two’s complement, 16-bit cosine of an angle specified as an 8-bit “binary radian” (0 to 255) angle. COS is the same as SIN in all respects, except that the cosine function returns the x distance instead of the y distance. See “Sine: SIN”, below, for a code example and more information. COSINE: COS The Decoder operator (DCD) is a 2n-power decoder of a four-bit value. DCD accepts a value from 0 to 15, and returns a 16-bit number with the bit, described by value, set to 1. For example: DECODER: DCD result VAR result = DCD DEBUG BIN16 ? result DEBUG result DEBUG VAR 12 result 2 ' Set bit 12 ' Display result (%0001000000000000) INVERSE: ~ Byte = %11110001 BIN8 ? result = ~ result BIN8 ? Result ' ' ' ' Store bits Display in Complement Display in in byte result. binary (%11110001) result binary (%00001110) The Negative operator (-) negates a 16-bit number (converts to its twos complement). SYMBOL All 2 Word The Inverse operator (~) complements (inverts) the bits of a number. Each bit that contains a 1 is changed to 0 and each bit containing 0 is changed to 1. This process is also known as a “bitwise NOT” and “ones complement”. For example: result All result result = -99 result = result + 100 DEBUG result = W1 NEGATIVE: - 1 ' ' ' ' Put -99 ...(2's Add 100 Display into result complement format) to it result (1) -- or -Page 106 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 4: BASIC Stamp Architecture – NCD, SIN All 2 result VAR Word result = 99 ' ' ' ' ' DEBUG SDEC ? result result = -result DEBUG SDEC ? result ENCODER: NCD All 2 The Encoder operator (NCD) is a "priority" encoder of a 16-bit value. NCD takes a 16-bit value, finds the highest bit containing a 1 and returns the bit position plus one (1 through 16). If the input value is 0, NCD returns 0. NCD is a fast way to get an answer to the question “what is the largest power of two that this value is greater than or equal to?” The answer NCD returns will be that power, plus one. Example: result SINE: SIN All 2 Put -99 into result ...(2's complement format) Display as a signed # Negate the value Display as a signed # VAR result = %1101 DEBUG ? NCD result Word ' Highest bit set is bit 3 ' Show the NCD of result (4)The Sine operator (SIN) returns the two’s complement, 16-bit sine of an angle specified as an 8-bit binary radian (0 to 255) angle. To understand the SIN operator more completely, let’s look at a typical sine function. By definition: given a circle with a radius of 1 unit (known as a unit circle), the sine is the y-coordinate distance from the center of the circle to its edge at a given angle. Angles are measured relative to the 3o'clock position on the circle, increasing as you go around the circle counterclockwise. At the origin point (0 degrees) the sine is 0, because that point has the same y (vertical) coordinate as the circle center. At 45 degrees the sine is 0.707. At 90 degrees, sine is 1. At 180 degrees, sine is 0 again. At 270 degrees, sine is -1. The BASIC Stamp SIN operator breaks the circle into 0 to 255 units instead of 0 to 359 degrees. Some textbooks call this unit a “binary radian” or “brad.” Each brad is equivalent to 1.406 degrees. And instead of a unit circle, which results in fractional sine values between 0 and 1, BASIC Stamp SIN is based on a 127-unit circle. Results are given in two’s complement form in order to accommodate negative values. So, at the origin, SIN is 0. At 45 degrees (32 brads), sine is 90. At 90 degrees (64 brads), sine is 127. At 180 degrees (128 brads), sine is 0. At 270 degrees (192 brads), sine is -127. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 107 BASIC Stamp Architecture – SIN, SQR Figure 4.1: 127-Unit Circle To convert brads to degrees, multiply by 180 then divide by 128, or simply multiply with “*/ 360”. To convert degrees to brads, multiply by 128, then divide by 180. Here’s a small program that demonstrates the SIN and COS operators: degr brads VAR Word VAR Byte DEBUG 2, 4, 0,"ANGLE", TAB, "COS", TAB, "SIN", CR DEBUG "DEGREES", TAB,"BRADS", TAB, "(X)", TAB,"(Y)", CR FOR degr = 0 TO 359 STEP 45 brads = degr * 128 / 180 DEBUG CR, DEC3 degr, TAB, DEC3 brads, TAB DEBUG SDEC COS brads, TAB, SDEC SIN brads NEXT ' ' ' ' Increment degrees Convert to brads Display angle Display COS & SIN The Square Root operator (SQR) computes the integer square root of an unsigned 16-bit number. (The number must be unsigned since the square root of a negative number is an ‘imaginary’ number.) Remember that most square roots have a fractional part that the BASIC Stamp discards when Page 108 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com SQUARE ROOT: SQR All 2 4: BASIC Stamp Architecture – + doing its integer-only math. So it computes the square root of 100 as 10 (correct), but the square root of 99 as 9 (the actual is close to 9.95). Example: DEBUG ? SQR DEBUG ? SQR ' Display square root of 100 (10) ' Display of square root of 99 ' ...(9 due to truncation) Table 4.6 lists the available Binary (two-argument) Operators. BINARY OPERATORS. Table 4.6: Binary Operators. Note: some binary operators are not supported by all BASIC Stamp models. ADD: + 100 99 1 All 2 Operator + * ** */ / // ATN HYP MIN MAX DIG > REV & | ^ &/ |/ ^/ Description Addition Subtraction Multiplication Multiplication (returns upper 16-bits) Multiply by 8-bit integer, 8-bit fraction Division Modulus (Remainder of division) Returns arctangent of X/Y vector Returns hypotenuse of X/Y vector Limits a value to a specified low Limits a value to a specified high Returns specified digit of number Shift bits left by specified amount Shift bits right by specified amount Reverse specified number of bits Bitwise AND Bitwise OR Bitwise XOR Logical AND NOT Logical OR NOT Logical XOR NOT Supported By: All All All All All BS2 models All All All BS2 models All BS2 models All All All BS2 models All BS2 models All BS2 models All BS2 models All All All BS1 Only BS1 Only BS1 Only The Addition operator (+) adds variables and/or constants, returning a 16bit result. It works exactly as you would expect with unsigned integers from 0 to 65535. If the result of addition is larger than 65535, the carry bit will be lost. If the values added are signed 16-bit numbers and the destination is a 16-bit variable, the result of the addition will be correct in both sign and value. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 109 BASIC Stamp Architecture – +, -, * For example: SYMBOL SYMBOL value1 value2 value1 DEBUG value1 value2 = = W0 W1 = - 99 = 100 = value1 + value2 value1 1 ' Add the numbers ' Show the result (1) -- or -value1 value2 value1 value2 value1 DEBUG VAR VAR Word Word All = - 1575 = 976 = value1 + value2 SDEC ? value1 ' Add the numbers ' Show the result (-599) The Subtraction operator (-) subtracts variables and/or constants, returning a 16-bit result. It works exactly as you would expect with unsigned integers from 0 to 65535. If the result is negative, it will be correctly expressed as a signed 16-bit number. For example: SYMBOL SYMBOL value1 value2 value1 DEBUG value1 value2 = = W0 W1 = 199 = 100 = value1 - value2 value1 2 SUBTRACT: 1 All 2 1 ' Subtract the numbers ' Show the result (99) -- or -value1 value2 value1 value2 value1 DEBUG VAR VAR Word Word = 1000 = 1999 = value1 - value2 SDEC ? value1 All 2 ' Subtract the numbers ' Show the result (-999) The Multiply operator (*) multiplies variables and/or constants, returning the low 16 bits of the result. It works exactly as you would expect with unsigned integers from 0 to 65535. If the result of multiplication is larger than 65535, the excess bits will be lost. Multiplication of signed variables will be correct in both number and sign, provided that the result is in the range -32767 to +32767. Page 110 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com MULTIPLY: * 1 All 2 4: BASIC Stamp Architecture – *, ** 1 SYMBOL SYMBOL value1 value2 value1 DEBUG value1 value2 = = W0 W1 = 1000 = 19 = value1 * value2 value1 ' Multiply value1 by value2 ' Show the result (19000) VAR VAR = 1000 = - 19 = value1 SDEC ? ' Multiply value1 by value2 ' Show the result (-19000) -- or -All MULTIPLY HIGH: ** 2 1 All 2 1 value1 value2 value1 value2 value1 DEBUG Word Word * value2 value1 The Multiply High operator (**) multiplies variables and/or constants, returning the high 16 bits of the result. When you multiply two 16-bit values, the result can be as large as 32 bits. Since the largest variable supported by PBASIC is a word (16 bits), the highest 16 bits of a 32-bit multiplication result are normally lost. The ** (double-star) instruction gives you these upper 16 bits. For example, suppose you multiply 65000 ($FDE8) by itself. The result is 4,225,000,000 or $FBD46240. The * (star, or normal multiplication) instruction would return the lower 16 bits, $6240. The ** instruction returns $FBD4. SYMBOL SYMBOL value1 value2 = = W0 W1 value1 = $FDE8 value2 = value1 ** value1 DEBUG $value2 ' Multiply $FDE8 by itself ' Return high 16 bits ($FBD4) -- or -All 2 value1 value2 VAR VAR Word Word value1 = $FDE8 value2 = value1 ** value1 DEBUG HEX ? value2 ' Multiply $FDE8 by itself ' Return high 16 bits ($FBD4) An interesting application of the ** operator allows you no multiply a number by a fractional value less than one. The fraction must be expressed in units of 1/65536. To find the fractional ** argument, BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 111 BASIC Stamp Architecture – **, */ multiply the fraction part by 65536. For example, 0.72562 is represented by 47554, which is 0.72562 * 65536. SYMBOL SYMBOL Frac value = 47554 = W0 value = 10000 value = value ** Frac DEBUG value ' = 0.72562 x 65536 1 ' Multiply 10000 by 0.72562 ' Show result (7256) -- or – Frac value CON VAR value = 10000 value = value ** Frac DEBUG ? value 47554 Word ' = 0.72562 x 65536 VAR Word value1 = 100 value1 = value1*/ $0180 DEBUG ? value1 2 ' Multiply 10000 by 0.72562 ' Show result (7256) The Multiply Middle operator (*/) multiplies variables and/or constants, returning the middle 16 bits of the 32-bit result. This has the effect of multiplying a value by a whole number and a fraction. The whole number is the upper byte of the multiplier (0 to 255 whole units) and the fraction is the lower byte of the multiplier (0 to 255 units of 1/256 each). The */ (starslash) instruction gives you an excellent workaround for the BASIC Stamp's integer-only math. Suppose you want to multiply a value by 1.5. The whole number, and therefore the upper byte of the multiplier, would be 1, and the lower byte (fractional part) would be 128, since 128/256 = 0.5. It may be clearer to express the */ multiplier in hex—as $0180—since hex keeps the contents of the upper and lower bytes separate. Here's an example: value1 All ' Multiply by 1.5 [1 + (128/256)] ' Show result (150) To calculate the constant for use with the */ operator, multiply the target (mixed) value by 256 and convert to an integer. For instance, take Pi (π, 3.14159). The */ constant would be INT(3.14159 * 256) = 804 ($0324). So the constant Pi for use with */ would be $0324. This isn’t a perfect match for Pi, but the error is only about 0.1%. Note that the */ operator can be used to multiply by mixed values up to about 255.996. Page 112 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com MULTIPLY MIDDLE: */ All 2 All 2 4: BASIC Stamp Architecture – /, // DIVIDE: / 1 All 2 1 The Divide operator (/) divides variables and/or constants, returning a 16-bit result. Works exactly as you would expect with unsigned integers from 0 to 65535. Use / only with positive values; signed values do not provide correct results. Here’s an example of unsigned division: SYMBOL value1 SYMBOL value2 value1 = 1000 value2 = 5 = = W0 W1 value1 = value1 / value2 DEBUG value1 ' Divide the numbers ' Show the result (200) -- or -All 2 value1 value2 value1 value2 value1 DEBUG VAR VAR Word Word = 1000 = 5 = value1 / value2 DEC ? value1 ' Divide the numbers ' Show the result (200) A workaround to the inability to divide signed numbers is to have your program divide absolute values, then negate the result if one (and only one) of the operands was negative. All values must lie within the range of -32767 to +32767. Here is an example: All 2 sign value1 value2 VAR VAR VAR Bit Word Word ' Bit to hold the result sign value1 = 100 value2 = -3200 sign = value1.BIT15 ^ value2.BIT15 value2 = ABS value2 / ABS value1 IF (sign = 1) THEN value2 = -value2 DEBUG SDEC ? value2 MODULUS: // 1 All 2 ' ' ' ' Determine sign of result Divide absolute values Negate result if sign = 1 Show the result (-32) The Modulus operator (//) returns the remainder left after dividing one value by another. Some division problems don’t have a whole-number result; they return a whole number and a fraction. For example, 1000/6 = 166.667. Integer math doesn’t allow the fractional portion of the result, so 1000/6 = 166. However, 166 is an approximate answer, because 166*6 = 996. The division operation left a remainder of 4. The // (double-slash) BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 113 BASIC Stamp Architecture – //, ATN returns the remainder, 4 in this example. Naturally, numbers that divide evenly, such as 1000/5, produce a remainder of 0. Example: SYMBOL SYMBOL value1 value2 = W0 = W1 value1 = 1000 value2 = 6 value1 = value1 // value2 DEBUG value1 ' Get remainder of value1 / value2 ' Show the result (4) -- or -value1 value2 VAR VAR Word Word value1 = 1000 value2 = 6 value1 = value1 // value2 DEBUG ? value1 ' Get remainder of value1 / value2 ' Show the result (4) The Arctangent operator (ATN) returns the angle to the vector specified by X and Y coordinate values. The syntax of ATN is: xCoord ATN yCoord where xCoord and yCoord are the coordinates of the target vector point. In the BASIC Stamp, the angle is returned in binary radians (0 to 255) instead of degrees (0 to 359). See the explanation of the SIN operator for more information about binary radians. Coordinate input values are limited to -127 to 127 (signed bytes) as shown in the diagram of the PBASIC Unit Circle (Figure 4.2). brads degr VAR VAR brads = 4 ATN 4 degr = brads */ 360 DEBUG SDEC ? brads DEBUG SDEC ? degr Word Word ' angle in brads ' angle in degrees ' ' ' ' get angle convert to degrees display brads (32) display degrees (45) Page 114 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com ARCTANGENT: ATN All 2 4: BASIC Stamp Architecture – ATN, HYP, MIN Figure 4.2: ATN and HYP operators in the PBASIC unit circle HYPOTENUSE: HYP All 2 The Hypotenuse operator (HYP) returns the length of the hypotenuse of a right triangle with sides of length A and B. The syntax of HYP is: SideA HYP SideB where SideA and SideB are the side lengths of a right-triangle (the order isn’t important). Another application of HYP is to calculate the distance between the origin (0, 0) and a point (X, Y) in a Cartesian coordinate system. Side length (vector) input values are limited to -127 to 127 (signed bytes). See diagram with ATN operator, Figure 4.2. DEBUG ? 3 HYP 4 MINIMUM: MIN 1 All 2 ' hypotenuse of 3x4 triangle (5) The Minimum operator (MIN) limits a value to a specified 16-bit positive minimum. The syntax of MIN is: value MIN limit where value is a constant or variable value to perform the MIN function upon and limit is the minimum value that value is allowed to be. Its logic is, ‘if value is less than limit, then make result = limit; if value is greater than or equal to limit, make result = value.’ BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 115 BASIC Stamp Architecture – MIN, MAX MIN works in positive math only; its comparisons are not valid when used on two’s complement negative numbers, since the positive-integer representation of a number like -1 ($FFFF or 65535 in unsigned decimal) is larger than that of a number like 10 ($000A or 10 decimal). Use MIN only with unsigned integers. Because of the way fixed-size integers work, you should be careful when using an expression involving MIN 0. For example, 0-1 MIN 0 will result in 65535 because of the way fixed-size integers wrap around. SYMBOL SYMBOL value1 value2 = W0 = W1 FOR value1 = 100 TO 0 STEP -10 value2 = value1 MIN 50 DEBUG value2 NEXT 1 ' Walk value1 from 100 to 0 ' Use MIN to clamp at 50 ' Show "clamped" value -- or -value VAR Word FOR value = 100 TO 0 STEP 10 DEBUG ? value MIN 50 NEXT All The Maximum operator (MAX) limits a value to a specified 16-bit positive maximum. The syntax of MAX is: value MAX 2 ' Walk value from 100 to 0 ' Show value1, use MIN to clamp at 50 Limit Where value is a constant or variable value to perform the MAX function upon and limit is the maximum value that value is allowed to be. Its logic is, ‘if value is greater than limit, then make result = limit; if value is less than or equal to limit, make result = value.’ MAX works in positive math only; its comparisons are not valid when used on two’s complement negative numbers, since the positive-integer representation of a number like -1 ($FFFF or 65535 in unsigned decimal) is larger than that of a number like 10 ($000A or 10 decimal). Use MAX only with unsigned integers. Because of the way fixed-size integers work, you should be careful when using an expression involving MAX 65535. For example, 65535+1 MAX 65535 will result in 0 because of the way fixed-size integers wrap around. Page 116 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com MAXIMUM: MAX 1 All 2 4: BASIC Stamp Architecture – MAX, DIG, 1 SYMBOL SYMBOL value1 value2 = W0 = W1 FOR value1 = 0 TO 100 STEP 10 value2 = value1 MAX 50 DEBUG value2 NEXT ' Walk value1 from 0 to 100 ' Use MAX to clamp at 50 ' Show "clamped" value -- or -All 2 value VAR Word FOR value = 0 TO 100 STEP 10 DEBUG ? value MAX 50 NEXT DIGIT: DIG All 2 ' Walk value from 0 to 100 ' Show value, use MAX clamp at 50 The Digit operator (DIG) returns the specified decimal digit of a 16-bit positive value. Digits are numbered from 0 (the rightmost digit) to 4 (the leftmost digit of a 16-bit number; 0 to 65535). Example: value idx value = DEBUG ? FOR idx DEBUG NEXT SHIFT LEFT: > idx NEXT ' Repeat with idx = 1 to 16 ' Shift value right idx places The Reverse operator (REV) returns a reversed (mirrored) copy of a specified number of bits of a value, starting with the right-most bit (least significant bit or “lsb”). For instance, %10101101 REV 4 would return %1011, a mirror image of the right-most four bits of the value. Example: DEBUG BIN4 ? %10101101 REV 4 REVERSE: REV All 2 ' Mirror 1st 4 bits (%1011) The And operator (&) returns the bitwise AND of two values. Each bit of the values is subject to the following logic: AND: & 1 All 2 0 AND 0 = 0 0 AND 1 = 0 1 AND 0 = 0 1 AND 1 = 1 The result returned by & will contain 1s in only those bit positions in which both input values contain 1s. Example: SYMBOL SYMBOL SYMBOL value1 value2 result = B2 = B3 = B4 value1 = %00001111 value2 = %10101101 result = value1 & value2 DEBUG %result 1 ' Show result of AND (%00001101) -- or -DEBUG BIN8 ? %00001111 & %10101101 ' Show result of AND (%00001101) The OR operator (|) returns the bitwise OR of two values. Each bit of the values is subject to the following logic: Page 118 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com All 2 OR: | 1 All 2 4: BASIC Stamp Architecture – |, ^ 0 OR 0 = 0 0 OR 1 = 1 1 OR 0 = 1 1 OR 1 = 1 The result returned by | will contain 1s in any bit positions in which one or the other (or both) input values contain 1s. Example: 1 SYMBOL SYMBOL SYMBOL value1 value2 result = B2 = B3 = B4 value1 = %00001111 value2 = %10101001 result = value1 | value2 DEBUG %result ' Show result of OR (%10101111) -- or -DEBUG XOR: ^ All 2 BIN ? %00001111 | %10101001 ' Show result of OR (%10101111) The Xor operator (^) returns the bitwise XOR of two values. Each bit of the values is subject to the following logic: 0 XOR 0 = 0 0 XOR 1 = 1 1 XOR 0 = 1 1 XOR 1 = 0 The result returned by ^ will contain 1s in any bit positions in which one or the other (but not both) input values contain 1s. Example: 1 SYMBOL SYMBOL SYMBOL value1 value2 result = B2 = B3 = B4 value1 = %00001111 value2 = %10101001 result = value1 ^ value2 DEBUG %result ' Show result or XOR (%10100110) -- or -- BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 119 BASIC Stamp Architecture – &/, |/ DEBUG BIN8 ? %00001111 ^ %10101001 ' Show result of XOR (%10100110) The And Not operator (&/) returns the bitwise AND NOT of two values. Each bit of the values is subject to the following logic: All 2 AND NOT: &/ 1 0 AND NOT 0 = 0 0 AND NOT 1 = 0 1 AND NOT 0 = 1 1 AND NOT 1 = 0 The result returned by &/ will contain 1s in any bit positions in which the first value is 1 and the second value is 0. Example: SYMBOL SYMBOL SYMBOL value1 value2 result = B2 = B3 = B4 value1 = %00001111 value2 = %10101001 result = value1 &/ value2 DEBUG %result 1 ' Show result of AND NOT (%00000110) The Or Not operator (|/) returns the bitwise OR NOT of two values. Each bit of the values is subject to the following logic: OR NOT: |/ 1 0 OR NOT 0 = 1 0 OR NOT 1 = 0 1 OR NOT 0 = 1 1 OR NOT 1 = 1 The result returned by |/ will contain 1s in any bit positions in which the first value is 1 or the second value is 0. Example: SYMBOL SYMBOL SYMBOL value1 value2 result = B2 = B3 = B4 value1 = %00001111 value2 = %10101001 result = value1 |/ value2 DEBUG %result 1 ' Show result of OR NOT (%01011111) Page 120 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 4: BASIC Stamp Command Reference – ^/ XOR NOT: ^/ 1 The Xor Not operator (^/) returns the bitwise XOR NOT of two values. Each bit of the values is subject to the following logic: 0 XOR NOT 0 = 1 0 XOR NOT 1 = 0 1 XOR NOT 0 = 0 1 XOR NOT 1 = 1 The result returned by ^/ will contain 1s in any bit positions in which the first value and second values are equal. Example: 1 SYMBOL SYMBOL SYMBOL value1 value2 result = B2 = B3 = B4 value1 = %00001111 value2 = %10101001 result = value1 ^/ value2 DEBUG %result ' Show result of OR NOT (%01011001) BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 121 BASIC Stamp Architecture Page 122 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 5: BASIC Stamp Command Reference Introduction This chapter provides details on all three versions of the PBASIC Programming Language. A categorical listing of all available PBASIC commands is followed by an alphabetized command reference with syntax, functional descriptions, and example code for each command. PBASIC LANGUAGE VERSIONS There are three forms of the PBASIC language: PBASIC 1.0 (for the BS1), PBASIC 2.0 (for all BS2 models) and PBASIC 2.5 (for all BS2 models). You may use any version of the language that is appropriate for your BASIC Stamp module; however, when using any BS2 model, we suggest you use PBASIC 2.5 for any new programs you write because of the advanced control and flexibility it allows. PBASIC 2.5 is backward compatible with almost every existing PBASIC 2.0-based program, and code that is not 100% compatible can easily be modified to work in PBASIC 2.5. This chapter gives details on every command for every BASIC Stamp model. Be sure to pay attention to any notes in the margins and body text regarding supported models and PBASIC language versions wherever they apply. The BASIC Stamp Editor for Windows defaults to using PBASIC 1.0 (for the BS1) or PBASIC 2.0 (for all BS2 models). If you wish to use the default language for your BASIC Stamp model you need not do anything special. If you wish to use PBASIC 2.5, you must specify that fact, using the $PBASIC directive in your source code, for example: ' {$PBASIC 2.5} Review the Compiler Directives section of Chapter 3 for more details on this directive. Note: you may also specify either 1.0 or 2.0 using the $PBASIC directive if you wish to explicitly state those desired languages. Please note that the reserved word set will vary with each version of PBASIC, with additional reserved words for some BASIC Stamp models. Please see the reserved words tables in Appendix B for the complete lists. PBASIC 2.5 features many enhancements. Table 5.1 gives a brief summary of these items, with references to more information given elsewhere. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 123 BASIC Stamp Command Reference Feature Categories New Items DEBUGIN, Additional Commands DO...LOOP, EXIT, ON. SELECT...CASE IF...THEN, Enhanced Commands GET, PUT, READ, WRITE Description Allows easier user input and program control. See individual command descriptions. Improves program control, and SPRAM and EEPROM access. See individual command descriptions. Provides flexible, context-sensitive I/O pin Additional Directive PIN references; see page 99. Encourages development of source code #DEFINE, #ERROR, Conditional Compile that is compatible with multiple BASIC #IF...#THEN...#ELSE, Directives Stamp models and helpful user hints; see #SELECT...CASE page 70. CLRDN, CLREOL, CRSRDN, CRSRLF, Symbols for control characters supported by Additional CRSRRT, CRSRUP, the Debug Terminal. See Table 5.13 in the Predefined Constants CRSRX, CRSRXY, DEBUG command description, page 168. CRSRY, LF Any line can be continued to the next line after the comma (,) character wherever Syntax Enhancements commas are normally used. , and : Colons are required on label declarations. CATEGORICAL LISTING OF COMMANDS This section lists all available PBASIC commands for all BASIC Stamp models, grouped by category. Commands with PBASIC 2.5 enhanced syntax options are marked with (*); commands that exist only in PBASIC 2.5 are indicated with ( 2.5 ). One or more of these icons indicates the item applies to the BS1, BS2, BS2e, BS2sx, BS2p, BS2pe, or BS2px respectively. All 2 If an item applies to all of the models in the BS2 family, this icon is used. BRANCHING / PROGRAM CONTROL 1 All 2 BRANCH Jump to address specified by offset. 1 All 2 IF...THEN* Conditionally execute one or more blocks of code. 1 All 2 GOTO Jump to address. 1 All 2 GOSUB Jump to subroutine at address. Page 124 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com Table 5.1: PBASIC 2.5 Enhancements. 5: BASIC Stamp Command Reference All 2 ON2.5 1 All 2 All Jump to address or subroutine specified by an offset. RETURN Return from subroutine. RUN Switch execution to another program slot. POLLRUN Switch execution to another program page upon the occurrence of a polled interrupt. 2 SELECT …CASE2.5 All 2 STOP Evaluate expression and conditionally execute a block of code based on comparison to multiple conditions. Halt program execution until BASIC Stamp is reset. LOOPING STRUCTURES All 2 DO…LOOP2.5 Execute code block repetitively, with optional, conditional exit. All 2 EXIT2.5 1 All 2 FOR...NEXT Terminate execution of a looping code block (DO...LOOP or FOR...NEXT). Execute code block repetitively, a finite number of times using a counter. EEPROM ACCESS 1 All EEPROM 2 DATA Store data in EEPROM during program download. Store data in EEPROM during program download. 1 All 2 READ* Read EEPROM value into variable. 1 All 2 WRITE* Write value into EEPROM. STORE Switch READ/WRITE access to different program slot. RAM ACCESS GET* Read Scratch Pad RAM value into variable. PUT* Write value into Scratch Pad RAM. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 125 BASIC Stamp Command Reference NUMERICS 1 LET Optional instruction assignments. to perform variable 1 All 2 LOOKUP Look up data specified by offset and store in variable. This instruction provides a means to make a lookup table. 1 All 2 LOOKDOWN Find target’s matching value in table and store match number (0-N) in variable. 1 All 2 RANDOM Generate a pseudo-random number. DIGITAL I/O CONFIGPIN Configure pin properties. 1 All 2 INPUT Make pin an input. 1 All 2 OUTPUT Make pin an output. 1 All 2 REVERSE Reverse direction of a pin. 1 All 2 LOW Make pin output low. 1 All 2 HIGH Make pin output high. 1 All 2 TOGGLE Make pin an output and toggle state. 1 All 2 PULSIN Measure width of an input pulse. 1 All 2 PULSOUT Output a pulse by inverting a pin for a given amount of time. 1 All 2 BUTTON Debounce button, perform auto-repeat, and branch to address if button is in target state. All 2 COUNT Count cycles on a pin for a given amount of time. All 2 XOUT Generate X-10 power line control codes. AUXIO Switch control to auxiliary I/O pin group. MAINIO Switch control to main I/O pin group. IOTERM Switch control to specified I/O pin group. POLLIN Specify pin and state for a polled-interrupt. POLLOUT Specify pin and state for output upon a polledinterrupt. POLLMODE Specify the polled-interrupt mode. Page 126 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 5: BASIC Stamp Command Reference ASYNCHRONOUS SERIAL I/O 1 All 2 SERIN Input data in an asynchronous serial stream. 1 All 2 SEROUT Output data in an asynchronous serial stream. OWIN Input data from a 1-wire device. OWOUT Output data to a 1-wire device. SYNCHRONOUS SERIAL I/O 1 All 2 SHIFTIN Shift data in from synchronous serial device. 1 All 2 SHIFTOUT Shift data out to synchronous serial device. I2CIN Input data from I2C serial device. I2COUT Output data to I2C serial device. PARALLEL I/O LCDCMD Write a command to an LCD. LCDIN Read data from an LCD. LCDOUT Write data to an LCD. ANALOG I/O 1 All 2 1 All PWM Output using pulse width modulation, then return pin to input. POT Read a 5 kΩ - 50 kΩ potentiometer and scale result. 2 RCTIME Measure a variable resistance or capacitance. COMPARE Compare two 0-5 V analog voltages. PAUSE Pause execution for 0–65535 milliseconds. POLLWAIT Pause until a polled-interrupt occurs. SOUND Generate tones or white noise. TIME 1 All 2 SOUND 1 All 2 FREQOUT Generate one or two sine waves of specified frequencies. All 2 DTMFOUT Generate DTMF telephone tones. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 127 BASIC Stamp Command Reference POWER CONTROL 1 All 2 NAP Nap for a short period. Power consumption is reduced. 1 All 2 SLEEP Sleep for 1-65535 seconds. Power consumption is reduced. 1 All 2 END Sleep until the power cycles or the PC connects. Power consumption is reduced. PROGRAM DEBUGGING 1 All 2 All DEBUG 2 DEBUGIN2.5 Send information to the PC for viewing in the Debug Terminal’s Receive windowpane. Retrieve information from the user via the PC, entered into the Debug Terminal’s Transmit windowpane. SYNTAX CONVENTIONS BOLD UPPER CASE – any word that appears bold with all capital letters must be typed exactly as shown. These are all reserved words. Italics – italicized words must be replaced with your content. [ ] – square brackets must be typed, in the position shown around the given syntax element. Only used with PBASIC 2.0 and 2.5. ( ) – parentheses must be typed in the position shown around the given syntax element; only used this way with PBASIC 1.0.** { } – curly braces indicate optional syntax items. They are not typed as part of any syntax other than compiler directives. | – vertical line separates mutually exclusive syntax elements. , \ # = – where they appear, commas, backslashes, pound signs, and equal signs must be typed in the positions shown. **NOTE: You may use parentheses to enclose expressions in PBASIC 2.0 and 2.5, but they are not necessary. Used within an expression, parentheses will change the order of evaluation. See page 103 for details and examples. Page 128 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 5: BASIC Stamp Command Reference – AUXIO AUXIO BS1 BS2 BS2e BS2sx BS2p BS2pe BS2px AUXIO Function Switch from control of main I/O pins to auxiliary I/O pins (on the BS2p40 only). Quick Facts Table 5.2: AUXIO Quick Facts. I/O pin IDs Special Notes Related Commands BS2p, BS2pe, and BS2px 0 – 15 (just like main I/O, but after AUXIO command, all references affect physical pins 21 – 36). The BS2p, BS2pe, and BS2px 24-pin modules accept this command, however, only the BS2p40 gives access to the auxiliary I/O pins. MAINIO and IOTERM Explanation The BS2p, BS2pe, and BS2px are available as 24-pin modules that are pin compatible with the BS2, BS2e and BS2sx. Also available is a 40-pin module called the BS2p40, with an additional 16 I/O pins (for a total of 32). The BS2p40's extra, or auxiliary, I/O pins can be accessed in the same manner as the main I/O pins (by using the IDs 0 to 15) but only after issuing an AUXIO or IOTERM command. The AUXIO command causes the BASIC Stamp to affect the auxiliary I/O pins instead of the main I/O pins in all further code until the MAINIO or IOTERM command is reached, or the BASIC Stamp is reset or power-cycled. AUXIO is also used when setting the DIRS register for auxiliary I/O pins on the BS2p40. When the BASIC Stamp module is reset, all RAM variables including DIRS and OUTS are cleared to zero. This affects both main and auxiliary I/O pins. On the BS2p24, BS2pe, and BS2px, the auxiliary I/O pins from the interpreter chip are not connected to physical I/O pins on the BASIC Stamp module. While not connected to anything, these pins do have internal pull-up resistors activated, effectively connecting them to Vdd. After reset, reading the auxiliary I/O from a BS2p24, BS2pe24, or BS2px24 will return all 1s. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 129 AUXIO - BASIC Stamp Command Reference Here is a simple AUXIO example: HIGH 0 AUXIO LOW 0 A SIMPLE AUXIO EXAMPLE. ' make P0 high ' select auxiliary pins ' make X0 low The first line of the above example will set I/O pin 0 of the main I/O pins (P0, physical pin 5) high. Afterward, the AUXIO command tells the BASIC Stamp that all commands following it should affect the auxiliary I/O pins. The following LOW command will set I/O pin 0 of the auxiliary I/O pins (X0, physical pin 21) low. Note that the main I/O and auxiliary I/O pins are independent of each other; the states of the main I/O pins remain unchanged while the program affects the auxiliary I/O pins, and vice versa. MAIN I/O AND AUXILIARY I/O PINS ARE INDEPENDENT AND UNAFFECTED BY CHANGES IN THE OPPOSITE GROUP. Other commands that affect I/O group access are MAINIO and IOTERM. 2 Demo Program (AUX_MAIN_TERM.bsp) p ' AUX_MAIN_TERM.bsp ' This program demonstrates the use of the AUXIO, MAINIO and IOTERM ' commands to affect I/O pins in the auxiliary and main I/O groups. ' {$STAMP BS2p} ' {$PBASIC 2.5} #SELECT $STAMP #CASE BS2, BS2E, BS2SX #ERROR "Program requires BS2p40" #CASE BS2P, BS2PE, BS2PX DEBUG "Note: This program designed for the BS2p40.", CR #ENDSELECT port VAR Main: DO MAINIO TOGGLE 0 PWM 1, 100, 40 AUXIO TOGGLE 0 PULSOUT 1, 1000 PWM 2, 100, 40 Bit ' Switch to main I/O pins ' Toggle state of I/O pin P0 ' Generate PWM on I/O pin P1 ' ' ' ' Switch to auxiliary Toggle state of I/O Generate a pulse on Generate PWM on I/O Page 130 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com I/O pin I/O pin pins X0 pin X1 X2 NOTE: This example program will tokenize with the 24-pin BS2p , BS2pe, and BS2px, but its effects can only be seen on the BS2p40. This program uses conditional compilation techniques; see Chapter 3 for more information. 5: BASIC Stamp Command Reference – AUXIO IOTERM port TOGGLE 3 port = ~port PAUSE 1000 LOOP END ' ' ' ' ' ' Switch to main or aux I/Os -- depending on port Toggle state of I/O pin 3 -- on main and aux, alternately Invert port 1 second delay BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 131 AUXIO - BASIC Stamp Command Reference Page 132 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 5: BASIC Stamp Command Reference – BRANCH BRANCH 1 All 2 BS1 BS2 BS2e BS2sx BS2p BS2pe BS2px BRANCH Offset, ( Address0, Address1, ...AddressN ) BRANCH Offset, [ Address0, Address1, ...AddressN ] Function 1 NOTE: Expressions are not allowed as arguments on the BS1. Go to the address specified by offset (if in range). • Offset is a variable/constant/expression (0 – 255) that specifies the index of the address, in the list, to branch to (0 – N). • Addresses are labels that specify where to go. BRANCH will ignore any list entries beyond offset 255. Quick Facts Table 5.3: BRANCH Quick Facts. Limit of Address Entries Related Commands BS1 All BS2 Models Limited only by memory 256 None ON...GOTO Explanation The BRANCH instruction is useful when you want to write something like this: IF value = 0 THEN Case_0 IF value = 1 THEN Case_1 IF value = 2 THEN Case_2 ' when value is 0, jump to Case_0 ' when value is 1, jump to Case_1 ' when value is 2, jump to Case_2 1 You can use BRANCH to organize this into a single statement: BS1 syntax not shown here. BRANCH value, [Case_0, Case_1, Case_2] This works exactly the same as the previous IF...THEN example. If the value isn’t in range (in this case if value is greater than 2), BRANCH does nothing and the program continues with the next instruction after BRANCH. BRANCH can be teamed with the LOOKDOWN instruction to create a simplified SELECT...CASE statement. See LOOKDOWN for an example. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 133 BRANCH – BASIC Stamp Command Reference Demo Program (BRANCH.bs1) 1 ' BRANCH.bs1 ' This program shows how the value of idx controls the destination of the ' BRANCH instruction. ' {$STAMP BS1} ' {$PBASIC 1.0} SYMBOL idx = B2 Main: DEBUG "idx: ", #idx, " " BRANCH idx, (Task_0, Task_1, Task_2) DEBUG "BRANCH target error...", CR, CR Next_Task: idx = idx + 1 // 4 GOTO Main ' branch to task ' ... unless out of range ' force idx to be 0..3 Task_0: DEBUG "BRANCHed to Task_0", CR GOTO Next_Task Task_1: DEBUG "BRANCHed to Task_1", CR GOTO Next_Task Task_2: DEBUG "BRANCHed to Task_2", CR GOTO Next_Task Demo Program (BRANCH.bs2) All ' BRANCH.bs2 ' This program shows how the value of idx controls the destination of the ' BRANCH instruction. ' {$STAMP BS2} ' {$PBASIC 2.5} idx VAR Nib Main: DEBUG "idx: ", DEC1 idx, " " BRANCH idx, [Task_0, Task_1, Task_2] DEBUG "BRANCH target error...", CR, CR ' branch to task ' ... unless out of range Next_Task: idx = idx + 1 // 4 ' force idx to be 0..3 Page 134 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 2 NOTE: This example program can be used with all BS2 models by changing the $STAMP directive accordingly. 5: BASIC Stamp Command Reference – BRANCH PAUSE 250 GOTO Main Task_0: DEBUG "BRANCHed to Task_0", CR GOTO Next_Task Task_1: DEBUG "BRANCHed to Task_1", CR GOTO Next_Task Task_2: DEBUG "BRANCHed to Task_2", CR GOTO Next_Task BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 135 BRANCH – BASIC Stamp Command Reference Page 136 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 5: BASIC Stamp Command Reference – BUTTON BUTTON 1 All 2 BS1 BS2 BS2e BS2sx BS2p BS2pe BS2px BUTTON Pin, DownState, Delay, Rate, Workspace, TargetState, Address Function 1 NOTE: Expressions are not allowed as arguments on the BS1. The range of the Pin argument on the BS1 is 0 – 7. Monitor and process a pushbutton input, perform auto-repeat, and branch to address if button is in target state. Button circuits may be active-low or active-high. • Pin is a variable/constant/expression (0–15) that specifies the I/O pin to use. This pin will be set to input mode. • DownState is a variable/constant/expression (0 or 1) that specifies which logical state occurs when the button is pressed. • Delay is a variable/constant/expression (0 – 255) that specifies how long the button must be pressed before auto-repeat starts. The delay is measured in cycles of the BUTTON routine. Delay has two special settings: 0 and 255. If Delay is 0, BUTTON performs no debounce or auto-repeat. If Delay is 255, BUTTON performs debounce, but no auto-repeat. • Rate is a variable/constant/expression (0 – 255) that specifies the number of cycles between auto-repeats. The rate is expressed in cycles of the BUTTON routine. • Workspace is a byte variable used by BUTTON for workspace. It must be cleared to 0 before being used by BUTTON for the first time and should not be adjusted outside of the BUTTON command. NOTE: All RAM is cleared to 0 by default upon power-up or reset of the BASIC Stamp module. • TargetState is a variable/constant/expression (0 or 1) that specifies which state the button should be in for a branch to occur. (0=not pressed, 1=pressed) • Address is a label that specifies where to branch if the button is in the target state. Explanation When you press a button or flip a switch, the contacts make or break a connection. A brief (1 to 20-ms) burst of noise occurs as the contacts scrape and bounce against each other. By scanning an input within a loop to BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 137 BUTTON – BASIC Stamp Command Reference ensure that the contact remains in a specified state for a minimum duration, spurious multiple inputs caused by contact noise can be eliminated. The BUTTON instruction helps prevent this noise from being interpreted as more than one switch action; this is the function of the Delay parameter. For a demonstration of switch bounce, see the demo program for the COUNT instruction. Delay, combined with the Rate argument, allows the programmer to control the rate at which multiple inputs are accepted by the BASIC Stamp. BUTTON also lets PBASIC react to a button press the way your computer keyboard does to a key press. When you press a key, a character immediately appears on the screen. If you hold the key down, there’s a delay, then a rapid-fire stream of characters appears on the screen. BUTTON’s auto-repeat function can be set up to work much the same way. BUTTON is designed for use inside a program loop. Each time through the loop, BUTTON checks the state of the specified pin. When it first matches DownState, BUTTON begins the Delay countdown for auto-repeat. Then, in accordance with TargetState, it either branches to Address (TargetState = 1) or doesn’t (TargetState = 0). If the switch stays in DownState, BUTTON counts the number of program loops that execute. When this count equals Delay, BUTTON once again triggers the action specified by TargetState and Address. Hereafter, if the switch remains in DownState, BUTTON waits Rate number of cycles between actions. The Workspace variable is used by BUTTON to keep track of how many cycles have occurred since the Pin switched to TargetState or since the last auto-repeat. BUTTON does not stop program execution. In order for its delay and auto-repeat functions to work properly, BUTTON must be executed from within a program loop. Page 138 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 5: BASIC Stamp Command Reference – BUTTON Figure 5.1: Sample BUTTON circuits. Active-high (left) and active-low (right). 1 Demo Program (BUTTON.bs1) ' ' ' ' ' ' ' BUTTON.bs1 Connect an active-low circuit to pin P0 of the BS1. When you press the button, the DEBUG screen will display an asterisk (*). The program, as shown below, will print an asterisk at the first button press, then delay approximately one second (200 x 5 ms PAUSE) before auto-repeating at a rate of approximately 100 ms (5 x 20 ms). Feel free to modify the program to see the effects of your changes on the way BUTTON responds. ' {$STAMP BS1} ' {$PBASIC 1.0} SYMBOL Btn = 0 SYMBOL btnWrk = B2 Main: ' Try changing the Delay value (200) in BUTTON to see the effect of ' its modes: 0 = no delay; 1-254 = varying delays before auto-repeat; ' 255 = no auto-repeat (only one action per button press) ' ' The BUTTON instruction will cause the program to branch to ' No_Press unless P0 = 0 PAUSE 5 BUTTON Btn, 0, 200, 20, btnWrk, 0, No_Press DEBUG "*" No_Press: GOTO Main BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 139 BUTTON – BASIC Stamp Command Reference Demo Program (BUTTON.bs2) ' ' ' ' ' ' ' BUTTON.bs2 Connect an active-low circuit to pin P0 of the BS2. When you press the button, the DEBUG screen will display an asterisk (*). The program, as shown below, will print an asterisk at the first button press, then delay approximately one second (200 x 5 ms PAUSE) before auto-repeating at a rate of approximately 100 ms (5 x 20 ms). Feel free to modify the program to see the effects of your changes on the way BUTTON responds. ' {$STAMP BS2} ' {$PBASIC 2.5} Btn PIN 0 btnWrk VAR Byte Main: ' Try changing the Delay value (200) in BUTTON to see the effect of ' its modes: 0 = no delay; 1-254 = varying delays before auto-repeat; ' 255 = no auto-repeat (only one action per button press) ' ' The BUTTON instruction will cause the program to branch to ' No_Press unless P0 = 0 PAUSE 5 BUTTON Btn, 0, 200, 20, btnWrk, 0, No_Press DEBUG "*" No_Press: GOTO Main Page 140 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com All 2 NOTE: This example program can be used with all BS2 models by changing the $STAMP directive accordingly. 5: BASIC Stamp Command Reference – COMPARE COMPARE BS1 BS2 BS2e BS2sx BS2p BS2pe BS2px COMPARE Mode, Variable Function Enable or disable comparator, compare voltages on P1 and P2 and retrieve comparison result to store in Variable. • Mode is a variable/constant/expression (0 – 2) that enables or disables the comparator (input pins P1 and P2) and determines if the optional comparator output pin (pin P0) is enabled or not. See Table 5.4 for an explanation of the Mode values. • Variable is a variable (usually a bit) in which the comparison result is stored. Quick Facts Table 5.4: COMPARE Quick Facts. BS2px 0: Disables comparator Mode Values 1: Enables comparator with P0 as result output 2: Enables comparator without P0 as result output 0: Voltage P1 > P2; P0 optionally outputs 0 Variable Values 1: Voltage P1 < P2; P0 optionally outputs 1 Explanation The COMPARE command enables or disables the built-in comparator hardware on the BS2px’s I/O pins P0, P1, and P2. I/O pins P1 and P2 are the comparator inputs and P0 is optionally the comparator result output pin. By default, the comparator feature is disabled. Using the COMPARE command with a Mode argument of 1 or 2 enables the comparator feature (using input pins P1 and P2) and returns the result of the comparison in Variable. If Mode is 1, the result of the comparison is also output on I/O pin P0. The following is an example of the COMPARE command: Result COMPARE VAR 1, Bit Result This example enables the comparator (setting P0 to output the result, with P1 and P2 as the comparator inputs) and writes the result of the comparison into Result. Both Result and the output pin P0 will be 0 if the BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 141 COMPARE – BASIC Stamp Command Reference input voltage on P1 was greater than that of P2. Result and the output pin P0 will be 1 if the input voltage on P1 was less than that of P2. Note that the comparator hardware operates independently of the execution speed of the BS2px and will continue to run and update P0 if Mode = 1, even during sleep mode (execution of END, NAP, POLLWAIT 8, or SLEEP commands). To avoid spurious current draw during sleep mode, disable the comparator first. Demo Program (COMPARE.bpx) ' ' ' ' ' ' COMPARE.bpx This example demonstrates the use of the COMPARE command. Connect two variable voltage sources (0 to 5 volts) on I/O pins P1 and P2 (or a button on each pin connected to ground). Run the program and watch the Debug Terminal display as you adjust the variable voltage or press the buttons. ' {$STAMP BS2px} ' {$PBASIC 2.5} Result VAR Bit #IF $STAMP BS2PX #THEN #ERROR "This program requires a BS2px." #ENDIF Setup: CONFIGPIN DIRECTION, %0000000000000001 'P0 = output, all others = input CONFIGPIN PULLUP, %0000000000000110 'Enable pull-ups on P1 and P2 DEBUG "BS2px COMPARATOR DEMONSTRATION", CR, "==============================", CR, "Input Voltage: P1 > P2", CR, "Output State: P0 = 0" Main: DO COMPARE 1, Result IF Result = 0 THEN DEBUG CRSRXY,18,2,">" ELSE DEBUG CRSRXY,18,2," " DEBUGIN DEC1 myNum IF ((myNum >= 1) AND (myNum = 3) ' test after loop statements The difference is that with this loop, the code block will always be run at least once before the condition is tested and will continue to run as long as the UNTIL condition evaluates as False. Page 176 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 5: BASIC Stamp Command Reference – DO...LOOP Note that the WHILE test (loop runs WHILE Condition is True) and UNTIL test (loop runs UNTIL Condition is True) can be interchanged, but they are generally used as illustrated above. All 2 NOTE: This example program can be used with all BS2 models by changing the $STAMP directive accordingly. Demo Program (DO-LOOP.bs2) ' ' ' ' ' ' DO-LOOP.bs2 This program creates a little guessing game. It starts by creating a (pseudo) random number between 1 and 10. The inner loop will run until the answer is guessed or 10 tries have been attempted. The outer loop has no condition and will cause the inner loop code to run until the BASIC Stamp is reprogrammed. ' {$STAMP BS2} ' {$PBASIC 2.5} rVal answer guess tries VAR VAR VAR VAR Word Byte Byte Nib Main: DO RANDOM rVal answer = rVal.LOWBYTE */ 10 + 1 tries = 0 ' ' ' ' random value game answer player guess number of tries ' create 1 - 10 answer DO ' get answer until out of tries DEBUG CLS, "Guess a number (1 - 10): " DEBUGIN DEC guess ' get new guess tries = tries + 1 ' update tries count LOOP UNTIL ((tries = 10) OR (guess = answer)) IF (guess = answer) THEN ' test reason for loop end DEBUG CR, "You got it!" ELSE DEBUG CR, "Sorry ... the answer was ", DEC answer, "." ENDIF PAUSE 1000 LOOP ' run again END BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 177 DO...LOOP – BASIC Stamp Command Reference Page 178 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 5: BASIC Stamp Command Reference – DTMFOUT DTMFOUT All 2 BS1 BS2 BS2e BS2sx BS2p BS2pe BS2px DTMFOUT Pin, { OnTime, OffTime, } [ Tone {, Tone…} ] Function Generate dual-tone, multifrequency tones (DTMF, i.e., telephone “touch” tones). • Pin is a variable/constant/expression (0 – 15) that specifies the I/O pin to use. This pin will be set to output mode during generation of tones and set to input mode afterwards. • OnTime is an optional variable/constant/expression (0 – 65535) specifying a duration of the tone. The unit of time and the default time for OnTime is described in Table 5.19. • OffTime is an optional variable/constant/expression (0 – 65535) specifying the length of silent pause after a tone (or between tones, if multiple tones are specified). The unit of time and the default time for OffTime is described in Table 5.19. • Tone is a variable/constant/expression (0 – 15) specifying the DTMF tone to generate. Tones 0 through 11 correspond to the standard layout of the telephone keypad, while 12 through 15 are the fourthcolumn tones used by phone test equipment and in ham-radio applications. Quick Facts Table 5.19: DMTFOUT Quick Facts. Default OnTime Default OffTime Units in OnTime Units in OffTime Related Command BS2, BS2e 200 ms 50 ms 1 ms 1 ms BS2sx 80 ms 50 ms 0.4 ms 1 ms BS2p 55 ms 50 ms 0.265 ms 1 ms FREQOUT BS2pe 196 ms 50 ms 1 ms 1 ms BS2px 34 ms 50 ms 0.166 ms 1 ms Explanation DTMF tones are used to dial the phone or remotely control certain radio equipment. The BASIC Stamp can generate these tones digitally using the DTMFOUT instruction. Figure 5.4 shows how to connect a speaker or audio amplifier to hear these tones and Figure 5.5 shows how to connect the BASIC Stamp to the phone line. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 179 DTMFOUT – BASIC Stamp Command Reference The following DTMFOUT instruction will generate DTMF tones on I/O pin 10: DTMFOUT 10, [6, 2, 4, 8, 3, 3, 3] ' Call Parallax If the BASIC Stamp is connected to the phone line properly, the above command would be equivalent to dialing 624-8333 from a phone keypad. If you wanted to slow the pace of the dialing to accommodate a noisy phone line or radio link, you could use the optional OnTime and OffTime values: DTMFOUT 10, 500, 100, [ 6, 2, 4, 8, 3, 3, 3] ' Call Parallax, slowly In this example, on a BS2 the OnTime is set to 500 ms (1/2 second) and OffTime to 100 ms (1/10th second). Tone Value 0–9 10 11 12 – 15 Corresponding Telephone Key Digits 0 through 9 Star (*) Pound (#) Fourth column tones A through D Driving an Audio Amplifier 1k 1k Amplifier (e.g., Radio Shack from I/O pin 0.01µF 0.1µF Vss 277-1008C) Vss Vss Driving a Speaker 10µF (both) from I/O pin + C1 + C2 ≥40Ω Speaker (or 8Ω in series with 33Ω resistor) Vss Vss Notes: C1 may be omitted for piezo speakers C2 is optional, but reduces high-frequency noise Page 180 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com Table 5.20: DTMF Tones and Corresponding Telephone Keys. Figure 5.4: Example RC Filter Circuits for Driving an Audio Amplifier (top) or a Speaker (bottom). 5: BASIC Stamp Command Reference – DTMFOUT The BASIC Stamp microcontroller is a purely digital device. DTMF tones are analog waveforms, consisting of a mixture of two sine waves at different audio frequencies. So how does a digital device generate analog output? The BASIC Stamp creates and mixes the sine waves mathematically, then uses the resulting stream of numbers to control the duty cycle of a very fast pulse-width modulation (PWM) routine. So what’s actually coming out of the I/O pin is a rapid stream of pulses. The purpose of the filtering arrangements shown in Figure 5.4 and Figure 5.5 is to smooth out the high-frequency PWM, leaving only the lower frequency audio behind. TECHNICAL BACKGROUND. Keep this in mind if you want to interface BASIC Stamp's DTMF output to radios and other equipment that could be adversely affected by the presence of high-frequency noise on the input. Make sure to filter the DTMF output thoroughly. The circuits in Figure 5.4 are only a starting point; you may want to use an active low-pass filter with a roll-off point around 2 kHz. Figure 5.5: Example DAA Circuit to Interface to a Standard Telephone Line. Interfacing to the Telephone Line connect switch (or relay contacts) phone line (red and green) 600-600Ω transformer (JC: 117760) 10Ω (both) 270V “Sidactor” (DK: P3000AA61-ND P3000AA61-ND) Digi-Key (DK), 1-800-344-4539 or 218-681-6674 All 2 NOTE: This example program can be used with all BS2 models. This program uses conditional compilation techniques; see Chapter 3 for more information. 1 kΩ 0.1µF from I/O pin 0.001µF 3.9V zeners (both) DK: 1N5228BCT-ND Vss Jameco (JC), 1-800-831-4242 or 415-592-8097 Demo Program (DTMFOUT.bs2) ' ' ' ' ' ' ' DTMFOUT.bs2 This demo program is a rudimentary memory dialer. Since DTMF digits fit within a nibble (four bits), the program below packs two DTMF digits into each byte of three EEPROM data tables. The end of phone number is marked by the nibble $F, since this is not a valid phone-dialing digit. Conditional compilation sets the timing adjustment factor so that the output will sound the same on any BS2 model. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 181 DTMFOUT – BASIC Stamp Command Reference ' {$STAMP BS2} ' {$PBASIC 2.5} Spkr PIN 10 #SELECT $STAMP #CASE BS2, BS2E, BS2PE TmAdj CON $100 #CASE BS2SX TmAdj CON $280 #CASE BS2P TmAdj CON $3C5 #CASE BS2PX TmAdj CON $607 #ENDSELECT ' DTMF output on pin 10 ' x 1.0 (time adjust) ' x 2.5 ' x 3.77 ' x 6.03 eeLoc eeByte dtDig phone hiLo VAR VAR VAR VAR VAR Byte Byte eeByte.NIB1 Nib Bit ' ' ' ' ' EEPROM address of stored number Byte containing two DTMF digits Digit to dial Pick a phone # Bit to select upper and lower nib Parallax ParallaxFax Information DATA DATA DATA $19,$16,$62,$48,$33,$3F $19,$16,$62,$48,$00,$3F $15,$20,$55,$51,$21,$2F ' Phone: 1-916-624-8333 ' Phone: 1-916-624-8003 ' Phone: 1-520-555-1212 Main: FOR phone = 0 TO 2 ' retrieve address LOOKUP phone, [Parallax, ParallaxFax, Information], eeLoc GOSUB Dial_Number PAUSE 2000 NEXT END Dial_Number: DO READ eeLoc, eeByte ' eeLoc = eeLoc + 1 ' FOR hiLo = 0 TO 1 ' IF (dtDig = $F) THEN EXIT ' DTMFOUT Spkr, ' 150 */ TmAdj, 25, [dtDig] ' eeByte = eeByte 9) THEN EXIT DEBUG CRSRXY, (col * 8), row, DEC col, "/", DEC row, CR NEXT col = col + 1 IF (col = 3) THEN EXIT LOOP END ' ' ' ' attempt 10 iterations attempt 16 iterations terminate when row > 9 print col/row at location ' update column ' terminate when col = 3 Page 190 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 5: BASIC Stamp Command Reference – FOR...NEXT FOR…NEXT 1 BS1 BS2 BS2e BS2sx BS2p BS2pe BS2px FOR Counter = StartValue TO EndValue { STEP {-} StepValue } Statement(s) NEXT { Counter } All 2 FOR Counter = StartValue TO EndValue { STEP StepValue } Statement(s) NEXT { Counter } Function 1 NOTE: Expressions are not allowed as arguments on the BS1. 1 NOTE: Use a minus sign to indicate negative StepValues on the BS1. Create a repeating loop that executes the Statement(s), one or more program lines that form a code block, between FOR and NEXT, incrementing or decrementing Counter according to StepValue until the value of the Counter variable passes the EndValue. • Counter is a variable (usually a byte or a word) used as a counter. • StartValue is a variable/constant/expression (0 – 65535) that specifies the initial value of the variable (Counter). • EndValue is a variable/constant/expression (0 – 65535) that specifies the end value of the variable (Counter). When the value of Counter is outside of the range StartValue to EndValue, the FOR...NEXT loop stops executing and the program goes on to the instruction after NEXT. • StepValue is an optional variable/constant/expression (0 – 65535) by which the Counter increases or decreases with each iteration through the FOR…NEXT loop. On the BS1, use a minus sign (-) in front of the StepValue to indicate a negative step. On all BS2 models, if StartValue is larger than EndValue, PBASIC understands StepValue to be negative, even though no minus sign is used. • Statement is any valid PBASIC instruction. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 191 FOR…NEXT – BASIC Stamp Command Reference Quick Facts BS1 All BS2 Models 8 16 Set StartValue > EndValue and Set StartValue > EndValue enter negative StepValue* Exit loop if Counter exceeds Exit loop if Counter outside range Counter Comparison EndValue set by StartValue to EndValue None DO...LOOP and EXIT Related Commands *NOTE: For the BS1, direction (increment or decrement) cannot be changed at run-time. Max. Nested Loops To Decrement Counter Variable Table 5.25: FOR...NEXT Quick Facts. Explanation FOR...NEXT loops let your program execute a series of instructions for a specified number of repetitions (called iterations). By default, each time through the loop, the Counter variable is incremented by 1. It will continue to loop until the value of Counter is outside of the range set by StartValue and EndValue. Also, FOR…NEXT loops always execute at least once. The simplest form is shown here: SIMPLEST FORM OF FOR...NEXT. 1 NOTE: On the BS1, the loop will continue until Counter has gone past EndValue. reps NOTE: Replace the first line with SYMBOL reps = B0 on the BS1. VAR Nib FOR reps = 1 TO 3 DEBUG "*" NEXT ' counter for the FOR/NEXT loop ' repeat with reps = 1, 2, 3 ' put * on screen for each repetition In the above code, the FOR command sets reps = 1. Then the DEBUG line (within the FOR…NEXT loop) is executed; printing an asterisk (*) on the screen. When the BASIC Stamp sees the NEXT command, it goes back to the previous FOR command, adds 1 to reps and compares the result to the range set by StartValue and EndValue. If reps is still within range, it executes the code in the loop again. Each time the FOR...NEXT loop executes, the value of reps is updated (incremented by 1) and the code within the loop (the DEBUG line) is executed; printing another asterisk on the screen. This code will run through the loop three times; setting reps to 1, 2 and 3, and printing three asterisks on the screen. After the third loop, again the BASIC Stamp goes back up to the FOR command, adds 1 to reps and compares the result (4 in this case) to the range. Since the range is 1 to 3 and the value is 4 (outside the range) the FOR…NEXT loop is done and the BASIC Stamp will jump down to the first line of code following the NEXT command. You can view the changing values of reps by including the reps variable in a DEBUG command within the loop: Page 192 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 1 PROCESSING A FOR…NEXT LOOP. 5: BASIC Stamp Command Reference – FOR...NEXT NOTE: Change the first line as noted 1 above and replace line 3 with DEBUG #Reps, CR reps VAR Nib FOR reps = 1 TO 3 DEBUG DEC reps, CR NEXT ' counter for the FOR/NEXT loop ' repeat with reps = 1, 2, 3 ' print rep number Running this example should display "1" , "2", and "3" on the screen. FOR…NEXT can also be made to decrement (rather than increment) the Counter variable. The BS1 does this when you specify a negative StepValue (as well as a StartValue that is greater than the EndValue). All other BASIC Stamp models do this automatically when the StartValue is greater than the EndValue. Examples of both are shown below: DECREMENTING THE COUNTER INSTEAD OF INCREMENTING IT. 1 SYMBOL reps = B0 FOR reps = 3 TO 1 STEP -1 DEBUG #reps, CR NEXT ' counter for the FOR/NEXT loop ' repeat with reps = 3, 2, 1 ' print reps number -- or -All 2 reps VAR Nib FOR reps = 3 TO 1 DEBUG DEC reps, CR NEXT ' counter for the FOR/NEXT loop ' repeat with reps = 3, 2, 1 ' print reps number All 2 Note that the code for all the BS2 models did not use the optional STEP argument. This is because we wanted to decrement by positive 1 anyway (the default unit) and the BASIC Stamp realizes it needs to decrement because the StartValue is greater than the EndValue. A negative StepValue on any BS2 model would be treated as its positive, twos complement counterpart. For example, –1 in twos complement is 65535. So the following code executes only once: All 2 reps VAR Nib FOR reps = 3 TO 1 STEP -1 DEBUG DEC reps, CR NEXT ' counter for the FOR/NEXT loop ' try to decrement 3 by 65535 ' print reps number The above code would run through the loop once with reps set to 3. The second time around, it would decrement reps by 65535 (-1 is 65535 in twos complement) effectively making the number –65532 (4 in twos complement) which is outside the range of the loop. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 193 FOR…NEXT – BASIC Stamp Command Reference All the arguments in the FOR…NEXT command can be constants, variables or expressions on all BS2 models. This leads to some interesting uses. For example, if you make the StartValue and EndValue a variable, and change their values within the loop, you'll change the behavior of the loop itself. Try the following: {' $PBASIC 2.5} reps startVal endVal USING VARIABLES AS ARGUMENTS. All VAR VAR VAR Byte Byte Byte 2 ' counter for the FOR/NEXT loop 1 startVal = 1 endVal = 3 ' initialize startVal to 1 ' initialize endVal to 3 FOR reps = startVal TO endVal DEBUG DEC reps, CR IF (reps = 3) THEN startVal = 3 endVal = 1 ENDIF NEXT ' repeat for 1 to 3 NOTE: The increment/decrement direction of the FOR…NEXT loop cannot be changed on the BS1. ' if reps =3, swap startVal/endVal ' otherwise continue loop Here the loop starts with a range of 1 to 3. First, the DEBUG line prints the value of reps. Then the IF…THEN line makes a decision; if reps is equal to 3, then swap the order of startVal and endVal, otherwise continue the loop execution. The next time through the loop (after startVal and endVal have been swapped), reps will be decremented instead of incremented because startVal is greater than endVal. The result is a display on the screen of the numbers 1, 2, 3, 2, 1. The following example uses the value of reps as the StepValue. This creates a display of power's of 2 (1, 2, 4, 8, 16, 32, 64, etc): reps VAR Word FOR reps = 1 TO 256 STEP reps DEBUG DEC ? reps NEXT ' counter for the loop ' each loop add current value of reps ' show reps in Debug window There is a potential bug that you should be careful to avoid. The BASIC Stamp uses unsigned 16-bit integer math for any math operation it performs, regardless of the size of values or variables. The maximum value the BASIC Stamp can internally calculate is 65535 (the largest 16-bit Page 194 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 1 NOTE: For BS1's, change line 1 to SYMBOL reps = W0 and line 3 to DEBUG reps WATCH OUT FOR 16-BIT ROLLOVER, OR VARIABLE RANGE, ERRORS. 5: BASIC Stamp Command Reference – FOR...NEXT number). If you add 1 to 65535, you get 0 as the 16-bit register rolls over (like a car’s odometer does when you exceed the maximum mileage it can display). Similarly, if you subtract 1 from 0, you'll get 65535 as the 16-bit register rolls under (a rollover in the opposite direction). If you write a FOR...NEXT loop who's StepValue would cause Counter to go past 65535, this rollover may cause the loop to execute more times than you expect. Try the following example: 1 reps NOTE: For BS1's, change line 1 to SYMBOL reps = W0 and line 3 to DEBUG reps VAR Word FOR reps = 0 TO 65535 STEP 3000 DEBUG DEC ? reps NEXT ' counter for the loop ' each loop add 3000 ' show reps in Debug window The value of reps increases by 3000 each trip through the loop. As it approaches the EndValue, an interesting thing happens; reps is: 57000, 60000, 63000, 464, 3464... It passes the EndValue, rolls over and keeps going. That’s because the result of the calculation 63000 + 3000 exceeds the maximum capacity of a 16-bit number and then rolls over to 464. When the result of 464 is tested against the range (“Is Reps > 0 and is Reps < 65535?”) it passes the test and the loop continues. A similar symptom can be seen in a program who's EndValue is mistakenly set higher than what the counter variable can hold. The example below uses a byte-sized variable, but the EndValue is set to a number greater than what will fit in a byte: SYMBOL reps = B2 FOR reps = 0 TO 300 DEBUG reps NEXT ' counter for the loop ' each loop add 1 ' show reps in Debug window 1 -- or -All 2 reps VAR Byte FOR reps = 0 TO 300 DEBUG DEC ? reps NEXT ' counter for the loop ' each loop add 1 ' show reps in Debug window Here, reps is a byte variable; which can only hold the number range 0 to 255. The EndValue is set to 300, however; greater than 255. This code will loop endlessly because when reps is 255 and the FOR…NEXT loop adds 1, BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 195 FOR…NEXT – BASIC Stamp Command Reference reps becomes 0 (bytes will rollover after 255 just like words will rollover after 65535). The result, 0, is compared against the range (0 – 255) and it is found to be within the range, so the FOR…NEXT loop continues. It's important to realize that on all the BS2 models, the test is against the entire range, not just the EndValue. The code below is a slight modification of the previous example (the StartValue is 10 instead of 0) and will not loop endlessly. reps VAR Byte ' counter for the loop FOR reps = 10 TO 300 DEBUG DEC ? reps NEXT NOTE: On the BS1, the loop will continue until Counter has gone past EndValue. The rollover error will still occur if the BS1 cannot determine if Counter went past EndValue. All ' each loop add 1 ' show reps in Debug window reps still rolls over to 0, as before, however, this time it is outside the range of 10 to 255. The loop stops, leaving reps at 0. Note that this code is still in error since reps will never reach 300 until it is declared as a Word. Demo Program (FOR-NEXT.bs1) ' ' ' ' ' ' 1 FOR-NEXT.bs1 This example uses a FOR...NEXT loop to churn out a series of sequential squares (numbers 1, 2, 3, 4... raised to the second power) by using a variable to set the FOR...NEXT StepValue, and incrementing StepValue within the loop. Sir Isaac Newton is generally credited with the discovery of this technique. ' {$STAMP BS1} ' {$PBASIC 1.0} SYMBOL SYMBOL square stepSize = B2 = B3 ' FOR/NEXT counter ' step size increases by 2 each loop Setup: stepSize = 1 square = 1 Main: FOR square = 1 TO 250 STEP stepSize DEBUG square stepSize = stepSize + 2 NEXT END ' ' ' ' show squares up to 250 display on screen add 2 to stepSize loop until square > 250 Page 196 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 2 5: BASIC Stamp Command Reference – FOR...NEXT All 2 NOTE: This example program can be used with all BS2 models by changing the $STAMP directive accordingly. Demo Program (FOR-NEXT.bs2) ' ' ' ' ' ' FOR-NEXT.bs2 This example uses a FOR...NEXT loop to churn out a series of sequential squares (numbers 1, 2, 3, 4... raised to the second power) by using a variable to set the FOR...NEXT StepValue, and incrementing StepValue within the loop. Sir Isaac Newton is generally credited with the discovery of this technique. ' {$STAMP BS2} ' {$PBASIC 2.5} square stepSize VAR VAR Byte Byte ' FOR/NEXT counter ' step size increases by 2 each loop Setup: stepSize = 1 square = 1 Main: FOR square = 1 TO 250 STEP stepSize DEBUG DEC ? square stepSize = stepSize + 2 NEXT END ' ' ' ' show squares up to 250 display on screen add 2 to stepSize loop until square > 250 BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 197 FOR…NEXT – BASIC Stamp Command Reference Page 198 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 5: BASIC Stamp Command Reference – FREQOUT FREQOUT 1 All 2 BS1 BS2 BS2e BS2sx BS2p BS2pe BS2px (See SOUND) FREQOUT Pin, Duration, Freq1 { , Freq2 } Function Generate one or two sine-wave tones for a specified Duration. • Pin is a variable/constant/expression (0 – 15) that specifies the I/O pin to use. This pin will be set to output mode. • Duration is a variable/constant/expression (0 - 65535) specifying the amount of time to generate the tone(s). The unit of time for Duration is described in Table 5.26. • Freq1 is a variable/constant/expression (0 – 32767) specifying frequency of the first tone. The unit of Freq1 is described in Table 5.26. • Freq2 is an optional argument exactly like Freq1. When specified, two frequencies will be mixed together on the specified I/O pin. Quick Facts Table 5.26: FREQOUT Quick Facts. BS2, BS2e BS2sx BS2p BS2pe BS2px Units in 1 ms 0.4 ms 0.265 ms 1 ms 0.166 ms Duration Units in 1 Hz 2.5 Hz 3.77 Hz 1.51 Hz 6.03 Hz Freq1 and Freq2 Range of 0 to 32767 Hz 0 to 81917 Hz 0 to 123531 Hz 0 to 49478 Hz 0 to 197585 Hz Frequency Related DTMFOUT and PWM Commands Explanation FREQOUT generates one or two sine waves using a pulse-width modulation algorithm. The circuits shown in Figure 5.6 will filter the signal in order to play the tones through a speaker or audio amplifier. Here’s a simple FREQOUT command: SIMPLEST FORM OF FREQOUT. FREQOUT 2, 1000, 2500 BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 199 FREQOUT – BASIC Stamp Command Reference On the BS2, this command generates a 2500 Hz tone for 1 second (1000 ms) on I/O pin 2. See Table 5.26 for timing data on other BASIC Stamp models. To play two tones on the same I/O pin at once: FREQOUT 2, 1000, 2500, 3000 GENERATING TWO TONES AT ONCE. This will generate a 2500 Hz and 3000 Hz tone for 1 second. The frequencies will mix together for a chord- or bell-like sound. To generate a silent pause, specify frequency value(s) of 0. Driving an Audio Amplifier 1k 1k Amplifier (e.g., Radio Shack from I/O pin 0.1µF 0.01µF Vss Figure 5.6: Example RC filter circuits for driving an audio amplifier(top) or a speaker (bottom). 277-1008C) Vss Vss Driving a Speaker 10µF (both) from I/O pin + C1 + C2 ≥40Ω Speaker (or 8Ω in series with 33Ω resistor) Vss Vss Notes: C1 may be omitted for piezo speakers C2 is optional, but reduces high-frequency noise The circuits in Figure 5.6 work by filtering out the high-frequency PWM used to generate the sine waves. FREQOUT works over a very wide range of frequencies (as shown in Table 5.26) so at the upper end of its range, those PWM filters will also filter out most of the desired frequency. You may find it necessary to reduce values of the parallel capacitors shown in the circuit, or to devise a custom active filter for your application. Page 200 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com FREQUENCY CONSIDERATIONS. 5: BASIC Stamp Command Reference – FREQOUT All 2 NOTE: This example program can be used with all BS2 models. This program uses conditional compilation techniques; see Chapter 3 for more information. Demo Program (FREQOUT.bs2) ' ' ' ' FREQOUT.bs2 This program demonstrates sound-effects generation by the BASIC Stamp. Conditional compilation sets timing and frequency adjustment factors so that the output will sound the same on any BS2 model. ' {$STAMP BS2} ' {$PBASIC 2.5} Spkr PIN #SELECT $STAMP #CASE BS2, BS2E TmAdj CON FrAdj CON #CASE BS2SX TmAdj CON FrAdj CON #CASE BS2P TmAdj CON FrAdj CON #CASE BS2PE TmAdj CON FrAdj CON #CASE BS2PX TmAdj CON FrAdj CON #ENDSELECT 10 ' output pin for FREQOUT $100 $100 ' x 1.0 (time adjust) ' x 1.0 (freq adjust) $280 $066 ' x 2.5 ' x 0.4 $3C5 $044 ' x 3.77 ' x 0.265 $100 $0A9 ' x 1.0 ' x 0.662 $607 $2A ' x 6.03 ' x 0.166 Main: DEBUG "Let's make a call...", CR ' combine 350 Hz & 440 Hz FREQOUT Spkr, 2000 */ TmAdj, 350 */ FrAdj, 440 */ FrAdj ' dial number (digits 150 ms on, 25 ms off) DTMFOUT Spkr, 150 */ TmAdj, 25, [5, 5, 5, 1, 2, 1, 2] PAUSE 500 ' bad connection (SIT sequence) FREQOUT Spkr, 375 */ TmAdj, 985 */ FrAdj FREQOUT Spkr, 375 */ TmAdj, 1371 */ FrAdj FREQOUT Spkr, 375 */ TmAdj, 1777 */ FrAdj DEBUG "Oops! -- try again...", CR PAUSE 1000 DTMFOUT Spkr, 150 */ TmAdj, 25, [5, 5, 5, 2, 2, 2, 2] DEBUG "Ringing" FREQOUT Spkr, 2000 */ TmAdj, 440 */ FrAdj, 480 */ FrAdj PAUSE 4000 FREQOUT Spkr, 2000 */ TmAdj, 440 */ FrAdj, 480 */ FrAdj INPUT Spkr END BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 201 FREQOUT – BASIC Stamp Command Reference Page 202 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 5: BASIC Stamp Command Reference – GET GET BS1 BS2 BS2e BS2sx BS2p BS2pe BS2px GET Location, { WORD } Variable { , { WORD } Variable... } NOTE: The optional arguments require PBASIC 2.5. Function Read the value from Scratch Pad RAM (SPRAM) Location and store in Variable. • Location is a variable/constant/expression (0 – 63 for BS2e and BS2sx and 0 – 131 for BS2p, BS2pe, and BS2px) that specifies the SPRAM location to read from. • Variable is a variable (usually a byte, or word if using the optional WORD modifier) in which to store the value. Quick Facts Table 5.27: GET Quick Facts. BS2e and BS2sx Scratch Pad RAM 64 bytes (0 – 63). Organized as Size and bytes only. Organization General Purpose 0 - 62 Locations Special Use Location BS2p, BS2pe, and BS2px 136 bytes (0 – 135). Organized as bytes only. 0 – 126 Location 127: READ/WRITE slot and Active Program slot (read only). Locations 128-135: Polled Interrupt status (read only). PUT and STORE, PUT and SPSTR formatter. Multiple sequential variables may be read from the Scratch Pad RAM. The optional WORD modifier may be specified to retrieve 16-bit values. Location 63: Active program slot number (read only). Related Commands PBASIC 2.5 Syntax Options Explanation The GET command reads a value from the specified Scratch Pad RAM location and stores it into Variable. All values in all locations can be retrieved from within any of the 8 program slots. USES FOR SCRATCH PAD RAM. SPRAM is useful for passing data to programs in other program slots and for additional workspace. It is different than regular RAM in that symbol names cannot be assigned directly to locations and each location is always configured as a byte only. The following code will read the value at location 25, store it in a variable called temp and display it: BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 203 GET – BASIC Stamp Command Reference temp VAR Byte GET 25, temp DEBUG DEC temp ' retrieve byte from location 25 When using the PBASIC 2.5 directive, multiple sequential variables may be read from the Scratch Pad RAM, starting at Location, and the WORD modifier may be specified to retrieve 16-bit values. ' {$PBASIC 2.5} temp temp2 VAR VAR Byte Word GET 25, temp, Word temp2 ' retrieve byte from location 25 ' and word from locations 26 and 27 DEBUG DEC temp, CR DEBUG DEC temp2 The low nibble of location 63 (BS2e and BS2sx) and location 127 (BS2p, BS2pe, and BS2px) is a special, read-only location that always contains the number of the currently running program slot. On the BS2p, BS2pe, and BS2px, the high nibble of location 127 also contains the current program slot that will be used for the READ and WRITE commands. See the demo program below for an example of use. Table 5.28 shows the layout of all SPRAM registers. Page 204 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 5: BASIC Stamp Command Reference – GET Table 5.28: Layout of SPRAM Registers. Location 0...62 64..126 BS2e and BS2sx General Purpose RAM Bits 0-3: Active program slot number. n/a 127 n/a 128 n/a 129 n/a 130 n/a 131 n/a 132 n/a 133 n/a 134 n/a 135 n/a 63 NOTE: Scratch Pad RAM can only be accessed with the GET and PUT commands. Scratch Pad RAM cannot have variable names assigned to it. BS2p, BS2pe, and BS2px General Purpose RAM General Purpose RAM General Purpose RAM Bits 0-3, Active program slot #. Bits 4-7, program slot for READ and WRITE operations. Polled input trigger status of Main I/O pins 0-7 (0 = not triggered, 1 = triggered). Polled input trigger status of Main I/O pins 8-15 (0 = not triggered, 1 = triggered). Polled input trigger status of Auxiliary I/O pins 0-7 (0 = not triggered, 1 = triggered). Polled input trigger status of Auxiliary I/O pins 8-15 (0 = not triggered, 1 = triggered). Bits 0-3: Polled-interrupt mode, set by POLLMODE Bits 0-2: Polled-interrupt “run” slot, set by POLLRUN. Bit 0: Active I/O group; 0 = Main I/O, 1 = Auxiliary I/O. Bit 0: Polled-output status (set by POLLMODE); 0 = disabled, 1= enabled. Bit 1: Polled-input status; 0 = none defined, 1 = at least one defined. Bit 2: Polled-run status (set by POLLMODE); 0 = disabled, 1 = enabled. Bit 3: Polled-output latch status; 0 = real-time mode, 1 = latch mode. Bit 4: Polled-input state; 0 = no trigger, 1 = triggered. Bit 5: Polled-output latch state; 0 = nothing latched, 1 = signal latched. Bit 6: Poll-wait state; 0 = No Event, 1 = Event Occurred. (Cleared by POLLMODE only). Bit 7: Polling status; 0 = not active, 1 = active. Demo Program (GET_PUT1.bsx) NOTE: This is written for the BS2sx but can be used with the BS2e, BS2p, BS2pe and BS2px also. This program uses conditional compilation techniques; see Chapter 3 for more information. ' ' ' ' ' ' ' GET_PUT1.bsx This example demonstrates the use of the GET and PUT commands. First, slot location is read using GET to display the currently running program number. Then a set of values are written (PUT) into locations 0 TO 9. Afterwards, program number 1 is RUN. This program is a BS2SX project consisting of GET_PUT1.BSX and GET_PUT2.BSX, but will run on the BS2e, BS2p, BS2pe and BS2px without modification. ' {$STAMP BS2sx, GET_PUT2.BSX} ' {$PBASIC 2.5} BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 205 GET – BASIC Stamp Command Reference #SELECT $STAMP #CASE BS2 #ERROR "BS2e or greater required." #CASE BS2E, BS2SX Slot CON 63 #CASE BS2P, BS2PE, BS2PX Slot CON 127 #ENDSELECT value idx VAR VAR Byte Byte Setup: GET Slot, value DEBUG "Program Slot #", DEC value.NIB0, CR Main: FOR idx = 0 TO 9 value = (idx + 3) * 8 PUT idx, value DEBUG " Writing: ", DEC2 value, " to location: ", DEC2 idx, CR NEXT DEBUG CR RUN 1 END Demo Program (GET_PUT2.bsx) ' ' ' ' ' ' ' GET_PUT2.bsx This example demonstrates the use of the GET and PUT commands. First, the Slot location is read using GET to display the currently running program number. Then a set of values are read (GET) from locations 0 to 9 and displayed on the screen for verification. This program is a BS2SX project consisting of GET_PUT1.BSX and GET_PUT2.BSX, but will run on the BS2e, BS2p, BS2pe, and BS2px without modification. ' {$STAMP BS2sx} ' {$PBASIC 2.5} #SELECT $STAMP #CASE BS2 #ERROR "BS2e or greater required." #CASE BS2E, BS2SX Slot CON 63 #CASE BS2P, BS2PE, BS2PX Slot CON 127 #ENDSELECT value idx VAR VAR Byte Byte Page 206 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com NOTE: This is written for the BS2sx but can be used with the BS2e, BS2p, BS2pe and BS2px also. This program uses conditional compilation techniques; see Chapter 3 for more information. 5: BASIC Stamp Command Reference – GET Setup: GET Slot, value DEBUG "Program Slot #", DEC value.NIB0, CR Main: FOR idx = 0 TO 9 GET idx, value DEBUG " Reading: ", DEC2 value, " from location: ", DEC2 idx, CR NEXT END BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 207 GET – BASIC Stamp Command Reference Page 208 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 5: BASIC Stamp Command Reference – GOSUB GOSUB 1 All 2 BS1 BS2 BS2e BS2sx BS2p BS2pe BS2px GOSUB Address Function Store the address of the next instruction after GOSUB, then go to the point in the program specified by Address; with the intention of returning to the stored address. • Address is a label that specifies where to go. Quick Facts Table 5.29: GOSUB Quick Facts. Max. GOSUBs per program Max. nested GOSUBs Related Commands BS1 All BS2 Models 16 255 4 4 GOTO ON...GOSUB and GOTO Explanation GOSUB is a close relative of GOTO, in fact, its name means, "GO to a SUBroutine". When a PBASIC program reaches a GOSUB, the program executes the code beginning at the specified address label. Unlike GOTO, GOSUB also stores the address of the instruction immediately following itself. When the program encounters a RETURN command, it interprets it to mean, “go to the instruction that follows the most recent GOSUB.” In other words, a GOSUB makes the BASIC Stamp do a similar operation as you do when you see a table or figure reference in this manual; 1) you remember where you are, 2) you go to the table or figure and read the information there, and 3) when you've reached the end of it, you "return" to the place you were reading originally. GOSUB CAN SAVE EEPROM (PROGRAM) SPACE. GOSUB is mainly used to execute the same piece of code from multiple locations. If you have, for example, a block of three lines of code that need to be run from 10 different locations in your entire program you could simply copy and paste those three lines to each of those 10 locations. This would amount to a total of 30 lines of repetitive code (and extra space wasted in the program memory). A better solution is to place those three lines in a separate routine, complete with it's own label and followed by a BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 209 GOSUB – BASIC Stamp Command Reference RETURN command, then just use a GOSUB command at each of the 10 locations to access it. This technique can save a lot of program space. Try the example below: Main: GOSUB Hello DEBUG "How are you?" END Hello: DEBUG "Hello, my friend!", CR RETURN The above code will start out by GOSUB'ing to the section of code beginning with the label Hello. It will print "Hello, my friend!" on the screen then RETURN to the line after the GOSUB… which prints "How are you?" and ENDs. Note: colons ( : ) are placed after labels, as in “ “Main: “ and “Hello:” but the colon is not used on references to these labels such as in the “GOSUB Hello” line. There's another interesting lesson here; what would happen if we removed the END command from this example? Since the BASIC Stamp reads the code from left to right / top to bottom (like the English language) once it had returned to and run the "How are you?" line, it would naturally "fall into" the Hello routine again. Additionally, at the end of the Hello routine, it would see the RETURN again (although it didn't GOSUB to that routine this time) and because there wasn't a previous place to return to, the BASIC Stamp will start the entire program over again. This would cause an endless loop. The important thing to remember here is to always make sure your program doesn't allow itself to "fall into" a subroutine. A limited number of GOSUBs are allowed per program (as shown in Table 5.29), and they may be nested only four levels deep. In other words, the subroutine that’s the destination of a GOSUB can contain a GOSUB to another subroutine, and so on, to a maximum depth (total number of GOSUBS before the first RETURN) of four. Any deeper, and the program will "forget" its way back to the starting point (the instruction following the very first GOSUB). When GOSUBS are nested, each RETURN takes the program back to the instruction after the most-recent GOSUB. As is mentioned above, if the Page 210 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com WATCH OUT FOR SUBROUTINES THAT YOUR PROGRAM CAN "FALL INTO." 1 NOTE: On the BS1, a RETURN without a GOSUB will return the program to the last GOSUB (or will end the program if no GOSUB was executed). GOSUB LIMITATIONS. 5: BASIC Stamp Command Reference – GOSUB BASIC Stamp encounters a RETURN without a previous GOSUB, the entire program starts over from the beginning. Take care to avoid these phenomena. 1 Demo Program (GOSUB.bs1) ' ' ' ' ' ' ' ' ' ' GOSUB.bs1 This program is a guessing game that generates a random number in a subroutine called Pick_A_Number. It is written to stop after ten guesses. To see a common bug associated with GOSUB, delete or comment out the line beginning with END after the FOR-NEXT loop. This means that after the loop is finished, the program will wander into the Pick_A_Number subroutine. When the RETURN at the end executes, the program will go back to the beginning of the program. This will cause the program to execute endlessly. Make sure that your programs can't accidentally execute subroutines! ' {$STAMP BS1} ' {$PBASIC 1.0} SYMBOL SYMBOL SYMBOL rounds numGen myNum = B2 = W0 = B3 Setup: numGen = 11500 ' number of reps ' random number holder ' random number, 1-10 ' initialize random "seed" Main: FOR rounds = 1 TO 10 DEBUG CLS, "Pick a number from 1 to 10", CR GOSUB Pick_A_Number PAUSE 2000 ' dramatic pause DEBUG "My number was: ", #myNum ' show the number PAUSE 1000 ' another pause. NEXT DEBUG CLS, "Done" END ' end program ' ' ' ' Random-number subroutine. the RETURN instruction at subroutines with a GOSUB. correct address, and your A subroutine is just a piece of code with the end. Always make sure your program enters If you don't, the RETURN won't have the program will have a bug! Pick_A_Number: RANDOM numGen DEBUG numGen, CR myNum = numGen / 6550 MIN 1 RETURN ' stir up the bits of NumGen. ' scale to fit 1-10 range. ' go back to 1st instruction ' after GOSUB that got us here BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 211 GOSUB – BASIC Stamp Command Reference Demo Program (GOSUB.bs2) ' ' ' ' ' ' ' ' ' ' All GOSUB.bs2 This program is a guessing game that generates a random number in a subroutine called Pick_A_Number. It is written to stop after ten guesses. To see a common bug associated with GOSUB, delete or comment out the line beginning with END after the FOR-NEXT loop. This means that after the loop is finished, the program will wander into the Pick_A_Number subroutine. When the RETURN at the end executes, the program will go back to the beginning of the program. This will cause the program to execute endlessly. Make sure that your programs can't accidentally execute subroutines! ' {$STAMP BS2} ' {$PBASIC 2.5} rounds numGen myNum VAR VAR VAR Byte Word Byte Setup: numGen = 11500 ' initialize random "seed" Main: FOR rounds = 1 TO 10 DEBUG CLS, "Pick a number from 1 to GOSUB Pick_A_Number PAUSE 2000 DEBUG "My number was: ", DEC myNum PAUSE 1000 NEXT DEBUG CLS, "Done" END ' ' ' ' Random-number subroutine. the RETURN instruction at subroutines with a GOSUB. correct address, and your ' number of reps ' random number holder ' random number, 1-10 10", CR ' dramatic pause ' show the number ' another pause. ' end program A subroutine is just a piece of code with the end. Always make sure your program enters If you don't, the RETURN won't have the program will have a bug! Pick_A_Number: RANDOM numGen DEBUG DEC ? numGen myNum = numGen / 6550 MIN 1 RETURN ' stir up the bits of NumGen. ' scale to fit 1-10 range. ' go back to 1st instruction ' after GOSUB that got us here Page 212 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 2 NOTE: This example program can be used with all BS2 models by changing the $STAMP directive accordingly. 5: BASIC Stamp Command Reference – GOTO GOTO 1 All 2 BS1 BS2 BS2e BS2sx BS2p BS2pe BS2px GOTO Address Function Go to the point in the program specified by Address. • Address is a label that specifies where to go. Quick Facts Table 5.30: GOTO Quick Facts. Related Commands Max. GOTOs per Program BS1 All BS2 Models BRANCH and GOSUB ON...GOTO, BRANCH and GOSUB Unlimited, but good programming practices suggest using the least amount possible. Explanation The GOTO command makes the BASIC Stamp execute the code that starts at the specified Address location. The BASIC Stamp reads PBASIC code from left to right / top to bottom, just like in the English language. The GOTO command forces the BASIC Stamp to jump to another section of code. A common use for GOTO is to create endless loops; programs that repeat a group of instructions over and over. For example: Start: DEBUG "Hi", CR GOTO Start The above code will print "Hi" on the screen, over and over again. The GOTO Start line simply tells it to go back to the code that begins with the label Start. Note: colons ( : ) are placed after labels, as in “Start:” to further indicate that they are labels, but the colon is not used on references to labels such as in the “GOTO Start” line. 1 All 2 NOTE: This is written for the BS2 but can be used for the BS1 and all other BS2 models as well, by modifying the $STAMP directive accordingly. Demo Program (GOTO.bs2) ' ' ' ' ' GOTO.bs2 This program is not very practical, but demonstrates the use of GOTO to jump around the code. This code jumps between three different routines, each of which print something different on the screen. The routines are out of order for this example. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 213 GOTO – BASIC Stamp Command Reference '{$STAMP BS2} GOTO Routine1 Routine2: DEBUG "We're in routine #2",CR PAUSE 1000 GOTO Routine3 Routine1: DEBUG "We're in routine #1",CR PAUSE 1000 GOTO Routine2 Routine3: DEBUG "We're in routine #3",CR PAUSE 1000 GOTO Routine1 Page 214 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 5: BASIC Stamp Command Reference – HIGH HIGH 1 All 2 BS1 BS2 BS2e BS2sx BS2p BS2pe BS2px BS2px HIGH Pin Function 1 NOTE: Expressions are not allowed as arguments on the BS1. The range of the Pin argument on the BS1 is 0 – 7. Make the specified pin output high. • Pin is a variable/constant/expression (0 – 15) that specifies which I/O pin to set high. This pin will be placed into output mode. Quick Facts Table 5.31: HIGH Quick Facts. BS1 and all BS2 Models Related Commands LOW and TOGGLE Explanation The HIGH command sets the specified pin to 1 (a +5 volt level) and then sets its mode to output. For example, HIGH 6 does exactly the same thing as: All 2 OUT6 = 1 DIR6 = 1 Using the HIGH command is faster and more concise, in this case. Connect an LED and a resistor as shown in Figure 5.7 for demo program HIGH.bs2, below. Figure 5.7: Example LED Circuit. P0 LED 470 Ω Vss BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 215 HIGH – BASIC Stamp Command Reference Demo Program (HIGH.bs2) ' ' ' ' HIGH.bs2 This simple program sets I/O pin 0 high for 1/2 second and low for 1/2 second in an endless loop. Connect an LED to P0 for a simple blinker. ' {$STAMP BS2} Main: HIGH 0 PAUSE 500 LOW 0 PAUSE 500 GOTO Main END Page 216 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 1 All 2 NOTE: This is written for the BS2 but can be used for the BS1 and all other BS2 models as well, by modifying the $STAMP directive accordingly. 5: BASIC Stamp Command Reference – I2CIN I2CIN BS1 BS2 BS2e BS2sx BS2p BS2pe BS2px I2CIN Pin, SlaveID, { Address { \LowAddress }, } [ InputData ] Function Receive data from a device using the I2C protocol. • Pin is a variable/constant/expression (0 or 8) that specifies which I/O pins to use. I2C devices require two I/O pins to communicate. The Pin argument serves a double purpose; specifying the first pin (for connection to the chip's SDA pin) and, indirectly, the other required pin (for connection to the chip's SCL pin). See explanation below. Both I/O pins will be toggled between output and input mode during the I2CIN command and both will be set to input mode by the end of the I2CIN command. • SlaveID is a variable/constant/expression (0 – 255) indicating the unique ID of the I2C chip. • Address is an optional variable/constant/expression (0 – 255) indicating the desired address within the I2C chip to receive data from. The Address argument may be used with the optional LowAddress argument to indicate a word-sized address value. • LowAddress is an optional variable/constant/expression (0 – 255) indicating the low-byte of the word-sized address within the I2C chip to receive data from. This argument must be used along with the Address argument. • InputData is a list of variables and modifiers that tells I2CIN what to do with incoming data. I2CIN can store data in a variable or array, interpret numeric text (decimal, binary, or hex) and store the corresponding value in a variable, wait for a fixed or variable sequence of bytes, or ignore a specified number of bytes. These actions can be combined in any order in the InputData list. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 217 I2CIN – BASIC Stamp Command Reference Quick Facts Values for Pin I/O Pin Arrangement Transmission Rate Special Notes BS2p, BS2pe, and BS2px Pin = 0 Pin = 8 0: Serial Data (SDA) pin 8: Serial Data (SDA) pin 1: Serial Clock (SCL) pin 9: Serial Clock (SCL) pin Approximately 81 kbits/sec on a BS2p, 45 kbits/sec on a BS2pe, and 83 kbits/sec on a BS2px (not including overhead). Both the SDA and SCL pins must have 1 kΩ - 4.7 kΩ pull-up resistors. The I2CIN command does not allow for multiple masters. 2 The BASIC Stamp cannot operate as an I C slave device. Related Command Table 5.32: I2CIN Quick Facts. I2COUT Explanation The I2C protocol is a form of synchronous serial communication developed by Phillips Semiconductors. It only requires two I/O pins and both pins can be shared between multiple I2C devices. The I2CIN command allows the BASIC Stamp to receive data from an I2C device. The following is an example of the I2CIN command: A SIMPLE I2CIN EXAMPLE. result VAR Byte I2CIN 0, $A1, 0, [result] This code will transmit a "read" command to an I2C device (connected to I/O pins 0 and 1) and then will receive one byte and store it in the variable result. Though it may seem strange, the I2CIN command first transmits some data and then receives data. It must first transmit information (ID, read/write and address) in order to tell the I2C device what information it would like to receive. The exact information transmitted ($A1, 0) depends on the I2C device that is being used. The above example will read a byte of data from location 0 of a 24LC16B EEPROM from Microchip. Figure 5.8 shows the proper wiring for this example to work. The SlaveID argument ($A1) is both the ID of the chip and the command to read from the chip; the 1 means read. The Address argument (0) is the EEPROM location to read from. Page 218 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com NOTE: The I2C command will make up to 8 attempts to connect to the addressed device. If the device does not properly respond, the I2C command will timeout and the InputData will remain unchanged.. 5: BASIC Stamp Command Reference – I2CIN Figure 5.8: Example Circuit for the I2CIN command and a 24LC16B EEPROM. P0 SDA P1 SCL Vdd Note: The 4.7 kΩ resistors are required for the I2CIN command to function properly. 4.7 kΩ 1 2 3 4 Vss RECEIVING FORMATTED DATA. 8 7 6 5 4.7 kΩ 24LC16B (DIP) The I2CIN command's InputData argument is similar to the SERIN command's InputData argument. This means data can be received as ASCII character values, decimal, hexadecimal and binary translations and string data as in the examples below. (Assume the 24LC16B EEPROM is used and it has the string, "Value: 3A:101" stored, starting at location 0). value I2CIN I2CIN I2CIN I2CIN I2CIN VAR 0, 0, 0, 0, 0, $A1, $A1, $A1, $A1, $A1, Byte(13) 0, 0, 0, 0, 0, [value] [DEC value] [HEX value] [BIN value] [STR value\13] ' ' ' ' ' receive receive receive receive receive the the the the the ASCII value for "V" number 3 number $3A number %101 string "Value: 3A:101" Table 5.33 and Table 5.34 below list all the available special formatters and conversion formatters available to the I2CIN command. See the SERIN command for additional information and examples of their use. Table 5.33: I2CIN Special Formatters. Special Formatter SKIP Length SPSTR L STR ByteArray \L {\E} WAITSTR ByteArray {\L} Action Ignore Length bytes of characters. Input a character stream of length L bytes (up to 126) into Scratch Pad RAM, starting at location 0. Use GET to retrieve the characters. Input a character string of length L into an array. If specified, an end character E causes the string input to end before reaching length L. Remaining bytes are filled with 0s (zeros). Wait for a sequence of bytes matching a string stored in an array variable, optionally limited to L characters. If the optional L argument is left off, the end of the array-string must be marked by a byte containing a zero (0). BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 219 I2CIN – BASIC Stamp Command Reference Conversion Formatter Type of Number DEC{1..5} SDEC{1..5} Decimal, optionally limited to 1 – 5 digits Signed decimal, optionally limited to 1 – 5 digits Hexadecimal, optionally limited to 1 – 4 digits HEX{1..4} SHEX{1..4} IHEX{1..4} ISHEX{1..4} BIN{1..16} SBIN{1..16} IBIN{1..16} ISBIN{1..16} NUM 2 3 4 5 Notes 1 1,2 0 through 9, A through F -, 0 through 9, A through F $, 0 through 9, A through F -, $, 0 through 9, A through F 0, 1 -, 0, 1 1,3,5 1 1,2 %, 0, 1 1,4 -, %, 0, 1 1,2,4 $, %, 0 through 9, A through F 1, 3, 4 1,2,3 1,3,4 1,2,3,4 -, $, %, 0 through 9, 1,2,3,4 A through F All numeric conversions will continue to accept new data until receiving either the specified number of digits (ex: three digits for DEC3) or a non-numeric character. To be recognized as part of a number, the minus sign (-) must immediately precede a numeric character. The minus sign character occurring in non-numeric text is ignored and any character (including a space) between a minus and a number causes the minus to be ignored. The hexadecimal formatters are not case-sensitive; “a” through “f” means the same as “A” through “F”. Indicated hexadecimal and binary formatters ignore all characters, even valid numerics, until they receive the appropriate prefix ($ for hexadecimal, % for binary). The indicated formatters can differentiate between text and hexadecimal (ex: ABC would be interpreted by HEX as a number but IHEX would ignore it unless expressed as $ABC). Likewise, the binary version can distinguish the decimal number 10 from the binary number %10. A prefix occurring in non-numeric text is ignored, and any character (including a space) between a prefix and a number causes the prefix to be ignored. Indicated, signed formatters require that the minus sign come before the prefix, as in -$1B45. The HEX modifier can be used for Decimal to BCD Conversion. See “Hex to BCD Conversion” on page 97. SNUM 1 Signed hexadecimal, optionally limited to 1 – 4 digits Indicated hexadecimal, optionally limited to 1 – 4 digits Signed, indicated hexadecimal, optionally limited to 1 – 4 digits Binary, optionally limited to 1 – 16 digits Signed binary, optionally limited to 1 – 16 digits Indicated binary, optionally limited to 1 – 16 digits Signed, indicated binary, optionally limited to 1 – 16 digits Generic numeric input (decimal, hexadecimal or binary); hexadecimal or binary number must be indicated Numeric Characters Accepted 0 through 9 -, 0 through 9 Similar to NUM with value treated as signed with range -32768 to +32767 For examples of all conversion formatters and how they process incoming data, see Appendix C. Page 220 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com Table 5.34: I2CIN Conversion Formatters. 5: BASIC Stamp Command Reference – I2CIN 2 THE I C PROTOCOL FORMAT. Figure 5.9: Slave ID Format. The I2C protocol has a well-defined standard for the information passed at the start of each transmission. First of all, any information sent must be transmitted in units of 1 byte (8-bits). The first byte, we call the SlaveID, is an 8-bit pattern whose upper 7-bits contain the unique ID of the device you wish to communicate with. The lowest bit indicates whether this is a write operation (0) or a read operation (1). Figure 5.9 shows this format. 7 6 5 4 3 2 1 0 A6 A5 A4 A3 A2 A1 A0 R/W The second byte, immediately following the SlaveID, is the optional Address. It indicates the 8-bit address (within the device) containing the data you would like to receive. Note that the Address argument is optional and may be left unspecified for devices that don't require an Address argument. USING LONG ADDRESSES. Some devices require more than 8 bits of address. For this case, the optional LowAddress argument can be used for the low-byte of the required address. When using the LowAddress argument, the Address argument is effectively the high-byte of the address value. For example, if the entire address value is 2050, use 8 for the Address argument and 2 for the LowAddress argument (8 * 256 + 2 = 2050). Following the last address byte is the first byte of data. This data byte may be transmitted or received by the BASIC Stamp. In the case of the I2CIN command, this data byte is transmitted by the device and received by the BASIC Stamp. Additionally, multiple data bytes can follow the address, depending on the I2C device. Note that every device has different limitations regarding how may contiguous bytes they can receive or transmit in one session. Be aware of these device limitations and program accordingly. START AND STOP CONDITIONS AND ACKNOWLEDGMENTS. Every I2C transmission session begins with a Start Condition and ends with a Stop Condition. Additionally, immediately after every byte is transmitted, an extra clock cycle is used to send or receive an acknowledgment signal (ACK). All of these operations are automatically taken care of by the I2CIN command so that you need not be concerned with them. The general I2C transmission format is shown in Figure 5.10. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 221 I2CIN – BASIC Stamp Command Reference S T A R T B U S SlaveID S a6 a5 a4 a3 a2 a1 a0 rw A C K Data S F A T R C O E K P E d7 d6 d5 d4 d3 d2 d1 d0 P A C K Address a7 a6 a5 a4 a3 a2 a1 a0 2 Figure 5.10: I C Transmission Format. NOTES: S = Start Condition P = Stop Condition a = id or address bit 2 d = data bit (transmitted by the BASIC Stamp or the I C device) ACK = Acknowledge signal. (Most acknowledge signals are generated by the I2C device) Since the I2CIN command is intended for input only, it actually overrides the "R/W" bit (bit 0) in the SlaveID argument. This is done so that it can use the I2C protocol's "Combined Format" for receiving data. Put simply, this means a command such as: I2CIN 0, $A1, 10, [Result] actually transmits $A0, then 10, then $A1 and then it reads the data back from the device. The $A0 means "write", the 10 is the address to write to, and finally, the $A1 indicates a change of direction; to "read" the location, instead. Even though the I2CIN command really doesn't care what the value of the SlaveID's LSB is, it is suggested that you still set it appropriately for clarity. SPECIAL NOTE ABOUT I2CIN INPLIMENTATION. Also note that the I2CIN command does not support multiple I2C masters and the BASIC Stamp cannot operate as an I2C slave device. Demo Program (I2C.bsp) ' ' ' ' ' I2C.bsp This program demonstrates writing and reading every location in a 24LC16B EEPROM using the BS2p/BS2pe's I2C commands. Connect the BS2p, BS2pe, or BS2px to the 24LC16B DIP EEPROM as shown in the diagram in the I2CIN or I2COUT command description. ' {$STAMP BS2p} ' {$PBASIC 2.5} #IF ($STAMP < BS2P) #THEN #ERROR "Program requires BS2p, BS2pe, or BS2px." #ENDIF SDA SCL PIN PIN 0 SDA + 1 ' I2C SDA pin Page 222 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com NOTE: This example program can be used with the BS2p, BS2pe, and BS2px. This program uses conditional compilation techniques; see Chapter 3 for more information. 5: BASIC Stamp Command Reference – I2CIN addr block value check result VAR VAR VAR VAR VAR Word Nib Byte Nib Byte(16) ' ' ' ' ' internal address block address in 24LC16 value to write for checking retuned values array for returned value Write_To_EEPROM: DEBUG "Writing...", CR PAUSE 2000 FOR addr = 0 TO 2047 STEP 16 ' loop through all addresses block = addr.NIB2 < >= 4000) THEN DEBUG "Value was greater than 4000" ELSEIF (value = 4000) THEN DEBUG "Value was equal to 4000" ELSE DEBUG "Value was less than 4000" ENDIF ' evaluate duration This IF…THEN construct does the same thing as in the previous example: 1) if value is greater than 4000: it displays “Value was greater than 4000” 2) else, if value is equal to 4000 (the ELSEIF part): it displays “Value was equal to 4000” 3) and finally (ELSE) if none of the above were true: it displays “Value was less than 4000” BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 239 IF…THEN – BASIC Stamp Command Reference Note that an IF…THEN construct can have as many as sixteen (16) ELSEIF clauses, but a maximum of only one (1) ELSE clause. There are three demo programs below. The first two demonstrate the PBASIC 1.0 (BS1) and PBASIC 2.0 (all BS2 models) form of the IF…THEN command. The last example demonstrates the PBASIC 2.5 (all BS2 models) form of IF…THEN. Demo Program (IF-THEN.bs1) ' ' ' ' ' ' 1 IF-THEN.bs1 The program below generates a series of 16-bit random numbers and tests each to determine whether they're evenly divisible by 3. If a number is evenly divisible by 3, then it is printed, otherwise, the program generates another random number. The program counts how many numbers it prints, and quits when this number reaches 10. ' {$STAMP BS1} ' {$PBASIC 1.0} SYMBOL SYMBOL SYMBOL sample samps temp = W0 = B2 = B3 ' Random number to be tested ' Number of samples taken ' Temporary workspace Setup: sample = 11500 Mult3: RANDOM sample temp = sample // 3 IF temp 0 THEN Mult3 DEBUG #sample, "divides by 3", CR samps = samps + 1 IF samps = 10 THEN Done GOTO Mult3 ' Put a random number into sample ' ' ' ' ' Not multiple of 3? -- try again show sample divisible by 3 Count multiples of 3 Quit with 10 samples keep checking Done: DEBUG CR, "All done." END Demo Program (IF-THEN.bs2) ' ' ' ' ' ' IF-THEN.bs2 The program below generates a series of 16-bit random numbers and tests each to determine whether they're evenly divisible by 3. If a number is evenly divisible by 3, then it is printed, otherwise, the program generates another random number. The program counts how many numbers it prints, and quits when this number reaches 10. Page 240 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com All 2 NOTE: This example program can be used with all BS2 models by changing the $STAMP directive accordingly. 5: BASIC Stamp Command Reference – IF...THEN ' {$STAMP BS2} ' {$PBASIC 2.0} sample samps temp VAR VAR VAR Word Nib Nib ' Random number to be tested ' Number of samples taken ' Temporary workspace Setup: sample = 11500 Mult3: RANDOM sample ' Put a random number into sample temp = sample // 3 IF temp 0 THEN Mult3 ' Not multiple of 3? -- try again DEBUG DEC5 sample, " divides by 3", CR samps = samps + 1 ' Count multiples of 3 IF samps = 10 THEN Done ' Quit with 10 samples GOTO Mult3 ' keep checking Done: DEBUG CR, "All done." END All 2 NOTE: This example program can be used with all BS2 models by changing the $STAMP directive accordingly. Demo Program (IF-THEN-ELSE.bs2) ' ' ' ' ' ' IF-THEN-ELSE.bs2 The program below generates a series of 16-bit random numbers and tests each to determine whether they're evenly divisible by 3. If a number is evenly divisible by 3, then it is printed, otherwise, the program generates another random number. The program counts how many numbers it prints, and quits when this number reaches 10. ' {$STAMP BS2} ' {$PBASIC 2.5} sample hits misses ' version 2.5 required VAR VAR VAR Word Nib Word ' Random number to be tested ' Number of hits ' Number of misses Setup: sample = 11500 Main: DO RANDOM sample IF ((sample // 3) = 0) THEN DEBUG DEC5 sample, " is divisible by 3", CR ' Put a random number into sample ' divisible by 3? ' - yes, print value and message BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 241 IF…THEN – BASIC Stamp Command Reference hits = hits + 1 ELSE misses = misses + 1 ENDIF LOOP UNTIL (hits = 10) DEBUG CR, "All done.", "Hits: ", "Misses: ", "Samples: ", END CR, DEC DEC DEC ' count hits (divisible by 3) ' count misses ' quit after 10 hits CR, ' display results hits, CR, misses, CR, (hits + misses) Page 242 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 5: BASIC Stamp Command Reference – INPUT INPUT 1 All 2 1 NOTE: Expressions are not allowed as arguments on the BS1. The range of the PIN argument on the BS1 is 0 – 7. BS1 BS2 BS2e BS2sx BS2p BS2pe BS2px INPUT Pin Function Make the specified pin an input. • Pin is a variable/constant/expression (0 – 15) that specifies which I/O pin to set to input mode. Quick Facts Table 5.41: INPUT Quick Facts. Input Pin Variables Related Commands BS1 All BS2 Models PINS; PIN0 through PIN7 INS; IN0 through IN15 OUTPUT and REVERSE Explanation There are several ways to make a pin an input. When a program begins, all of the BASIC Stamp's pins are inputs. Commands that rely on input pins, like PULSIN and SERIN, automatically change the specified pin to input. Writing 0s to particular bits of the variable DIRS makes the corresponding pins inputs. And then there’s the INPUT command. When a pin is an input, your program can check its state by reading the corresponding INS variable (PINS on the BS1). For example: All 2 INPUT 4 Hold: IF IN4 = 0 THEN Hold ' stay here until P4 = 1 The code above will read the state of P4 as set by external circuitry. If nothing is connected to P4, it will alternate between states (1 or 0) apparently at random. What happens if your program writes to the OUTS bit (PINS bit on the BS1) of a pin that is set up as an input? The value is stored in OUTS (PINS on the BS1), but has no effect on the outside world. If the pin is changed to output, the last value written to the corresponding OUTS bit (or PINS bit BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 243 INPUT – BASIC Stamp Command Reference on the BS1) will appear on the pin. The demo program shows how this works. Demo Program (INPUT.bs1) ' ' ' ' ' ' ' ' ' ' 1 INPUT.bs1 This program demonstrates how the input/output direction of a pin is determined by the corresponding bit of DIRS. It also shows that the state of the pin itself (as reflected by the corresponding bit of PINS) is determined by the outside world when the pin is an input, and by the corresponding bit of OUTS when it's an output. To set up the demo, connect a 10k resistor from +5V to P7 on the BASIC Stamp. The resistor to +5V puts a high (1) on the pin when it's an input. The BASIC Stamp can override this state by writing a low (0) to bit 7 of OUTS and changing the pin to output. ' {$STAMP BS1} ' {$PBASIC 1.0} Main: INPUT 7 DEBUG "State of P7: ", #PIN7, CR ' Make P7 an input PIN7 = 0 DEBUG "After 0 written to OUT7: " DEBUG #PIN7, CR ' Write 0 to output latch OUTPUT 7 DEBUG "After P7 changed to output: " DEBUG #PIN7 ' Make P7 an output Demo Program (INPUT.bs2) ' ' ' ' ' ' ' ' ' ' All INPUT.bs2 This program demonstrates how the input/output direction of a pin is determined by the corresponding bit of DIRS. It also shows that the state of the pin itself (as reflected by the corresponding bit of INS) is determined by the outside world when the pin is an input, and by the corresponding bit of OUTS when it's an output. To set up the demo, connect a 10k resistor from +5V to P7 on the BASIC Stamp. The resistor to +5V puts a high (1) on the pin when it's an input. The BASIC Stamp can override this state by writing a low (0) to bit 7 of OUTS and changing the pin to output. ' {$STAMP BS2} ' {$PBASIC 2.5} Main: INPUT 7 DEBUG "State of P7: ", ' Make P7 an input Page 244 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 2 NOTE: This example program can be used with all BS2 models by changing the $STAMP directive accordingly. 5: BASIC Stamp Command Reference – INPUT BIN1 IN7, CR OUT7 = 0 DEBUG "After 0 written to OUT7: ", BIN1 IN7, CR ' Write 0 to output latch OUTPUT 7 ' Make P7 an output DEBUG "After P7 changed to output: ", BIN1 IN7 BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 245 INPUT – BASIC Stamp Command Reference Page 246 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 5: BASIC Stamp Command Reference – IOTERM IOTERM BS1 BS2 BS2e BS2sx BS2p BS2pe BS2px IOTERM Port Function Switch control to main I/O pins or auxiliary I/O pins (on the BS2p40 only) depending on state of Port. • Port is a variable/constant/expression (0 – 1) that specifies which I/O port to use. Quick Facts Table 5.42: IOTERM Quick Facts. Values for Port I/O pin IDs Special Notes Related Commands BS2p, BS2pe, and BS2px 0 = switch to main I/O group, 1 = switch to auxiliary I/O group. 0 – 15 (after IOTERM command, all references affect physical pins 5 – 20 or 21 – 36 depending on state of Port). Both the BS2p and BS2pe 24-pin modules accept this command, however, only the BS2p40 gives access to the auxiliary I/O pins. AUXIO and MAINIO Explanation The BS2p, BS2pe and BS2px are available as 24-pin modules that are pin compatible with the BS2, BS2e and BS2sx. Also available is a 40-pin module called the BS2p40, with an additional 16 I/O pins (for a total of 32). The BS2p40's I/O pins are organized into two groups, called main and auxiliary. The I/O pins in each group can be accessed in the same manner (by referencing I/O pins 0 – 15) but access is only possible within one group at a time. The IOTERM command causes the BASIC Stamp to affect either the main or auxiliary I/O pins in all further code until the MAINIO, AUXIO or another IOTERM command is reached, or the BASIC Stamp is reset or power-cycled. The value of Port determines which group of I/O pins will be referenced. Using 0 for Port will switch to the main I/O group and using 1 for Port will switch to the auxiliary group. A SIMPLE IOTERM EXAMPLE. The following example illustrates this: HIGH 0 IOTERM 1 LOW 0 ' make P0 high ' Port = 1, so switch to auxiliary pins ' make X0 low The first line of the above example will set I/O pin 0 of the main I/O pins (physical pin 5) high. Afterward, the IOTERM command tells the BASIC BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 247 IOTERM – BASIC Stamp Command Reference Stamp that all commands following it should affect the auxiliary I/O pins (Port = 1). The following LOW command will set I/O pin 0 of the auxiliary I/O pins (physical pin 21) low. Note that the main I/O and auxiliary I/O pins are independent of each other; the states of the main I/O pins remain unchanged while the program affects the auxiliary I/O pins, and vice versa. MAIN I/O AND AUXILIARY I/O PINS ARE INDEPENDENT AND UNAFFECTED BY CHANGES IN THE OPPOSITE GROUP. Other commands that affect I/O group access are AUXIO and MAINIO. 2 Demo Program (AUX_MAIN_TERM.bsp) p ' AUX_MAIN_TERM.bsp ' This program demonstrates the use of the AUXIO, MAINIO and IOTERM ' commands to affect I/O pins in the auxiliary and main I/O groups. ' {$STAMP BS2p} ' {$PBASIC 2.5} #SELECT $STAMP #CASE BS2, BS2E, BS2SX #ERROR "Program requires BS2p40" #CASE BS2P, BS2PE, BS2PX DEBUG "Note: This program designed for the BS2p40.", CR #ENDSELECT port VAR Main: DO MAINIO TOGGLE 0 PWM 1, 100, 40 Bit ' Switch to main I/O pins ' Toggle state of I/O pin P0 ' Generate PWM on I/O pin P1 AUXIO TOGGLE 0 PULSOUT 1, 1000 PWM 2, 100, 40 ' ' ' ' Switch to auxiliary Toggle state of I/O Generate a pulse on Generate PWM on I/O IOTERM port ' ' ' ' ' ' Switch to main or aux I/Os -- depending on port Toggle state of I/O pin 3 -- on main and aux, alternately Invert port 1 second delay TOGGLE 3 port = ~port PAUSE 1000 LOOP END Page 248 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com I/O pin I/O pin pins X0 pin X1 X2 NOTE: This example program will tokenize with the 24-pin BS2p, BS2pe, and BS2px but its effects can only be seen on the BS2p40. This program uses conditional compilation techniques; see Chapter 3 for more information. 5: BASIC Stamp Command Reference – LCDCMD LCDCMD BS1 BS2 BS2e BS2sx BS2p BS2pe BS2px LCDCMD Pin, Command Function Send a command to an LCD display. • Pin is a variable/constant/expression (0 – 1 or 8 – 9) that specifies which I/O pins to use. The LCD requires, at most, seven I/O pins to operate. Note that LCDCMD, LCDIN and LCDOUT use a 4-bit interface to the LCD which requires a specific initialization sequence before LCDIN and LCDOUT can be used. Specifics on the initialization sequence will follow. The Pin argument serves a double purpose; specifying the first pin and, indirectly, the group of other required pins. See explanation below. All I/O pins will be set to output mode. • Command is a variable/constant/expression (0 – 255) indicating the LCD command to send. Quick Facts Table 5.43: LCDCMD Quick Facts. Values for Pin I/O Pin Arrangement when Pin is 0 or 1 I/O Pin Arrangement when Pin is 8 or 9 Special Notes Related Commands BS2p, BS2pe, and BS2px 0, 1, 8 or 9 0 or 1 (depending on pin): LCD Enable (E) pin 2: LCD Read/Write (R/W) pin 3: LCD Register Select (RS) pin 4 – 7: LCD Data Buss (DB4 – DB7, respectively) pins 8 or 9 (depending on pin): LCD Enable (E) pin 10: LCD Read/Write (R/W) pin 11: LCD Register Select (RS) pin 12 – 15: LCD Data Buss (DB4 – DB7, respectively) pins LCDCMD is designed to use the LCD's 4-bit mode only. LCDIN and LCDOUT Explanation NOTE: LCDCMD, LCDIN and LCDOUT use a 4-bit interface to the LCD which requires a specific initialization sequence before LCDIN and LCDOUT can be used; read more below. The three LCD commands (LCDCMD, LCDIN and LCDOUT) allow the BS2p, BS2pe, and BS2px to interface directly to standard LCD displays that feature a Hitachi 44780 controller (part #HD44780A). This includes many 1 x 16, 2 x 16 and 4 x 20 character LCD displays. The Hitachi 44780 LCD controller supports a number of special instructions for initializing the display, moving the cursor, changing the default layout, etc. The LCDCMD command is used to send one of these BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 249 LCDCMD – BASIC Stamp Command Reference instructions to the LCD. It is most commonly used to initialize the display upon a power-up or reset condition. The following is an example of the LCDCMD command: A SIMPLE LCDCMD EXAMPLE. LCDOUT 0, 24 The above code will send the Scroll Left command (represented by the number 24) to the LCD whose enable pin is connected to I/O pin 0. This will cause the LCD display to scroll, or shift, the entire display one character to the left. You may have noticed that the Pin argument in the example above was 0. The LCDCMD command actually uses more than just this I/O pin, however. The LCDCMD command requires seven I/O pins. This is because the standard LCD displays have a parallel interface, rather than a serial one. The Pin argument can be the numbers 0, 1, 8 or 9 and will result in the use of the I/O pins shown in Table 5.43. Figure 5.14 shows the required wiring for the above command to work. WIRING THE BASIC STAMP TO AN LCD. Figure 5.14: Example LCD Circuit. Shown with all connections necessary for the LCDCMD, LCDIN and LCDOUT commands. Page 250 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 5: BASIC Stamp Command Reference – LCDCMD Note that we could have used 1 for the Pin argument and moved the LCD's Enable pin (pin 6) to I/O pin 1. Similarly, using 9 for the Pin argument would have required us to wire the LCD's pins to I/O pins 9 through 15, rather than I/O pins 0 and 2 through 7. INITIALIZING THE LCD; THE MOST IMPORTANT STEP! When the LCD is first powered-up, it defaults to an 8-bit interface and must be configured for a 4-bit buss before sending commands like the one shown above. This process is known as initializing the LCD and is the first thing your program should do upon starting up. The following code is a good example of LCD initialization. Init_LCD: PAUSE 1000 LCDCMD 0, %00110000 PAUSE 5 LCDCMD 0, %00110000 PAUSE 0 LCDCMD 0, %00110000 PAUSE 0 LCDCMD 0, %00100000 LCDCMD 0, %00101000 LCDCMD 0, %00001100 LCDCMD 0, %00000110 ' allow LCD to self-initialize first ' send wakeup sequence to LCD ' pause required by LCD specs ' pause required by LCD specs ' ' ' ' ' pause required by LCD specs set data bus to 4-bit mode set to 2-line mode with 5x8 font display on without cursor auto-increment cursor This initialization code is the most commonly used sequence for a 2 x 16 and 4 x 20 LCD display (the 2-line mode instruction sets the 4 x 20 to 4-line mode). The PAUSE 1000 command is optional, but only if your program takes more than approximately 700 ms before it executes the InitLCD code above. Without it, upon powering your circuit, the BASIC Stamp may talk to the LCD too early, the LCD will then miss some of the commands and the display will operate strangely, or not at all. Do not change the "wake-up" and "4-bit mode" sequence commands. However, the commands below the line that says, "Set data bus to 4-bit mode" may be modified to set other desired modes. COMMON LCD COMMANDS. Table 5.44 shows the most commonly used LCD commands. Here's an example: LCDCMD 0, 16 This will make the LCD's cursor move left by one character (16 is the Cursor Left command), even if the cursor is not visible. The next character BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 251 LCDCMD – BASIC Stamp Command Reference printed on the display (with the LCDOUT command) will appear at the current cursor's location. Here's another example: LCDCMD 0, 128 + 64 The above command will move the cursor to the first character position on the second line (on a 2 x 16 display). 128 is the Move To Display Address command and 64 is the location number. See the "Character Positioning" section, below, for more information. Do Nothing Clear Display Home Display Inc Cursor Display Off Display On Blinking Cursor Underline Cursor Cursor Left Cursor Right Scroll Left Scroll Right Move To CGRAM Address Move To DDRAM Address Command (in decimal) 0 1 2 6 8 12 13 14 16 20 24 28 Description Don't perform any special operation. Clear the display and move cursor to home position. Move cursor and display to home position. Set cursor direction to right, without a display shift. Turn off display (display data is retained). Turn on display without cursor (display is restored). Turn on display with blinking cursor. Turn on display with underline cursor. Move cursor left one character. Move cursor right one character. Scroll display left one character. Scroll display right one character. 64 + address Move pointer to character RAM location. 128 + address Move cursor to Display Data RAM location. Table 5.44: Common LCD Commands. These are supported by LCDs with the Hitachi 44780 controller. While most users will only need the commands shown in Table 5.44 above, Table 5.45 below details all of the instructions supported by the LCD (for advanced users). Many instructions are multipurpose, depending on the state of special bits. Clever manipulation of the instruction bits will allow for powerful control of the LCD. A NOTE ABOUT ADVANCED LCD COMMANDS. The last command shown above (Move To DDRAM Address) is used to move the cursor to a specific position on the LCD. The LCD's DDRAM (Display Data RAM) is a fixed size with a unique position number for each character cell. The viewable portion of the DDRAM depends on the LCD's logical view position (which can be altered with the Scroll Display command). The default view position is called the Home position; it means that the display's upper left character corresponds to DDRAM CHARACTER POSITIONING: MOVING THE CURSOR. Page 252 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 5: BASIC Stamp Command Reference – LCDCMD location 0. Figure 5.15 indicates the position numbers for characters on the LCD screen. Table 5.45: All LCD Commands (for advanced users). These are supported by LCDs with the Hitachi 44780 controller. Command Code (in binary) 6 5 4 3 2 1 7 Description 0 Clear Display 0 0 0 0 0 0 0 1 Home Display 0 0 0 0 0 0 1 0 Entry Mode 0 0 0 0 0 1 M S Display/Cursor 0 0 0 0 1 D U B Scroll Display / Shift Cursor 0 0 0 1 C M 0 0 Function Set 0 0 1 B L F 0 0 1 A A A A A A A A A A A A A Move To CGRAM 0 Address Move To DDRAM 1 Address Clear entire display and move cursor home (address 0). Move cursor home and return display to home position. Sets cursor direction (M: 0=left, 1=right) and display scrolling (S: 0=no scroll, 1=scroll) Sets display on/off (D), underline cursor (U) and blinking block cursor (B). (0=off, 1=on) Shifts display or cursor (C: 0=cursor, 1=display) left or right (M: 0=left, 1=right). Sets buss size (B: 0=4-bits, 1=8-bits), number of lines (L: 0=1-line, 1=2-lines) and font size (F: 0=5x8, 1=5x10) Move pointer to character RAM location specified by address (A) Move cursor to display RAM location specified by address (A) Note that Figure 5.15 shows the most common DDRAM mapping, though some LCD's may have organized the DDRAM differently. A little experimentation with your LCD may reveal this. 2 x 16 Display Figure 5.15: LCD Character Positions. NOTE: Many 1 x 16 displays conform to the position numbers shown on Line 1 of the 2 x 16 display. On-screen positions* Line 1: 0 1 2 3 4 5 6 7 8 Off-screen positions* 9 10 11 12 13 14 15 16 … 39 Line 2: 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 … 103 4 x 20 Display Line 1: 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 Line 2: 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 Line 3: 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 Line 4: 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100101 102103 *Assuming the display is in the home position. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 253 LCDCMD – BASIC Stamp Command Reference On a standard 2 x 16 character display, the following command would move the cursor to the third column of the second line: LCDCMD 0, 128 + 66 The number 128 tells the LCD we wish to move the cursor and 66 is the location number of the desired position. Similarly, sending just 128 (128 + 0) would move the cursor to the first character of the first line (the upper left character if the display is at the home position). You may have noticed that the 2 x 16 display has many locations that are not visible; they are beyond the right edge of the screen. These locations (16 – 39 and 80 to 103) become important for scrolling operations. For example, it is possible to move the cursor to location 16, print some text there and then issue a number of Scroll Left instructions (LCDCMD 0, 24) to slowly scroll the text onto the display from right to left. If you did so, the DDRAM positions that were on the left of the screen would now be past the left edge of the screen. For example, SCROLLING THE DISPLAY. LCDCMD 0, 24 LCDCMD 0, 24 would cause the screen to scroll to the left by two characters. At this point, the upper-left character in the display would actually be DDRAM location 2 and the lower-left character would be DDRAM location 66. Locations 0, 1, 64 and 65 would be off the left edge of the LCD and would no longer be visible. Some interesting effects can be achieved by taking advantage of this feature. The 4 x 20 LCD has a strange DDRAM map. The upper-right character is location 19 and the next location, 20, appears as the first character of the third line. This strange mapping is due to constraints in the LCD controller and the manufacturers design, and unfortunately makes the scrolling features virtually useless on the 4 x 20 displays. NOTES ON DDRAM MAPPING FOR 4 X 20 LCDS. Even though the LCD requires many pins to talk to it, only the Enable pin needs to remain dedicated to the LCD and all the other pins can be multiplexed (shared) with certain other devices (if wired carefully). In addition, the I/O pin connected to the LCD's R/W pin is only necessary if the LCDIN command will be used in the application. If the LCDIN command will not be used, LCD pin 5 (R/W pin) can be connected to DETAILS ON LCD WIRING. Page 254 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 5: BASIC Stamp Command Reference – LCDCMD ground, the 4 resistors on LCD pins 7-10 may be removed (connecting pins 7-10 directly to ground). Note that even though this change will leave BASIC Stamp I/O pin 2 disconnected, it will still be set to output mode for each LCDCMD and LCDOUT command executed. Demo Program (LCDINIT.bsp) NOTE: This example program can be used with the BS2p, BS2pe, and BS2px by changing the $STAMP directive accordingly. ' ' ' ' ' LCDINIT.bsp This program demonstrates initialization and printing on a 2 x 16 character LCD display. The set of "LCD constants", below, are provided as pre-defined and useful LCD commands, though not all are actually used in this program. ' {$STAMP BS2p} ' {$PBASIC 2.5} #IF ($STAMP < BS2P) #THEN #ERROR "Program requires BS2p, BS2pe or BS2px." #ENDIF Lcd PIN 0 LcdCls LcdHome LcdCrsrL LcdCrsrR LcdDispL LcdDispR LcdDDRam LcdCGRam LcdLine1 LcdLine2 CON CON CON CON CON CON CON CON CON CON $01 $02 $10 $14 $18 $1C $80 $40 $80 $C0 Init_LCD: PAUSE 1000 LCDCMD Lcd, PAUSE 5 LCDCMD Lcd, PAUSE 0 LCDCMD Lcd, PAUSE 0 LCDCMD Lcd, LCDCMD Lcd, LCDCMD Lcd, LCDCMD Lcd, %00110000 ' ' ' ' ' ' ' ' ' ' clear the LCD move cursor home move cursor left move cursor right shift chars left shift chars right Display Data RAM Character Generator RAM DDRAM address of line 1 DDRAM address of line 2 ' allow LCD to self-initialize first ' send wakeup sequence to LCD ' pause required by LCD specs %00110000 ' pause required by LCD specs %00110000 %00100000 %00101000 %00001100 %00000110 ' ' ' ' ' pause required by LCD specs set data bus to 4-bit mode set to 2-line mode with 5x8 font display on without cursor auto-increment cursor Main: DO LCDOUT Lcd, LcdCls, ["Hello, World!"] LCDOUT Lcd, LcdLine2, ["How are you?"] BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 255 LCDCMD – BASIC Stamp Command Reference PAUSE 3000 LCDCMD Lcd, LcdCls PAUSE 500 LOOP END Page 256 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 5: BASIC Stamp Command Reference – LCDIN LCDIN BS1 BS2 BS2e BS2sx BS2p BS2pe BS2px LCDIN Pin, Command, [ InputData ] Function Receive data from an LCD display. • Pin is a variable/constant/expression (0 – 1 or 8 – 9) that specifies which I/O pins to use. The LCD requires, at most, seven I/O pins to operate. The Pin argument serves a double purpose; specifying the first pin and, indirectly, the group of other required pins. See explanation below. All I/O pins will be set to output mode initially and the upper I/O pins (4 – 7 or 12 – 15) will be set to input mode by the end of the LCDIN command. • Command is a variable/constant/expression (0 – 255) indicating the LCD command to send. • InputData is a list of variables and formatters that tells LCDIN what to do with incoming data. LCDIN can store data in a variable or array, interpret numeric text (decimal, binary, or hex) and store the corresponding value in a variable, wait for a fixed or variable sequence of bytes, or ignore a specified number of bytes. These actions can be combined in any order in the InputData list. Quick Facts Table 5.46: LCDIN Quick Facts. Values for Pin I/O Pin Arrangement when Pin is 0 or 1 I/O Pin Arrangement when Pin is 8 or 9 Special Notes Related Commands BS2p, BS2pe, and BS2px 0, 1, 8 or 9 0 or 1 (depending on pin): LCD Enable (E) pin 2: LCD Read/Write (R/W) pin 3: LCD Register Select (RS) pin 4 – 7: LCD Data Buss (DB4 – DB7, respectively) pins 8 or 9 (depending on pin): LCD Enable (E) pin 10: LCD Read/Write (R/W) pin 11: LCD Register Select (RS) pin 12 – 15: LCD Data Buss (DB4 – DB7, respectively) pins LCDIN is designed to use the LCD's 4-bit mode only. LCDCMD and LCDOUT BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 257 LCDIN – BASIC Stamp Command Reference Explanation The three LCD commands (LCDCMD, LCDIN and LCDOUT) allow the BS2p, BS2pe, and BS2px to interface directly to standard LCD displays that feature a Hitachi 44780 controller (part #HD44780A). This includes many 1 x 16, 2 x 16 and 4 x 20 character LCD displays. NOTE: LCDCMD, LCDIN and LCDOUT use a 4-bit interface to the LCD which requires a specific initialization sequence before LCDIN and LCDOUT can be used; read more below. The LCDIN command is used to send one instruction and then receive at least one data byte from the LCD's Character Generator RAM or Display Data RAM. The following is an example of the LCDIN command: A SIMPLE LCDIN EXAMPLE. char LCDIN VAR Byte 0, 128, [char] The above code will read the character value at location 0 of the DDRAM. See the "Character Positioning" section, of the LCDCMD command description on page 252 for more information. The LCDIN command actually uses more than just the I/O pin specified by the Pin argument. The LCDIN command requires seven I/O pins. This is because the standard LCD displays have a parallel interface, rather than a serial one. The Pin argument can be the numbers 0, 1, 8 or 9 and will result in the use of the I/O pins shown in Table 5.46. Please refer to the LCDCMD command description for information on page properly wiring the LCD display. TWO VERY IMPORTANT STEPS: 1) WIRING THE BASIC STAMP TO AN LCD. 2) INITIALIZING THE LCD. When the LCD is first powered-up, it defaults to an 8-bit interface and must be properly configured for a 4-bit buss before sending commands like the one shown above. This process is known as initializing the LCD and is the first thing your program should do upon starting up. Please refer to the LCDCMD command description for information on properly initializing the LCD display. The LCDIN command's InputData argument is similar to the SERIN command's InputData argument. This means data can be received as ASCII character values, decimal, hexadecimal and binary translations and string data as in the examples below (assume the LCD display has "Value: 3A:101" starting at the first character of the first line on the screen). Page 258 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com RECEIVING FORMATTED DATA. 5: BASIC Stamp Command Reference – LCDIN value LCDIN LCDIN LCDIN LCDIN LCDIN 0, 0, 0, 0, 0, VAR 128, 128, 128, 128, 128, Byte(13) [value] [DEC value] [HEX value] [BIN value] [STR value\13] 'receive 'receive 'receive 'receive 'receive the the the the the ASCII value for "V" number 3. number $3A. number %101. string "Value: 3A:101" Table 5.47 and Table 5.48 list all the special formatters and conversion formatters available to the LCDIN command. See the SERIN command for additional information and examples of their use. Some possible uses of the LCDIN command are 1) in combination with the LCDOUT command to store and read data from the unused DDRAM or CGRAM locations (as extra variable space), 2) to verify that the data from a previous LCDOUT command was received and processed properly by the LCD, and 3) to read character data from CGRAM for the purposes of modifying it and storing it as a custom character. Table 5.47: LCDIN Special Formatters. Special Formatter SPSTR L STR ByteArray \L {\E} WAIT (Value) WAITSTR ByteArray {\L} SKIP Length Action Input a character string of length L bytes (up to 126) into Scratch Pad RAM, starting at location 0. Use GET to retrieve the characters. Input a character string of length L into an array. If specified, an end character E causes the string input to end before reaching length L. Remaining bytes are filled with 0s (zeros). Wait for a sequence of bytes specified by value. Value can be numbers separated by commas or quoted text (ex: 65, 66, 67 or “ABC”). The WAIT formatter is limited to a maximum of six characters. Wait for a sequence of bytes matching a string stored in an array variable, optionally limited to L characters. If the optional L argument is left off, the end of the array-string must be marked by a byte containing a zero (0). Ignore Length bytes of characters. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 259 LCDIN – BASIC Stamp Command Reference Conversion Formatter Type of Number DEC{1..5} SDEC{1..5} Decimal, optionally limited to 1 – 5 digits Signed decimal, optionally limited to 1 – 5 digits Hexadecimal, optionally limited to 1 – 4 digits HEX{1..4} SHEX{1..4} IHEX{1..4} ISHEX{1..4} BIN{1..16} SBIN{1..16} IBIN{1..16} ISBIN{1..16} NUM 2 3 4 5 Notes 1 1,2 0 through 9, A through F -, 0 through 9, A through F $, 0 through 9, A through F -, $, 0 through 9, A through F 0, 1 -, 0, 1 1,3,5 1 1,2 %, 0, 1 1,4 -, %, 0, 1 1,2,4 $, %, 0 through 9, A through F 1, 3, 4 1,2,3 1,3,4 1,2,3,4 -, $, %, 0 through 9, 1,2,3,4 A through F All numeric conversions will continue to accept new data until receiving either the specified number of digits (ex: three digits for DEC3) or a non-numeric character. To be recognized as part of a number, the minus sign (-) must immediately precede a numeric character. The minus sign character occurring in non-numeric text is ignored and any character (including a space) between a minus and a number causes the minus to be ignored. The hexadecimal formatters are not case-sensitive; “a” through “f” means the same as “A” through “F”. Indicated hexadecimal and binary formatters ignore all characters, even valid numerics, until they receive the appropriate prefix ($ for hexadecimal, % for binary). The indicated formatters can differentiate between text and hexadecimal (ex: ABC would be interpreted by HEX as a number but IHEX would ignore it unless expressed as $ABC). Likewise, the binary version can distinguish the decimal number 10 from the binary number %10. A prefix occurring in non-numeric text is ignored, and any character (including a space) between a prefix and a number causes the prefix to be ignored. Indicated, signed formatters require that the minus sign come before the prefix, as in -$1B45. The HEX modifier can be used for Decimal to BCD Conversion. See “Hex to BCD Conversion” on page 97. SNUM 1 Signed hexadecimal, optionally limited to 1 – 4 digits Indicated hexadecimal, optionally limited to 1 – 4 digits Signed, indicated hexadecimal, optionally limited to 1 – 4 digits Binary, optionally limited to 1 – 16 digits Signed binary, optionally limited to 1 – 16 digits Indicated binary, optionally limited to 1 – 16 digits Signed, indicated binary, optionally limited to 1 – 16 digits Generic numeric input (decimal, hexadecimal or binary); hexadecimal or binary number must be indicated Numeric Characters Accepted 0 through 9 -, 0 through 9 Similar to NUM with value treated as signed with range -32768 to +32767 For examples of all conversion formatters and how they process incoming data see Appendix C. Page 260 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com Table 5.48: LCDIN Conversion Formatters 5: BASIC Stamp Command Reference – LCDIN Demo Program (LCDIN.bsp) NOTE: This example program can be used with the BS2p, BS2pe, and BS2px. This program uses conditional compilation techniques; see Chapter 3 for more information. ' LCDIN.bsp ' This program demonstrates initialization, printing and reading ' from a 2 x 16 character LCD display. ' {$STAMP BS2p} ' {$PBASIC 2.5} #IF ($STAMP < BS2P) #THEN #ERROR "Program requires BS2p, BS2pe or BS2px." #ENDIF Lcd PIN 0 LcdCls LcdHome LcdCrsrL LcdCrsrR LcdDispL LcdDispR LcdDDRam LcdCGRam LcdLine1 LcdLine2 CON CON CON CON CON CON CON CON CON CON $01 $02 $10 $14 $18 $1C $80 $40 $80 $C0 char VAR Byte(16) Init_LCD: PAUSE 1000 LCDCMD Lcd, PAUSE 5 LCDCMD Lcd, PAUSE 0 LCDCMD Lcd, PAUSE 0 LCDCMD Lcd, LCDCMD Lcd, LCDCMD Lcd, LCDCMD Lcd, %00110000 ' ' ' ' ' ' ' ' ' ' clear the LCD move cursor home move cursor left move cursor right shift chars left shift chars right Display Data RAM Character Generator RAM DDRAM address of line 1 DDRAM address of line 2 ' allow LCD to self-initialize first ' send wakeup sequence to LCD ' pause required by LCD specs %00110000 ' pause required by LCD specs %00110000 %00100000 %00101000 %00001100 %00000110 ' ' ' ' ' pause required by LCD specs set data bus to 4-bit mode set to 2-line mode with 5x8 font display on without cursor auto-increment cursor Main: DO LCDOUT Lcd, LcdCls, ["Hello!"] GOSUB Read_LCD_Screen PAUSE 3000 LCDOUT Lcd, LcdCls, ["I'm a 2x16 LCD!"] GOSUB Read_LCD_Screen PAUSE 3000 LOOP BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 261 LCDIN – BASIC Stamp Command Reference Read_LCD_Screen: DEBUG "LCD now says: " LCDIN Lcd, LcdLine1, [STR char\16] DEBUG STR char\16, CR RETURN Page 262 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 5: BASIC Stamp Command Reference – LCDOUT LCDOUT BS1 BS2 BS2e BS2sx BS2p BS2pe BS2px LCDOUT Pin, Command, [ OutputData ] Function Send data to an LCD display. • Pin is a variable/constant/expression (0 – 1 or 8 – 9) that specifies which I/O pins to use. The LCD requires, at most, seven I/O pins to operate. The Pin argument serves a double purpose; specifying the first pin and, indirectly, the group of other required pins. See explanation below. All I/O pins will be set to output mode. • Command is a variable/constant/expression (0 – 255) indicating an LCD command to send. • OutputData is a list of variables, constants, expressions and formatters that tells LCDOUT how to format outgoing data. LCDOUT can transmit individual or repeating bytes, convert values into decimal, hex or binary text representations, or transmit strings of bytes from variable arrays. These actions can be combined in any order in the OutputData list. Quick Facts Table 5.49: LCDOUT Quick Facts. Values for Pin I/O Pin Arrangement when Pin is 0 or 1 I/O Pin Arrangement when Pin is 8 or 9 Special Notes Related Commands BS2p, BS2pe, and BS2px 0, 1, 8 or 9 0 or 1 (depending on pin): LCD Enable (E) pin 2: LCD Read/Write (R/W) pin 3: LCD Register Select (RS) pin 4 – 7: LCD Data Buss (DB4 – DB7, respectively) pins 8 or 9 (depending on pin): LCD Enable (E) pin 10: LCD Read/Write (R/W) pin 11: LCD Register Select (RS) pin 12 – 15: LCD Data Buss (DB4 – DB7, respectively) pins LCDOUT is designed to use the LCD's 4-bit mode only. LCDCMD and LCDIN Explanation NOTE: LCDCMD, LCDIN and LCDOUT use a 4-bit interface to the LCD which requires a specific initialization sequence before LCDIN and LCDOUT can be used; read more below. The three LCD commands (LCDCMD, LCDIN and LCDOUT) allow the BS2p, BS2pe, and BS2px to interface directly to standard LCD displays that feature a Hitachi 44780 controller (part #HD44780A). This includes many 1 x 16, 2 x 16 and 4 x 20 character LCD displays. BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 263 LCDOUT – BASIC Stamp Command Reference The LCDOUT command is used to send one instruction followed by at least one data byte to the LCD. The data that is output is written to the LCD's Character Generator RAM or Display Data RAM. The following is an example of the LCDOUT command: LCDOUT A SIMPLE LCDOUT EXAMPLE. 0, 1, ["Hello World!"] The above code will clear the LCD screen and then send "Hello World!" to the screen. The first argument (0) is the starting I/O pin number and the second argument (1) is the LCD's instruction for Clear Screen. The LCDOUT command actually uses more than just the I/O pin specified by the Pin argument. The LCDOUT command requires seven I/O pins. This is because the standard LCD displays have a parallel interface, rather than a serial one. The Pin argument can be the numbers 0, 1, 8 or 9 and will result in the use of the I/O pins shown in Table 5.49. Please refer to the LCDCMD command description for information on properly wiring the LCD display. TWO VERY IMPORTANT STEPS: 1) WIRING THE BASIC STAMP TO AN LCD. 2) INITIALIZING THE LCD. When the LCD is first powered-up, it defaults to an 8-bit interface and must be properly configured for a 4-bit buss before sending commands like the one shown above. This process is known as initializing the LCD and is the first thing your program should do upon starting up. Please refer to the LCDCMD command description for information on properly initializing the LCD display. The LCDOUT command's OutputData argument is exactly like that of the DEBUG and SEROUT command's OutputData argument. This means data can be sent as literal text, ASCII character values, repetitive values, decimal, hexadecimal and binary translations and string data as in the examples below. value VAR Byte value = 65 LCDOUT LCDOUT LCDOUT LCDOUT LCDOUT 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, [value] [REP value\5] [DEC value] [HEX value] [BIN value] ' ' ' ' ' send send send send send "A" "AAAAA" "6" and "5" "4" and "1" "1000001" Page 264 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com SENDING AND FORMATTING DATA. 5: BASIC Stamp Command Reference – LCDOUT Table 5.50 and Table 5.51 list all the available conversion formatters and special formatters available to the LCDOUT command. See the DEBUG and SEROUT commands for additional information and examples of their use. Table 5.50: LCDOUT Conversion Formatters. Conversion Formatter DEC{1..5} SDEC{1..5} HEX{1..4} SHEX{1..4} IHEX{1..4} Type of Number Notes Decimal, optionally fixed to 1 – 5 digits 1 Signed decimal, optionally fixed to 1 – 5 digits 1,2 Hexadecimal, optionally fixed to 1 – 4 digits 1,3 Signed hexadecimal, optionally fixed to 1 – 4 digits 1,2 Indicated hexadecimal, optionally fixed to 1 – 4 digits ($ prefix) 1 Signed, indicated hexadecimal, optionally fixed to 1 – 4 digits ISHEX{1..4} 1,2 ($ prefix) BIN{1..16} Binary, optionally fixed to 1 – 16 digits 1 SBIN{1..16} Signed binary, optionally fixed to 1 – 16 digits 1,2 IBIN{1..16} Indicated binary, optionally fixed to 1 – 16 digits (% prefix) 1 ISBIN{1..16} Signed, indicated binary, optionally fixed to 1 – 16 digits (% prefix) 1,2 1 Fixed-digit formatters like DEC4 will pad the number with leading 0s if necessary; ex: DEC4 65 sends 0065. If a number is larger than the specified number of digits, the leading digits will be dropped; ex: DEC4 56422 sends 6422. 2 Signed modifiers work under two's complement rules. 3 The HEX modifier can be used for BCD to Decimal Conversion. See “Hex to BCD Conversion” on page 97. Table 5.51: LCDOUT Special Formatters. Special Formatter ? ASC ? STR ByteArray {\L} REP Byte \L USING THE COMMAND ARGUMENT. Action Displays "symbol = x' + carriage return; where x is a number. Default format is decimal, but may be combined with conversion formatters (ex: BIN ? x to display "x = binary_number"). Displays "symbol = 'x'" + carriage return; where x is an ASCII character. Send character string from an array. The optional \L argument can be used to limit the output to L characters, otherwise, characters will be sent up to the first byte equal to 0 or the end of RAM space is reached. Send a string consisting of Byte repeated L times (ex: REP "X"\10 sends "XXXXXXXXXX"). The Command argument is useful for proceeding a set of data with a special LCD instruction. For example, the code below will move the cursor to location 64 (the first character on the second line) and print "Hi": LCDOUT 0, 128 + 64, ["Hi"] The next example, below, will turn on the blinking block cursor and print "Yo!": BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 265 LCDOUT – BASIC Stamp Command Reference LCDOUT 0, 13, ["Yo!"] Most of the time, you will want to send data without preceding it with a command. To do this, simply use 0 for the Command argument, as in: LCDOUT 0, 0, ["Hello there!"] Another use for the LCDOUT command is to access and create custom characters. The Hitachi 44780 controller has a built-in character set that is similar to the ASCII character set (at least for the first 128 characters). Most of these characters are stored in ROM and are not changeable, however, the first eight characters (ASCII 0 though 7) are programmable. CREATING CUSTOM CHARACTERS. Each of the programmable characters is five pixels wide and eight pixels tall. It takes eight bytes to describe each character; one byte per row (the left-most three bits are ignored). For example, the character at ASCII location 0 is defined by the bit patterns stored in bytes 0 through 7 of Character Generator RAM (CGRAM). The character at ASCII location 1 is defined by the bit patterns stored in bytes 8 through 15 of CGRAM, and so on. To create a custom character, use some graph paper to plot out the bit pattern (on and off pixels) in a 5 x 8 pattern, as shown in Figure 5.16. Then calculate the corresponding binary value of the bit pattern for each of the eight rows of character data. Character Cell Structure and Data ---------Bits--------4 3 2 1 0 Byte 0: Byte 1: Byte 2: Byte 3: Byte 4: Byte 5: Byte 6: Byte 7: Binary Values Decimal Values xxx00000 xxx01010 xxx00000 xxx00100 xxx10001 xxx01110 xxx00000 xxx00000 00 10 00 04 17 14 00 00 After the data is calculated for each character (8 byte values per character), use the LCDOUT command with the "Move To CGRAM Address" instruction to insert the data into the character's CGRAM locations. For example, the code below will store the character shown in Figure 5.16 into Page 266 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com Figure 5.16: LCD Character Structure. 5: BASIC Stamp Command Reference – LCDOUT character 0's CGRAM data locations. Then it will place the cursor back on the display (DDRAM) and print the character on the screen. LCDOUT LCDOUT 0, 64+0, [00, 10, 00, 04, 17, 14, 00, 00] 0, 128+0, ["Custom Char: ", 0] The number 64 in the Command argument is the LCD's "Move to CGRAM Address" instruction and the 0 that is added to it is the location of the first row of data for the character 0. The LCDOUT command will write the first OutputData value (00) to this location, the second OutputData value (10) to location 1, etc. If we wanted this custom character to affect character 1, instead of 0, we'd have to adjust the value of the "Move To..." command, i.e.: 64+8. To affect character 2, we'd use 64+16. To try the example above, don't forget to execute the LCD initialization code (shown in the LCDCMD description) first and never forget to move the cursor back to the screen (as with the last command, above) when you're done writing the character data to CGRAM. Demo Program (LCDOUT.bsp) NOTE: This example program can be used with the BS2p, BS2pe, and BS2px. This program uses conditional compilation techniques; see Chapter 3 for more information. ' LCDOUT.bsp ' This program demonstrates initialization and printing on a 2x16 ' character LCD display. ' {$STAMP BS2p} ' {$PBASIC 2.5} #IF ($STAMP < BS2P) #THEN #ERROR "Program requires BS2p, BS2pe or BS2px." #ENDIF Lcd PIN 0 LcdCls LcdHome LcdCrsrL LcdCrsrR LcdDispL LcdDispR LcdDDRam LcdCGRam LcdLine1 LcdLine2 CON CON CON CON CON CON CON CON CON CON $01 $02 $10 $14 $18 $1C $80 $40 $80 $C0 Init_LCD: PAUSE 1000 ' ' ' ' ' ' ' ' ' ' clear the LCD move cursor home move cursor left move cursor right shift chars left shift chars right Display Data RAM Character Generator RAM DDRAM address of line 1 DDRAM address of line 2 ' allow LCD to self-initialize first BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 267 LCDOUT – BASIC Stamp Command Reference LCDCMD Lcd, PAUSE 5 LCDCMD Lcd, PAUSE 0 LCDCMD Lcd, PAUSE 0 LCDCMD Lcd, LCDCMD Lcd, LCDCMD Lcd, LCDCMD Lcd, %00110000 ' send wakeup sequence to LCD ' pause required by LCD specs %00110000 ' pause required by LCD specs %00110000 %00100000 %00101000 %00001100 %00000110 ' ' ' ' ' pause required by LCD specs set data bus to 4-bit mode set to 2-line mode with 5x8 font display on without cursor auto-increment cursor LCDOUT Lcd, LcdCGRam, ' load custom character map [$00, $0A, $0A, $00, $11, $0E, $06, $00] Main: DO LCDOUT Lcd, PAUSE 750 LCDOUT Lcd, PAUSE 1500 LCDCMD Lcd, LCDOUT Lcd, LCDOUT Lcd, PAUSE 2000 LOOP END LcdCls, ["Hello my friend."] LcdLine2, ["How are you?"] LcdCls LcdLine1 + 1, ["I'm doing just"] LcdLine2 + 4, ["fine! ", 0] Page 268 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 5: BASIC Stamp Command Reference – LET LET 1 BS1 BS2 BS2e BS2sx BS2p BS2pe BS2px { LET } Variable = Value Function Sets Variable equal to the value of Value. • Value is a variable/constant/expression. (0-65535). • Variable is a variable which will be set equal to Value. Explanation LET is an optional instruction for the BASIC Stamp 1 that can be used with variable assignment statements, such as A = 5 and B = A + 2, etc. This instruction is not required and only exists on the BASIC Stamp 1. LET was a commonly used command in early forms of BASIC, and was originally included in the BS1 command set to accommodate programmers from that generation. Parallax recommends that all new BASIC Stamp 1 programs use assignment statements without the LET command. 1 Demo Program (LET.bs1) ' ' ' ' ' LET.bs1 This example demonstrates the use of LET in assignment statements, which is optional and not recommended. Note that the Lunchtime and Dinnertime routines do essentially the same thing, but the Dinnertime method is recommended(even though the pricing scheme is not!) ' {$PBASIC 1.0} ' {$STAMP BS1} SYMBOL SYMBOL SYMBOL SYMBOL SYMBOL salad bread soup lunch dinner = = = = = B1 B2 B3 B4 B5 Lunchtime: LET salad = 3 LET bread = 1 LET soup = 4 LUNCH = salad + bread + soup DEBUG "lunch = $", #lunch, "plus local tax.", CR Dinnertime: salad = 4 bread = 2 soup = 5 BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 269 LET – BASIC Stamp Command Reference dinner = salad + bread + soup DEBUG "Dinner = $",# lunch, "plus local tax.", CR Page 270 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com 5: BASIC Stamp Command Reference – LOOKDOWN LOOKDOWN 1 All 2 BS1 BS2 BS2e BS2sx BS2p BS2pe BS2px LOOKDOWN Target, ( Value0, Value1, ...ValueN ), Variable LOOKDOWN Target, { ComparisonOp } [ Value0, Value1, ...ValueN ], Variable Function 1 NOTE: Expressions are not allowed as arguments on the BS1. All 2 Compare Target value to a list of values and store the index number of the first value that matches into Variable. If no value in the list matches, Variable is left unaffected. On all BS2 models, the optional ComparisonOp is used as criteria for the match; the default criteria is "equal to." • Target is a variable/constant/expression (0 – 65535) to be compared to the values in the list. • ComparisonOp is an optional comparison operator (as described in Table 5.53) to be used as the criteria when comparing values. When no ComparisonOp is specified, equal to (=) is assumed. This argument is not available on the BS1. • Values are variables/constants/expressions (0 – 65535) to be compared to Target. • Variable is a variable (usually a byte) that will be set to the index (0 – 255) of the matching value in the Values list. If no matching value is found, Variable is left unaffected. Quick Facts Table 5.52: LOOKDOWN Quick Facts. BS1 and all BS2 Models Limit of Value Entries Starting Index Number If value list contains no match… Related Command 256 0 Variable is left unaffected LOOKUP Explanation LOOKDOWN works like the index in a book. In an index, you search for a topic and get the page number. LOOKDOWN searches for a target value in a list, and stores the index number of the first match in a variable. For example: BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 271 LOOKDOWN – BASIC Stamp Command Reference SYMBOL SYMBOL value result value result = 17 = 15 = = B0 B1 1 LOOKDOWN value, (26, 177, 13, 1, 0, 17, 99), result DEBUG "Value matches item ", #result, "in list" -- or -value result value result VAR VAR = 17 = 15 Byte Nib All 2 LOOKDOWN value, [26, 177, 13, 1, 0, 17, 99], result DEBUG "Value matches item ", DEC result, " in list" DEBUG prints, “Value matches item 5 in list” because the value (17) matches item 5 of [26, 177, 13, 1, 0, 17, 99]. Note that index numbers count up from 0, not 1; that is, in this list, 26 is item 0. THE INDEX NUMBER OF THE FIRST ITEM IS 0, NOT 1. What happens if the value doesn’t match any of the items in the list? Try changing “Value = 17” to “Value = 2.” Since 2 is not on the list, LOOKDOWN leaves result unaffected. Since result contained 15 before LOOKDOWN executed, DEBUG prints “Value matches item 15 in list.” By strategically setting the initial value of result, as we have here, your program can be written to detect when an item was not found in the list. Don’t forget that text phrases are just lists of byte values, so they too are eligible for LOOKDOWN searches, as in this example: SYMBOL SYMBOL value result value = result = = = B0 B1 "f" 255 LOOKDOWN value, ("The quick brown fox"), result DEBUG "Value matches item ", #result, "in list" -- or -- Page 272 • BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com USING TEXT IN THE VALUE LIST. 1 5: BASIC Stamp Command Reference – LOOKDOWN All 2 value result value result VAR VAR = = Byte Nib "f" 255 LOOKDOWN value, ["The quick brown fox"], result DEBUG "Value matches item ", DEC result, " in list" DEBUG prints, “Value matches item 16 in list” because the character at index item 16 is "f" in the phrase, “The quick brown fox”. LOOKDOWN CAN USE VARIABLES AND EXPRESSIONS IN THE VALUE LIST. The examples above show LOOKDOWN working with lists of constants, but it also works with variables and expressions also. Note, however, that expressions are not allowed as argument on the BS1. USING LOOKDOWN'S COMPARISON OPERATORS. On all BS2 models, the LOOKDOWN command can also use another All 2 criteria (other than "equal to") for its list. All of the examples above use LOOKDOWN’s default comparison operator, =, that searches for an exact match. The entire list of ComaprisonOps is shown in Table 5.53. The "greater than" comparison operator (>) is used in the following example: value result value result VAR VAR = = Byte Nib 17 15 LOOKDOWN value, >[26, 177, 13, 1, 0, 17, 99], result DEBUG "Value greater than item ", DEC result, " in list" DEBUG prints, “Value greater than item 2 in list” because the first item the value 17 is greater than is 13 (which is item 2 in the list). Value is also greater than items 3 and 4, but these are ignored, because LOOKDOWN only cares about the first item that matches the criteria. This can require a certain amount of planning in devising the order of the list. See the demo program below. WATCH OUT FOR UNSIGNED MATH ERRORS WHEN USING THE COMPARISON OPERATORS. LOOKDOWN comparison operators (Table 5.53) use unsigned 16-bit math. They will not work correctly with signed numbers, which are represented internally as two’s complement (large 16-bit integers). For example, the two’s complement representation of -99 is 65437. So although -99 is certainly less than 0, it would appear to be larger than zero BASIC Stamp Syntax and Reference Manual 2.2 • www.parallax.com • Page 273 LOOKDOWN – BASIC Stamp Command Reference to the LOOKDOWN comparison operators. The bottom line is: Don’t used signed numbers with LOOKDOWN comparisons. ComparisonOp Symbol = > < >=