Lesson 08: Add ezTiva Library into Your Project
The ezTiva Library is a Keil v5.x library for TI Tiva LaunchPad — TM4C123G and TM4C1294 microcontrollers.
Add ezTiva LIB to Your Project
1. EZ-Tiva Library
- Download ezTiva Library
- Current Version:
- Previous Version:
V1.2.7
- Current Version:
- Extract the zip file.
- Copy the ezTivaLib folder to your project home folder, such as the EE3450 folder.
Version History:
- 1.2. (2021/04/14)
- Add ezDelay() and ezDelayUs() function
- For LCD, add ezLCD_PutChar()
- 1.2.6 (2021/03/25)
- Fixed the LCD driver compatibility issue.
- 1.2.5 (2020/10/28)
- Support updating SystemCoreClock variable after change the system clock frequency.
- Change the library filename to ez123G.lib and ez1294.lib.
- 1.2.4 (2020/10/13)
- Using Compiler V6 to rebuild the libraries for both boards.
- Add a delay to fix compatibility issues for some LCD modules.
- 1.2.3 (2018/02/20)
- Using Compiler V5.06 update 5 (build 528) to rebuild the libraries for both boards.
- 1.2.2 (2017/12/02)
- Add more configurations for system clock setting
- Fixed the timer_waitMillis() function error in different system clock
2. Add ezTiva LIB
- In the Project tab, right-click on "Source Group 1" to open "Add Files..." window.
- In the "Add Files.." window, change the "Files of type" to "Library file (*.lib)"
Click on Add and then click on Close to return to the main menu.
3. Increase Stack and Heap
The stack is used for static memory allocation and Heap for dynamic memory allocation, both stored in the computer's RAM.
In C, when a function declares a local variable, it is "pushed" onto the stack. All the local variables will be deleted when the function exits. Or when a function or a method calls another function, sometimes the parameters and return address will be stored onto the stack.
When you use malloc() or calloc() to allocate dynamic memory space, it will be allocated on the heap. Once you have allocated memory on the heap, you are responsible for using free() to deallocate that memory once you don't need it anymore.
Change the memory size for stack and heap
The default memory size for the stack is 0x200 (512) bytes, 0x0 (0) bytes for the heap. Therefore, we need to modify the memory size for both.
- In the Project tab under Device, double-click on "startup_TM4xxx.s (Startup)" to open it up.
- Select its "Configuration Wizard" tab. Change the Stack Size to 0x400 bytes (1024 bytes) and Heap Size is to 0x400 bytes (1024 bytes)
4. Add ezTivaLIB to the Include Path
Next, you need to add the ezTivaLIB folder to the Options for Target ➤ C/C++ tab ➤ Include Paths.
- Select Options for Target (Alt+F7) from the Project menu, or click
button to open the Options window.
- Change to C/C++ tab. Click the button that is in the Include Paths field to setup a folder. In the Folder Setup window, click the New (Insert) button to add the ezTivaLIB folder to the Include Paths.
- Click OK to close the Options window.
ezTiva LIB API
System Frequency
You can easy to change the system clock frequency on your TI Tiva LaunchPad by using the ezTivaLIB. The following APIs are the predefined functions for different frequencies:
EK-TM4C123GXL LaunchPad
| # | API | Description |
| 1 | void Setup_123G_8MHz(void) | Setup System Clock Frequency to 8 MHz |
| 2 | void Setup_123G_16MHz(void) | Setup System Clock Frequency to 16 MHz |
| 3 | void Setup_123G_20MHz(void) | Setup System Clock Frequency to 20 MHz |
| 4 | void Setup_123G_25MHz(void) | Setup System Clock Frequency to 25 MHz |
| 5 | void Setup_123G_40MHz(void) | Setup System Clock Frequency to 40 MHz |
| 6 | void Setup_123G_50MHz(void) | Setup System Clock Frequency to 50 MHz |
| 7 | void Setup_123G_80MHz(void) | Setup System Clock Frequency to 80 MHz |
EK-TM4C1294XL LaunchPad
| # | API | Description |
| 1 | void Setup_1294_6MHz(void) | Setup System Clock Frequency to 6 MHz |
| 2 | void Setup_1294_12MHz(void) | Setup System Clock Frequency to 12 MHz |
| 3 | void Setup_1294_16MHz(void) | Setup System Clock Frequency to 16 MHz |
| 4 | void Setup_1294_20MHz(void) | Setup System Clock Frequency to 20 MHz |
| 5 | void Setup_1294_24MHz(void) | Setup System Clock Frequency to 24 MHz |
| 6 | void Setup_1294_30MHz(void) | Setup System Clock Frequency to 30 MHz |
| 7 | void Setup_1294_32MHz(void) | Setup System Clock Frequency to 32 MHz |
| 8 | void Setup_1294_40MHz(void) | Setup System Clock Frequency to 40 MHz |
| 9 | void Setup_1294_48MHz(void) | Setup System Clock Frequency to 48 MHz |
| 10 | void Setup_1294_60MHz(void) | Setup System Clock Frequency to 60 MHz |
| 11 | void Setup_1294_80MHz(void) | Setup System Clock Frequency to 80 MHz |
| 12 | void Setup_1294_96MHz(void) | Setup System Clock Frequency to 96 MHz |
| 13 | void Setup_1294_120MHz(void) | Setup System Clock Frequency to 120 MHz |
Delay Function
There are two timer-based (hardware) delay functions that can be used in your code:
void timer_waitMillis(uint32_t ms)
void ezDelay(uint32_t ms)
| Description: | Delay by the specified number of milliseconds. |
| Parameters: | ms: Number of milliseconds to delay. |
| Return Value: | None |
| Side Effects and Restrictions: | timer_waitMillis is implemented by Timer 5 (T5CCP0). |
void timer_waitMicros(uint32_t us)
void ezDelayUs(uint32_t us)
| Description: | Delay by the specified number of microseconds. |
| Parameters: | us: Number of microseconds to delay. |
| Return Value: | None |
| Side Effects and Restrictions: | timer_waitMicros is implemented by Timer 5 (T5CCP0) |
Do not use Timer5 (T5CCP0) in your project, it is used for the hardware timer delay functions — timer_waitMicros() and timer_waitMillis().
Character LCD APIs
The Character LCD APIs enable simple use of one, two, or four-line LCD modules that follow the Hitachi 44780 standard 4-bit interface. The APIs also implement horizontal and vertical bar graphs, or you can create and display your own custom characters.
LCD Connections
This section describes the various input and output connections available for the Character LCD.
Data Pins
Data transfer between the Tiva Launchpad and the Character LCD module will occur in the 4-bit interface mode. The D4 ~ D7 (Pin 11 ~ 14) of the LCD module must be connected to start on the first physical pin of a port on the Tiva LaunchPad; it may not span ports. That is, the D4 pin could theoretically be Port D pin 0 or Port E pin 0. Forcing the LCD data port to be at pin 0 can improve efficiency by reducing the number of shifts required to align data for a write.
Control Pins
The RS (data/command pin), R/W (read/write pin), and EN (enable pin) pins can be connected to any pins on the Tiva LaunchPad.
All the GPIO pins on the Tiva LaunchPad which are connected to the LCD module are output pins.
The following is a example to connect the
Figure: The Connections between the LCD Module and Tiva LaunchPad.
Before using the LCD module, the LCD object must be created and assigned to the port.pins based on the circuit connection. The example code as follows:
PEZOBJ_LCD lcd; // LCD Object
lcd = ezLCD_Create(); // Creating a new Hardware LCD Object
ezLCD_Connect_DataPort(lcd, _PORTD, ON_PIN_3_0); // Connecting DATA port on PortD[3:0]
ezLCD_Connect_ENPin(lcd, _PORTE, _PIN1); // Connecting EN pin on PortE[1]
ezLCD_Connect_RSPin(lcd, _PORTE, _PIN2); // Connecting RS pin on PortE[2]
ezLCD_Connect_RWPin(lcd, _PORTE, _PIN3); // Connecting RW pin on PortE[3]
ezLCD_Start(lcd); // Starting lcd object
Line 1: Declare an LCD object
Line 3: After initializing the GPIO ports, create a new hardware LCD object and then assign it to the lcd object pointer.
Line 4: Connect data pins (D4 ~ D7) to Port D pin 0 ~ pin 3.
Line 5: Connect the EN (enable) pin to Port E pin 1.
Line 6: Connect the RS (data/command) pin to Port E pin2.
Line 7: Connect the RW (read/write) pin to Port E pin 3.
Application Programming Interface (API)
void ezLCD_Start(PEZOBJ_LCD lcd)
| Description: |
This function will start up the LCD object and initialize the LCD hardware module as follow:
|
| Parameters: | PEZOBJ_LCD lcd: LCD object |
| Return Value: | None |
| Side Effects: | None |
void ezLCD_ClearDisplay(PEZOBJ_LCD lcd)
| Description: | Clears the contents of the LCD screen and resets the cursor location to be row and column zero. |
| Parameters: | PEZOBJ_LCD lcd: LCD object |
| Return Value: | None |
| Side Effects: | None |
void ezLCD_Position(PEZOBJ_LCD lcd, uint8_t row, uint8_t column)
| Description: | Move the cursor to the location specified by the argument row and column. |
| Parameters: | PEZOBJ_LCD lcd: LCD object. uint8_t row: The row number at which to position the cursor. uiny8_t column: The column number at which to position the cursor. |
| Return Value: | None |
| Side Effects: | None |
void ezLCD_PrintString(PEZOBJ_LCD lcd, char const str[])
| Description: | Writes a null-terminated string of characters to the LCD screen beginning at the current cursor location. |
| Parameters: | PEZOBJ_LCD lcd: LCD object. char const str[]: Null-terminated array of ASCII characters to be displayed on the LCD screen. |
| Return Value: | None |
| Side Effects: | None |
void ezLCD_PrintInt8(PEZOBJ_LCD lcd, uint8_t value)
| Description: | Prints a two-ASCII-character representation of the 8-bit value to the Character LCD screen at the current cursor location. |
| Parameters: | PEZOBJ_LCD lcd: LCD object. uint8_t value: The 8-bit value to be printed in hexadecimal ASCII characters. |
| Return Value: | None |
| Side Effects: | None |
void ezLCD_PrintInt16(PEZOBJ_LCD lcd, uint16_t value)
| Description: | Prints a four-ASCII-character representation of the 16-bit value to the Character LCD screen at the current cursor location. |
| Parameters: | PEZOBJ_LCD lcd: LCD object. uint16_t value: The 16-bit value to be printed in hexadecimal ASCII characters. |
| Return Value: | None |
| Side Effects: | None |
void ezLCD_PrintInt32(PEZOBJ_LCD lcd, uint32_t value)
| Description: | Prints an eight-ASCII-character representation of the 32-bit value to the Character LCD screen at the current cursor location. |
| Parameters: | PEZOBJ_LCD lcd: LCD object. uint32_t value: The 32-bit value to be printed in hexadecimal ASCII characters. |
| Return Value: | None |
| Side Effects: | None |
void ezLCD_Number(PEZOBJ_LCD lcd, uint16_t value)
| Description: | Prints the decimal value of a 16-bit value as left-justified ASCII characters. |
| Parameters: | PEZOBJ_LCD lcd: LCD object uint16_t value: The 16-bit value to be printed in ASCII characters as a decimal number |
| Return Value: | None |
| Side Effects: | None |
void ezLCD_Print32Number(PEZOBJ_LCD lcd, uint32_t value)
| Description: | Prints the decimal value of a 32-bit value as left-justified ASCII characters. |
| Parameters: | PEZOBJ_LCD lcd: LCD object. uint32_t value: The 32-bit value to be printed in ASCII characters as a decimal number |
| Return Value: | None |
| Side Effects: | None |
Example Code
EK-TM4C123GXL LaunchPad
#include <stdio.h>
#include <stdlib.h>
#include <stdbool.h>
#include <stdint.h>
#include "TM4C123GH6PM.h"
#include "MyDefines.h"
#include "ez123G.h"
char str[100];
void Setup_GPIO();
int main(void)
{
PEZOBJ_LCD lcd; // LCD Object
uint16_t i = 0;
Setup_GPIO(); // GPIO Configuration
lcd = ezLCD_Create(); // Creating a new Hardware LCD Object
ezLCD_Connect_DataPort(lcd, _PORTD, ON_PIN_3_0);// Connecting DATA port on PortD[3:0]
ezLCD_Connect_ENPin(lcd, _PORTE, _PIN1); // Connecting EN pin on PortE[1]
ezLCD_Connect_RSPin(lcd, _PORTE, _PIN2); // Connecting RS pin on PortE[2]
ezLCD_Connect_RWPin(lcd, _PORTE, _PIN3); // Connecting RW pin on PortE[3]
ezLCD_Start(lcd); // Starting lcd object
ezLCD_LoadVerticalBargraphFonts(lcd); // Load vertical bargraph fonts
ezLCD_ClearDisplay(lcd); // Clear LCD display
ezLCD_PrintString(lcd, "HELLO"); // Display string on LCD screen
ezLCD_Position(lcd, 1,0); // Set dispplay position at [1,0] (raw 1. col 0)
ezLCD_PrintString(lcd, "TI Tiva 123G"); // Display string on LCD screen
while (1){
sprintf(str,"i = %d ", i);
ezLCD_Position(lcd, 0, 6);
ezLCD_PrintString(lcd, str);
ezLCD_DrawVerticalBG(lcd, 1, 15, 2, i%16); // Draw a vertical bar at (1,6), maximum 2 characters, bar number is 0~15
i++;
timer_waitMillis(100); // Hardware timer delay for 100 ms
}
}
void Setup_GPIO()
{
// GPIO Initialization and Configuration
// 1. Enable Clock to the GPIO Modules (SYSCTL->RCGCGPIO |= (_PORTs);)
SYSCTL->RCGCGPIO |= (_PORTs); |= (__);
// allow time for clock to stabilize (SYSCTL->PRGPIO & (_PORTs))
while ((SYSCTL->PRGPIO & (__)) != (__)) {};
// 2. Unlock GPIO only PD7, PF0 on TM4C123G; PD7 on TM4C1294 (GPIOx->LOCK = 0x4C4F434B; and GPIOx->CR = _PINs;)
// 3. Set Analog Mode Select bits for each Port (GPIOx->AMSEL = _PINs; 0=digital, 1=analog)
// 4. Set Port Control Register for each Port (GPIOx->PCTL = PMCn << _PTCL_PINn, check the PCTL table)
// 5. Set Alternate Function Select bits for each Port (GPIOx->AFSEL = _PINs; 0=regular I/O, 1=PCTL peripheral)
// 6. Set Output pins for each Port (Direction of the Pins: GPIOx->DIR = _PINs; 0=input, 1=output)
// 7. Set PUR bits (internal Pull-Up Resistor), PDR (Pull-Down Resistor), ODR (Open Drain) for each Port (0: disable, 1=enable)
// 8. Set Digital ENable register on all GPIO pins (GPIOx->DEN = _PINs; 0=disable, 1=enable)
}
EK-TM4C1294XL LaunchPad
#include <stdio.h>
#include <stdlib.h>
#include <stdbool.h>
#include <stdint.h>
#include "TM4C1294NCPDT.h"
#include "MyDefines.h"
#include "ez1294.h"
char str[100];
void Setup_GPIO();
int main(void)
{
PEZOBJ_LCD lcd;
uint16_t i = 0;
Setup_GPIO();
lcd = ezLCD_Create(); // Creating a new Hardware LCD Object
ezLCD_Connect_DataPort(lcd, _PORTE, ON_PIN_3_0);// Connecting DATA port on PortE[3:0]
ezLCD_Connect_ENPin(lcd, _PORTD, _PIN7); // Connecting EN pin on PortD[7]
ezLCD_Connect_RSPin(lcd, _PORTA, _PIN6); // Connecting RS pin on PortA[6]
ezLCD_Connect_RWPin(lcd, _PORTM, _PIN4); // Connecting RW pin on PortM[4]
ezLCD_Start(lcd); // Starting lcd object
ezLCD_LoadVerticalBargraphFonts(lcd); // Load vertical bargraph fonts
ezLCD_ClearDisplay(lcd); // Clear LCD display
ezLCD_PrintString(lcd, "HELLO"); // Display string on LCD screen
ezLCD_Position(lcd, 1,0); // Set dispplay position at [1,0] (raw 1. col 0)
ezLCD_PrintString(lcd, "TI Tiva 1294"); // Display string on LCD screen
while (1){
sprintf(str,"i = %d ", i);
ezLCD_Position(lcd, 0, 6);
ezLCD_PrintString(lcd, str);
ezLCD_DrawVerticalBG(lcd, 1, 15, 2, i%16); // Draw a vertical bar at (1,6), maximum 2 characters, bar number is 0~15
i++;
timer_waitMillis(100); // Hardware timer delay for 100 ms
}
}
void Setup_GPIO()
{
// GPIO Initialization and Configuration
// 1. Enable Clock to the GPIO Modules (SYSCTL->RCGCGPIO |= (_PORTs);)
SYSCTL->RCGCGPIO |= (_PORTs); |= (__);
// allow time for clock to stabilize (SYSCTL->PRGPIO & (_PORTs))
while ((SYSCTL->PRGPIO & (__)) != (__)) {};
// 2. Unlock GPIO only PD7, PF0 on TM4C123G; PD7 on TM4C1294 (GPIOx->LOCK = 0x4C4F434B; and GPIOx->CR = _PINs;)
GPIOD_AHB->LOCK = 0x4C4F434B;
while ((GPIOD_AHB->LOCK & 0x01) == 0x01); // Unlocked when reading the GPIOx->LOCK = 0x4C4F434B; ==0x00
*(((char*)GPIOD_AHB)+0x524) = 0xFF;
// 3. Set Analog Mode Select bits for each Port (GPIOx->AMSEL = _PINs; 0=digital, 1=analog)
// 4. Set Port Control Register for each Port (GPIOx->PCTL = PMCn << _PTCL_PINn, check the PCTL table)
// 5. Set Alternate Function Select bits for each Port (GPIOx->AFSEL = _PINs; 0=regular I/O, 1=PCTL peripheral)
// 6. Set Output pins for each Port (Direction of the Pins: GPIOx->DIR = _PINs; 0=input, 1=output)
// 7. Set PUR bits (internal Pull-Up Resistor), PDR (Pull-Down Resistor), ODR (Open Drain) for each Port (0: disable, 1=enable)
// 8. Set Digital ENable register on all GPIO pins (GPIOx->DEN = _PINs; 0=disable, 1=enable)
}