Atmel AVR944: Atmel LED Driver Library for 8bit AVR
Features
• Library to control the Atmel® LED Driver MSLxxxx series of Atmel LED drivers
®
®
• Includes TWI library for Atmel XMEGA , megaAVR
2
- Compatible with Philips' I C protocol
• Includes SPI library for the Atmel tinyAVR®
- Also includes USI library to be used as SPI for tinyAVR
• MCU and application-independent application programming interface
• Easy to configure and use
8-bit Atmel
Microcontrollers
Application Note
1 Introduction
Atmel MSLxxxx is a series of compact, high power LED drivers. This application
note explains how to use 8-bit Atmel AVR® microcontrollers to interface with these
LED drivers. MSLxxxx series of drivers feature either TWI or SPI interface to read
and write to their internal registers. Atmel LED driver library provides easy to use
wrapper functions to read/write to those registers using any 8-bit AVR as master.
This library supports both TWI and SPI interfaces. Table 1-1 shows the interfaces
supported by this library for each AVR.
Table 1-1. Interfaces supported by the Atmel LED driver library.
Microcontroller
Interface
megaAVR
TWI
XMEGA
TWI
tinyAVR
SPI, USI (SPI)
Rev. 8464A-AVR-11/11
2 Prerequisites
The LED Driver Library used in this document requires basic familiarity with following:
• Compiling C projects with Atmel AVR Studio® 5, as the library is written using this
IDE
• General familiarity with SPI and TWI interfaces and electrical connection
requirements
• Basics of MSLxxxx register set and their use
• A method to debug and test the compiled application, or download the application
hex files into the targeted device, such as the Atmel AVR JTAGICE mk-II or Atmel
AVR JTAGICE 3
3 Limitations
• The LED Driver Library was compiled and tested with the Atmel AVR Studio 5 with
GCC C compiler. This library was not compiled with IAR™ or any other compiler
• The LED Driver Library supports only TWI with Atmel megaAVR and XMEGA
devices and only SPI and USI (SPI) with Atmel tinyAVR devices
• ‘ATXMEGA’, ‘MEGAAVR’, ‘TINYAVR’, ‘SPI’, ‘TWI’ and ‘SPI_USI’ are important
keywords; do not use them elsewhere in the code as they are used as defines in
the configuration file
2
Atmel AVR944
8464A-AVR-11/11
Atmel AVR944
4 Creating a project
Table 4-1 shows the list of files contained in this library along with a short description.
To include this library in a new project, “atmel_led_device_config.h” must be
configured (as explained in Section 5) and added along with the required driver files
and the compiler file (avr_compiler.h). For example, to create a project for ATxmega
TWI interface, the following files should be included:
• atxmega_twi_driver.c
• atxmega_twi_driver.h
• avr_compiler.h*
• atmel_led_device_config.h*
The configuration and compiler files (marked with *) must be included irrespective of
the AVR and interface as the project will not compile without these.
In the user application source file, include “atmel_led_device_config.h” by adding the
following statement on the top.
#include "atmel_led_device_config.h"
This file will automatically include all the required files. The file
“atmel_led_drvr_demo.c” provides a very good example of how to include and use
this library.
Table 4-1. List of files in the Atmel LED driver library.
Source file
Description
atmega_twi_driver.c
Driver for megaAVR with TWI interface
atmega_twi_driver.h
Header file for atmega_twi_driver.c
atxmega_twi_driver.c
Driver for XMEGA AVR with TWI interface
atxmega_twi_driver.h
Header file for atxmega_twi_driver.h
tiny_avr_spi_via_usi_driver.c
Driver for tinyAVR with USI interface
tiny_avr_spi_via_usi_driver.h
Header file for tiny_avr_spi_via_usi_driver.c
tiny_avr_spi_driver.c
Driver for tinyAVR with SPI interface
tiny_avr_spi_driver.h
Header for tiny_avr_spi_driver.c
atmel_led_device_config.h
Atmel LED driver library configuration file
atmel_led_drvr_demo.c
Atmel LED driver library demo application
avr_compiler.h
AVR compiler file
documentation.h
Used only by Doxygen
3
8464A-AVR-11/11
5 Configuring the library
Configure the library with only one file “atmel_led_device_config.h”. This file contains
pre-compilation directives to compile the source required only for the selected AVR
and interface. The default configuration file provided with the library is setup for the
Atmel ATtiny40 AVR with SPI interface. The configuration file settings for different
AVR microcontrollers are explained next.
5.1 Selecting the device and interface
There are four definitions related to device and interface. Select the target AVR and
interface with the first two #defines.
//***************************************************************/
//User can define the device here: ATXMEGA, MEGAAVR or TINYAVR
#define ATXMEGA
//****************************************************************/
//Define the interface here SPI, TWI or SPI_USI
#define TWI
This example shows the target as ATxmega with TWI interface.
‘ATXMEGA’, ‘MEGAAVR’, ‘TINYAVR’, ‘SPI’, ‘TWI’ and ‘SPI_USI’ are essential
keywords; do not be use them anywhere else in the code. They selectively compile
only the required source files.
The next two defines are shown below.
//CPU Clock on which AVR is running at. It is used to calculate
//baud rate settings and delays.
#define F_CPU 20000000
//*****************************************************************
//Define slave addresses here.
#define SLAVE_ADDRESS 0xA0
• F_CPU is the frequency in hertz (Hz) at which the AVR is running. It calculates
delays and baud rate settings
• SLAVE_ADDRESS is the address of the slave MSLxxxx. It can be TWI slave or
SPI slave. This is a seven bit address and the bit 0 is ignored. Bit 0 is used to
indicate a read or a write operation
5.2 Interface settings
There are four sections in the “atmel_led_device_config.h” file, each used for different
kind of interface. One of the four sections is compiled depending on the type of AVR
and interface used.
5.2.1 Atmel XMEGA with TWI interface
The following code section contains definitions related to this target.
//*********ATXMEGA TWI PARAMETERS******************************/
#if defined(ATXMEGA) && defined(TWI)
#include "atxmega_twi_driver.h"
/*! \brief Largest message size that will be sent/received
excluding address byte and register address. When using array
4
Atmel AVR944
8464A-AVR-11/11
Atmel AVR944
write/read functions, the count parameter can not exceed
NUM_BYTES*/
#define NUM_BYTES 16
/*! TWI port used, */
#define TWI_PORT TWIC
/*! TWI master Interrupt */
#define TWI_INT_VECTOR TWIC_TWIM_vect
/*BAUDRATE 100Khz*/
#define BAUDRATE
100000
//*****************************************************************
• NUM_BYTES defines the maximum number of data bytes that can be sent in one
transfer. It is used when using the array read/write commands. The count
parameter can not exceed NUM_BYTES
• TWI_PORT defines which TWI module is used
• TWI_INIT_VECTOR defines the interrupt associated with that TWI module
• BAUDRATE defines the target SCL clock frequency in hertz. For most TWI
applications, it is 100kHz
5.2.2 Atmel megaAVR with TWI interface
The following code section contains definitions related to this target.
//******************MEGAAVR TWI PARAMETERS***********************/
#elif defined(MEGAAVR) && defined(TWI)
#include "atmega_twi_driver.h"
/*! \brief Largest message size that will be sent/received
excluding address byte and register address. When using array
write/read functions, the count parameter can not exceed
NUM_BYTES*/
#define NUM_BYTES 16
// Bit rate Register setting for 8MHz CPU clock, 100 KHz SCL
#define TWI_TWBR
0x20
#define TWI_TWPS
0x00
//*****************************************************************
• NUM_BYTES defines the maximum number of data bytes that can be sent in one
transfer. It is used when using the array read/write commands. The count
parameter can not exceed NUM_BYTES
• TWI_BUFFER_SIZE defines the size of Tx/Rx buffer. In simple read/write
transactions with MSLxxxx, three bytes are transferred one way
• TWI_TWBR and TWI_TWPS define the baud rate register settings according to
Equation 5-1. Carefully enter these to set the SCL clock frequency
Equation 5-1. megaAVR SCL frequency calculation.
SCL = (CPU_CLOCK FREQ)/(16 + 2 × TWBR × (4^TWPS))
5
8464A-AVR-11/11
5.2.3 Atmel tinyAVR with USI interface
Most of the tinyAVR microcontrollers do not have SPI module. Instead they have a
universal serial interface which can be implemented as either SPI or TWI. This library
contains drivers for the SPI implementation of the tinyAVR USI. Drive the SPI
interface of the MSLxxxx with the AVR USI ports to control the LED driver using this
library. Since USI is a three pin interface, use an additional I/O pin as SS by the
software.
The following code section contains the definitions related to this target.
#elif defined(TINYAVR) && defined(SPI_USI)
#include "tiny_avr_spi_via_usi_driver.h"
/* USI port and pin definitions for ATTINY25*/
#define USI_OUT_REG
PORTB //!< USI port output register.
#define USI_IN_REG
PINB //!< USI port input register.
#define USI_DIR_REG
DDRB //!< USI port direction register.
#define USI_CLOCK_PIN PB2 //!< USI clock I/O pin.
#define USI_DATAIN_PIN
PB0
//!< USI data input pin.
#define USI_DATAOUT_PIN
PB1
//!< USI data output pin.
#define CSB_PIN
PB4
//!< Atmel LED driver CSB
#define TC0_PRESCALER_VALUE 1 //!< Must be 1, 8, 64, 256, 1024
#define TC0_COMPARE_VALUE
31 //!< Must be 0 to 255. Minimum 31
//with prescaler CLK/1.
•
•
•
•
•
•
•
USI_OUT_REG defines the USI port used
USI_IN_REG defines the USI port input register
USI_DIR_REG defines the USI port direction register
USI_CLOCK_PIN defines the USCK pin (SCK)
USI_DATAIN_PIN defines the USI data in (MISO) pin
USI_DATA_OUT defines the USI data out (MOSI) pin
CSB_PIN is the software controlled I/O pin (SS). Since USI is a three pin interface,
use this pin, which is software controlled, to drive the MSLxxxxCSB input
• TCO_PRESCALAR_VALUE and TCO_COMPARE_VALUE set the SCK bits-persecond of the interface according to the Equation 5-2
Use prescaler value of {1, 8, 64, 256 or 1024} and compare value 0 to 255. Use at
least 31 when using prescaler value of 1. Hence maximum SCK bits-per-second is
F_CPU/64.
Equation 5-2. USI SCK calculation.
Bits per second = F_CPU / (PRESCALER × (COMPAREVALUE+1) × 2)
5.2.4 Atmel tinyAVR with SPI interface
For the tinyAVR microcontrollers with built in SPI module, the LED Driver Library
contains tinyAVR SPI drivers to interface with Atmel LED driver chips like the Atmel
MSL2160. The following code section contains the built-in SPI definitions.
#elif defined(TINYAVR) && defined(SPI)
#include "tiny_avr_spi_driver.h"
6
Atmel AVR944
8464A-AVR-11/11
Atmel AVR944
//This is the SCK divider setting as defined by SPR[1:0]
#define SPI_CLK_DIVIDER 4 //Must be 4,16,64,128
//This is the SPI2X bit setting which, if set, doubles the SCK.
#define SPI_CLK_DOUBLE 1 //Must be 1 or 0
#define SPI_DIR_REG DDRC
//!< SPI port direction register.
#define SPI_PORT
PORTC //!< SPI port output register.
#define SPI_SCK
PC1
//!< SPI clock I/O pin.
#define SPI_MISO
PC2
//!< SPI data input pin.
#define SPI_MOSI
PC4
//!< SPI data output pin.
#define SPI_SS
PC0
//!< Atmel LED driver CSB pin
• SPI_CLOCK_DIVIDER and SPI_CLK_DOUBLE determine the SCK frequency
according to Equation 5-3
• Use clock divider value of {4, 16, 64 or 128} and clock double value 0 or 1
• SPI_DIR_REG defines the SPI port direction register
• SPI_PORT defines the SPI port output register
• SPI_SCK defines the SCK pin
• SPI_MISO defines the MISO pin
• SPI_MOSI defines the MOSI pin
• SPI_SS defines the Slave select pin which is connected to MSLxxxx CSB pin
Equation 5-3. SPI SCK calculation.
Bits per second = (F_CPU/SPI_CLK_DIVIDER) × (2^SPI_CLK_DOUBLE)
7
8464A-AVR-11/11
6 Electrical connections
6.1 TWI
To connect a MSLxxxx as a TWI slave to AVR master (megaAVR or XMEGA), pull up
SDA and SCL lines with a 10kΩ resistor as shown in Figure 6-1. In this figure, R1 and
R2 are 10kΩ resistors. Devices 1 to n are multiple MSLxxxx TWI slaves.
Figure 6-1. TWI connections.
6.2 SPI
To connect a MSLxxxx as a SPI slave to tinyAVR SPI (or USI) master, do not pull-up
MISO, MOSI, SCK, or CSB, but add a 33Ω series resistor on MISO between the AVR
and MSLxxxx as shown in Figure 6-2.
Figure 6-2. SPI connections.
SCK
SCK
MOSI
MOSI
SS
SS
MISO
Atmel AVR MCU
8
33Ω
MISO
Atmel LED driver
Atmel AVR944
8464A-AVR-11/11
Atmel AVR944
7 Using the library
This section explains the functions available to the user by this library. The prototypes
remain the same irrespective of the Atmel AVR and interface used. For this purpose,
this section assumes that the file “atmel_led_device_config.h” is correctly configured.
7.1 Library functions
The library provides the following application programmer interfaces (APIs). More
information on these can be found in the accompanying Doxygen documentation.
7.1.1 atmel_led_drvr_init()
This function configures the AVR to act as a master. Call this function before further
communication with the slave. This function returns void.
7.1.2 atmel_led_drvr_writeregister(slave_address, REG_ADDR. REG_DATA)
This function accesses the MSLxxxx slave at slave_address and writes REG_DATA
to its internal register at REG_ADDR. The function returns 1 if successful, else it
returns 0.
7.1.3 atmel_led_drvr_readregister(slave_address, REG_ADDR, *receivedData)
This function accesses the slave at slave_address and reads its internal register at
REG_ADDR and stores the data in receivedData pointer. The function returns 1 if
successful, else it returns 0.
7.1.4 atmel_led_drvr_writearray(slave_address, REG_ADDR, *Data, count)
This function writes a byte array of length ‘count’ pointed by ‘Data’ pointer to a slave
at slave_address, starting at register address REG_ADDR. For XMEGA and
megaAVR devices, this count can not exceed the NUM_BYTES defined in the
configuration file.
7.1.5 atmel_led_drvr_readarray(slave_address, REG_ADDR, *Data, count)
This function reads a byte array of length ‘count’ from a slave at slave_address,
starting at register address REG_ADDR into a buffer pointed by ‘Data’ pointer. For
XMEGA and megaAVR devices, this count can not exceed the NUM_BYTES defined
in the configuration file.
7.2 Writing user defined functions
Using the three primitive functions allows writing more user friendly functions which
read to and write from to specific registers of LED drivers. For example, the global
intensity register of Atmel MSL2160 has an internal address of 0x1F. This register
sets global LED intensity. The values 0 to 0xFF correspond to 0 to 100% brightness
respectively. The example code below shows a simple wrapper function to set global
intensity of a particular slave:
char SetBrighntessLevel(char slave_addr, char intensity)
{
return atmel_led_drvr_writeregister(slave_addr, 0x1F,
intensity);
}
9
8464A-AVR-11/11
8 Demo program
The file “atmel_led_drvr_demo.c” contains the source for a demo program for Atmel
ATtiny40 AVR with SPI interface to connect to Atmel MSL2160 Evaluation board. The
program accesses a MSL2160 slave and writes ‘0xAA’ to its register at ‘0x00’ address
and reads the register back. This operation is done in an infinite loop.
8.1 Hardware requirements
The demo setup needs the following components:
1. ATtiny40 AVR with any development kit (like the Atmel STK®600) which exposes
the MCU pins.
2. MSL2160 Evaluation board with LED load board and power supply.
3. 33Ω resistor.
10
Atmel AVR944
8464A-AVR-11/11
Atmel AVR944
9 References
AVR TWI for beginners:
www.atmel.com/dyn/resources/prod_documents/doc2564.pdf
AVR151: Setup And Use of The SPI:
http://atmel.com/dyn/resources/prod_documents/doc2585.pdf
MSL2160/61 datasheet:
http://www.atmel.com/dyn/resources/prod_documents/F1_MSL2160_DB.pdf
MSL2100 datasheet:
http://www.atmel.com/dyn/resources/prod_documents/F1_MSL2100_DB.pdf
AVR Studio 5:
http://www.atmel.com/micosite/avr_studio_5/default.asp?source=redirect
AVR319: Using the USI module for SPI communication:
http://atmel.com/dyn/resources/prod_documents/doc2582.pdf
11
8464A-AVR-11/11
10 Table of contents
Features ............................................................................................... 1
1 Introduction ...................................................................................... 1
2 Prerequisites .................................................................................... 2
3 Limitations........................................................................................ 2
4 Creating a project ............................................................................ 3
5 Configuring the library .................................................................... 4
5.1 Selecting the device and interface ...................................................................... 4
5.2 Interface settings ................................................................................................. 4
5.2.1 Atmel XMEGA with TWI interface.............................................................................. 4
5.2.2 Atmel megaAVR with TWI interface .......................................................................... 5
5.2.3 Atmel tinyAVR with USI interface .............................................................................. 6
5.2.4 Atmel tinyAVR with SPI interface .............................................................................. 6
6 Electrical connections ..................................................................... 8
6.1 TWI ...................................................................................................................... 8
6.2 SPI....................................................................................................................... 8
7 Using the library............................................................................... 9
7.1 Library functions .................................................................................................. 9
7.1.1 atmel_led_drvr_init().................................................................................................. 9
7.1.2 atmel_led_drvr_writeregister(slave_address, REG_ADDR. REG_DATA)................. 9
7.1.3 atmel_led_drvr_readregister(slave_address, REG_ADDR, *receivedData) .............. 9
7.1.4 atmel_led_drvr_writearray(slave_address, REG_ADDR, *Data, count) .................... 9
7.1.5 atmel_led_drvr_readarray(slave_address, REG_ADDR, *Data, count)..................... 9
7.2 Writing user defined functions ............................................................................. 9
8 Demo program ............................................................................... 10
8.1 Hardware requirements..................................................................................... 10
9 References...................................................................................... 11
10 Table of contents ......................................................................... 12
12
Atmel AVR944
8464A-AVR-11/11
Atmel Corporation
2325 Orchard Parkway
San Jose, CA 95131
USA
Tel: (+1)(408) 441-0311
Fax: (+1)(408) 487-2600
www.atmel.com
Atmel Asia Limited
Unit 01-5 & 16, 19F
BEA Tower, Milennium City 5
418 Kwun Tong Road
Kwun Tong, Kowloon
HONG KONG
Tel: (+852) 2245-6100
Fax: (+852) 2722-1369
Atmel Japan
16F, Shin Osaki Kangyo Bldg.
1-6-4 Osaki Shinagawa-ku
Tokyo 104-0032
JAPAN
Tel: (+81) 3-6417-0300
Fax: (+81) 3-6417-0370
Atmel Munich GmbH
Business Campus
Parkring 4
D-85748 Garching b. Munich
GERMANY
Tel: (+49) 89-31970-0
Fax: (+49) 89-3194621
© 2011 Atmel Corporation. All rights reserved.
®
®
®
®
®
®
®
Atmel , Atmel logo and combinations thereof, AVR , AVR Studio , megaAVR , STK , tinyAVR , XMEGA , and others are registered
trademarks or trademarks of Atmel Corporation or its subsidiaries. Other terms and product names may be trademarks of others.
Disclaimer: The information in this document is provided in connection with Atmel products. No license, express or implied, by estoppel or otherwise, to
any intellectual property right is granted by this document or in connection with the sale of Atmel products. EXCEPT AS SET FORTH IN THE ATMEL
TERMS AND CONDITIONS OF SALES LOCATED ON THE ATMEL WEBSITE, ATMEL ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS
ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL ATMEL BE
LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION,
DAMAGES FOR LOSS AND PROFITS, BUSINESS INTERRUPTION, OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO
USE THIS DOCUMENT, EVEN IF ATMEL HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Atmel makes no representations or
warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and
product descriptions at any time without notice. Atmel does not make any commitment to update the information contained herein. Unless specifically
provided otherwise, Atmel products are not suitable for, and shall not be used in, automotive applications. Atmel products are not intended, authorized, or
warranted for use as components in applications intended to support or sustain life.
8464A-AVR-11/11