Arduino FreeRTOS

Arduino FreeRTOS Logo

For a long time I have been using the AVR port of FreeRTOS as the platform for my Arduino hardware habit. I’ve written (acquired, stolen, and corrupted) a plethora of different drivers and solutions for the various projects I’ve built over the last years. But, sometimes it would be nice to just try out a new piece of hardware in a solid multi-tasking environment without having to dive into the datasheets and write code. Also, when time is of the essence rewriting someone’s existing driver is just asking for stress and failure.

So recently, with an important hack-a-thon coming up, I thought it would be nice to build a robust FreeRTOS implementation that can just shim into the Arduino IDE and allow me to use the best parts of both environments, seamlessly.

Arduino IDE Core is just AVR

One of the good things about the Arduino core environment is that it is just the normal AVR environment with a simple Java IDE added. That means that all of the AVR command line tools used to build Arduino sketches will also just work my AVR port of FreeRTOS.

Some key aspects of the AVR FreeRTOS port have been adjusted to create the seamless integration with the Arduino IDE. These optimizations are not necessarily the best use of FreeRTOS, but they make the integration much easier.

FreeRTOS needs to have an interrupt timer to trigger the scheduler to check which task should be using the CPU, and to fairly distribute processing time among equivalent priority tasks. In the case of the Arduino environment all of the normal timers are configured in advance, and therefore are not available for use as the system_tick timer. However, all AVR ATmega devices have a watchdog timer which is driven by an independent 128kHz internal oscillator. Arduino doesn’t configure the watchdog timer, and conveniently the watchdog configuration is identical across the entire ATmega range. That means that the entire range of classic AVR based Arduino boards can be supported within FreeRTOS with one system_tick configuration.

The Arduino environment has only two entry point functions available for the user, setup() and loop(). These functions are written into an .ino file and are linked together with and into a main() function present in the Arduino libraries. The presence of a fixed main() function within the Arduino libraries makes it really easy to shim FreeRTOS into the environment.

The main() function in the main.c file contains a initVariant() weak attribute stub function prior to the internal Arduino initialisation setup() function. By implementing an initVariant() function execution can be diverted into the FreeRTOS environment, after calling the normal setup() initialisation, by simply continuing to start the FreeRTOS scheduler.

int main(void) // Normal Arduino main.cpp. Normal execution order.
{
    init();
    initVariant();  // Our initVariant() diverts execution from here.
    setup();  // The Arduino setup() function.

    for (;;)
    {
        loop();  // The Arduino loop() function.
        if (serialEventRun) serialEventRun();
    }
    return 0;
}

Firstly, this initVariant() function is located in the variantHooks.cpp file in the FreeRTOS library. It replaces the weak attribute function definition in the Arduino core.

void initVariant(void)
{
    setup();  // The Arduino setup() function.
    vTaskStartScheduler();  // Initialise and run the FreeRTOS scheduler. Execution should never return to here.
    vApplicationMallocFailedHook();  // Possibly we've failed trying to initialise heap for the scheduler. Let someone know.
}

Secondly, the FreeRTOS idle task is used to run the loop() function whenever there is no unblocked FreeRTOS task available to run. In the trivial case, where there are no configured FreeRTOS tasks, the loop() function will be run exactly as normal, with the exception that a short scheduler interrupt will occur every 15 milli-seconds (configurable). This function is located in the variantHooks.cpp file in the library.

void vApplicationIdleHook( void )
{
    loop();  // The Arduino loop() function.
    if (serialEventRun) serialEventRun();
}

Putting these small changes into the Arduino IDE, together with a single directory containing the necessary FreeRTOS v9.0.0 files configured for AVR, is all that needs to be done to slide the FreeRTOS shim under the Arduino environment.

I have published the relevant files on Github where the commits can be browsed and the repository downloaded. The simpler solution is to install FreeRTOS using the Arduino Library Manager, or download the ZIP files from Github and install manually as a library in your Arduino IDE.

Getting Started with FreeRTOS

Ok, with these simple additions to the Arduino IDE via a normal Arduino library, we can get started.

Firstly in the Arduino IDE Library manager, from Version 1.6.8, look for the FreeRTOS library under the Type: “Contributed” and the Topic: “Timing”.

Arduino Library Manager

Arduino Library Manager

Ensure that the most recent FreeRTOS library is installed. As of writing that is v9.0.0-1.

FreeRTOS v8.2.3-6 Installed

Example of FreeRTOS v8.2.3-6 Installed

Then under the Sketch->Include Library menu, ensure that the FreeRTOS library is included in your sketch. A new empty sketch will look like this.

ArduinoIDE_FreeRTOS

Compile and upload this empty sketch. This will show you how much of your flash is consumed by the FreeRTOS scheduler. As a guide the following information was compiled using Arduino v1.6.9 on Windows 10.

// Device:   loop() -> FreeRTOS | Additional Program Storage
// Uno:         444 ->   7340   |     21%
// Goldilocks:  502 ->   7408   |      6%
// Leonardo:   3624 ->  10508   |     24%
// Yun:        3618 ->  10502   |     24%
// Mega:        656 ->  24108   |      9%

Now test and upload the Blink sketch, with an underlying Real-Time Operating System. That’s all there is to having FreeRTOS running in your sketches. So simple.

Next Steps

Blink_AnalogRead.ino is a good way to take the next step as it combines two basic Arduino examples, Blink and AnalogRead into one sketch with in two separate tasks. Both tasks perform their duties, managed by the FreeRTOS scheduler.

#include <Arduino_FreeRTOS.h>

// define two tasks for Blink and AnalogRead
void TaskBlink( void *pvParameters );
void TaskAnalogRead( void *pvParameters );

// the setup function runs once when you press reset or power the board
void setup() {

  // Now set up two tasks to run independently.
  xTaskCreate(
    TaskBlink
    ,  (const portCHAR *) "Blink";   // A name just for humans
    ,  128  // This stack size can be checked and adjusted by reading the Stack Highwater
    ,  NULL
    ,  2  // Priority, with 3 (configMAX_PRIORITIES - 1) being the highest, and 0 being the lowest.
    ,  NULL );

  xTaskCreate(
    TaskAnalogRead
    ,  (const portCHAR *) "AnalogRead";
    ,  128  // Stack size
    ,  NULL
    ,  1  // Priority, with 3 (configMAX_PRIORITIES - 1) being the highest, and 0 being the lowest.
    ,  NULL );

  // Now the task scheduler, which takes over control of scheduling individual tasks, is automatically started.
}

void loop()
{
  // Empty. Things are done in Tasks.
}

/*--------------------------------------------------*/
/*---------------------- Tasks ---------------------*/
/*--------------------------------------------------*/

void TaskBlink(void *pvParameters)  // This is a task.
{
  (void) pvParameters;

  // initialize digital pin 13 as an output.
  pinMode(13, OUTPUT);

  for (;;) // A Task shall never return or exit.
  {
    digitalWrite(13, HIGH);   // turn the LED on (HIGH is the voltage level)
    vTaskDelay( 1000 / portTICK_PERIOD_MS ); // wait for one second
    digitalWrite(13, LOW);    // turn the LED off by making the voltage LOW
    vTaskDelay( 1000 / portTICK_PERIOD_MS ); // wait for one second
  }
}

void TaskAnalogRead(void *pvParameters)  // This is a task.
{
  (void) pvParameters;

  // initialize serial communication at 9600 bits per second:
  Serial.begin(9600);

  for (;;)
  {
    // read the input on analog pin 0:
    int sensorValue = analogRead(A0);
    // print out the value you read:
    Serial.println(sensorValue);
    vTaskDelay(1);  // one tick delay (15ms) in between reads for stability
  }
}

Next there are a number of examples in the FreeRTOS Quick Start Guide.

One last important thing you can do is to reduce device power consumption by not using the default loop() function for anything more than putting the MCU to sleep. This code below can be used for simply putting the MCU into a sleep mode of your choice, while no tasks are unblocked. Remember that the loop() function shouldn’t ever disable interrupts and block processing.

#include <avr/sleep.h>  // include the Arduino (AVR) sleep functions.

loop() // Remember that loop() is simply the FreeRTOS idle task. Something to do, when there's nothing else to do.
{
// Digital Input Disable on Analogue Pins
// When this bit is written logic one, the digital input buffer on the corresponding ADC pin is disabled.
// The corresponding PIN Register bit will always read as zero when this bit is set. When an
// analogue signal is applied to the ADC7..0 pin and the digital input from this pin is not needed, this
// bit should be written logic one to reduce power consumption in the digital input buffer.

#if defined(__AVR_ATmega640__) || defined(__AVR_ATmega1280__) || defined(__AVR_ATmega1281__) || defined(__AVR_ATmega2560__) || defined(__AVR_ATmega2561__) // Mega with 2560
DIDR0 = 0xFF;
DIDR2 = 0xFF;
#elif defined(__AVR_ATmega644P__) || defined(__AVR_ATmega644PA__) || defined(__AVR_ATmega1284P__) || defined(__AVR_ATmega1284PA__) // Goldilocks with 1284p
DIDR0 = 0xFF;

#elif defined(__AVR_ATmega328P__) || defined(__AVR_ATmega168__) || defined(__AVR_ATmega8__) // assume we're using an Arduino with 328p
DIDR0 = 0x3F;

#elif defined(__AVR_ATmega32U4__) || defined(__AVR_ATmega16U4__) // assume we're using an Arduino Leonardo with 32u4
DIDR0 = 0xF3;
DIDR2 = 0x3F;
#endif

// Analogue Comparator Disable
// When the ACD bit is written logic one, the power to the Analogue Comparator is switched off.
// This bit can be set at any time to turn off the Analogue Comparator.
// This will reduce power consumption in Active and Idle mode.
// When changing the ACD bit, the Analogue Comparator Interrupt must be disabled by clearing the ACIE bit in ACSR.
// Otherwise an interrupt can occur when the ACD bit is changed.
ACSR &= ~_BV(ACIE);
ACSR |= _BV(ACD);

// There are several macros provided in the header file to actually put
// the device into sleep mode.
// SLEEP_MODE_IDLE (0)
// SLEEP_MODE_ADC (_BV(SM0))
// SLEEP_MODE_PWR_DOWN (_BV(SM1))
// SLEEP_MODE_PWR_SAVE (_BV(SM0) | _BV(SM1))
// SLEEP_MODE_STANDBY (_BV(SM1) | _BV(SM2))
// SLEEP_MODE_EXT_STANDBY (_BV(SM0) | _BV(SM1) | _BV(SM2))

set_sleep_mode( SLEEP_MODE_IDLE );

portENTER_CRITICAL();
sleep_enable();

// Only if there is support to disable the brown-out detection.
#if defined(BODS) && defined(BODSE)
sleep_bod_disable();
#endif

portEXIT_CRITICAL();
sleep_cpu(); // good night.

// Ugh. I've been woken up. Better disable sleep mode.
sleep_reset(); // sleep_reset is faster than sleep_disable() because it clears all sleep_mode() bits.
}

o that’s all there is to it. There’s nothing more to do except to read the FreeRTOS Quick Start Guide.
Further reading with manicbug, and by searching on this site too.

General Usage

FreeRTOS has a multitude of configuration options, which can be specified from within the FreeRTOSConfig.h file. To keep commonality with all of the Arduino hardware options, some sensible defaults have been selected.

The AVR Watchdog Timer is used with to generate 15ms time slices, but Tasks that finish before their allocated time will hand execution back to the Scheduler. This does not affect the use of any of the normal Timer functions in Arduino.

Time slices can be selected from 15ms up to 500ms. Slower time slicing can allow the Arduino MCU to sleep for longer, without the complexity of a Tickless idle.

Watchdog period options:

  • WDTO_15MS
  • WDTO_30MS
  • WDTO_60MS
  • WDTO_120MS
  • WDTO_250MS
  • WDTO_500MS

Note that Timer resolution is affected by integer math division and the time slice selected. Trying to accurately measure 100ms, using a 60ms time slice for example, won’t work.

