Core Library

The Pollen cloud bundles contain definitions of fundamental and useful types for embedded programming, as well as some implementations for specific targets.

These bundles can be used as is in the cloud, or they can be downloaded, modified, and used locally. They also provide examples of Pollen code.

One useful bundle in the cloud is pollen-core. Here is an an overview of the packages in that Pollen cloud bundle, followed by a discussion of how to use events and timers.

How to Use Events

In package pollen.event there are four types which support the event subsystem: Event, Newsroom, HandlerProtocol, and EventQueue.

• Event. Applications that use events will use this class. Code to create, post, and fire events is here. The event handler is initialized in the constructor and you can also call a function to set the handler after construction.

• Newsroom. The Newsroom class handles administration and registration of events. The event subsystem runs in a loop and it is necessary to call Newsroom.run() to start that loop but otherwise calls to Newsroom are usually not necessary in client code.

• HandlerProtocol. This protocol defines a signature for handlers used by events.

• EventQueue. Used by Newsroom.

The timer subsystem creates events in a manner similar to the way a typical Pollen application would; it is the Timer class which creates and initializes an event. It is the timer clients who start the event subsystem by calling Newsroom.run(). We highlight this call in our TimerBlink example below.

import pollen.environment as Env
from Env import Led

from pollen.time import Timer

module TimerBlink {

  host new Timer t1(tick)    

  tick() {
    Led.toggle()
  }

  pollen.run() {
    t1.start(500, true)      
    Env.Newsroom.run()      // start the event subsystem
  }
}

Newsroom provides support for a simple loop dispatcher where queued events are dispatched in FIFO order. The loop runs indefinitely. Each event handler runs to completion. This loop is initiated by the call to run(). This simple approach is suitable to many embedded applications which run with extremely tight memory and time constraints and cannot host even a scaled down microkernel RTOS. It is also more deterministic than dispatchers that use priority and that is important in saftey critical applications. This approach conforms to a pattern common to embedded applications and Pollen provides support for it in package pollen.event. Of course you can use Pollen with other approaches.

The Timer class encapsulates the timer event. To show an Event example we extract the code in the Timer class which uses the event subsystem.

from pollen.event import HandlerProtocol as HP  // import the HandlerProtocol
from pollen.event import Event                  // import the Event class
import TimerManager

class Timer {  

  host Event tickEvent                          // declare an Event
  bool active = false
  bool periodic = false
  uint16 duration = 0
  uint16 tickCount = 0
  // ...
  public host Timer(HP.handler h) {   
    tickEvent = new Event(h)                    // initialize an Event with a handler
    TimerManager.registerTimerOnHost(@)
  }  
  // ...
  public fire() {
    tickEvent.fire()                            // fire the event 
  }
  // ...
  public tick() {
    if (@active) {
      @tickCount++
      if (@tickCount == @duration) {
        @tickEvent.post()                       // post the Event.
        if (@periodic) {
          @tickCount = 0
        } else {
          @stop()
        }
      }
    }
  }
  // ...
}

The tick() function in Timer is called by the TimerManager (which is the controller for hardware timer interrupts). When the interval specified by the timer client has passed, a tick will result in the posting of a tickEvent. That means the tickEvent will be added to the EventQueue for eventual dispatch by Newsroom.

To use the event subsystem a client application follows these steps:

1. Declare an Event.

2. Define an Event handler.

3. Initialize the Event with handler.

4. Call Newsroom.run(). This call will not return. The Newsroom dispatch loop will run indefinitely.

You must also post events, according to your application logic.

How to Use Timers

There are two classes for timers in package pollen.time. The TimerManager class handles administration and registration of timers. It is usually not necessary for a timer client to access this class. Timer clients can use the timer subsystem via the Timer class.

Here is a simple example that allocates a Timer with a handler and starts it. When the timer ticks, the code toggles an led.

import pollen.environment as Env
from Env import Led

from pollen.time import Timer

module TimerBlink {

  host new Timer t1(tick)    // Declare and allocate a Timer with a tick() handler

  tick() {
    Led.toggle()
  }

  pollen.run() {
    t1.start(500, true)      // Start the timer
    Env.Newsroom.run()
  }
}

The Timer class is located in the pollen-core bundle and you can download it. It is very simple to use.

1. Define a handler for the timer. This handler will define what you want to happen when the timer ticks a specified number of times. In the code above the handler is tick().

2. Declare and initialize a host Timer. In this example the host timer is called t1 and it is initialized with tick() as its handler.

3. Start the timer by calling start(). The first parameter specifies the timer interval in milliseconds and the second is a boolean which controls whether this interval will repeat. In this code the start method is called in pollen.run() which is the main entry function (like main in C).

To stop the timer stop() can be called.

To translate this code an environment must be chosen. You can do this on the command line. There are environments that are available in the pollen-core cloud bundle or you can define your own. The -e option below selects the Arduino Uno environment. All the bundles specified below are cloud bundles as indicated by the @ preceding the bundle name but you can define your own locally. (Or you can download and modify these). The -t option specifies the tool chain. This command line will invoke the avr-gcc compiler on the code.

pollenc    		                        \
    -o <output path>		            \
    -t avr-gcc --mcu atmega328p 		\
    -b @pollen-core 		            \
    -b @atmel 		                    \
    -b @environments 		            \
    -e @environments/arduino/Uno 		\
    TimerBlink.p