TimeStamp Library

1. Purpose

TimeStamp library creates a background task that keeps track of time. A counter will automatically increase by 1 every millisecond goes by. The program can read that counter to see how much time has gone by since the last time it was checked. Timeout checking for multiple events can be implemented with this library, and the processor can be freed to do other tasks while an event is waiting.

2. Using the library

To include this library into the program, in Ansteron IDE, go to menu Build, select Compiler settings then add library file into Additional libraries section.

TimeStamp task will start running when function TimeStamp_start(); is called. The counter will also be reset to zero and will increase by one every millisecond. At any time, value of the counter can be read using function TimeStamp_get_ms(); or its synonym now(); . The value return is a long integer, which allows the longest timeout period of over 49 days. The counter can be reset to zero any time using function TimeStamp_reset(); .

For example, the program will reset TimeStamp counter when an event occurred. It will then doing other tasks and periodically checks if 2 second (2000 milliseconds) has passed.

If timeouts for multiple events need to be checked simultaneously, the program should save the time value when an event occurs then compare that with current time instead of resetting the counter. Note that variables that are used to store time values must have long type. See example below:


Larger image

In this example, the program uses two long variables to save the times and two signal variables to indicate if the event has occurred. If the event occurred, the time must have been captured. The program will compare the time value captured with current time by subtracting to determine timeout.

In this way, multiple events can be served. The number of events is only limited by available memory and processing power of the microcontroller, that varies for each program.

TimeStamp library does consume CPU processing time while running in the background. Whenever time tracking is not needed, background task can be turn off by calling function TimeStamp_stop(); .TimeStamp can always be restarted any time by calling TimeStamp_start(); mentioned above.

3. Use note

TimeStamp library is based on hardware interrupt. While the background task running, other function may be affected. Besides, other library may also affect the function TimeStamp library as well. Below are common situations:

While the background task of TimeStamp library is running, function delay_ms(time); of standard library will wait longer than given time. The reason is that delay function relies on counting CPU cycles to figure out the time. It does not know when TimeStamp library is running and consume some of the CPU time. TimeStamp library consumes 25.2% of CPU time. To work around, simply reduce the time giving to delay_ms() fuction by multiply with the percentage of CPU time variable. For example, if the program needs to delay 1000ms and TimeStamp library itself takes 25.2% of CPU time. There will be 74.8% left for the function, so enter 748ms instead. Another way is to use TimeStamp library to wait instead of delay_ms() function.

Function TimeStamp_delay_ms(long_value); can be used as well. However, this function will reset TimeStamp counter and should only be used if resetting the counter is permitted.

If the program call function system_disable_interrupt();, the background task of TimeStamp library is also disabled. If interrupts are only needed to be off for a short period of time, make sure that it will be re-enable within 16 microseconds. Otherwise, time tracking will be inaccurate.

SoftSerial library (software based Serial interface) will make time tracking inaccurate if using at the same time with TimeStamp library. Functions that send and receive data of SoftSerial library will temporally disable all interrupts, therefore background task of TimeStamp library will be disable as well. To avoid the effect, time tracking should not be used while sending or receiving data by SoftSerial.