Stack for the loop() function has been set at 128 bytes. This can be configured by adjusting the configIDLE_STACK_SIZE parameter. It should not be less than the configMINIMAL_STACK_SIZE. If you have stack overflow issues, just increase it. Users should prefer to allocate larger structures, arrays, or buffers using pvPortMalloc(), rather than defining them locally on the stack. Or, just declare them as global variables.

Memory for the heap is allocated by the normal malloc() function, wrapped by pvPortMalloc(). This option has been selected because it is automatically adjusted to use the capabilities of each device. Other heap allocation schemes are supported by FreeRTOS, and they can used with additional configuration.

Errors

  • Stack Overflow: If any stack (for the loop() or) for any Task overflows, there will be a slow LED blink, with 4 second cycle.
  • Heap Overflow: If any Task tries to allocate memory and that allocation fails, there will be a fast LED blink, with 100 millisecond cycle.

Compatibility

  • ATmega328 @ 16MHz : Arduino UNO, Arduino Duemilanove, Arduino Diecimila, etc.
  • ATmega328 @ 16MHz : Adafruit Pro Trinket 5V, Adafruit Metro 328, Adafruit Metro Mini
  • ATmega328 @ 16MHz : Seeed Studio Stalker
  • ATmega328 @ 16MHz : Freetronics Eleven, Freetronics 2010
  • ATmega328 @ 12MHz : Adafruit Pro Trinket 3V
  • ATmega32u4 @ 16MHz : Arduino Leonardo, Arduino Micro, Arduino Yun, Teensy 2.0
  • ATmega32u4 @ 8MHz : Adafruit Flora, Bluefruit Micro
  • ATmega1284p @ 20MHz : Freetronics Goldilocks V1
  • ATmega1284p @ 24.576MHz : Seeed Studio Goldilocks V2, Seeed Studio Goldilocks Analogue
  • ATmega2560 @ 16MHz : Arduino Mega, Arduino ADK
  • ATmega2560 @ 16MHz : Freetronics EtherMega
  • ATmega2560 @ 16MHz : Seeed Studio ADK
  • ATmegaXXXX @ XXMHz : Anything with an ATmega MCU, really.

Files and Configuration

  • Arduino_FreeRTOS.h : Must always be #include first. It references other configuration files, and sets defaults where necessary.
  • FreeRTOSConfig.h : Contains a multitude of API and environment configurations.
  • FreeRTOSVariant.h : Contains the AVR specific configurations for this port of FreeRTOS.
  • heap_3.c : Contains the heap allocation scheme based on malloc(). Other schemes are available and can be substituted (heap_1.c, heap_2.c, heap_4.c, and heap_5.c) to get a smaller binary file, but they depend on user configuration for specific MCU choice.

Goldilocks Analogue – Wrap Up

This is the final item on the Goldilocks Analogue as a design and production exercise.

Thank you for pledging on the Kickstarter Project page. Closed on November 19th 2015, with 124% funding. Now that the Kickstarter Pledges have been shipped, the Goldilocks Analogue is available on Tindie.

I sell on Tindie

I’ve been updating this post with the pre-production and production experience over the past few months.

The pre-production design materials, correcting the errata noted on Prototype Version 4, have been finalised and sent to Seeed Studio.
GoldilocksAnalogue_Seeed_20151120

The interim backer report is out, and now manufacturing quantities for procuring parts ready for the February production run have been finalised.

An updated version of the Goldilocks Analogue User Manual is available, and the Production Testing Document has reached Version 2 following inclusion of Windows 10 test procedures.

Revised Arduino IDE Variant files for Goldilocks Analogue using the Arduino core are available on Github.

Also additional optional libraries to provide support for each of the advanced features of the Goldilocks Analogue are available in the Arduino IDE Library Manager.

Arduino IDE compatibility testing revealed only a few remaining issues related to support of the ATmega1284p used in the Goldilocks Analogue. Two issues have been raised and resolved as 2 pull requests on the main Arduino IDE development path.

Both these issues have been committed into the Arduino main git tree, and they have landed in Arduino IDE Release 1.6.8.

The only remaining known issue is the limitation in the configuration of the Tones() code to use only Timer 2. We would like to use Timer 2 for the RTC. There is no other option but to use this Timer for the RTC support, so it would be good if Tones() could be configured to use a different timer.

Testing

Rather than going back over old ground, I’ll just be testing the pre-production version against the Version Prototype 4, to ensure that the things that should have improved, are improved, and that nothing has become broken.

Power Supplies

In the image below, Channel 1 (yellow) is 4.47mV of noise present at the output capacitor for the power supply, and Channel 2 (blue) is the 3.47mV supply noise present on a test Vcc pin closest to the MCU.

The significant improvement in noise level for the pre-production version at the MCU is similar to that achieved for the Prototype 4 (even slightly better), and this is probably due to reduced capacitive coupling into the ground plane by removing the ground copper from directly under the main supply inductor.

GA PP Power Supply Noise

GA PP: 5V Power Supply Noise

Remembering, for context, that 4mV is still the same order of the least significant bit for a 5V 10 bit ADC sampler, as found in the ATmega1284p, and a one bit change in the LSB of the MCP4822 input generates a 1mV change in output.

Checking the other power supplies on the board, Channel 1 (yellow) is the 3.3V positive supply, provided by a linear regulator. This supply is not used for analogue components, so the 4.0mV noise level is not critical, but never the less it is slightly less than on the Version P4.

Channel 2 (blue) below shows the -3V supply for the Operational Amplifier. This shows that the supply voltage noise of 5.9mV after filtering by a first order LC filter further smooth this supply. Compared to the Version P4 with no filtering (shown below) the noise is reduced substantially. The Version P4 shows a 10mV ramp, because it is a capacitive charge switching device. The addition of this LC filter was the one substantial change from the Prototype 4, so it is good to see the positive effect on the negative supply input to the Op Amp.

GA PP 3.3V and -3V Power Supply Noise

GA PP: 3.3V and -3V Power Supply Noise

Goldilocks Analogue Prototype 4 - 3.3V & -3V Supply Noise

GA P4: 3.3V & -3V Power Supply Noise

Analogue Output

The standard test that I’ve been using throughout the development is to feed in a 43.1Hz Sine wave generated from a 1024 value 16 bit LUT. The sampling rate is 44.1kHz, which is generated by Timer 1 to get the closest match.

The spectra and oscilloscope charts below can be directly compared to the testing done with prototype Version P4 and earlier versions of the Goldilocks Analogue.

The below chart shows the sine wave generated at the output of the Op Amp. This is exactly as we would like to see, with no compression of either the 4.096V peak, or the 0V trough.

Goldilocks Analogue – 43Hz Sine Wave – Two Channels – One Channel Inverted

GA PP: 43Hz Sine Wave – Two Channels – One Channel Inverted

Looking at the spectra generated up to 953Hz it is possible to see harmonics from the Sine Wave, and other low frequency noise.

The spectrum produced by the Goldilocks Analogue shows most distortion is below -70dB, and that the noise floor lies below -100dB. The pre-production sample shows slightly higher noise carriers than the Version P4, but the difference is not substantial.

GA PP 953Hz

GA PP: 43.1Hz Sine Wave – 953Hz Spectrum

In the spectrum out to 7.6kHz we are looking at the clearly audible range, which is the main use case for the device.

The Goldilocks Analogue has noise carriers out to around 4.5kHz, but they are all below -80dB. After 4.5kHz the only noise remains below -100dB.

GA PP 7k6Hz

GA PP: 43.1Hz Sine Wave – 7k6Hz Spectrum

The spectra out to 61kHz should show a noise carrier generated by the reconstruction frequency of 44.1kHz.

The Goldilocks Analogue shows the spectrum maintains is low noise level below -90dB right out to the end of the audible range, and further out to the reconstruction carrier at 44.1kHz.

GA PP 61kHz

GA PP: 43.1Hz Sine Wave –  61kHz Spectrum

The final spectrum shows the signal out to 976kHz. We’d normally expect to simply see the noise floor, beyond the 44.1kHz reconstruction carrier noise.

The Goldilocks Analogue has a noise carrier at around 210kHz, probably generated by the -3V supply. The noise carrier at 340kHz is generated through the 5V SMPS supply, and is absent when powered by USB socket. Aside from the two carriers mentioned, there is no further noise out to 976kHz.

GA PP 976kHz

GA PP: 43.1Hz Sine Wave – 976kHz Spectrum

The Pre-production analogue output works as specified, and is essentially identical to the analogue output on the Prototype 4. It can maintain the 72dB SNR required, of which it should theoretically be capable.

Goldilocks Analogue – Testing 4

Recap

I’ve been working on the Goldilocks Analogue now for so long that its been the centerpiece of my coding evenings for the past 18 months. This is the first time that I’ve designed a piece of hardware, and I’ve managed to make many mistakes (or learnings) along the way, so I think that every step of the process has been worthwhile.

Goldilocks Analogue Prototype 4 - Rotating

Goldilocks Analogue Prototype 4 – Rotating

In this project, I’ve learned about Digital to Analogue Converters, Operational Amplifiers, Voltage translation, Switching Power Supplies, and most importantly have gained a working knowledge of the Eagle PCB design tools.

Version History

The original Goldilocks Project was specifically about getting the ATmega1284p MCU onto a format equivalent to the Arduino Uno R3. The main goal was to get more SRAM and Flash memory into the same physical footprint used by traditional Arduino (pre-R3) and latest release Uno R3 shields.

The Goldilocks project achieved that goal, but the resulting ATmega platform still lacked one function that I believe is necessary; a high quality analogue capability. The world is analogue, but having an ADC capability, without having a corresponding digital-to-analogue capability, is like having a real world recorder (the ADC capability) with no means to playback and recover these real world recordings.

A major initiative of the Goldilocks is to bring an analogue capability to the Arduino platform via a DAC, so this project was called the Goldilocks Analogue. Following a Kickstarter campaign, the Goldilocks Analogue is now available on Tindie.

I sell on Tindie

Version 1 implemented the MCP4822 DAC buffered with an expensive, very musical, Burr Brown Operational Amplifier. Although the DAC performed exactly as designed, I neglected to provide the Op Amp with a negative supply rail, so it could not approach 0V required to reproduce the full range of output available (0v to 4.096V) from the DAC. That was a mistake.

Version 1 also reverted the USB to Serial interface to use a proper FTDI FT232R device from the ATmega32u2 MCU (the solution preferred now by Arduino). Using the ATmega32u2 (or ATmega16u2) to interface with anything not running at its own 16MHz CPU clock rate is broken and doesn’t work. This is because the ATmega devices don’t produce correct serial when their CPU clock is not a clean multiple of the USART required rate. I learned this the hard way with the Goldilocks Project.

Finally Version 1 implemented a buffered microSD card interface, using devices suitable to convert from 5V to 3.3V (SCK, MOSI, CS), and 3.3V to 5V (MISO) for the SPI interface. This was a correct implementation, but later I removed it because sometimes I’m really too smart for my own good.

Updated - Goldilocks Analogue

Goldilocks Analogue – Version P1

Some significant rework of the analogue section was required for Version 2. Firstly, I decided that audio was a significant use case for the Goldilocks Analogue so it was worth while reducing the cost of the Op Amp, and sharing that expenditure with a special purpose headphone amplifier, working in parallel with the Op Amp.

The TPA6132A2 headphone amplifier was found, and implemented into the prototype. This “DirectPath” device removes the need for large output capacitors in the signal path, as it provides a zero centred output from a single supply voltage.

Version 2 also had a lesser but fully adequate TS922A Op Amp for providing DC to full rate signals, buffering the MCP4822 DAC. I had learned that Op Amps need to be provided with a negative supply rail, if they are to achieve 0V output under load.

To create a negative supply rail for the Version 2 Op Amp, I used a pair of TPS60403 voltage inverters producing -5V from the main power supply, and then fed that signal into a TPS72301 regulator configured to produce -1.186V. This design worked very well, but needed 3 devices to produce the output and also quite a lot of board space.

Finally, for Version 2, I changed the microSD voltage translation to use the TXS0104 (TXB0104) level translation products. These special purpose devices enable the bidirectional transfer of signals over voltage transitions. Normally these two device types (TXB / TXS) work very well, but somehow I couldn’t ever get either version to work properly, which caused the microSD card to never work. This exercise was a failure, and was reverted to normal buffer logic for Version 3.

