This is a sample application for Tollos, with explanatory notes. The sample is included in the Tollos download, so you do not need to cut and paste the pieces from this page. It has been tested with the mbed development board, although it has no specific board or processor dependencies.

The sample is a single program (sample.c), all of which is shown here, with notes interspersed. It is assumed that you are familiar with the C language.

Include file

  /* --------------------------------------------------------------- */
  /* sample.c -- Tollos sample application                           */
  /* --------------------------------------------------------------- */

  #include "tollos.h"           // Tollos library

This sample only uses the board-independent functions that Tollos provides, so it only needs to include the tollos.h file. This, by definition, exposes no board- or device-specific interfaces, so if you want to access those you would add includes (for example, LPC17xx.h to access the vendor-provided functions for the LPC 1768 microcontroller used on the mbed board).

Initialization function

  /* --------------------------------------------------------------- */
  /* init -- initialization function                                 */
  /*                                                                 */
  /* This is called once, after C and processor initialization.      */
  /* Return 0 to start tick() calls, or 1 to halt (power down).      */
  /* --------------------------------------------------------------- */
  int init(void) {

No parameter is passed to init(). It should normally return 0; however if 1 is returned then the processor will be powered down (and the tick() function will not be called).

    // Send a string to the host computer terminal
    debugf("%s; sample compiled on %s at %s\n", TOLLOS_VERSION,
           __DATE__, __TIME__);

These lines send a character string to a debug terminal (if available). See the Getting Started page for details on how to set this up. The debugf function is a subset of the C printf function; for details of what formatting is supported, see the function description. The string displayed should be similar to this: tollos 1.06; sample compiled on Nov 19 2010 at 10:23:40

    // blink LED4 (if any) for a second
    ledSet(4, LED_INVERT);
    sysPause(1000);             // wait 1000 ms
    ledSet(4, LED_INVERT);

These lines invert the state of LED4, leave it that way for a second, then switch it back. The ledSet function is part of the tollosLED module, and sysPause is part of the tollos core module.

    // Request that the watchdog timer reset the processor if a
    // tick() call takes more than 2 seconds
    sysSet(SYS_WATCHDOG, 2000);

This call demonstrates how to use the processor watchdog timer. Once set, it cannot be disabled (although you can change the time interval); if any call to tick() takes longer than the set time then the processor will be reset. This acts as a protection in case some call to tick() has a problem (perhaps goes into a loop unexpectedly).

The sysSet function can be used to set a number of parameters, and is described here.

    return 0;
    } // init

This returns to the Tollos supervisor; the return code of 0 indicates normal completion and that Tollos should now begin calling the tick() function. The init() function also has the option of never returning to Tollos, or of returning 1 which will power down the processor.

The tick function

  /* --------------------------------------------------------------- */
  /* tick -- repeating tick function                                 */
  /*                                                                 */
  /* This is called once a tick (default 25 Hz) after init() ends.   */
  /* Return 0 to continue tick() calls, or 1 to halt (power down).   */
  /* --------------------------------------------------------------- */
  int tick(void) {
    static int ticks=0;         // counter
    int c;                      // work

The two variables here are a counter (static, so it will persist between calls to tick()) and a work variable. Note that c is an int because −1 is a possible return value from debugGet().

    // Change a LED state every second
    ticks++;                    // bump counter
    if (ticks==25) {            // every second ..
      ledSet(1, LED_INVERT);    // .. invert LED1
      ticks=0;                  // .. and reset counter
      }

These lines first increment the counter; then on every twenty-fifth tick LED1 is inverted and the counter is reset.

    // Flip Port 1 bit 31 every tick [to watch on a 'scope]
    // On the mbed this is pin 20
    bitSet(PORT1, BIT31, BIT_INVERT);

This inverts a digital output on every tick (the bit is automatically set to output mode when it is set on, off, or is inverted). On the mbed board this output is connected to pin 20, so an oscilloscope connected between that pin and ground (pin 1) should show a square ware with a period of 80 ms.

See the tollosBit module description for more details.

    // check the serial input
    c=debugGet();
    if       (c=='1') ledSet(1, LED_INVERT);
     else if (c=='2') ledSet(2, LED_INVERT);
     else if (c=='3') ledSet(3, LED_INVERT);
     else if (c=='4') ledSet(4, LED_INVERT);
     else if (c=='x') return 1;                     // power off
     else if (c=='?') {                             // do some queries
      debugf("SysTickTime   %d\n", sysQuery(SYS_TICKTIME));
      debugf("SysTickMax    %d\n", sysQuery(SYS_TICKMAX));
      debugf("SysStackUsed  %d\n", sysQuery(SYS_STACKUSED));
      debugf("SysWatchdog   %d\n", sysQuery(SYS_WATCHDOG));
      }
     // other characters (and -1) are ignored

The debugGet function reads a character from the debug terminal. It does not block; that is, if no character has been typed at the terminal it will return immediately with the value −1 being returned. Since it does not block it can be used safely in the tick() function as it will not prevent tick() returning in time.

In this sample, each character is treated as a one-character ‘command’. The characters 1 through 4 invert the appropriate LED. ‘x’ (for ‘eXit’) powers off the device by returning from tick() with the value 1. ‘?’ displays some of the values available by calling sysQuery (for example, if this is invoked twice the SysTickMax value will increase, showing how long it took to send the four lines to the debug terminal).

To check that the watchdog works you could add another command that simply went into a never-ending loop; this would then cause the processor to be reset after the interval set in the init() function.

    return 0;
    } // tick

This is the normal return from tick().

This page was last updated on 2010-12-03 by mfc.