refactor API, begin() (#27)

- refactor API, begin()
- update readme.md
- remove obsolete getAddr() => **getAddress()**
- rename brightness() => **setBrightness()**
- add **getBrightness()**
- rename blink() ==> **setBlink()**
- add **getBlink()**
- minor edits

Author: RobTillaart

CHANGELOG.md

@@ -6,11 +6,22 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.4.0] - 2023-12-05
+- refactor API, begin()
+- update readme.md
+- remove obsolete getAddr() => **getAddress()**
+- rename brightness() => **setBrightness()**
+- add **getBrightness()**
+- rename blink() ==> **setBlink()**
+- add **getBlink()**
+- minor edits
+
+----
+
 ## [0.3.9] - 2023-09-22
 - add Wire1 support for ESP32
 - update readme.md
 
-
 ## [0.3.8] - 2023-02-26
 - add **getBrightness()**
 - moved code to .cpp file (prep 0.4.0)
@@ -20,7 +31,6 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - update license 2023
 - minor edits
 
-
 ## [0.3.7] - 2022-11-19
 - add displayUnit(float, char);
 - add top c symbol

HT16K33.cpp

@@ -1,7 +1,7 @@
 //
 //    FILE: HT16K33.cpp
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.3.9
+// VERSION: 0.4.0
 //    DATE: 2019-02-07
 // PURPOSE: Arduino Library for HT16K33 4x7segment display
 //     URL: https://github.com/RobTillaart/HT16K33
@@ -76,25 +76,8 @@ HT16K33::HT16K33(const uint8_t address, TwoWire *wire)
 }
 
 
-#if defined (ESP8266) || defined(ESP32)
-bool HT16K33::begin(uint8_t sda, uint8_t scl)
-{
-  if ((sda < 255) && (scl < 255))
-  {
-    _wire->begin(sda, scl);
-  } else {
-    _wire->begin();
-  }
-  if (! isConnected()) return false;
-  reset();
-  return true;
-}
-#endif
-
-
 bool HT16K33::begin()
 {
-  _wire->begin();
   if (! isConnected()) return false;
   reset();
   return true;
@@ -113,7 +96,8 @@ void HT16K33::reset()
   displayClear();
   setDigits(1);
   clearCache();
-  brightness(8);
+  setBrightness(8);
+  setBlink(0);
 }
 
 
@@ -136,7 +120,6 @@ void HT16K33::cacheOn()
 }
 
 
-
 void HT16K33::cacheOff()
 {
   _cache = false;
@@ -157,7 +140,7 @@ void HT16K33::displayOn()
 {
   writeCmd(HT16K33_ON);
   writeCmd(HT16K33_DISPLAYON);
-  brightness(_bright);
+  setBrightness(_bright);
 }
 
 
@@ -168,14 +151,21 @@ void HT16K33::displayOff()
 }
 
 
-void HT16K33::blink(uint8_t value)
+void HT16K33::setBlink(uint8_t value)
 {
   if (value > 0x03) value = 0x00;
+  _blink = value;
   writeCmd(HT16K33_BLINKOFF | (value << 1) );
 }
 
 
-void HT16K33::brightness(uint8_t value)
+uint8_t HT16K33::getBlink()
+{
+  return _blink;
+}
+
+
+void HT16K33::setBrightness(uint8_t value)
 {
   if (value == _bright) return;
   _bright = value;
@@ -196,6 +186,12 @@ void HT16K33::setDigits(uint8_t value)
 }
 
 
+uint8_t HT16K33::getDigits()
+{
+  return _digits;
+}
+
+
 void HT16K33::suppressLeadingZeroPlaces(uint8_t value)
 {
   _digits = value > 4 ? 0 : 4 - value;
@@ -433,27 +429,31 @@ bool HT16K33::displayFixedPoint0(float f)
   return inRange;
 }
 
+
 bool HT16K33::displayFixedPoint1(float f)
 {
   bool inRange = ((-99.5 < f) && (f < 999.95));
   displayFloat(f, 1);
   return inRange;
 }
 
+
 bool HT16K33::displayFixedPoint2(float f)
 {
   bool inRange = ((-9.95 < f) && (f < 99.995));
   displayFloat(f, 2);
   return inRange;
 }
 