Goldilocks Analogue Version 2

Goldilocks Analogue – Version P2

Version 3 was supposed to be my final prototype prior to putting this into a crowd funding project. I made some fairly simple changes, and I was pretty happy with the outcome of Version 2 as it was.

Version 3 changed the MCP4822 DAC interface to use the USART1 interface present on the ATmega1284p MCU. Using the USART1 in MSPI Mode allows the DAC to operate independently of the normal SPI bus. This frees up timing constraints on the SPI interface so that slow microSD cards can be read and streamed to the DAC, or SPI graphics interfaces can be used as in the case of the synthesiser demonstration.

As part of the testing, I found that the ATmega1284p would operate successfully at 24.576MHz. This is a magic frequency because it allows an 8 bit timer to reproduce all of the major audio sampling rates related to 48kHz. I’ve tested using this frequency and everything is working fine.

Obviously there was some feature creep over the course of experimentation, so I decided to add two SPI memory device layouts to the PCB. This would allow up to 23LC1024 256kByte of SRAM to be addressed, together with AT25M01 256kByte of EEPROM, for example. Putting these layouts on the board meant that the JTAG interface had to be moved to the back of the PCB. This was actually not a bad thing, as it would have been impossible to use the JTAG interface with a Shield in place anyway.

I was asked to beef up the 3.3V supply capability of the Goldilocks Analogue, so I added a AP1117 device capable of up to 1A supply, upgrading from 150mA.

Goldilocks Analogue Version 3

Goldilocks Analogue – Version P3

Version 4 added the feature of amplified Microphone Input. Using the MAX9814 Mic Amp electret microphones present in the normal headsets used with smart-phones can act as an audio input to the Goldilocks Analogue. The amplified signal is presented on Pin A7, which falls outside of the normal Arduino Uno R3 footprint. For completeness, I also added a level shifted non-amplified signal (for line-in) to Pin A6.

Because of the extra microphone amplifier circuitry, I needed to reduce the footprint of the negative supply rail. So I used a regulated -3V device LTC1983 to produce the negative supply rail required for the Op Amp. There are now 3 regulators on the Goldilocks Analogue, 5V at up to 2.4A, 3.3V at up to 1A, and -3V at 100mA.

Version 4 also saw the last of the through hole components gone. Both the main crystal and the 32kHz clock crystal were reformatted into surface mount technology. This reduces the flexibility of the platform, but it makes manufacturing a bit easier.

Goldilocks Analogue - Version P4

Goldilocks Analogue – Version P4

Version 4 is the end. There will be some minor adjustments to the board for the production version. But, finally, I think this is it.

Unboxing

Prototype 4 back from manufacturing

Prototype 4 back from manufacturing

Errata

There is no power supply jumper provided. Add this to the BOM.

The EEPROM is built with SOIC8 Wide Body, but it should be Narrow Body. Fix the BOM.

Labels for the recommended power supply Voltage are partially obscured by power jack. Move the labels.

The main crystal doesn’t oscillate, because the Eagle library had an incorrect footprint.
Tested to work by rotating the crystal on its existing footprint.

Respecify the main MCU crystal to the Atmel recommended type.

Change C2 and C3 to 15pF in line with Atmel recommendation.

Change C1 and C11 to 12pF in line with Atmel recommendation.

Change R18 to 100kOhm, to bias the Analogue Line in correctly.

Add a simple LC filter to the -3.3V supply, using the known inductor and 10uF capacitor.

Tie Mic Gain to AVcc with a separable link, to produce 40dB default gain. This is the setting required for most normal microphones, so will improve the “out of box” experience for most users.

Testing

Front

Version P4 – Front

Back

Version P4 – Back

Power Supplies

First, looking at power supply noise, we’ve got a slightly better result for noise at the power supply over the Prototype 1. Prototype 1 used the EUP3476 Switched Mode supply device. Problems with obtaining ready supply of this device led to changing it to the AP6503, which is pin compatible but needs slightly different voltage selection resistors. In contrast to the Arduino Uno and other devices, this is very good.

We remember that 1mV represents the Voltage change in the least significant bit of the 12 bit MCP4822. The least significant bit of the ATmega1283p 10 bit ADC is about 4mV. Sampling voltages similar to the noise level inherent on the platform will not generate any further accuracy.

Power Supply GA 4

GA P4: 5V Power Supply Noise

Channel 1 (yellow) is 4.0mV of noise present at the output capacitor for the power supply, and represents the lowest noise inherent in the supply. Channel 2 (blue) is the 5.6mV supply noise present on a test pin closest to the MCU.

The significant improvement in noise level for the GA4 version at the MCU may be due to the currently decreased system clock rate, and therefore is subject to confirmation.

Power Supply GA1

GA P1: 5V Power Supply Noise

Checking the other power supplies on the board, Channel 1 (yellow) is the 3.3V positive supply, provided by a linear regulator. This supply is not used for analogue components, so the 4.3mV noise level is not critical.

Channel 2 (blue) below shows the -3V supply for the Operational Amplifier. This shows a 10mV supply voltage ramp, generated because it is a capacitive charge switching device. This is not particularly good, and it will be worth adding an LC filter to attempt to further smooth this supply, for the production Goldilocks Analogue.

Goldilocks Analogue Prototype 4 - 3.3V & -3V Supply Noise

GA P4: 3.3V & -3V Power Supply Noise

Microphone Input

Microphone amplifier works.

Interestingly, when the amplifier is set to 60dB gain (default setting, Channel 2, blue) it oscillates at 144kHz when not connected to anything, while it doesn’t do this with the normal gain setting of 40dB (Channel 1, yellow) based on the amplification required for typical smartphone headphones. In either case, as soon as the Mic input is grounded, the Mic output reduces to less than 4mVAC on the correct bias of 1.25VDC.

Suggest to make 40dB amplification the default setting for the production Goldilocks Analogue, but allowing the connection to be segmented for increased amplification if required.

GA4 - Mic Oscillation Comparison 60dB and 40dB

GA4 – Mic Oscillation Comparison at 40dB (CH1) and 60dB (CH2) amplification.

Line-In (PA6) seems to be biased at 1.07V rather than 1.25V. Check calculation again… Doh! R18 should be 100kOhm.

Analogue Output

The standard test that I’ve been using throughout the development is to feed in a 43.1Hz Sine wave generated from a 1024 value 16 bit LUT. The sampling rate is 44.1kHz, which is generated by Timer 1 to get the closest match.

The spectra and oscilloscope charts below can be directly compared to the testing done with previous prototype versions of the Goldilocks Analogue.

The below chart shows the sine wave generated at the output of the Op Amp. This is exactly as we would like to see, with no compression of either the 4.096V peak, or the 0V trough.

Goldilocks Analogue – 43Hz Sine Wave – Two Channels – One Channel Inverted

Goldilocks Analogue P4 – 43Hz Sine Wave – Two Channels – One Channel Inverted

Looking at the spectra generated up to 953Hz it is possible to see harmonics from the Sine Wave, and other low frequency noise.

The spectrum produced by the Goldilocks Analogue shows most distortion is below -70dB, and that the noise floor lies below -100dB.

Goldilocks Analogue – 43.1Hz Sine Wave – 953Hz Spectrum

Goldilocks Analogue P4 – 43.1Hz Sine Wave – 953Hz Spectrum

Comparing the same DAC output channel A from Op Amp (Channel 1 – Blue) with the same Headphone Amp Left (Channel 2 – Red), we see slightly more noise carriers.

Goldilocks Analogue P4 – 43.1Hz Sine Wave – 953Hz Spectrum

Goldilocks Analogue P4 – 43.1Hz Sine Wave – 953Hz Spectrum – Headphone in Red

In the spectrum out to 7.6kHz we are looking at the clearly audible range, which is the main use case for the device.

The Goldilocks Analogue has noise carriers out to around 4.5kHz, but they are all below -80dB. After 4.5kHz the only noise remains below -100dB.

Goldilocks Analogue – 43.1Hz Sine Wave – 7.6kHz Spectrum

Goldilocks Analogue P4 – 43.1Hz Sine Wave – 7.6kHz Spectrum

The spectra out to 61kHz should show a noise carrier generated by the reconstruction frequency of 44.1kHz.

The Goldilocks Analogue shows the spectrum maintains is low noise level below -90dB right out to the end of the audible range, and further out to the reconstruction carrier at 44.1kHz.

Goldilocks Analogue – 43.1Hz Sine Wave – 61kHz Spectrum

Goldilocks Analogue P4 – 43.1Hz Sine Wave – 61kHz Spectrum

The final spectrum shows the signal out to 976kHz. We’d normally expect to simply see the noise floor, beyond the 44.1kHz reconstruction carrier noise.

The Goldilocks Analogue has a noise carrier at around 210kHz. Aside from the single carrier mentioned, there is no further noise out to 976kHz.

Goldilocks Analogue – 43.1Hz Sine Wave – 976kHz Spectrum

Goldilocks Analogue P4 – 43.1Hz Sine Wave – 976kHz Spectrum

Analogue output works as specified. It can maintain the 72dB SNR required, of which it should theoretically be capable.

SPI Devices

MicroSD works.

SPI SRAM / EEPROM devices work.

Tests for REWORK

These tests are for the factory rework of the prototype boards.

Check 5V Power Supply

Plug 7-23VDC positive centre into J1.
CHECK: that there is 5VDC available on H15 DC Pin.

GAV4-5VDC

Check 3.3V and -3V Power Supply

Add a jumper to J1 from the centre pin to DC Pin.

CHECK: that 5VDC, 3.3VDC, and -3VDC is available at the test points indicated.

GA4V-Powered

Check for Internal RC Oscillator Function

Connect an AVRISP Mk2 in circuit programmer to the ICSP Socket.

Use the following command to enable the CLKO on PB1, and set other fuses correctly.

avrdude -pm1284p -cavrisp2 -Pusb -u -Ulfuse:w:0x82:m -Uhfuse:w:0xd8:m -Uefuse:w:0xfc:m

CHECK: Using an oscilloscope or counter, check that the CLKO signal on PB1 is between 7MHz and 8.1MHz (nominal value 8MHz).

GAV4-CLKO

Rework 24.576MHz Crystal & Capacitors

Identify Crystal Y2, and capacitors C2 & C3 and C1 & C11.

Screenshot from 2015-10-06 23:21:16

IMPORTANT: Y2 must be ROTATED 90 degrees (either direction) from standard footprint.

Rework Y2 to the 24.576MHz SMD Crystal Digikey 644-1053-1-ND device.

Rework C2 & C3 to 15pF.

Rework C1 & C11 to 12pF.

Check External Crystal Oscillator Function

Connect an AVRISP Mk2 in circuit programmer to the ICSP Socket.

Use the following command to enable the CLKO on PB1, and set other fuses to External Full Swing Oscillator with BOD.

avrdude	-pm1284p -cavrisp2 -Pusb -u -Ulfuse:w:0x97:m -Uhfuse:w:0xd8:m -Uefuse:w:0xfc:m

CHECK: Using an oscilloscope or counter, check that the CLKO signal on PB1 is 24.576MHz.

GAV4-CLKO

Use the following command to disable the CLKO on PB1, and set other fuses to External Full Swing Oscillator with BOD.

avrdude	-pm1284p -cavrisp2 -Pusb -u -Ulfuse:w:0xd7:m -Uhfuse:w:0xd8:m -Uefuse:w:0xfc:m

Rework R18

CHECK: DC voltage on Port A6 (ADC Input 6). Expected value 1.07VDC.

Identify resistor R18. R18 needs to be reworked to 100kOhm.

Screenshot from 2015-10-06 23:21:02

GAV4-Rework

CHECK: DC voltage on Port A6 (ADC Input 6). Confirm the expected value 1.25VDC.

Load Bootloader

Connect an AVRISP Mk2 in circuit programmer to the ICSP Socket.

Use the following command to program a bootloader using the provided HEX file.

avrdude -pm1284p -cavrisp2 -Pusb -Uflash:w:GABootMonitor.hex:a

