Configuration

TeensyTimerTool can be configured in the following two ways.

Change settings globally

To change settings for all sketches you can edit the file ./src/defautConfig.h in the library folder. Changing this file affects all sketches using TeensyTimerTool. Of course, updates of the library or reinstallation will overwrite the changes. So, if you want to go that route make sure to do a backup of the config file before updating.

Project scope settings

Instead of changing global settings in defaultConfig.h you can also copy the file to your sketch folder and rename it to 'userConfig.h'. If TeensyTimerTool finds this file it will read it instead of the default config.

Note: Depending on your build system, copying the config file might require a clean rebuild. This of course is only necessary once after copying the file. Subsequent config changes will be detected as usual and do not require a clean rebuild.

Settings

The following block shows the available settings.

#pragma once

#include "boardDef.h"
namespace TeensyTimerTool
{
//--------------------------------------------------------------------------------------------
// Timer pool defintion
// Add and sort as required

#if defined(T4_0)
    TimerGenerator* const timerPool[] = {GPT1, GPT2, TMR1, TMR2, TMR3, TMR4, TCK};

#elif defined(T3_6)
    TimerGenerator* const timerPool[] = {FTM0, FTM1, FTM2, FTM3, FTM4, TCK};

#elif defined(T3_5)
    TimerGenerator* const timerPool[] = {FTM0, FTM1, FTM2, FTM3, TCK};

#elif defined(T3_2)
    TimerGenerator* const timerPool[] = {FTM0, FTM1, FTM2, TCK};

#elif defined(T3_0)
    TimerGenerator* const timerPool[] = {FTM0, FTM1, TCK};

#elif defined(TLC)
    TimerGenerator* const timerPool[] = {TCK};

#elif defined(ESP32)
    TimerGenerator* const timerPool[] = {TCK};

#elif defined(UNO)
    TimerGenerator* const timerPool[] = {TCK};
#endif
    constexpr unsigned timerCnt = sizeof(timerPool) / sizeof(timerPool[0]);

//--------------------------------------------------------------------------------------------
// Timer Settings
//
// Default settings for various timers

// TMR (QUAD) Prescaler
    constexpr unsigned TMR_DEFAULT_PSC = 7;     // default prescaler, 0..7 -> prescaler= 1,2,4,...128, timer clock f=150MHz

// FTM Prescaler
    constexpr int FTM_DEFAULT_PSC = -1;         // -1: Auto, 0..7 -> prescaler= 1,2,4,...128, timer clock f=F_BUS

// GPT & PID
    constexpr bool USE_GPT_PIT_150MHz = false;  // changes the clock source for GPT and PIT from 24MHz (standard) to 150MHz, might have side effects!

// TCK yield() settings
    #define YIELD_NONE       0                  // Doesn't override yield at all, make sure to call TeensyTimerTool::Tick as often as possible
    #define YIELD_STANDARD   1                  // Uses the standard yield function and adds a call to TeensyTimerTool::Tick() lots of overhead in yield...
    #define YIELD_OPTIMIZED  2                  // Generate an optimized yield which only calls TeensyTimerTool::Tick()

    #define YIELD_TYPE YIELD_OPTIMIZED          // Select the required yield strategy here


//--------------------------------------------------------------------------------------------
// Callback type
// Uncomment if you prefer function pointer callbacks instead of std::function callbacks

//    #define PLAIN_VANILLA_CALLBACKS

//--------------------------------------------------------------------------------------------
// Advanced Features
// Uncomment if you need access to advanced features

//#define ENABLE_ADVANCED_FEATURES
}
}

TimerPool Settings

The TimerPool settings define which timer modules should be available to the timer pool. If you look at the setting for T4.0 you see that the pool contains both GPTs, all 4 TMR modules and the TCK timer. For a T4.0 and the settings from above the following code

PeriodicTimer t1,t2,t3,t4;

will generate timers using GPT1 (t1), GPT2 (t2), TMR1, ch1 (t3), TMR1, ch2 (t4). You can change this settings to fit your needs.

Timer Settings

Pre-Scaling the TMR channels

The TMR timers are clocked with 150MHz. Since these timers are only 16bit wide you'd get a maximum period of 1/150MHz * 2^16 = 437µs. For longer periods you can prescale the timer clock using the TMR_DEFAULT_PSC. Setting this to 0,1,2..7 leads to a pre-scale value of 1,2,4,...128 respectively. Using say 7 you'd get 128/150MHz = 0.853µs per tick and a maximum period of 128/150MHz * 2^16 = 55.9ms.

Pre-Scaling the FTM channels

The FTM timers are clocked with F_BUS. Since these timers are only 16bit wide you'd get a maximum period of 1/F_BUS * 2^16 = 1.36ms (assuming the standard F_BUS of 48MHz). For longer periods you can prescale the timer clock using the FTM_DEFAULT_PSC. Setting this to 0,1,2..7 leads to a pre-scale value of 1,2,4,...128 respectively. Using say 7 you'd get 128/150MHz = 0.853µs per tick and a maximum period of 128/F_BUS * 2^16 = 174ms (@F_BUS=48MHz). Setting this value to -1 uses an automatically calculated prescale value which generates about 1µs timer ticks.

Clock setting for the GPT and PIT timers

The USE_GPT_PID_150MHz setting determines if the GPT and PIT should use a 24MHz (default) or 150MHz clock. Please note that there is no possibility to change the clock for GPT or PIT individually. Changing this setting will also change the clock for the stock IntervalTimers.

TCK yield() settings

To run the software timers the function TeensyTimerTool::TCK_t::tick() needs to be called as often as possible. Per default the TeensyTimerTool changes the stock yield() function to automatically do this for you. With the following settings you can select a different tick strategy.

• YIELD_OPTIMIZED
  This is the default setting. The library generates a yield() function which only ticks the software timers.

• YIELD_STANDARD
  Choose this setting if you need the special functionality of the standard yield() function. The library generates a yield function which does exactly the same as the stock yield function (i.e., calling the SerialEvents and EventResponder handlers) and adds a call to the timer tick function at the end. Since the standard yield functionality generates significant overhead I recommend to use this setting only if you really use it.

• YIELD_NONE
  Use this setting if you want to call TeensyTimerTool::TCK_t::tick() yourself. In this case TeensyTimerTool does not touch the stock yield() at all.

Callback Type

This setting allows for switching the standard std::function interface for callbacks to the traditional void (f*)() function pointer interface. In some cases the function pointer interfaces is more efficient than the std::function interface. But of course you will loose all the benefits described in the callback chapter above.