Timers

WARNING: Do not use these functions unless you REALLY know what you are doing!

Timing in Nano-RK should be handled using the suspend calls described in the Time Management section. However, there are some situations when you require better than an OS quantum (about 1ms) time granularity. For example sampling the audio sensor for recording sound at a high frequency. In these cases, it is possible to setup a high speed timer interrupt that automatically calls a user defined function. Care should be taken when using a timer interrupts for four reasons. First, a timer callback could potentially interrupt at any point in the system operation which means that the interrupt could use additional stack space. This includes the kernel and the idle task stacks. Second, a high speed interrupt will keep the processor awake longer which in turn consumes energy. For correct operation, deep sleep power mode must be disabled. ( #define NRK_NO_POWER_DOWN in nrk_cfg.h ) Since the kernel's scheduler is not aware of user defined (potentially dynamic) timer interrupts, the node can only safely enter the idle power state and can not going into deep sleep (since only the OS timer wakes the system from deep sleep with a predictable latency). Third, interrupts are not prioritized on many micro controllers which means the callback function from the interrupt routine will execute at the highest priority in the system which is at an equal priority with the kernel. Finally, interrupt callback functions are not governed by reservations or controlled by the kernel in any way, so if the execution time of the interrupt is too long, all tasks can be starved.

The default state of the timers support below is the capture and compare count to counter and reset mode of operation. This means that a counter will start counting up from zero and once it reaches the capture compare threshold, it automatically resets to zero and triggers the interrupt function. This means that the counter can be free running to support periodic interrupts.

ATmega1281 Support Timers

NRK_APP_TIMER_0
  • 16 bit compare capture timer
  • Prescale Divider
    • 1 1
    • 2 8
    • 3 64
    • 4 256
    • 5 1024

ATmega128 Support Timers

NRK_APP_TIMER_0
  • 8 bit compare capture timer (only lower 8 bits are used in capture_compare value)
  • Prescale Divider
    • 1 1
    • 2 8
    • 3 64
    • 4 256
    • 5 512
    • 6 1024

nrk_timer_int_configure

nrk_status_t nrk_timer_int_configure( TIMER_ID, uint8_t divider, uint16_t capture_compare_value, void *callback_function )

Parameters: TIMER_ID is a #define selecting a particular system timer
Parameters: uint8_t divider sets the timer clock divider, this is a platform specific parameter.
Parameters: uint16_t capture_compare_value sets the compare value that the timer must reach before calling an interrupt
Parameters: void *callback_function is a function pointer for a user function that should be called by the timer
Return Values: NRK_OK or NRK_ERROR
 1// Setup application timer with:
 2//       Prescaler = 5 
 3//       Compare Match = 25000
 4//       Sys Clock = 7.3728 MHz
 5// Prescaler 5 means divide sys clock by 1024
 6// 7372800 / 1024 = 7200 Hz clock
 7// 1 / 7200 = 0.138 ms per tick
 8// 0.138 ms * 25000 = ~3472 ms / per interrupt callback
 9
10  val=nrk_timer_int_configure(NRK_APP_TIMER_0, 5, 25000, &my_timer_callback );
11  if(val==NRK_OK) nrk_kprintf( PSTR("Callback timer setup\r\n"));
12  else nrk_kprintf( PSTR("Error setting up timer callback\r\n"));

nrk_timer_int_reset

nrk_status_t nrk_timer_int_reset( TIMER_ID )

Parameters: TIMER_ID is a #define selecting a particular system timer
Return Values: NRK_OK or NRK_ERROR

This function will reset the counter value specified by TIMER_ID. The following code section shows how to stop, reset and start a timer.

 1  // stop the timer interrupt
 2  nrk_timer_int_stop(NRK_APP_TIMER_0);
 3
 4  // do some work that takes time
 5
 6  // Zero the timer
 7  nrk_timer_int_reset(NRK_APP_TIMER_0);
 8  // The timer will already be counting, so don't do any long work here!
 9  // Start the timer interrupt
10  nrk_timer_int_start(NRK_APP_TIMER_0);

nrk_timer_int_start

nrk_status_t nrk_timer_int_start( TIMER_ID )

Parameters: TIMER_ID is a #define selecting a particular system timer
Return Values: NRK_OK or NRK_ERROR

This function enables the interrupt for a particular timer. If the timer was already running, the interrupt will be triggered once the interrupt is enabled and the timer reaches the capture_compare value set by nrk_timer_int_configure().

nrk_timer_int_stop

nrk_status_t nrk_timer_int_stop( TIMER_ID )
Parameters: TIMER_ID is a #define selecting a particular system timer
Return Values: NRK_OK or NRK_ERROR

This function will disable the particular timer specified by TIMER_ID. This only disables the interrupt, but does not stop the timer from counting.

nrk_timer_int_read

uint16_t nrk_timer_int_read( TIMER_ID )

Parameters: TIMER_ID is a #define selecting a particular system timer
Return Values: uint16 with the current timer value

This function will return the current value of the timer specified by TIMER_ID.

External Interrupts

External interrupts are platform specific. Nano-RK has set aside various generic pin names that are typically used for interrupts, but be sure to check platform specific data sheets to verify correct wiring.

nrk_ext_int_configure

nrk_status_t nrk_ext_int_configure( INT_PIN_ID, NRK_EXT_INT_MODE, void *callback_function )

Parameters: INT_PIN_ID is a #define selecting a particular interrupt pin. This is not compatible with the normal NRK GPIO defines.
Parameters: NRK_EXT_INT_MODE is a #define selecting a particular way of triggering the interrupt. See below for more detail
Parameters: void *callback_function is the address of a function you wish to link with the particular interrupt
Return Values: NRK_OK or NRK_ERROR

This function sets up an external pin interrupt. It can be configured to execute a user defined callback function based on specific pin changes. The pins and modes of operation are platform specific. Interrupt must be enabled after configuration.

FireFly2_2 platform:
  • INT_PIN_ID
    • NRK_EXT_INT_0
      • Port D.0
    • NRK_EXT_INT_1
      • Port D.1
    • NRK_EXT_INT_2
      • Port D.2
    • NRK_PC_INT_0
      • Port B.0
      • PC_INT0 -> PC_INT7 share the same callback and are only NRK_LEVEL_TRIGGER compatible
    • NRK_PC_INT_1
      • Port B.1
      • PC_INT0 -> PC_INT7 share the same callback and are only NRK_LEVEL_TRIGGER compatible
    • NRK_PC_INT_2
      • Port B.2
      • PC_INT0 -> PC_INT7 share the same callback and are only NRK_LEVEL_TRIGGER compatible
    • NRK_PC_INT_3
      • Port B.3
      • PC_INT0 -> PC_INT7 share the same callback and are only NRK_LEVEL_TRIGGER compatible
    • NRK_PC_INT_4
      • Port B.4
      • PC_INT0 -> PC_INT7 share the same callback and are only NRK_LEVEL_TRIGGER compatible
    • NRK_PC_INT_5
      • Port B.5
      • PC_INT0 -> PC_INT7 share the same callback and are only NRK_LEVEL_TRIGGER compatible
    • NRK_PC_INT_6
      • Port B.6
      • PC_INT0 -> PC_INT7 share the same callback and are only NRK_LEVEL_TRIGGER compatible
    • NRK_PC_INT_7
      • Port B.7
      • PC_INT0 -> PC_INT7 share the same callback and are only NRK_LEVEL_TRIGGER compatible
  • NRK_EXT_INT_MODE
    • NRK_LOW_TRIGGER
      • callback triggered when pin is low
    • NRK_LEVEL_TRIGGER
      • callback triggered when pin changes level
    • NRK_FALLING_EDGE
      • callback triggered when pin goes from high to low
    • NRK_RISING_EDGE
      • callback triggered when pin goes from low to high

nrk_ext_int_enable

nrk_status_t nrk_ext_int_enable( INT_PIN_ID )

Parameters: INT_PIN_ID is a #define selecting a particular interrupt pin. This is not compatible with the normal NRK GPIO defines.
Return Values: NRK_OK or NRK_ERROR

This function will enable the interrupt specified for a particular pin.

nrk_ext_int_disable

nrk_status_t nrk_ext_int_disable( INT_PIN_ID )

Parameters: INT_PIN_ID is a #define selecting a particular interrupt pin. This is not compatible with the normal NRK GPIO defines.
Return Values: NRK_OK or NRK_ERROR

This function will disable the interrupt specified for a particular pin.

Prev: Contents Next: Critical Section Top