Connect the Goldilocks Analogue to a USB port and open a serial terminal at 38400 baud to the attached FTDI USB /dev/ttyUSB0 interface.

CHECK: Enter !!! into the serial terminal, immediately following a board RESET (using the RESET button). This will enable the Boot Monitor. These are the boot monitor commands.

Bootloader&gt;
Bootloader&gt;H Help
0=Zero addr (for all commands)
?=CPU stats
@=EEPROM test
B=Blink LED
E=Dump EEPROM
F=Dump FLASH
H=Help
L=List I/O Ports
Q=Quit
R=Dump RAM
V=show interrupt Vectors
Y=Port blink

Bootloader&gt;
Bootloader&gt;? CPU stats
Goldilocks explorer stk500v2
Compiled on = Oct  7 2015
CPU Type    = ATmega1284P
__AVR_ARCH__= 51
GCC Version = 4.8.2
AVR LibC Ver= 1.8.0
CPU ID      = 1E9705
Low fuse    = D7
High fuse   = D8
Ext fuse    = FC
Lock fuse   = FF

Close the serial terminal program (disconnect from the /dev/ttyUSB0 device).

Load Test Program

With the USB interface connected to the Goldilocks Analogue, and the DTR switch in the right most position (closest to DTR text; opposite position to the pictured position).

GAV4-DTR

Use the following command to program a Test Suite using the provided HEX file.

avrdude	-pm1284p -cwiring -P/dev/ttyUSB0 -b38400 -D -v -Uflash:w:GATestSuite.hex:a

Plug a standard smartphone headset (with microphone) with a 3.5mm TRRS connector in LRGM (left, right, ground, mic) configuration into the socket.
CHECK: Sound (echo of input) should be heard from the headphones, when speaking into the microphone.

Connect the Goldilocks Analogue to a USB port and open a serial terminal at 38400 baud to the attached FTDI USB /dev/ttyUSB0 interface.
CHECK: Information on each Task’s stack “Highwater” mark should be seen on the serial terminal.

Goldilocks Analogue – Prototyping 4

Just over 6 months since the third iteration of the Goldilocks Analogue Prototyping was started, and now I’ve finished the design for a forth iteration. The Goldilocks Analogue Prototype 4 design is now finished, and I’m working out what the final bill of materials will cost to assemble into a final outcome. Testing for the Prototype 4 has begun, and everything is working as expected.

The third prototype was completely successful, and produced the improvements I was looking for. The use of the MSPI Mode on USART1 means that two SPI interfaces can be run in parallel, allowing the DAC to hold its tight timing requirements while slower SD card transactions take place (for example). This was proven through the implementation of a direct digital synthesiser, controlled by a SPI controlled touch screen.

Goldilocks Analogue - Prototype 3

Goldilocks Analogue – Prototype 3

Revision for Prototype 4

The Prototype 3 was supposed to be the final version, and it achieved everything that I set out in the original design specifications. But, then there was some feature creep.

Prototype 4 back from manufacturing

Prototype 4 back from manufacturing

In discussing the TRS 3.5mm audio socket, a better more robust TRRS version was found. The realisation that it would be possible to have a microphone input, without requiring additional board space, led me to experiment with the Adafruit breakout board for the MAX9814 Microphone amplifier, and then to build a very simple Walkie-Talkie demonstration to test the use of audio input (with the integrated ADC), simultaneously with audio output (via the DAC).

Once the use of the MAX9814 was proven, I could implement a reference circuit as an input option. The amplified microphone input is connected to Pin 7 of the Analogue Port A. Conveniently, the MAX9814 delivers the amplified signal at +1.25V with a 2V peak to peak signal. This allows the sample to fall into the range of 0V to 2.56V internal reference voltage for the ATmega ADC, providing the maximum sampling resolution with no further adjustments.

The MAX9814 also includes an integrated microphone biasing circuitry, which is designed to support normal electret microphones.

 

As an alternative input functionality, the Prototype 4 also allows for LINE level inputs. I have used a voltage divider to reference the input signal to 1.25V DC. Although a 2V peak to peak Line level input will overload the Microphone amplifier, rendering the output signal on PA7 unusable, the LINE input is routed to Pin 6 on Port A will have exactly the right range to sample using the internal ATmega ADC voltage reference.

Both Port A Pin 6 and Pin 7 are outside of the normal Arduino UNO R3 footprint, so the normal functionality of the UNO footprint is not affected by either the two input options. And if desired, the connection can be separated at a solder-jumper on the rear of the board.

The additional space required for the microphone and line level input circuitry has been created by simplifying the negative supply rail for the Op-Amp. The Op-Amp is provided to support DC to 50k sample per second analogue output. To achieve a linear output from 0v to 4.096V the Op-Amp requires a negative supply voltage. In this revision, I have used a single LTC1983 regulated supply device to provide the negative -3V supply rail. The outcome should be equivalent to the Prototype 3 solution, which used 3 devices.

Board Layout

The final board layout has been completed, and the board is now in discussion for manufacturing.

The GoldilocksAnalogueP4Schematic in PDF format.

Front of board (All Layers)

Front

This is the front of the board showing all of the layers, and the general layout of the devices. The board layout is pretty busy, but still there is sufficient prototyping capability to take all the port pins off-board, or provide on-board breakouts.

GoldilocksAnalogue_TopSilk

Top Layer

This is the Top Layer, which contains all of the devices. There are no devices on the Bottom Layer.

Route 2 (GND) Layer

The Ground Layer on Route 2 is unchanged from previous iterations, and provides a solid platform for low noise analogue circuits.

Route 15 (Vcc) Layer

The Route 15 power supply layer contains all of the supply lines, providing 5V regulated, 5V filtered for analogue AVcc, 3.3V regulated, and -3V regulated.

Bottom Layer

Back

All the pin outs are defined on the Bottom Layer. In addition to the items previously mentioned, there are two small locations where the Line and Microphone inputs can be cut, and allow the full functionality of PA6 and PA7 to be recovered.

Pin Mapping

This the map of the ATmega1284p pins to the Arduino physical platform, and their usage on the Goldilocks Analogue

