0.7.3 PCA9685_RT

Author: RobTillaart

libraries/PCA9685_RT/.arduino-ci.yml

@@ -20,7 +20,7 @@ compile:
     # - due
     # - zero
     # - leonardo
-    - m4
+    # - m4
     - esp32
     # - esp8266
     # - mega2560

libraries/PCA9685_RT/.github/workflows/arduino-lint.yml

@@ -6,8 +6,8 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
-      - uses: actions/checkout@v4
-      - uses: arduino/arduino-lint-action@v1
+      - uses: actions/checkout@v5
+      - uses: arduino/arduino-lint-action@v2
         with:
           library-manager: update
           compliance: strict

libraries/PCA9685_RT/.github/workflows/arduino_test_runner.yml

@@ -8,7 +8,7 @@ jobs:
     timeout-minutes: 20
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: 2.6

libraries/PCA9685_RT/.github/workflows/jsoncheck.yml

@@ -5,13 +5,15 @@ on:
     paths:
       - '**.json'
   pull_request:
+    paths:
+      - '**.json'
 
 jobs:
   test:
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: json-syntax-check
         uses: limitusus/json-syntax-check@v2
         with:

libraries/PCA9685_RT/CHANGELOG.md

@@ -6,6 +6,18 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.7.3] - 2025-11-13
+- fix #29, add read1()
+- fix mask in setPWM()
+- refactored getPWM()
+- update GitHub actions
+- made some functions explicit deprecated.
+- update examples
+- update readme.md
+- update keywords.txt
+- minor edits
+
+
 ## [0.7.2] - 2025-05-08
 - fix #30, Sync with PCA9634
 - fix OutputEnable pin code

libraries/PCA9685_RT/PCA9685.cpp

@@ -2,7 +2,7 @@
 //    FILE: PCA9685.cpp
 //  AUTHOR: Rob Tillaart
 //    DATE: 24-apr-2016
-// VERSION: 0.7.2
+// VERSION: 0.7.3
 // PURPOSE: Arduino library for PCA9685 I2C LED driver, 16 channel PWM, 12 bit.
 //     URL: https://github.com/RobTillaart/PCA9685_RT
 
@@ -139,9 +139,10 @@ uint8_t PCA9685::setPWM(uint8_t channel, uint16_t onTime, uint16_t offTime)
     _error = PCA9685_ERR_CHANNEL;
     return _error;
   }
-  offTime &= 0x0FFFF;   //  non-doc feature - to easy set figure 8 P.17
   uint8_t reg = PCA9685_CHANNEL(channel);
-  return writeRegister2(reg, onTime, offTime);
+  //  mask both onTime and offTime to be in range 0..4095
+  //  allows to set the FULL_ON / FULL OFF bits.
+  return writeRegister2(reg, onTime & 0x1FFF, offTime & 0x1FFF);
 }
 
 
@@ -153,6 +154,7 @@ uint8_t PCA9685::setPWM(uint8_t channel, uint16_t offTime)
 
 
 //  read value from single PWM channel
+//  may include FULL_ON or FULL_OFF bit.
 uint8_t PCA9685::getPWM(uint8_t channel, uint16_t* onTime, uint16_t* offTime)
 {
   _error = PCA9685_OK;
@@ -162,19 +164,7 @@ uint8_t PCA9685::getPWM(uint8_t channel, uint16_t* onTime, uint16_t* offTime)
     return _error;
   }
   uint8_t reg = PCA9685_CHANNEL(channel);
-  _wire->beginTransmission(_address);
-  _wire->write(reg);
-  _error = _wire->endTransmission();
-  if (_wire->requestFrom(_address, (uint8_t)4) != 4)
-  {
-    _error = PCA9685_ERR_I2C;
-    return _error;
-  }
-  uint16_t _data = _wire->read();
-  *onTime = (_wire->read() * 256) + _data;
-  _data = _wire->read();
-  *offTime = (_wire->read() * 256) + _data;
-  return _error;
+  return readRegister2(reg, onTime, offTime);
 }
 
 
@@ -199,8 +189,8 @@ uint8_t PCA9685::setFrequency(uint16_t freq, int offset)
 }
 
 
