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,23 @@ 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.
+
+```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

@@ -103,6 +103,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 +254,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,7 @@ 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
+int millisecond(); // the millisecond now
 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 +119,7 @@ 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 
+time_t now(uint32_t& sysTimeMillis); // return the current time as seconds and milliseconds since Jan 1 1970
 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