+
 bool HT16K33::displayFixedPoint3(float f)
 {
   bool inRange = ((0 < f) && (f < 9.9995));
   displayFloat(f, 3);
   return inRange;
 }
 
+
 /////////////////////////////////////////////////////////////////////
 
 void HT16K33::displayTest(uint8_t del)
@@ -608,11 +608,6 @@ uint8_t HT16K33::getAddress()
 
 
 
-
-
-
-
-
 //////////////////////////////////////////////////////////
 //
 // PRIVATE
@@ -628,6 +623,7 @@ void HT16K33::_refresh()
   }
 }
 
+
 void HT16K33::writeCmd(uint8_t cmd)
 {
   _wire->beginTransmission(_address);

HT16K33.h

@@ -2,7 +2,7 @@
 //
 //    FILE: HT16K33.h
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.3.9
+// VERSION: 0.4.0
 //    DATE: 2019-02-07
 // PURPOSE: Arduino Library for HT16K33 4x7segment display
 //          http://www.adafruit.com/products/1002
@@ -13,7 +13,7 @@
 #include "Wire.h"
 
 
-#define HT16K33_LIB_VERSION         (F("0.3.9"))
+#define HT16K33_LIB_VERSION         (F("0.4.0"))
 
 
 //  Characters
@@ -45,12 +45,8 @@ class HT16K33
 public:
   HT16K33(const uint8_t address, TwoWire *wire = &Wire);   //  0x70 .. 0x77
 
-#if defined (ESP8266) || defined(ESP32)
-  bool    begin(uint8_t sda, uint8_t scl);
-#endif
   bool    begin();
   void    reset();
-
   bool    isConnected();
 
   //  default _cache is true as it is ~3x faster but if one has noise
@@ -64,13 +60,16 @@ class HT16K33
   void    displayOn();
   void    displayOff();
 
-  void    brightness(uint8_t value);             //  0 .. 15
+  void    setBrightness(uint8_t value);          //  0 .. 15
   uint8_t getBrightness();
-  void    blink(uint8_t value);                  //  0 .. 3     0 = off
+  void    setBlink(uint8_t value);               //  0 .. 3     0 = off
+  uint8_t getBlink();
 
 
   //  0,1,2,3,4 digits - will replace suppressLeadingZeroPlaces
   void    setDigits(uint8_t value);
+  uint8_t getDigits();
+
 
   void    displayClear();
   bool    displayInt(int n);                   //  -999 .. 9999
@@ -122,14 +121,14 @@ class HT16K33
   bool    displayFixedPoint2(float f);
   bool    displayFixedPoint3(float f);
 
-
-  //  OBSOLETE SOON
-  //  use getAddress(); instead.
-  uint8_t getAddr()    { return getAddress(); };
-  
   //  use setDigits(); instead.
   //  0 = off, 1,2,3,4 digits  space instead of 0
-  void suppressLeadingZeroPlaces(uint8_t value);
+  void    suppressLeadingZeroPlaces(uint8_t value);
+
+
+  //  OBSOLETE 0.4.x
+  void    brightness(uint8_t value) { setBrightness(value); };
+  void    blink(uint8_t value)      { setBlink(value); };
 
 
 private:
@@ -143,6 +142,7 @@ class HT16K33
   bool    _cache = true;
   uint8_t _digits = 0;
   uint8_t _bright;
+  uint8_t _blink;
 
   TwoWire*  _wire;
 };

README.md

@@ -25,6 +25,15 @@ it is faster for writing on average. The actual gain depends on the
 application and of course the values. 
 
 
+#### 0.4.0 Breaking change
+
+Version 0.4.0 introduced a breaking change.
+You cannot set the pins in **begin()** any more.
+This reduces the dependency of processor dependent Wire implementations.
+The user has to call **Wire.begin()** and can optionally set the Wire pins 
+before calling **begin()**.
+
+
 ## Perfomance 
 
 Version 0.3.0 allows one to switch the caching on/off to enforce
@@ -66,13 +75,12 @@ get leading/trailing zero's correctly.
 #### Setup behaviour
 
 - **HT16K33(const uint8_t address)** address is 0x70..0x77 depending on the jumpers A0..A2. **0x70** is default.