Arduino
UNO R3
328p Feature 328p Pin 1284p Pin 1284p Feature Comment
Analog 0 PC0 PA0
Analog 1 PC1 PA1
Analog 2 PC2 PA2
Analog 3 PC3 PA3
Analog 4 SDA PC4 PA4 PC1 I2C -> Bridge Pads
Analog 5 SCL PC5 PA5 PC0 I2C -> Bridge Pads
Reset Reset PC6 RESET Separate Pin
Digital 0 RX PD0 PDO RX0
Digital 1 TX PD1 PD1 TX0
Digital 2 INT0 PD2 PD2 INT0 / RX1 USART1
Digital 3 INT1 / PWM2 PD3 PD3 INT1 / TX1 USART1
-> MCP4822 SPI MOSI
Digital 4 PD4 PD4 PWM1 / XCK1 16bit PWM
-> MCP4822 SPI SCK
Digital 5 PWM0 PD5 PD5 PWM1 16bit PWM
Digital 6 PWM0 PD6 PD6 PWM2
Digital 7 PD7 PD7 PWM2
Digital 8 PB0 PB2 INT2 <- _INT/SQW DS3231
Digital 9 PWM1 PB1 PB3 PWM0
Digital 10 _SS / PWM1 PB2 PB4 _SS / PWM0 SPI
Digital 11 MOSI / PWM2 PB3 PB5 MOSI SPI
Digital 12 MISO PB4 PB6 MISO SPI
Digital 13 SCK PB5 PB7 SCK SPI
 (Digital 14 PB0  T0 -> SDCard SPI _SS
 (Digital 15) PB1  T1 -> MCP4822 SPI _SS
SCL PC0 SCL I2C – Separate
SDA PC1 SDA I2C – Separate
PC2 TCK JTAG <- _CARD_DETECT
for uSD Card
PC3 TMS JTAG -> MCP4822 _LDAC
PC4 TDO JTAG -> SRAM SPI _SS
PC5 TDI JTAG -> EEPROM SPI _SS
PC6 TOSC1 <- 32768Hz Crystal
PC7 TOSC2 -> 32768Hz Crystal
XTAL1 PB6
XTAL2 PB7
 (Analog 6) PA6 -> LINE Input
 (Analog 7) PA7 -> MIC Input

ATmega Arduino USART in SPI Master Mode MSPIM

The AVR ATmega MCU used by the Arduino Uno and its clones and peers (Leonardo, Pro, Fio, LilyPad, etc) and the Arduino Mega have the capability to use their USART (Universal Serial Asynchronous Receiver Transmitter), also known as the Serial Port, as an additional SPI bus interface in SPI Master mode. This fact is noted in the datasheets of the ATmega328p, ATmega32u4, and the ATmega2560 devices at the core of the Arduino platforms, but until recently it hasn’t meant much to me.

Over the past 18 months I’ve been working on an advanced derivative of the Arduino platform, using an ATmega1284p MCU at its core. I consider the ATmega1284p device the “Goldilocks” of the ATmega family, and as such the devices I’ve built have carried that name. Recently I have been working on a platform which has some advanced analogue output capabilities incorporating the MCP4822 dual channel DAC, together with a quality headphone amplifier, and linear OpAmp for producing buffered AC and DC analogue signals. This is all great, but when it comes down to outputting continuous analogue samples to produce audio it is imperative that the sample train is not interrupted or the music simply stops!

The issue is that the standard configuration of the Arduino platform (over)loads the SPI interface with all of the SPI duties. In the case of the Goldilocks and other Arduino style devices I have ended up having the MicroSD card, some SPI EEPROM and SRAM, and the MCP4822 DAC all sharing same SPI bus. This means that the input stream of samples from the MicroSD card are interfering and time-sharing with the output sample stream to the DAC. The MicroSD card has a lot of latency, often taking hundreds of milliseconds to respond to a command, whereas the DAC needs a constant stream of samples with no jitter and no more than 22us between each sample. That is a conflict that is difficult to resolve. Even using large buffers is not a solution, as when streaming audio it is easy to consume MBytes of information; which is orders of magnitude more than can be buffered anywhere on the ATmega platform.

Other solutions using a DAC to generate music have used a “soft SPI” and bit-banging techniques to work around the issue. But this creates a performance limitation as the maximum sample output rate is strongly limited by the rate at which the soft SPI port can be bit-banged. There has to be a better way.

USART in SPI mode

The better way to attach SPI Slave devices to the ATmega platform is referenced in this overlooked datasheet heading: “USART in SPI mode”. Using the USART in “Master SPI Mode” (MSPIM) is may be limiting if you need to use the sole serial port to interact with the Arduino (ATmega328p), but once the program is loaded (in the case of using a bootloader) there is often no further need to use the serial port. But for debugging if there is only one USART then obviously it becomes uncomfortable to build a system based on the sole USART in SPI mode.

However in the case of the Goldilocks ATmega1284p MCU with two USARTs, the Arduino Leonardo with both USB serial and USART, and the Arduino Mega ATmega2560 MCU with four USARTs, there should be nothing to stop us converting their use to MSPIM buses according to need.

Excuse me for being effusive about this MSPIM capability in the AVR ATmega. It is not exactly a secret as it is well documented and ages old, but it is a great feature that I’ve simply not previously explored. But now I have explored it, I think it is worthwhile to write about my experience. Also, I think that many others have also overlooked this USART MSPIM capability, because of the dearth of objective review to be found on the ‘net.

Any ATmega datasheet goes into the detailed features and operation of the USART in SPI mode. I’ll go into some of the features in detail and what it means for use in real life.

  • Full Duplex, Three-wire Synchronous Data Transfer – The MSPIM does not rely on having a Slave Select line on a particular pin, and further it doesn’t rely on having both MOSI and MISO lines active at the same time. This means that it is possible to attach a SPI Slave device that doesn’t use the _SS to begin or end transactions with just two pins, being the XCK pin and the Tx pin. If a _SS is required (as in the MCP4822) then only three wires are required. The fact that the MISO (Rx) pin is optional saves precious pins too.
  • Master Operation – The MSPIM only works in SPI Master mode, which means that it is only really useful for connecting accessories. But in the Arduino world, that is what we are doing 99% of the time.
  • Supports all four SPI Modes of Operation (Mode 0, 1, 2, and 3) – yes, it does.
  • LSB First or MSB First Data Transfer (Configurable Data Order) – yes, it does.
  • Queued Operation (Double Buffered) – The MSPIM inherits the USART Tx double buffering capability. This is a function not available on the standard SPI interface and is a great thing. For example, to output a 16bit command two writes to the I/O register can follow each other immediately, and the resulting XCK has no delay between each Byte output. To output a stream of bytes the buffer empty flag can be used as a signal to load the next available byte, ensuring that if the next byte can be loaded with 16 instructions then we can generate a constant stream of bytes. In contrast with the standard SPI interface transmission is not buffered and therefore in Master Mode we’re invariably wait-looping before sending the next byte. This wastes cycles in between each byte in recognising completion, and then loading the next byte for transmission.
  • High Resolution Baud Rate Generator – yes, it is. The MSPIM baud rate can be set to any rate up to half the FCPU clock rate. Whilst there may be little need to run the MSPIM interface at less than the maximum for pure SPI transactions, it is possible to to use this feature, together with double buffered transmission, to generate continuous arbitrary binary bit-streams at almost any rate.
  • High Speed Operation (fXCKmax = FCPU/2) – The MSPIM runs at exactly the same maximum clock speed as the standard SPI interface, but through the double buffering capability mentioned above the actual byte transmission rate can be significantly greater.
  • Flexible Interrupt Generation – The MSPIM has all the same interrupts as the USART from which it inherits its capabilities. In particular the differentiation between buffer space available flag / interrupt and transmission complete flag / interrupt capabilities make it possible to develop useful arbitrary byte streaming solutions.

Implementation Notes

As the USART in normal mode and the USART in MSPIM mode are quite similar in operation there is little that needs to be written. The data sheet has a very simple initialisation code example, which in practice is sufficient for getting communications going. I would note that as there is no automatic Slave Select management, the _SS line needs to be manually configured as an output, and then set (high) appropriately until such time as the attached SPI device is to be addressed. Also note that the XCKn (USART synchronous clock output) needs to be set as an output before configuring the USART for MSPIM. And also to note that the transmission complete flag (TXCn) is not automatically cleared by reading (it is only automatically cleared if an Interrupt is processed), and needs to be manually cleared before commencing a transmission (by writing a 1 to the TXCn bit) it you are planning to use it to signal transaction completion in your code. The Transmit and Receive Data Register (UDRn) is also not automatically cleared, and needs to be flushed before use if a receive transaction is to synchronised to the transmitted bytes.

So the implementation of a simple initialisation code fragment looks like this:

SPI_PORT_DIR_SS |= SPI_BIT_SS;   // Set SS as output pin.
SPI_PORT_SS |= SPI_BIT_SS;       // Pull SS high to deselect the SPI device.
UBRR1 = 0x0000;
DDRD |= _BV(PD4);                // Setting the XCK1 port pin as output, enables USART SPI master mode (this pin for ATmega1284p)
UCSR1C = _BV(UMSEL11) | _BV(UMSEL10) | _BV(UCSZ10) | _BV(UCPOL1);
                                 // Set USART SPI mode of operation and SPI data mode 1,1. UCPHA1 = UCSZ10
UCSR1B = _BV(TXEN1);             // Enable transmitter. Enable the Tx (also disable the Rx, and the rest of the interrupt enable bits set to 0 too).
                                 // Set baud rate. IMPORTANT: The Baud Rate must be set after the Transmitter is enabled.
UBRR1 = 0x0000;                  // Where maximum speed of FCPU/2 = 0x0000

And a fragment of the code to transmit a 16 bit value looks like this. Note with this example there is no need to wait for the UDREn flag to be set between bytes, as we are only writing two bytes into the double transmit buffer. This means that the 16 clocks are generated on XCKn with no gap in delivery.

UCSR1A = _BV(TXC1);              // Clear the Transmit complete flag, all other bits should be written 0.
SPI_PORT_SS &= ~_BV(SPI_BIT_SS); // Pull SS low to select the SPI device.
UDR1 = write.value.u8[1];        // Begin transmission of first byte.
UDR1 = write.value.u8[0];        // Continue transmission with second byte.
while ( !(UCSR1A & _BV(TXC1)) ); // Check we've finished, by waiting for Transmit complete flag.
SPI_PORT_SS |= _BV(SPI_BIT_SS);  // Pull SS high to deselect the SPI device.

Results

Looking at the output generated by the two different SPI interfaces on the AVR ATmega, it is easy to see the features in action. In the first image we can see that the two bytes of the 16 bit information for the DAC are separated, as loading the next byte to be transmitted requires clock cycles AFTER the transmission completed SPIF flag has been raised.

DAC control using SPI bus.

DAC control using SPI bus.

In the case of the MSPIM output, we can’t recognise where the two bytes are separated, and the end of the transaction is triggered by the Transaction complete flag. This example shows that the MSPIM can be actually faster than the standard SPI interface, even though the maximum clock speed in both cases is FCPU/2.

DAC control using USART MSPIM bus.

DAC control using USART MSPIM bus.

The final image shows the Goldilocks DAC generating a 44.1kHz output signal, with dual 12 bit outputs. Whilst this is not fully CD quality, comparisons with other DAC solutions available on the Arduino platform have been favourable.

44.1kHz samples using USART MSPI output.

44.1kHz samples using USART MSPI output.

Conclusion

I am now convinced to use the USART MSPIM capability for the Goldilocks Analogue, and I think that it is time to write some generalised MSPIM interface routines to go into my AVRfreeRTOS Sourceforge repository to make it easy to use this extremely powerful capability.

Gameduino 2 with Goldilocks and EVE

My Gameduino 2 was delivered just a few weeks ago, and I’ve spent too much time with it already. It is the latest Kickstarter project by James Bowman. James has written a Gameduino 2 Book too.

Sourcecode for the below examples is located at Sourceforge AVRfreeRTOS.

Recently, I’ve used the Gameduino 2 to implement a multi-oscillator audio synthesizer GUI, using many FTDI EVE GPU co-processor widgets. The use of widgets linked with the integrated touch functionality really simplifies the programming of complex GUIs.

The ability to add a large touch screen, with integrated audio and accelerometer to any Arduino project is a great thing. Previously, you had to move to 32 bit processors with LVDS interfaces to work with LCD screens, but the new FT800 EVE Graphical Processing Unit (GPU) integrates all of the graphic issues and allow you to drive it with a very high level object orientated graphics language. For example it takes just one command to create an entire clock face with hour, minute, and second-hands.

The Gameduino 2, via the FT800 EVE chip, provides the following capabilities:

  • 32-bit internal color precision
  • OpenGL-style command set
  • 256 KBytes of video RAM
  • smooth sprite rotate and zoom with bilinear filtering
  • smooth circle and line drawing in hardware – 16x antialiased
  • JPEG loading in hardware
  • audio tones and WAV audio output
  • built-in rendering of gradients, text, dials, sliders, clocks and buttons
  • intelligent touch capabilities, where objects can be tagged and recognised.

The FT800 runs the 4.3 inch 480×272 TFT touch panel screen at 60 Hz and drives a mono headphone output.

EVE Block Diagram

First off, there’s a demo of some of the capabilities of the Gameduino 2. I’ll come to the drivers later, but the Arduino compatible platform used here is the Goldilocks ATmega1284P from Freetronics. The Goldilocks is in my opinion the best platform to use with the Gameduino 2. Firstly there is the extra RAM and Flash capabilities in line with the ATmega1284p MCU. But also importantly the Goldilocks holds the Pre-R3 Arduino Uno connector standard, with the SPI pins located correctly on Pins 11, 12, and 13. And the INT0 interrupt located on Pin 2. This means that it can be used with the Gameduino 2, out of the box. No hacking required.

Thank you for pledging on the Kickstarter Project page. Closed on November 19th 2015, with 124% funding. Now that the Kickstarter Pledges have been shipped, the new Goldilocks Analogue is available on Tindie.

I sell on Tindie

Must be addicted to these touch screens. I’ve just received an Australian designed 4D Systems FT843 Screen. It has possibly an identical screen to the Gameduino 2, but is based on a R3 Arduino shield format (SPI on ICSP) called the ADAM (Arduino Display Adapter Module), which means that it will work on any current Arduino hardware, without hacking. The FT843 ADAM supports a RESET line, which resolves the only problem I’ve noted with the Gameduino 2. Unfortunately, audio is not supported by a 3.5mm jack but rather by a pin-out option. The FT843 uses Swizzle 0, unlike the Gameduino 2 which uses Swizzle 3, and has the Display SPI Select on either D9 or D4 rather than on D8 like the Gameduino 2. Other than these simple configuration options, it similar.

4D Systems FT843 on Goldilocks 1284p

4D Systems FT843 on Goldilocks 1284p

Demo

The screen shows 5 sets of demonstrations. These demos are provided by FTDI, and typically in an Arduino Uno you would have to choose which of the 5 sets you want to see. With the extra capabilities of the Goldilocks, it is possible to load all of them simultaneously in 110kB of flash.

Set 0 focusses on individual commands that are loaded into the Display List. The Display List is essentially a list of commands that is executed or rendered for each frame of display. A Display List will be rendered indefinitely, until it is swapped by another Display List. Two Display Lists are maintained in a double buffering arrangement. One is written, whilst the other is displayed.

Set 1 exhibits some of the co-processor command capabilities, that allow complex objects to be created with only one command. A clock, slider, dial, or a rows of buttons can be created easily in this manner.

Set 2 shows the JPEG image rendering capabilities in RGB and in 8 bit mono.

Set 3 demonstrates custom font capabilities. There are 16 fonts available in the ROM of the FT800 EVE, but you can add your own as is desired.

Set 4 shows some advanced co-processor capabilities, such as touch tag recognition, no touch (zero MCU activity) screensaver, capturing screen sketches, and inbuilt audio options.

The main screen shows an analogue clock that is drawn with one co-processor command. Real time is generated by a 32,768Hz Crystal driving the Goldilocks Timer 2 for a system clock. The accuracy of the clock is limited only by the accuracy of the watch crystal, and I’ve built mine with a 5ppm version, which should be enough to keep within a few seconds per month.

Sample Application

The FTDI provided sample application covers most of the available commands and options for the FT800 EVE GPU.

The FT_SampleApp.h file contains definitions of functions implemented for the main application. These code snippets are not really useful beyond demonstrations of capability of the GPU, but never the less demonstrate how each specific feature of the FT800 EVE GPU can be utilised.

Driver

Because the FT800 EVE GPU has a very capable object orientated graphics language, the FTDI drivers present a very capable high level interface to the user. FTDI have prepared an excellent starting point from which I could easily make customisations suitable for the AVR ATmega Arduino hardware that I prefer to use.

The FTDI driver set is separated into a Command Layer, and into a Hardware Abstraction Layer (HAL). This separation makes it easy to customise for the AVR ATmega platform, but retains the standard FTDI command language for easy implementation of their example applications, and portability of code written for their command language.

To use the FT800 EVE drivers for the Gameduino 2 it is only necessary to include the FT_Platform.h file in the main program. This file contains references to all of the other files needed.

#include "../lib_ft800/FT_DataTypes.h"
#include "../lib_ft800/FT_X11_RGB.h"
#include "../lib_ft800/FT_Gpu.h"
#include "../lib_ft800/FT_Gpu_Hal.h"
#include "../lib_ft800/FT_Hal_Utils.h"
#include "../lib_ft800/FT_CoPro_Cmds.h"
#include "../lib_ft800/FT_API.h"

The FT_DataTypes.h file contains FTDI type definitions for the specific data types needed for the FT800 EVE GPU. This is mainly used to abstract the drivers for varying MCU. For the AVR it is not absolutely necessary, but it will help when the code is used on other platforms.

The FT_X11_RGB.h file contains the standard colour set used in X11 colours and on the Web, which are stored PROGMEM. I’ve written a small macro that will insert these into commands needing 24 bit colour settings. These colours will be stored and referenced from PROGMEM when they are called from either of the X11 specific macros defined in FT_Gpu.h If they are not called from the program, they will be discarded by the linker and not waste space in the final linked program.

X11 Colours

The FT_Gpu.h file contains all the definitions for command and register setting options. I have significantly rearranged the layout and comments in this file, compared to the FTDI version. Hopefully it is arranged in a way that allows options applying to specific commands and registers to be quickly located.

By writing DL commands to the Display List which are configured by the options in the FT_Gpu.h file it is possible to control most of the low level functions in the FT800 EVE GPU. The Display List is used by the FT800 GPU to render the screen, so it is only the contents of the active Display List that appear on the screen.

In the FT_Gpu_Hal.h file the commands specific to the SPI bus (or the I2C bus if this transfer mechanism is being used) are defined.

I have simplified out some HAL options provided by FTDI for high performance MCU, that might be constrained writing to the SPI bus at only 30MHz, the maximum FT800 SPI bus rate. The Goldilocks SPI bus only runs at 11MHz, and the standard Arduino Uno SPI bus only runs at 8 MHz, so those optimisations don’t help, and they also consume RAM for streaming buffers.

But, I have integrated a multi-byte SPI transfer into the HAL, which don’t use additional RAM buffer space, as they write via a pointer. This is probably the best way to work the SPI bus in the Arduino environment. I have also implemented multi byte SPI transfer directly from the PROGMEM for Strings, and for precomputed commands.

As a preferred option, I’ve implemented PROGMEM storage of Strings for all commands. The commands utilising RAM storage of Strings are retained for compatibility, and to allow computed Strings to be used.

All of the FTDI provided commands now have optional *_P variants which take PROGMEM strings, rather than RAM strings. This saves eleven hundred bytes of RAM used for strings, just in the demonstration programs provided by FTDI and shown in the Demo!

The FT_Hal_Util.h file contains some simple utility macros.

The FT_CoPro_Cmds.h file contains definitions for all of the available co-processor commands. These command are written to the co-processor command buffer, and are used to generate low level commands that appear in the Display List and be rendered for each frame.

Many of the co-processor commands replicate functionality of setting specific registers with options via the Display List GPU commands. This is useful because it is possible to programme the co-processor to implement a task and remain at the object orientated view of the screen, even though the a individual command may be a simple GPU setting that could have been done at Display List command level. Having all the commands available at co-processor level obviates the need to switch between the two “modes” of operation and thought.

I extracted a few of the standard functions that are needed irrespective of the specific application into an API. The FT_API.h file contains these simple command sequences, for booting up the Gameduino 2, and for managing the screen brightness. It also contains precalculated simplified sin, cos, and atan functions useful when drawing circles and clocks.

The API level also contains calls on the Hardware Abstraction Layer that are simply passed through. These calls are flattened by avr-gcc to save digging ourselves into a stack wasting function call hole.

And, of course, everything is integrated into the freeRTOS v8.0.0 port that I support on Sourceforge, AVRfreeRTOS, which gives non-blocking timing, tasks, semaphores, queues, and all aspects of freeRTOS that are so great.

As an example of the power of this combination of freeRTOS and the FT800 object orientated command language we can describe the method used to create an accurate well rendered clock on the Gameduino 2 screen. Using the 3 commands below, we obtain the clock face seen in my demo video main screen.

time(&currentTime); // get a time stamp in current seconds elapsed from Midnight, Jan 1 2000 UTC (the Y2K 'epoch'), as maintained by freeRTOS.
localtime_r(&currentTime, &calendar); // converts the time stamp pointed to by currentTime into broken-down time in a calendar structure, expressed as Local time.
FT_GPU_CoCmd_Clock(phost, FT_DispWidth - (FT_DispHeight/2), FT_DispHeight/2, FT_DispHeight/2 - 20, OPT_3D, calendar.tm_hour, calendar.tm_min, calendar.tm_sec, 0); // draw a clock in 3D rendering.

I’ve updated the clock function to include a touch screen time setting interface. Using the FT800 Touch Tags, and Button generation, this process is really incredibly easy.

Hardware

I’ve taken the liberty of borrowing some of James’ pictures for this story. They can originally be found here.

Gameduino 2 Pinout

Note that because of the wrap around connector and cable for the LCD screen, it is not possible to use the Arduino R3 pin out. The SPI bus pins are located at the traditional location on Pin 11 though Pin 13. Unless you want to hack your board, you’re limited to using Arduino Uno style boards.

Gameduino 2 Shield

Unfortunately, the FTDI FT800 Reset pin has not been implemented by the Gameduino 2. Using an ISP to programme the Arduino usually “accidentally” puts the FT800 EVE GPU into an unsupported state. This means that the Gameduino 2 and Arduino usually have to be power-cycled or hard Reset following each programming iteration. It would have been good to tie the FT800 Reset pin to the Arduino Reset pin via a short (ms) delay chip, to obviate the need to remove power to generate the hard Reset for the FT800.

Hello World & other examples

I thought it might be interesting to compare the code required to achieve the demonstration outcomes that James Bowman provides on the Gameduino2 site, with the code required to achieve the same result using freeRTOS and the FTDI style driver. So I’ve implemented three simple examples, “Hello World”, “Sprites”, and “Blobs” from his library.

All of the examples have been built using an Arduino Uno ATmega328p as the MCU hardware platform.

helloworld

The Hello World application simply initialises the Gameduino2, sets the colour to which the screen shall be cleared, and then writes text with the OPT_CENTER option to center it in the X and Y axis. As there is no delay, this is written as often and as fast as the MCU can repeat the loop.

#include <SPI.h>
#include <GD2.h>

void setup()
{
  GD.begin();
}

void loop()
{
  GD.ClearColorRGB(0x103000);
  GD.Clear();
  GD.cmd_text(240, 136, 31, OPT_CENTER, "Hello world");
  GD.swap();
}

The same result can be generated in C using freeRTOS and the FTDI Drivers. I have commented extensively within the code below.

/* freeRTOS Scheduler include files. */
/* these four header files encompass the full freeRTOS real-time OS features,
   of multiple prioritised tasks each with their own stack space, queues for moving data,
   and scheduling tasks, and semaphores for controlling execution flows */
#include "FreeRTOS.h"
#include "task.h"
#include "queue.h"
#include "semphr.h"

/* Gameduino 2 include file. */
#include "FT_Platform.h"

/*------Global used for HAL context management---------*/
extern FT_GPU_HAL_Context_t * phost;           // optional, just to make it clear where this variable comes from.
                                               // It is automatically included, so this line is actually unnecessary.

/*--------------Function Definitions-------------------*/

int main(void) __attribute__((OS_main));       // optional, just good practice.
                                               // Saves a few bytes of stack because the return from main() is not implemented.

static void TaskWriteLCD(void *pvParameters);  // define a single task to write to Gameduino 2 LCD.
                                               // typically multiple concurrent tasks are defined,
                                               // but in this case to replicate the Arduino environment, just one is implemented.

/*-----------------Functions---------------------------*/
/* Main program loop */
int main(void)
{
  xTaskCreate(            // create a task to write on the Gameduino 2 LCD
       TaskWriteLCD
    ,  (const portCHAR *)"WriteLCD"
    ,  128                // number of bytes for this task stack
    ,  NULL
    ,  3		  // priority of this task (1 is highest priority, 4 lowest).
    ,  NULL );

  vTaskStartScheduler();  // now freeRTOS has taken over, and the pre-emptive scheduler is running.
}

 

/*-----------------------------------------------------------*/
/* Tasks                                                     */
/*-----------------------------------------------------------*/

static void TaskWriteLCD(void *pvParameters) // A Task to write to Gameduino 2 LCD
{
  (void) pvParameters;

  FT_API_Boot_Config();  // initialise the Gameduino 2.

  while(1)               // a freeRTOS task should never return
  {
    FT_API_Write_CoCmd( CMD_DLSTART );                       // initialise and start a Display List
//  FT_API_Write_CoCmd( CLEAR_COLOR_RGB(0x10, 0x30, 0x00) ); // set the colour to which the screen is cleared (using RGB triplets) as in GD2 library OR
    FT_API_Write_CoCmd( CLEAR_COLOR_X11(FORESTGREEN) );      // set the colour to which the screen is cleared (using X11 colour definitions)
    FT_API_Write_CoCmd( CLEAR(1,1,1) );                      // clear the screen

    FT_GPU_CoCmd_Text_P(phost,FT_DispWidth/2, FT_DispHeight/2, 31, OPT_CENTER, PSTR("Hello world"));
      // write "Hello World" to X and Y centre of screen using OPT_CENTER  with the largest font 31
      // The string "Hello world" is stored in PROGMEM
      // Functions with *_P all use PROGMEM Strings (and don't consume RAM)
      // FT_DispWidth and FT_DispHeight are global variables set to orientate us in a flexible consistent way,
      // without hard coding the screen resolution.

    FT_API_Write_CoCmd( DISPLAY() );                         // close the Display List (DL) opened by CMD_DLSTART()
    FT_API_Write_CoCmd( CMD_SWAP );                          // swap the active Display List (double buffering), to display the new "Hello World" commands written to the Display List
  }
}

sprites

The Sprites application is similar to the original one built for the Gameduino, but here each sprite is rotating around a random point. The 2001 random points are stored in a PROGMEM array sprites. This takes 8K of flash. A second PROGMEM array circle holds the 256 XY coordinates to make the sprite move in a circle. The only RAM used is a single byte t used to keep track of the current rotation position, by counting iterations.

#include <EEPROM.h>
#include <SPI.h>
#include <GD2.h>

#include "sprites_assets.h"

void setup()
{
  GD.begin();
  GD.copy(sprites_assets, sizeof(sprites_assets));
}

static byte t;

void loop()
{
  GD.Clear();
  GD.Begin(BITMAPS);
  byte j = t;
  uint32_t v, r;

  int nspr = min(2001, max(256, 19 * t));

  PROGMEM prog_uint32_t *pv = sprites;
  for (int i = 0; i &lt; nspr; i++) {
    v = pgm_read_dword(pv++);
    r = pgm_read_dword(circle + j++);
    GD.cmd32(v + r);
  }

  GD.ColorRGB(0x000000);
  GD.ColorA(140);
  GD.LineWidth(28 * 16);
  GD.Begin(LINES);
  GD.Vertex2ii(240 - 110, 136, 0, 0);
  GD.Vertex2ii(240 + 110, 136, 0, 0);

  GD.RestoreContext();

  GD.cmd_number(215, 110, 31, OPT_RIGHTX, nspr);
  GD.cmd_text( 229, 110, 31, 0, "sprites");

  GD.swap();
  t++;
}

The code in freeRTOS is similar. I have commented within the code.

/* freeRTOS Scheduler include files. */
#include "FreeRTOS.h"
#include "task.h"
#include "queue.h"
#include "semphr.h"

/* Gameduino 2 include file. */
#include "FT_Platform.h"

// The include file containing the sprite graphics, and the special command sequence
#include "sprites_assets.h

/*------Global used for HAL context management---------*/
extern FT_GPU_HAL_Context_t * phost;           // optional, just to make it clear where this variable comes from

/*--------------Function Definitions-------------------*/

int main(void) __attribute__((OS_main));       // optional, just good practice

static void TaskWriteLCD(void *pvParameters);  // define a single task to write to Gameduino 2 LCD

/*-----------------Functions---------------------------*/

/* Main program loop */
int main(void)
{
  xTaskCreate(             // create a task to write on the Gameduino 2 LCD
    TaskWriteLCD
    ,  (const portCHAR *)"WriteLCD"
    ,  128                 // number of bytes for this task stack
    ,  NULL
    ,  3                   // priority of task (1 is highest priority, 4 lowest).
    ,  NULL );

  vTaskStartScheduler();   // now freeRTOS has taken over, and the pre-emptive scheduler is running
}

 

/*-----------------------------------------------------------*/
/* Tasks                                                     */
/*-----------------------------------------------------------*/

static void TaskWriteLCD(void *pvParameters) // A Task to write to Gameduino 2 LCD
{
  (void) pvParameters;

  uint8_t t = 0;         // iterate over the code for 255 times, before restarting with 256 sprites where t = 0

  FT_API_Boot_Config();  // initialise the Gameduino 2.
  FT_GPU_HAL_WrCmdBuf_P(phost, sprites_assets, sizeof(sprites_assets));
    // Copy James' magic list of commands into the command buffer.
    // These co-processor commands are "compiled" into their 4 byte equivalents, and I haven't decoded them in detail.
    // But, since the FT800 is reading the same double word codes, it doesn't really matter how they're generated.

  while(1)               // a freeRTOS task should never return
  {
    FT_API_Write_CoCmd( CMD_DLSTART );       // initialise and start a Display List (DL)
    FT_API_Write_CoCmd( CLEAR(1,1,1) );      // clear the screen

    FT_API_Write_CoCmd( BEGIN(BITMAPS) );    // start to write BITMAPS into the DL
    uint8_t j = t;
    uint32_t v;
    uint32_t r;
    int16_t nspr = min(2001, max(256, 19 * t));
    ft_prog_uint32_t * pv = sprites;         //  pv is the sprite BITMAP pointer

    for (uint16_t i = 0; i < nspr; ++i) {
      v = pgm_read_dword(pv++);              // determine which sprite we're controlling
      r = pgm_read_dword(circle + j++);      // circle is the rotation control
      FT_GPU_HAL_WrCmd32(phost, v + r);      // the sprite address and the location are written here to the co-processor
    }
    FT_API_Write_CoCmd( END());              // finish writing BITMAPS into the Display List

    FT_API_Write_CoCmd( BEGIN(LINES) );      // start to write LINES into the Display List
    FT_API_Write_CoCmd( COLOR_RGB(0x00, 0x00, 0x00) );  // set the line colour to black 0x000000
    FT_API_Write_CoCmd( COLOR_A(140) );                 // set alpha channel transparency
    FT_API_Write_CoCmd( LINE_WIDTH( 28 * 16) );
    FT_API_Write_CoCmd( VERTEX2II(240 - 110, 136, 0, 0) );  // start to draw an alpha transparency background line
    FT_API_Write_CoCmd( VERTEX2II(240 + 110, 136, 0, 0) );  // finish the line
    FT_API_Write_CoCmd( END() );             // finish writing LINES into the Display List

    FT_API_Write_CoCmd( RESTORE_CONTEXT() ); // With no prior SAVE_CONTEXT() command, this restores the default colours and values.

    FT_GPU_CoCmd_Number(phost, 215, 110, 31, OPT_RIGHTX, nspr);    // write a number.
    FT_GPU_CoCmd_Text_P(phost, 229, 110, 31, 0, PSTR("sprites"));  // write using a PROGMEM stored string function, to save RAM
      //  phost is a pointer to the context for the Gameduino2.
      //  Mainly used where there may be multiple screens present, but in this case several state and semaphore items are maintained.

    FT_API_Write_CoCmd( DISPLAY() );          // close the active Display List (DL) opened by CMD_DLSTART()
    FT_API_Write_CoCmd( CMD_SWAP );           // Do a DL swap to render the just written DL

    t++;    // t will roll over and will restart the number of sprites to the minimum of 256
  }
}

main2

blobs is a sketching demonstration, as you paint on the touch screen a trail of circles follows.
The code keeps a history of the last 128 touch positions, and draws the transparent, randomly coloured circles.

#include <EEPROM.h>
#include <SPI.h>
#include <GD2.h>

#define NBLOBS      128
#define OFFSCREEN   -16384

struct xy {
  int x, y;
} blobs[NBLOBS];

void setup()
{
  GD.begin();

  for (int i = 0; i < NBLOBS; i++) {
    blobs[i].x = OFFSCREEN;
    blobs[i].y = OFFSCREEN;
  }
}

void loop()
{
  static byte blob_i;
  GD.get_inputs();
  if (GD.inputs.x != -32768) {
    blobs[blob_i].x = GD.inputs.x << 4;
    blobs[blob_i].y = GD.inputs.y << 4;
  } else {
    blobs[blob_i].x = OFFSCREEN;
    blobs[blob_i].y = OFFSCREEN;
  }
  blob_i = (blob_i + 1) & (NBLOBS - 1);

  GD.ClearColorRGB(0xe0e0e0);
  GD.Clear();

  GD.Begin(POINTS);
  for (int i = 0; i < NBLOBS; i++) {
    // Blobs fade away and swell as they age
    GD.ColorA(i << 1);
    GD.PointSize((1024 + 16) - (i << 3));

    // Random color for each blob, keyed from (blob_i + i)
    uint8_t j = (blob_i + i) & (NBLOBS - 1);
    byte r = j * 17;
    byte g = j * 23;
    byte b = j * 147;
    GD.ColorRGB(r, g, b);

    // Draw it!
    GD.Vertex2f(blobs[j].x, blobs[j].y);
  }
  GD.swap();
}

The code in freeRTOS is similar, but the touch functionality is derived directly from the FT800 register containing the most recent screen touch location. I have commented within the code.

/* freeRTOS Scheduler include files. */
#include "FreeRTOS.h"
#include "task.h"
#include "queue.h"
#include "semphr.h"

/* Gameduino 2 include file. */
#include "FT_Platform.h"

#define NBLOBS       128
#define OFFSCREEN   -16384

/*----------Global used for HAL management-------------*/
extern FT_GPU_HAL_Context_t * phost;           // optional, just to make it clear where this comes from

struct xy {										// somewhere to store all the blob locations
  int16_t x, y;
} blobs[NBLOBS];

/*--------------Function Definitions-------------------*/

int main(void) __attribute__((OS_main));       // optional, just good practice

static void TaskWriteLCD(void *pvParameters);  // define a single task to write to Gameduino 2 LCD

/*-----------------Functions---------------------------*/

/* Main program loop */
int main(void)
{
  xTaskCreate(            // create a task to write on the Gameduino 2 LCD
    TaskWriteLCD
    ,  (const portCHAR *)"WriteLCD"
    ,  128                // number of bytes for the task stack
    ,  NULL
    ,  3                  // priority of task (1 is highest priority, 4 lowest).
    ,  NULL );

  vTaskStartScheduler();  // now freeRTOS has taken over, and the scheduler is running
}

 


/*-----------------------------------------------------------*/
/* Tasks                                                     */
/*-----------------------------------------------------------*/

static void TaskWriteLCD(void *pvParameters) // A Task to write to Gameduino 2 LCD
{
 (void) pvParameters;

  FT_API_Boot_Config();     // initialise the Gameduino 2.
  FT_API_Touch_Config();    // initialise the FT800 Touch capability.

  for (uint8_t i = 0; i < NBLOBS; ++i)   {     blobs[i].x = OFFSCREEN;     blobs[i].y = OFFSCREEN;   }   while(1)                  // a freeRTOS task should never return   {     static uint8_t blob_i;  // the blob we're currently processing     uint32_t readTouch;     // xy coordinates of a touch are stored in uint32_t     // this is the touch interface stuff     readTouch = FT_GPU_HAL_Rd32(phost, REG_TOUCH_SCREEN_XY);// the screen location of the last touch is stored in REG_TOUCH_SCREEN_XY     if (readTouch != NIL_TOUCH_XY)                          // if there was a touch     {       blobs[blob_i].x  = (int16_t)((readTouch >> 16) & 0xffff) << 4; // read where x axis touch occurred, and scale it
      blobs[blob_i].y = (int16_t)(readTouch & 0xffff) << 4; // read where y axis touch occurred, and scale it
    } else {
      blobs[blob_i].x = OFFSCREEN;         // if there was no touch, draw the blob OFFSCREEN
      blobs[blob_i].y = OFFSCREEN;
    }
    blob_i = (blob_i + 1) & (NBLOBS - 1);  // increment to the next blob for touch interaction

    // this is the display interface stuff
    FT_API_Write_CoCmd( CMD_DLSTART );      // initialise and start a display list (DL)

    FT_API_Write_CoCmd( CLEAR_COLOR_RGB(0xe0, 0xe0, 0xe0) );// set the colour to which the screen will be cleared
    FT_API_Write_CoCmd( CLEAR(1,1,1) );     // clear the screen

    FT_API_Write_CoCmd( BEGIN(POINTS) );    // start to write POINTS into the Display List (DL)

    for (uint8_t i = 0; i < NBLOBS; ++i)
    {
      // Blobs fade away and swell as they age
      FT_API_Write_CoCmd( COLOR_A(i << 1) ); // set an alpha transparency
      FT_API_Write_CoCmd( POINT_SIZE((1024 + 16) - (i << 3)) );

      // Random colour for each blob, keyed from (blob_i + i)
      uint8_t j = (blob_i + i) & (NBLOBS - 1);
      uint8_t r = j * 17;
      uint8_t g = j * 23;
      uint8_t b = j * 147;
      FT_API_Write_CoCmd( COLOR_RGB(r, g, b) );

      // Draw it!
      FT_API_Write_CoCmd( VERTEX2F(blobs[j].x, blobs[j].y) );
    }

    FT_API_Write_CoCmd( END() );            // finish writing POINTS into the active DL

    FT_API_Write_CoCmd( DISPLAY() );        // close the active Display List (DL)
    FT_API_Write_CoCmd( CMD_SWAP );         // Do a DL swap to render the just written DL
    }
}