-//  returns the actual used frequency.
-//  therefore it does not use offset
+//  cache == false returns the actual used frequency.
+//  cache == true returns the frequency without pre-scaler (offset).
 uint16_t PCA9685::getFrequency(bool cache)
 {
   _error = PCA9685_OK;
@@ -230,6 +220,31 @@ uint8_t PCA9685::write1(uint8_t channel, uint8_t mode)
 }
 
 
+//  See #29 for discussion.
+uint8_t PCA9685::read1(uint8_t channel)
+{
+  _error = PCA9685_OK;
+  if (channel >= _channelCount)
+  {
+    _error = PCA9685_ERR_CHANNEL;
+    return _error;
+  }
+
+  uint8_t reg = PCA9685_CHANNEL(channel);
+
+  uint16_t on, off;
+  if (readRegister2(reg, &on, &off) != PCA9685_OK) return 2;
+  if (on  & 0x1000) return HIGH;  //  FULL_ON
+  if (off & 0x1000) return LOW;   //  FULL_OFF
+
+  uint16_t duty = (off - on) & 0x0FFF;
+  if (duty == 4095) return HIGH;  //  PWM = 100%
+  if (duty == 0)    return LOW;   //  PWM = 0%
+
+  return 2;  //  not HIGH not LOW => use getPWM() to get PWM value.
+}
+
+
 uint8_t PCA9685::allOFF()
 {
   _error = PCA9685_OK;
@@ -479,6 +494,7 @@ uint8_t PCA9685::readRegister(uint8_t reg)
   _wire->beginTransmission(_address);
   _wire->write(reg);
   _error = _wire->endTransmission();
+  if (_error != PCA9685_OK) return 0;
 
   if (_wire->requestFrom(_address, (uint8_t)1) != 1)
   {
@@ -490,5 +506,26 @@ uint8_t PCA9685::readRegister(uint8_t reg)
 }
 
 
+int PCA9685::readRegister2(uint8_t reg, uint16_t * v1, uint16_t * v2)
+{
+  _wire->beginTransmission(_address);
+  _wire->write(reg);
+  _error = _wire->endTransmission();
+  if (_error != PCA9685_OK) return _error;
+
+  if (_wire->requestFrom(_address, (uint8_t)4) != 4)
+  {
+    _error = PCA9685_ERR_I2C;
+    return _error;
+  }
+  uint16_t data = _wire->read();
+  *v1 = (_wire->read() * 256) + data;
+  data = _wire->read();
+  *v2 = (_wire->read() * 256) + data;
+  _error = PCA9685_OK;
+  return _error;
+}
+
+
 //  -- END OF FILE --
 

libraries/PCA9685_RT/PCA9685.h

@@ -3,7 +3,7 @@
 //    FILE: PCA9685.h
 //  AUTHOR: Rob Tillaart
 //    DATE: 24-apr-2016
-// VERSION: 0.7.2
+// VERSION: 0.7.3
 // PURPOSE: Arduino library for PCA9685 I2C LED driver, 16 channel PWM, 12 bit.
 //     URL: https://github.com/RobTillaart/PCA9685_RT
 
@@ -12,7 +12,7 @@
 #include "Wire.h"
 
 
-#define PCA9685_LIB_VERSION         (F("0.7.2"))
+#define PCA9685_LIB_VERSION         (F("0.7.3"))
 
 // ERROR CODES
 #define PCA9685_OK                  0x00
@@ -111,6 +111,7 @@ class PCA9685
   //  onTime = 0..4095, offTime = 0..4095
   //  allows shifted PWM's e.g. 2 servo's that do not start at same time.
   //         this will distribute the (peak) load
+  //  a value of 4096 sets the FULL_ON or FULL_OFF bit.
   uint8_t  setPWM(uint8_t channel, uint16_t onTime, uint16_t offTime);
   uint8_t  getPWM(uint8_t channel, uint16_t* onTime, uint16_t* offTime);
 
@@ -123,19 +124,21 @@ class PCA9685
   //  note: as the frequency is converted to an 8 bit pre-scaler
   //       the frequency set will seldom be exact, but best effort.
   uint8_t  setFrequency(uint16_t freq, int offset = 0);
+  //  cache == false returns the actual used frequency (with offset).
+  //  cache == true returns the set frequency without offset.
   uint16_t getFrequency(bool cache = true);
 
 
   /////////////////////////////////////////////////////
   //
   //  WRITE
   //
-  //  set channel  HIGH or LOW (effectively no PWM)
+  //  set channel  mode == HIGH or LOW (effectively no PWM)
   uint8_t  write1(uint8_t channel, uint8_t mode);
-
-  //  for backwards compatibility; will be removed in future
-  uint8_t  setON(uint8_t channel)   { return write1(channel, HIGH); };
-  uint8_t  setOFF(uint8_t channel)  { return write1(channel, LOW); };
+  //  returns {HIGH, LOW, 2},
+  //           2 => PWM value set; use getPWM() if needed.
+  //  check getError() to see if an I2C error occurred.
+  uint8_t  read1(uint8_t channel);
 
   uint8_t  allOFF();
 
@@ -192,14 +195,22 @@ class PCA9685
   //
   [[deprecated("use setMode1(value) or setMode2(value) instead")]]
   uint8_t  writeMode(uint8_t reg, uint8_t value);
+  [[deprecated("use getMode1() or getMode2() instead")]]
   uint8_t  readMode(uint8_t reg);
 
+  //  for backwards compatibility; will be removed in future
+  [[deprecated("use write1(uint8_t channel, uint8_t mode) instead")]]
+  uint8_t  setON(uint8_t channel)   { return write1(channel, HIGH); };
+  [[deprecated("use write1(uint8_t channel, uint8_t mode) instead")]]
+  uint8_t  setOFF(uint8_t channel)  { return write1(channel, LOW); };
+
 
 private:
   //  DIRECT CONTROL
   uint8_t  writeRegister(uint8_t reg, uint8_t value);
   uint8_t  writeRegister2(uint8_t reg, uint16_t a, uint16_t b);
   uint8_t  readRegister(uint8_t reg);
+  int      readRegister2(uint8_t reg, uint16_t * v1, uint16_t * v2);
 
   uint8_t  _address;
   TwoWire * _wire;

libraries/PCA9685_RT/README.md

@@ -112,7 +112,7 @@ Obsolete in near future, use functions above as those are less error prone.
 
 ### Constants for mode registers
 
-|  Name                     |  Value  |  Description                         |
+|  MODE1 names              |  Value  |  Description                         |
 |:--------------------------|:-------:|:-------------------------------------|
 |  PCA9685_MODE1_RESTART    |  0x80   |  0 = disable       1 = enable        |
 |  PCA9685_MODE1_EXTCLK     |  0x40   |  0 = internal      1 = external      |
@@ -123,7 +123,10 @@ Obsolete in near future, use functions above as those are less error prone.
 |  PCA9685_MODE1_SUB3       |  0x02   |  0 = disable       1 = enable        |
 |  PCA9685_MODE1_ALLCALL    |  0x01   |  0 = disable       1 = enable        |
 |  PCA9685_MODE1_NONE       |  0x00   |                                      |
-|  ----                     |         |                                      |
+
+
+|  MODE2  names             |  Value  |  Description                         |
+|:--------------------------|:-------:|:-------------------------------------|
 |  PCA9685_MODE2_INVERT     |  0x10   |  0 = normal        1 = inverted      |
 |  PCA9685_MODE2_STOP       |  0x08   |  0 = on STOP       1 = on ACK        |
 |  PCA9685_MODE2_TOTEMPOLE  |  0x04   |  0 = open drain    1 = totem-pole    |
@@ -157,17 +160,23 @@ The signal is divided in 4096 steps, 0..4095.
 The pulse can begin **onTime** on any step and it can stop on any step **offTime**.
 This allows e.g. to distribute the power over the 16 channels, e.g. the
 channels do not need to start at the same moment with HIGH.
+The values 4096 allows to set the FULL_ON or FULL OFF bit.
 - **uint8_t setPWM(uint8_t channel, offTime)** simple PWM that always start on **onTime = 0**.
 - **uint8_t getPWM(uint8_t channel, uint16_t \* onTime, uint16_t \* offTime)** 
 read back the configuration of the channel.
+Note the values may include the FULL ON / FULL OFF bit (0x1000).
 - **uint8_t allOFF()** switches all PWM channels OFF. **Experimental** in 0.3.0.
 To "undo" the allOFF one can call the **reset()** function and set all 
 PWM channels again.
-- **uint8_t write1(channel, mode)** mode = HIGH or LOW, just use the PCA9685 as 
-a digital pin, write 1 bit.
-This single function replaces the setON() and setOFF() that will become
+- **uint8_t write1(uint8_t channel, uint8_t mode)** mode = HIGH or LOW, just use the PCA9685 as 
+a digital pin, write 1 bit. Returns PCA9685_OK or error code.
+This single write1() function replaces the setON() and setOFF() that will become
 obsolete in the future.
 
+**fix #29 experimental**
+- **uint8_t read1(uint8_t channel)** reads the status of the digital pin.
+Can return { LOW = 0, HIGH = 1, other = 2 } or an error code.
+
 
 ### Frequency 
 
@@ -185,7 +194,7 @@ After changing the frequency, one must set all channels (again),
 so one should set the frequency in **setup()**
 
 The parameter offset can be used to tune the **preScaler** to get a frequency
-closer to the requested value. See **PCA9685_setFrequency_offset** example. 
+closer to the requested value. See **PCA9685_setFrequency_offset.ino** example. 
 Default the offset = 0. As the **preScaler** is smaller at higher frequencies 
 higher frequencies are less accurate.
 Making offset too large can result in very incorrect frequencies.
@@ -205,6 +214,8 @@ When using offset, the **getFrequency(false)** will return the adjusted **preSca
 |  PCA9685_ERR_MODE    |   0xFD  |  Invalid mode
 |  PCA9685_ERR_I2C     |   0xFC  |  I2C communication error
 
+Be sure to check **lastError()** for possible errors if you want robustness.
+
 
 ## SUB CALL and ALL CALL
 
@@ -233,12 +244,16 @@ Typically there is only one such group but one can configure more of them by app
 
 The functions to enable all/sub-addresses are straightforward:
 
+SubCall functions:
+
 - **bool enableSubCall(uint8_t nr)** nr = 1,2,3
 - **bool disableSubCall(uint8_t nr)** nr = 1,2,3
 - **bool isEnabledSubCall(uint8_t nr)** nr = 1,2,3
 - **bool setSubCallAddress(uint8_t nr, uint8_t address)**
 - **uint8_t getSubCallAddress(uint8_t nr)**
 
+AllCall functions:
+
 - **bool enableAllCall()**
 - **bool disableAllCall()**
 - **bool isEnabledAllCall()**
@@ -310,14 +325,16 @@ For further details of the development, see - #10 (PCA9634 repo)
 - improve error handling
   - return values etc.
   - documentation.
-- #defines ==> const int?
+- #defines ==> const uint16_t ? (not possible for all defines)
+
 
 #### Could
 
 - default values for functions.
 - unit tests
 - investigate int vs uint16_t ?
   - **setFrequency(), getFrequency(), \_freq**
+- need for an **allON()** function?
 
 #### Wont
 

libraries/PCA9685_RT/examples/PCA9685_OE_control/PCA9685_OE_control.ino

@@ -14,6 +14,7 @@ PCA9685 ledArray(0x20);
 void setup()
 {
   Serial.begin(115200);
+  Serial.println();
   Serial.println(__FILE__);
   Serial.print("PCA9685_LIB_VERSION: ");
   Serial.println(PCA9685_LIB_VERSION);

libraries/PCA9685_RT/examples/PCA9685_allOFF_test/PCA9685_allOFF_test.ino

@@ -19,6 +19,7 @@ const uint8_t PIN = 2;
 void setup()
 {
   Serial.begin(115200);
+  Serial.println();
   Serial.println(__FILE__);
   Serial.print("PCA9685_LIB_VERSION: ");
   Serial.println(PCA9685_LIB_VERSION);