Thursday, February 21, 2013

A First Sketch

After installing and moving the different directories (Cosa source/headers and examples) into place it is time to look at an example. Restart Arduino IDE and check that the examples are now available in your Sketchbook.

You should have the above menu structure with the Cosa examples. Select the CosaBlinkPeriodic example and let us look into an interesting twist of the classical Arduino blink example.

This example make use of Cosa's class for Periodic functions together with the Watchdog timer and the Event dispatcher. The twist is running three LEDs (RGB) with different frequencies to generate a palette of colors.

For this example we include the Periodic class, the Pins header file for the OutputPin class and the Board Pin definitions. We use the periodic class with its run() method to allow toggling of the output pin with a given time period. 

#include "Cosa/Periodic.hh"
#include "Cosa/Pins.hh"

#include "Cosa/Board.hh"

class LED : public Periodic {
  OutputPin m_pin;
  LED(Board::DigitalPin pin, uint16_t ms, uint8_t initial = 0) :
    Periodic(ms), m_pin(pin, initial) {}
  virtual void run() { m_pin.toggle(); }

The next step is to create three instances to handle the RGB LED connected to pins 5, 6 and 7. Here comes a big difference to standard Arduino/Wiring. Instead of a pin number, as in Arduino Wiring, Cosa uses symbols (see Board.hh) which allows the compiler to do some checking. The second constructor parameter is the timeout period in milliseconds. The last parameter is the initial state of the LED, default is zero(0), LED off. The green LED is initiated to one(1), LED on. 

LED redLedPin(Board::D5, 512);
LED greenLedPin(Board::D6, 1024, 1);
LED blueLedPin(Board::D7, 1024);

The red LED should be connected to the D5 pin. It will blink with a 1 Hz period (toggled on and off every 512 ms). The green LED to the D6 pin. It will blink with 0.5 Hz. Etc.

The setup() is simply to start the time out event generator. The Watchdog is used for this to allow low power mode in Cosa. The ATmega/ATtiny built-in Watchdog has its own clock circuit. The parameters to Watchdog::begin() are the timeout period in ms (16 is the shortest period), sleep mode and interrupt handler. The predefined interrupt handler that pushes timeout events is used.

void setup()
  Watchdog::begin(16, SLEEP_MODE_IDLE, Watchdog::push_timeout_events);

The main loop is a basic event dispatcher. The Watchdog will produce timeout events which are then dispatch to calls to the LED class run() functions.

void loop()
  Event event;

The event wait will put the processor in low power mode.

There are several advantages with the object-oriented nature of Cosa compared to Arduino/Wiring. The most important is speed. Cosa trades a small amount of memory to cache the pin special register reference and port bit mask. This gives between X2-X10 speedup compared to Arduino/Wiring. I will get back to this in a later posting. 

Friday, February 15, 2013

Installing Cosa

To install Cosa download from github. For Arduino 1.0.X: Unzip in your Sketchbook hardware folder. Create the hardware folder if missing. Path: Sketchbook/hardware/Cosa. The location of the Sketchbook folder may be found in the Arduino IDE Preferences. Please see the File menu.

For Arduino 1.5.X: Create a folder named Cosa in your Sketchbook hardware folder. Create the hardware folder if missing. Unzip in your Sketchbook hardware/Cosa folder. Your should have the path; Sketchbook/hardware/Cosa/Cosa. Rename the inner Cosa to avr; Sketchbook/hardware/Cosa/avr.

The Cosa core contains support for most Arduino boards plus Mighty and Tiny processors. All boards with ATmega328P, ATmega32U4, ATmega1264 and ATmega2560 are supported. No extra cores need to be installed. The source code for Cosa will support all of these targets and allow your project to be moved seamless between them. Please see the Tools>Board menu. You must select a Cosa prefixed board to compile Cosa sketches.

If you intend to compile sketches for ATtiny please install the following patch to AVR GCC (for Arduino Windows): Also please remember to program the device with the bootloader (i.e. set the correct fuse). For more details see the High-Low Tech Tutorial.

Please clone instead if you intend to follow this project more closely and do frequent updates.

The Application Programmers Interface (API) documentation is available on-line and for download as Uncompress this file and navigate your browser to the index file. The documentation contains a full hyperlinked description of all classes, methods and functions in Cosa together with UML graphs of the class hierarchy, include dependencies, and much more. Uncompressing will take some time as the documentation is over 50 Mbyte.

Fig. 3: Cosa documentation (doxygen)

The provided documentation is generated with doxygen and may also be generated for users source code if the Cosa documentation style is adapted. See the Doxyfile for configuration of doxygen.

Cosa is a project with rapid development and frequent updates. Please follow the project by updating your installation. Report bugs and propose improvements on GitHub. Use the New Issue button. Additional Blackduck based information about the project is available on Ohloh. Support this project by adding your interest to github and Ohloh.

Additional information about installing Cosa may be found on github

The easiest way to install Cosa is to use the new Arduino IDE Boards Manager. First add the URL ( to the package information to the Arduino IDE Preferences (File>Preferences:Additional Boards Manager URLs:). Second select Cosa in the Boards Manager (Tools>Board:"">Boards Manager...). This will handle both download and install of the latest Cosa release.

Che Cosa?

Cosa is an object-oriented platform for Arduino. It replaces the Arduino and Wiring library with a large set of integrated classes that support the full range of AVR/ATmega/ATtiny internal hardware modules; all pin modes, Digital, and Analog Pins, External and Pin Change Interrupts, Analog Comparator, PWM, Watchdog, Timer0 (RTC), Timer1 (Servo), UART, USI, SPI, TWI and EEPROM.
Cosa is implemented as an Arduino IDE core. The Cosa platform can be used with almost all Arduino boards and ATtiny/ATmega processors. All classes may be compiled for all variants.

Though object-oriented with optional operator overloading syntax, Cosa is between 2-10X faster than Arduino with regard to digital pin functions. This comes with a small price-tag; memory, 4 bytes per digital pin and 12 bytes per analog pin. Cosa analog pin objects holds the latest sample and allows an event handler. See the benchmarks in the examples directory for further details.

Cosa also contains a data streaming format (Ciao) for encoding of C/C++ language data types such as strings, integer and floating pointer numbers into a binary format. It may be used for a number of applications; tracing, remote procedure calls, data exchange between Arduino devices, etc. The format allows user data types to be defined and values exchanged without additional encoding. The stream header itself is a pre-defined serializable data type. Ciao is used to define an Arduino monitoring and control language (Cosa fai) which has much in common with Firmata.

The primary programming paradigm is object-oriented and state-machine/event driven with proto-threads or multi-tasking. There is a large number of device drivers available for SPI, I2C (TWI) and 1-Wire (OWI). A strict directory structure is used to organize the Cosa/driver source code. Sub-directories are used for each driver type. This allows a foundation for scaling and configuration.

To improve debugging and testing there is trace/syslog style support. The IOStream class allows output to both serial communication (UART) and small TFT displays (such as the ST7735R). The drawing Canvas class supports basic drawing operation and scripting to reduce program memory footprint. The Canvas class also supports drawing of icons and multiple fonts (GLCD and UTFT).

The popular VirtualWire library has been refactored to the object-oriented style of Cosa (VWI) and extended with three additional codecs; Manchester, 4B5B and Bitstuffing. This allows basic ultra cheap wireless nodes with RF315/433 receiver and transmitter. For more advanced wireless connections there is also a driver for the Nordic Semiconductor NRF24L01+ chip, which allows low-power wireless communication of up to 2 Mbps in the 2.4GHz band, and the TI CC1101 Low-Power Sub-1 GHz RF Transceiver.

The goal of this project is to provide an efficient programming platform for rapid prototyping of "Internet-of-things"-devices. There is an Ethernet/Socket with W5100 Ethernet controller device driver. This implementation allows streaming direct to the device buffers. Cosa also implements a number of IP protocols; DNS, DHCP, NTP, HTTP, SNMP and MQTT.

Unfortunately Cosa is not a beginners entry level programming platform, though following some of the design patterns in Cosa will help beginners build more complex small scale embedded systems with richer concurrency and low power consumption. So much for the sales pitch. Now lets see whats Cosa all about when programming the Arduino.