I intend to build a few more demonstrations of the code, and to copy some games that James has already implemented, because I’m not a game designer.

freeRTOS and libraries for AVR ATmega with Eclipse IDE

I’ve created a Sourceforge project as a place to host all my current tools and working environment. The Sourceforge site is now 4 years old, and there’s a GitHub site too, which is now the most up to date repository

Preferred: Github freeRTOS & libraries for AVR ATMEGA

Secondary: Sourceforge freeRTOS & libraries for AVR ATMEGA

The Sourceforge repository has become so complex, with so many libraries, I thought that it was about time to make a simple version, which has the minimum implementation to get started. No additional libraries included. One timer option, using the watchdog timer. One heap option, using avr-libc malloc. One example application, just a blink with two tasks, for Uno, Mega, and Goldilocks boards.

Github minimum AVRfreeRTOS

The thing about open source. Sometime you have to give back.

Things I’m really happy about:

  • Arduino Uno family ATmega328p, Freetronics EtherMega (Arduino Mega2560), and Goldilocks ATmega1284p, scheduling and IO works.
  • Being able to use any Timer on the AVR as the system Tick. In practice this means Timer0 on 328p (Arduino Uno), Timer3 on 2560 (Arduino Mega) and 1284p (Pololu SVP) and Timer2 on 1284p with 32.768kHz watch crystal (Freetronics Goldilocks). The watchdog timer has also been implemented, and if there is no critical need for accurate timing, this is the lowest resource impact system tick.
  • Converting all of the relevant libraries to be friendly to a RTOS system. No delay busy-wait loops etc. Everything defers to (is interruptible by) the scheduler when waiting, or is driven from interrupts.
  • Having many finished projects, that are good demonstrations of lots of AVR and freeRTOS capabilities.
  • Having the Sparkfun LCD Shield working properly, with printf string formatting.
  • Having the Rugged Circuits QuadRAM 512kByte and MegaRAM 128kByte RAM extensions working on ATmega2560.
  • Porting ChaN FatF microSD card support for a variety of uSD shield cages.
  • Porting Wiznet W5100, W5200, and W5500 drivers for Arduino Ethernet shields.
  • Porting Wiznet and uIP DHCP and HTTP applications, creating options for implementing a basic web server.
  • Properly implementing semaphores for access to resources (ports, interfaces, ADC, LCD).
  • Properly implementing queues for transferring data between tasks (threads).

