You are here: Spin Programming Tutorial > Spin Lesson 9 > A Library Object for TV

A Library Object for TV

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 keyboards, mice and monitors, etc.

This lesson uses two Propeller Library objects, Numbers and TV_Terminal, to convert numeric values to strings and display them on a TV.

The Propeller Object Library is simply a folder containing Propeller object files that are automatically created during the Propeller Tool software installation.  You can get to the Propeller Library folder by selecting “Propeller Library” from the Recent Folders list.  After selecting the Propeller Library, the Files List will display all the available objects.

Propeller Library Browsing

 

Spin Exercise 9-1: Creating a Top Object "Display.spin"

{{ Display.spin }}

CON
  _clkmode = xtal1 + pll16x
  _xinfreq = 5_000_000

OBJ
  Num   :       "Numbers"
  TV    :       "TV_Terminal"
  
PUB Main | Temp                   
  Num.Init                                    'Initialize Numbers   
  TV.Start(12)                                'Start TV Terminal    
                                                                              
  Temp := 900 * 45 + 401                      'Evaluate expression  
  TV.Str(string("900 * 45 + 401 = "))         'then display it and  
  TV.Str(Num.ToStr(Temp, Num#DDEC))           'its result in decimal
  TV.Out(13)                                                                  
  TV.Str(string("In hexadecimal it's  = "))   'and in hexadecimal   
  TV.Str(Num.ToStr(Temp, Num#IHEX))                                           
  TV.Out(13)                                                                  
  TV.Out(13)                                                                  
                                                                              
  TV.Str(string("Counting by fives:"))        'Now count by fives   
  TV.Out(13)
  repeat Temp from 5 to 30 step 5
    TV.Str(Num.ToStr(Temp, Num#DEC))
    if Temp < 30
      TV.Out(",")

 

900 * 45 + 401 = 40,901
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 objects and three resistors (on the Propeller Demo Board) we converted numeric values to text strings and generated a TV-compatible signal to display that text in real time on a standard TV!  In fact, while you are reading this, a cog is keeping busy constantly generating an NTSC signal at 60 frames per second that the TV can lock onto.

The TV_Terminal object provides a great display for debugging purposes.  Since the Propeller has many processors and can run quite fast, a real-time display such as a TV monitor (CRT or LCD) used for debugging purposes goes a long way toward developing optimal source code.  We recommend using this technique along with the usual debugging techniques to speed up development time.

Let’s look at some important parts of our code now.  The first new item in our code is the | Temp that appears in Main’s declaration line.  Don't be fooled, this may look like a return variable declaration, but it is not.  The pipe symbol ‘|’ indicates we are declaring local variables next.  So, | Temp declares that Temp is a long-sized local variable for Main

Next we have two very important statements, Num.Init and TV.Start(12).  These two statements initialize the Numbers object and start the TV_Terminal object (on pins 12, 13 and 14), respectively.  Each of these objects requires some kind of initialization before using it.  Numbers requires that its Init method is called to initialize some internal registers.  TV_Terminal requires that its Start method is called to configure the proper output pins and to start two more cogs to generate the display signals.  Objects typically indicate these requirements in their documentation, but it is common that they include an Init or a Start method if they require some initial setup before use.

The next line performs some arithmetic and sets our local variable, Temp, to the result.  We'll use this result soon.

The next three statements create the first line of text on the TV display:  9 * 45 + 401 = 40,901.  The TV.Str method outputs a zero-terminated string to the display.  Its parameter, string("900 * 45 + 401 = ") is new to us.  STRING is a directive that creates a zero-terminated string of characters (multiple bytes of character data followed by a zero; sometimes called a z-string) and returns the address of that string.  Most methods that deal with strings require just the address of the starting character and for the string to end with a byte equal to zero.  TV.Str method’s parameter requires exactly that, the address of a zero-terminated string.  So the line TV.Str(string("900 * 45 + 401 = ")) causes the string “900 * 45 + 401 =” to be displayed on the TV.

The next statement, TV.Str(Num.ToStr(Temp, NumxxDDEC)) prints the “40,901” part of the line.  The Num.ToStr method converts the numeric value in Temp into a string using delimited decimal format and returns the address of that string.  Temp, of course, holds the long-sized result of our earlier expression: 40901.  The Num#DDEC part is new to us, however.  The # symbol when used this way is an Object-Constant reference; it is used to reference a constant that was defined in another object.  In this case, Num#DDEC refers to the “format constant” DDEC that is declared within the Numbers object.  As defined by Numbers, DDEC stands for Delimited Decimal and holds a value that indicates to the ToStr method that it should format the number with a thousands-group delimiter; a comma in this case.  So, ToStr creates a z-string equal to “40,901” and returns the address of it.  TV.Str then outputs that string onto the display.  Read the documentation in the Numbers object for more information about this and other format constants.

TV.Out(13) outputs a single byte, 13, to the display.  The 13 is the ASCII code for a carriage return (a non-visible character) and causes the TV_Terminal object to move to the next text line.  We do this in preparation for the next string we'll print afterward.

Propeller Help Version 1.1

Copyright © Parallax Inc.

5/13/2009