A collection of (maybe) frequently asked questions.

Hardware

Board design

Kakapo doesn't have the "ICSP/SPI" connector

Warning: rant incoming.

The original purpose of the 6-pin connector in the bottom right of an Arduino was for external programming of the MCU, using the ICSP/SPI protocol.

That the header had SPI was a side effect of the way external programming for the chip worked. The "official" SPI pins were on the digital pin headers along the top. The ICSP header was a dupe of the pins with the extra pins needed for ICSP (power and reset).

When the Arduino Leonardo came along, the Arduino project decided to not wire SPI to the digital IO headers. Instead, the only SPI pins were provided on the "ICSP" header. This broke a wide array of shields which didn't use the ICSP header for SPI.

For Kakapo, external programming is not done over SPI, and uses dedicated programming pins. SPI is provided on the pins the Uno had them available on. The choice was then between duplicating the pins on the digital header down to an "SPI" header (which wouldn't have any programming capability) or using this space to provide an 8-pin header for extra pins on the Kakapo MCU.

We chose to give you more usable IOs rather than duplicate pins.

libkakapo

General Hardware

Will there be a driver for the ______ module?

The drivers provided by libkakapo are intended to be the most common used peripherals, but not all of them. Some modules are difficult to abstract as they interact with a wide variety of other modules (eg, DMA). Others are less likely to be used vs the effort of writing a general driver for them.

These features currently have no drivers in libkakapo:

  • DMA
  • Complete coverage of the event system (some module drivers expose their own elements of it, but not all aspects of the event system are covered).
  • DAC
  • Crypto acceleration
  • CRC generator
  • EBI
  • Sync mode and 9-bit mode on USART
  • SPI master mode on USART
  • TWI slave
  • AWeX and HiRes timer modes
  • XCL
  • USB
  • NVM controller beyond signature rows, eeprom, and functions provided by xboot API
  • Power modes (except as already provided by avr-libc)

Note that while libkakapo does not have drivers for these features, nothing should stop you from writing your own driver mixed with libkakapo.

We are also always happy to see patches to libkakapo to support other modules, so if you have written support for a module please consider contributing it.

Do I always need to call kakapo_init()?

kakapo_init() provides a few initial setup tasks that are typically needed for most projects anyway. It performs the following tasks:

  • Set up the system clock according to the F_CPU define
  • Set the pin direction on the built-in LEDs so they are outputs
  • Enable interrupts

Note that as many drivers are compiled with delays and timing configuration based on F_CPU, it is important to call kakapo_init() to ensure the system runs at the speed the drivers were expecting.

How do I adjust the frequency that the Kakapo runs at?

Unlike the ATMEGA on boards such as the Arduino, the clock frequency can be entirely set at runtime, and does not require an external programmer or changing crystals.

By default, kakapo_init() and all drivers will handle either 32MHz or 2MHz. This can be changed by building the library with the frequency passed as a paramter to make. For example, this rebuilds the library with 2MHz system clock:

make clean; make F_CPU=2000000

It's important to do a `make clean` before to ensure all drivers are recompiled against the new frequency. You will also need to ensure your project calls kakapo_init() fairly early.

For other frequencies, be aware that many drivers do not support frequencies other than 32MHz or 2MHz. You will need to check every driver and add appropriate blocks for your chosen frequency, and either perform clock setup yourself (using the functions in clock.h), or modify kakapo_init() to support your chosen clock.

USARTS

When using the USART right on power-up, I get corrupt text before it comes right?

The FTDI chip which provides USB based access appears to need a few cycles to get in sync with the USART from the MCU. The easiest way to force the sync is to emit a single character and then a delay.

/* init some serial ports! */
usart_init(usart_d0, 64, 128);
usart_conf(usart_d0, 115200, 8, none, 1, U_FEAT_NONE, NULL);
usart_run(usart_d0);
usart_map_stdio(usart_d0);

/* this is required to force sync with the FTDI chip */
putchar(0);
_delay_ms(1);
printf("\fhello, world\r\n");

The 1ms delay is sufficient to let the chip identify the true start/bits/stop clock edges.

SPI

Why is the clock speed a division of the CPU frequency?

The way the SPI hardware is designed is that the SPI clock is driven from the 1x peripheral clock (which will be the same as the CPU clock), rather than using a baud rate generator. libkakapo doesn't hide this detail, so while TWI and USARTs have a baud generator, and accept baud rates, SPI has a divisor and accepts divisions only.

Timing

There is no millis() function!

No, there is not. libkakapo doesn't assume you must use the hardware resources a specific way. You're free to allocate timers as you see fit, rather than have them taken away from you to support a function you may or may not use.

If you need a millis() function, configure a timer of your choice to overflow at 1000Hz (ie, every millisecond) and use a an overflow hook to keep a count of milliseconds. An example of this is in the libkakapo examples directory, under "timer".

What's the difference between rtc32 and rtc?

Most XMEGA chips only have a 16-bit RTC module, and this is supported by the "rtc" libkakapo driver. The XMEGA 256A3BU and 256A3B have a 32-bit RTC module instead, this is supported by the "rtc32" libkakapo driver.

In most cases, you will want the "rtc" driver. The "rtc32" driver is included so that if you design your own board around an XMEGA chip with an RTC32 module instead, it's still easy to access.

ADC

"ADC_REFSEL_INTVCC_gc" is undefined

Some versions of the avr-libc (notably, some provided by Atmel directly as part of their toolchain) did not use the names in the datasheets for ADC internal references.

The problem is not present in avr-libc 1.8.0, nor in Atmel AVR8 Toolchain releases from 3.4.4. It is in current versions of the AVR Crosspack, however.

There is a workaround until fixed headers are available in all distributions: uncomment the following line:

#define BUG_AVRLIBC_ADC_REFNOINTPREFIX

This will use the names present in these incorrect header releases.

Toolchain

Why can't I find _____ in the avr-libc docs?

The avr-libc docs are very old, and don't reflect the current state of supported chips. XMEGA definitions are largely missing or unclear.

This is not the case for the actual library itself, which in the most recent version (1.8.0) has mostly correct XMEGA part definitions, and increasingly better support for the avr-libc helper functions supporting XMEGA.

Since there are some issues with the avr-libc helper functions, libkakapo tends to implement the functionality directly rather than rely on the helper functions.