The repository of files on Sourceforge freeRTOS & libraries for AVR ATMEGA is a working collection for a freeRTOS based platform using the AVR-GCC and AVRDUDE platform. The development environment used was Eclipse IDE.

With the Eclipse IDE the C Development Environment (CDE), and the AVR plug-in are both needed. It is assumed that the AVR avr-libc libraries are installed.

The freeRTOS folder contains the most recent version 8.2.3 of freeRTOS, but it has been abridged down to only those files relevant for AVR GCC. The port.c file has been extensively modified to allow the use of either of the 328p Timer0 or Timer1 timers. And, the use of Timer3 on the Pololu SVP which has uses a 1284p. Timer 3 for Arduino Mega using a 2560 also works. Timer2 support has been added for the Freetronics Goldilocks and its 32,768kHz crystal. A Real Time system_tick is added using time.h functionality added to the system libraries described below.

The freeRTOSBoardDefs.h file contains most of the variables that you’ll need to change regularly.

There are some relevant and often used libraries added to the basic freeRTOS capabilities.

  • lib_io: contains often used I/O digital and ADC routines borrowed from Pololu.
  • lib_io: contains the tools to use the TWI (non-trademarked I2C) bus. It contains integrated interrupt driven master and slave routines
  • lib_io: contains the tools to use the SPI bus.
  • lib_io: contains routines to drive the serial interface. there are three versions; avrSerial for use before the freeRTOS scheduler has been enabled, and xSerial for use during normal operations. xSerial is interrupt driven and uses an optimised ring buffer. xSerialN is further generalised to allow multiple simultaneous serial ports.
  • lib_ext_ram: contains routines to drive the Rugged Circuits QuadRam on Arduino Mega2560, or Freetronics EtherMega.
  • lib_util: Optimised CRC calculations.
  • lib_util: Extended alpha (string) to integer (binary, octal, decimal, hexdecimal) conversion.
  • lib_time: Real time calculations, from avr-libc upstream, providing esoteric time and date calculations.
  • lib_rtc: drivers for the DS1307 RTC using I2C.
  • lib_fatf: contains ChaN’s FatF FAT32 libraries for driving the microSD card.
  • lib_iinchip: contains the W5100 drivers and the W5200 drivers from Wiznet.
  • lib_inet: contains a DHCP, and HTTP implementation.
  • lib-uIP: contains the uIP implementation derived from Contiki2.7, implemented on MACRAW mode of W5100/W5200, and extensible.
  • lib_ft800: contains optimised drivers for the Gameduino2, a FTDI FT800 implementation, with LCD and touch screen support.

