122-32000 Parallax Inc, 122-32000 Datasheet
122-32000
Specifications of 122-32000
Related parts for 122-32000
122-32000 Summary of contents
Page 1
Propeller Manual Version 1.01 ...
Page 2
... 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. ...
Page 3
... 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 ...
Page 4
...
Page 5
PREFACE ............................................................................................................................... 12 CHAPTER 1 : INTRODUCING THE PROPELLER CHIP....................................................... 13 C ............................................................................................................................. 13 ONCEPT P T ................................................................................................................... 14 ACKAGE YPES P D ................................................................................................................ 15 IN ESCRIPTIONS S ................................................................................................................... 16 PECIFICATIONS H C .................................................................................................... 17 ARDWARE ONNECTIONS ...
Page 6
Line Numbers.................................................................................................................. .........................................................................................................................65 DIT ODES Insert and Overwrite Modes............................................................................................65 Align Mode ...................................................................................................................... LOCK ELECTION AND ELECTION I O .................................................................................................69 NDENTING AND UTDENTING Single Lines.....................................................................................................................70 Multiple Lines .................................................................................................................. ...................................................................................................74 LOCK ROUP NDICATORS S ...
Page 7
Quick Review & 10.............................................................................................. 137 E 11 XERCISE IBRARY BJECTS Work and Library Folders ............................................................................................. 141 E 12 XERCISE HOLE AND EAL Pseudo-Real Numbers ................................................................................................. 143 Floating-Point Numbers................................................................................................ 144 Context-Sensitive Compile Information ........................................................................ 147 ...
Page 8
COGNEW................................................................................................................................189 COGSTOP ..............................................................................................................................193 CON .....................................................................................................................................194 CONSTANT ............................................................................................................................200 .................................................................................................202 ONSTANTS PRE DEFINED CTRA, CTRB.........................................................................................................................204 DAT .....................................................................................................................................208 DIRA, DIRB.........................................................................................................................212 FILE ...................................................................................................................................215 FLOAT..................................................................................................................................216 _FREE..................................................................................................................................218 FRQA, FRQB.........................................................................................................................219 IF .......................................................................................................................................220 IFNOT..................................................................................................................................225 INA, INB ............................................................................................................................226 LOCKCLR ..............................................................................................................................228 LOCKNEW ..............................................................................................................................230 LOCKRET ..............................................................................................................................233 LOCKSET ...
Page 9
S ............................................................................................................................ 312 YMBOLS TRUNC ................................................................................................................................. 314 VAR..................................................................................................................................... 315 VCFG................................................................................................................................... 317 VSCL................................................................................................................................... 320 WAITCNT ............................................................................................................................. 322 WAITPEQ ............................................................................................................................. 326 WAITPNE ............................................................................................................................. 328 WAITVID ............................................................................................................................. 329 WORD................................................................................................................................... 331 WORDFILL............................................................................................................................ 335 WORDMOVE............................................................................................................................ 336 _XINFREQ............................................................................................................................ 337 CHAPTER 5 : ASSEMBLY LANGUAGE REFERENCE ....................................................... ...
Page 10
CLKSET................................................................................................................................361 CMP .....................................................................................................................................362 CMPS ...................................................................................................................................362 CMPSUB................................................................................................................................363 CMPSX..................................................................................................................................364 CMPX ...................................................................................................................................364 COGID..................................................................................................................................365 COGINIT ..............................................................................................................................366 COGSTOP ..............................................................................................................................367 C ( IF_ ) ............................................................................................................368 ONDITIONS X DJNZ ...................................................................................................................................370 E .............................................................................................................................371 FFECTS FIT .....................................................................................................................................372 HUBOP..................................................................................................................................373 JMP .....................................................................................................................................374 JMPRET................................................................................................................................374 LOCKCLR ..............................................................................................................................375 LOCKNEW ..............................................................................................................................376 LOCKRET ..............................................................................................................................376 LOCKSET ..............................................................................................................................377 ...
Page 11
RDBYTE ............................................................................................................................... 394 RDLONG ............................................................................................................................... 395 RDWORD ............................................................................................................................... 396 R ......................................................................................................................... 397 EGISTERS RES..................................................................................................................................... 398 RET..................................................................................................................................... 399 REV..................................................................................................................................... 399 ROL..................................................................................................................................... 400 ROR..................................................................................................................................... 400 SAR..................................................................................................................................... 401 SHL..................................................................................................................................... 402 SHR..................................................................................................................................... 402 SUB..................................................................................................................................... 403 SUBABS ............................................................................................................................... 404 SUBS................................................................................................................................... 404 SUBSX ................................................................................................................................. 405 SUBX................................................................................................................................... ...
Page 12
Preface Thank you for purchasing a Propeller chip. You will be spinning your own programs in no time! Propeller chips are incredibly capable multiprocessor microcontrollers; the much-anticipated result of over eight years of the intense efforts of Chip Gracey and ...
Page 13
Chapter 1: Introducing the Propeller Chip This chapter describes the Propeller chip hardware. To fully understand and use the Propeller effectively, it’s important to first understand its hardware architecture. This chapter presents the details of the hardware such as package ...
Page 14
Package Types The Propeller chip is available in the package types shown here. P8X32A-D40 40-pin DIP P8X32A-Q44 P8X32A-M44 44-pin LQFP 44-pin QFN Page 14 · Propeller Manual v1.0 ...
Page 15
Pin Descriptions Pin Name Direction Description General purpose I/O Port A. Can source/sink 30 mA each at 3.3 VDC. Do not exceed 100 mA source/sink total across any group of I/O pins at once. Logic threshold is ≈ ½ VDD; ...
Page 16
Specifications Model P8X32A Power Requirements 3.3 volts DC External Clock Speed MHz (4 MHz to 8 MHz with Clock PLL running) System Clock Speed MHz 12 MHz or 20 kHz (approximate; may range from ...
Page 17
Hardware Connections Figure 1-1 shows an example wiring diagram that provides host and EEPROM access to the Propeller chip. In this example the host access is achieved through the Propeller Clip device (a USB to TTL serial converter). Figure 1-1: ...
Page 18
Boot Up Procedure Upon power-up (+ 100 ms), RESn low-to-high, or software reset: 1. The Propeller chip starts its internal clock in slow mode (≈ 20 KHz), delays for 50 ms (reset delay), switches the internal clock to fast mode ...
Page 19
See Chapter 3: Propeller Programming Tutorial. Shutdown Procedure When the Propeller goes into shutdown mode, the internal clock is stopped causing all cogs to halt and all I/O pins are set to input ...
Page 20
Block Diagram Figure 1-2: Propeller Chip Block Diagram Page 20 · Propeller Manual v1.0 ...
Page 21
Cog and Hub interaction is critical to the Propeller chip. The Hub controls which cog can access mutually-exclusive resources, such as Main RAM/ROM, configuration registers, etc. The Hub gives exclusive access to every cog one at a time in a ...
Page 22
Shared Resources There are two types of shared resources in the Propeller: 1) common, and 2) mutually- exclusive. Common resources can be accessed at any time by any number of cogs. Mutually-exclusive resources can also be accessed by any number ...
Page 23
Each cog has its own RAM, called Cog RAM, which contains 512 registers of 32 bits each. The Cog RAM is all general purpose RAM except for the last 16 registers, which are special purpose registers, as described in Table ...
Page 24
Each Special Purpose Register may be accessed via: 1) its physical register address, 2) its predefined name register array variable with an index 15. The following are examples in Propeller Assembly: MOV $1F4, #$FF ...
Page 25
Figure 1-3: Cog-Hub Interaction – Best Case Scenario Figure 1-4 shows the worst-case scenario; the hub instruction was ready on the cycle right after the start of Cog 0’s access window; it just barely missed it. The cog waits until ...
Page 26
I/O Pins The Propeller has 32 I/O pins which are entirely general purpose. Four I/O pins (28 - 31) have a special purpose at Boot Up and are available for general purpose use afterwards; see the Boot Up ...
Page 27
Table 1-4: I/O Sharing Examples Bit 12 of Cogs’ I/O Direction Register Cog Example Example ...
Page 28
CLK Register The CLK register is the System Clock configuration control; it determines the source of and the characteristics for the System Clock. More precisely, the CLK register configures the RC Oscillator, Clock PLL, Crystal Oscillator, and Clock Selector circuits. ...
Page 29
Table 1-7: PLLENA (Bit 6) Bit Effect Disables the PLL circuit. The RCFAST and RCSLOW settings of the _CLKMODE 0 declaration configure PLLENA this way. Enables the PLL circuit. Each of the PLLxx settings of the _CLKMODE declaration configures PLLENA ...
Page 30
Table 1-10: CLKSELx (Bits 2:0) CLKSELx _CLKMODE Setting RCFAST RCSLOW XINPUT XTALx and PLL1x XTALx and PLL2x XTALx and ...
Page 31
ROM. The Main RAM is general purpose and is the destination of a Propeller Application either downloaded from a host or uploaded from the external 32 KB EEPROM. The Main ROM contains all the ...
Page 32
Main ROM The second half of Main Memory is all ROM. This space is used for character definitions, math functions, and the Boot Loader and Spin Interpreter. Character Definitions The first half of ROM is dedicated to a set of ...
Page 33
The character pairs are merged row-by-row such that each character's 16 horizontal pixels are spaced apart and interleaved with their neighbors' so that the even character takes bits ...30, and the odd character takes bits 1, 3, ...
Page 34
Log and Anti-Log Tables The log and anti-log tables are useful for converting values between their number form and exponent form. When numbers are ...
Page 35
... The Propeller Tool software consists of a single executable file, some on-line help files and Propeller library files, all stored in the same folder by the installer, typically: C:\Program Files\Parallax Inc\Propeller. The Propeller Tool’s executable file “Propeller.exe” can be copied and run from any folder on the computer; it does not rely on special system files other than what comes standard with the operating system. Each library file (files with a “ ...
Page 36
This means fewer files to maintain and a higher likelihood that the documentation will stay in sync with the source code revision. To further enable this process, we’ve created: • Two types of source comments, 1) code comments (for ...
Page 37
Propeller products. For more information about files, objects, object documentation, library files and source code, see Chapter 3: Propeller Programming Tutorial. Screen ...
Page 38
Panes one, two and three are all part of the Integrated Explorer. The Integrated Explorer is the region to the left of the Editor pane (pane four) that provides views of the project you’re working on as well as folders ...
Page 39
Pane 1: Object View Pane Pane one is the Object View pane. The Propeller chip’s language, Spin, is object-based and a Propeller Project can be made up of multiple objects. hierarchical view of the project you most recently compiled successfully, ...
Page 40
The Filter field (below the File List) provides a drop-down list of file extensions, called filters, to display in the File List. Typically it will be set to show Spin files only (those with “.spin” file extensions) but can also ...
Page 41
Each edit page can display source code in one of four views: 1) Full Source 2) Condensed 3) Summary 4) Documentation. The view mode can be seen or changed, individually for each edit tab, by: 1) selecting the respective radio ...
Page 42
Figure 2-5: Viewing and Arranging Multiple Objects Page 42 · Propeller Manual v1.0 Step 1: To see more than one object’s source code simultaneously, left-click and drag an edit tab to a lower region of the Editor Pane. Step 2: ...
Page 43
The vertical size of these two regions can be changed by dragging the horizontal splitter bar separating them. Of course, the objects you’re interfacing to can be viewed in whatever mode is convenient at the moment (Full Source, Condensed, Summary, ...
Page 44
The Status Bar at the bottom of the Propeller Tool, is separated into six panels, each displaying useful information at various stages of the development process. Panel one of the Status Bar always displays the row and column position of ...
Page 45
Menu Items File Menu New Open… Open From… Save Save As… Save To… Save All Close Close All Select Top Object File… Archive → Project… → Project + Propeller Tool... Perform the same task as above but add the entire ...
Page 46
Hide/Show Explorer Print Preview… Print… <recent files> Exit Edit Menu Undo Redo Cut Copy Paste Select All Find / Replace… Find Next Replace Go To Bookmark Page 46 · Propeller Manual v1.0 Hide or show the Integrated Explorer panels (left ...
Page 47
Text Bigger Text Smaller Preferences… Run Menu Compile Current → View Info… → Update Status → Load RAM → Load EEPROM Compile Top → View Info… → Update Status → Load RAM → Load EEPROM Increase the font size in ...
Page 48
Identify Hardware… Help Menu Propeller Tool… Spin Language… Assembly Language… Example Projects… View Character Chart… View Parallax Website… E-mail Parallax Support… About… Page 48 · Propeller Manual v1.0 Scan available ports for the Propeller chip and, if found, display the ...
Page 49
Find/Replace Dialog The Find/Replace dialog is used to find and/or replace text in the current edit page. Figure 2-8: The Find/Replace Dialog Find: The Find: field is where to enter the string you wish to search for word ...
Page 50
Whole Words Select the Whole Words checkbox if you want the string in the Find: field to match only characters of entire words rather than both characters of entire words and characters within larger words. Case Select the Case checkbox ...
Page 51
Find Button The Find button starts the search process based on all the settings in the Find/Replace dialog. If text in the edit page matches the criteria selected and moved into view, and then the Find button changes ...
Page 52
Object View The Object View displays a hierarchical view of the project you most recently compiled successfully. There are two Object Views in the Propeller Tool: 1) The Object View at the top of the Integrated Explorer in the main ...
Page 53
Work Folder The Work Folder (yellow) is the folder where the top object file exists. Every project has one, and only one, work folder. Library Folder The Library Folder (blue) is where the Propeller Tool’s library objects exist, such as ...
Page 54
... Figure 2-10b shows the hint for the Numbers object: 1) it’s an object file (i.e.: a sub object, rather than the top object), 2) it’s in the library folder, and 3) it’s at the path and file name: C:\Program Files\Parallax Inc\Propeller\Numbers.spin. From this information you can also infer that the library folder for this project is: C:\Program Files\Parallax Inc\Propeller. It’ ...
Page 55
Object Info The Object Info form displays details about the project you just compiled successfully using the Compile Current/Top → View Info… function. At the top is an Info Object View very similar to that of the Integrated Explorer’s Object ...
Page 56
Info Object View The Info Object View works exactly like the Object View (see Object View, p. 52) with a few exceptions: • Clicking on an object within the Info Object View updates the Object Info display with information pertaining ...
Page 57
Figure 2-12: Example Object Info Form display with the object Hex View open showing the hex values of the ABC Product compilation. The buttons under the hex display allow for downloading and saving of the currently displayed hex data. The ...
Page 58
Character Chart The Character Chart window is available from the Help → View Character Chart… menu item. It shows the entire character set for the Parallax Font that is used by the Propeller Tool and is also built into the ...
Page 59
The Vertical Resistor character (near the lower right of the display) is selected in this example. The information at the bottom of the window shows the font size, in points, and the character’s location in the character set in decimal, ...
Page 60
Symbolic Order Symbolic Order, Figure 2-15, shows the characters arranged categorically. This is useful for finding the special characters in the Parallax font for depicting timing diagrams, lines, arrows, and schematics. Figure 2-15: Parallax Font Character Chart, Symbolic Order Page ...
Page 61
View Modes, Bookmarks and Line Numbers While developing objects, or conversing about them with other users, it may sometimes be difficult to quickly navigate to certain regions of code simply because of the size of the file itself or because ...
Page 62
Figure 2-16: View Modes Example Page 62 · Propeller Manual v1.0 Can’t find a routine in an object? Step 1: Select Summary Mode Step 2: Click on the routine’s line. Step 3: Select Full Source mode again; ...
Page 63
Bookmarks You can also set bookmarks on various lines of each edit page’s source code to quickly jump to desired locations. Figure 2-17 shows an example of two bookmarks set in the Graphics object’s edit tab. To enable bookmarks, press ...
Page 64
Line Numbers Maybe it is easier to remember a region of code by its line number. At any time, you can enable or disable line numbers in the edit page. Line Numbers show up in the Line Number Gutter, next ...
Page 65
Edit Modes There are three edit modes provided by the Editor pane: 1) Insert (default), 2) Align (available for “.spin” objects only), and 3) Overwrite. You can switch between each mode by using the Insert key. The current mode is ...
Page 66
Align Mode The Align mode is a special version of the Insert mode designed specifically for maintaining source code. To understand Align mode, we first need to consider common programming techniques. There are two very common practices used when writing ...
Page 67
If the original code used space characters to align the comments, changing “ “ ” will cause the comments to shift right by three characters. BtnDelay Figure 2-22: Common Alignment Issues – Space Aligned If the original code had been ...
Page 68
Since the Align mode maintains existing alignments as much as possible, much less time is wasted realigning elements due to future edits by the programmer. Additionally, since spaces are used instead of tab characters, the code maintains the same look ...
Page 69
Figure 2-24: Block Selection and Selection Moving Indenting and Outdenting A common programming practice is to indent blocks of code that are either in loops or are conditionally executed in order to make that code easier to read. The act ...
Page 70
Single Lines For Spin code, the Propeller Tool uses a set of fixed tab positions that you can change via the Edit → Preferences menu. Each Spin block ( Fixed Tab settings. The Tab key moves the cursor to the ...
Page 71
If the cursor is immediately to the left of the first character on a line, both the Shift + Tab and the Backspace keys cause the cursor and the text to be shifted left to the previous tab position; i.e.: ...
Page 72
Figure 2-29: Code Block Indenting Note that the four lines we had selected in the second step are now indented to the next fixed tab position (two spaces to the right of the start of the “repeat”) and the selection ...
Page 73
Figure 2-30: Sample Code Block with Comments to the Right If we block select the first few characters of the comments (Alt + Left Mouse Button and Drag, Figure 2-31), we can press the Tab key to indent those comments ...
Page 74
Block-Group Indicators Sometimes it may be hard to see exactly how groups of code are logically arranged simply by their level of indention. The Propeller Tool can optionally indicate the logical block-groups of conditional blocks or loop blocks as shown ...
Page 75
Shortcut Keys Categorical Listings In Table 2-1, keyboard shortcuts are grouped by related functions. In Table 2-2, which begins on page 80, the keyboard shortcuts are grouped by key rather than by function. Table 2-1: Shortcut Keys – Categorical Listing ...
Page 76
Table 2-1: Shortcut Keys – Categorical Listing (continued) Function Select Top File Identify Hardware Compile Current File and View Information Compile Current File and Update Status Compile Current File, Load RAM and Run Compile Current File, Load EEPROM and Run ...
Page 77
Table 2-1: Shortcut Keys – Categorical Listing (continued) Navigation Shortcuts (cont.) Function Select word Select line Select to start of next word Select to start of previous word Select to start of line Select to end of line Select to ...
Page 78
Table 2-1: Shortcut Keys – Categorical Listing (continued) Function Delete current line Delete to end of line Rename Folder/File (in Folder List or File List) Insert Negative One Superior Character ( ¹ Insert One Superior Character ( ² Insert Two ...
Page 79
Table 2-1: Shortcut Keys – Categorical Listing (continued) Function × Insert Multiply Character ( ) ÷ Insert Divide Character ( ) √ Insert Radical Character ( ) ∞ Insert Infinity Character ( ) δ Insert Delta Character ( ) µ ...
Page 80
Listing by Key Table 2-2: Shortcuts By Key Function F10 F11 End Esc Home Insert Page Down Page Up Tab Double-Click Triple-Click Ctrl + A Ctrl + B Ctrl + C Ctrl + E ...
Page 81
Table 2-2: Shortcuts By Key (continued) Function Ctrl + N Ctrl + O Ctrl + S Ctrl + P Ctrl + T Ctrl + V Ctrl + W Ctrl + X Ctrl + Y Ctrl + Z Ctrl + F4 ...
Page 82
Table 2-2: Shortcuts By Key (continued) Alt + C Alt + D Alt + S Alt + Q Alt + U Alt + Down Alt + Left Alt + Mouse Wheel Down Alt + Mouse Wheel Up Alt + Right ...
Page 83
Table 2-2: Shortcuts By Key (continued) Function Ctrl + Shift + $ Ctrl + Shift + % Ctrl + Shift + * Ctrl + Shift + - Ctrl + Shift + . Ctrl + Shift + / Ctrl + Shift ...
Page 84
Function Ctrl + Shift + Tab Table 2-2: Shortcuts By Key (continued) Function Ctrl + Shift + Alt + $ Ctrl + Shift + Alt + < Ctrl + Shift + Alt + > Ctrl + Shift + Alt + ...
Page 85
Chapter 3: Propeller Programming Tutorial This chapter assumes you are familiar with the general programming concepts of other programming languages, including object-oriented languages. Discussion of some basic concepts will be presented, but some prior knowledge and programming experience is recommended. ...
Page 86
Propeller Languages (Spin and Propeller Assembly) The Propeller chip is programmed using two languages designed specifically for it: 1) Spin, a high-level object-based language, and 2) Propeller Assembly, a low-level, highly-optimized assembly language. There are many hardware-based commands in Propeller ...
Page 87
By using existing objects, more sophisticated applications can be built very quickly. For instance, an application can include both the Keyboard and Mouse objects, and with just a few additional lines of code, a standard user interface is realized. Since ...
Page 88
Figure 3-2: Object Files consist of Spin, and possibly Propeller Assembly, and are stored as “.spin” files on your computer’s hard drive. Each object can be thought “building block” for an application. An object may choose to ...
Page 89
Object File and the other three objects are loaded and compiled with it resulting in a finished program called a Propeller Application, or “application” for short. Applications are formed from one or more objects. The application is really a specially ...
Page 90
Connect for Downloading In order to download a Propeller Application from the PC, you first need to connect the Propeller chip properly. • If you have a Propeller Demo Board (Rev C or D), it includes the Propeller chip and ...
Page 91
Propeller chip is powered and connected to the PC properly, you should see an “Information” dialog similar to Figure 3-6. Quick Review: Intro • The Propeller is programmed using two custom-designed languages: Spin and Propeller Assembly. o Spin is a ...
Page 92
Exercise 1: Output.spin – Our First Object The following is a simple object, written in Spin, that will toggle an I/O pin high and low repeatedly. Start the Propeller Tool software and enter this program into the editor. We’ll explain ...
Page 93
Downloading to RAM vs. EEPROM Before we explain the code, let’s take a closer look at the downloading process. Since our code was downloaded to RAM only, power cycling or resetting the Propeller will cause RAM contents to be lost ...
Page 94
Exercise 1: Output.spin Explanation Now for an explanation of the source code: PUB Toggle dira[16]~~ repeat !outa[16] waitcnt(3_000_000 + cnt) The first line, , declares that we’re creating a “public” method called “ PUB Toggle method is the object-oriented term ...
Page 95
System Counter, so this line means “wait for System Counter to equal 3 million plus its current value.” In this code example, we didn’t specify any clock settings for the Propeller chip ...
Page 96
Quick Review • Applications are downloaded to either Propeller RAM only or RAM and EEPROM. o Those in RAM will not survive power cycling or resetting the Propeller chip. o Those in EEPROM are loaded into RAM on ...
Page 97
Cogs (Processors) The Propeller has eight identical processors, called cogs. Each cog can be individually set to run or stop at any time as directed by the application it is running. Each cog can be programmed to run independent tasks ...
Page 98
Spin code, it continues to reside only in main memory while a cog running the Spin Interpreter (Cog 0 in this case) reads, interprets and effectively executes it. No other cogs were started during boot up or ...
Page 99
LED blink. Pin NOTE: you can try 18 through 23 as well, but on the Propeller Demo Board they are connected in pairs with resistors for ...
Page 100
PUB the order they are given in the list above. The very first block in the very first object (the Top Object File where compilation starts ...
Page 101
Toggles Pin with Delay clock cycles of high/low time.}} CON Pin = 16 Delay = 3_000_000 PUB Toggle ''Toggle Pin forever {Toggles I/O pin given by Pin and waits Delay system clock cycles in between each toggle.} dira[Pin]~~ repeat ...
Page 102
The following is what this looks like: Output.spin Toggles Pin with Delay clock cycles of high/low time. Object "Output" Interface: PUB Toggle Program: 8 Longs Variable: 0 Longs PUB Toggle Toggle ...
Page 103
Quick Review & 3 • The Propeller has eight identical processors, called cogs. o Any number of cogs can be running or halted at any time as directed by the application. o Each cog can run independent or ...
Page 104
Exercise 4: Output.spin – Parameters, Calls, and Finite Loops Our current object from Exercise 3 is interesting, but still isn’t very flexible; after all, the method only works with a specific pin and delay. Let’s make the Toggle more flexible ...
Page 105
The Toggle Method Let’s look closely at the Toggle immediately to the right of its name. This creates a “parameter list” for our Count) method consisting of three parameters, symbols that must be filled with values when the method is ...
Page 106
Propeller goes into a low-power mode until the next reset or power cycle. Don’t be confused by the look of the code. The two methods, right after another, but they are treated as distinct ...
Page 107
The VAR Block In the block we defined an array of longs, VAR used by the method. Main The Main Method We modified the method’s first line such that its original code, the call to Main encased in a command. ...
Page 108
Figure 3-10 illustrates this. The Propeller loads the Spin Interpreter into Cog 0 to execute the application (the two leftmost arrows in the figure). Then the application requests a new cog to activate, via the command, which causes the Propeller ...
Page 109
Quick Review & 5 • Spin language: o Methods: To call methods in the same object, use method where method is the method’s name, see Methods automatically exit, returning to their caller, when they run out of code ...
Page 110
Exercise 6: Output.spin & Blinker1.spin – Using Our Object Now let’s explore the power of objects. All of the preceding exercises created an application that contained only one object; the Output.spin object is the entire application. This is typical of ...
Page 111
The Start Method Here we replaced the method with a Main cog to run the method independently and passes along the Toggle parameters. The interface to an object is made up of its public ( has two interface components, the ...
Page 112
OBJ method. This is called an Object-Method reference. Blinker1 refers to the Output object calls Output’s LED LED.Start method. When Blinker1 is compiled, since it references Output, the two objects ...
Page 113
The Object View updates itself each time an application is successfully compiled to show you the logical structure of that application. The view shown in Figure 3-12 is the Object View’s way of illustrating the logical structure in Figure 3-11. ...
Page 114
Each menu, Compile Current and Compile Top, has the same sub-options but they start their compilation from different places. Compile Current starts from the active edit tab and Compile Top starts from the designated Top Object File. You can tell ...
Page 115
Figure 3-14: Setting Blinker1 to be the Top Object File a. b. Which Objects Were Compiled? If there’s ever a question of which object files were compiled in the last successful compile operation, use the mouse to explore the resulting ...
Page 116
Quick Review • Spin language: o Methods: To call methods in anoTher object, use object . method where object is the object’s symbolic name (given the method is the method’s name within that other object. ...
Page 117
Objects vs. Cogs It’s important to understand that there is no direct relationship between objects and cogs. Remember, Exercise 5 used just one object but two cogs and Exercise 6 used two objects and two cogs, but each of these ...
Page 118
Output.spin }} VAR long Stack[9] byte Cog PUB Start(Pin, Delay, Count): Success {{Start new blinking process in new cog; return TRUE if successful}} Stop Success := (Cog := cognew(Toggle(Pin, Delay, Count), @Stack PUB Stop {{Stop toggling process, ...
Page 119
The VAR Block In the block we’ve added a byte-sized variable, VAR the ID of the cog started by the Start to the object; they can be used within any modified by one method, other methods will see the new ...
Page 120
Boolean return value? A Boolean result of Start numerical value 0 and is -1, but Boolean comparisons treat zero (0) as TRUE non-zero value (≠ This is very convenient and is the reason we added ...
Page 121
The Stop Method Our method needs to stop the cog that was started by Stop conditional structure meaning “if the Cog variable is block. ” Remember, was set cog was started, and set to 1 through ...
Page 122
... Once again, since the result, -1, is non-zero ( Count would execute again. So, if started out as 0, the loop iterates endlessly! If Count it loops only that number of times! Page 122 · Propeller Manual v1 The repeat..while . This is another form of REPEAT (ie: non-zero). This condition is another compound ‘ ...
Page 123
Quick Review • Objects: o Have no direct relationship with cogs. o Should call interface methods “Start” and “Stop” if they affect other cogs. o Should call interface method “Init” needs initialization. • Spin language: o ...
Page 124
Exercise 8: Blinker2.spin – Many Objects, Many Cogs Now let’s make a new object that takes advantage of the enhancements to Output to use many cogs for many parallel processes. Here’s the code: Example Object: Blinker2.spin {{ Blinker2.spin }} CON ...
Page 125
Compile and download Blinker2. You should see six LEDs start blinking with different, independent, rates and periods. Look carefully, after about 8 seconds P20 will stop blinking and P22 will start. A few seconds later, P18 will stop and P23 ...
Page 126
This means the I/O pin 16 endlessly, suddenly has its toggling P16 to immediately stop and start again but with P20 instead. The final line only there to keep the ...
Page 127
MAXLEDS of the available object. That value is used by Behind the Scenes In the object block, we created an array of six Output objects. Each object that an application uses ...
Page 128
Object Info Window We can see this effect using the Propeller Tool’s Object Info feature. First, change the object block in Blinker2 to specify only one instance of the Output object; Don’t run the code this way, it will not ...
Page 129
The top part of the window is the Info Object View similar to the Object View. The center part of the window shows the application’s RAM Usage. Notice that the “Program” (the compiled source code) itself consumes 68 ...
Page 130
This means that every instance of an object that is, or may be, required must be declared at compile time in the block, just as we did in Exercise 8 with the array of Output objects. OBJ Quick Review: Ex ...
Page 131
Exercise 9: Clock Settings The Propeller chip’s internal clock has two speeds, slow (≈ 20 KHz) and fast (≈ 12 MHz). Since we never specified any clock settings for our application, all previous exercises used the Propeller chip’s default, internal ...
Page 132
Modify your code to match the following: {{ Blinker2.spin }} CON _CLKMODE = RCSLOW _CLKMODE = XTAL1 _XINFREQ = 5_000_000 MAXLEDS = 6 <remaining code unchanged> Here we set to _CLKMODE XTAL1 crystal and configures the Propeller internal oscillator gain ...
Page 133
Blinker2.spin }} CON _CLKMODE = XTAL1 + PLL4X _XINFREQ = 5_000_000 MAXLEDS = 6 <remaining code unchanged> Here we changed the setting slightly by adding the _CLKMODE the clock mode to use the internal phase-locked loop (PLL) to wind ...
Page 134
Example Object: Output.spin {{ Output.spin }} VAR long Stack[9] byte Cog PUB Start(Pin, DelayMS, Count): Success {{Start new blinking process in new cog; return True if successful.}} Stop Success := (Cog := cognew(Toggle(Pin, DelayMS, Count), @Stack PUB Stop ...
Page 135
We modified the and Start Toggle meaning “delay in units of milliseconds.” Then we modified the that instead of waiting a fixed number of clock cycles, it calculates the number of clock cycles that there are in DelayMS current System ...
Page 136
Example Object: Blinker2.spin {{ Blinker2.spin }} CON _CLKMODE = XTAL1 + PLL4X _XINFREQ = 5_000_000 MAXLEDS = 6 OBJ LED[6] : "Output" PUB Main {Toggle pins at different rates, simultaneously} dira[16..23]~~ LED[NextObject].Start(16, 250, LED[NextObject].Start(17, 500, LED[NextObject].Start(18, 50, 300) LED[NextObject].Start(19, 500, ...
Page 137
adjusted the second parameter of the all the calls to Main cycles” to “delay in milliseconds.” Compile and download the Blinker2 object now. Notice that the rate at which each LED blinks is the same as it ...
Page 138
Exercise 11: Library Objects The Propeller Tool comes with a library of objects created by Parallax engineers. These objects perform many useful functions such as serial communication, floating-point math, number-to-string and string-to-number conversion, and TV display generation, using standard PC-style ...
Page 139
Example Object: Display.spin {{ Display.spin }} CON _clkmode = xtal1 + pll16x _xinfreq = 5_000_000 OBJ Num : "Numbers" "TV_Terminal" PUB Main | Temp Num.Init TV.Start(12) Temp := 900 * 45 + 401 TV.Str(string("900 * 45 + 401 ...
Page 140
In hexadecimal it's = $9FC5 Counting by fives: 5, 10, 15, 20, 25, 30 Look at what we just achieved! Using just a few lines of our own code plus two existing library ...
Page 141
So the line TV.Str(string("900 * 45 + 401 = ")) * 45 + 401 = ” displayed on the TV. The next statement, TV.Str(Num.ToStr(Temp, Num#DDEC)) The method converts the numeric value in Num.ToStr decimal format and ...
Page 142
... You can find out the location of each object, and the work and library folders, by pointing the mouse at each object in the Object View. In the figures below we see that Display is in C:\Source (the “work” folder) and Numbers is in C:\Program Files\Parallax Inc\Propeller Tool (the “library” folder). ...
Page 143
Exercise 12: Whole and Real Numbers The Propeller is a 32-bit device and can naturally handle whole numbers as signed integers (-2,147,483,648 to 2,147,483,647) both in constants or in run-time math expressions. However, for real numbers (those with both integer ...
Page 144
Floating-Point Numbers In many cases, expressions involving real numbers can be solved without using floating-point values and methods, such as with the pseudo-real number technique. Since solutions like the one above tend to execute much faster and consume less memory, ...
Page 145
Example Object: RealNumbers.spin {{ RealNumbers.spin}} CON _clkmode = xtal1 + pll16x _xinfreq = 5_000_000 iB = 760 iC = 3875 iD = 1250 38. 12 100.0 OBJ Term : "TV_Terminal" F ...
Page 146
Compile and download RealNumbers.spin. It will display the following display: Pseudo-Real Number Result: 2356 Floating-Point Number Result: 23.56 Another Pseudo-Real Number Result: 2356 The pseudo-real results, of course, each represent the value 23.56 but the entire value ...
Page 147
Context-Sensitive Compile Information After an object has been compiled, the Propeller Tool displays context-sensitive compile information on the status bar (panel 5) about the source item the cursor is currently near or within. This is very useful in verifying and ...
Page 148
Quick Review & 12 • Propeller Library folder automatically created by the Propeller Tool installer. o Contains Parallax-made Propeller objects that perform useful functions. o The “Propeller Library” item in the Recent Folders list allows ...
Page 149
Chapter 4: Spin Language Reference This chapter describes all elements of the Propeller chip’s Spin language and is best used as a reference for individual elements of the Spin language. For a general tutorial of the use of the Spin ...
Page 150
Structure of Propeller Objects Each Propeller object has an inherent structure consisting six different special- purpose blocks CON VAR OBJ PUB that they typically appear in objects) along with the set of elements usable ...
Page 151
PUB/PRI: Public and Private method blocks define Spin routines ABORT FLOAT p 161 BYTE FRQA p 165 BYTEFILL FRQB p 169 BYTEMOVE IF p 170 CASE IFNOT p 171 CHIPVER INA p 174 CLKFREQ INB p 175 CLKMODE LOCKCLR p ...
Page 152
Categorical Listing of Propeller Spin Language Elements marked with a superscript “a” are also available in Propeller Assembly. Block Designators CON Declare constant block; p 194. VAR Declare variable block; p 315. OBJ Declare object reference block; p 247. PUB ...
Page 153
PLL8X Constant for PLL16X Constant for Cog Control a COGID Current cog’s ID (0-7); p 186. COGNEW Start the next available cog; p 189. a COGINIT Start, or restart, a cog by ID; p 187. a COGSTOP Stop a cog ...
Page 154
REPEAT Execute block of code repetitively an infinite or finite number of times with optional loop counter, intervals, exit and continue conditions; p ...FROM 293. ...TO ...STEP ...UNTIL ...WHILE NEXT Skip rest of QUIT Exit from REPEAT RETURN Exit / ...
Page 155
Directives STRING Declare in-line string expression; resolved at compile time; p 310. CONSTANT Declare in-line constant expression; resolved at compile time; p 200. FLOAT Declare floating-point expression; resolved at compile time; p 216. ROUND Round compile-time floating-point expression to integer; ...
Page 156
Constants a TRUE Logical true: -1 ($FFFFFFFF); p 202. a FALSE Logical false: 0 ($00000000 202. a POSX Maximum positive integer: 2,147,483,647 ($7FFFFFFF); p 202. a NEGX Maximum negative integer: -2,147,483,648 ($80000000); p 202 Floating-point value ...
Page 157
Binary Operators NOTE: All right-column operators are assignment operators. = --and-- = Constant assignment ( := --and-- := Variable assignment ( + += --or-- Add; p 255. - --or-- -= Subtract; p 256. * --or-- *= Multiply and return lower ...
Page 158
Syntax Symbols % Binary number indicator Quaternary number indicator Hexadecimal number indicator, as " String designator _ Group delimiter in constant values, or underscore in symbols; p 312. # Object-Constant reference: . Object-Method reference: ...
Page 159
Spin Language Elements The remainder of this chapter describes the elements of the Spin Language, shown above, in alphabetical order. A few elements are explained within the context of others for clarity; use the page references from the categorical listing, ...
Page 160
Syntax Definitions In addition to detailed descriptions, the following pages contain syntax definitions for many elements that describe, in short terms, all the options of that element. The syntax definitions use special symbols to indicate when and how certain element ...
Page 161
ABORT Exit from / method using abort status with optional return Value. PUB PRI ((PUB ┆ PRI)) ABORT 〈 〉 Value Returns: Either the current RESULT • optional expression whose value returned, with abort status, ...
Page 162
Spin Language Reference and more methods are returned from (via call stack gets shorter. This is called “pushing” onto the stack and “popping” off of the stack, respectively. The command pops the most recent data off the call stack ...
Page 163
The type of exit that actually used, MayAbort the trapping call; it may have just happened to be the destination of a Therefore, the code must be written in a way to detect which type was used. possibilities are: 1) ...
Page 164
Spin Language Reference <more code> The above example shows three methods of various logical levels, (“mid-level”) and DriveMotors maker of the application; deciding how to respond to events like sensor activations and motor movements. The mid-level method, distance. The ...
Page 165
BYTE Declare byte-sized symbol, byte aligned/sized data, or read/write a byte of main memory. VAR 〈 〉 BYTE Symbol [Count] DAT BYTE Data ((PUB ┆ PRI)) 〈 BYTE [BaseAddress] [Offset] ((PUB ┆ PRI)) .BYTE 〈 〉 Symbol [Offset] • Symbol ...
Page 166
Spin Language Reference Byte Variable Declaration (Syntax 1) In blocks, syntax 1 of VAR BYTE byte-sized, or are any array of bytes. For example: VAR byte Temp byte Str[25] The above example declares two variables (symbols), byte-sized variable. The ...
Page 167
For more information about using BYTE to the section’s Declaring Data (Syntax 1) on page 208, and keep in mind that DAT used for the Size field in that description. Reading/Writing Bytes of Main ...
Page 168
Spin Language Reference This example works just like the previous, except that we use the byte of main memory from the address of With a similar syntax, bytes of main memory can be written to as well, as long ...
Page 169
BYTEFILL Fill bytes of main memory with a value. ((PUB ┆ PRI)) BYTEFILL (StartAddress, Value, Count ) • StartAddress is an expression indicating the location of the first byte of memory to fill with Value. • Value is an expression ...
Page 170
Spin Language Reference BYTEMOVE Copy bytes from one region to another in main memory. ((PUB ┆ PRI)) BYTEMOVE (DestAddress, SrcAddress, Count ) • DestAddress is an expression specifying the main memory location to copy the first byte of source ...
Page 171
CASE Compare expression against matching expression(s) and execute code block if match found. ((PUB ┆ PRI)) CASE CaseExpression MatchExpression : Statement(s) 〈 MatchExpression : 〉 Statement(s) 〈 OTHER : 〉 Statement(s) • CaseExpression is the expression to compare. • is ...
Page 172
Spin Language Reference you can press Ctrl + I to turn on block-group indicators. Pressing Ctrl + I again will disable that feature. See Indenting and Outdenting, page 69, and Block-Group Indicators, page 74. Using CASE is handy where ...
Page 173
This means that if we had rearranged the 25 and 20..30 lines, so that the range of 20..30 is checked first, we’d ...
Page 174
Spin Language Reference CHIPVER Get the Propeller chip’s version number. ((PUB ┆ PRI)) CHIPVER Returns: Version number of the Propeller chip. Explanation The command reads and returns the version number of the Propeller chip. For CHIPVER example ...
Page 175
CLKFREQ Current System Clock frequency; the frequency at which each cog is running. ((PUB ┆ PRI)) CLKFREQ Returns: Current System Clock frequency, in Hz. Explanation The value returned by CLKFREQ current clock mode (oscillator type, gain, and PLL settings) and ...
Page 176
Spin Language Reference CLKFREQ vs. _CLKFREQ is related to, but not the same as, CLKFREQ current System Clock frequency whereas contains the application’s System Clock frequency at startup. In other words, current clock frequency and _CLKFREQ to be the ...
Page 177
Pre-defined, one-time settable constant for specifying the System Clock frequency. CON _CLKFREQ = Expression • integer expression that indicates the System Clock frequency upon Expression application start-up. Explanation specifies the System Clock frequency for start-up ...
Page 178
Spin Language Reference CON _CLKMODE = XTAL2 _CLKFREQ = 10_000_000 These two declarations set the clock mode for an external medium-speed crystal, no Clock PLL multiplier, and a System Clock frequency of 10 MHz. automatically set to 10 MHz, ...
Page 179
CLKMODE Current clock mode setting. ((PUB ┆ PRI)) CLKMODE Returns: Current clock mode. Explanation The clock mode setting is the byte-sized value, determined by the application at compile time, from the CLK register. See CLK Register, page 28, for explanation ...
Page 180
Spin Language Reference _CLKMODE Pre-defined, one-time settable constant for specifying application-level clock mode settings. CON _CLKMODE = Expression • integer expression made up of one or two Clock Mode Setting Expression Constants shown in table Table 4-3. ...
Page 181
Table 4-4: Valid Clock Mode Expressions and CLK Register Values Valid Expression CLK Register Value RCFAST 0_0_0_00_000 RCSLOW 0_0_0_00_001 XINPUT 0_0_0_00_010 XTAL1 0_0_1_01_010 XTAL2 0_0_1_10_010 XTAL3 0_0_1_11_010 XINPUT + PLL1X 0_1_1_00_011 XINPUT + PLL2X 0_1_1_00_100 XINPUT + PLL4X 0_1_1_00_101 XINPUT ...
Page 182
Spin Language Reference multiplied by 16 (the Clock PLL always multiplies by 16) but the 8x result would be used; the System Clock would be 4 MHz * MHz. CON _CLKMODE = XINPUT + PLL2X This ...
Page 183
CLKSET Set both the clock mode and System Clock frequency at run time. ((PUB ┆ PRI)) CLKSET (Mode, Frequency) • Mode is an integer expression that will be written to the CLK register to change the clock mode. • Frequency ...
Page 184
Spin Language Reference CNT System Counter register. ((PUB ┆ PRI)) CNT Returns: Current 32-bit System Counter value. Explanation The register contains the current value in the global 32-bit System Counter. The System CNT Counter serves as the central time ...
Page 185
Here, I/O pin 0 is set to output. Then the local variable System Clock frequency divided by 1000; i.e.: the number of System Clock cycles per 1 millisecond of time. Next, the local variable value. Finally, the last two lines ...
Page 186
Spin Language Reference COGID Current cog’s ID number (0-7). ((PUB ┆ PRI)) COGID Returns: The current cog’s ID (0-7). Explanation The value returned by is the ID of the cog that executed the command. Normally, the COGID actual cog ...
Page 187
COGINIT Start or restart a cog run the Spin code or Propeller Assembly code. ((PUB ┆ PRI)) COGINIT (CogID, SpinMethod ((PUB ┆ PRI)) COGINIT (CogID, AsmAddress, Parameter ) • is the ID (0 – the ...
Page 188
Spin Language Reference This example launches the Square and the address of as SqStack information. Propeller Assembly Code (Syntax 2) To run Propeller Assembly code in a specific cog, the the address of the assembly routine, and a value ...
Page 189
COGNEW Start the next available cog to run Spin code or Propeller Assembly code. ((PUB ┆ PRI)) 〈 COGNEW (SpinMethod (ParameterList) ((PUB ┆ PRI)) COGNEW (AsmAddress, Parameter ) Returns: The ID of the newly started cog (0-7) if successful, or ...
Page 190
Spin Language Reference Spin Code (Syntax 1) To run a Spin method in another cog, the parameters, and a pointer to some stack space. For example: VAR long SqStack[6] PUB Main | cognew(Square(@X), @SqStack) 'Launch ...
Page 191
Spin object, they are running independently. The “ ” line can be replaced with code that uses the value of here> Propeller Assembly Code (Syntax 2) To run Propeller Assembly code in another cog, the ...
Page 192
Spin Language Reference Later, if the method is called, it first checks the condition, “ Stop true only if is non-zero. If true (i.e.: a cog was successfully started by the Cog then the following line, “ cogstop(Cog~ - ...
Page 193
COGSTOP Stop cog by its ID. ((PUB ┆ PRI)) COGSTOP (CogID ) • CogID is the ID (0 – the cog to stop. Explanation stops a cog whose ID is CogID and places that cog into a dormant ...
Page 194
Spin Language Reference CON Declare a Constant Block. CON 〈 Symbol = Expression (( ,┆ )) Symbol = Expression CON 〈 #Expression (( ,┆ )) Symbol CON 〈 〉 Symbol (( ,┆ )) Symbol … • is the desired ...
Page 195
Example: CON Delay = 500 Baud = 9600 AChar = "A" —or— CON Delay = 500, Baud = 9600, AChar = "A" Both of these examples create a symbol called that is equal to 9600, and a symbol called Baud ...
Page 196
Spin Language Reference The following are examples of valid constants: floating-point value 0.5 floating-point value 1.0 floating-point value 3.14 floating-point value 1e16 floating-point value 51.025e5 integer expression floating-point expression 3.0 + 4.0 invalid expression; causes compile ...
Page 197
Enumerations (Syntax 2 and 3) Constant Blocks can also declare enumerated constant symbols. Enumerations are logically grouped symbols which have incrementing integer constant values assigned to them that are each unique for the group. For example, an object may have ...
Page 198
Spin Language Reference Using the example above, the methods that use them can do things like the following (assume is a symbol set by a calling object): Mode case Mode RunTest : <test code here> RunVerbose : <verbose code ...
Page 199
Here, and are 1 and 2, respectively, and RunTest RunVerbose 6, respectively. While this feature may be handy, to maintain good programming practices it should only be used in rare cases. Syntax variation of the enumeration syntax. ...
Page 200
Spin Language Reference CONSTANT Declare in-line constant expression to be completely resolved at compile time. ((PUB ┆ PRI)) CONSTANT (ConstantExpression ) Returns: Resolved value of constant expression. • is the desired constant expression. ConstantExpression Explanation The block may be ...