add toSeconds() (#5)

- update readme.md
- implement **toSeconds()** -> 45.123 or 45.123456
- add **add()** to adjust the offset.
- update keywords.txt
- test on ESP32.
- update GitHub actions
- update license 2023

CHANGELOG.md

@@ -6,12 +6,21 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.2.5] - 2023-02-10
+- update readme.md
+- implement **toSeconds()** -> 45.123 or 45.123456
+- add **add()** to adjust the offset.
+- update keywords.txt
+- test on ESP32.
+- update GitHub actions
+- update license 2023
+
+
 ## [0.2.4] - 2022-11-26
 - Add RP2040 support to build-CI.
 - Add CHANGELOG.md
 - update readme.md
 
-
 ## [0.2.3] - 2021-12-29
 - update library.json
 - update license

README.md

@@ -1,4 +1,3 @@
-
 [![Arduino CI](https://github.com/RobTillaart/timing/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)
 [![Arduino-lint](https://github.com/RobTillaart/timing/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/RobTillaart/timing/actions/workflows/arduino-lint.yml)
 [![JSON check](https://github.com/RobTillaart/timing/actions/workflows/jsoncheck.yml/badge.svg)](https://github.com/RobTillaart/timing/actions/workflows/jsoncheck.yml)
@@ -8,77 +7,114 @@
 
 # Timing
 
-Arduino library with wrappers for seconds millis micros.
+Arduino library with wrappers for seconds, millis, and micros.
 
 
 ## Description
 
 A request often made on the Arduino forum and otherwise is an option to reset
-the **millis()** function to 0 or another value. 
-This library provide wrapper classes around **millis()** and **micros()** 
-with the extra function to do this. 
-To implement this only a 4 byte offset is needed.
+the **millis()** function to 0 or to another value.
+
+This library provide wrapper classes around **millis()** and **micros()**
+with the extra function to do reset the count by means of an offset.
+To implement this only a 4 byte offset is needed per "clock".
 
 The classes are based upon **millis()** and **micros()**.
-Therefore they have the same restrictions as these functions with respect to 
-overflow and accuracy. Depending on e.g. interrupts millis and micros can drift.
+Therefore they have the same restrictions as these functions with respect to
+overflow and accuracy. Depending on e.g. interrupts, millis() and micros() can drift.
 
 
 |  class         |  overflow after            |  Notes                |
 |:---------------|:---------------------------|:----------------------|
 |  seconds       |  49 days, 17:02:47         |  based upon millis()  |
-|  milliSeconds  |  49 days, 17:02:47.297     |
-|  microSeconds  |  00 days  01:11:34.967296  |
+|  milliSeconds  |  49 days, 17:02:47.297     |  based upon millis()  |
+|  microSeconds  |  00 days  01:11:34.967296  |  based upon micros()  |
+
+
+#### Tests
+
+Code is tested on UNO and ESP32, should work on all platforms.
+
+No performance tests as code is 'basic'.
 
 
 ## Applications
 
-These classes make it easy to make a simple stopwatch.
-Or sync the time with an external source. 
+These classes make it easy to make a simple stopwatch, clock or countdown timer.
+It is also possible to sync the time (e.g. millis()) with an external source,
+which could be another Arduino.
+
 
+## Interface
 
-## Interface 
+```cpp
+#include "timing.h"
+```
 
 The interface of all three are very similar:
 
 - **microSeconds()** constructor, sets the offset so it starts at 0.
 - **milliSeconds()** constructor, sets the offset so it starts at 0.
 - **seconds()** constructor, sets the offset so it starts at 0.
 - **uint32_t now()** returns the time elapsed since its 'zero moment'.
-Ether set during construction or by a call to **set(0)**. 
-- **void set(uint32_t value = 0UL)** sets the offset of the object. 
+Ether set during construction or by a call to **set(0)**.
+- **void set(uint32_t value = 0UL)** sets the offset of the object.
 As it is possible to set it to a non zero value it is easy to adjust the time.
 This allows one e.g. to compensate for overhead. Default = zero.
-- **uint32_t getOffset()** returns current offset.
+- **void add(uint32_t value)** allows one to increment or decrement the offset for calibration.
+Allows one to sync time e.g. with an external reference in small incremental steps.
+- **uint32_t getOffset()** returns current offset in base units.
+So seconds for seconds, millis for millis and micros for micros.
+- **double toSeconds()** returns a float representation of the current value in seconds.
+e.g. 15678 milliseconds becomes 15.678 seconds (SI units).
 
+#### Experimental
 
-## Operation
-
-See examples.
+- ** char \* toClock()** converts current seconds to a clock like char array "HH:MM:SS".
+Only for the seconds class for now.
 
 
 ## Future
 
-#### must
-- test on ESP32
+#### Must
 
-#### should
-- implement toClock() 
-  - idea to give it a clock print layout
-  - seconds.toClock() -> DD 12:34:56
+- update documentation
+  - describe rounding effect (seconds)
+
+#### Should
+
+- implement toClock()
+  - seconds.toClock() -> DD 12:34:56  (days ??)
   - milliSeconds.toClock(3) -> 12:23:45.123    (3) == 3 decimals..
   - milliSeconds.toClock(1) -> 12:23:45.1
   - microSeconds.toCLock()  -> 12:23:45.123456  ???
   - printHelpers class?
-- implement toSeconds()
-  - double milliSeconds.toSeconds() -> 45.123
-  - double microSeconds.toSeconds() -> 45.123456
 
-#### could
+
+```cpp
+  // something like this.
+  char * toClock()
+  {
+    static char buf[12];
+    uint32_t _now = now();
+    int hh = _now / 3600;
+    _now = _now - hh * 3600;
+    int mm  = _now / 60;
+    int ss = _now - mm * 60;
+    sprintf(buf, "%02d:%02d:%02d", hh, mm, ss);
+    return buf;
+  }
+```
+
+
+#### Could
+
 - nanos() on ESP32 ?
+  - measureable?
 - implement printable interface
   - add unit (s, ms, us)
   - what layout to use?
-- update documentation
-- rounding effect, describe
+- move code to .cpp file?
+
+#### Wont
 

examples/seconds_toClock/.arduino-ci.yml

@@ -0,0 +1,30 @@
+platforms:
+  rpipico:
+    board: rp2040:rp2040:rpipico
+    package: rp2040:rp2040
+    gcc:
+      features:
+      defines:
+        - ARDUINO_ARCH_RP2040
+      warnings:
+      flags:
+
+packages:
+  rp2040:rp2040:
+    url: https://github.com/earlephilhower/arduino-pico/releases/download/global/package_rp2040_index.json
+
+compile:
+  # Choosing to run compilation tests on 2 different Arduino platforms
+  platforms:
+    - uno
+    # - due
+    # - zero
+    # - leonardo
+    - m4
+    # - esp32  #  warning breaks Arduino build
+    - esp8266
+    # - mega2560
+    - rpipico
+  libraries:
+    - "printHelpers"
+

examples/seconds_toClock/seconds_toClock.ino

@@ -0,0 +1,33 @@
+//
+//    FILE: seconds_toClock.ino
+//  AUTHOR: Rob Tillaart
+// PURPOSE: demo simple clock
+//     URL: https://github.com/RobTillaart/timing
+
+
+#include "timing.h"
+
+uint32_t last = 0;
+
+seconds sec;
+
+void setup()
+{
+  Serial.begin(115200);
+  Serial.println(__FILE__);
+
+  sec.set(3545);
+}
+
+
+void loop()
+{
+  if (last != sec.now())
+  {
+    last = sec.now();
+    Serial.println(sec.toClock());
+  }
+}
+
+
+//  -- END OF FILE --

keywords.txt

@@ -10,6 +10,9 @@ seconds	KEYWORD1
 # Methods and Functions (KEYWORD2)
 now	KEYWORD2
 set	KEYWORD2
+add	KEYWORD2
+getOffset	KEYWORD2
+toSeconds	KEYWORD2
 
 
 # Constants (LITERAL1)

library.json

@@ -1,7 +1,7 @@
 {
   "name": "timing",
   "keywords": "seconds, milliSeconds, microSeconds, now, reset, zero",
-  "description": "Arduino library with wrapper classes for seconds millis micros. These wrappers allow to reset the value of the time.",
+  "description": "Arduino library with wrapper classes for seconds, millis and micros. These wrappers allow to reset the value of the time.",
   "authors":
   [
     {
@@ -15,7 +15,7 @@
     "type": "git",
     "url": "https://github.com/RobTillaart/timing"
   },
-  "version": "0.2.4",
+  "version": "0.2.5",
   "license": "MIT",
   "frameworks": "arduino",
   "platforms": "*",

library.properties

@@ -1,8 +1,8 @@
 name=timing
-version=0.2.4
+version=0.2.5
 author=Rob Tillaart <rob.tillaart@gmail.com>
 maintainer=Rob Tillaart <rob.tillaart@gmail.com>
-sentence=Arduino library with wrapper classes for seconds millis micros. 
+sentence=Arduino library with wrapper classes for seconds, millis and micros.
 paragraph=These wrappers allow to reset the value of the time.
 category=Data Processing
 url=https://github.com/RobTillaart/timing

test/unit_test_001.cpp

@@ -73,4 +73,5 @@ unittest(test_constructor)
 unittest_main()
 
 
-// --------
+//  --END OF FILE --
+

timing.h

@@ -1,22 +1,24 @@
 #pragma once
-// 
+//
 //    FILE: timing.h
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.2.4
-// PURPOSE: Arduino library with wrapper classes for seconds millis micros 
+// VERSION: 0.2.5
+// PURPOSE: Arduino library with wrapper classes for seconds millis micros
 //     URL: https://github.com/RobTillaart/timing
 
 
-#define TIMING_LIB_VERSION        (F("0.2.4"))
+#define TIMING_LIB_VERSION        (F("0.2.5"))
 
 
 class microSeconds
 {
 public:
-  microSeconds()                  { set(0); }
-  uint32_t now()                  { return micros() - _offset; }
-  void set(uint32_t value = 0UL)  { _offset = micros() - value; }
+  microSeconds()                  { set(0); };
+  uint32_t now()                  { return micros() - _offset; };
+  void set(uint32_t value = 0UL)  { _offset = micros() - value; };
+  void add(uint32_t value)        { _offset -= value; };
   uint32_t getOffset()            { return _offset; };
+  double toSeconds()              { return (millis() - _offset) * 0.000001; };
 
 private:
   uint32_t _offset = 0UL;
@@ -29,7 +31,9 @@ class milliSeconds
   milliSeconds()                  { set(0); };
   uint32_t now()                  { return millis() - _offset; };
   void set(uint32_t value = 0UL)  { _offset = millis() - value; };
+  void add(uint32_t value)        { _offset -= value; };
   uint32_t getOffset()            { return _offset; };
+  double toSeconds()              { return (millis() - _offset) * 0.001; };
 
 private:
   uint32_t _offset = 0UL;
@@ -39,15 +43,33 @@ class milliSeconds
 class seconds
 {
 public:
-  seconds()                       { set(0); }
-  uint32_t now()                  { return millis() / 1000UL - _offset; }
-  void set(uint32_t value = 0UL)  { _offset = millis() / 1000UL - value; }
+  seconds()                       { set(0); };
+  uint32_t now()                  { return millis() / 1000UL - _offset; };
+  void set(uint32_t value = 0UL)  { _offset = millis() / 1000UL - value; };
+  void add(uint32_t value)        { _offset -= value; };
   uint32_t getOffset()            { return _offset; };
+  //  for completeness
+  double toSeconds()              { return millis() * 0.001 - _offset; };
+
+  //  experimental
+  char * toClock()
+  {
+    static char buf[12];
+    uint32_t _now = now();
+    int hh = _now / 3600;
+    _now = _now - hh * 3600;
+    int mm  = _now / 60;
+    int ss = _now - mm * 60;
+    //  ESP32 warning breaks Arduino build. next line.
+    sprintf(buf, "%02d:%02d:%02d", hh, mm, ss);
+    return buf;
+  }
+
 
 private:
-    uint32_t _offset = 0UL;
+  uint32_t _offset = 0UL;
 };
 
 
-// -- END OF FILE --
+//  -- END OF FILE --