Some more recent posts are here:

Arduino AVRfreeRTOS

Goldilocks Analogue Synthesiser

Goldilocks Analogue Prototyping 4

Melding freeRTOS with ChaN’s FatF & HD44780 LCD on Freetronics EtherMega

Rugged Circuits QuadRAM on Freetronics EtherMega

Quick review of Freetronics EtherMega

Description of the AVR Pong multi-processor game.

Additional steps to use the Mega2560

EtherMega (Arduino Mega2560) and FreeRTOS

I sell on Tindie

Step-by-step Instructions

Our Destination:

On completing these instructions you should have an Eclipse IDE (Integrated Development Environment) installed with all relevant libraries installed, to use the freeRTOS, and the libraries I’ve modified, to build projects (Eclipse term for a set of code) of your own.

We’re Assuming:

These instructions are based on an Ubuntu LTS install, but the path to the destination is not complex, and can be roughly followed for any installation platform.

Step 0. As usual on an Ubuntu (Debian) system, refresh the software sources.

sudo apt-get update

Step 1. Install the AVR Libraries.

Together, avr-binutils, avr-gcc, and avr-libc form the heart of the Free Software toolchain for the Atmel AVR microcontrollers. They are further accompanied by projects for in-system programming software (uisp, avrdude), simulation (simulavr) and debugging (avr-gdb, AVaRICE).
sudo aptitude install avr-libc avrdude binutils-avr gcc-avr gdb-avr

Step 2. Install the Arduino environment.

Doesn’t hurt to have the Arduino environment available. It can be used for programming boot-loaders (using AVR-ISP code), and generally for checking health of equipment, using known good example code.

This will pull in some extra libraries that the Arduino platform needs.

sudo aptitude install arduino

 

Step 3. Install the Eclipse IDE.

It is not necessary to use or install an IDE to develop with freeRTOS, or with any other system. It is easy to use makefiles and the command line with avr-gcc and avrdude. In fact, I didn’t use Eclipse for a long time. And, when I first started to use it, it felt very unnatural and clumsy.

However, now I’ve been using it for some time I highly recommend it, for the ability to see deeper into the code (definitions are detailed on mouse over), and to compare (live differences) and roll-back code to any step of your editing process.

Again, installation is easy with Ubuntu (Debian), but it can take a while. Lots of things get installed along with it.

sudo aptitude install eclipse

Step 4. Select the C & C++ development tools within Eclipse.

Eclipse is a Java based platform, but it works just as well with C, and C++, as it does with a wide variety of languages. Getting the C Development Tools (CDT) is the first step to a C environment that we’ll be using.

Open Eclipse, and lock it to your launcher. You’ll be using it frequently.

Using the Menus, click:

Help>>Install New Software…>>Add…

CDT Indigo http://download.eclipse.org/tools/cdt/releases/indigo

Select only “CDT Main Features”, and install these plugin development tools.

Step 5. Select the AVR development environment within Eclipse.

The AVR environment includes direct access to the avrdude downloading tool for one-click programming of your AVR devices.

Using the Menus, click:

Help>>Install New Software…>>Add…

AVR Plugin http://avr-eclipse.sourceforge.net/updatesite/

Select “CDT Optional Features”, and install these plugin development tools.

Step 5c. Select C/C++ Perspective

First you need to select the right perspective, being C/C++. Top right there is a button showing “Java”. Just to the left is a button (like a window) for selecting perspective. Select

Other…>>C/C++

When that is finished, you should have Eclipse menu button containing a AVR* with a green down arrow. That is the button used to program the device.

Step 6. Define a freeRTOS static library project.

There are lots of short cuts, and alternative ways to achieve things using context sensitive menus in Eclipse. I’ll concentrate on the top menu bar options, though you can get most things from a context menu click in the right window.

File>>New>>C Project: AVR Cross Target Static Library: Empty Project

A static library project is never run by itself. It is always linked to by other projects, called AVR Cross Target Applications.

Give the project a name (perhaps freeRTOS82x).

Now a project will apear in the “Project Explorer” window. Select it. We are going to set some options relating to this project.

Project>>Build Configurations>>Set Active>>Release

Project>>Properties

AVR:Target Hardware: MCU Type: ATmega328p (or other depending on hardware)

AVR:Target Hardware: MCU Clock Frequency: 16000000 (for Arduino hardware or other depending on your hardware)

C/C++ Build: Configuration: [All Configurations] (make sure this is set for all following configurations)

C/C++ Build: Environment: AVRTARGETFCPU: 16000000

C/C++ Build: Environment: AVRTARGETMCU: atmega328p

C/C++ Build: Settings: AVR Compiler: Optimisation: Other Optimisation Flags: -ffunction-sections -fdata-sections -mcall-prologues -mrelax (and use -Os or -O2)

Now we are going to add just the freeRTOS files, from the subdirectory within the freeRTOS82x_All_Files.zip file that you have downloaded from Sourceforge, and extracted somewhere sensible.

File>>Import…>>General:File System

Select the “into folder” as the project name you just created, and “Select All” for the import on the freeRTOS subdirectory. That should import the entire freeRTOS system. Spend some time browsing, if you like.

NOTE. Do NOT import the entire contents of the freeRTOS82x_All_Files.zip file. At this stage just import contents of the freeRTOS subdirectory.

Now we define the include library for the build. Remember to select [All Configurations] first.

Project>>Properties>>C/C++ Build>>Settings: AVR Compiler: Directories 

Add the from the “Workspace…”: freeRTOS82x/include

“${workspace_loc:/${ProjName}/include}”

Now there are fouralternative memory management routines, explained in the freeRTOS documentation. We are going to use the heap_2.c version, so we need to exclude the other three files from the build. In the project explorer RIGHT CLICK (context menu) each one then exclude them.

./MemMang/heap_1.c

./MemMang/heap_3.c

./MemMang/heap_4.c

Resource Configurations>>Exclude from Build…: Select All

Following this step, it should be possible to compile the library.

Project>>Build All

If there are any ERRORS, then go back and check the configurations for the project. Sometimes they may be changed, forgotten, or otherwise different from what you expected.

There will be some WARNINGS, relating to the usage of different Timers. I added these warnings to keep these things front of mind, as depending on which hardware I’m using the ./include/FreeRTOSBoardDefs.h file needs to be managed to suit.

Step 7. Define an Application Project.

An Application will generate the final hex code that you upload to the AVR with avrdude. This final code is created from the freeRTOS static library code generated above, together with code contained in the avr-libc, and any other linked projects.

We are going to import the UnoBlink or MegaBlink project as it makes a good example. Without a display, or real-time-clock module, it will only flash a LED. But, least we know it is alive.

To get started create a new project as below.

 File>>New>>C Project: AVR Cross Target Application: Empty Project

Give the project a name (perhaps MegaBlink or retrograde).

Now a project will appear in the “Project Explorer” window. Select it. We are going to set some options relating to this project.

Project>>Build Configurations>>Set Active>>Release

Project>>Properties

AVR:AVRDUDE:Programmer:New…

Configuration name: Arduino or Freetronics 2010

Programmer Hardware: Atmel STK500 Version 1.x firmware

Override default port: /dev/ttyUSB0 (FTDI USB) OR /dev/ttyACM0 (AVR USB)

Override default baudrate: as or if required.

AVR:Target Hardware: MCU Type: ATmega328p (or other depending on hardware)

AVR:Target Hardware: MCU Clock Frequency: 16000000 (or other depending on hardware)

C/C++ Build: Configuration: [All Configurations] (make sure this is set for all following configurations)

C/C++ Build: Environment: AVRTARGETFCPU: 16000000

C/C++ Build: Environment: AVRTARGETMCU: atmega328p

C/C++ Build: Settings: AVR Compiler: Directories: “${workspace_loc:/freeRTOS82x/include}”

C/C++ Build: Settings: AVR Compiler: Optimisation: Other Optimisation Flags: -mcall-prologues -mrelax (and use -Os or -O2)

C/C++ Build: Settings: AVR C Linker: General: Other Arguments -Wl,–gc-sections

C/C++ Build: Settings: AVR C Linker: Libraries: Add “m” without quotes. m is the standard math library, which should be included in most projects.

C/C++ Build: Settings: AVR C Linker: Objects: Other Objects Here you need to add the compiled freeRTOS library. And this is the only place where the Debug and Release builds are different.

With Release Build selected, paste “${workspace_loc:/freeRTOS82x/Release/libfreeRTOS82x.a}”

With Debug Build selected, paste “${workspace_loc:/freeRTOS82x/Debug/libfreeRTOS82x.a}”

Or select the Workspace option to navigate to the actual assembler files to be linked into the project.

Project References: freeRTOS82x ticked.

Now we are going to add the MegaBlink (or retrograde) files, from the MegaBlink.zip (or retrograde.zip) file that you have downloaded from sourceforge, and extracted somewhere sensible. If you downloaded the freeRTOSxxx_All_Files.zip, you have all the sources.

File>>Import…>>General:File System

Select the “into folder” as the project name you just created, and “Select All” for the import. That should import the 2 files shown inro the project file system. Spend some time browsing, if you like.

Following this step, it should be possible to compile and link the project.

Project>>Build All

If this step completes successfully, with no additional ERRORS, then the final step is to upload the new application into your Arduino or Freetronics device.

Make sure that you have your device plugged into the USB port, then simply hit the AVR* button in the row of buttons. You will see some green text showing the status of the upload, finishing with the words

avrdude done. Thank you.

Now, you should have a flashing LED.

Now you can import any additional projects, in the same way.

Step 8. Things to watch.

Turn on the serial port by removing the comments around the serial port definitions, and watch to see aspects of the program in action.

Expect to manage the amount of heap allocated in the ./include/FreeRTOSBoardDefs.h file, to ensure that the total SRAM utilised (as noted in the final linker stage when using heap_1.c, heap_2.c or heap_4.c) remains less than 100% or for ATmega328p 2048 bytes.

Expect to manage the amount of stack space allocated to each task during the set up, to ensure you’re not wasting space, nor (worse) you’re over writing another task’s stack.

For the Arduino Uno, keep the total number of tasks to below 4, otherwise too much SRAM is consumed in stack allocations.