Frequently Asked Questions

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 (except as already provided by avr-libc and 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 sysclk_init()?

sysclk_init() is a helper to easily map the CPU frequency set by F_CPU into a configuration for the clocking system within the MCU. You are free not to call it and do your own initialisation of the  CPU and peripheral clocks.

However, be aware that many of the libkakapo drivers have been compiled with a specific F_CPU defined. This may mean that delays and baud rate calculations will be wrong if you don’t set the clock to produce the same frequency.

If you want to use a different F_CPU, always ensure libkakapo is recompiled for the different value. Not all F_CPU values are supported by the various drivers, either. The drivers will throw an error if the specific frequency is unsupported.

Note that unlike the AVR MEGA, the CPU frequency of an XMEGA can be changed at run-time, and does not require changing crystals or an external programmer. This means you can easily run the MCU at a frequency of your choice.

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.

Leave a Reply

Tech and Electronics