-- **bool begin(uint8_t sda, uint8_t scl)** for ESP32, select I2C pins, initialize I2C and calls **reset()**. 
-Returns false if device not seen on I2C bus.
-- **bool begin()** initialize I2C and calls **reset()**.
-Returns false if device not seen on I2C bus.
-- **bool isConnected()** Returns false if device not seen on I2C bus.
+- **bool begin()** initialize library and calls **reset()**.
+Returns false if address not seen on I2C bus.
+- **bool isConnected()** Returns false if address not seen on I2C bus.
 - **void reset()** resets display.
 
+
 #### Cache
 
 - **void clearCache()** forced clearing of the cache, to be used to switch the cache off just for one write.
@@ -83,10 +91,12 @@ Returns false if device not seen on I2C bus.
 
 - **void displayOn()** enable display.
 - **void displayOff()** disable display, fast way to darken display e.g. for energy consumption.
-- **void brightness(uint8_t value)** values (dim) 0..15 (bright).
-- **void blink(uint8_t value)** values 0..3   0 = off.
+- **void setBrightness(uint8_t value)** values (dim) 0..15 (bright).
+- **void getBrightness()** returns (dim) 0..15 (bright).
+- **void setBlink(uint8_t value)** values 0..3   0 = off.
+- **void getBlink(uint8_t value)** values 0..3   0 = off.
 - **void setDigits(uint8_t value)** values 0..4, minimal number of digits shown, mandatory for large numbers on dual display.
-- **uint8_t getAddress()** idem.
+
 
 
 #### Data types
@@ -115,9 +125,7 @@ The unitChar must be one of the chars supported like HT16K33_C, HT16K33_TOP_C or
 So **displayUnit(25.6, 1, HT16K33_DEGREE)** will display **23.5°**.
 
 
-#### Experimental fixed point
-
-These functions are new and still under investigation.
+#### Fixed point
 
 - **bool displayFixedPoint0(float f)** displays values -999  .. 9999 without decimals.
 - **bool displayFixedPoint1(float f)** displays values -99.9 .. 999.9 with 1 decimals.
@@ -137,7 +145,7 @@ These functions are new and still under investigation.
 - **void display(uint8_t \* array, uint8_t point)** idem + point = position of the digit with point (0..3).
 - **void displayColon(uint8_t on)** 0 = off, all values other are on.
 - **void displayRaw(uint8_t \* array, bool colon)** array of 4 bytes to control one 7seg display + colon flag.
-- **void displayExtraLeds(uint8_t value)** switch on extra leds.
+- **void displayExtraLeds(uint8_t value)** switch on extra LEDs.
 value is in fact a bit mask see table below. 0 = all off.
 
 
@@ -160,12 +168,13 @@ value is in fact a bit mask see table below. 0 = all off.
 - **void dumpSerial(uint8_t \* array, uint8_t point)** debugging equivalent of the display.
 Prints to Serial.
 - **void dumpSerial()** print HEX codes equivalent of the display to Serial.
+- **uint8_t getAddress()** idem.
 
 
-#### Obsolete
+#### Obsolete soon
 
-- suppressLeadingZeroPlaces(uint8_t value) use **setDigits()**
-- getAddr() use **getAddress()**
+- brightness() use setBrightness()
+- blink() use setBlink()
 
 
 ## Characters supported
@@ -209,18 +218,13 @@ See examples
 
 #### Must
 
-Mainly for a 0.4.0
+Mainly for a 0.4.x
 
 - **bool isDisplayOn()** and similar state functions
   - configuration byte: 4 bits brightness, 1 bit on off flag, 1 bit cache flag, 2 blink rate
-  
-  
+
 #### Should 
 
-- **void setBrightness()**
-- **void setBlink()** and **uint8_t getBlink()**
-- **void getDigits()**
-- **FixedPoint()** regular (experimental in 0.3.2)
 
 
 #### Could
@@ -233,7 +237,6 @@ Mainly for a 0.4.0
   - [status] dd.d
 - add examples
   - car battery monitor (voltage divider & analogRead)
-  - 
 - add more "special chars"?
   - #define HT16K33_P  Pascal / Pressure   0x73
   - #define HT16K33_J  joule               0x0E