geekfactory/timelib

Time management library for embedded devices

GeekFactory TimeLib Library

This library contains Unix time routines and can be used as a software RTC on various microcontroller platforms. The library is itself very small in size and can be used in 8, 16 and 32 bit devices, including the AVR based arduino boards.

This work is based in Paul Stoffregen libraries for the Arduino platform.

Basic library usage

In order to use the library we need to call a function to set the time. Internally the time is kept in the unix format, so the library expects you to provide it in that format. Functions are provided for converting between human readable time/date and the Unix time.

The following snippet shows how to convert and set the TimeLib clock:

// Structure that holds human readable time information;
struct timelib_tm tinfo;
// Variable to hold Unix time
timelib_t initialt;

// Set time manually to 13:55:30 Jan 1st 2014
tinfo.tm_year = 14;
tinfo.tm_mon = 1;
tinfo.tm_mday = 1;
tinfo.tm_hour = 13;
tinfo.tm_min = 55;
tinfo.tm_sec = 30;

// Convert time structure to timestamp
initialt = timelib_make(&tinfo);

// Set system time counter
timelib_set(initialt);

// Configure the library to update every day
timelib_set_provider(time_provider, TIME_SECS_PER_DAY);

Basic library example using arduino

/**
   GeekFactory - "Construye tu propia tecnologia"
   Distribucion de materiales para el desarrollo e innovacion tecnologica
   www.geekfactory.mx

   Example of the TimeLib library in Arduino. This code should display the time on
   the serial monitor. User can set the time on the tinfo structure. This is a basic
   example that shows how the library can be used as software only RTC.
*/
#include "TimeLib.h"

// Structure that holds human readable time information;
struct timelib_tm tinfo;

timelib_t now, initialt;
// Store last time we sent the information
uint32_t last = 0;

void setup()
{
  // Configure serial port
  Serial.begin(115200);
  while (!Serial);

  // Set time manually to 13:55:30 Jan 1st 2014
  // YOU CAN SET THE TIME FOR THIS EXAMPLE HERE
  tinfo.tm_year = 14;
  tinfo.tm_mon = 1;
  tinfo.tm_mday = 1;
  tinfo.tm_hour = 13;
  tinfo.tm_min = 55;
  tinfo.tm_sec = 30;

  // Convert time structure to timestamp
  initialt = timelib_make(&tinfo);

  // Set system time counter
  timelib_set(initialt);

  // Configure the library to update / sync every day (for hardware RTC)
  timelib_set_provider(time_provider, TIMELIB_SECS_PER_DAY);
}

void loop()
{
  // Display the time every second
  if (millis() - last > 1000) {
    // Keep track of the time we last sent data to serial monitor
    last = millis();
    // Get the timestamp from the library
    now = timelib_get();
    // Convert to human readable format
    timelib_break(now, &tinfo);
    // Send to serial port
    Serial.print(tinfo.tm_hour);
    printDigits(tinfo.tm_min);
    printDigits(tinfo.tm_sec);
    Serial.print(" ");
    Serial.print(tinfo.tm_mday);
    Serial.print(" ");
    Serial.print(tinfo.tm_mon);
    Serial.print(" ");
    Serial.print(tinfo.tm_year);
    Serial.println();
  }
}

void printDigits(int digits)
{
  // utility function for digital clock display: prints preceding colon and leading 0
  Serial.print(":");
  if (digits < 10)
    Serial.print('0');
  Serial.print(digits);
}

timelib_t time_provider()
{
  // Prototype if the function providing time information
  return initialt;
}

Project Objectives

Our library should fulfill the following goals:

• Code should be portable to other platforms
• Library should be compact and have minimal dependencies
• Library should not include C++ code

Supported devices

This library was developed/tested on the following boards:

• PIC24HJ128GA504 devices using MPLAB X and XC16 compilers
• Arduino UNO R3
• Arduino Mega 2560 R3
• Basic testing on ESP8266 boards

The library is meant to work in other CPU architectures where a C compiler is available, please tell us about your experience if you try it in other platforms.

Contact me

• Feel free to write for any inquiry: ruben at geekfactory.mx
• Check our website: https://www.geekfactory.mx

timelib's Issues

Issue with timelib_get_status()

Hi! First of all, thanks for sharing this library. I am using it to convert time from human to epoch format and back together with a local RTC. I got an issue when trying to get the status to know if sending a NTP request was necessary or not.

My basic code is

if (E_TIME_OK == (time_status)timelib_get_status())
  {
    app.setTime(timelib_get());
  }

And I got a wrong status when calling timelib_get_status(). Checking the code, I noticed that the update of sys_time is done AFTER checking if sync_time <= sys_time. In this way, the first time we call timelib_get_status() will always return E_TIME_OK, since the sys_time wasn't updated yet. Hence, I believe the best implementation is to FIRST update sys_time to LATER check if we need a time sync:

timelib_t timelib_get()
{
	timelib_t now = 0;

	// Clock halted, return always the same value (no update)
	if (halt == true)
		return sys_time;

	// Check how many seconds have elapsed (if any) since the last call
	// and update the timestamp counter
	while (tick_get() - last_update >= TICK_SECOND) {
		// Increment timestamp
		sys_time++;
		last_update += TICK_SECOND;
	}
	
	// Check if time needs sync to timebase
	if (sync_next <= sys_time) {
		// Null pointer check
		if (timelib_provider_callback != 0) {
			// Invoke callback function
			now = timelib_provider_callback();
			// Got time from callback?
			if (now != 0) {
				timelib_set(now);
			} else {
				sync_next = sys_time + sync_interval;
				tstatus = (tstatus == E_TIME_NOT_SET) ? E_TIME_NOT_SET : E_TIME_NEEDS_SYNC;
			}
		}
	}

	return sys_time;
}

Am I missing something or we can do this modification?