Having precise timing in microcontrollers is important in many projects. For this you can use the two libraries presented in this article - millis & micros.
millis library triggers a timer interrupt every 1 millisecond and increments the milliseconds variable. The user can select the size of the milliseconds variable ranging from char (8 bits) to long long (64 bits) with an overflow from 255 milliseconds to 584.9 million years.
micros library is almost the same as millis but for microseconds. The overflow is between 255 microseconds and 584942 years.
For both libraries the user can select which timer to use: Timer0, Timer1, Timer2, Timer3 or Timer4.
In the case of millis library, it is recommended that other interrupts take less than 1 millisecond to complete otherwise the millis timer interrupt will be delayed. For the micros the ISRs must finish in less than 100 microseconds. The faster the CPU clock the better.
For the milliseconds and microseconds variable decide if you really need a 32 or 64 variable (long and long long) because the bigger the variable the longer it takes to increment it. For example on a 1MHz CPU it takes about 77 microseconds to increment a long long variable.
Contents
- Library Setup
- Code Example
- Library Usage
- Initialization
- Get time
- Pause timer
- Resume timer
- Reset timer
- Add time
- Subtract time
- Attach interrupt function
- Spreadsheet calculator
- Download
Library setup
By default the libraries are set to use Timer 2 and unsigned long variable type for time tracking but these can be changed inside the header files.
Classic AVR vs Modern AVR
Since version 2, the libraries supports modern AVR devices. I will be
referring to them as UPDI devices since they can be programmed using UPDI
interface.
F_CPU - the CPU clock frequency
When using UPDI devices the F_CPU can be a function argument so there is no
need for a #define. However for non-UPDI devices like ATmega328PB the F_CPU
needs to be defined in the header file so that the timer
prescaler can be calculated depending on what timer you select.
F_CPU is best to be defined inside project properties in Microchip Studio (or
your particular IDE) or a Makefile if custom Makefiles are used. See
https://www.programming-electronics-diy.xyz/2024/01/defining-fcpu.html.
Data type
Both millis and micros libraries have their own data types. The default works
in most cases.
/************************************************************* USER SETUP SECTION **************************************************************/ /* * Milliseconds data type * Data type - Max time span - Memory used * unsigned char - 255 milliseconds - 1 byte * unsigned int - 65.54 seconds - 2 bytes * unsigned long - 49.71 days - 4 bytes * unsigned long long - 584.9 million years - 8 bytes */ typedef unsigned long millis_t;
Selecting the Timer
When using non-UPDI devices the following timers can be selected:
/*------------------------------------------------------------- Non-UPDI devices MILLIS_TIMER0 - 8-bits MILLIS_TIMER1 - 16-bits MILLIS_TIMER2 - 8-bits MILLIS_TIMER3 - 16-bits MILLIS_TIMER4 - 16-bits ---------------------------------------------------------------*/ #define MILLIS_TIMER MILLIS_TIMER2 // which timer to use
On UPDI devices the timer source can be RTC or TCA.
RTC is the internal 16-bit Real Time Counter and is set to use the internal low power 32 kHz oscillator.
TCA is a 16-bit timer and is set to use channel 0.
/*-------------------------------------------------------------- UPDI devices Select timing module. TIMING_USING_RTC - use internal RTC TIMING_USING_TCA - use timer TCA channel 0 ----------------------------------------------------------------*/ #define MILLIS_TIMING_MODULE TIMING_USING_TCA
Timer error compensation
A positive or negative number that will be added/subtracted from the compare
register value. By setting a pin high then low inside the timer interrupt, a
logic analyzer can be used to measure timing accuracy then this value can be
adjusted accordingly.
/*-------------------------------------------------------------- Error calibration. A negative or positive number that will be added or subtracted from timer register value. ----------------------------------------------------------------*/ #define MILLIS_ERR_CAL 0 // usually 1 or -1 for RTC
Code example
Non-blocking delay using millis library:
#include "millis.h" int main(void){ millis_init(16000000); millis_t lastTime = 0; while(1){ if((millis_t)(millis_get() - lastTime) > 5000){ lastTime = millis_get(); // Code runs every 5 seconds } } }
Library Usage
Initialization
void millis_init(uint32_t f_cpu) void micros_init(uint32_t f_cpu, uint16_t resolution)
Configures the timer and enables global interrupts. For millis the
resolution is set to 1 millisecond.
f_cpu
CPU clock frequency in Hertz. When RTC is used as a timer, the frequency is always 32768.
resolution
This sets the micros interrupt frequency in microseconds. For non-UPDI devices, the maximum value is 100 microseconds. For UPDI devices, when RTC is used, the minimum value is 120us because the RTC clock is 32768 Hz with a resolution of 30.5us but this value is multiplied by 4 RTC clocks.
Get time
millis_t millis_get() micros_t micros_get()
Returns the number of milliseconds / microseconds since the init function was executed or since the last overflow of the variable.
Dealing with millis or micros overflows
Depending on the millis_t data type (uint8_t, uint16_t, uint32_t or uint64_t) the global variable milliseconds or microseconds that holds the time, will eventually reach it's maximum value and then overflow back to 0.
Most of the time you need to use this functions like this:
uint16_t interval = 1000; uint16_t lastTime = 0; if(micros() - lastTime >= interval){ lastTime = micros(); blink_led(); // 1000ms interval (1s) }
After the overflow the micros() will return smaller values than
lastTime and the subtraction result will be negative and you don't want that.
To solve this issue, simply cast the result to an unsigned integer like
this:
uint16_t interval = 1000; uint16_t lastTime = 0; if((micros_t) micros() - lastTime >= interval){ lastTime = micros(); blink_led(); // 1000ms interval (1s) }
For more details consider this link https://arduino.stackexchange.com/questions/12587/how-can-i-handle-the-millis-rollover/12588#12588.
Pause timer
void millis_pause() void micros_pause()
Pause and turn off timer to save power.
Resume timer
void millis_resume() void micros_resume()
Turn the timer back on.
Reset timer
void millis_reset() void micros_reset()
Reset milliseconds / microseconds count to 0.
Add time
void millis_add(millis_t ms) void micros_add(micros_t ms)
Add microseconds / milliseconds.
Subtract time
void millis_subtract(millis_t ms) void micros_subtract(micros_t ms)
Subtract microseconds / milliseconds.
Attach interrupt function
void millis_interrupt_attach(void (*funcPtr)(void))
Attach a custom function to timer interrupt.
Usage:
millis_interrupt_attach(btnReader);The function btnReader will be executed on each interrupt.
Error, OCRA and prescaler tables based on CPU frequency for 1 millisecond
timer interrupt - Timer0, Timer1 and Timer2
Error, OCRA and prescaler tables based on CPU frequency and time resolution in microseconds timer interrupt - Timer0, Timer1 and Timer2
Notice the error is 0% for most CPU frequencies however the time accuracy will
also depend on how accurate the RC oscillator or crystal will be.
Download
| millis v2.1 | ||
| millis.h | ||
| millis.c | ||
| micros v2.0 | ||
| micros.h | ||
| micros.c | ||
| Other links | ||
| spreadsheet calculator for LibreOffice | Error and OCR calculator based on time resolution and CPU frequency | |
| Changelog | ||
| v2.1 |
7, March, 2024: - millis: a callback function was included in the timer interrupt that can be attached to a custom user function. |
|
| v2.0 | - added support for modern AVR (UPDI devices). Tested on tinyAVR402. | |
No comments:
Post a Comment