QuickStart 3: Introduction to Spin Objects

The Propeller really shines when it comes to its ability to easy interact with peripheral devices.  The multi-cog design of the Propeller allows it almost unlimited compatibility using software “Objects” which perform the communication tasks in the background, leaving your programs uninterrupted.

Historically, microcontrollers could only perform a single task at a time, requiring the processor to be “interrupted” momentarily to communicate with outside devices.  The Propeller allows the program to launch additional code to run in parallel and then continue.  For example, interfacing a keyboard is as simple as starting the established keyboard object code at the beginning of the program, launching it into a separate cog.    The first cog in which the main program is running is unaffected by the keyboard running in the next cog.  Data can be requested from the keyboard object anytime it is needed without stopping the main program.

Supporting objects like the one described in the example are made up of Spin and/or Propeller Assembly code.   Many objects contain code which starts them running on an independent cog, but that is not always the case.  Sometimes supporting objects are simply additional methods which might be used in frequent programs thus making it handy to keep them in a separate file instead of placing the methods in the main program.

Objects can be obtained from several sources.   Installation of the Parallax Propeller Tool includes many commonly used objects created by Parallax.   Hundreds of user-contributed objects can be found in the Object Exchange Library (OBEX)[1].  Additionally, Parallax has created the “Object Gold Standard” library which can be downloaded from Parallax Semiconductor.   Gold Standard objects must meet strict standards for guaranteed reliability.

Because Propeller objects are simply software, they ensure continued compatibility.  As  new components and devices are manufactured, additional support is readily available with new objects to support them.   They also reduce development time by preventing the requirement of re-inventing the wheel each time a supported component or device is used.

In QuickStart Lesson 1, a few lines of simple code were used to flash an LED.  With the addition of an object containing a few LED methods, we can add a level of sophistication quickly and easily.

CON

  _clkmode = xtal1 + pll16x         'Establish speed
  _xinfreq = 5_000_000              '80Mhz

OBJ

  led: "E555_LEDEngine.spin"        'Include LED methods object

VAR

  byte Counter                      'Establish Counter Variable

PUB Main                            'Method declaration 

  repeat Counter from 0 to 100      'Repeat loop Counter
    led.LEDBrightness(Counter, 16)  'Adjust LED brightness
    waitcnt(clkfreq/50 + cnt)       'Wait a moment

The OBJ block includes the E555_LEDEngine object and is given the nickname of “led” including all of its methods in our code. 

The VAR block declares a byte variable Counter.   By including it in the VAR block its information can be accessed by any method in the code.

The PUB Main block starts a repeat loop, counting from 0 to 100.  Each time the loop is made, the Counter variable is increased by one.  The method LEDBrightness is called each time sending the brightness level of Counter to the LED on P16 of the Propeller chip’s I/O.   A small delay has been added to end of the loop to slow things down.

In this example, the LED methods are very simple and do not require a separate cog.

Consider the following example:

CON

  _clkmode = xtal1 + pll16x           'Establish speed   
  _xinfreq = 5_000_000                '80Mhz             

OBJ

   pst : "Parallax Serial Terminal"
   

PUB Hello                             ' Method declaration 
    pst.start(115200)                 ' Start PST on another cog.  

    repeat                            ' Endless loop prevents
                                      ' program from ending.

        pst.str(string("HELLO "))     ' Send "HELLO " to PST
        waitcnt(clkfreq/50 + cnt)     ' Wait a moment
        

The OBJ block includes the Parallax Serial Terminal object and gives it the prefix name of “pst” to access its methods in our code.

The PUB Hello block starts the PST object on another cog, passing it the baud rate setting of 115,200.   A repeat loop is started and the word HELLO is transmitted to PST until the program or Propeller is stopped.   Again, a small delay has been added to give the humans a better chance to see what is happening.

As a general rule, the presence of a mandatory “start” method is a pretty good indicator that the object is operating in a separate cog.   Each object is a single file; however, objects may call on additional “child objects,” other files, sometimes even launching those additional code pieces into additional cogs.   As long as your objects (and all of their required child objects) are locatable by the development tool at compile time, Propeller Application will compile.