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 its contents instead of the default config.

Please note the following platform depended instructions:

PlatformIO

In standard configuration PlatformIO will find your user config file and will do a clean rebuild after you copied the file. So, for PlatformIO, project scope settings will work out of the box. Just copy the defaultConfig file as described above and you are done.

VisualTeensy

VisualTeensy will also find your user config file. Just do a Build|Clean followed by a normal Build once you copied the config file and you are done.

Arduino IDE

The Arduino IDE / Teensyduino does not include the current sketch folder in the list of header search folders. Thus, the compiler will not find the user configuration file and can't read its contents.

Workaround: The Arduino builder allows users to override some settings done in platform.txt by copying a platform.local.txt into the architecture folder.

Here a link to a platform.local.txt which adds the sketch folder to the include search folders: platform.local.txt (right click -> save link). You need to copy that file into the same folder where you find platform.txt. I.e, into <arduino>/hardware/teensy/avr/. After that Arduino will find your user config file. A restart of the IDE might be necessary.

BTW: platform.local.txt will survive an update of Teensyduino and Arduino. If you want to deactivate it just rename or delete the file.

Available settings

The following block shows the available settings.

#pragma once

#include "boardDef.h"
namespace TeensyTimerTool
{
//--------------------------------------------------------------------------------------------
// Timer pool defintion
// Add, and sort and remove to define the timer pool. Timers will be allocted from left to right

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

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

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

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

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

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

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

#elif defined(ARDUINO_TEENSYLC)
    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]);

//--------------------------------------------------------------------------------------------
// Default settings for various timers

// TMR (QUAD)
    constexpr int TMR_DEFAULT_PSC = PSC_128;  // Allowed prescaling values: PSC_1, PSC_2, PSC_4 ... PSC_128, clock = 150MHz

// FTM
    constexpr int FTM_DEFAULT_PSC[] =         // Allowed prescaling values: PSC_AUTO, PSC_1, PSC_2, PSC_4 ... PSC_128, clock = FBUS
    {                                         // (PSC_AUTO adjusts prescaler to get roughly 2 timer ticks per µs)
        /*FTM0*/ PSC_AUTO,
        /*FTM1*/ PSC_AUTO,
        /*FTM2*/ PSC_AUTO,
        /*FTM3*/ PSC_AUTO
    };


// 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
    constexpr unsigned NR_OF_TCK_TIMERS = 20; // How many TCK timers shall be available

    #define YIELD_TYPE  YIELD_STANDARD        // Select the required yield strategy from the list below
                                              // YIELD_NONE:      lib doesn't touch yield. Make sure to call TeensyTimerTool::tick as often as possible
                                              // YIELD_STANDARD:  uses the standard yield function and adds a call to TeensyTimerTool::tick(). Lots of overhead in yield...
                                              // YIELD_OPTIMIZED: generate an optimized yield which only calls TeensyTimerTool::Tick()  (recommended if you don't use SerialEvents)




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

//   #define PLAIN_VANILLA_CALLBACKS

//--------------------------------------------------------------------------------------------
// Use c++14 time literals (e.g. 3.4s, 50ms ...) for time inputs
// Comment the following line if you don't want this.

    #define USE_TIME_LITERALS

//--------------------------------------------------------------------------------------------
// 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 the timer clock can be pre scaled using TMR_DEFAULT_PSC. Setting this to PSC_1 ... PSC_128 pre-scales the clock by 1,2,4,...128 respectively. Using say PSC_128 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 PSC_1 ... PSC_128 leads to a pre-scale value of 1,2,4,...128 respectively. Using say PSC_128 and F_BUS = 48MHz you'd get 128/F_BUS = 2.66µs per tick and a maximum period of 128/F_BUS * 2^16 = 175ms. Setting FTM_DEFAULT_PSC to PSC_AUTO uses an automatically calculated prescale value which tries to generate about 0.5µs timer ticks regardless of the used bus frequency F_BUS. You can do this setting for each FTM counter module.

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 The library generates a yield() function which only ticks the software timers. This is the recommended setting if you don't use the event responder or serial events. The only reason why this is not the standard setting is to avoid confusion for users using serial events.

• YIELD_STANDARD (Default setting) 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.