Provide access to left-over milliseconds

Readme.md

@@ -32,8 +32,6 @@ there are also functions to return the hour in 12-hour format
 hourFormat12();    // the hour now in 12 hour format
 isAM();            // returns true if time now is AM
 isPM();            // returns true if time now is PM
-
-now();             // returns the current time as seconds since Jan 1 1970
 ```
 
 The time and date functions can take an optional parameter for the time. This prevents
@@ -52,13 +50,24 @@ month(t);         // the month for the given time t
 year(t);          // the year for the given time t
 ```
 
+There are also two functions that return the number of milliseconds left-over. Care
+should be taken when using this value since there are no functions to set the time
+with sub-second accuracy and the value may jump when the time is synchronized.
+However, it is always consistent with the current time. To access these functions,
+you have to `#define TIMELIB_ENABLE_MILLIS` in your sketch.
+
+```c
+time_t t = now(uint32_t& m) // store the current time in time variable t and milliseconds in m
+millisecond();     // the millisecond now (0-999)
+```
+
 Functions for managing the timer services are:
 
 ```c
 setTime(t);                      // set the system time to the give time t
 setTime(hr,min,sec,day,mnth,yr); // alternative to above, yr is 2 or 4 digit yr
                                  // (2010 or 10 sets year to 2010)
-adjustTime(adjustment);          // adjust system time by adding the adjustment value
+adjustTime(adjustment);          // adjust system time by adding the adjustment value (in seconds)
 timeStatus();                    // indicates if time has been set and recently synchronized
                                  // returns one of the following enumerations:
 timeNotSet                       // the time has never been set, the clock started on Jan 1, 1970

Time.cpp

@@ -33,6 +33,7 @@
 #include <WProgram.h> 
 #endif
 
+#define TIMELIB_ENABLE_MILLIS
 #include "TimeLib.h"
 
 static tmElements_t tm;          // a cache of time elements
@@ -103,6 +104,12 @@ int second(time_t t) {  // the second for the given time
   return tm.Second;
 }
 
+int millisecond() {
+  uint32_t ms;
+  now(ms);
+  return (int)ms;
+}
+
 int day(){
   return(day(now())); 
 }
@@ -248,9 +255,16 @@ time_t sysUnsyncedTime = 0; // the time sysTime unadjusted by sync
 
 
 time_t now() {
-	// calculate number of seconds passed since last call to now()
-  while (millis() - prevMillis >= 1000) {
-		// millis() and prevMillis are both unsigned ints thus the subtraction will always be the absolute value of the difference
+  uint32_t sysTimeMillis;
+  return now(sysTimeMillis);
+}
+
+time_t now(uint32_t& sysTimeMillis) {
+  // calculate number of seconds passed since last call to now()
+  while ((sysTimeMillis = millis() - prevMillis) >= 1000) {
+    // millis() and prevMillis are both unsigned ints thus the subtraction will
+    // always result in a positive difference. This is OK since it corrects for
+    // wrap-around and millis() is monotonic.
     sysTime++;
     prevMillis += 1000;	
 #ifdef TIME_DRIFT_INFO

TimeLib.h

@@ -108,6 +108,9 @@ int     minute();          // the minute now
 int     minute(time_t t);  // the minute for the given time
 int     second();          // the second now 
 int     second(time_t t);  // the second for the given time
+#ifdef TIMELIB_ENABLE_MILLIS
+int     millisecond();     // the millisecond now
+#endif
 int     day();             // the day now 
 int     day(time_t t);     // the day for the given time
 int     weekday();         // the weekday now (Sunday is day 1) 
@@ -118,6 +121,9 @@ int     year();            // the full four digit year: (2009, 2010 etc)
 int     year(time_t t);    // the year for the given time
 
 time_t now();              // return the current time as seconds since Jan 1 1970 
+#ifdef TIMELIB_ENABLE_MILLIS
+time_t now(uint32_t& sysTimeMillis); // return the current time as seconds and milliseconds since Jan 1 1970
+#endif
 void    setTime(time_t t);
 void    setTime(int hr,int min,int sec,int day, int month, int yr);
 void    adjustTime(long adjustment);

keywords.txt

@@ -10,6 +10,7 @@ time_t	KEYWORD1
 # Methods and Functions (KEYWORD2)
 #######################################
 now	KEYWORD2
+millisecond	KEYWORD2
 second	KEYWORD2
 minute	KEYWORD2
 hour	KEYWORD2