AVR Libraries

Note: 15 February 2014. This is a very incomplete library but is sufficient for the devices covered. It is no longer under development. A library with much better coverage is Procyon Engineering avrlib.

A number of libraries for AVR and using avr-gcc compilation have been developed, and are provided here under the GPL version 2 opensource licence. All are combined into one library. Most of these libraries were adapted from libraries freely available, but have been recast to allow use with a non-interrupting scheduling OS.

  1. TWI (I2C) Master

  2. TWI (I2C) Slave

  3. A/D Conversion

  4. Timer

  5. USART

  6. NARTOS (non-real time scheduling OS) suitable for very small memory devices.

I2C Master library

This provides basic functions for performing master operations over the I2C interface (designated also as the Two-Wire Interface, TWI). The functions provide read and write of a block (address+data) to and from a slave device. Each function initiates an operation and returns, that is, it is nonblocking. The operation is completed through interrupts and a flag is set when complete. A polling function is provided to allow the calling program to test for completion of the operation. This way the code is suitable for use with a scheduling operating system.

The library maintains a read and a write buffer. The write buffer holds all data to be transferred including the address and device ID. Thus a simple device read will also involve the write buffer and a change in transfer direction will need to occur. The I2C communication works with block transactions; the master informs the slave how many bytes it wants to be sent back during a read operation, and supplies a start address if the device needs one (such as an EEPROM chip). It is possible to have read only, write only and read/write (atomic) transactions. Much of the work is done in the interrupt service routine working as a state machine to interpret the bus activity. The I2C bus allows for multiple masters to contend for control of the bus. The code at this time only handles a single master.

  1. twiInit(bitRate)  Initialise the TWI interface.

  2. twiSetupTransaction(numBytes) All in and out buffer pointers are reset and the read count is set to the number of bytes to be read. If numBytes is zero, then the transaction is taken to be write only, otherwise it is read/write.

  3. twiWriteByte(dataByte) Write the next byte to the write buffer. If the buffer is full, the byte is not written. This call simply fills the write buffer and no transaction takes place. The number of bytes to be sent to the device will be the number in the queue at the time the write transaction is activated.

  4. twiLaunch(device) Launch a master transaction with a slave device. The calling program is expected to have setup the transaction by putting data in the write buffer and specifying a number of bytes to be read. If there are no bytes to
    write, the transaction is a master read. If there are no bytes to read the transaction is a master write. If there are bytes to write and read the transaction is an atomic write/read. If there is nothing to do, the function will return an error indication.

  5. twiReadByte() Read the next received byte from the read buffer. Before calling this function the calling program is expected to determine how many bytes have been received from the read transaction, and if any error occurred. The next read
    byte is returned, unless attempting to read beyond the end of the buffer whence an error indication is returned and the pointer is not incremented.

  6. twiErrorStatus() Check the error status of a transaction (whether an error occurred and its code).

  7. twiCompletionStatus() Check the completion status of a transaction (whether it completed a block transfer and how many transfers remain to be done).

I2C Slave library

This provides basic functions for performing slave operations over the I2C interface. The master addresses the slave with a request for read or write. In each case if the slave is unable to respond it must signal the master through the acknowledgement bit. In the case of reads this can only happen after a byte is written to a full buffer. Thus the byte is set aside in a special location to be added after the read buffer is read. The master will receive the negative acknowledgement and must try again later. This situation arises in master-slave transactions as the slave does not initiate any activity, but only responds to master requests.

  • twiSlaveInit(bitRate, id) Initialize the TWI interface using the id as the own device address. Buffers are reset to empty state.

  • twiWriteByte(dataByte) Write the next byte to the write buffer. If the buffer is full, the byte is not written. The number of bytes to be sent to the device will be the number in the queue at the time the write transaction is activated.

  • twiReadCount() Return a value for the number of bytes in the read buffer. This is used to check if anything has arrived and to manage access to incoming data.

  • twiReadByte() Read a byte from the read buffer. Before calling this function the calling program is expected to determine how many bytes have been received from the read transaction, and if any error occurred. The next read byte is returned, unless attempting to read beyond the end of the buffer whence an error indication is returned and the pointer is not incremented. If the ISR has received a byte when the buffer is full, the byte will have been set aside and is put back onto the end of the read buffer after this function has accessed the byte to be read (this is due to a characteristic of TWI master-slave transactions).

  • twiSlaveLaunch() The TWI is setup with interrupts enabled and ready to respond to a master communication by enabling address recognition. If the TWI is busy, it returns with an indication.

  • twiErrorStatus() Check the error status of a transaction (whether an error occurred and its code).

References to AVR libraries only:

  • BASCOM (commercial) I2C slave library

  • Keeser I2C master library (not sure if this uses TWI hardware support)

  • Fleury (GPL) I2C master library

  • Procyon AVRlib (GPL). Extensive set of libraries. I2C libraries with and without TWI hardware support

  • Efstathiou (GPL) I2C master library

A/D converter Library

This library, based on that of Chris Efstathiou, provides basic functions for A/D conversion using interrupt/polled and noise reduction sleep operations. Support for free running operation is also provided.

  1. Single A/D conversion of one or a group of channels. This starts the conversion and returns. An ISR reads the result to a temporary location. This way either interrupt driven or polled mode can be used in the application.

  2. Free running A/D conversion. Once started the A/D converter continues to restart automatically. Channel scanning can be used, in which case all channels are scanned before proceeding to the next round of conversions. The program is responsible for picking up the results before they are overwritten. This can be useful for obtaining data at the maximum rate.

The functions are non-blocking. Once the A/D converter is started, a read  function can be used to check if conversion is complete and will return to the main program flow.

Some AVRs also have external or internal triggers for the ADC, this is not used in this library.

  1. adcInit(mode,adcClock) Initialise A/D conversion process. This function will initialise the ADC with the mode of operation and the clock rate to be used. An error will be returned if the ADC is busy.

  2. adcStart(channelMask)  Start an A/D conversion. This function will initiate an A/D conversion on a set of channels given by a
    channel mask (a 1 in each bit corresponding to the A/D channel 0-MAX).

  3. adcIsBusy() Check Progress of an A/D conversion.

  4. adcRead(channel)  Return the result of the A/D conversion. This will check if a result is ready for a given channel, and return the
    result or -1 if not available. For the AVRs the result will have a maximum precision of 10 bits.

  5. abortConversion() Abort any running A/D conversion.

References:

  • Procyon AVRlib (GPL). Extensive set of libraries, ADC library included.

  • Efstathiou (GPL) ADC library included.


First created 19 June 2007

Last Modified 15 February 2014