From 7d50cb36c0eae8aa62fa6f0116870fd5480716c4 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Wed, 10 Aug 2016 20:49:54 -0700 Subject: [PATCH 01/57] v1.2.3 release. --- PCA9685.cpp | 720 +++++++++++++++--- PCA9685.h | 227 ++++-- README.md | 228 ++++-- Screen Shot 2012-02-18 at 16.55.07.png | Bin 12400 -> 0 bytes library.properties | 9 + .../PCA9685 datasheet.pdf | Bin 6 files changed, 992 insertions(+), 192 deletions(-) delete mode 100644 Screen Shot 2012-02-18 at 16.55.07.png create mode 100644 library.properties rename PCA9685 datasheet.pdf => support files/PCA9685 datasheet.pdf (100%) diff --git a/PCA9685.cpp b/PCA9685.cpp index 0efb024..39a142b 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -1,5 +1,5 @@ -/* PCA9685 LED library for Arduino - Copyright (C) 2012 Kasper SkÃ¥rhøj +/* Arduino Library for the PCA9685 16-Channel PWM Driver Module. + Copyright (C) 2012 Kasper SkÃ¥rhøj This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -13,105 +13,645 @@ You should have received a copy of the GNU General Public License along with this program. If not, see . + + Created by Kasper SkÃ¥rhøj, August 3rd, 2012. + Forked by Vitska, June 18th, 2016. + Forked by NachtRaveVL, July 29th, 2016. + + PCA9685-Arduino - Version 1.2.3 */ + #include "PCA9685.h" -void PCA9685::begin(int i2cAddress) { - _i2cAddress = PCA9685_I2C_BASE_ADDRESS | (i2cAddress & B00111111); -} - -void PCA9685::init(byte mode) { - //Reset SWRST - Wire.beginTransmission(0); - Wire.write((byte)0x06); - Wire.endTransmission(); - //Init - Wire.beginTransmission(_i2cAddress); - Wire.write(PCA9685_MODE1); - Wire.write(0b00100000); //Autoincrement - Wire.write(mode); - Wire.endTransmission(); -} - -void PCA9685::setPwmFrequency(int hz){ - uint32_t val = 6104L / (uint32_t)hz; - if(val > 255)val = 255; - if(val < 3)val = 3; - Wire.beginTransmission(_i2cAddress); - Wire.write(PCA9685_PRE_SCALE); - Wire.write((byte)val); - Wire.endTransmission(); -} - -void PCA9685::on(int nr) { - writeChBegin(nr); - writeChannel(PCA9685_PWM_FULL, 0); - writeEnd(); -} - -void PCA9685::off(int nr) { - writeChBegin(nr); - writeChannel(0, PCA9685_PWM_FULL); - writeEnd(); -} - -void PCA9685::setChannel(byte nr, word amount) { // Amount from 0-100 (off-on) - writeChBegin(nr); - if (amount==PCA9685_CH_OFF){ - writeChannel(0, PCA9685_PWM_FULL); - } - else if (amount>=PCA9685_CH_ON){ - writeChannel(PCA9685_PWM_FULL, 0); - } - else { - //int randNumber = (int)random(4096); // Randomize the phaseshift to distribute load. Good idea? Hope so. - word phase = (4096 / 16) * nr; - writeChannel(phase, (amount+phase) & 0xFFF); - } - writeEnd(); -} - -// IN:avr/libraries/Wire.h -// avr/libraries/utility/twi.h -// BUFFER_LENGTH should be increased to 64 + 2 at least, default is 32 so only 7 lines could be written in one transaction -void PCA9685::setChannel(byte startch, byte count, const word* amount) { // Amount from 0-100 (off-on) - writeChBegin(startch); - word onval = 0, offval = 0; - for(byte i = 0; i < count; i++){ - if (amount[i]==PCA9685_CH_OFF){ - onval = 0; - offval = PCA9685_PWM_FULL; +#define PCA9685_I2C_BASE_ADDRESS (byte)0x40 + +// Register addresses from data sheet +#define PCA9685_MODE1_REG (byte)0x00 +#define PCA9685_MODE2_REG (byte)0x01 +#define PCA9685_SUBADR1_REG (byte)0x02 +#define PCA9685_SUBADR2_REG (byte)0x03 +#define PCA9685_SUBADR3_REG (byte)0x04 +#define PCA9685_ALLCALL_REG (byte)0x05 +#define PCA9685_LED0_REG (byte)0x06 // Start of LEDx regs, 4B per reg, 2B on phase, 2B off phase, little-endian +#define PCA9685_PRESCALE_REG (byte)0xFE +#define PCA9685_ALLLED_REG (byte)0xFA + +// Mode1 register pin layout +#define PCA9685_MODE_RESTART (byte)0x80 +#define PCA9685_MODE_EXTCLK (byte)0x40 +#define PCA9685_MODE_AUTOINC (byte)0x20 +#define PCA9685_MODE_SLEEP (byte)0x10 +#define PCA9685_MODE_SUBADR1 (byte)0x08 +#define PCA9685_MODE_SUBADR2 (byte)0x04 +#define PCA9685_MODE_SUBADR3 (byte)0x02 +#define PCA9685_MODE_ALLCALL (byte)0x01 + +#define PCA9685_SW_RESET (byte)0x06 // Sent to address 0x00 to reset all devices on Wire line +#define PCA9685_PWM_FULL (word)0x01000 // Special value for full on/full off LEDx modes + +// To balance the load out in a weaved fashion, we use this offset table to distribute the +// load on the outputs in a more intelligent fashion than just a simple 4096/16 offset per +// channel. We can set the off cycle value to be lower than the on cycle, which will put +// the high edge across the 0-4095 phase cycle range. +static word phaseDistTable[16] = { 0, 2048, 1024, 3072, 512, 3584, 1536, 2560, 256, 3840, 1280, 2304, 3328, 768, 2816, 1792 }; + +#ifndef PCA9685_USE_SOFTWARE_I2C +PCA9685::PCA9685(TwoWire& wire, PCA9685_PhaseBalancer phaseBalancer) { + _wire = &wire; +#else +PCA9685::PCA9685(PCA9685_PhaseBalancer phaseBalancer) { +#endif + _i2cAddress = 0; + _phaseBalancer = phaseBalancer; + _isProxyAddresser = false; +} + +void PCA9685::resetDevices() { +#ifdef PCA9685_DEBUG_OUTPUT + Serial.println("PCA9685::resetDevices"); +#endif + + wire_beginTransmission(0x00); + wire_write(PCA9685_SW_RESET); + wire_endTransmission(); + + delayMicroseconds(10); +} + +void PCA9685::init(byte i2cAddress, byte mode) { + if (_isProxyAddresser) return; + + // I2C address is B 1 A5 A4 A3 A2 A1 A0 {W=0, R=1} + _i2cAddress = PCA9685_I2C_BASE_ADDRESS | ((i2cAddress & 0x3F) << 1); + +#ifdef PCA9685_DEBUG_OUTPUT + Serial.print("PCA9685::init i2cAddress: 0x"); + Serial.println(_i2cAddress, HEX); +#endif + + writeRegister(PCA9685_MODE1_REG, PCA9685_MODE_RESTART | PCA9685_MODE_AUTOINC); + writeRegister(PCA9685_MODE2_REG, mode); +} + +#ifndef PCA9685_EXCLUDE_EXT_FUNC + +void PCA9685::initAsProxyAddresser(byte i2cAddress) { + _i2cAddress = i2cAddress & 0xFE; + _isProxyAddresser = true; + +#ifdef PCA9685_DEBUG_OUTPUT + Serial.print("PCA9685::initAsProxyAddresser i2cAddress: 0x"); + Serial.println(_i2cAddress, HEX); +#endif +} + +#endif + +void PCA9685::setPWMFrequency(float pwmFrequency) { + if (pwmFrequency < 0 || _isProxyAddresser) return; + + // This equation comes from section 7.3.5 of the datasheet, but the rounding has been + // removed because it isn't needed. Lowest freq is 23.84, highest is 1525.88. + int preScalerVal = (25000000 / (4096 * pwmFrequency)) - 1; + if (preScalerVal > 255) preScalerVal = 255; + if (preScalerVal < 3) preScalerVal = 3; + +#ifdef PCA9685_DEBUG_OUTPUT + Serial.print("PCA9685::setPWMFrequency pwmFrequency: "); + Serial.print(pwmFrequency); + Serial.print(", preScalerVal: 0x"); + Serial.println(preScalerVal, HEX); +#endif + + // The PRE_SCALE register can only be set when the SLEEP bit of MODE1 register is set to logic 1. + byte mode1Val = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Val = (mode1Val & ~PCA9685_MODE_RESTART) | PCA9685_MODE_SLEEP)); + writeRegister(PCA9685_PRESCALE_REG, (byte)preScalerVal); + + // It takes 500us max for the oscillator to be up and running once SLEEP bit has been set to logic 0. + writeRegister(PCA9685_MODE1_REG, (mode1Val = (mode1Val & ~PCA9685_MODE_SLEEP) | PCA9685_MODE_RESTART)); + delayMicroseconds(500); +} + +void PCA9685::setChannelOn(int channel) { + if (channel < 0 || channel > 15) return; + +#ifdef PCA9685_DEBUG_OUTPUT + Serial.println("PCA9685::setChannelOn"); +#endif + + writeChannelBegin(channel); + writeChannelPWM(0, PCA9685_PWM_FULL); + writeChannelEnd(); +} + +void PCA9685::setChannelOff(int channel) { + if (channel < 0 || channel > 15) return; + +#ifdef PCA9685_DEBUG_OUTPUT + Serial.println("PCA9685::setChannelOff"); +#endif + + writeChannelBegin(channel); + writeChannelPWM(PCA9685_PWM_FULL, 0); + writeChannelEnd(); +} + +void PCA9685::setChannelPWM(int channel, word pwmAmount) { + if (channel < 0 || channel > 15) return; + +#ifdef PCA9685_DEBUG_OUTPUT + Serial.println("PCA9685::setChannelPWM"); +#endif + + writeChannelBegin(channel); + + word phaseBegin, phaseEnd; + getPhaseCycle(channel, pwmAmount, &phaseBegin, &phaseEnd); + + writeChannelPWM(phaseBegin, phaseEnd); + + writeChannelEnd(); +} + +void PCA9685::setChannelsPWM(int startChannel, int count, const word *pwmAmounts) { + // In avr/libraries/Wire.h and avr/libraries/utility/twi.h, BUFFER_LENGTH should be increased to + // 64 + 2 at least, since default is 32 so only 7 PWN values can be written in one transaction. + if (startChannel < 0 || startChannel > 15 || count < 0) return; + if (count > 7) count = 7; + if (startChannel + count > 15) count -= (startChannel + count) - 15; + +#ifdef PCA9685_DEBUG_OUTPUT + Serial.print("PCA9685::setChannelsPWM count: "); + Serial.println(count); +#endif + + writeChannelBegin(startChannel); + + for (int i = 0; i < count; i++) { + word phaseBegin, phaseEnd; + getPhaseCycle(startChannel + i, pwmAmounts[i], &phaseBegin, &phaseEnd); + + writeChannelPWM(phaseBegin, phaseEnd); + } + + writeChannelEnd(); +} + +#ifndef PCA9685_EXCLUDE_EXT_FUNC + +void PCA9685::setAllChannelsPWM(word pwmAmount) { +#ifdef PCA9685_DEBUG_OUTPUT + Serial.println("PCA9685::setAllChannelsPWM"); +#endif + + writeChannelBegin(-1); // Special value for ALLLED registers + + word phaseBegin, phaseEnd; + getPhaseCycle(0, pwmAmount, &phaseBegin, &phaseEnd); + + writeChannelPWM(phaseBegin, phaseEnd); + + writeChannelEnd(); +} + +word PCA9685::getChannelPWM(int channel) { + if (channel < 0 || channel > 15 || _isProxyAddresser) return 0; + + byte regAddress = PCA9685_LED0_REG + (channel << 2); + +#ifdef PCA9685_DEBUG_OUTPUT + Serial.print("PCA9685::getChannelPWM channel: "); + Serial.print(channel); + Serial.print(", regAddress: 0x"); + Serial.println(regAddress, HEX); +#endif + + wire_beginTransmission(_i2cAddress); + wire_write(regAddress); + wire_endTransmission(); + + byte retBytes = wire_requestFrom((uint8_t)_i2cAddress, (uint8_t)4); + if (retBytes != 4) { +#ifdef PCA9685_DEBUG_OUTPUT + Serial.println(" PCA9685::getChannelPWM Read request data not available. Aborting."); +#endif + return 0; + } + + word phaseBegin = wire_read(); + phaseBegin |= wire_read() << 8; + word phaseEnd = wire_read(); + phaseEnd |= wire_read() << 8; + +#ifdef PCA9685_DEBUG_OUTPUT + Serial.print(" PCA9685::getChannelPWM phaseBegin: "); + Serial.print(phaseBegin); + Serial.print(", phaseEnd: "); + Serial.println(phaseEnd); +#endif + + word retVal; + if (phaseBegin == PCA9685_PWM_FULL && phaseEnd == 0) + retVal = 0; + else if (phaseBegin == 0 && phaseEnd == PCA9685_PWM_FULL) + retVal = PCA9685_PWM_FULL; + else if (phaseBegin <= phaseEnd) + retVal = phaseEnd - phaseBegin; + else + retVal = (phaseEnd + PCA9685_PWM_FULL) - phaseBegin; + +#ifdef PCA9685_DEBUG_OUTPUT + Serial.print(" PCA9685::getChannelPWM retVal: "); + Serial.println(retVal); +#endif + + return retVal; +} + +void PCA9685::enableAllCallAddress(byte i2cAddress) { + if (_isProxyAddresser) return; + + i2cAddress &= 0xFE; + +#ifdef PCA9685_DEBUG_OUTPUT + Serial.print("PCA9685::enableAllCallAddress i2cAddress: 0x"); + Serial.println(i2cAddress, HEX); +#endif + + writeRegister(PCA9685_ALLCALL_REG, i2cAddress); + + byte mode1Val = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Val |= PCA9685_MODE_ALLCALL)); +} + +void PCA9685::enableSub1Address(byte i2cAddress) { + if (_isProxyAddresser) return; + + i2cAddress &= 0xFE; + +#ifdef PCA9685_DEBUG_OUTPUT + Serial.print("PCA9685::enableSub1Address i2cAddress: 0x"); + Serial.println(i2cAddress, HEX); +#endif + + writeRegister(PCA9685_SUBADR1_REG, i2cAddress); + + byte mode1Val = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Val |= PCA9685_MODE_SUBADR1)); +} + +void PCA9685::enableSub2Address(byte i2cAddress) { + if (_isProxyAddresser) return; + + i2cAddress &= 0xFE; + +#ifdef PCA9685_DEBUG_OUTPUT + Serial.print("PCA9685::enableSub2Address i2cAddress: 0x"); + Serial.println(i2cAddress, HEX); +#endif + + writeRegister(PCA9685_SUBADR2_REG, i2cAddress); + + byte mode1Val = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Val |= PCA9685_MODE_SUBADR2)); +} + +void PCA9685::enableSub3Address(byte i2cAddress) { + if (_isProxyAddresser) return; + + i2cAddress &= 0xFE; + +#ifdef PCA9685_DEBUG_OUTPUT + Serial.print("PCA9685::enableSub3Address i2cAddress: 0x"); + Serial.println(i2cAddress, HEX); +#endif + + writeRegister(PCA9685_SUBADR3_REG, i2cAddress); + + byte mode1Val = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Val |= PCA9685_MODE_SUBADR3)); +} + +void PCA9685::disableAllCallAddress() { + if (_isProxyAddresser) return; + +#ifdef PCA9685_DEBUG_OUTPUT + Serial.println("PCA9685::disableAllCallAddress"); +#endif + + byte mode1Val = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Val &= ~PCA9685_MODE_ALLCALL)); +} + +void PCA9685::disableSub1Address() { + if (_isProxyAddresser) return; + +#ifdef PCA9685_DEBUG_OUTPUT + Serial.println("PCA9685::disableSub1Address"); +#endif + + byte mode1Val = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Val &= ~PCA9685_MODE_SUBADR1)); +} + +void PCA9685::disableSub2Address() { + if (_isProxyAddresser) return; + +#ifdef PCA9685_DEBUG_OUTPUT + Serial.println("PCA9685::disableSub2Address"); +#endif + + byte mode1Val = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Val &= ~PCA9685_MODE_SUBADR2)); +} + +void PCA9685::disableSub3Address() { + if (_isProxyAddresser) return; + +#ifdef PCA9685_DEBUG_OUTPUT + Serial.println("PCA9685::disableSub3Address"); +#endif + + byte mode1Val = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Val &= ~PCA9685_MODE_SUBADR3)); +} + +void PCA9685::enableExtClockLine() { +#ifdef PCA9685_DEBUG_OUTPUT + Serial.println("PCA9685::enableExtClockLine"); +#endif + + // The PRE_SCALE register can only be set when the SLEEP bit of MODE1 register is set to logic 1. + byte mode1Val = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Val = (mode1Val & ~PCA9685_MODE_RESTART) | PCA9685_MODE_SLEEP)); + writeRegister(PCA9685_MODE1_REG, (mode1Val |= PCA9685_MODE_EXTCLK)); + + // It takes 500us max for the oscillator to be up and running once SLEEP bit has been set to logic 0. + writeRegister(PCA9685_MODE1_REG, (mode1Val = (mode1Val & ~PCA9685_MODE_SLEEP) | PCA9685_MODE_RESTART)); + delayMicroseconds(500); +} + +#endif + +void PCA9685::getPhaseCycle(int channel, word pwmAmount, word *phaseBegin, word *phaseEnd) { + if (pwmAmount == 0) { + *phaseBegin = PCA9685_PWM_FULL; + *phaseEnd = 0; + } + else if (pwmAmount >= PCA9685_PWM_FULL - 1) { + *phaseBegin = 0; + *phaseEnd = PCA9685_PWM_FULL; + } + else if (_phaseBalancer == PCA9685_PhaseBalancer_Weaved) { + // Distribute high phase area over entire phase range to balance load. + *phaseBegin = phaseDistTable[channel]; + *phaseEnd = *phaseBegin + pwmAmount; + if (*phaseEnd >= PCA9685_PWM_FULL) + *phaseEnd -= PCA9685_PWM_FULL; + } + else if (_phaseBalancer == PCA9685_PhaseBalancer_Linear) { + // Distribute high phase area over entire phase range to balance load. + *phaseBegin = channel * (4096 / 16); + *phaseEnd = *phaseBegin + pwmAmount; + if (*phaseEnd >= PCA9685_PWM_FULL) + *phaseEnd -= PCA9685_PWM_FULL; } - else if (amount[i]>=PCA9685_CH_ON){ - onval = PCA9685_PWM_FULL; - offval = 0; - } else { - //int randNumber = (int)random(4096); // Randomize the phaseshift to distribute load. Good idea? Hope so. - byte nr = startch+i; - word phase = (4096 / 16) * nr; - onval = phase; - offval = (amount[i]+phase) & 0xFFF; + *phaseBegin = 0; + *phaseEnd = pwmAmount; } - writeChannel(onval, offval); - } - writeEnd(); } -void PCA9685::writeChBegin(int nr) { // LED_ON and LED_OFF are 12bit values (0-4095); ledNumber is 0-15 - byte addr = PCA9685_LED0 + 4*nr; - Wire.beginTransmission(_i2cAddress); - Wire.write(addr); +void PCA9685::writeChannelBegin(int channel) { + byte regAddress; + + if (channel != -1) regAddress = PCA9685_LED0_REG + (channel << 2); + else regAddress = PCA9685_ALLLED_REG; + +#ifdef PCA9685_DEBUG_OUTPUT + Serial.print(" PCA9685::writeChannelBegin channel: "); + Serial.print(channel); + Serial.print(", regAddress: 0x"); + Serial.println(regAddress, HEX); +#endif + + wire_beginTransmission(_i2cAddress); + wire_write(regAddress); +} + +void PCA9685::writeChannelEnd() { + byte retStat = wire_endTransmission(); + +#ifdef PCA9685_DEBUG_OUTPUT + Serial.print(" PCA9685::writeChannelEnd retStat: "); + Serial.println(retStat); +#endif } -void PCA9685::writeEnd() { // LED_ON and LED_OFF are 12bit values (0-4095); ledNumber is 0-15 - Wire.endTransmission(); +void PCA9685::writeChannelPWM(word phaseBegin, word phaseEnd) { +#ifdef PCA9685_DEBUG_OUTPUT + Serial.print(" PCA9685::writeChannelPWM phaseBegin: "); + Serial.print(phaseBegin); + Serial.print(", phaseEnd: "); + Serial.println(phaseEnd); +#endif + + wire_write(lowByte(phaseBegin)); + wire_write(highByte(phaseBegin)); + wire_write(lowByte(phaseEnd)); + wire_write(highByte(phaseEnd)); } -void PCA9685::writeChannel(word LED_ON, word LED_OFF) { // LED_ON and LED_OFF are 12bit values (0-4095); ledNumber is 0-15 - Wire.write(lowByte(LED_ON)); - Wire.write(highByte(LED_ON)); - Wire.write(lowByte(LED_OFF)); - Wire.write(highByte(LED_OFF)); +void PCA9685::writeRegister(byte regAddress, byte value) { +#ifdef PCA9685_DEBUG_OUTPUT + Serial.print(" PCA9685::writeRegister regAddress: 0x"); + Serial.print(regAddress, HEX); + Serial.print(", value: 0x"); + Serial.println(value, HEX); +#endif + + wire_beginTransmission(_i2cAddress); + wire_write(regAddress); + wire_write(value); + byte retStat = wire_endTransmission(); + +#ifdef PCA9685_DEBUG_OUTPUT + Serial.print(" PCA9685::writeRegister retStat: "); + Serial.println(retStat); +#endif } +byte PCA9685::readRegister(byte regAddress) { +#ifdef PCA9685_DEBUG_OUTPUT + Serial.print(" PCA9685::readRegister regAddress: 0x"); + Serial.println(regAddress, HEX); +#endif + + wire_beginTransmission(_i2cAddress); + wire_write(regAddress); + wire_endTransmission(); + + byte retBytes = wire_requestFrom((uint8_t)_i2cAddress, (uint8_t)1); + if (retBytes != 1) { +#ifdef PCA9685_DEBUG_OUTPUT + Serial.println(" PCA9685::readRegister Read request data not available. Aborting."); +#endif + return 0; + } + + byte retVal = wire_read(); + +#ifdef PCA9685_DEBUG_OUTPUT + Serial.print(" PCA9685::readRegister retVal: 0x"); + Serial.println(retVal, HEX); +#endif + + return retVal; +} + +#ifdef PCA9685_USE_SOFTWARE_I2C +bool __attribute__((noinline)) i2c_start(uint8_t addr); +void __attribute__((noinline)) i2c_stop(void) asm("ass_i2c_stop"); +bool __attribute__((noinline)) i2c_write(uint8_t value) asm("ass_i2c_write"); +uint8_t __attribute__((noinline)) i2c_read(bool last); +#endif + +void PCA9685::wire_beginTransmission(uint8_t addr) { +#ifndef PCA9685_USE_SOFTWARE_I2C + _wire->beginTransmission(addr); +#else + i2c_start(addr); +#endif +} + +uint8_t PCA9685::wire_endTransmission(void) { +#ifndef PCA9685_USE_SOFTWARE_I2C + return _wire->endTransmission(); +#else + i2c_stop(); + return 0; +#endif +} + +uint8_t PCA9685::wire_requestFrom(uint8_t addr, uint8_t len) { +#ifndef PCA9685_USE_SOFTWARE_I2C + return _wire->requestFrom(addr, len); +#else + i2c_start(addr | 0x01); + return (_readBytes = len); +#endif +} + +size_t PCA9685::wire_write(uint8_t data) { +#ifndef PCA9685_USE_SOFTWARE_I2C + return _wire->write(data); +#else + return (size_t)i2c_write(data); +#endif +} + +int PCA9685::wire_read(void) { +#ifndef PCA9685_USE_SOFTWARE_I2C + return _wire->read(); +#else + if (_readBytes > 1) + return (int)i2c_read(_readBytes--); + else { + _readBytes = 0; + int retVal = (int)i2c_read(true); + i2c_stop(); + return retVal; + } +#endif +} + + +#ifndef PCA9685_EXCLUDE_SERVO_EVAL + +PCA9685_ServoEvaluator::PCA9685_ServoEvaluator(word n90PWMAmount, word p90PWMAmount) { + n90PWMAmount = constrain(n90PWMAmount, 0, PCA9685_PWM_FULL); + p90PWMAmount = constrain(p90PWMAmount, n90PWMAmount, PCA9685_PWM_FULL); + + _coeff = new float[2]; + _isCSpline = false; + + _coeff[0] = n90PWMAmount; + _coeff[1] = (p90PWMAmount - n90PWMAmount) / 180.0f; +} + +PCA9685_ServoEvaluator::PCA9685_ServoEvaluator(word n90PWMAmount, word zeroPWMAmount, word p90PWMAmount) { + n90PWMAmount = constrain(n90PWMAmount, 0, PCA9685_PWM_FULL); + zeroPWMAmount = constrain(zeroPWMAmount, n90PWMAmount, PCA9685_PWM_FULL); + p90PWMAmount = constrain(p90PWMAmount, zeroPWMAmount, PCA9685_PWM_FULL); + + if (p90PWMAmount - zeroPWMAmount != zeroPWMAmount - n90PWMAmount) { + _coeff = new float[8]; + _isCSpline = true; + + // Cubic spline code adapted from: https://shiftedbits.org/2011/01/30/cubic-spline-interpolation/ + /* "THE BEER-WARE LICENSE" (Revision 42): Devin Lane wrote this [part]. As long as you retain + * this notice you can do whatever you want with this stuff. If we meet some day, and you + * think this stuff is worth it, you can buy me a beer in return. */ + + float x[3] = { 0, 90, 180 }; + float y[3] = { (float)n90PWMAmount, (float)zeroPWMAmount, (float)p90PWMAmount }; + float c[3], b[2], d[2], h[2], l[1], u[2], a[1], z[2]; // n = 3 + + h[0] = x[1] - x[0]; + u[0] = z[0] = 0; + c[2] = 0; + + for (int i = 1; i < 2; ++i) { + h[i] = x[i + 1] - x[i]; + l[i - 1] = (2 * (x[i + 1] - x[i - 1])) - h[i - 1] * u[i - 1]; + u[i] = h[i] / l[i - 1]; + a[i - 1] = (3 / h[i]) * (y[i + 1] - y[i]) - (3 / h[i - 1]) * (y[i] - y[i - 1]); + z[i] = (a[i - 1] - h[i - 1] * z[i - 1]) / l[i - 1]; + } + + for (int i = 1; i >= 0; --i) { + c[i] = z[i] - u[i] * c[i + 1]; + b[i] = (y[i + 1] - y[i]) / h[i] - (h[i] * (c[i + 1] + 2 * c[i])) / 3; + d[i] = (c[i + 1] - c[i]) / (3 * h[i]); + + _coeff[4 * i + 0] = y[i]; // a + _coeff[4 * i + 1] = b[i]; // b + _coeff[4 * i + 2] = c[i]; // c + _coeff[4 * i + 3] = d[i]; // d + } + } + else { + _coeff = new float[2]; + _isCSpline = false; + + _coeff[0] = n90PWMAmount; + _coeff[1] = (p90PWMAmount - n90PWMAmount) / 180.0f; + } +} + +PCA9685_ServoEvaluator::~PCA9685_ServoEvaluator() { + if (_coeff) delete[] _coeff; +} + +word PCA9685_ServoEvaluator::pwmForAngle(float angle) { + float retVal; + angle = constrain(angle + 90, 0, 180); + + if (!_isCSpline) { + retVal = _coeff[0] + (_coeff[1] * angle); + } + else { + if (angle <= 90) { + retVal = _coeff[0] + (_coeff[1] * angle) + (_coeff[2] * angle * angle) + (_coeff[3] * angle * angle * angle); + } + else { + angle -= 90; + retVal = _coeff[4] + (_coeff[5] * angle) + (_coeff[6] * angle * angle) + (_coeff[7] * angle * angle * angle); + } + } + + return (word)constrain((int)roundf(retVal), 0, PCA9685_PWM_FULL); +}; + +#endif diff --git a/PCA9685.h b/PCA9685.h index 60d52da..b06a47b 100644 --- a/PCA9685.h +++ b/PCA9685.h @@ -1,5 +1,5 @@ -/* PCA9685 library for Arduino - Copyright (C) 2012 Kasper SkÃ¥rhøj +/* Arduino Library for the PCA9685 16-Channel PWM Driver Module. + Copyright (C) 2012 Kasper SkÃ¥rhøj This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -13,69 +13,186 @@ You should have received a copy of the GNU General Public License along with this program. If not, see . + + Created by Kasper SkÃ¥rhøj, August 3rd, 2012. + Forked by Vitska, June 18th, 2016. + Forked by NachtRaveVL, July 29th, 2016. + + PCA9685-Arduino - Version 1.2.3 */ + #ifndef PCA9685_H #define PCA9685_H +// Library Setup + +// Uncomment this define if using the software i2c library (min 4MHz+ processor required) +//#define PCA9685_USE_SOFTWARE_I2C 1 // http://playground.arduino.cc/Main/SoftwareI2CLibrary + +// Uncomment this define if wanting to exclude extended functionality from compilation +//#define PCA9685_EXCLUDE_EXT_FUNC 1 + +// Uncomment this define if wanting to exclude ServoEvaluator assistant from compilation +//#define PCA9685_EXCLUDE_SERVO_EVAL 1 + +// Uncomment this define to enable debug output +//#define PCA9685_DEBUG_OUTPUT 1 + +// Servo Control Note +// Many 180 degree controlled digital servos run on a 20ms pulse width (50Hz update +// frequency) based duty cycle, and do not utilize the entire pulse width for their +// -90/+90 degree control. Typically, 2.5% of the 20ms pulse width (0.5ms) is considered +// -90 degrees, and 12.5% of the 20ms pulse width (2.5ms) is considered +90 degrees. This +// roughly translates to raw PCA9685 PWM values of 102 and 512 (out of the 4096 value +// range) for -90 to +90 degree control, but may need to be adjusted to fit your specific +// servo (e.g. some I've tested run ~130 to ~525 for their -90/+90 degree control). Also +// be aware that driving some servos past their -90/+90 degrees of movement can cause a +// little plastic limiter pin to break off and get stuck inside of the gearing, which +// could potentially cause the servo to become jammed. See the PCA9685_ServoEvaluator +// class to assist with calculating PWM values from Servo angle values. + #if defined(ARDUINO) && ARDUINO >= 100 -#include "Arduino.h" +#include #else -#include "WProgram.h" +#include #endif +#ifndef PCA9685_USE_SOFTWARE_I2C +#include +#endif + +#define PCA9685_MODE_INVRT (byte)0x10 // Inverts polarity of channel output signal +#define PCA9685_MODE_OUTPUT_ONACK (byte)0x08 // Channel update happens upon ACK (post-set) rather than on STOP (endTransmission) +#define PCA9685_MODE_OUTPUT_TPOLE (byte)0x04 // Use a totem-pole (push-pull) style output, typical for boards using this chipset +#define PCA9685_MODE_OUTNE_HIGHZ (byte)0x02 // For active low output enable, sets channel output to high-impedance state +#define PCA9685_MODE_OUTNE_LOW (byte)0x01 // Similarly, sets channel output to high if in totem-pole mode, otherwise high-impedance state -#include "Wire.h" - -/** - Version 1.0.0 - (Semantic Versioning) -**/ - -//Register defines from data sheet -#define PCA9685_MODE1 (byte)0x00 // location for Mode1 register address -#define PCA9685_MODE2 (byte)0x01 // location for Mode2 reigster address -#define PCA9685_LED0 (byte)0x06 // location for start of LED0 registers -// The maximum PWM frequency is 1526 Hz if the PRE_SCALE register is set "0x03h". -// The minimum PWM frequency is 24 Hz if the PRE_SCALE register is set "0xFFh". -#define PCA9685_PRE_SCALE (byte)0xfe //prescaler to program the PWM output frequency (default is 200 Hz) -#define PCA9685_ALL_LED (byte)0xFA -#define PCA9685_MAX_CHANNEL 15 -#define PCA9685_MIN_CHANNEL 0 -#define PCA9685_CHANNEL_COUNT 16 -#define PCA9685_ALL_LED_CHANNEL (PCA9685_ALL_LED-PCA9685_LED0) >> 2 - -#define PCA9685_MODE_INVRT 0x10 -#define PCA9685_MODE_OUTPUT_ON_ACK 0x08 -#define PCA9685_MODE_OUTPUT_POLE 0x04 - -#define PCA9685_CH_ON 4096 -#define PCA9685_CH_OFF 0 -#define PCA9685_PWM_FULL 0x1000 - -#define PCA9685_I2C_BASE_ADDRESS 0x40 +#define PCA9685_MIN_CHANNEL 0 +#define PCA9685_MAX_CHANNEL 15 +#define PCA9685_CHANNEL_COUNT 16 + +typedef enum { + PCA9685_PhaseBalancer_None = -1, // Disables phase balancing, all high phase areas start at begining of cycle + PCA9685_PhaseBalancer_Weaved = 0, // Balances first few outputs better, steps away from previous shorten towards last output + PCA9685_PhaseBalancer_Linear, // Balances all outputs linearly, 256 steps away from previous output + PCA9685_PhaseBalancer_Count +} PCA9685_PhaseBalancer; class PCA9685 { - public: - //NB the i2c address here is the value of the A0, A1, A2, A3, A4 and A5 pins ONLY - //as the class takes care of its internal base address. - //so i2cAddress should be between 0 and 63 - PCA9685(){} - void begin(int i2cAddress); - void init(byte mode = PCA9685_MODE_OUTPUT_ON_ACK | PCA9685_MODE_OUTPUT_POLE); - - void on(int nr); - void off(int nr); - // 0: instant OFF(0) - // 4096: instant ON(1) - // 1 - 4095: duty sicle - void setChannel(byte nr, word amount); - void setChannel(byte startch, byte count, const word* amount); - void setPwmFrequency(int hz); - private: - void writeChannel(word outputStart, word outputEnd); - void writeChBegin(int nr); - void writeEnd(); - // Our actual i2c address: - byte _i2cAddress; +public: +#ifndef PCA9685_USE_SOFTWARE_I2C + // May use a different Wire instance than Wire. Some chipsets, such as Due/Zero/etc., + // have a Wire1 class instance that uses the SDA1/SCL1 lines instead. + // Supported baud rates are 100kHz, 400kHz, and 1000kHz. + PCA9685(TwoWire& wire = Wire, PCA9685_PhaseBalancer phaseBalancer = PCA9685_PhaseBalancer_Weaved); +#else + // Minimum supported baud rate is 100kHz, which means minimum supported processor + // speed is 4MHz+ while running i2c standard mode. For 400kHz baud rate, minimum + // supported processor speed is 16MHz+ while running i2c fast mode. + PCA9685(PCA9685_PhaseBalancer phaseBalancer = PCA9685_PhaseBalancer_Weaved); +#endif + + // Should be called only once in setup(), before any init()'s, but after Wire.begin(). + // Only should be called once on any Wire instance to do a software reset, which + // will affect all devices on that line. This helps when you're constantly rebuilding + // and reuploading to ensure all the devices on that line are reset properly. + void resetDevices(); + + // The i2c address here is the value of the A0, A1, A2, A3, A4 and A5 pins ONLY, + // as the class takes care of its internal base address. i2cAddress should be a + // value between 0 and 61, since only 62 boards can be addressed. + void init(byte i2cAddress = 0, byte mode = PCA9685_MODE_OUTPUT_ONACK | PCA9685_MODE_OUTPUT_TPOLE); + +#ifndef PCA9685_EXCLUDE_EXT_FUNC + // Used when instance talks through to AllCall/Sub1-Sub3 instances as a proxy + void initAsProxyAddresser(byte i2cAddress = 0xE0); +#endif + + // Min: 24Hz, Max: 1526Hz, Default: 200Hz (resolution widens as Hz goes higher) + void setPWMFrequency(float pwmFrequency); + + // Turns channel either full on or full off + void setChannelOn(int channel); + void setChannelOff(int channel); + + // PWM amounts 0 - 4096, 0 full off, 4096 full on + void setChannelPWM(int channel, word pwmAmount); + // Max of 7 channels can be batched at once + void setChannelsPWM(int startChannel, int count, const word *pwmAmounts); + +#ifndef PCA9685_EXCLUDE_EXT_FUNC + // Sets all channels, but won't distribute phases + void setAllChannelsPWM(word pwmAmount); + + // Returns PWM amounts 0 - 4096, 0 full off, 4096 full on + word getChannelPWM(int channel); + + // Enables multiple talk-through paths via i2c bus (lsb/bit0 must stay 0) + // To use, create a new class instance using initAsSubAddressed() with said address + void enableAllCallAddress(byte i2cAddress = 0xE0); + void enableSub1Address(byte i2cAddress = 0xE2); + void enableSub2Address(byte i2cAddress = 0xE4); + void enableSub3Address(byte i2cAddress = 0xE8); + void disableAllCallAddress(); + void disableSub1Address(); + void disableSub2Address(); + void disableSub3Address(); + + // Allows external clock line to be utilized (once enabled cannot be disabled) + void enableExtClockLine(); +#endif + +private: +#ifndef PCA9685_USE_SOFTWARE_I2C + TwoWire *_wire; // Wire class instance to use +#endif + byte _i2cAddress; // Module's i2c address + PCA9685_PhaseBalancer _phaseBalancer; // Phase balancer scheme to distribute load + bool _isProxyAddresser; // Instance is a proxy for sub addressing (disables certain functionality) + + void getPhaseCycle(int channel, word pwmAmount, word *phaseBegin, word *phaseEnd); + + void writeChannelBegin(int channel); + void writeChannelEnd(); + void writeChannelPWM(word phaseBegin, word phaseEnd); + + void writeRegister(byte regAddress, byte value); + byte readRegister(byte regAddress); + +#ifdef PCA9685_USE_SOFTWARE_I2C + uint8_t _readBytes; +#endif + void wire_beginTransmission(uint8_t); + uint8_t wire_endTransmission(void); + uint8_t wire_requestFrom(uint8_t, uint8_t); + size_t wire_write(uint8_t); + int wire_read(void); }; + +#ifndef PCA9685_EXCLUDE_SERVO_EVAL + +// Class to assist with calculating Servo PWM values from angle values +class PCA9685_ServoEvaluator { +public: + // Uses a linear interpolation method to quickly compute PWM output value. Uses + // default values of 2.5% and 12.5% of phase length for -90/+90. + PCA9685_ServoEvaluator(word n90PWMAmount = 102, word p90PWMAmount = 512); + + // Uses a cubic spline to interpolate due to an offsetted zero angle that isn't + // exactly between -90/+90. This takes more time to compute, but gives a more + // accurate PWM output value along the entire range. + PCA9685_ServoEvaluator(word n90PWMAmount, word zeroPWMAmount, word p90PWMAmount); + + ~PCA9685_ServoEvaluator(); + + // Returns the PWM value to use given the angle (-90 to +90) + word pwmForAngle(float angle); + +private: + float *_coeff; // a,b,c,d coefficient values + bool _isCSpline; // Cubic spline tracking, for _coeff length +}; + +#endif + #endif diff --git a/README.md b/README.md index 55971a2..115d5df 100644 --- a/README.md +++ b/README.md @@ -1,59 +1,193 @@ -# PCA9685-Arduino-Library -Arduino Library for the PCA9685 LED Driver chip +# PCA9685-Arduino +Arduino Library for the PCA9685 16-Channel PWM Driver Module. -## Example +**PCA9685-Arduino - Version 1.2.3** + +Library to control a PCA9685 16-channel PWM driver module from an Arduino board. +Licensed under the copy-left GNU GPL v3 license. + +Created by Kasper Skårhøj, August 3rd, 2012. +Forked by Vitska, June 18th, 2016. +Forked by NachtRaveVL, July 29th, 2016. + +## Library Setup + +There are several defines inside of the library's header file that allows for more fine-tuned control. + +```Arduino +// Uncomment this define if using the software i2c library (min 4MHz+ processor required) +//#define PCA9685_USE_SOFTWARE_I2C 1 // http://playground.arduino.cc/Main/SoftwareI2CLibrary + +// Uncomment this define if wanting to exclude extended functionality from compilation +//#define PCA9685_EXCLUDE_EXT_FUNC 1 + +// Uncomment this define if wanting to exclude ServoEvaluator assistant from compilation +//#define PCA9685_EXCLUDE_SERVO_EVAL 1 + +// Uncomment this define to enable debug output +//#define PCA9685_DEBUG_OUTPUT 1 +``` + +## Servo Control Note + +Many 180 degree controlled digital servos run on a 20ms pulse width (50Hz update frequency) based duty cycle, and do not utilize the entire pulse width for their -90/+90 degree control. Typically, 2.5% of the 20ms pulse width (0.5ms) is considered -90 degrees, and 12.5% of the 20ms pulse width (2.5ms) is considered +90 degrees. This roughly translates to raw PCA9685 PWM values of 102 and 512 (out of the 4096 value range) for -90 to +90 degree control, but may need to be adjusted to fit your specific servo (e.g. some I've tested run ~130 to ~525 for their -90/+90 degree control). Also be aware that driving some servos past their -90/+90 degrees of movement can cause a little plastic limiter pin to break off and get stuck inside of the gearing, which could potentially cause the servo to become jammed. See the PCA9685_ServoEvaluator class to assist with calculating PWM values from Servo angle values. + +## Example Usage + +Below are several examples of library usage. + +### Simple Example +```Arduino +#include +#include "PCA9685.h" + +PCA9685 pwmDriver; + +void setup() { + Serial.begin(115200); + Wire.begin(); // Wire must be started first + Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz + + pwmDriver.resetDevices(); // Software resets all PCA9685 devices on Wire line + + pwmDriver.init(B000000); // Address pins A5-A0 set to B000000 + pwmDriver.setPWMFrequency(100); // Default is 200Hz, supports 24Hz to 1526Hz + + + pwmDriver.setChannelPWM(0, 128 << 4); // Set PWM to 128/255, but in 4096 land + + Serial.println(pwmDriver.getChannelPWM(0)); // Should output 2048, which is 128 << 4 +} + +``` + +### Batching Example ```Arduino +#include #include "PCA9685.h" -PCA9685 pwmDriver; +PCA9685 pwmDriver; void setup() { - Wire.begin(); // Wire must be started! - Wire.setClock(400000L); - pwmDriver.begin(B000000); // Address pins A5-A0 set to B111000 - pwmDriver.init(); - pwmDriver.setPwmFrequency(1500); + Wire.begin(); // Wire must be started first + Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz + + pwmDriver.resetDevices(); // Software resets all PCA9685 devices on Wire line + + pwmDriver.init(B010101); // Address pins A5-A0 set to B010101 + pwmDriver.setPWMFrequency(500); // Default is 200Hz, supports 24Hz to 1526Hz + + randomSeed(analogRead(0)); // Use white noise for our randomness } void loop() { - word pwms[PCA9685_CHANNEL_COUNT]; - pwms[0] = PCA9685_CH_OFF; - pwms[1] = PCA9685_CH_OFF; - pwms[2] = PCA9685_CH_OFF; - pwms[3] = PCA9685_CH_OFF; - pwms[4] = PCA9685_CH_OFF; - pwms[5] = PCA9685_CH_OFF; - pwms[6] = PCA9685_CH_OFF; - pwms[7] = PCA9685_CH_OFF; - pwms[8] = PCA9685_CH_OFF; - pwms[9] = PCA9685_CH_OFF; - pwms[10] = PCA9685_CH_OFF; - pwms[11] = PCA9685_CH_OFF; - pwms[12] = PCA9685_CH_OFF; - pwms[13] = PCA9685_CH_OFF; - pwms[14] = PCA9685_CH_OFF; - pwms[15] = PCA9685_CH_OFF; - pwmDriver.setChannel(PCA9685_MIN_CHANNEL, PCA9685_CHANNEL_COUNT, pwms); - delay(250); - - pwms[0] = PCA9685_CH_ON; - pwms[1] = PCA9685_CH_ON; - pwms[2] = PCA9685_CH_ON; - pwms[3] = PCA9685_CH_ON; - pwms[4] = PCA9685_CH_ON; - pwms[5] = PCA9685_CH_ON; - pwms[6] = PCA9685_CH_ON; - pwms[7] = PCA9685_CH_ON; - pwms[8] = PCA9685_CH_ON; - pwms[9] = PCA9685_CH_ON; - pwms[10] = PCA9685_CH_ON; - pwms[11] = PCA9685_CH_ON; - pwms[12] = PCA9685_CH_ON; - pwms[13] = PCA9685_CH_ON; - pwms[14] = PCA9685_CH_ON; - pwms[15] = PCA9685_CH_ON; - pwmDriver.setChannel(PCA9685_MIN_CHANNEL, PCA9685_CHANNEL_COUNT, pwms); - delay(250); + // Only 7 channels can be batched at once, due to a BUFFER_LENGTH limit of 32 + word pwms[7]; + pwms[0] = random(0, 4096); + pwms[1] = random(0, 4096); + pwms[2] = random(0, 4096); + pwms[3] = random(0, 4096); + pwms[4] = random(0, 4096); + pwms[5] = random(0, 4096); + pwms[6] = random(0, 4096); + pwmDriver.setChannelsPWM(0, 7, pwms); + delay(500); +} + +``` + +### Multi-Device Proxy Example +```Arduino +#include +#include "PCA9685.h" + +PCA9685 pwmDriver1; +PCA9685 pwmDriver2; + +PCA9685 pwmDriverAll; // Not a real device, will act as a proxy to pwmDriver1 and pwmDriver2 + +void setup() { + Serial.begin(115200); + Wire.begin(); // Wire must be started first + Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz + + pwmDriver1.resetDevices(); // Software resets all PCA9685 devices on Wire line (including pwmDriver2 in this case) + + pwmDriver1.init(B000000); // Address pins A5-A0 set to B000000 + pwmDriver2.init(B000001); // Address pins A5-A0 set to B000001 + + + pwmDriver1.setChannelOff(0); // Turn channel 0 off + pwmDriver2.setChannelOff(0); // On both + + pwmDriver1.enableAllCallAddress(); // Default address of 0xE0 + pwmDriver2.enableAllCallAddress(); // Same default address + + pwmDriverAll.initAsProxyAddresser(); // Same default address of 0x0E as used in enable above + + pwmDriverAll.setChannelPWM(0, 4096); // Enables full on on both pwmDriver1 and pwmDriver2 + + Serial.println(pwmDriver1.getChannelPWM(0)); // Should output 4096 + Serial.println(pwmDriver2.getChannelPWM(0)); // Should also output 4096 + + // Note: Various parts of functionality of the proxy class instance actually + // are disabled, typically anything that involves a read command being issued. +} + +``` + +### Servo Evaluator Example +```Arduino +#include +#include "PCA9685.h" + +PCA9685 pwmDriver; + +// Linearly interpolates between standard 2.5%/12.5% phase length (102/512) for -90°/+90° +PCA9685_ServoEvaluator pwmServo1; + +// Testing our second servo has found that -90° sits at 128, 0° at 324, and +90° at 526. +// Since 324 isn't precisely in the middle, a cubic spline will be used to smoothly +// interpolate PWM values, which will account for said discrepancy. Additionally, since +// 324 is closer to 128 than 526, there is less resolution in the -90° to 0° range, and +// more in the 0° to +90° range. +PCA9685_ServoEvaluator pwmServo2(128,324,526); + +void setup() { + Serial.begin(115200); + Wire.begin(); // Wire must be started first + Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz + + pwmDriver.resetDevices(); // Software resets all PCA9685 devices on Wire line + + pwmDriver.init(B000000); // Address pins A5-A0 set to B000000 + pwmDriver.setPWMFrequency(50); // 50Hz provides 20ms standard servo phase length + + + pwmDriver.setChannelPWM(0, pwmServo1.pwmForAngle(-90)); + Serial.println(pwmDriver.getChannelPWM(0)); // Should output 102 for -90° + + // Showing linearity for midpoint, 205 away from both -90° and 90° + Serial.println(pwmServo1.pwmForAngle(0)); // Should output 307 for 0° + + pwmDriver.setChannelPWM(0, pwmServo1.pwmForAngle(90)); + Serial.println(pwmDriver.getChannelPWM(0)); // Should output 512 for +90° + + + pwmDriver.setChannelPWM(1, pwmServo2.pwmForAngle(-90)); + Serial.println(pwmDriver.getChannelPWM(1)); // Should output 128 for -90° + + // Showing less resolution in the -90° to 0° range + Serial.println(pwmServo2.pwmForAngle(-45)); // Should output 225 for -45°, 97 away from -90° + + pwmDriver.setChannelPWM(1, pwmServo2.pwmForAngle(0)); + Serial.println(pwmDriver.getChannelPWM(1)); // Should output 324 for 0° + + // Showing more resolution in the 0° to +90° range + Serial.println(pwmServo2.pwmForAngle(45)); // Should output 424 for +45°, 102 away from +90° + + pwmDriver.setChannelPWM(1, pwmServo2.pwmForAngle(90)); + Serial.println(pwmDriver.getChannelPWM(1)); // Should output 526 for +90° } ``` diff --git a/Screen Shot 2012-02-18 at 16.55.07.png b/Screen Shot 2012-02-18 at 16.55.07.png deleted file mode 100644 index d7a19e9f835f9a8fa8b5c42e8b87b34631214785..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 12400 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, Vitska, NachtRaveVL +maintainer=NachtRaveVL +sentence=Library to control a PCA9685 16-channel PWM driver module from an Arduino board. +paragraph=This library allows communication with boards running a PCA6985 16-channel PWM driver module. It supports a wide range of available functionality, from setting the output PWM frequecy, allowing multi-device proxy addressing, and provides an assistant class for working with Servos. +category=Device Control +url=https://github.com/NachtRaveVL/PCA9685-Arduino +architectures=* diff --git a/PCA9685 datasheet.pdf b/support files/PCA9685 datasheet.pdf similarity index 100% rename from PCA9685 datasheet.pdf rename to support files/PCA9685 datasheet.pdf From ca834e04305e36b11927152d26c369bea3ac1791 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Wed, 10 Aug 2016 20:52:01 -0700 Subject: [PATCH 02/57] Removing examples. --- examples/BasicLEDTest/BasicLEDTest.ino | 48 ------------------------ examples/Scanning/Scanning.ino | 52 -------------------------- 2 files changed, 100 deletions(-) delete mode 100644 examples/BasicLEDTest/BasicLEDTest.ino delete mode 100644 examples/Scanning/Scanning.ino diff --git a/examples/BasicLEDTest/BasicLEDTest.ino b/examples/BasicLEDTest/BasicLEDTest.ino deleted file mode 100644 index b029e23..0000000 --- a/examples/BasicLEDTest/BasicLEDTest.ino +++ /dev/null @@ -1,48 +0,0 @@ -/***************** - * This example demonstrates the library assuming that LEDs are connected to the outputs - * It will run through all 16 LEDs turning them up and down in 10 steps. - * The PCA9685 chip is assumed to have PINS A0,A1 and A2 grounded (LOW) and A3,A4 and A5 set to VCC (5V, HIGH) - * - * - kasper - */ - -#include -#include - - -PCA9685 ledDriver; - -void setup() -{ - Serial.begin(9600); // set up serial - Serial.println("Serial Started"); - - Wire.begin(); // Wire must be started! - ledDriver.begin(B111000); // Address pins A5-A0 set to B111000 - ledDriver.init(); - - -} - -void loop() -{ - // Notice: setLEDDimmed cannot be used in a loop to give you a pleasant - // "turning-up" of the LED. This is because each time you set a level for a LED - // it will calculate random timing intervals for the PWM function in the chip - // This is done in order to distribute current consumptions of the full time period. - - for(int level=5;level>=0;level--) { - for(int i=0; i<16; i++) { - ledDriver.setLEDDimmed(i,level*20); - delay(100); - } - } - for(int level=0;level<=5;level++) { - for(int i=0; i<16; i++) { - ledDriver.setLEDDimmed(i,level*20); - delay(100); - } - } -} - - diff --git a/examples/Scanning/Scanning.ino b/examples/Scanning/Scanning.ino deleted file mode 100644 index 1cf0b50..0000000 --- a/examples/Scanning/Scanning.ino +++ /dev/null @@ -1,52 +0,0 @@ -/***************** - - - * - kasper - */ - -#include -#include - - -// no-cost stream operator as described at -// http://arduiniana.org/libraries/streaming/ -template -inline Print &operator <<(Print &obj, T arg) -{ - obj.print(arg); - return obj; -} - -PCA9685 ledDriver; - - - -void setup() -{ - Serial.begin(9600); // set up serial - Serial << F("\n- - - - - - - -\nSerial Started\n"); - - Wire.begin(); // Wire must be started! - -} - -void loop() -{ - Serial << "\n"; - - for(uint8_t i=0;i<=63;i++) { - // Set up each board: - ledDriver.begin(i); // Address pins A5-A0 set to B111000 - - if (ledDriver.init()) { - Serial << "\nBoard #" << i << " found\n"; - } else { - Serial << "."; - } - delay(10); - } -} - - - - From 5ae7a5744d8d2a116997f9963dfe1cbf8aadc855 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Sun, 14 Aug 2016 17:18:43 -0700 Subject: [PATCH 03/57] Library standardizations. --- PCA9685.cpp | 78 ++++++++++++++++++++++++++--------------------------- PCA9685.h | 19 +++++++------ 2 files changed, 48 insertions(+), 49 deletions(-) diff --git a/PCA9685.cpp b/PCA9685.cpp index 39a142b..9ab44b1 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -56,8 +56,8 @@ static word phaseDistTable[16] = { 0, 2048, 1024, 3072, 512, 3584, 1536, 2560, 256, 3840, 1280, 2304, 3328, 768, 2816, 1792 }; #ifndef PCA9685_USE_SOFTWARE_I2C -PCA9685::PCA9685(TwoWire& wire, PCA9685_PhaseBalancer phaseBalancer) { - _wire = &wire; +PCA9685::PCA9685(TwoWire& i2cWire, PCA9685_PhaseBalancer phaseBalancer) { + _i2cWire = &i2cWire; #else PCA9685::PCA9685(PCA9685_PhaseBalancer phaseBalancer) { #endif @@ -71,9 +71,9 @@ void PCA9685::resetDevices() { Serial.println("PCA9685::resetDevices"); #endif - wire_beginTransmission(0x00); - wire_write(PCA9685_SW_RESET); - wire_endTransmission(); + i2cWire_beginTransmission(0x00); + i2cWire_write(PCA9685_SW_RESET); + i2cWire_endTransmission(); delayMicroseconds(10); } @@ -227,11 +227,11 @@ word PCA9685::getChannelPWM(int channel) { Serial.println(regAddress, HEX); #endif - wire_beginTransmission(_i2cAddress); - wire_write(regAddress); - wire_endTransmission(); + i2cWire_beginTransmission(_i2cAddress); + i2cWire_write(regAddress); + i2cWire_endTransmission(); - byte retBytes = wire_requestFrom((uint8_t)_i2cAddress, (uint8_t)4); + byte retBytes = i2cWire_requestFrom((uint8_t)_i2cAddress, (uint8_t)4); if (retBytes != 4) { #ifdef PCA9685_DEBUG_OUTPUT Serial.println(" PCA9685::getChannelPWM Read request data not available. Aborting."); @@ -239,10 +239,10 @@ word PCA9685::getChannelPWM(int channel) { return 0; } - word phaseBegin = wire_read(); - phaseBegin |= wire_read() << 8; - word phaseEnd = wire_read(); - phaseEnd |= wire_read() << 8; + word phaseBegin = i2cWire_read(); + phaseBegin |= i2cWire_read() << 8; + word phaseEnd = i2cWire_read(); + phaseEnd |= i2cWire_read() << 8; #ifdef PCA9685_DEBUG_OUTPUT Serial.print(" PCA9685::getChannelPWM phaseBegin: "); @@ -436,12 +436,12 @@ void PCA9685::writeChannelBegin(int channel) { Serial.println(regAddress, HEX); #endif - wire_beginTransmission(_i2cAddress); - wire_write(regAddress); + i2cWire_beginTransmission(_i2cAddress); + i2cWire_write(regAddress); } void PCA9685::writeChannelEnd() { - byte retStat = wire_endTransmission(); + byte retStat = i2cWire_endTransmission(); #ifdef PCA9685_DEBUG_OUTPUT Serial.print(" PCA9685::writeChannelEnd retStat: "); @@ -457,10 +457,10 @@ void PCA9685::writeChannelPWM(word phaseBegin, word phaseEnd) { Serial.println(phaseEnd); #endif - wire_write(lowByte(phaseBegin)); - wire_write(highByte(phaseBegin)); - wire_write(lowByte(phaseEnd)); - wire_write(highByte(phaseEnd)); + i2cWire_write(lowByte(phaseBegin)); + i2cWire_write(highByte(phaseBegin)); + i2cWire_write(lowByte(phaseEnd)); + i2cWire_write(highByte(phaseEnd)); } void PCA9685::writeRegister(byte regAddress, byte value) { @@ -471,10 +471,10 @@ void PCA9685::writeRegister(byte regAddress, byte value) { Serial.println(value, HEX); #endif - wire_beginTransmission(_i2cAddress); - wire_write(regAddress); - wire_write(value); - byte retStat = wire_endTransmission(); + i2cWire_beginTransmission(_i2cAddress); + i2cWire_write(regAddress); + i2cWire_write(value); + byte retStat = i2cWire_endTransmission(); #ifdef PCA9685_DEBUG_OUTPUT Serial.print(" PCA9685::writeRegister retStat: "); @@ -488,11 +488,11 @@ byte PCA9685::readRegister(byte regAddress) { Serial.println(regAddress, HEX); #endif - wire_beginTransmission(_i2cAddress); - wire_write(regAddress); - wire_endTransmission(); + i2cWire_beginTransmission(_i2cAddress); + i2cWire_write(regAddress); + i2cWire_endTransmission(); - byte retBytes = wire_requestFrom((uint8_t)_i2cAddress, (uint8_t)1); + byte retBytes = i2cWire_requestFrom((uint8_t)_i2cAddress, (uint8_t)1); if (retBytes != 1) { #ifdef PCA9685_DEBUG_OUTPUT Serial.println(" PCA9685::readRegister Read request data not available. Aborting."); @@ -500,7 +500,7 @@ byte PCA9685::readRegister(byte regAddress) { return 0; } - byte retVal = wire_read(); + byte retVal = i2cWire_read(); #ifdef PCA9685_DEBUG_OUTPUT Serial.print(" PCA9685::readRegister retVal: 0x"); @@ -517,43 +517,43 @@ bool __attribute__((noinline)) i2c_write(uint8_t value) asm("ass_i2c_write"); uint8_t __attribute__((noinline)) i2c_read(bool last); #endif -void PCA9685::wire_beginTransmission(uint8_t addr) { +void PCA9685::i2cWire_beginTransmission(uint8_t addr) { #ifndef PCA9685_USE_SOFTWARE_I2C - _wire->beginTransmission(addr); + _i2cWire->beginTransmission(addr); #else i2c_start(addr); #endif } -uint8_t PCA9685::wire_endTransmission(void) { +uint8_t PCA9685::i2cWire_endTransmission(void) { #ifndef PCA9685_USE_SOFTWARE_I2C - return _wire->endTransmission(); + return _i2cWire->endTransmission(); #else i2c_stop(); return 0; #endif } -uint8_t PCA9685::wire_requestFrom(uint8_t addr, uint8_t len) { +uint8_t PCA9685::i2cWire_requestFrom(uint8_t addr, uint8_t len) { #ifndef PCA9685_USE_SOFTWARE_I2C - return _wire->requestFrom(addr, len); + return _i2cWire->requestFrom(addr, len); #else i2c_start(addr | 0x01); return (_readBytes = len); #endif } -size_t PCA9685::wire_write(uint8_t data) { +size_t PCA9685::i2cWire_write(uint8_t data) { #ifndef PCA9685_USE_SOFTWARE_I2C - return _wire->write(data); + return _i2cWire->write(data); #else return (size_t)i2c_write(data); #endif } -int PCA9685::wire_read(void) { +int PCA9685::i2cWire_read(void) { #ifndef PCA9685_USE_SOFTWARE_I2C - return _wire->read(); + return _i2cWire->read(); #else if (_readBytes > 1) return (int)i2c_read(_readBytes--); diff --git a/PCA9685.h b/PCA9685.h index b06a47b..cd00d6c 100644 --- a/PCA9685.h +++ b/PCA9685.h @@ -77,14 +77,13 @@ typedef enum { PCA9685_PhaseBalancer_Count } PCA9685_PhaseBalancer; -class PCA9685 -{ +class PCA9685 { public: #ifndef PCA9685_USE_SOFTWARE_I2C // May use a different Wire instance than Wire. Some chipsets, such as Due/Zero/etc., // have a Wire1 class instance that uses the SDA1/SCL1 lines instead. - // Supported baud rates are 100kHz, 400kHz, and 1000kHz. - PCA9685(TwoWire& wire = Wire, PCA9685_PhaseBalancer phaseBalancer = PCA9685_PhaseBalancer_Weaved); + // Supported i2c baud rates are 100kHz, 400kHz, and 1000kHz. + PCA9685(TwoWire& i2cWire = Wire, PCA9685_PhaseBalancer phaseBalancer = PCA9685_PhaseBalancer_Weaved); #else // Minimum supported baud rate is 100kHz, which means minimum supported processor // speed is 4MHz+ while running i2c standard mode. For 400kHz baud rate, minimum @@ -144,7 +143,7 @@ class PCA9685 private: #ifndef PCA9685_USE_SOFTWARE_I2C - TwoWire *_wire; // Wire class instance to use + TwoWire *_i2cWire; // Wire class instance to use #endif byte _i2cAddress; // Module's i2c address PCA9685_PhaseBalancer _phaseBalancer; // Phase balancer scheme to distribute load @@ -162,11 +161,11 @@ class PCA9685 #ifdef PCA9685_USE_SOFTWARE_I2C uint8_t _readBytes; #endif - void wire_beginTransmission(uint8_t); - uint8_t wire_endTransmission(void); - uint8_t wire_requestFrom(uint8_t, uint8_t); - size_t wire_write(uint8_t); - int wire_read(void); + void i2cWire_beginTransmission(uint8_t); + uint8_t i2cWire_endTransmission(void); + uint8_t i2cWire_requestFrom(uint8_t, uint8_t); + size_t i2cWire_write(uint8_t); + int i2cWire_read(void); }; #ifndef PCA9685_EXCLUDE_SERVO_EVAL From 100cb1c62ae95c3280fa7ebdaf2e9450a1b1496a Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Mon, 15 Aug 2016 14:37:25 -0700 Subject: [PATCH 04/57] Standardizing library with explicit lengthed/signed data types. --- PCA9685.cpp | 128 ++++++++++++++++++++++++++-------------------------- PCA9685.h | 64 +++++++++++++------------- 2 files changed, 97 insertions(+), 95 deletions(-) diff --git a/PCA9685.cpp b/PCA9685.cpp index 9ab44b1..6fae4a2 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -23,37 +23,37 @@ #include "PCA9685.h" -#define PCA9685_I2C_BASE_ADDRESS (byte)0x40 +#define PCA9685_I2C_BASE_ADDRESS (uint8_t)0x40 // Register addresses from data sheet -#define PCA9685_MODE1_REG (byte)0x00 -#define PCA9685_MODE2_REG (byte)0x01 -#define PCA9685_SUBADR1_REG (byte)0x02 -#define PCA9685_SUBADR2_REG (byte)0x03 -#define PCA9685_SUBADR3_REG (byte)0x04 -#define PCA9685_ALLCALL_REG (byte)0x05 -#define PCA9685_LED0_REG (byte)0x06 // Start of LEDx regs, 4B per reg, 2B on phase, 2B off phase, little-endian -#define PCA9685_PRESCALE_REG (byte)0xFE -#define PCA9685_ALLLED_REG (byte)0xFA +#define PCA9685_MODE1_REG (uint8_t)0x00 +#define PCA9685_MODE2_REG (uint8_t)0x01 +#define PCA9685_SUBADR1_REG (uint8_t)0x02 +#define PCA9685_SUBADR2_REG (uint8_t)0x03 +#define PCA9685_SUBADR3_REG (uint8_t)0x04 +#define PCA9685_ALLCALL_REG (uint8_t)0x05 +#define PCA9685_LED0_REG (uint8_t)0x06 // Start of LEDx regs, 4B per reg, 2B on phase, 2B off phase, little-endian +#define PCA9685_PRESCALE_REG (uint8_t)0xFE +#define PCA9685_ALLLED_REG (uint8_t)0xFA // Mode1 register pin layout -#define PCA9685_MODE_RESTART (byte)0x80 -#define PCA9685_MODE_EXTCLK (byte)0x40 -#define PCA9685_MODE_AUTOINC (byte)0x20 -#define PCA9685_MODE_SLEEP (byte)0x10 -#define PCA9685_MODE_SUBADR1 (byte)0x08 -#define PCA9685_MODE_SUBADR2 (byte)0x04 -#define PCA9685_MODE_SUBADR3 (byte)0x02 -#define PCA9685_MODE_ALLCALL (byte)0x01 - -#define PCA9685_SW_RESET (byte)0x06 // Sent to address 0x00 to reset all devices on Wire line -#define PCA9685_PWM_FULL (word)0x01000 // Special value for full on/full off LEDx modes +#define PCA9685_MODE_RESTART (uint8_t)0x80 +#define PCA9685_MODE_EXTCLK (uint8_t)0x40 +#define PCA9685_MODE_AUTOINC (uint8_t)0x20 +#define PCA9685_MODE_SLEEP (uint8_t)0x10 +#define PCA9685_MODE_SUBADR1 (uint8_t)0x08 +#define PCA9685_MODE_SUBADR2 (uint8_t)0x04 +#define PCA9685_MODE_SUBADR3 (uint8_t)0x02 +#define PCA9685_MODE_ALLCALL (uint8_t)0x01 + +#define PCA9685_SW_RESET (uint8_t)0x06 // Sent to address 0x00 to reset all devices on Wire line +#define PCA9685_PWM_FULL (uint16_t)0x01000 // Special value for full on/full off LEDx modes // To balance the load out in a weaved fashion, we use this offset table to distribute the // load on the outputs in a more intelligent fashion than just a simple 4096/16 offset per // channel. We can set the off cycle value to be lower than the on cycle, which will put // the high edge across the 0-4095 phase cycle range. -static word phaseDistTable[16] = { 0, 2048, 1024, 3072, 512, 3584, 1536, 2560, 256, 3840, 1280, 2304, 3328, 768, 2816, 1792 }; +static uint16_t phaseDistTable[16] = { 0, 2048, 1024, 3072, 512, 3584, 1536, 2560, 256, 3840, 1280, 2304, 3328, 768, 2816, 1792 }; #ifndef PCA9685_USE_SOFTWARE_I2C PCA9685::PCA9685(TwoWire& i2cWire, PCA9685_PhaseBalancer phaseBalancer) { @@ -78,7 +78,7 @@ void PCA9685::resetDevices() { delayMicroseconds(10); } -void PCA9685::init(byte i2cAddress, byte mode) { +void PCA9685::init(uint8_t i2cAddress, uint8_t mode) { if (_isProxyAddresser) return; // I2C address is B 1 A5 A4 A3 A2 A1 A0 {W=0, R=1} @@ -95,7 +95,7 @@ void PCA9685::init(byte i2cAddress, byte mode) { #ifndef PCA9685_EXCLUDE_EXT_FUNC -void PCA9685::initAsProxyAddresser(byte i2cAddress) { +void PCA9685::initAsProxyAddresser(uint8_t i2cAddress) { _i2cAddress = i2cAddress & 0xFE; _isProxyAddresser = true; @@ -124,9 +124,9 @@ void PCA9685::setPWMFrequency(float pwmFrequency) { #endif // The PRE_SCALE register can only be set when the SLEEP bit of MODE1 register is set to logic 1. - byte mode1Val = readRegister(PCA9685_MODE1_REG); + uint8_t mode1Val = readRegister(PCA9685_MODE1_REG); writeRegister(PCA9685_MODE1_REG, (mode1Val = (mode1Val & ~PCA9685_MODE_RESTART) | PCA9685_MODE_SLEEP)); - writeRegister(PCA9685_PRESCALE_REG, (byte)preScalerVal); + writeRegister(PCA9685_PRESCALE_REG, (uint8_t)preScalerVal); // It takes 500us max for the oscillator to be up and running once SLEEP bit has been set to logic 0. writeRegister(PCA9685_MODE1_REG, (mode1Val = (mode1Val & ~PCA9685_MODE_SLEEP) | PCA9685_MODE_RESTART)); @@ -157,7 +157,7 @@ void PCA9685::setChannelOff(int channel) { writeChannelEnd(); } -void PCA9685::setChannelPWM(int channel, word pwmAmount) { +void PCA9685::setChannelPWM(int channel, uint16_t pwmAmount) { if (channel < 0 || channel > 15) return; #ifdef PCA9685_DEBUG_OUTPUT @@ -166,7 +166,7 @@ void PCA9685::setChannelPWM(int channel, word pwmAmount) { writeChannelBegin(channel); - word phaseBegin, phaseEnd; + uint16_t phaseBegin, phaseEnd; getPhaseCycle(channel, pwmAmount, &phaseBegin, &phaseEnd); writeChannelPWM(phaseBegin, phaseEnd); @@ -174,7 +174,7 @@ void PCA9685::setChannelPWM(int channel, word pwmAmount) { writeChannelEnd(); } -void PCA9685::setChannelsPWM(int startChannel, int count, const word *pwmAmounts) { +void PCA9685::setChannelsPWM(int startChannel, int count, const uint16_t *pwmAmounts) { // In avr/libraries/Wire.h and avr/libraries/utility/twi.h, BUFFER_LENGTH should be increased to // 64 + 2 at least, since default is 32 so only 7 PWN values can be written in one transaction. if (startChannel < 0 || startChannel > 15 || count < 0) return; @@ -189,7 +189,7 @@ void PCA9685::setChannelsPWM(int startChannel, int count, const word *pwmAmounts writeChannelBegin(startChannel); for (int i = 0; i < count; i++) { - word phaseBegin, phaseEnd; + uint16_t phaseBegin, phaseEnd; getPhaseCycle(startChannel + i, pwmAmounts[i], &phaseBegin, &phaseEnd); writeChannelPWM(phaseBegin, phaseEnd); @@ -200,14 +200,14 @@ void PCA9685::setChannelsPWM(int startChannel, int count, const word *pwmAmounts #ifndef PCA9685_EXCLUDE_EXT_FUNC -void PCA9685::setAllChannelsPWM(word pwmAmount) { +void PCA9685::setAllChannelsPWM(uint16_t pwmAmount) { #ifdef PCA9685_DEBUG_OUTPUT Serial.println("PCA9685::setAllChannelsPWM"); #endif writeChannelBegin(-1); // Special value for ALLLED registers - word phaseBegin, phaseEnd; + uint16_t phaseBegin, phaseEnd; getPhaseCycle(0, pwmAmount, &phaseBegin, &phaseEnd); writeChannelPWM(phaseBegin, phaseEnd); @@ -215,10 +215,10 @@ void PCA9685::setAllChannelsPWM(word pwmAmount) { writeChannelEnd(); } -word PCA9685::getChannelPWM(int channel) { +uint16_t PCA9685::getChannelPWM(int channel) { if (channel < 0 || channel > 15 || _isProxyAddresser) return 0; - byte regAddress = PCA9685_LED0_REG + (channel << 2); + uint8_t regAddress = PCA9685_LED0_REG + (channel << 2); #ifdef PCA9685_DEBUG_OUTPUT Serial.print("PCA9685::getChannelPWM channel: "); @@ -231,7 +231,7 @@ word PCA9685::getChannelPWM(int channel) { i2cWire_write(regAddress); i2cWire_endTransmission(); - byte retBytes = i2cWire_requestFrom((uint8_t)_i2cAddress, (uint8_t)4); + uint8_t retBytes = i2cWire_requestFrom((uint8_t)_i2cAddress, (uint8_t)4); if (retBytes != 4) { #ifdef PCA9685_DEBUG_OUTPUT Serial.println(" PCA9685::getChannelPWM Read request data not available. Aborting."); @@ -239,9 +239,9 @@ word PCA9685::getChannelPWM(int channel) { return 0; } - word phaseBegin = i2cWire_read(); + uint16_t phaseBegin = i2cWire_read(); phaseBegin |= i2cWire_read() << 8; - word phaseEnd = i2cWire_read(); + uint16_t phaseEnd = i2cWire_read(); phaseEnd |= i2cWire_read() << 8; #ifdef PCA9685_DEBUG_OUTPUT @@ -251,7 +251,7 @@ word PCA9685::getChannelPWM(int channel) { Serial.println(phaseEnd); #endif - word retVal; + uint16_t retVal; if (phaseBegin == PCA9685_PWM_FULL && phaseEnd == 0) retVal = 0; else if (phaseBegin == 0 && phaseEnd == PCA9685_PWM_FULL) @@ -269,7 +269,7 @@ word PCA9685::getChannelPWM(int channel) { return retVal; } -void PCA9685::enableAllCallAddress(byte i2cAddress) { +void PCA9685::enableAllCallAddress(uint8_t i2cAddress) { if (_isProxyAddresser) return; i2cAddress &= 0xFE; @@ -281,11 +281,11 @@ void PCA9685::enableAllCallAddress(byte i2cAddress) { writeRegister(PCA9685_ALLCALL_REG, i2cAddress); - byte mode1Val = readRegister(PCA9685_MODE1_REG); + uint8_t mode1Val = readRegister(PCA9685_MODE1_REG); writeRegister(PCA9685_MODE1_REG, (mode1Val |= PCA9685_MODE_ALLCALL)); } -void PCA9685::enableSub1Address(byte i2cAddress) { +void PCA9685::enableSub1Address(uint8_t i2cAddress) { if (_isProxyAddresser) return; i2cAddress &= 0xFE; @@ -297,11 +297,11 @@ void PCA9685::enableSub1Address(byte i2cAddress) { writeRegister(PCA9685_SUBADR1_REG, i2cAddress); - byte mode1Val = readRegister(PCA9685_MODE1_REG); + uint8_t mode1Val = readRegister(PCA9685_MODE1_REG); writeRegister(PCA9685_MODE1_REG, (mode1Val |= PCA9685_MODE_SUBADR1)); } -void PCA9685::enableSub2Address(byte i2cAddress) { +void PCA9685::enableSub2Address(uint8_t i2cAddress) { if (_isProxyAddresser) return; i2cAddress &= 0xFE; @@ -313,11 +313,11 @@ void PCA9685::enableSub2Address(byte i2cAddress) { writeRegister(PCA9685_SUBADR2_REG, i2cAddress); - byte mode1Val = readRegister(PCA9685_MODE1_REG); + uint8_t mode1Val = readRegister(PCA9685_MODE1_REG); writeRegister(PCA9685_MODE1_REG, (mode1Val |= PCA9685_MODE_SUBADR2)); } -void PCA9685::enableSub3Address(byte i2cAddress) { +void PCA9685::enableSub3Address(uint8_t i2cAddress) { if (_isProxyAddresser) return; i2cAddress &= 0xFE; @@ -329,7 +329,7 @@ void PCA9685::enableSub3Address(byte i2cAddress) { writeRegister(PCA9685_SUBADR3_REG, i2cAddress); - byte mode1Val = readRegister(PCA9685_MODE1_REG); + uint8_t mode1Val = readRegister(PCA9685_MODE1_REG); writeRegister(PCA9685_MODE1_REG, (mode1Val |= PCA9685_MODE_SUBADR3)); } @@ -340,7 +340,7 @@ void PCA9685::disableAllCallAddress() { Serial.println("PCA9685::disableAllCallAddress"); #endif - byte mode1Val = readRegister(PCA9685_MODE1_REG); + uint8_t mode1Val = readRegister(PCA9685_MODE1_REG); writeRegister(PCA9685_MODE1_REG, (mode1Val &= ~PCA9685_MODE_ALLCALL)); } @@ -351,7 +351,7 @@ void PCA9685::disableSub1Address() { Serial.println("PCA9685::disableSub1Address"); #endif - byte mode1Val = readRegister(PCA9685_MODE1_REG); + uint8_t mode1Val = readRegister(PCA9685_MODE1_REG); writeRegister(PCA9685_MODE1_REG, (mode1Val &= ~PCA9685_MODE_SUBADR1)); } @@ -362,7 +362,7 @@ void PCA9685::disableSub2Address() { Serial.println("PCA9685::disableSub2Address"); #endif - byte mode1Val = readRegister(PCA9685_MODE1_REG); + uint8_t mode1Val = readRegister(PCA9685_MODE1_REG); writeRegister(PCA9685_MODE1_REG, (mode1Val &= ~PCA9685_MODE_SUBADR2)); } @@ -373,7 +373,7 @@ void PCA9685::disableSub3Address() { Serial.println("PCA9685::disableSub3Address"); #endif - byte mode1Val = readRegister(PCA9685_MODE1_REG); + uint8_t mode1Val = readRegister(PCA9685_MODE1_REG); writeRegister(PCA9685_MODE1_REG, (mode1Val &= ~PCA9685_MODE_SUBADR3)); } @@ -383,7 +383,7 @@ void PCA9685::enableExtClockLine() { #endif // The PRE_SCALE register can only be set when the SLEEP bit of MODE1 register is set to logic 1. - byte mode1Val = readRegister(PCA9685_MODE1_REG); + uint8_t mode1Val = readRegister(PCA9685_MODE1_REG); writeRegister(PCA9685_MODE1_REG, (mode1Val = (mode1Val & ~PCA9685_MODE_RESTART) | PCA9685_MODE_SLEEP)); writeRegister(PCA9685_MODE1_REG, (mode1Val |= PCA9685_MODE_EXTCLK)); @@ -394,7 +394,7 @@ void PCA9685::enableExtClockLine() { #endif -void PCA9685::getPhaseCycle(int channel, word pwmAmount, word *phaseBegin, word *phaseEnd) { +void PCA9685::getPhaseCycle(int channel, uint16_t pwmAmount, uint16_t *phaseBegin, uint16_t *phaseEnd) { if (pwmAmount == 0) { *phaseBegin = PCA9685_PWM_FULL; *phaseEnd = 0; @@ -424,7 +424,7 @@ void PCA9685::getPhaseCycle(int channel, word pwmAmount, word *phaseBegin, word } void PCA9685::writeChannelBegin(int channel) { - byte regAddress; + uint8_t regAddress; if (channel != -1) regAddress = PCA9685_LED0_REG + (channel << 2); else regAddress = PCA9685_ALLLED_REG; @@ -441,7 +441,7 @@ void PCA9685::writeChannelBegin(int channel) { } void PCA9685::writeChannelEnd() { - byte retStat = i2cWire_endTransmission(); + uint8_t retStat = i2cWire_endTransmission(); #ifdef PCA9685_DEBUG_OUTPUT Serial.print(" PCA9685::writeChannelEnd retStat: "); @@ -449,7 +449,7 @@ void PCA9685::writeChannelEnd() { #endif } -void PCA9685::writeChannelPWM(word phaseBegin, word phaseEnd) { +void PCA9685::writeChannelPWM(uint16_t phaseBegin, uint16_t phaseEnd) { #ifdef PCA9685_DEBUG_OUTPUT Serial.print(" PCA9685::writeChannelPWM phaseBegin: "); Serial.print(phaseBegin); @@ -463,7 +463,7 @@ void PCA9685::writeChannelPWM(word phaseBegin, word phaseEnd) { i2cWire_write(highByte(phaseEnd)); } -void PCA9685::writeRegister(byte regAddress, byte value) { +void PCA9685::writeRegister(uint8_t regAddress, uint8_t value) { #ifdef PCA9685_DEBUG_OUTPUT Serial.print(" PCA9685::writeRegister regAddress: 0x"); Serial.print(regAddress, HEX); @@ -474,7 +474,7 @@ void PCA9685::writeRegister(byte regAddress, byte value) { i2cWire_beginTransmission(_i2cAddress); i2cWire_write(regAddress); i2cWire_write(value); - byte retStat = i2cWire_endTransmission(); + uint8_t retStat = i2cWire_endTransmission(); #ifdef PCA9685_DEBUG_OUTPUT Serial.print(" PCA9685::writeRegister retStat: "); @@ -482,7 +482,7 @@ void PCA9685::writeRegister(byte regAddress, byte value) { #endif } -byte PCA9685::readRegister(byte regAddress) { +uint8_t PCA9685::readRegister(uint8_t regAddress) { #ifdef PCA9685_DEBUG_OUTPUT Serial.print(" PCA9685::readRegister regAddress: 0x"); Serial.println(regAddress, HEX); @@ -492,7 +492,7 @@ byte PCA9685::readRegister(byte regAddress) { i2cWire_write(regAddress); i2cWire_endTransmission(); - byte retBytes = i2cWire_requestFrom((uint8_t)_i2cAddress, (uint8_t)1); + uint8_t retBytes = i2cWire_requestFrom((uint8_t)_i2cAddress, (uint8_t)1); if (retBytes != 1) { #ifdef PCA9685_DEBUG_OUTPUT Serial.println(" PCA9685::readRegister Read request data not available. Aborting."); @@ -500,7 +500,7 @@ byte PCA9685::readRegister(byte regAddress) { return 0; } - byte retVal = i2cWire_read(); + uint8_t retVal = i2cWire_read(); #ifdef PCA9685_DEBUG_OUTPUT Serial.print(" PCA9685::readRegister retVal: 0x"); @@ -569,7 +569,7 @@ int PCA9685::i2cWire_read(void) { #ifndef PCA9685_EXCLUDE_SERVO_EVAL -PCA9685_ServoEvaluator::PCA9685_ServoEvaluator(word n90PWMAmount, word p90PWMAmount) { +PCA9685_ServoEvaluator::PCA9685_ServoEvaluator(uint16_t n90PWMAmount, uint16_t p90PWMAmount) { n90PWMAmount = constrain(n90PWMAmount, 0, PCA9685_PWM_FULL); p90PWMAmount = constrain(p90PWMAmount, n90PWMAmount, PCA9685_PWM_FULL); @@ -580,7 +580,7 @@ PCA9685_ServoEvaluator::PCA9685_ServoEvaluator(word n90PWMAmount, word p90PWMAmo _coeff[1] = (p90PWMAmount - n90PWMAmount) / 180.0f; } -PCA9685_ServoEvaluator::PCA9685_ServoEvaluator(word n90PWMAmount, word zeroPWMAmount, word p90PWMAmount) { +PCA9685_ServoEvaluator::PCA9685_ServoEvaluator(uint16_t n90PWMAmount, uint16_t zeroPWMAmount, uint16_t p90PWMAmount) { n90PWMAmount = constrain(n90PWMAmount, 0, PCA9685_PWM_FULL); zeroPWMAmount = constrain(zeroPWMAmount, n90PWMAmount, PCA9685_PWM_FULL); p90PWMAmount = constrain(p90PWMAmount, zeroPWMAmount, PCA9685_PWM_FULL); @@ -634,7 +634,7 @@ PCA9685_ServoEvaluator::~PCA9685_ServoEvaluator() { if (_coeff) delete[] _coeff; } -word PCA9685_ServoEvaluator::pwmForAngle(float angle) { +uint16_t PCA9685_ServoEvaluator::pwmForAngle(float angle) { float retVal; angle = constrain(angle + 90, 0, 180); @@ -651,7 +651,7 @@ word PCA9685_ServoEvaluator::pwmForAngle(float angle) { } } - return (word)constrain((int)roundf(retVal), 0, PCA9685_PWM_FULL); + return (uint16_t)constrain((int)roundf(retVal), 0, PCA9685_PWM_FULL); }; #endif diff --git a/PCA9685.h b/PCA9685.h index cd00d6c..d9c6410 100644 --- a/PCA9685.h +++ b/PCA9685.h @@ -60,11 +60,11 @@ #include #endif -#define PCA9685_MODE_INVRT (byte)0x10 // Inverts polarity of channel output signal -#define PCA9685_MODE_OUTPUT_ONACK (byte)0x08 // Channel update happens upon ACK (post-set) rather than on STOP (endTransmission) -#define PCA9685_MODE_OUTPUT_TPOLE (byte)0x04 // Use a totem-pole (push-pull) style output, typical for boards using this chipset -#define PCA9685_MODE_OUTNE_HIGHZ (byte)0x02 // For active low output enable, sets channel output to high-impedance state -#define PCA9685_MODE_OUTNE_LOW (byte)0x01 // Similarly, sets channel output to high if in totem-pole mode, otherwise high-impedance state +#define PCA9685_MODE_INVRT (uint8_t)0x10 // Inverts polarity of channel output signal +#define PCA9685_MODE_OUTPUT_ONACK (uint8_t)0x08 // Channel update happens upon ACK (post-set) rather than on STOP (endTransmission) +#define PCA9685_MODE_OUTPUT_TPOLE (uint8_t)0x04 // Use a totem-pole (push-pull) style output, typical for boards using this chipset +#define PCA9685_MODE_OUTNE_HIGHZ (uint8_t)0x02 // For active low output enable, sets channel output to high-impedance state +#define PCA9685_MODE_OUTNE_LOW (uint8_t)0x01 // Similarly, sets channel output to high if in totem-pole mode, otherwise high-impedance state #define PCA9685_MIN_CHANNEL 0 #define PCA9685_MAX_CHANNEL 15 @@ -85,8 +85,8 @@ class PCA9685 { // Supported i2c baud rates are 100kHz, 400kHz, and 1000kHz. PCA9685(TwoWire& i2cWire = Wire, PCA9685_PhaseBalancer phaseBalancer = PCA9685_PhaseBalancer_Weaved); #else - // Minimum supported baud rate is 100kHz, which means minimum supported processor - // speed is 4MHz+ while running i2c standard mode. For 400kHz baud rate, minimum + // Minimum supported i2c baud rate is 100kHz, which means minimum supported processor + // speed is 4MHz+ while running i2c standard mode. For 400kHz i2c baud rate, minimum // supported processor speed is 16MHz+ while running i2c fast mode. PCA9685(PCA9685_PhaseBalancer phaseBalancer = PCA9685_PhaseBalancer_Weaved); #endif @@ -97,14 +97,16 @@ class PCA9685 { // and reuploading to ensure all the devices on that line are reset properly. void resetDevices(); - // The i2c address here is the value of the A0, A1, A2, A3, A4 and A5 pins ONLY, - // as the class takes care of its internal base address. i2cAddress should be a - // value between 0 and 61, since only 62 boards can be addressed. - void init(byte i2cAddress = 0, byte mode = PCA9685_MODE_OUTPUT_ONACK | PCA9685_MODE_OUTPUT_TPOLE); + // Called in setup(). The i2c address here is the value of the A0, A1, A2, A3, A4 and + // A5 pins ONLY, as the class takes care of its internal base address. i2cAddress + // should be a value between 0 and 61, since only 62 boards can be addressed. + void init(uint8_t i2cAddress = 0, uint8_t mode = PCA9685_MODE_OUTPUT_ONACK | PCA9685_MODE_OUTPUT_TPOLE); #ifndef PCA9685_EXCLUDE_EXT_FUNC - // Used when instance talks through to AllCall/Sub1-Sub3 instances as a proxy - void initAsProxyAddresser(byte i2cAddress = 0xE0); + // Called in setup(). Used when instance talks through to AllCall/Sub1-Sub3 instances + // as a proxy object. Using this method will disable any method that performs a read + // or conflicts certain states. + void initAsProxyAddresser(uint8_t i2cAddress = 0xE0); #endif // Min: 24Hz, Max: 1526Hz, Default: 200Hz (resolution widens as Hz goes higher) @@ -115,23 +117,23 @@ class PCA9685 { void setChannelOff(int channel); // PWM amounts 0 - 4096, 0 full off, 4096 full on - void setChannelPWM(int channel, word pwmAmount); + void setChannelPWM(int channel, uint16_t pwmAmount); // Max of 7 channels can be batched at once - void setChannelsPWM(int startChannel, int count, const word *pwmAmounts); + void setChannelsPWM(int startChannel, int count, const uint16_t *pwmAmounts); #ifndef PCA9685_EXCLUDE_EXT_FUNC // Sets all channels, but won't distribute phases - void setAllChannelsPWM(word pwmAmount); + void setAllChannelsPWM(uint16_t pwmAmount); // Returns PWM amounts 0 - 4096, 0 full off, 4096 full on - word getChannelPWM(int channel); + uint16_t getChannelPWM(int channel); // Enables multiple talk-through paths via i2c bus (lsb/bit0 must stay 0) // To use, create a new class instance using initAsSubAddressed() with said address - void enableAllCallAddress(byte i2cAddress = 0xE0); - void enableSub1Address(byte i2cAddress = 0xE2); - void enableSub2Address(byte i2cAddress = 0xE4); - void enableSub3Address(byte i2cAddress = 0xE8); + void enableAllCallAddress(uint8_t i2cAddress = 0xE0); + void enableSub1Address(uint8_t i2cAddress = 0xE2); + void enableSub2Address(uint8_t i2cAddress = 0xE4); + void enableSub3Address(uint8_t i2cAddress = 0xE8); void disableAllCallAddress(); void disableSub1Address(); void disableSub2Address(); @@ -143,20 +145,20 @@ class PCA9685 { private: #ifndef PCA9685_USE_SOFTWARE_I2C - TwoWire *_i2cWire; // Wire class instance to use + TwoWire *_i2cWire; // Wire class instance to use #endif - byte _i2cAddress; // Module's i2c address + uint8_t _i2cAddress; // Module's i2c address PCA9685_PhaseBalancer _phaseBalancer; // Phase balancer scheme to distribute load - bool _isProxyAddresser; // Instance is a proxy for sub addressing (disables certain functionality) + bool _isProxyAddresser; // Instance is a proxy for sub addressing (disables certain functionality) - void getPhaseCycle(int channel, word pwmAmount, word *phaseBegin, word *phaseEnd); + void getPhaseCycle(int channel, uint16_t pwmAmount, uint16_t *phaseBegin, uint16_t *phaseEnd); void writeChannelBegin(int channel); void writeChannelEnd(); - void writeChannelPWM(word phaseBegin, word phaseEnd); + void writeChannelPWM(uint16_t phaseBegin, uint16_t phaseEnd); - void writeRegister(byte regAddress, byte value); - byte readRegister(byte regAddress); + void writeRegister(uint8_t regAddress, uint8_t value); + uint8_t readRegister(uint8_t regAddress); #ifdef PCA9685_USE_SOFTWARE_I2C uint8_t _readBytes; @@ -175,17 +177,17 @@ class PCA9685_ServoEvaluator { public: // Uses a linear interpolation method to quickly compute PWM output value. Uses // default values of 2.5% and 12.5% of phase length for -90/+90. - PCA9685_ServoEvaluator(word n90PWMAmount = 102, word p90PWMAmount = 512); + PCA9685_ServoEvaluator(uint16_t n90PWMAmount = 102, uint16_t p90PWMAmount = 512); // Uses a cubic spline to interpolate due to an offsetted zero angle that isn't // exactly between -90/+90. This takes more time to compute, but gives a more // accurate PWM output value along the entire range. - PCA9685_ServoEvaluator(word n90PWMAmount, word zeroPWMAmount, word p90PWMAmount); + PCA9685_ServoEvaluator(uint16_t n90PWMAmount, uint16_t zeroPWMAmount, uint16_t p90PWMAmount); ~PCA9685_ServoEvaluator(); // Returns the PWM value to use given the angle (-90 to +90) - word pwmForAngle(float angle); + uint16_t pwmForAngle(float angle); private: float *_coeff; // a,b,c,d coefficient values From 4d25cb5224b3ad871b703097ed75f9e2dc9d4cc4 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Mon, 15 Aug 2016 14:43:58 -0700 Subject: [PATCH 05/57] Standardizing defines. Upping version number. --- PCA9685.cpp | 76 +++++++++++++++++++++++----------------------- PCA9685.h | 20 ++++++------ README.md | 12 ++++---- library.properties | 2 +- 4 files changed, 55 insertions(+), 55 deletions(-) diff --git a/PCA9685.cpp b/PCA9685.cpp index 6fae4a2..bf429ad 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -18,7 +18,7 @@ Forked by Vitska, June 18th, 2016. Forked by NachtRaveVL, July 29th, 2016. - PCA9685-Arduino - Version 1.2.3 + PCA9685-Arduino - Version 1.2.4 */ #include "PCA9685.h" @@ -55,7 +55,7 @@ // the high edge across the 0-4095 phase cycle range. static uint16_t phaseDistTable[16] = { 0, 2048, 1024, 3072, 512, 3584, 1536, 2560, 256, 3840, 1280, 2304, 3328, 768, 2816, 1792 }; -#ifndef PCA9685_USE_SOFTWARE_I2C +#ifndef PCA9685_ENABLE_SOFTWARE_I2C PCA9685::PCA9685(TwoWire& i2cWire, PCA9685_PhaseBalancer phaseBalancer) { _i2cWire = &i2cWire; #else @@ -67,7 +67,7 @@ PCA9685::PCA9685(PCA9685_PhaseBalancer phaseBalancer) { } void PCA9685::resetDevices() { -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.println("PCA9685::resetDevices"); #endif @@ -84,7 +84,7 @@ void PCA9685::init(uint8_t i2cAddress, uint8_t mode) { // I2C address is B 1 A5 A4 A3 A2 A1 A0 {W=0, R=1} _i2cAddress = PCA9685_I2C_BASE_ADDRESS | ((i2cAddress & 0x3F) << 1); -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print("PCA9685::init i2cAddress: 0x"); Serial.println(_i2cAddress, HEX); #endif @@ -99,7 +99,7 @@ void PCA9685::initAsProxyAddresser(uint8_t i2cAddress) { _i2cAddress = i2cAddress & 0xFE; _isProxyAddresser = true; -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print("PCA9685::initAsProxyAddresser i2cAddress: 0x"); Serial.println(_i2cAddress, HEX); #endif @@ -116,7 +116,7 @@ void PCA9685::setPWMFrequency(float pwmFrequency) { if (preScalerVal > 255) preScalerVal = 255; if (preScalerVal < 3) preScalerVal = 3; -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print("PCA9685::setPWMFrequency pwmFrequency: "); Serial.print(pwmFrequency); Serial.print(", preScalerVal: 0x"); @@ -136,7 +136,7 @@ void PCA9685::setPWMFrequency(float pwmFrequency) { void PCA9685::setChannelOn(int channel) { if (channel < 0 || channel > 15) return; -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.println("PCA9685::setChannelOn"); #endif @@ -148,7 +148,7 @@ void PCA9685::setChannelOn(int channel) { void PCA9685::setChannelOff(int channel) { if (channel < 0 || channel > 15) return; -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.println("PCA9685::setChannelOff"); #endif @@ -160,7 +160,7 @@ void PCA9685::setChannelOff(int channel) { void PCA9685::setChannelPWM(int channel, uint16_t pwmAmount) { if (channel < 0 || channel > 15) return; -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.println("PCA9685::setChannelPWM"); #endif @@ -181,7 +181,7 @@ void PCA9685::setChannelsPWM(int startChannel, int count, const uint16_t *pwmAmo if (count > 7) count = 7; if (startChannel + count > 15) count -= (startChannel + count) - 15; -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print("PCA9685::setChannelsPWM count: "); Serial.println(count); #endif @@ -201,7 +201,7 @@ void PCA9685::setChannelsPWM(int startChannel, int count, const uint16_t *pwmAmo #ifndef PCA9685_EXCLUDE_EXT_FUNC void PCA9685::setAllChannelsPWM(uint16_t pwmAmount) { -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.println("PCA9685::setAllChannelsPWM"); #endif @@ -220,7 +220,7 @@ uint16_t PCA9685::getChannelPWM(int channel) { uint8_t regAddress = PCA9685_LED0_REG + (channel << 2); -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print("PCA9685::getChannelPWM channel: "); Serial.print(channel); Serial.print(", regAddress: 0x"); @@ -233,7 +233,7 @@ uint16_t PCA9685::getChannelPWM(int channel) { uint8_t retBytes = i2cWire_requestFrom((uint8_t)_i2cAddress, (uint8_t)4); if (retBytes != 4) { -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.println(" PCA9685::getChannelPWM Read request data not available. Aborting."); #endif return 0; @@ -244,7 +244,7 @@ uint16_t PCA9685::getChannelPWM(int channel) { uint16_t phaseEnd = i2cWire_read(); phaseEnd |= i2cWire_read() << 8; -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print(" PCA9685::getChannelPWM phaseBegin: "); Serial.print(phaseBegin); Serial.print(", phaseEnd: "); @@ -261,7 +261,7 @@ uint16_t PCA9685::getChannelPWM(int channel) { else retVal = (phaseEnd + PCA9685_PWM_FULL) - phaseBegin; -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print(" PCA9685::getChannelPWM retVal: "); Serial.println(retVal); #endif @@ -274,7 +274,7 @@ void PCA9685::enableAllCallAddress(uint8_t i2cAddress) { i2cAddress &= 0xFE; -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print("PCA9685::enableAllCallAddress i2cAddress: 0x"); Serial.println(i2cAddress, HEX); #endif @@ -290,7 +290,7 @@ void PCA9685::enableSub1Address(uint8_t i2cAddress) { i2cAddress &= 0xFE; -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print("PCA9685::enableSub1Address i2cAddress: 0x"); Serial.println(i2cAddress, HEX); #endif @@ -306,7 +306,7 @@ void PCA9685::enableSub2Address(uint8_t i2cAddress) { i2cAddress &= 0xFE; -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print("PCA9685::enableSub2Address i2cAddress: 0x"); Serial.println(i2cAddress, HEX); #endif @@ -322,7 +322,7 @@ void PCA9685::enableSub3Address(uint8_t i2cAddress) { i2cAddress &= 0xFE; -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print("PCA9685::enableSub3Address i2cAddress: 0x"); Serial.println(i2cAddress, HEX); #endif @@ -336,7 +336,7 @@ void PCA9685::enableSub3Address(uint8_t i2cAddress) { void PCA9685::disableAllCallAddress() { if (_isProxyAddresser) return; -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.println("PCA9685::disableAllCallAddress"); #endif @@ -347,7 +347,7 @@ void PCA9685::disableAllCallAddress() { void PCA9685::disableSub1Address() { if (_isProxyAddresser) return; -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.println("PCA9685::disableSub1Address"); #endif @@ -358,7 +358,7 @@ void PCA9685::disableSub1Address() { void PCA9685::disableSub2Address() { if (_isProxyAddresser) return; -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.println("PCA9685::disableSub2Address"); #endif @@ -369,7 +369,7 @@ void PCA9685::disableSub2Address() { void PCA9685::disableSub3Address() { if (_isProxyAddresser) return; -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.println("PCA9685::disableSub3Address"); #endif @@ -378,7 +378,7 @@ void PCA9685::disableSub3Address() { } void PCA9685::enableExtClockLine() { -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.println("PCA9685::enableExtClockLine"); #endif @@ -429,7 +429,7 @@ void PCA9685::writeChannelBegin(int channel) { if (channel != -1) regAddress = PCA9685_LED0_REG + (channel << 2); else regAddress = PCA9685_ALLLED_REG; -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print(" PCA9685::writeChannelBegin channel: "); Serial.print(channel); Serial.print(", regAddress: 0x"); @@ -443,14 +443,14 @@ void PCA9685::writeChannelBegin(int channel) { void PCA9685::writeChannelEnd() { uint8_t retStat = i2cWire_endTransmission(); -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print(" PCA9685::writeChannelEnd retStat: "); Serial.println(retStat); #endif } void PCA9685::writeChannelPWM(uint16_t phaseBegin, uint16_t phaseEnd) { -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print(" PCA9685::writeChannelPWM phaseBegin: "); Serial.print(phaseBegin); Serial.print(", phaseEnd: "); @@ -464,7 +464,7 @@ void PCA9685::writeChannelPWM(uint16_t phaseBegin, uint16_t phaseEnd) { } void PCA9685::writeRegister(uint8_t regAddress, uint8_t value) { -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print(" PCA9685::writeRegister regAddress: 0x"); Serial.print(regAddress, HEX); Serial.print(", value: 0x"); @@ -476,14 +476,14 @@ void PCA9685::writeRegister(uint8_t regAddress, uint8_t value) { i2cWire_write(value); uint8_t retStat = i2cWire_endTransmission(); -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print(" PCA9685::writeRegister retStat: "); Serial.println(retStat); #endif } uint8_t PCA9685::readRegister(uint8_t regAddress) { -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print(" PCA9685::readRegister regAddress: 0x"); Serial.println(regAddress, HEX); #endif @@ -494,7 +494,7 @@ uint8_t PCA9685::readRegister(uint8_t regAddress) { uint8_t retBytes = i2cWire_requestFrom((uint8_t)_i2cAddress, (uint8_t)1); if (retBytes != 1) { -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.println(" PCA9685::readRegister Read request data not available. Aborting."); #endif return 0; @@ -502,7 +502,7 @@ uint8_t PCA9685::readRegister(uint8_t regAddress) { uint8_t retVal = i2cWire_read(); -#ifdef PCA9685_DEBUG_OUTPUT +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print(" PCA9685::readRegister retVal: 0x"); Serial.println(retVal, HEX); #endif @@ -510,7 +510,7 @@ uint8_t PCA9685::readRegister(uint8_t regAddress) { return retVal; } -#ifdef PCA9685_USE_SOFTWARE_I2C +#ifdef PCA9685_ENABLE_SOFTWARE_I2C bool __attribute__((noinline)) i2c_start(uint8_t addr); void __attribute__((noinline)) i2c_stop(void) asm("ass_i2c_stop"); bool __attribute__((noinline)) i2c_write(uint8_t value) asm("ass_i2c_write"); @@ -518,7 +518,7 @@ uint8_t __attribute__((noinline)) i2c_read(bool last); #endif void PCA9685::i2cWire_beginTransmission(uint8_t addr) { -#ifndef PCA9685_USE_SOFTWARE_I2C +#ifndef PCA9685_ENABLE_SOFTWARE_I2C _i2cWire->beginTransmission(addr); #else i2c_start(addr); @@ -526,7 +526,7 @@ void PCA9685::i2cWire_beginTransmission(uint8_t addr) { } uint8_t PCA9685::i2cWire_endTransmission(void) { -#ifndef PCA9685_USE_SOFTWARE_I2C +#ifndef PCA9685_ENABLE_SOFTWARE_I2C return _i2cWire->endTransmission(); #else i2c_stop(); @@ -535,7 +535,7 @@ uint8_t PCA9685::i2cWire_endTransmission(void) { } uint8_t PCA9685::i2cWire_requestFrom(uint8_t addr, uint8_t len) { -#ifndef PCA9685_USE_SOFTWARE_I2C +#ifndef PCA9685_ENABLE_SOFTWARE_I2C return _i2cWire->requestFrom(addr, len); #else i2c_start(addr | 0x01); @@ -544,7 +544,7 @@ uint8_t PCA9685::i2cWire_requestFrom(uint8_t addr, uint8_t len) { } size_t PCA9685::i2cWire_write(uint8_t data) { -#ifndef PCA9685_USE_SOFTWARE_I2C +#ifndef PCA9685_ENABLE_SOFTWARE_I2C return _i2cWire->write(data); #else return (size_t)i2c_write(data); @@ -552,7 +552,7 @@ size_t PCA9685::i2cWire_write(uint8_t data) { } int PCA9685::i2cWire_read(void) { -#ifndef PCA9685_USE_SOFTWARE_I2C +#ifndef PCA9685_ENABLE_SOFTWARE_I2C return _i2cWire->read(); #else if (_readBytes > 1) diff --git a/PCA9685.h b/PCA9685.h index d9c6410..c599103 100644 --- a/PCA9685.h +++ b/PCA9685.h @@ -18,7 +18,7 @@ Forked by Vitska, June 18th, 2016. Forked by NachtRaveVL, July 29th, 2016. - PCA9685-Arduino - Version 1.2.3 + PCA9685-Arduino - Version 1.2.4 */ #ifndef PCA9685_H @@ -26,17 +26,17 @@ // Library Setup -// Uncomment this define if using the software i2c library (min 4MHz+ processor required) -//#define PCA9685_USE_SOFTWARE_I2C 1 // http://playground.arduino.cc/Main/SoftwareI2CLibrary +// Uncomment this define to enable use of the software i2c library (min 4MHz+ processor required) +//#define PCA9685_ENABLE_SOFTWARE_I2C 1 // http://playground.arduino.cc/Main/SoftwareI2CLibrary // Uncomment this define if wanting to exclude extended functionality from compilation -//#define PCA9685_EXCLUDE_EXT_FUNC 1 +//#define PCA9685_EXCLUDE_EXT_FUNC 1 // Uncomment this define if wanting to exclude ServoEvaluator assistant from compilation -//#define PCA9685_EXCLUDE_SERVO_EVAL 1 +//#define PCA9685_EXCLUDE_SERVO_EVAL 1 // Uncomment this define to enable debug output -//#define PCA9685_DEBUG_OUTPUT 1 +//#define PCA9685_ENABLE_DEBUG_OUTPUT 1 // Servo Control Note // Many 180 degree controlled digital servos run on a 20ms pulse width (50Hz update @@ -56,7 +56,7 @@ #else #include #endif -#ifndef PCA9685_USE_SOFTWARE_I2C +#ifndef PCA9685_ENABLE_SOFTWARE_I2C #include #endif @@ -79,7 +79,7 @@ typedef enum { class PCA9685 { public: -#ifndef PCA9685_USE_SOFTWARE_I2C +#ifndef PCA9685_ENABLE_SOFTWARE_I2C // May use a different Wire instance than Wire. Some chipsets, such as Due/Zero/etc., // have a Wire1 class instance that uses the SDA1/SCL1 lines instead. // Supported i2c baud rates are 100kHz, 400kHz, and 1000kHz. @@ -144,7 +144,7 @@ class PCA9685 { #endif private: -#ifndef PCA9685_USE_SOFTWARE_I2C +#ifndef PCA9685_ENABLE_SOFTWARE_I2C TwoWire *_i2cWire; // Wire class instance to use #endif uint8_t _i2cAddress; // Module's i2c address @@ -160,7 +160,7 @@ class PCA9685 { void writeRegister(uint8_t regAddress, uint8_t value); uint8_t readRegister(uint8_t regAddress); -#ifdef PCA9685_USE_SOFTWARE_I2C +#ifdef PCA9685_ENABLE_SOFTWARE_I2C uint8_t _readBytes; #endif void i2cWire_beginTransmission(uint8_t); diff --git a/README.md b/README.md index 115d5df..4bde375 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # PCA9685-Arduino Arduino Library for the PCA9685 16-Channel PWM Driver Module. -**PCA9685-Arduino - Version 1.2.3** +**PCA9685-Arduino - Version 1.2.4** Library to control a PCA9685 16-channel PWM driver module from an Arduino board. Licensed under the copy-left GNU GPL v3 license. @@ -15,17 +15,17 @@ Forked by NachtRaveVL, July 29th, 2016. There are several defines inside of the library's header file that allows for more fine-tuned control. ```Arduino -// Uncomment this define if using the software i2c library (min 4MHz+ processor required) -//#define PCA9685_USE_SOFTWARE_I2C 1 // http://playground.arduino.cc/Main/SoftwareI2CLibrary +// Uncomment this define to enable use of the software i2c library (min 4MHz+ processor required) +//#define PCA9685_ENABLE_SOFTWARE_I2C 1 // http://playground.arduino.cc/Main/SoftwareI2CLibrary // Uncomment this define if wanting to exclude extended functionality from compilation -//#define PCA9685_EXCLUDE_EXT_FUNC 1 +//#define PCA9685_EXCLUDE_EXT_FUNC 1 // Uncomment this define if wanting to exclude ServoEvaluator assistant from compilation -//#define PCA9685_EXCLUDE_SERVO_EVAL 1 +//#define PCA9685_EXCLUDE_SERVO_EVAL 1 // Uncomment this define to enable debug output -//#define PCA9685_DEBUG_OUTPUT 1 +//#define PCA9685_ENABLE_DEBUG_OUTPUT 1 ``` ## Servo Control Note diff --git a/library.properties b/library.properties index b9a9f2c..7fcbec6 100644 --- a/library.properties +++ b/library.properties @@ -1,5 +1,5 @@ name=PCA9685 16-Channel PWM Driver Module Library -version=1.2.3 +version=1.2.4 author=Kasper Skårhøj , Vitska, NachtRaveVL maintainer=NachtRaveVL sentence=Library to control a PCA9685 16-channel PWM driver module from an Arduino board. From 54468dbeabc73999da9703205503a011ebcc96c0 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Mon, 15 Aug 2016 15:10:54 -0700 Subject: [PATCH 06/57] Typos. --- PCA9685.h | 8 ++++---- README.md | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/PCA9685.h b/PCA9685.h index c599103..460fdf0 100644 --- a/PCA9685.h +++ b/PCA9685.h @@ -26,16 +26,16 @@ // Library Setup -// Uncomment this define to enable use of the software i2c library (min 4MHz+ processor required) +// Uncomment this define to enable use of the software i2c library (min 4MHz+ processor required). //#define PCA9685_ENABLE_SOFTWARE_I2C 1 // http://playground.arduino.cc/Main/SoftwareI2CLibrary -// Uncomment this define if wanting to exclude extended functionality from compilation +// Uncomment this define if wanting to exclude extended functionality from compilation. //#define PCA9685_EXCLUDE_EXT_FUNC 1 -// Uncomment this define if wanting to exclude ServoEvaluator assistant from compilation +// Uncomment this define if wanting to exclude ServoEvaluator assistant from compilation. //#define PCA9685_EXCLUDE_SERVO_EVAL 1 -// Uncomment this define to enable debug output +// Uncomment this define to enable debug output. //#define PCA9685_ENABLE_DEBUG_OUTPUT 1 // Servo Control Note diff --git a/README.md b/README.md index 4bde375..3152503 100644 --- a/README.md +++ b/README.md @@ -15,16 +15,16 @@ Forked by NachtRaveVL, July 29th, 2016. There are several defines inside of the library's header file that allows for more fine-tuned control. ```Arduino -// Uncomment this define to enable use of the software i2c library (min 4MHz+ processor required) +// Uncomment this define to enable use of the software i2c library (min 4MHz+ processor required). //#define PCA9685_ENABLE_SOFTWARE_I2C 1 // http://playground.arduino.cc/Main/SoftwareI2CLibrary -// Uncomment this define if wanting to exclude extended functionality from compilation +// Uncomment this define if wanting to exclude extended functionality from compilation. //#define PCA9685_EXCLUDE_EXT_FUNC 1 -// Uncomment this define if wanting to exclude ServoEvaluator assistant from compilation +// Uncomment this define if wanting to exclude ServoEvaluator assistant from compilation. //#define PCA9685_EXCLUDE_SERVO_EVAL 1 -// Uncomment this define to enable debug output +// Uncomment this define to enable debug output. //#define PCA9685_ENABLE_DEBUG_OUTPUT 1 ``` From 17ee9013c772f932d07790a37b604ce3791e3cdd Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Mon, 15 Aug 2016 17:06:28 -0700 Subject: [PATCH 07/57] Added getLastI2CError. --- PCA9685.cpp | 36 +++++++++++++++++++++++++++++++----- PCA9685.h | 3 +++ 2 files changed, 34 insertions(+), 5 deletions(-) diff --git a/PCA9685.cpp b/PCA9685.cpp index bf429ad..ebd373c 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -73,9 +73,14 @@ void PCA9685::resetDevices() { i2cWire_beginTransmission(0x00); i2cWire_write(PCA9685_SW_RESET); - i2cWire_endTransmission(); + uint8_t retStat = i2cWire_endTransmission(); delayMicroseconds(10); + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.print(" PCA9685::resetDevices retStat: "); + Serial.println(retStat); +#endif } void PCA9685::init(uint8_t i2cAddress, uint8_t mode) { @@ -229,13 +234,21 @@ uint16_t PCA9685::getChannelPWM(int channel) { i2cWire_beginTransmission(_i2cAddress); i2cWire_write(regAddress); - i2cWire_endTransmission(); + uint8_t retStat = i2cWire_endTransmission(); + + if (retStat != 0) { +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.println(" PCA9685::getChannelPWM Read request did not set register. Aborting."); +#endif + return 0; + } uint8_t retBytes = i2cWire_requestFrom((uint8_t)_i2cAddress, (uint8_t)4); if (retBytes != 4) { #ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.println(" PCA9685::getChannelPWM Read request data not available. Aborting."); #endif + _lastI2CError = 4; return 0; } @@ -394,6 +407,10 @@ void PCA9685::enableExtClockLine() { #endif +int PCA9685::getLastI2CError() { + return _lastI2CError; +} + void PCA9685::getPhaseCycle(int channel, uint16_t pwmAmount, uint16_t *phaseBegin, uint16_t *phaseEnd) { if (pwmAmount == 0) { *phaseBegin = PCA9685_PWM_FULL; @@ -490,13 +507,22 @@ uint8_t PCA9685::readRegister(uint8_t regAddress) { i2cWire_beginTransmission(_i2cAddress); i2cWire_write(regAddress); - i2cWire_endTransmission(); + uint8_t retStat = i2cWire_endTransmission(); + + if (retStat != 0) { +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.println(" PCA9685::readRegister Read request did not set register. Aborting."); +#endif + return 0; + } uint8_t retBytes = i2cWire_requestFrom((uint8_t)_i2cAddress, (uint8_t)1); + if (retBytes != 1) { #ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.println(" PCA9685::readRegister Read request data not available. Aborting."); #endif + _lastI2CError = 4; return 0; } @@ -527,10 +553,10 @@ void PCA9685::i2cWire_beginTransmission(uint8_t addr) { uint8_t PCA9685::i2cWire_endTransmission(void) { #ifndef PCA9685_ENABLE_SOFTWARE_I2C - return _i2cWire->endTransmission(); + return (_lastI2CError = _i2cWire->endTransmission()); #else i2c_stop(); - return 0; + return (_lastI2CError = 0); #endif } diff --git a/PCA9685.h b/PCA9685.h index 460fdf0..8c8edc1 100644 --- a/PCA9685.h +++ b/PCA9685.h @@ -143,6 +143,8 @@ class PCA9685 { void enableExtClockLine(); #endif + int getLastI2CError(); + private: #ifndef PCA9685_ENABLE_SOFTWARE_I2C TwoWire *_i2cWire; // Wire class instance to use @@ -150,6 +152,7 @@ class PCA9685 { uint8_t _i2cAddress; // Module's i2c address PCA9685_PhaseBalancer _phaseBalancer; // Phase balancer scheme to distribute load bool _isProxyAddresser; // Instance is a proxy for sub addressing (disables certain functionality) + int _lastI2CError; // Last i2c error void getPhaseCycle(int channel, uint16_t pwmAmount, uint16_t *phaseBegin, uint16_t *phaseEnd); From 3bcddf6e41adefb39bfd53030ae7835f2bf57740 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Mon, 15 Aug 2016 17:08:29 -0700 Subject: [PATCH 08/57] Typo --- PCA9685.cpp | 2 +- PCA9685.h | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/PCA9685.cpp b/PCA9685.cpp index ebd373c..4725473 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -407,7 +407,7 @@ void PCA9685::enableExtClockLine() { #endif -int PCA9685::getLastI2CError() { +uint8_t PCA9685::getLastI2CError() { return _lastI2CError; } diff --git a/PCA9685.h b/PCA9685.h index 8c8edc1..0b0a74e 100644 --- a/PCA9685.h +++ b/PCA9685.h @@ -143,7 +143,7 @@ class PCA9685 { void enableExtClockLine(); #endif - int getLastI2CError(); + uint8_t getLastI2CError(); private: #ifndef PCA9685_ENABLE_SOFTWARE_I2C @@ -152,7 +152,7 @@ class PCA9685 { uint8_t _i2cAddress; // Module's i2c address PCA9685_PhaseBalancer _phaseBalancer; // Phase balancer scheme to distribute load bool _isProxyAddresser; // Instance is a proxy for sub addressing (disables certain functionality) - int _lastI2CError; // Last i2c error + uint8_t _lastI2CError; // Last i2c error void getPhaseCycle(int channel, uint16_t pwmAmount, uint16_t *phaseBegin, uint16_t *phaseEnd); From 45a2ca6c5b93804db67bbd3c49253fb27c9d2a4c Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Mon, 15 Aug 2016 17:10:31 -0700 Subject: [PATCH 09/57] More standardization. --- PCA9685.cpp | 1 + 1 file changed, 1 insertion(+) diff --git a/PCA9685.cpp b/PCA9685.cpp index 4725473..e812f5d 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -544,6 +544,7 @@ uint8_t __attribute__((noinline)) i2c_read(bool last); #endif void PCA9685::i2cWire_beginTransmission(uint8_t addr) { + _lastI2CError = 0; #ifndef PCA9685_ENABLE_SOFTWARE_I2C _i2cWire->beginTransmission(addr); #else From 37387bb0b18337666fde8c275a5cc4d2ed9d925f Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Mon, 15 Aug 2016 21:48:13 -0700 Subject: [PATCH 10/57] Naming standardizations. --- PCA9685.cpp | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/PCA9685.cpp b/PCA9685.cpp index e812f5d..6c7209d 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -243,8 +243,8 @@ uint16_t PCA9685::getChannelPWM(int channel) { return 0; } - uint8_t retBytes = i2cWire_requestFrom((uint8_t)_i2cAddress, (uint8_t)4); - if (retBytes != 4) { + uint8_t bytesRead = i2cWire_requestFrom((uint8_t)_i2cAddress, (uint8_t)4); + if (bytesRead != 4) { #ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.println(" PCA9685::getChannelPWM Read request data not available. Aborting."); #endif @@ -516,9 +516,8 @@ uint8_t PCA9685::readRegister(uint8_t regAddress) { return 0; } - uint8_t retBytes = i2cWire_requestFrom((uint8_t)_i2cAddress, (uint8_t)1); - - if (retBytes != 1) { + uint8_t bytesRead = i2cWire_requestFrom((uint8_t)_i2cAddress, (uint8_t)1); + if (bytesRead != 1) { #ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.println(" PCA9685::readRegister Read request data not available. Aborting."); #endif @@ -544,7 +543,6 @@ uint8_t __attribute__((noinline)) i2c_read(bool last); #endif void PCA9685::i2cWire_beginTransmission(uint8_t addr) { - _lastI2CError = 0; #ifndef PCA9685_ENABLE_SOFTWARE_I2C _i2cWire->beginTransmission(addr); #else From c05d776b151b62a9f9d74ab619b9a82f43f24084 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Mon, 15 Aug 2016 23:16:53 -0700 Subject: [PATCH 11/57] Library naming/org standardization. --- PCA9685.cpp | 1 + 1 file changed, 1 insertion(+) diff --git a/PCA9685.cpp b/PCA9685.cpp index 6c7209d..96852ec 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -543,6 +543,7 @@ uint8_t __attribute__((noinline)) i2c_read(bool last); #endif void PCA9685::i2cWire_beginTransmission(uint8_t addr) { + _lastI2CError = 0; #ifndef PCA9685_ENABLE_SOFTWARE_I2C _i2cWire->beginTransmission(addr); #else From 8c6f29db69b9521111e823addc08e55e497dde49 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Tue, 16 Aug 2016 16:01:04 -0700 Subject: [PATCH 12/57] Adding explicit initialization. --- PCA9685.cpp | 1 + 1 file changed, 1 insertion(+) diff --git a/PCA9685.cpp b/PCA9685.cpp index 96852ec..68557d0 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -64,6 +64,7 @@ PCA9685::PCA9685(PCA9685_PhaseBalancer phaseBalancer) { _i2cAddress = 0; _phaseBalancer = phaseBalancer; _isProxyAddresser = false; + _lastI2CError = 0; } void PCA9685::resetDevices() { From a75b200a470e336fc0fe87539b2682cc604b7987 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Fri, 19 Aug 2016 01:45:51 -0700 Subject: [PATCH 13/57] Added base accessors. Added printModuleInfo/checkForErrors. Fixed a few minor bugs. Upping version number. --- PCA9685.cpp | 162 ++++++++++++++++++++++++++++++++++++++++----- PCA9685.h | 11 ++- README.md | 2 +- library.properties | 2 +- 4 files changed, 156 insertions(+), 21 deletions(-) diff --git a/PCA9685.cpp b/PCA9685.cpp index 68557d0..aa1c026 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -18,7 +18,7 @@ Forked by Vitska, June 18th, 2016. Forked by NachtRaveVL, July 29th, 2016. - PCA9685-Arduino - Version 1.2.4 + PCA9685-Arduino - Version 1.2.5 */ #include "PCA9685.h" @@ -74,13 +74,12 @@ void PCA9685::resetDevices() { i2cWire_beginTransmission(0x00); i2cWire_write(PCA9685_SW_RESET); - uint8_t retStat = i2cWire_endTransmission(); + i2cWire_endTransmission(); delayMicroseconds(10); #ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.print(" PCA9685::resetDevices retStat: "); - Serial.println(retStat); + checkForErrors(); #endif } @@ -113,6 +112,14 @@ void PCA9685::initAsProxyAddresser(uint8_t i2cAddress) { #endif +uint8_t PCA9685::getI2CAddress() { + return _i2cAddress; +} + +PCA9685_PhaseBalancer PCA9685::getPhaseBalancer() { + return _phaseBalancer; +} + void PCA9685::setPWMFrequency(float pwmFrequency) { if (pwmFrequency < 0 || _isProxyAddresser) return; @@ -235,21 +242,23 @@ uint16_t PCA9685::getChannelPWM(int channel) { i2cWire_beginTransmission(_i2cAddress); i2cWire_write(regAddress); - uint8_t retStat = i2cWire_endTransmission(); - - if (retStat != 0) { + if (i2cWire_endTransmission() != 0) { #ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.println(" PCA9685::getChannelPWM Read request did not set register. Aborting."); + checkForErrors(); #endif return 0; } uint8_t bytesRead = i2cWire_requestFrom((uint8_t)_i2cAddress, (uint8_t)4); if (bytesRead != 4) { + while (bytesRead-- > 0) + i2cWire_read(); + _lastI2CError = 4; #ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.println(" PCA9685::getChannelPWM Read request data not available. Aborting."); + checkForErrors(); #endif - _lastI2CError = 4; return 0; } @@ -412,6 +421,123 @@ uint8_t PCA9685::getLastI2CError() { return _lastI2CError; } +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + +void PCA9685::printModuleInfo() { + Serial.println("\r\n ~~~ PCA9685 Module Info ~~~"); + + Serial.println("\r\ni2c Address:"); + Serial.print("0x"); + Serial.println(_i2cAddress, HEX); + + Serial.println("\r\nPhase Balancer:"); + switch (_phaseBalancer) { + case PCA9685_PhaseBalancer_None: + Serial.println("PCA9685_PhaseBalancer_None"); break; + case PCA9685_PhaseBalancer_Weaved: + Serial.println("PCA9685_PhaseBalancer_Weaved"); break; + case PCA9685_PhaseBalancer_Linear: + Serial.println("PCA9685_PhaseBalancer_Linear"); break; + default: + Serial.println(""); break; + } + + if (!_isProxyAddresser) { + Serial.println("\r\nProxy Addresser:"); + Serial.println("false"); + + Serial.println("\r\nMode1 Register:"); + uint8_t mode1Val = readRegister(PCA9685_MODE1_REG); + Serial.print("0x"); + Serial.print(mode1Val, HEX); + Serial.print(", Bitset:"); + if (mode1Val & PCA9685_MODE_RESTART) + Serial.print(" PCA9685_MODE_RESTART"); + if (mode1Val & PCA9685_MODE_EXTCLK) + Serial.print(" PCA9685_MODE_EXTCLK"); + if (mode1Val & PCA9685_MODE_AUTOINC) + Serial.print(" PCA9685_MODE_AUTOINC"); + if (mode1Val & PCA9685_MODE_SLEEP) + Serial.print(" PCA9685_MODE_SLEEP"); + if (mode1Val & PCA9685_MODE_SUBADR1) + Serial.print(" PCA9685_MODE_SUBADR1"); + if (mode1Val & PCA9685_MODE_SUBADR2) + Serial.print(" PCA9685_MODE_SUBADR2"); + if (mode1Val & PCA9685_MODE_SUBADR3) + Serial.print(" PCA9685_MODE_SUBADR3"); + if (mode1Val & PCA9685_MODE_ALLCALL) + Serial.print(" PCA9685_MODE_ALLCALL"); + Serial.println(""); + + Serial.println("\r\nMode2 Register:"); + uint8_t mode2Val = readRegister(PCA9685_MODE2_REG); + Serial.print("0x"); + Serial.print(mode2Val, HEX); + Serial.print(", Bitset:"); + if (mode2Val & PCA9685_MODE_INVRT) + Serial.print(" PCA9685_MODE_INVRT"); + if (mode2Val & PCA9685_MODE_OUTPUT_ONACK) + Serial.print(" PCA9685_MODE_OUTPUT_ONACK"); + if (mode2Val & PCA9685_MODE_OUTPUT_TPOLE) + Serial.print(" PCA9685_MODE_OUTPUT_TPOLE"); + if (mode2Val & PCA9685_MODE_OUTNE_HIGHZ) + Serial.print(" PCA9685_MODE_OUTNE_HIGHZ"); + if (mode2Val & PCA9685_MODE_OUTNE_LOW) + Serial.print(" PCA9685_MODE_OUTNE_LOW"); + Serial.println(""); + + Serial.println("\r\nSubAddress1 Register:"); + uint8_t subAdr1Val = readRegister(PCA9685_SUBADR1_REG); + Serial.print("0x"); + Serial.println(subAdr1Val, HEX); + + Serial.println("\r\nSubAddress2 Register:"); + uint8_t subAdr2Val = readRegister(PCA9685_SUBADR2_REG); + Serial.print("0x"); + Serial.println(subAdr2Val, HEX); + + Serial.println("\r\nSubAddress3 Register:"); + uint8_t subAdr3Val = readRegister(PCA9685_SUBADR3_REG); + Serial.print("0x"); + Serial.println(subAdr3Val, HEX); + + Serial.println("\r\nAllCall Register:"); + uint8_t allCallVal = readRegister(PCA9685_ALLCALL_REG); + Serial.print("0x"); + Serial.println(allCallVal, HEX); + } + else { + Serial.println("\r\nProxy Addresser:"); + Serial.println("true"); + } +} + +static const char *textForI2CError(uint8_t errorCode) { + switch (errorCode) { + case 0: + return "Success"; + case 1: + return "Data too long to fit in transmit buffer"; + case 2: + return "Received NACK on transmit of address"; + case 3: + return "Received NACK on transmit of data"; + default: + return "Other error"; + } +} + +void PCA9685::checkForErrors() { + if (_lastI2CError) { + Serial.print(" LeptonFLiR::checkErrors lastI2CError: "); + Serial.print(_lastI2CError); + Serial.print(": "); + Serial.println(textForI2CError(getLastI2CError())); + } +} + +#endif + void PCA9685::getPhaseCycle(int channel, uint16_t pwmAmount, uint16_t *phaseBegin, uint16_t *phaseEnd) { if (pwmAmount == 0) { *phaseBegin = PCA9685_PWM_FULL; @@ -459,11 +585,10 @@ void PCA9685::writeChannelBegin(int channel) { } void PCA9685::writeChannelEnd() { - uint8_t retStat = i2cWire_endTransmission(); + i2cWire_endTransmission(); #ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.print(" PCA9685::writeChannelEnd retStat: "); - Serial.println(retStat); + checkForErrors(); #endif } @@ -492,11 +617,10 @@ void PCA9685::writeRegister(uint8_t regAddress, uint8_t value) { i2cWire_beginTransmission(_i2cAddress); i2cWire_write(regAddress); i2cWire_write(value); - uint8_t retStat = i2cWire_endTransmission(); + i2cWire_endTransmission(); #ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.print(" PCA9685::writeRegister retStat: "); - Serial.println(retStat); + checkForErrors(); #endif } @@ -508,21 +632,23 @@ uint8_t PCA9685::readRegister(uint8_t regAddress) { i2cWire_beginTransmission(_i2cAddress); i2cWire_write(regAddress); - uint8_t retStat = i2cWire_endTransmission(); - - if (retStat != 0) { + if (i2cWire_endTransmission() != -0) { #ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.println(" PCA9685::readRegister Read request did not set register. Aborting."); + checkForErrors(); #endif return 0; } uint8_t bytesRead = i2cWire_requestFrom((uint8_t)_i2cAddress, (uint8_t)1); if (bytesRead != 1) { + while (bytesRead-- > 0) + i2cWire_read(); + _lastI2CError = 4; #ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.println(" PCA9685::readRegister Read request data not available. Aborting."); + checkForErrors(); #endif - _lastI2CError = 4; return 0; } diff --git a/PCA9685.h b/PCA9685.h index 0b0a74e..a2ea124 100644 --- a/PCA9685.h +++ b/PCA9685.h @@ -18,7 +18,7 @@ Forked by Vitska, June 18th, 2016. Forked by NachtRaveVL, July 29th, 2016. - PCA9685-Arduino - Version 1.2.4 + PCA9685-Arduino - Version 1.2.5 */ #ifndef PCA9685_H @@ -74,6 +74,7 @@ typedef enum { PCA9685_PhaseBalancer_None = -1, // Disables phase balancing, all high phase areas start at begining of cycle PCA9685_PhaseBalancer_Weaved = 0, // Balances first few outputs better, steps away from previous shorten towards last output PCA9685_PhaseBalancer_Linear, // Balances all outputs linearly, 256 steps away from previous output + PCA9685_PhaseBalancer_Count } PCA9685_PhaseBalancer; @@ -109,6 +110,9 @@ class PCA9685 { void initAsProxyAddresser(uint8_t i2cAddress = 0xE0); #endif + uint8_t getI2CAddress(); + PCA9685_PhaseBalancer getPhaseBalancer(); + // Min: 24Hz, Max: 1526Hz, Default: 200Hz (resolution widens as Hz goes higher) void setPWMFrequency(float pwmFrequency); @@ -145,6 +149,11 @@ class PCA9685 { uint8_t getLastI2CError(); +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + void printModuleInfo(); + void checkForErrors(); +#endif + private: #ifndef PCA9685_ENABLE_SOFTWARE_I2C TwoWire *_i2cWire; // Wire class instance to use diff --git a/README.md b/README.md index 3152503..c07aebc 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # PCA9685-Arduino Arduino Library for the PCA9685 16-Channel PWM Driver Module. -**PCA9685-Arduino - Version 1.2.4** +**PCA9685-Arduino - Version 1.2.5** Library to control a PCA9685 16-channel PWM driver module from an Arduino board. Licensed under the copy-left GNU GPL v3 license. diff --git a/library.properties b/library.properties index 7fcbec6..3cf5bbf 100644 --- a/library.properties +++ b/library.properties @@ -1,5 +1,5 @@ name=PCA9685 16-Channel PWM Driver Module Library -version=1.2.4 +version=1.2.5 author=Kasper Skårhøj , Vitska, NachtRaveVL maintainer=NachtRaveVL sentence=Library to control a PCA9685 16-channel PWM driver module from an Arduino board. From 04592ea46ce629c7b98c0303618b304ffa9a1296 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Fri, 19 Aug 2016 02:49:09 -0700 Subject: [PATCH 14/57] Reorganization. A few typos. --- PCA9685.cpp | 276 ++++++++++++++++++++++++++-------------------------- PCA9685.h | 34 +++---- 2 files changed, 157 insertions(+), 153 deletions(-) diff --git a/PCA9685.cpp b/PCA9685.cpp index aa1c026..fe49079 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -23,30 +23,30 @@ #include "PCA9685.h" -#define PCA9685_I2C_BASE_ADDRESS (uint8_t)0x40 +#define PCA9685_I2C_BASE_ADDRESS (byte)0x40 // Register addresses from data sheet -#define PCA9685_MODE1_REG (uint8_t)0x00 -#define PCA9685_MODE2_REG (uint8_t)0x01 -#define PCA9685_SUBADR1_REG (uint8_t)0x02 -#define PCA9685_SUBADR2_REG (uint8_t)0x03 -#define PCA9685_SUBADR3_REG (uint8_t)0x04 -#define PCA9685_ALLCALL_REG (uint8_t)0x05 -#define PCA9685_LED0_REG (uint8_t)0x06 // Start of LEDx regs, 4B per reg, 2B on phase, 2B off phase, little-endian -#define PCA9685_PRESCALE_REG (uint8_t)0xFE -#define PCA9685_ALLLED_REG (uint8_t)0xFA +#define PCA9685_MODE1_REG (byte)0x00 +#define PCA9685_MODE2_REG (byte)0x01 +#define PCA9685_SUBADR1_REG (byte)0x02 +#define PCA9685_SUBADR2_REG (byte)0x03 +#define PCA9685_SUBADR3_REG (byte)0x04 +#define PCA9685_ALLCALL_REG (byte)0x05 +#define PCA9685_LED0_REG (byte)0x06 // Start of LEDx regs, 4B per reg, 2B on phase, 2B off phase, little-endian +#define PCA9685_PRESCALE_REG (byte)0xFE +#define PCA9685_ALLLED_REG (byte)0xFA // Mode1 register pin layout -#define PCA9685_MODE_RESTART (uint8_t)0x80 -#define PCA9685_MODE_EXTCLK (uint8_t)0x40 -#define PCA9685_MODE_AUTOINC (uint8_t)0x20 -#define PCA9685_MODE_SLEEP (uint8_t)0x10 -#define PCA9685_MODE_SUBADR1 (uint8_t)0x08 -#define PCA9685_MODE_SUBADR2 (uint8_t)0x04 -#define PCA9685_MODE_SUBADR3 (uint8_t)0x02 -#define PCA9685_MODE_ALLCALL (uint8_t)0x01 - -#define PCA9685_SW_RESET (uint8_t)0x06 // Sent to address 0x00 to reset all devices on Wire line +#define PCA9685_MODE_RESTART (byte)0x80 +#define PCA9685_MODE_EXTCLK (byte)0x40 +#define PCA9685_MODE_AUTOINC (byte)0x20 +#define PCA9685_MODE_SLEEP (byte)0x10 +#define PCA9685_MODE_SUBADR1 (byte)0x08 +#define PCA9685_MODE_SUBADR2 (byte)0x04 +#define PCA9685_MODE_SUBADR3 (byte)0x02 +#define PCA9685_MODE_ALLCALL (byte)0x01 + +#define PCA9685_SW_RESET (byte)0x06 // Sent to address 0x00 to reset all devices on Wire line #define PCA9685_PWM_FULL (uint16_t)0x01000 // Special value for full on/full off LEDx modes // To balance the load out in a weaved fashion, we use this offset table to distribute the @@ -83,7 +83,7 @@ void PCA9685::resetDevices() { #endif } -void PCA9685::init(uint8_t i2cAddress, uint8_t mode) { +void PCA9685::init(byte i2cAddress, byte mode) { if (_isProxyAddresser) return; // I2C address is B 1 A5 A4 A3 A2 A1 A0 {W=0, R=1} @@ -100,7 +100,7 @@ void PCA9685::init(uint8_t i2cAddress, uint8_t mode) { #ifndef PCA9685_EXCLUDE_EXT_FUNC -void PCA9685::initAsProxyAddresser(uint8_t i2cAddress) { +void PCA9685::initAsProxyAddresser(byte i2cAddress) { _i2cAddress = i2cAddress & 0xFE; _isProxyAddresser = true; @@ -112,7 +112,7 @@ void PCA9685::initAsProxyAddresser(uint8_t i2cAddress) { #endif -uint8_t PCA9685::getI2CAddress() { +byte PCA9685::getI2CAddress() { return _i2cAddress; } @@ -137,9 +137,9 @@ void PCA9685::setPWMFrequency(float pwmFrequency) { #endif // The PRE_SCALE register can only be set when the SLEEP bit of MODE1 register is set to logic 1. - uint8_t mode1Val = readRegister(PCA9685_MODE1_REG); + byte mode1Val = readRegister(PCA9685_MODE1_REG); writeRegister(PCA9685_MODE1_REG, (mode1Val = (mode1Val & ~PCA9685_MODE_RESTART) | PCA9685_MODE_SLEEP)); - writeRegister(PCA9685_PRESCALE_REG, (uint8_t)preScalerVal); + writeRegister(PCA9685_PRESCALE_REG, (byte)preScalerVal); // It takes 500us max for the oscillator to be up and running once SLEEP bit has been set to logic 0. writeRegister(PCA9685_MODE1_REG, (mode1Val = (mode1Val & ~PCA9685_MODE_SLEEP) | PCA9685_MODE_RESTART)); @@ -231,7 +231,7 @@ void PCA9685::setAllChannelsPWM(uint16_t pwmAmount) { uint16_t PCA9685::getChannelPWM(int channel) { if (channel < 0 || channel > 15 || _isProxyAddresser) return 0; - uint8_t regAddress = PCA9685_LED0_REG + (channel << 2); + byte regAddress = PCA9685_LED0_REG + (channel << 2); #ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print("PCA9685::getChannelPWM channel: "); @@ -250,7 +250,7 @@ uint16_t PCA9685::getChannelPWM(int channel) { return 0; } - uint8_t bytesRead = i2cWire_requestFrom((uint8_t)_i2cAddress, (uint8_t)4); + byte bytesRead = i2cWire_requestFrom((byte)_i2cAddress, (byte)4); if (bytesRead != 4) { while (bytesRead-- > 0) i2cWire_read(); @@ -292,7 +292,7 @@ uint16_t PCA9685::getChannelPWM(int channel) { return retVal; } -void PCA9685::enableAllCallAddress(uint8_t i2cAddress) { +void PCA9685::enableAllCallAddress(byte i2cAddress) { if (_isProxyAddresser) return; i2cAddress &= 0xFE; @@ -304,11 +304,11 @@ void PCA9685::enableAllCallAddress(uint8_t i2cAddress) { writeRegister(PCA9685_ALLCALL_REG, i2cAddress); - uint8_t mode1Val = readRegister(PCA9685_MODE1_REG); + byte mode1Val = readRegister(PCA9685_MODE1_REG); writeRegister(PCA9685_MODE1_REG, (mode1Val |= PCA9685_MODE_ALLCALL)); } -void PCA9685::enableSub1Address(uint8_t i2cAddress) { +void PCA9685::enableSub1Address(byte i2cAddress) { if (_isProxyAddresser) return; i2cAddress &= 0xFE; @@ -320,11 +320,11 @@ void PCA9685::enableSub1Address(uint8_t i2cAddress) { writeRegister(PCA9685_SUBADR1_REG, i2cAddress); - uint8_t mode1Val = readRegister(PCA9685_MODE1_REG); + byte mode1Val = readRegister(PCA9685_MODE1_REG); writeRegister(PCA9685_MODE1_REG, (mode1Val |= PCA9685_MODE_SUBADR1)); } -void PCA9685::enableSub2Address(uint8_t i2cAddress) { +void PCA9685::enableSub2Address(byte i2cAddress) { if (_isProxyAddresser) return; i2cAddress &= 0xFE; @@ -336,11 +336,11 @@ void PCA9685::enableSub2Address(uint8_t i2cAddress) { writeRegister(PCA9685_SUBADR2_REG, i2cAddress); - uint8_t mode1Val = readRegister(PCA9685_MODE1_REG); + byte mode1Val = readRegister(PCA9685_MODE1_REG); writeRegister(PCA9685_MODE1_REG, (mode1Val |= PCA9685_MODE_SUBADR2)); } -void PCA9685::enableSub3Address(uint8_t i2cAddress) { +void PCA9685::enableSub3Address(byte i2cAddress) { if (_isProxyAddresser) return; i2cAddress &= 0xFE; @@ -352,7 +352,7 @@ void PCA9685::enableSub3Address(uint8_t i2cAddress) { writeRegister(PCA9685_SUBADR3_REG, i2cAddress); - uint8_t mode1Val = readRegister(PCA9685_MODE1_REG); + byte mode1Val = readRegister(PCA9685_MODE1_REG); writeRegister(PCA9685_MODE1_REG, (mode1Val |= PCA9685_MODE_SUBADR3)); } @@ -363,7 +363,7 @@ void PCA9685::disableAllCallAddress() { Serial.println("PCA9685::disableAllCallAddress"); #endif - uint8_t mode1Val = readRegister(PCA9685_MODE1_REG); + byte mode1Val = readRegister(PCA9685_MODE1_REG); writeRegister(PCA9685_MODE1_REG, (mode1Val &= ~PCA9685_MODE_ALLCALL)); } @@ -374,7 +374,7 @@ void PCA9685::disableSub1Address() { Serial.println("PCA9685::disableSub1Address"); #endif - uint8_t mode1Val = readRegister(PCA9685_MODE1_REG); + byte mode1Val = readRegister(PCA9685_MODE1_REG); writeRegister(PCA9685_MODE1_REG, (mode1Val &= ~PCA9685_MODE_SUBADR1)); } @@ -385,7 +385,7 @@ void PCA9685::disableSub2Address() { Serial.println("PCA9685::disableSub2Address"); #endif - uint8_t mode1Val = readRegister(PCA9685_MODE1_REG); + byte mode1Val = readRegister(PCA9685_MODE1_REG); writeRegister(PCA9685_MODE1_REG, (mode1Val &= ~PCA9685_MODE_SUBADR2)); } @@ -396,7 +396,7 @@ void PCA9685::disableSub3Address() { Serial.println("PCA9685::disableSub3Address"); #endif - uint8_t mode1Val = readRegister(PCA9685_MODE1_REG); + byte mode1Val = readRegister(PCA9685_MODE1_REG); writeRegister(PCA9685_MODE1_REG, (mode1Val &= ~PCA9685_MODE_SUBADR3)); } @@ -406,7 +406,7 @@ void PCA9685::enableExtClockLine() { #endif // The PRE_SCALE register can only be set when the SLEEP bit of MODE1 register is set to logic 1. - uint8_t mode1Val = readRegister(PCA9685_MODE1_REG); + byte mode1Val = readRegister(PCA9685_MODE1_REG); writeRegister(PCA9685_MODE1_REG, (mode1Val = (mode1Val & ~PCA9685_MODE_RESTART) | PCA9685_MODE_SLEEP)); writeRegister(PCA9685_MODE1_REG, (mode1Val |= PCA9685_MODE_EXTCLK)); @@ -417,102 +417,13 @@ void PCA9685::enableExtClockLine() { #endif -uint8_t PCA9685::getLastI2CError() { +byte PCA9685::getLastI2CError() { return _lastI2CError; } #ifdef PCA9685_ENABLE_DEBUG_OUTPUT -void PCA9685::printModuleInfo() { - Serial.println("\r\n ~~~ PCA9685 Module Info ~~~"); - - Serial.println("\r\ni2c Address:"); - Serial.print("0x"); - Serial.println(_i2cAddress, HEX); - - Serial.println("\r\nPhase Balancer:"); - switch (_phaseBalancer) { - case PCA9685_PhaseBalancer_None: - Serial.println("PCA9685_PhaseBalancer_None"); break; - case PCA9685_PhaseBalancer_Weaved: - Serial.println("PCA9685_PhaseBalancer_Weaved"); break; - case PCA9685_PhaseBalancer_Linear: - Serial.println("PCA9685_PhaseBalancer_Linear"); break; - default: - Serial.println(""); break; - } - - if (!_isProxyAddresser) { - Serial.println("\r\nProxy Addresser:"); - Serial.println("false"); - - Serial.println("\r\nMode1 Register:"); - uint8_t mode1Val = readRegister(PCA9685_MODE1_REG); - Serial.print("0x"); - Serial.print(mode1Val, HEX); - Serial.print(", Bitset:"); - if (mode1Val & PCA9685_MODE_RESTART) - Serial.print(" PCA9685_MODE_RESTART"); - if (mode1Val & PCA9685_MODE_EXTCLK) - Serial.print(" PCA9685_MODE_EXTCLK"); - if (mode1Val & PCA9685_MODE_AUTOINC) - Serial.print(" PCA9685_MODE_AUTOINC"); - if (mode1Val & PCA9685_MODE_SLEEP) - Serial.print(" PCA9685_MODE_SLEEP"); - if (mode1Val & PCA9685_MODE_SUBADR1) - Serial.print(" PCA9685_MODE_SUBADR1"); - if (mode1Val & PCA9685_MODE_SUBADR2) - Serial.print(" PCA9685_MODE_SUBADR2"); - if (mode1Val & PCA9685_MODE_SUBADR3) - Serial.print(" PCA9685_MODE_SUBADR3"); - if (mode1Val & PCA9685_MODE_ALLCALL) - Serial.print(" PCA9685_MODE_ALLCALL"); - Serial.println(""); - - Serial.println("\r\nMode2 Register:"); - uint8_t mode2Val = readRegister(PCA9685_MODE2_REG); - Serial.print("0x"); - Serial.print(mode2Val, HEX); - Serial.print(", Bitset:"); - if (mode2Val & PCA9685_MODE_INVRT) - Serial.print(" PCA9685_MODE_INVRT"); - if (mode2Val & PCA9685_MODE_OUTPUT_ONACK) - Serial.print(" PCA9685_MODE_OUTPUT_ONACK"); - if (mode2Val & PCA9685_MODE_OUTPUT_TPOLE) - Serial.print(" PCA9685_MODE_OUTPUT_TPOLE"); - if (mode2Val & PCA9685_MODE_OUTNE_HIGHZ) - Serial.print(" PCA9685_MODE_OUTNE_HIGHZ"); - if (mode2Val & PCA9685_MODE_OUTNE_LOW) - Serial.print(" PCA9685_MODE_OUTNE_LOW"); - Serial.println(""); - - Serial.println("\r\nSubAddress1 Register:"); - uint8_t subAdr1Val = readRegister(PCA9685_SUBADR1_REG); - Serial.print("0x"); - Serial.println(subAdr1Val, HEX); - - Serial.println("\r\nSubAddress2 Register:"); - uint8_t subAdr2Val = readRegister(PCA9685_SUBADR2_REG); - Serial.print("0x"); - Serial.println(subAdr2Val, HEX); - - Serial.println("\r\nSubAddress3 Register:"); - uint8_t subAdr3Val = readRegister(PCA9685_SUBADR3_REG); - Serial.print("0x"); - Serial.println(subAdr3Val, HEX); - - Serial.println("\r\nAllCall Register:"); - uint8_t allCallVal = readRegister(PCA9685_ALLCALL_REG); - Serial.print("0x"); - Serial.println(allCallVal, HEX); - } - else { - Serial.println("\r\nProxy Addresser:"); - Serial.println("true"); - } -} - -static const char *textForI2CError(uint8_t errorCode) { +static const char *textForI2CError(byte errorCode) { switch (errorCode) { case 0: return "Success"; @@ -568,7 +479,7 @@ void PCA9685::getPhaseCycle(int channel, uint16_t pwmAmount, uint16_t *phaseBegi } void PCA9685::writeChannelBegin(int channel) { - uint8_t regAddress; + byte regAddress; if (channel != -1) regAddress = PCA9685_LED0_REG + (channel << 2); else regAddress = PCA9685_ALLLED_REG; @@ -606,7 +517,7 @@ void PCA9685::writeChannelPWM(uint16_t phaseBegin, uint16_t phaseEnd) { i2cWire_write(highByte(phaseEnd)); } -void PCA9685::writeRegister(uint8_t regAddress, uint8_t value) { +void PCA9685::writeRegister(byte regAddress, byte value) { #ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print(" PCA9685::writeRegister regAddress: 0x"); Serial.print(regAddress, HEX); @@ -624,7 +535,7 @@ void PCA9685::writeRegister(uint8_t regAddress, uint8_t value) { #endif } -uint8_t PCA9685::readRegister(uint8_t regAddress) { +byte PCA9685::readRegister(byte regAddress) { #ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print(" PCA9685::readRegister regAddress: 0x"); Serial.println(regAddress, HEX); @@ -640,7 +551,7 @@ uint8_t PCA9685::readRegister(uint8_t regAddress) { return 0; } - uint8_t bytesRead = i2cWire_requestFrom((uint8_t)_i2cAddress, (uint8_t)1); + byte bytesRead = i2cWire_requestFrom((byte)_i2cAddress, (byte)1); if (bytesRead != 1) { while (bytesRead-- > 0) i2cWire_read(); @@ -652,7 +563,7 @@ uint8_t PCA9685::readRegister(uint8_t regAddress) { return 0; } - uint8_t retVal = i2cWire_read(); + byte retVal = i2cWire_read(); #ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print(" PCA9685::readRegister retVal: 0x"); @@ -719,6 +630,99 @@ int PCA9685::i2cWire_read(void) { #endif } +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + +void PCA9685::printModuleInfo() { + Serial.println("\r\n ~~~ PCA9685 Module Info ~~~"); + + Serial.println("\r\ni2c Address:"); + Serial.print("0x"); + Serial.println(_i2cAddress, HEX); + + Serial.println("\r\nPhase Balancer:"); + switch (_phaseBalancer) { + case PCA9685_PhaseBalancer_None: + Serial.println("PCA9685_PhaseBalancer_None"); break; + case PCA9685_PhaseBalancer_Weaved: + Serial.println("PCA9685_PhaseBalancer_Weaved"); break; + case PCA9685_PhaseBalancer_Linear: + Serial.println("PCA9685_PhaseBalancer_Linear"); break; + default: + Serial.println(""); break; + } + + if (!_isProxyAddresser) { + Serial.println("\r\nProxy Addresser:"); + Serial.println("false"); + + Serial.println("\r\nMode1 Register:"); + byte mode1Val = readRegister(PCA9685_MODE1_REG); + Serial.print("0x"); + Serial.print(mode1Val, HEX); + Serial.print(", Bitset:"); + if (mode1Val & PCA9685_MODE_RESTART) + Serial.print(" PCA9685_MODE_RESTART"); + if (mode1Val & PCA9685_MODE_EXTCLK) + Serial.print(" PCA9685_MODE_EXTCLK"); + if (mode1Val & PCA9685_MODE_AUTOINC) + Serial.print(" PCA9685_MODE_AUTOINC"); + if (mode1Val & PCA9685_MODE_SLEEP) + Serial.print(" PCA9685_MODE_SLEEP"); + if (mode1Val & PCA9685_MODE_SUBADR1) + Serial.print(" PCA9685_MODE_SUBADR1"); + if (mode1Val & PCA9685_MODE_SUBADR2) + Serial.print(" PCA9685_MODE_SUBADR2"); + if (mode1Val & PCA9685_MODE_SUBADR3) + Serial.print(" PCA9685_MODE_SUBADR3"); + if (mode1Val & PCA9685_MODE_ALLCALL) + Serial.print(" PCA9685_MODE_ALLCALL"); + Serial.println(""); + + Serial.println("\r\nMode2 Register:"); + byte mode2Val = readRegister(PCA9685_MODE2_REG); + Serial.print("0x"); + Serial.print(mode2Val, HEX); + Serial.print(", Bitset:"); + if (mode2Val & PCA9685_MODE_INVRT) + Serial.print(" PCA9685_MODE_INVRT"); + if (mode2Val & PCA9685_MODE_OUTPUT_ONACK) + Serial.print(" PCA9685_MODE_OUTPUT_ONACK"); + if (mode2Val & PCA9685_MODE_OUTPUT_TPOLE) + Serial.print(" PCA9685_MODE_OUTPUT_TPOLE"); + if (mode2Val & PCA9685_MODE_OUTNE_HIGHZ) + Serial.print(" PCA9685_MODE_OUTNE_HIGHZ"); + if (mode2Val & PCA9685_MODE_OUTNE_LOW) + Serial.print(" PCA9685_MODE_OUTNE_LOW"); + Serial.println(""); + + Serial.println("\r\nSubAddress1 Register:"); + byte subAdr1Val = readRegister(PCA9685_SUBADR1_REG); + Serial.print("0x"); + Serial.println(subAdr1Val, HEX); + + Serial.println("\r\nSubAddress2 Register:"); + byte subAdr2Val = readRegister(PCA9685_SUBADR2_REG); + Serial.print("0x"); + Serial.println(subAdr2Val, HEX); + + Serial.println("\r\nSubAddress3 Register:"); + byte subAdr3Val = readRegister(PCA9685_SUBADR3_REG); + Serial.print("0x"); + Serial.println(subAdr3Val, HEX); + + Serial.println("\r\nAllCall Register:"); + byte allCallVal = readRegister(PCA9685_ALLCALL_REG); + Serial.print("0x"); + Serial.println(allCallVal, HEX); + } + else { + Serial.println("\r\nProxy Addresser:"); + Serial.println("true"); + } +} + +#endif + #ifndef PCA9685_EXCLUDE_SERVO_EVAL diff --git a/PCA9685.h b/PCA9685.h index a2ea124..b0064f1 100644 --- a/PCA9685.h +++ b/PCA9685.h @@ -60,11 +60,11 @@ #include #endif -#define PCA9685_MODE_INVRT (uint8_t)0x10 // Inverts polarity of channel output signal -#define PCA9685_MODE_OUTPUT_ONACK (uint8_t)0x08 // Channel update happens upon ACK (post-set) rather than on STOP (endTransmission) -#define PCA9685_MODE_OUTPUT_TPOLE (uint8_t)0x04 // Use a totem-pole (push-pull) style output, typical for boards using this chipset -#define PCA9685_MODE_OUTNE_HIGHZ (uint8_t)0x02 // For active low output enable, sets channel output to high-impedance state -#define PCA9685_MODE_OUTNE_LOW (uint8_t)0x01 // Similarly, sets channel output to high if in totem-pole mode, otherwise high-impedance state +#define PCA9685_MODE_INVRT (byte)0x10 // Inverts polarity of channel output signal +#define PCA9685_MODE_OUTPUT_ONACK (byte)0x08 // Channel update happens upon ACK (post-set) rather than on STOP (endTransmission) +#define PCA9685_MODE_OUTPUT_TPOLE (byte)0x04 // Use a totem-pole (push-pull) style output, typical for boards using this chipset +#define PCA9685_MODE_OUTNE_HIGHZ (byte)0x02 // For active low output enable, sets channel output to high-impedance state +#define PCA9685_MODE_OUTNE_LOW (byte)0x01 // Similarly, sets channel output to high if in totem-pole mode, otherwise high-impedance state #define PCA9685_MIN_CHANNEL 0 #define PCA9685_MAX_CHANNEL 15 @@ -101,16 +101,16 @@ class PCA9685 { // Called in setup(). The i2c address here is the value of the A0, A1, A2, A3, A4 and // A5 pins ONLY, as the class takes care of its internal base address. i2cAddress // should be a value between 0 and 61, since only 62 boards can be addressed. - void init(uint8_t i2cAddress = 0, uint8_t mode = PCA9685_MODE_OUTPUT_ONACK | PCA9685_MODE_OUTPUT_TPOLE); + void init(byte i2cAddress = 0, byte mode = PCA9685_MODE_OUTPUT_ONACK | PCA9685_MODE_OUTPUT_TPOLE); #ifndef PCA9685_EXCLUDE_EXT_FUNC // Called in setup(). Used when instance talks through to AllCall/Sub1-Sub3 instances // as a proxy object. Using this method will disable any method that performs a read // or conflicts certain states. - void initAsProxyAddresser(uint8_t i2cAddress = 0xE0); + void initAsProxyAddresser(byte i2cAddress = 0xE0); #endif - uint8_t getI2CAddress(); + byte getI2CAddress(); PCA9685_PhaseBalancer getPhaseBalancer(); // Min: 24Hz, Max: 1526Hz, Default: 200Hz (resolution widens as Hz goes higher) @@ -134,10 +134,10 @@ class PCA9685 { // Enables multiple talk-through paths via i2c bus (lsb/bit0 must stay 0) // To use, create a new class instance using initAsSubAddressed() with said address - void enableAllCallAddress(uint8_t i2cAddress = 0xE0); - void enableSub1Address(uint8_t i2cAddress = 0xE2); - void enableSub2Address(uint8_t i2cAddress = 0xE4); - void enableSub3Address(uint8_t i2cAddress = 0xE8); + void enableAllCallAddress(byte i2cAddress = 0xE0); + void enableSub1Address(byte i2cAddress = 0xE2); + void enableSub2Address(byte i2cAddress = 0xE4); + void enableSub3Address(byte i2cAddress = 0xE8); void disableAllCallAddress(); void disableSub1Address(); void disableSub2Address(); @@ -147,7 +147,7 @@ class PCA9685 { void enableExtClockLine(); #endif - uint8_t getLastI2CError(); + byte getLastI2CError(); #ifdef PCA9685_ENABLE_DEBUG_OUTPUT void printModuleInfo(); @@ -158,10 +158,10 @@ class PCA9685 { #ifndef PCA9685_ENABLE_SOFTWARE_I2C TwoWire *_i2cWire; // Wire class instance to use #endif - uint8_t _i2cAddress; // Module's i2c address + byte _i2cAddress; // Module's i2c address PCA9685_PhaseBalancer _phaseBalancer; // Phase balancer scheme to distribute load bool _isProxyAddresser; // Instance is a proxy for sub addressing (disables certain functionality) - uint8_t _lastI2CError; // Last i2c error + byte _lastI2CError; // Last i2c error void getPhaseCycle(int channel, uint16_t pwmAmount, uint16_t *phaseBegin, uint16_t *phaseEnd); @@ -169,8 +169,8 @@ class PCA9685 { void writeChannelEnd(); void writeChannelPWM(uint16_t phaseBegin, uint16_t phaseEnd); - void writeRegister(uint8_t regAddress, uint8_t value); - uint8_t readRegister(uint8_t regAddress); + void writeRegister(byte regAddress, byte value); + byte readRegister(byte regAddress); #ifdef PCA9685_ENABLE_SOFTWARE_I2C uint8_t _readBytes; From a803dd054eb08a99d27bc4cebe238a46a3e8edf1 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Fri, 19 Aug 2016 21:46:27 -0700 Subject: [PATCH 15/57] Naimg standardizations. Making batch call work on all registers. Upping version number. --- PCA9685.cpp | 197 ++++++++++++++++++++++++--------------------- PCA9685.h | 10 +-- README.md | 15 +++- library.properties | 4 +- 4 files changed, 121 insertions(+), 105 deletions(-) diff --git a/PCA9685.cpp b/PCA9685.cpp index fe49079..006919f 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -1,5 +1,6 @@ /* Arduino Library for the PCA9685 16-Channel PWM Driver Module. - Copyright (C) 2012 Kasper SkÃ¥rhøj + Copyright (c) 2016 NachtRaveVL + Copyright (C) 2012 Kasper SkÃ¥rhøj This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -18,7 +19,7 @@ Forked by Vitska, June 18th, 2016. Forked by NachtRaveVL, July 29th, 2016. - PCA9685-Arduino - Version 1.2.5 + PCA9685-Arduino - Version 1.2.6 */ #include "PCA9685.h" @@ -137,12 +138,12 @@ void PCA9685::setPWMFrequency(float pwmFrequency) { #endif // The PRE_SCALE register can only be set when the SLEEP bit of MODE1 register is set to logic 1. - byte mode1Val = readRegister(PCA9685_MODE1_REG); - writeRegister(PCA9685_MODE1_REG, (mode1Val = (mode1Val & ~PCA9685_MODE_RESTART) | PCA9685_MODE_SLEEP)); + byte mode1Reg = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Reg = (mode1Reg & ~PCA9685_MODE_RESTART) | PCA9685_MODE_SLEEP)); writeRegister(PCA9685_PRESCALE_REG, (byte)preScalerVal); // It takes 500us max for the oscillator to be up and running once SLEEP bit has been set to logic 0. - writeRegister(PCA9685_MODE1_REG, (mode1Val = (mode1Val & ~PCA9685_MODE_SLEEP) | PCA9685_MODE_RESTART)); + writeRegister(PCA9685_MODE1_REG, (mode1Reg = (mode1Reg & ~PCA9685_MODE_SLEEP) | PCA9685_MODE_RESTART)); delayMicroseconds(500); } @@ -187,28 +188,34 @@ void PCA9685::setChannelPWM(int channel, uint16_t pwmAmount) { writeChannelEnd(); } -void PCA9685::setChannelsPWM(int startChannel, int count, const uint16_t *pwmAmounts) { - // In avr/libraries/Wire.h and avr/libraries/utility/twi.h, BUFFER_LENGTH should be increased to - // 64 + 2 at least, since default is 32 so only 7 PWN values can be written in one transaction. - if (startChannel < 0 || startChannel > 15 || count < 0) return; - if (count > 7) count = 7; - if (startChannel + count > 15) count -= (startChannel + count) - 15; +void PCA9685::setChannelsPWM(int begChannel, int numChannels, const uint16_t *pwmAmounts) { + if (begChannel < 0 || begChannel > 15 || numChannels < 0) return; + if (begChannel + numChannels > 15) numChannels -= (begChannel + numChannels) - 15; #ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.print("PCA9685::setChannelsPWM count: "); - Serial.println(count); + Serial.print("PCA9685::setChannelsPWM numChannels: "); + Serial.println(numChannels); #endif - writeChannelBegin(startChannel); - - for (int i = 0; i < count; i++) { - uint16_t phaseBegin, phaseEnd; - getPhaseCycle(startChannel + i, pwmAmounts[i], &phaseBegin, &phaseEnd); + // In avr/libraries/Wire.h and avr/libraries/utility/twi.h, BUFFER_LENGTH controls + // how many channels can be written at once. Therefore, we loop around until all + // channels have been written out into their registers. - writeChannelPWM(phaseBegin, phaseEnd); - } + while (numChannels > 0) { + writeChannelBegin(begChannel); - writeChannelEnd(); + int maxChannels = min(numChannels, (BUFFER_LENGTH - 1) / 4); + while (maxChannels-- > 0) { + uint16_t phaseBegin, phaseEnd; + getPhaseCycle(begChannel++, *pwmAmounts++, &phaseBegin, &phaseEnd); + + writeChannelPWM(phaseBegin, phaseEnd); + --numChannels; + } + + writeChannelEnd(); + if (_lastI2CError) return; + } } #ifndef PCA9685_EXCLUDE_EXT_FUNC @@ -250,7 +257,7 @@ uint16_t PCA9685::getChannelPWM(int channel) { return 0; } - byte bytesRead = i2cWire_requestFrom((byte)_i2cAddress, (byte)4); + int bytesRead = i2cWire_requestFrom((uint8_t)_i2cAddress, (uint8_t)4); if (bytesRead != 4) { while (bytesRead-- > 0) i2cWire_read(); @@ -262,10 +269,10 @@ uint16_t PCA9685::getChannelPWM(int channel) { return 0; } - uint16_t phaseBegin = i2cWire_read(); - phaseBegin |= i2cWire_read() << 8; - uint16_t phaseEnd = i2cWire_read(); - phaseEnd |= i2cWire_read() << 8; + uint16_t phaseBegin = (uint16_t)i2cWire_read(); + phaseBegin |= (uint16_t)i2cWire_read() << 8; + uint16_t phaseEnd = (uint16_t)i2cWire_read(); + phaseEnd |= (uint16_t)i2cWire_read() << 8; #ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print(" PCA9685::getChannelPWM phaseBegin: "); @@ -304,8 +311,8 @@ void PCA9685::enableAllCallAddress(byte i2cAddress) { writeRegister(PCA9685_ALLCALL_REG, i2cAddress); - byte mode1Val = readRegister(PCA9685_MODE1_REG); - writeRegister(PCA9685_MODE1_REG, (mode1Val |= PCA9685_MODE_ALLCALL)); + byte mode1Reg = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Reg |= PCA9685_MODE_ALLCALL)); } void PCA9685::enableSub1Address(byte i2cAddress) { @@ -317,11 +324,11 @@ void PCA9685::enableSub1Address(byte i2cAddress) { Serial.print("PCA9685::enableSub1Address i2cAddress: 0x"); Serial.println(i2cAddress, HEX); #endif - + writeRegister(PCA9685_SUBADR1_REG, i2cAddress); - byte mode1Val = readRegister(PCA9685_MODE1_REG); - writeRegister(PCA9685_MODE1_REG, (mode1Val |= PCA9685_MODE_SUBADR1)); + byte mode1Reg = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Reg |= PCA9685_MODE_SUBADR1)); } void PCA9685::enableSub2Address(byte i2cAddress) { @@ -336,8 +343,8 @@ void PCA9685::enableSub2Address(byte i2cAddress) { writeRegister(PCA9685_SUBADR2_REG, i2cAddress); - byte mode1Val = readRegister(PCA9685_MODE1_REG); - writeRegister(PCA9685_MODE1_REG, (mode1Val |= PCA9685_MODE_SUBADR2)); + byte mode1Reg = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Reg |= PCA9685_MODE_SUBADR2)); } void PCA9685::enableSub3Address(byte i2cAddress) { @@ -352,8 +359,8 @@ void PCA9685::enableSub3Address(byte i2cAddress) { writeRegister(PCA9685_SUBADR3_REG, i2cAddress); - byte mode1Val = readRegister(PCA9685_MODE1_REG); - writeRegister(PCA9685_MODE1_REG, (mode1Val |= PCA9685_MODE_SUBADR3)); + byte mode1Reg = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Reg |= PCA9685_MODE_SUBADR3)); } void PCA9685::disableAllCallAddress() { @@ -363,8 +370,8 @@ void PCA9685::disableAllCallAddress() { Serial.println("PCA9685::disableAllCallAddress"); #endif - byte mode1Val = readRegister(PCA9685_MODE1_REG); - writeRegister(PCA9685_MODE1_REG, (mode1Val &= ~PCA9685_MODE_ALLCALL)); + byte mode1Reg = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Reg &= ~PCA9685_MODE_ALLCALL)); } void PCA9685::disableSub1Address() { @@ -374,8 +381,8 @@ void PCA9685::disableSub1Address() { Serial.println("PCA9685::disableSub1Address"); #endif - byte mode1Val = readRegister(PCA9685_MODE1_REG); - writeRegister(PCA9685_MODE1_REG, (mode1Val &= ~PCA9685_MODE_SUBADR1)); + byte mode1Reg = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Reg &= ~PCA9685_MODE_SUBADR1)); } void PCA9685::disableSub2Address() { @@ -385,8 +392,8 @@ void PCA9685::disableSub2Address() { Serial.println("PCA9685::disableSub2Address"); #endif - byte mode1Val = readRegister(PCA9685_MODE1_REG); - writeRegister(PCA9685_MODE1_REG, (mode1Val &= ~PCA9685_MODE_SUBADR2)); + byte mode1Reg = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Reg &= ~PCA9685_MODE_SUBADR2)); } void PCA9685::disableSub3Address() { @@ -396,8 +403,8 @@ void PCA9685::disableSub3Address() { Serial.println("PCA9685::disableSub3Address"); #endif - byte mode1Val = readRegister(PCA9685_MODE1_REG); - writeRegister(PCA9685_MODE1_REG, (mode1Val &= ~PCA9685_MODE_SUBADR3)); + byte mode1Reg = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Reg &= ~PCA9685_MODE_SUBADR3)); } void PCA9685::enableExtClockLine() { @@ -406,12 +413,12 @@ void PCA9685::enableExtClockLine() { #endif // The PRE_SCALE register can only be set when the SLEEP bit of MODE1 register is set to logic 1. - byte mode1Val = readRegister(PCA9685_MODE1_REG); - writeRegister(PCA9685_MODE1_REG, (mode1Val = (mode1Val & ~PCA9685_MODE_RESTART) | PCA9685_MODE_SLEEP)); - writeRegister(PCA9685_MODE1_REG, (mode1Val |= PCA9685_MODE_EXTCLK)); + byte mode1Reg = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Reg = (mode1Reg & ~PCA9685_MODE_RESTART) | PCA9685_MODE_SLEEP)); + writeRegister(PCA9685_MODE1_REG, (mode1Reg |= PCA9685_MODE_EXTCLK)); // It takes 500us max for the oscillator to be up and running once SLEEP bit has been set to logic 0. - writeRegister(PCA9685_MODE1_REG, (mode1Val = (mode1Val & ~PCA9685_MODE_SLEEP) | PCA9685_MODE_RESTART)); + writeRegister(PCA9685_MODE1_REG, (mode1Reg = (mode1Reg & ~PCA9685_MODE_SLEEP) | PCA9685_MODE_RESTART)); delayMicroseconds(500); } @@ -481,8 +488,10 @@ void PCA9685::getPhaseCycle(int channel, uint16_t pwmAmount, uint16_t *phaseBegi void PCA9685::writeChannelBegin(int channel) { byte regAddress; - if (channel != -1) regAddress = PCA9685_LED0_REG + (channel << 2); - else regAddress = PCA9685_ALLLED_REG; + if (channel != -1) + regAddress = PCA9685_LED0_REG + (channel * 0x04); + else + regAddress = PCA9685_ALLLED_REG; #ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print(" PCA9685::writeChannelBegin channel: "); @@ -495,14 +504,6 @@ void PCA9685::writeChannelBegin(int channel) { i2cWire_write(regAddress); } -void PCA9685::writeChannelEnd() { - i2cWire_endTransmission(); - -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - checkForErrors(); -#endif -} - void PCA9685::writeChannelPWM(uint16_t phaseBegin, uint16_t phaseEnd) { #ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print(" PCA9685::writeChannelPWM phaseBegin: "); @@ -517,6 +518,14 @@ void PCA9685::writeChannelPWM(uint16_t phaseBegin, uint16_t phaseEnd) { i2cWire_write(highByte(phaseEnd)); } +void PCA9685::writeChannelEnd() { + i2cWire_endTransmission(); + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + checkForErrors(); +#endif +} + void PCA9685::writeRegister(byte regAddress, byte value) { #ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print(" PCA9685::writeRegister regAddress: 0x"); @@ -551,7 +560,7 @@ byte PCA9685::readRegister(byte regAddress) { return 0; } - byte bytesRead = i2cWire_requestFrom((byte)_i2cAddress, (byte)1); + int bytesRead = i2cWire_requestFrom((uint8_t)_i2cAddress, (uint8_t)1); if (bytesRead != 1) { while (bytesRead-- > 0) i2cWire_read(); @@ -633,13 +642,13 @@ int PCA9685::i2cWire_read(void) { #ifdef PCA9685_ENABLE_DEBUG_OUTPUT void PCA9685::printModuleInfo() { - Serial.println("\r\n ~~~ PCA9685 Module Info ~~~"); + Serial.println(""); Serial.println(" ~~~ PCA9685 Module Info ~~~"); - Serial.println("\r\ni2c Address:"); + Serial.println(""); Serial.println("i2c Address:"); Serial.print("0x"); Serial.println(_i2cAddress, HEX); - Serial.println("\r\nPhase Balancer:"); + Serial.println(""); Serial.println("Phase Balancer:"); switch (_phaseBalancer) { case PCA9685_PhaseBalancer_None: Serial.println("PCA9685_PhaseBalancer_None"); break; @@ -652,71 +661,71 @@ void PCA9685::printModuleInfo() { } if (!_isProxyAddresser) { - Serial.println("\r\nProxy Addresser:"); + Serial.println(""); Serial.println("Proxy Addresser:"); Serial.println("false"); - Serial.println("\r\nMode1 Register:"); - byte mode1Val = readRegister(PCA9685_MODE1_REG); + Serial.println(""); Serial.println("Mode1 Register:"); + byte mode1Reg = readRegister(PCA9685_MODE1_REG); Serial.print("0x"); - Serial.print(mode1Val, HEX); + Serial.print(mode1Reg, HEX); Serial.print(", Bitset:"); - if (mode1Val & PCA9685_MODE_RESTART) + if (mode1Reg & PCA9685_MODE_RESTART) Serial.print(" PCA9685_MODE_RESTART"); - if (mode1Val & PCA9685_MODE_EXTCLK) + if (mode1Reg & PCA9685_MODE_EXTCLK) Serial.print(" PCA9685_MODE_EXTCLK"); - if (mode1Val & PCA9685_MODE_AUTOINC) + if (mode1Reg & PCA9685_MODE_AUTOINC) Serial.print(" PCA9685_MODE_AUTOINC"); - if (mode1Val & PCA9685_MODE_SLEEP) + if (mode1Reg & PCA9685_MODE_SLEEP) Serial.print(" PCA9685_MODE_SLEEP"); - if (mode1Val & PCA9685_MODE_SUBADR1) + if (mode1Reg & PCA9685_MODE_SUBADR1) Serial.print(" PCA9685_MODE_SUBADR1"); - if (mode1Val & PCA9685_MODE_SUBADR2) + if (mode1Reg & PCA9685_MODE_SUBADR2) Serial.print(" PCA9685_MODE_SUBADR2"); - if (mode1Val & PCA9685_MODE_SUBADR3) + if (mode1Reg & PCA9685_MODE_SUBADR3) Serial.print(" PCA9685_MODE_SUBADR3"); - if (mode1Val & PCA9685_MODE_ALLCALL) + if (mode1Reg & PCA9685_MODE_ALLCALL) Serial.print(" PCA9685_MODE_ALLCALL"); Serial.println(""); - Serial.println("\r\nMode2 Register:"); - byte mode2Val = readRegister(PCA9685_MODE2_REG); + Serial.println(""); Serial.println("Mode2 Register:"); + byte mode2Reg = readRegister(PCA9685_MODE2_REG); Serial.print("0x"); - Serial.print(mode2Val, HEX); + Serial.print(mode2Reg, HEX); Serial.print(", Bitset:"); - if (mode2Val & PCA9685_MODE_INVRT) + if (mode2Reg & PCA9685_MODE_INVRT) Serial.print(" PCA9685_MODE_INVRT"); - if (mode2Val & PCA9685_MODE_OUTPUT_ONACK) + if (mode2Reg & PCA9685_MODE_OUTPUT_ONACK) Serial.print(" PCA9685_MODE_OUTPUT_ONACK"); - if (mode2Val & PCA9685_MODE_OUTPUT_TPOLE) + if (mode2Reg & PCA9685_MODE_OUTPUT_TPOLE) Serial.print(" PCA9685_MODE_OUTPUT_TPOLE"); - if (mode2Val & PCA9685_MODE_OUTNE_HIGHZ) + if (mode2Reg & PCA9685_MODE_OUTNE_HIGHZ) Serial.print(" PCA9685_MODE_OUTNE_HIGHZ"); - if (mode2Val & PCA9685_MODE_OUTNE_LOW) + if (mode2Reg & PCA9685_MODE_OUTNE_LOW) Serial.print(" PCA9685_MODE_OUTNE_LOW"); Serial.println(""); - Serial.println("\r\nSubAddress1 Register:"); - byte subAdr1Val = readRegister(PCA9685_SUBADR1_REG); + Serial.println(""); Serial.println("SubAddress1 Register:"); + byte subAdr1Reg = readRegister(PCA9685_SUBADR1_REG); Serial.print("0x"); - Serial.println(subAdr1Val, HEX); + Serial.println(subAdr1Reg, HEX); - Serial.println("\r\nSubAddress2 Register:"); - byte subAdr2Val = readRegister(PCA9685_SUBADR2_REG); + Serial.println(""); Serial.println("SubAddress2 Register:"); + byte subAdr2Reg = readRegister(PCA9685_SUBADR2_REG); Serial.print("0x"); - Serial.println(subAdr2Val, HEX); + Serial.println(subAdr2Reg, HEX); - Serial.println("\r\nSubAddress3 Register:"); - byte subAdr3Val = readRegister(PCA9685_SUBADR3_REG); + Serial.println(""); Serial.println("SubAddress3 Register:"); + byte subAdr3Reg = readRegister(PCA9685_SUBADR3_REG); Serial.print("0x"); - Serial.println(subAdr3Val, HEX); + Serial.println(subAdr3Reg, HEX); - Serial.println("\r\nAllCall Register:"); - byte allCallVal = readRegister(PCA9685_ALLCALL_REG); + Serial.println(""); Serial.println("AllCall Register:"); + byte allCallReg = readRegister(PCA9685_ALLCALL_REG); Serial.print("0x"); - Serial.println(allCallVal, HEX); + Serial.println(allCallReg, HEX); } else { - Serial.println("\r\nProxy Addresser:"); + Serial.println(""); Serial.println("Proxy Addresser:"); Serial.println("true"); } } diff --git a/PCA9685.h b/PCA9685.h index b0064f1..bafb39b 100644 --- a/PCA9685.h +++ b/PCA9685.h @@ -1,5 +1,6 @@ /* Arduino Library for the PCA9685 16-Channel PWM Driver Module. - Copyright (C) 2012 Kasper SkÃ¥rhøj + Copyright (c) 2016 NachtRaveVL + Copyright (C) 2012 Kasper SkÃ¥rhøj This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -18,7 +19,7 @@ Forked by Vitska, June 18th, 2016. Forked by NachtRaveVL, July 29th, 2016. - PCA9685-Arduino - Version 1.2.5 + PCA9685-Arduino - Version 1.2.6 */ #ifndef PCA9685_H @@ -122,8 +123,7 @@ class PCA9685 { // PWM amounts 0 - 4096, 0 full off, 4096 full on void setChannelPWM(int channel, uint16_t pwmAmount); - // Max of 7 channels can be batched at once - void setChannelsPWM(int startChannel, int count, const uint16_t *pwmAmounts); + void setChannelsPWM(int begChannel, int numChannels, const uint16_t *pwmAmounts); #ifndef PCA9685_EXCLUDE_EXT_FUNC // Sets all channels, but won't distribute phases @@ -166,8 +166,8 @@ class PCA9685 { void getPhaseCycle(int channel, uint16_t pwmAmount, uint16_t *phaseBegin, uint16_t *phaseEnd); void writeChannelBegin(int channel); - void writeChannelEnd(); void writeChannelPWM(uint16_t phaseBegin, uint16_t phaseEnd); + void writeChannelEnd(); void writeRegister(byte regAddress, byte value); byte readRegister(byte regAddress); diff --git a/README.md b/README.md index c07aebc..f570c11 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # PCA9685-Arduino Arduino Library for the PCA9685 16-Channel PWM Driver Module. -**PCA9685-Arduino - Version 1.2.5** +**PCA9685-Arduino - Version 1.2.6** Library to control a PCA9685 16-channel PWM driver module from an Arduino board. Licensed under the copy-left GNU GPL v3 license. @@ -81,8 +81,7 @@ void setup() { } void loop() { - // Only 7 channels can be batched at once, due to a BUFFER_LENGTH limit of 32 - word pwms[7]; + word pwms[12]; pwms[0] = random(0, 4096); pwms[1] = random(0, 4096); pwms[2] = random(0, 4096); @@ -90,8 +89,16 @@ void loop() { pwms[4] = random(0, 4096); pwms[5] = random(0, 4096); pwms[6] = random(0, 4096); - pwmDriver.setChannelsPWM(0, 7, pwms); + pwms[7] = random(0, 4096); + pwms[8] = random(0, 4096); + pwms[9] = random(0, 4096); + pwms[10] = random(0, 4096); + pwms[11] = random(0, 4096); + pwmDriver.setChannelsPWM(0, 12, pwms); delay(500); + + // Note that only 7 channels can be written in one i2c transaction due to a + // BUFFER_LENGTH limit of 32, so 12 channels will take two i2c transactions. } ``` diff --git a/library.properties b/library.properties index 3cf5bbf..c5523b0 100644 --- a/library.properties +++ b/library.properties @@ -1,6 +1,6 @@ name=PCA9685 16-Channel PWM Driver Module Library -version=1.2.5 -author=Kasper Skårhøj , Vitska, NachtRaveVL +version=1.2.6 +author=NachtRaveVL , Vitska, Kasper Skårhøj maintainer=NachtRaveVL sentence=Library to control a PCA9685 16-channel PWM driver module from an Arduino board. paragraph=This library allows communication with boards running a PCA6985 16-channel PWM driver module. It supports a wide range of available functionality, from setting the output PWM frequecy, allowing multi-device proxy addressing, and provides an assistant class for working with Servos. From aabcb55703900dad79dabe5c1a968d71773b059a Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Sat, 20 Aug 2016 03:53:58 -0700 Subject: [PATCH 16/57] Typo. --- PCA9685.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/PCA9685.cpp b/PCA9685.cpp index 006919f..9929d15 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -447,7 +447,7 @@ static const char *textForI2CError(byte errorCode) { void PCA9685::checkForErrors() { if (_lastI2CError) { - Serial.print(" LeptonFLiR::checkErrors lastI2CError: "); + Serial.print(" PCA9685::checkErrors lastI2CError: "); Serial.print(_lastI2CError); Serial.print(": "); Serial.println(textForI2CError(getLastI2CError())); From 0f6efe2cee0d0fb077c64ec8f56bc0cf8b6d60e2 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Sat, 20 Aug 2016 18:54:16 -0700 Subject: [PATCH 17/57] Updating readme. --- README.md | 54 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 53 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f570c11..af90c6f 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,8 @@ Created by Kasper Sk Forked by Vitska, June 18th, 2016. Forked by NachtRaveVL, July 29th, 2016. +This library allows communication with boards running a PCA6985 16-channel PWM driver module. It supports a wide range of available functionality, from setting the output PWM frequecy, allowing multi-device proxy addressing, and provides an assistant class for working with Servos. + ## Library Setup There are several defines inside of the library's header file that allows for more fine-tuned control. @@ -62,6 +64,9 @@ void setup() { ``` ### Batching Example + +In this example we will randomly select PWM frequencies on all 12 outputs and allow them to drive for 5 seconds before changing them. + ```Arduino #include #include "PCA9685.h" @@ -95,7 +100,7 @@ void loop() { pwms[10] = random(0, 4096); pwms[11] = random(0, 4096); pwmDriver.setChannelsPWM(0, 12, pwms); - delay(500); + delay(5000); // Note that only 7 channels can be written in one i2c transaction due to a // BUFFER_LENGTH limit of 32, so 12 channels will take two i2c transactions. @@ -198,3 +203,50 @@ void setup() { } ``` + +## Module Info + +If one uncomments the PCA9685_ENABLE_DEBUG_OUTPUT define in the header file (thus enabling debug output), a special printModuleInfo() method will become available which will display information about the module itself, including initalized states, register values, current settings, etc. All calls being made will display internal debug information about the structure of the call itself. An example of this output is shown here: + +```Arduino + ~~~ PCA9685 Module Info ~~~ + +i2c Address: +0x40 + +Phase Balancer: +PCA9685_PhaseBalancer_Weaved + +Proxy Addresser: +false + +Mode1 Register: + PCA9685::readRegister regAddress: 0x0 + PCA9685::readRegister retVal: 0x20 +0x20, Bitset: PCA9685_MODE_AUTOINC + +Mode2 Register: + PCA9685::readRegister regAddress: 0x1 + PCA9685::readRegister retVal: 0xC +0xC, Bitset: PCA9685_MODE_OUTPUT_ONACK PCA9685_MODE_OUTPUT_TPOLE + +SubAddress1 Register: + PCA9685::readRegister regAddress: 0x2 + PCA9685::readRegister retVal: 0xE2 +0xE2 + +SubAddress2 Register: + PCA9685::readRegister regAddress: 0x3 + PCA9685::readRegister retVal: 0xE4 +0xE4 + +SubAddress3 Register: + PCA9685::readRegister regAddress: 0x4 + PCA9685::readRegister retVal: 0xE8 +0xE8 + +AllCall Register: + PCA9685::readRegister regAddress: 0x5 + PCA9685::readRegister retVal: 0xE0 +0xE0 +``` \ No newline at end of file From 430ed25e3cce310951c71a8bbd5e8595c103e4e8 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Sat, 20 Aug 2016 18:55:50 -0700 Subject: [PATCH 18/57] Updating readme. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index af90c6f..518d0d3 100644 --- a/README.md +++ b/README.md @@ -249,4 +249,4 @@ AllCall Register: PCA9685::readRegister regAddress: 0x5 PCA9685::readRegister retVal: 0xE0 0xE0 -``` \ No newline at end of file +``` From a5aab26e8715fa62d2a1001661497ce5b6b06e0d Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Sat, 20 Aug 2016 19:38:48 -0700 Subject: [PATCH 19/57] Updated readme. --- README.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 518d0d3..12d671d 100644 --- a/README.md +++ b/README.md @@ -65,7 +65,7 @@ void setup() { ### Batching Example -In this example we will randomly select PWM frequencies on all 12 outputs and allow them to drive for 5 seconds before changing them. +In this example, we randomly select PWM frequencies on all 12 outputs and allow them to drive for 5 seconds before changing them. ```Arduino #include @@ -109,6 +109,9 @@ void loop() { ``` ### Multi-Device Proxy Example + +In this example, we use a special instance to control other modules attached to it via the ALL_CALL register. + ```Arduino #include #include "PCA9685.h" @@ -149,6 +152,9 @@ void setup() { ``` ### Servo Evaluator Example + +In this example, we utilize the ServoEvaluator class to assist with setting PWM frequencies when working with servos. + ```Arduino #include #include "PCA9685.h" From 8f4f89cdd7c025747f7fe4e60c22ee9635902176 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Sat, 20 Aug 2016 23:29:25 -0700 Subject: [PATCH 20/57] Updated readme. Made Linear phase balancing the default. Upping version number. --- PCA9685.cpp | 22 +++---- PCA9685.h | 10 +-- README.md | 158 +++++++++++++++++++++++++++++---------------- library.properties | 2 +- 4 files changed, 120 insertions(+), 72 deletions(-) diff --git a/PCA9685.cpp b/PCA9685.cpp index 9929d15..c1611f7 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -19,7 +19,7 @@ Forked by Vitska, June 18th, 2016. Forked by NachtRaveVL, July 29th, 2016. - PCA9685-Arduino - Version 1.2.6 + PCA9685-Arduino - Version 1.2.7 */ #include "PCA9685.h" @@ -50,10 +50,10 @@ #define PCA9685_SW_RESET (byte)0x06 // Sent to address 0x00 to reset all devices on Wire line #define PCA9685_PWM_FULL (uint16_t)0x01000 // Special value for full on/full off LEDx modes -// To balance the load out in a weaved fashion, we use this offset table to distribute the -// load on the outputs in a more intelligent fashion than just a simple 4096/16 offset per -// channel. We can set the off cycle value to be lower than the on cycle, which will put -// the high edge across the 0-4095 phase cycle range. +// To balance the load out in a weaved fashion, we use this offset table to distribute +// the load on the outputs in a more interleaving fashion than just a simple 16 offset +// per channel. We can set the off cycle value to be lower than the on cycle, which will +// put the high edge across the 0-4095 phase cycle range, which is supported by device. static uint16_t phaseDistTable[16] = { 0, 2048, 1024, 3072, 512, 3584, 1536, 2560, 256, 3840, 1280, 2304, 3328, 768, 2816, 1792 }; #ifndef PCA9685_ENABLE_SOFTWARE_I2C @@ -465,16 +465,16 @@ void PCA9685::getPhaseCycle(int channel, uint16_t pwmAmount, uint16_t *phaseBegi *phaseBegin = 0; *phaseEnd = PCA9685_PWM_FULL; } - else if (_phaseBalancer == PCA9685_PhaseBalancer_Weaved) { + else if (_phaseBalancer == PCA9685_PhaseBalancer_Linear) { // Distribute high phase area over entire phase range to balance load. - *phaseBegin = phaseDistTable[channel]; + *phaseBegin = channel * (4096 / 16); *phaseEnd = *phaseBegin + pwmAmount; if (*phaseEnd >= PCA9685_PWM_FULL) *phaseEnd -= PCA9685_PWM_FULL; } - else if (_phaseBalancer == PCA9685_PhaseBalancer_Linear) { + else if (_phaseBalancer == PCA9685_PhaseBalancer_Weaved) { // Distribute high phase area over entire phase range to balance load. - *phaseBegin = channel * (4096 / 16); + *phaseBegin = phaseDistTable[channel]; *phaseEnd = *phaseBegin + pwmAmount; if (*phaseEnd >= PCA9685_PWM_FULL) *phaseEnd -= PCA9685_PWM_FULL; @@ -652,10 +652,10 @@ void PCA9685::printModuleInfo() { switch (_phaseBalancer) { case PCA9685_PhaseBalancer_None: Serial.println("PCA9685_PhaseBalancer_None"); break; - case PCA9685_PhaseBalancer_Weaved: - Serial.println("PCA9685_PhaseBalancer_Weaved"); break; case PCA9685_PhaseBalancer_Linear: Serial.println("PCA9685_PhaseBalancer_Linear"); break; + case PCA9685_PhaseBalancer_Weaved: + Serial.println("PCA9685_PhaseBalancer_Weaved"); break; default: Serial.println(""); break; } diff --git a/PCA9685.h b/PCA9685.h index bafb39b..8a7e0fe 100644 --- a/PCA9685.h +++ b/PCA9685.h @@ -19,7 +19,7 @@ Forked by Vitska, June 18th, 2016. Forked by NachtRaveVL, July 29th, 2016. - PCA9685-Arduino - Version 1.2.6 + PCA9685-Arduino - Version 1.2.7 */ #ifndef PCA9685_H @@ -73,8 +73,8 @@ typedef enum { PCA9685_PhaseBalancer_None = -1, // Disables phase balancing, all high phase areas start at begining of cycle - PCA9685_PhaseBalancer_Weaved = 0, // Balances first few outputs better, steps away from previous shorten towards last output - PCA9685_PhaseBalancer_Linear, // Balances all outputs linearly, 256 steps away from previous output + PCA9685_PhaseBalancer_Linear = 0, // Balances all outputs linearly, 256 steps away from previous output + PCA9685_PhaseBalancer_Weaved, // Balances first few outputs better, steps away from previous shorten towards last output PCA9685_PhaseBalancer_Count } PCA9685_PhaseBalancer; @@ -85,12 +85,12 @@ class PCA9685 { // May use a different Wire instance than Wire. Some chipsets, such as Due/Zero/etc., // have a Wire1 class instance that uses the SDA1/SCL1 lines instead. // Supported i2c baud rates are 100kHz, 400kHz, and 1000kHz. - PCA9685(TwoWire& i2cWire = Wire, PCA9685_PhaseBalancer phaseBalancer = PCA9685_PhaseBalancer_Weaved); + PCA9685(TwoWire& i2cWire = Wire, PCA9685_PhaseBalancer phaseBalancer = PCA9685_PhaseBalancer_Linear); #else // Minimum supported i2c baud rate is 100kHz, which means minimum supported processor // speed is 4MHz+ while running i2c standard mode. For 400kHz i2c baud rate, minimum // supported processor speed is 16MHz+ while running i2c fast mode. - PCA9685(PCA9685_PhaseBalancer phaseBalancer = PCA9685_PhaseBalancer_Weaved); + PCA9685(PCA9685_PhaseBalancer phaseBalancer = PCA9685_PhaseBalancer_Linear); #endif // Should be called only once in setup(), before any init()'s, but after Wire.begin(). diff --git a/README.md b/README.md index 12d671d..154a15c 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # PCA9685-Arduino Arduino Library for the PCA9685 16-Channel PWM Driver Module. -**PCA9685-Arduino - Version 1.2.6** +**PCA9685-Arduino - Version 1.2.7** Library to control a PCA9685 16-channel PWM driver module from an Arduino board. Licensed under the copy-left GNU GPL v3 license. @@ -43,22 +43,23 @@ Below are several examples of library usage. #include #include "PCA9685.h" -PCA9685 pwmDriver; +PCA9685 pwmController; // Library using default Wire and default linear phase balancing scheme void setup() { Serial.begin(115200); - Wire.begin(); // Wire must be started first - Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz - pwmDriver.resetDevices(); // Software resets all PCA9685 devices on Wire line + Wire.begin(); // Wire must be started first + Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz - pwmDriver.init(B000000); // Address pins A5-A0 set to B000000 - pwmDriver.setPWMFrequency(100); // Default is 200Hz, supports 24Hz to 1526Hz + pwmController.resetDevices(); // Software resets all PCA9685 devices on Wire line + pwmController.init(B000000); // Address pins A5-A0 set to B000000 + pwmController.setPWMFrequency(100); // Default is 200Hz, supports 24Hz to 1526Hz - pwmDriver.setChannelPWM(0, 128 << 4); // Set PWM to 128/255, but in 4096 land - Serial.println(pwmDriver.getChannelPWM(0)); // Should output 2048, which is 128 << 4 + pwmController.setChannelPWM(0, 128 << 4); // Set PWM to 128/255, but in 4096 land + + Serial.println(pwmController.getChannelPWM(0)); // Should output 2048, which is 128 << 4 } ``` @@ -71,18 +72,18 @@ In this example, we randomly select PWM frequencies on all 12 outputs and allow #include #include "PCA9685.h" -PCA9685 pwmDriver; +PCA9685 pwmController; // Library using default Wire and default linear phase balancing scheme void setup() { - Wire.begin(); // Wire must be started first - Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz + Wire.begin(); // Wire must be started first + Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz - pwmDriver.resetDevices(); // Software resets all PCA9685 devices on Wire line + pwmController.resetDevices(); // Software resets all PCA9685 devices on Wire line - pwmDriver.init(B010101); // Address pins A5-A0 set to B010101 - pwmDriver.setPWMFrequency(500); // Default is 200Hz, supports 24Hz to 1526Hz + pwmController.init(B010101); // Address pins A5-A0 set to B010101 + pwmController.setPWMFrequency(500); // Default is 200Hz, supports 24Hz to 1526Hz - randomSeed(analogRead(0)); // Use white noise for our randomness + randomSeed(analogRead(0)); // Use white noise for our randomness } void loop() { @@ -99,10 +100,10 @@ void loop() { pwms[9] = random(0, 4096); pwms[10] = random(0, 4096); pwms[11] = random(0, 4096); - pwmDriver.setChannelsPWM(0, 12, pwms); + pwmController.setChannelsPWM(0, 12, pwms); delay(5000); - // Note that only 7 channels can be written in one i2c transaction due to a + // Note: Only 7 channels can be written in one i2c transaction due to a // BUFFER_LENGTH limit of 32, so 12 channels will take two i2c transactions. } @@ -110,56 +111,56 @@ void loop() { ### Multi-Device Proxy Example -In this example, we use a special instance to control other modules attached to it via the ALL_CALL register. +In this example, we use a special to control other modules attached to it via the ALL_CALL register. ```Arduino #include #include "PCA9685.h" -PCA9685 pwmDriver1; -PCA9685 pwmDriver2; +PCA9685 pwmController1; // Library using default Wire and default linear phase balancing scheme +PCA9685 pwmController2; // Library using default Wire and default linear phase balancing scheme -PCA9685 pwmDriverAll; // Not a real device, will act as a proxy to pwmDriver1 and pwmDriver2 +PCA9685 pwmControllerAll; // Not a real device, will act as a proxy to pwmController1 and pwmController2 void setup() { Serial.begin(115200); - Wire.begin(); // Wire must be started first - Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz + Wire.begin(); // Wire must be started first + Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz - pwmDriver1.resetDevices(); // Software resets all PCA9685 devices on Wire line (including pwmDriver2 in this case) + pwmController1.resetDevices(); // Software resets all PCA9685 devices on Wire line (including pwmController2 in this case) - pwmDriver1.init(B000000); // Address pins A5-A0 set to B000000 - pwmDriver2.init(B000001); // Address pins A5-A0 set to B000001 + pwmController1.init(B000000); // Address pins A5-A0 set to B000000 + pwmController2.init(B000001); // Address pins A5-A0 set to B000001 - pwmDriver1.setChannelOff(0); // Turn channel 0 off - pwmDriver2.setChannelOff(0); // On both + pwmController1.setChannelOff(0); // Turn channel 0 off + pwmController2.setChannelOff(0); // On both - pwmDriver1.enableAllCallAddress(); // Default address of 0xE0 - pwmDriver2.enableAllCallAddress(); // Same default address + pwmController1.enableAllCallAddress(); // Default address of 0xE0 + pwmController2.enableAllCallAddress(); // Same default address - pwmDriverAll.initAsProxyAddresser(); // Same default address of 0x0E as used in enable above + pwmControllerAll.initAsProxyAddresser(); // Same default address of 0x0E as used in enable above - pwmDriverAll.setChannelPWM(0, 4096); // Enables full on on both pwmDriver1 and pwmDriver2 + pwmControllerAll.setChannelPWM(0, 4096); // Enables full on on both pwmController1 and pwmController2 - Serial.println(pwmDriver1.getChannelPWM(0)); // Should output 4096 - Serial.println(pwmDriver2.getChannelPWM(0)); // Should also output 4096 + Serial.println(pwmController1.getChannelPWM(0)); // Should output 4096 + Serial.println(pwmController2.getChannelPWM(0)); // Should also output 4096 - // Note: Various parts of functionality of the proxy class instance actually - // are disabled, typically anything that involves a read command being issued. + // Note: Various parts of functionality of the proxy class instance are actually + // disabled - typically anything that involves a read command being issued. } ``` ### Servo Evaluator Example -In this example, we utilize the ServoEvaluator class to assist with setting PWM frequencies when working with servos. +In this example, we utilize the ServoEvaluator class to assist with setting PWM frequencies when working with servos. We will be using Wire1, which is only available on boards with SDA1/SCL1 (Due, Zero, etc.) - change to Wire if Wire1 is unavailable. ```Arduino #include #include "PCA9685.h" -PCA9685 pwmDriver; +PCA9685 pwmController(Wire1, PCA9685_PhaseBalancer_Weaved); // Library using Wire1 and weaved phase balancing scheme // Linearly interpolates between standard 2.5%/12.5% phase length (102/512) for -90°/+90° PCA9685_ServoEvaluator pwmServo1; @@ -173,48 +174,95 @@ PCA9685_ServoEvaluator pwmServo2(128,324,526); void setup() { Serial.begin(115200); - Wire.begin(); // Wire must be started first - Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz - pwmDriver.resetDevices(); // Software resets all PCA9685 devices on Wire line + Wire1.begin(); // Wire must be started first + Wire1.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz + + pwmController.resetDevices(); // Software resets all PCA9685 devices on Wire line - pwmDriver.init(B000000); // Address pins A5-A0 set to B000000 - pwmDriver.setPWMFrequency(50); // 50Hz provides 20ms standard servo phase length + pwmController.init(B000000); // Address pins A5-A0 set to B000000 + pwmController.setPWMFrequency(50); // 50Hz provides 20ms standard servo phase length - pwmDriver.setChannelPWM(0, pwmServo1.pwmForAngle(-90)); - Serial.println(pwmDriver.getChannelPWM(0)); // Should output 102 for -90° + pwmController.setChannelPWM(0, pwmServo1.pwmForAngle(-90)); + Serial.println(pwmController.getChannelPWM(0)); // Should output 102 for -90° // Showing linearity for midpoint, 205 away from both -90° and 90° Serial.println(pwmServo1.pwmForAngle(0)); // Should output 307 for 0° - pwmDriver.setChannelPWM(0, pwmServo1.pwmForAngle(90)); - Serial.println(pwmDriver.getChannelPWM(0)); // Should output 512 for +90° + pwmController.setChannelPWM(0, pwmServo1.pwmForAngle(90)); + Serial.println(pwmController.getChannelPWM(0)); // Should output 512 for +90° - pwmDriver.setChannelPWM(1, pwmServo2.pwmForAngle(-90)); - Serial.println(pwmDriver.getChannelPWM(1)); // Should output 128 for -90° + pwmController.setChannelPWM(1, pwmServo2.pwmForAngle(-90)); + Serial.println(pwmController.getChannelPWM(1)); // Should output 128 for -90° // Showing less resolution in the -90° to 0° range Serial.println(pwmServo2.pwmForAngle(-45)); // Should output 225 for -45°, 97 away from -90° - pwmDriver.setChannelPWM(1, pwmServo2.pwmForAngle(0)); - Serial.println(pwmDriver.getChannelPWM(1)); // Should output 324 for 0° + pwmController.setChannelPWM(1, pwmServo2.pwmForAngle(0)); + Serial.println(pwmController.getChannelPWM(1)); // Should output 324 for 0° // Showing more resolution in the 0° to +90° range Serial.println(pwmServo2.pwmForAngle(45)); // Should output 424 for +45°, 102 away from +90° - pwmDriver.setChannelPWM(1, pwmServo2.pwmForAngle(90)); - Serial.println(pwmDriver.getChannelPWM(1)); // Should output 526 for +90° + pwmController.setChannelPWM(1, pwmServo2.pwmForAngle(90)); + Serial.println(pwmController.getChannelPWM(1)); // Should output 526 for +90° +} + +``` + +### Software I2C Example + +In this example, we utilize the software I2C functionality for chips that do not have a hardware I2C bus. We must uncomment the PCA9685_ENABLE_SOFTWARE_I2C define in the libraries main header file for software I2C mode to be enabled. + +In PCA9685.h: +```Arduino +// Uncomment this define to enable use of the software i2c library (min 4MHz+ processor required). +#define PCA9685_ENABLE_SOFTWARE_I2C 1 // http://playground.arduino.cc/Main/SoftwareI2CLibrary +``` + +In main sketch: +```Arduino +#include "PCA9685.h" + +#define SCL_PIN 2 // Setup defines are written before library include +#define SCL_PORT PORTD +#define SDA_PIN 0 +#define SDA_PORT PORTC + +#if F_CPU >= 16000000 +#define I2C_FASTMODE 1 // Running a 16MHz processor allows us to use I2C fast mode +#endif + +#include "SoftI2CMaster.h" // Include must come after setup defines + +PCA9685 pwmController; // Library using linear weaved phase balancing scheme + +void setup() { + i2c_init(); // Software I2C must be started first + + pwmController.resetDevices(); // Software resets all PCA9685 devices on software I2C line + + pwmController.init(B000000); // Address pins A5-A0 set to B000000 + + pwmController.setChannelPWM(0, 2048); // Should see a 50% duty cycle along the 5ms phase width } ``` ## Module Info -If one uncomments the PCA9685_ENABLE_DEBUG_OUTPUT define in the header file (thus enabling debug output), a special printModuleInfo() method will become available which will display information about the module itself, including initalized states, register values, current settings, etc. All calls being made will display internal debug information about the structure of the call itself. An example of this output is shown here: +If one uncomments the PCA9685_ENABLE_DEBUG_OUTPUT define in the libraries main header file (thus enabling debug output), a special printModuleInfo() method will become available that will display information about the module itself, including initalized states, register values, current settings, etc. All calls being made will display internal debug information about the structure of the call itself. An example of this output is shown here: +In PCA9685.h: ```Arduino +// Uncomment this define to enable debug output. +#define PCA9685_ENABLE_DEBUG_OUTPUT 1 +``` + +In serial monitor: +``` ~~~ PCA9685 Module Info ~~~ i2c Address: diff --git a/library.properties b/library.properties index c5523b0..06418b0 100644 --- a/library.properties +++ b/library.properties @@ -1,5 +1,5 @@ name=PCA9685 16-Channel PWM Driver Module Library -version=1.2.6 +version=1.2.7 author=NachtRaveVL , Vitska, Kasper Skårhøj maintainer=NachtRaveVL sentence=Library to control a PCA9685 16-channel PWM driver module from an Arduino board. From a5776dba2fd6037edd695b62cae378e38ae08d73 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Sat, 20 Aug 2016 23:35:46 -0700 Subject: [PATCH 21/57] Updated readme. --- README.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/README.md b/README.md index 154a15c..88d080f 100644 --- a/README.md +++ b/README.md @@ -261,6 +261,17 @@ In PCA9685.h: #define PCA9685_ENABLE_DEBUG_OUTPUT 1 ``` +In main sketch: +```Arduino +PCA9685 pwmController; + +void setup() { + // ... + + pwmController.printModuleInfo(); +} +``` + In serial monitor: ``` ~~~ PCA9685 Module Info ~~~ From 09daa546d5d84951cd51b7ba9afe4adae00e7a99 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Sat, 20 Aug 2016 23:36:26 -0700 Subject: [PATCH 22/57] Updated readme. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 88d080f..a5c3f84 100644 --- a/README.md +++ b/README.md @@ -111,7 +111,7 @@ void loop() { ### Multi-Device Proxy Example -In this example, we use a special to control other modules attached to it via the ALL_CALL register. +In this example, we use a special instance to control other modules attached to it via the ALL_CALL register. ```Arduino #include From eb22c31554deaa45c04f95fecb7e7194359b779e Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Sun, 21 Aug 2016 03:59:41 -0700 Subject: [PATCH 23/57] Updating readme. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a5c3f84..90858f2 100644 --- a/README.md +++ b/README.md @@ -237,7 +237,7 @@ In main sketch: #include "SoftI2CMaster.h" // Include must come after setup defines -PCA9685 pwmController; // Library using linear weaved phase balancing scheme +PCA9685 pwmController; // Library using default linear phase balancing scheme void setup() { i2c_init(); // Software I2C must be started first From 31ae2a5ca7d9c3694e89718889ed76c062bb75c0 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Sun, 21 Aug 2016 04:01:54 -0700 Subject: [PATCH 24/57] Updating readme. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 90858f2..52fa774 100644 --- a/README.md +++ b/README.md @@ -253,7 +253,7 @@ void setup() { ## Module Info -If one uncomments the PCA9685_ENABLE_DEBUG_OUTPUT define in the libraries main header file (thus enabling debug output), a special printModuleInfo() method will become available that will display information about the module itself, including initalized states, register values, current settings, etc. All calls being made will display internal debug information about the structure of the call itself. An example of this output is shown here: +If one uncomments the PCA9685_ENABLE_DEBUG_OUTPUT define in the libraries main header file (thus enabling debug output), the printModuleInfo() method becomes available, which will display information about the module itself, including initalized states, register values, current settings, etc. All calls being made will display internal debug information about the structure of the call itself. An example of this output is shown here: In PCA9685.h: ```Arduino From ef54b9f86cc3c5533459f481d5cc3b561165e47f Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Sun, 21 Aug 2016 04:03:32 -0700 Subject: [PATCH 25/57] Updating readme. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 52fa774..ab78865 100644 --- a/README.md +++ b/README.md @@ -253,7 +253,7 @@ void setup() { ## Module Info -If one uncomments the PCA9685_ENABLE_DEBUG_OUTPUT define in the libraries main header file (thus enabling debug output), the printModuleInfo() method becomes available, which will display information about the module itself, including initalized states, register values, current settings, etc. All calls being made will display internal debug information about the structure of the call itself. An example of this output is shown here: +If one uncomments the PCA9685_ENABLE_DEBUG_OUTPUT define in the libraries main header file (thus enabling debug output) the printModuleInfo() method becomes available, which will display information about the module itself, including initalized states, register values, current settings, etc. All calls being made will display internal debug information about the structure of the call itself. An example of this output is shown here: In PCA9685.h: ```Arduino From d88b2b2c39d733a6263278caec4afcf5b079ca07 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Fri, 26 Aug 2016 18:47:56 -0700 Subject: [PATCH 26/57] Improvement to i2c software read method. --- PCA9685.cpp | 16 ++++++++-------- PCA9685.h | 2 +- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/PCA9685.cpp b/PCA9685.cpp index c1611f7..e4309e2 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -552,7 +552,7 @@ byte PCA9685::readRegister(byte regAddress) { i2cWire_beginTransmission(_i2cAddress); i2cWire_write(regAddress); - if (i2cWire_endTransmission() != -0) { + if (i2cWire_endTransmission() != 0) { #ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.println(" PCA9685::readRegister Read request did not set register. Aborting."); checkForErrors(); @@ -624,17 +624,17 @@ size_t PCA9685::i2cWire_write(uint8_t data) { #endif } -int PCA9685::i2cWire_read(void) { +uint8_t PCA9685::i2cWire_read(void) { #ifndef PCA9685_ENABLE_SOFTWARE_I2C - return _i2cWire->read(); + return (uint8_t)(_i2cWire->read() & 0xFF); #else - if (_readBytes > 1) - return (int)i2c_read(_readBytes--); + if (_readBytes > 1) { + _readByes -= 1; + return (uint8_t)(i2c_read(false) & 0xFF); + } else { _readBytes = 0; - int retVal = (int)i2c_read(true); - i2c_stop(); - return retVal; + return (uint8_t)(i2c_read(true) & 0xFF); } #endif } diff --git a/PCA9685.h b/PCA9685.h index 8a7e0fe..d4626bf 100644 --- a/PCA9685.h +++ b/PCA9685.h @@ -179,7 +179,7 @@ class PCA9685 { uint8_t i2cWire_endTransmission(void); uint8_t i2cWire_requestFrom(uint8_t, uint8_t); size_t i2cWire_write(uint8_t); - int i2cWire_read(void); + uint8_t i2cWire_read(void); }; #ifndef PCA9685_EXCLUDE_SERVO_EVAL From 3ea55dc9d720f313db50cd6ef92b692198aaeecc Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Fri, 26 Aug 2016 18:54:18 -0700 Subject: [PATCH 27/57] Removing unnecessary compares. --- PCA9685.cpp | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/PCA9685.cpp b/PCA9685.cpp index e4309e2..a6deef7 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -249,7 +249,7 @@ uint16_t PCA9685::getChannelPWM(int channel) { i2cWire_beginTransmission(_i2cAddress); i2cWire_write(regAddress); - if (i2cWire_endTransmission() != 0) { + if (i2cWire_endTransmission()) { #ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.println(" PCA9685::getChannelPWM Read request did not set register. Aborting."); checkForErrors(); @@ -552,7 +552,7 @@ byte PCA9685::readRegister(byte regAddress) { i2cWire_beginTransmission(_i2cAddress); i2cWire_write(regAddress); - if (i2cWire_endTransmission() != 0) { + if (i2cWire_endTransmission()) { #ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.println(" PCA9685::readRegister Read request did not set register. Aborting."); checkForErrors(); From 50be9ab910250f2b102c9572f9281dae5f8e3778 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Fri, 26 Aug 2016 19:04:54 -0700 Subject: [PATCH 28/57] Removed unncessary debug output. --- PCA9685.cpp | 4 ---- 1 file changed, 4 deletions(-) diff --git a/PCA9685.cpp b/PCA9685.cpp index a6deef7..be00081 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -251,7 +251,6 @@ uint16_t PCA9685::getChannelPWM(int channel) { i2cWire_write(regAddress); if (i2cWire_endTransmission()) { #ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.println(" PCA9685::getChannelPWM Read request did not set register. Aborting."); checkForErrors(); #endif return 0; @@ -263,7 +262,6 @@ uint16_t PCA9685::getChannelPWM(int channel) { i2cWire_read(); _lastI2CError = 4; #ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.println(" PCA9685::getChannelPWM Read request data not available. Aborting."); checkForErrors(); #endif return 0; @@ -554,7 +552,6 @@ byte PCA9685::readRegister(byte regAddress) { i2cWire_write(regAddress); if (i2cWire_endTransmission()) { #ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.println(" PCA9685::readRegister Read request did not set register. Aborting."); checkForErrors(); #endif return 0; @@ -566,7 +563,6 @@ byte PCA9685::readRegister(byte regAddress) { i2cWire_read(); _lastI2CError = 4; #ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.println(" PCA9685::readRegister Read request data not available. Aborting."); checkForErrors(); #endif return 0; From 36cbbf2b0303c78ea4e12bbef0c814b8c5457382 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Sun, 19 Mar 2017 17:24:46 -0700 Subject: [PATCH 29/57] Fixing channel 15 multi PWM setter. Thanks @SugarBombs for the catch! --- PCA9685.cpp | 4 +- PCA9685.h | 2 +- README.md | 535 +++++++++++++++++++++++---------------------- library.properties | 2 +- 4 files changed, 272 insertions(+), 271 deletions(-) diff --git a/PCA9685.cpp b/PCA9685.cpp index be00081..f916691 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -19,7 +19,7 @@ Forked by Vitska, June 18th, 2016. Forked by NachtRaveVL, July 29th, 2016. - PCA9685-Arduino - Version 1.2.7 + PCA9685-Arduino - Version 1.2.8 */ #include "PCA9685.h" @@ -190,7 +190,7 @@ void PCA9685::setChannelPWM(int channel, uint16_t pwmAmount) { void PCA9685::setChannelsPWM(int begChannel, int numChannels, const uint16_t *pwmAmounts) { if (begChannel < 0 || begChannel > 15 || numChannels < 0) return; - if (begChannel + numChannels > 15) numChannels -= (begChannel + numChannels) - 15; + if (begChannel + numChannels > 16) numChannels -= (begChannel + numChannels) - 16; #ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print("PCA9685::setChannelsPWM numChannels: "); diff --git a/PCA9685.h b/PCA9685.h index d4626bf..764da47 100644 --- a/PCA9685.h +++ b/PCA9685.h @@ -19,7 +19,7 @@ Forked by Vitska, June 18th, 2016. Forked by NachtRaveVL, July 29th, 2016. - PCA9685-Arduino - Version 1.2.7 + PCA9685-Arduino - Version 1.2.8 */ #ifndef PCA9685_H diff --git a/README.md b/README.md index ab78865..370d35c 100644 --- a/README.md +++ b/README.md @@ -1,231 +1,231 @@ -# PCA9685-Arduino -Arduino Library for the PCA9685 16-Channel PWM Driver Module. - -**PCA9685-Arduino - Version 1.2.7** - -Library to control a PCA9685 16-channel PWM driver module from an Arduino board. -Licensed under the copy-left GNU GPL v3 license. - -Created by Kasper Skårhøj, August 3rd, 2012. -Forked by Vitska, June 18th, 2016. -Forked by NachtRaveVL, July 29th, 2016. - -This library allows communication with boards running a PCA6985 16-channel PWM driver module. It supports a wide range of available functionality, from setting the output PWM frequecy, allowing multi-device proxy addressing, and provides an assistant class for working with Servos. - -## Library Setup - -There are several defines inside of the library's header file that allows for more fine-tuned control. - -```Arduino -// Uncomment this define to enable use of the software i2c library (min 4MHz+ processor required). -//#define PCA9685_ENABLE_SOFTWARE_I2C 1 // http://playground.arduino.cc/Main/SoftwareI2CLibrary - -// Uncomment this define if wanting to exclude extended functionality from compilation. -//#define PCA9685_EXCLUDE_EXT_FUNC 1 - -// Uncomment this define if wanting to exclude ServoEvaluator assistant from compilation. -//#define PCA9685_EXCLUDE_SERVO_EVAL 1 - -// Uncomment this define to enable debug output. -//#define PCA9685_ENABLE_DEBUG_OUTPUT 1 -``` - -## Servo Control Note - -Many 180 degree controlled digital servos run on a 20ms pulse width (50Hz update frequency) based duty cycle, and do not utilize the entire pulse width for their -90/+90 degree control. Typically, 2.5% of the 20ms pulse width (0.5ms) is considered -90 degrees, and 12.5% of the 20ms pulse width (2.5ms) is considered +90 degrees. This roughly translates to raw PCA9685 PWM values of 102 and 512 (out of the 4096 value range) for -90 to +90 degree control, but may need to be adjusted to fit your specific servo (e.g. some I've tested run ~130 to ~525 for their -90/+90 degree control). Also be aware that driving some servos past their -90/+90 degrees of movement can cause a little plastic limiter pin to break off and get stuck inside of the gearing, which could potentially cause the servo to become jammed. See the PCA9685_ServoEvaluator class to assist with calculating PWM values from Servo angle values. - -## Example Usage - -Below are several examples of library usage. - -### Simple Example -```Arduino -#include -#include "PCA9685.h" - -PCA9685 pwmController; // Library using default Wire and default linear phase balancing scheme - -void setup() { - Serial.begin(115200); - - Wire.begin(); // Wire must be started first - Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz - - pwmController.resetDevices(); // Software resets all PCA9685 devices on Wire line - - pwmController.init(B000000); // Address pins A5-A0 set to B000000 - pwmController.setPWMFrequency(100); // Default is 200Hz, supports 24Hz to 1526Hz - - - pwmController.setChannelPWM(0, 128 << 4); // Set PWM to 128/255, but in 4096 land - - Serial.println(pwmController.getChannelPWM(0)); // Should output 2048, which is 128 << 4 -} - -``` - -### Batching Example - -In this example, we randomly select PWM frequencies on all 12 outputs and allow them to drive for 5 seconds before changing them. - -```Arduino -#include -#include "PCA9685.h" - -PCA9685 pwmController; // Library using default Wire and default linear phase balancing scheme - -void setup() { - Wire.begin(); // Wire must be started first - Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz - - pwmController.resetDevices(); // Software resets all PCA9685 devices on Wire line - - pwmController.init(B010101); // Address pins A5-A0 set to B010101 - pwmController.setPWMFrequency(500); // Default is 200Hz, supports 24Hz to 1526Hz - - randomSeed(analogRead(0)); // Use white noise for our randomness -} - -void loop() { - word pwms[12]; - pwms[0] = random(0, 4096); - pwms[1] = random(0, 4096); - pwms[2] = random(0, 4096); - pwms[3] = random(0, 4096); - pwms[4] = random(0, 4096); - pwms[5] = random(0, 4096); - pwms[6] = random(0, 4096); - pwms[7] = random(0, 4096); - pwms[8] = random(0, 4096); - pwms[9] = random(0, 4096); - pwms[10] = random(0, 4096); - pwms[11] = random(0, 4096); - pwmController.setChannelsPWM(0, 12, pwms); - delay(5000); - - // Note: Only 7 channels can be written in one i2c transaction due to a - // BUFFER_LENGTH limit of 32, so 12 channels will take two i2c transactions. -} - -``` - -### Multi-Device Proxy Example - -In this example, we use a special instance to control other modules attached to it via the ALL_CALL register. - -```Arduino -#include -#include "PCA9685.h" - -PCA9685 pwmController1; // Library using default Wire and default linear phase balancing scheme -PCA9685 pwmController2; // Library using default Wire and default linear phase balancing scheme - -PCA9685 pwmControllerAll; // Not a real device, will act as a proxy to pwmController1 and pwmController2 - -void setup() { - Serial.begin(115200); - Wire.begin(); // Wire must be started first - Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz - - pwmController1.resetDevices(); // Software resets all PCA9685 devices on Wire line (including pwmController2 in this case) - - pwmController1.init(B000000); // Address pins A5-A0 set to B000000 - pwmController2.init(B000001); // Address pins A5-A0 set to B000001 - - - pwmController1.setChannelOff(0); // Turn channel 0 off - pwmController2.setChannelOff(0); // On both - - pwmController1.enableAllCallAddress(); // Default address of 0xE0 - pwmController2.enableAllCallAddress(); // Same default address - - pwmControllerAll.initAsProxyAddresser(); // Same default address of 0x0E as used in enable above - - pwmControllerAll.setChannelPWM(0, 4096); // Enables full on on both pwmController1 and pwmController2 - - Serial.println(pwmController1.getChannelPWM(0)); // Should output 4096 - Serial.println(pwmController2.getChannelPWM(0)); // Should also output 4096 - - // Note: Various parts of functionality of the proxy class instance are actually - // disabled - typically anything that involves a read command being issued. -} - -``` - -### Servo Evaluator Example - -In this example, we utilize the ServoEvaluator class to assist with setting PWM frequencies when working with servos. We will be using Wire1, which is only available on boards with SDA1/SCL1 (Due, Zero, etc.) - change to Wire if Wire1 is unavailable. - -```Arduino -#include -#include "PCA9685.h" - -PCA9685 pwmController(Wire1, PCA9685_PhaseBalancer_Weaved); // Library using Wire1 and weaved phase balancing scheme - -// Linearly interpolates between standard 2.5%/12.5% phase length (102/512) for -90°/+90° -PCA9685_ServoEvaluator pwmServo1; - -// Testing our second servo has found that -90° sits at 128, 0° at 324, and +90° at 526. -// Since 324 isn't precisely in the middle, a cubic spline will be used to smoothly -// interpolate PWM values, which will account for said discrepancy. Additionally, since -// 324 is closer to 128 than 526, there is less resolution in the -90° to 0° range, and -// more in the 0° to +90° range. -PCA9685_ServoEvaluator pwmServo2(128,324,526); - -void setup() { - Serial.begin(115200); - - Wire1.begin(); // Wire must be started first - Wire1.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz - - pwmController.resetDevices(); // Software resets all PCA9685 devices on Wire line - - pwmController.init(B000000); // Address pins A5-A0 set to B000000 - pwmController.setPWMFrequency(50); // 50Hz provides 20ms standard servo phase length - - - pwmController.setChannelPWM(0, pwmServo1.pwmForAngle(-90)); - Serial.println(pwmController.getChannelPWM(0)); // Should output 102 for -90° - - // Showing linearity for midpoint, 205 away from both -90° and 90° - Serial.println(pwmServo1.pwmForAngle(0)); // Should output 307 for 0° - - pwmController.setChannelPWM(0, pwmServo1.pwmForAngle(90)); - Serial.println(pwmController.getChannelPWM(0)); // Should output 512 for +90° - - - pwmController.setChannelPWM(1, pwmServo2.pwmForAngle(-90)); - Serial.println(pwmController.getChannelPWM(1)); // Should output 128 for -90° - - // Showing less resolution in the -90° to 0° range - Serial.println(pwmServo2.pwmForAngle(-45)); // Should output 225 for -45°, 97 away from -90° - - pwmController.setChannelPWM(1, pwmServo2.pwmForAngle(0)); - Serial.println(pwmController.getChannelPWM(1)); // Should output 324 for 0° - - // Showing more resolution in the 0° to +90° range - Serial.println(pwmServo2.pwmForAngle(45)); // Should output 424 for +45°, 102 away from +90° - - pwmController.setChannelPWM(1, pwmServo2.pwmForAngle(90)); - Serial.println(pwmController.getChannelPWM(1)); // Should output 526 for +90° -} - -``` - -### Software I2C Example - -In this example, we utilize the software I2C functionality for chips that do not have a hardware I2C bus. We must uncomment the PCA9685_ENABLE_SOFTWARE_I2C define in the libraries main header file for software I2C mode to be enabled. - -In PCA9685.h: -```Arduino -// Uncomment this define to enable use of the software i2c library (min 4MHz+ processor required). -#define PCA9685_ENABLE_SOFTWARE_I2C 1 // http://playground.arduino.cc/Main/SoftwareI2CLibrary -``` - -In main sketch: -```Arduino -#include "PCA9685.h" - +# PCA9685-Arduino +Arduino Library for the PCA9685 16-Channel PWM Driver Module. + +**PCA9685-Arduino - Version 1.2.8** + +Library to control a PCA9685 16-channel PWM driver module from an Arduino board. +Licensed under the copy-left GNU GPL v3 license. + +Created by Kasper Skårhøj, August 3rd, 2012. +Forked by Vitska, June 18th, 2016. +Forked by NachtRaveVL, July 29th, 2016. + +This library allows communication with boards running a PCA6985 16-channel PWM driver module. It supports a wide range of available functionality, from setting the output PWM frequecy, allowing multi-device proxy addressing, and provides an assistant class for working with Servos. + +## Library Setup + +There are several defines inside of the library's header file that allows for more fine-tuned control. + +```Arduino +// Uncomment this define to enable use of the software i2c library (min 4MHz+ processor required). +//#define PCA9685_ENABLE_SOFTWARE_I2C 1 // http://playground.arduino.cc/Main/SoftwareI2CLibrary + +// Uncomment this define if wanting to exclude extended functionality from compilation. +//#define PCA9685_EXCLUDE_EXT_FUNC 1 + +// Uncomment this define if wanting to exclude ServoEvaluator assistant from compilation. +//#define PCA9685_EXCLUDE_SERVO_EVAL 1 + +// Uncomment this define to enable debug output. +//#define PCA9685_ENABLE_DEBUG_OUTPUT 1 +``` + +## Servo Control Note + +Many 180 degree controlled digital servos run on a 20ms pulse width (50Hz update frequency) based duty cycle, and do not utilize the entire pulse width for their -90/+90 degree control. Typically, 2.5% of the 20ms pulse width (0.5ms) is considered -90 degrees, and 12.5% of the 20ms pulse width (2.5ms) is considered +90 degrees. This roughly translates to raw PCA9685 PWM values of 102 and 512 (out of the 4096 value range) for -90 to +90 degree control, but may need to be adjusted to fit your specific servo (e.g. some I've tested run ~130 to ~525 for their -90/+90 degree control). Also be aware that driving some servos past their -90/+90 degrees of movement can cause a little plastic limiter pin to break off and get stuck inside of the gearing, which could potentially cause the servo to become jammed. See the PCA9685_ServoEvaluator class to assist with calculating PWM values from Servo angle values. + +## Example Usage + +Below are several examples of library usage. + +### Simple Example +```Arduino +#include +#include "PCA9685.h" + +PCA9685 pwmController; // Library using default Wire and default linear phase balancing scheme + +void setup() { + Serial.begin(115200); + + Wire.begin(); // Wire must be started first + Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz + + pwmController.resetDevices(); // Software resets all PCA9685 devices on Wire line + + pwmController.init(B000000); // Address pins A5-A0 set to B000000 + pwmController.setPWMFrequency(100); // Default is 200Hz, supports 24Hz to 1526Hz + + + pwmController.setChannelPWM(0, 128 << 4); // Set PWM to 128/255, but in 4096 land + + Serial.println(pwmController.getChannelPWM(0)); // Should output 2048, which is 128 << 4 +} + +``` + +### Batching Example + +In this example, we randomly select PWM frequencies on all 12 outputs and allow them to drive for 5 seconds before changing them. + +```Arduino +#include +#include "PCA9685.h" + +PCA9685 pwmController; // Library using default Wire and default linear phase balancing scheme + +void setup() { + Wire.begin(); // Wire must be started first + Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz + + pwmController.resetDevices(); // Software resets all PCA9685 devices on Wire line + + pwmController.init(B010101); // Address pins A5-A0 set to B010101 + pwmController.setPWMFrequency(500); // Default is 200Hz, supports 24Hz to 1526Hz + + randomSeed(analogRead(0)); // Use white noise for our randomness +} + +void loop() { + word pwms[12]; + pwms[0] = random(0, 4096); + pwms[1] = random(0, 4096); + pwms[2] = random(0, 4096); + pwms[3] = random(0, 4096); + pwms[4] = random(0, 4096); + pwms[5] = random(0, 4096); + pwms[6] = random(0, 4096); + pwms[7] = random(0, 4096); + pwms[8] = random(0, 4096); + pwms[9] = random(0, 4096); + pwms[10] = random(0, 4096); + pwms[11] = random(0, 4096); + pwmController.setChannelsPWM(0, 12, pwms); + delay(5000); + + // Note: Only 7 channels can be written in one i2c transaction due to a + // BUFFER_LENGTH limit of 32, so 12 channels will take two i2c transactions. +} + +``` + +### Multi-Device Proxy Example + +In this example, we use a special instance to control other modules attached to it via the ALL_CALL register. + +```Arduino +#include +#include "PCA9685.h" + +PCA9685 pwmController1; // Library using default Wire and default linear phase balancing scheme +PCA9685 pwmController2; // Library using default Wire and default linear phase balancing scheme + +PCA9685 pwmControllerAll; // Not a real device, will act as a proxy to pwmController1 and pwmController2 + +void setup() { + Serial.begin(115200); + Wire.begin(); // Wire must be started first + Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz + + pwmController1.resetDevices(); // Software resets all PCA9685 devices on Wire line (including pwmController2 in this case) + + pwmController1.init(B000000); // Address pins A5-A0 set to B000000 + pwmController2.init(B000001); // Address pins A5-A0 set to B000001 + + + pwmController1.setChannelOff(0); // Turn channel 0 off + pwmController2.setChannelOff(0); // On both + + pwmController1.enableAllCallAddress(); // Default address of 0xE0 + pwmController2.enableAllCallAddress(); // Same default address + + pwmControllerAll.initAsProxyAddresser(); // Same default address of 0x0E as used in enable above + + pwmControllerAll.setChannelPWM(0, 4096); // Enables full on on both pwmController1 and pwmController2 + + Serial.println(pwmController1.getChannelPWM(0)); // Should output 4096 + Serial.println(pwmController2.getChannelPWM(0)); // Should also output 4096 + + // Note: Various parts of functionality of the proxy class instance are actually + // disabled - typically anything that involves a read command being issued. +} + +``` + +### Servo Evaluator Example + +In this example, we utilize the ServoEvaluator class to assist with setting PWM frequencies when working with servos. We will be using Wire1, which is only available on boards with SDA1/SCL1 (Due, Zero, etc.) - change to Wire if Wire1 is unavailable. + +```Arduino +#include +#include "PCA9685.h" + +PCA9685 pwmController(Wire1, PCA9685_PhaseBalancer_Weaved); // Library using Wire1 and weaved phase balancing scheme + +// Linearly interpolates between standard 2.5%/12.5% phase length (102/512) for -90°/+90° +PCA9685_ServoEvaluator pwmServo1; + +// Testing our second servo has found that -90° sits at 128, 0° at 324, and +90° at 526. +// Since 324 isn't precisely in the middle, a cubic spline will be used to smoothly +// interpolate PWM values, which will account for said discrepancy. Additionally, since +// 324 is closer to 128 than 526, there is less resolution in the -90° to 0° range, and +// more in the 0° to +90° range. +PCA9685_ServoEvaluator pwmServo2(128,324,526); + +void setup() { + Serial.begin(115200); + + Wire1.begin(); // Wire must be started first + Wire1.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz + + pwmController.resetDevices(); // Software resets all PCA9685 devices on Wire line + + pwmController.init(B000000); // Address pins A5-A0 set to B000000 + pwmController.setPWMFrequency(50); // 50Hz provides 20ms standard servo phase length + + + pwmController.setChannelPWM(0, pwmServo1.pwmForAngle(-90)); + Serial.println(pwmController.getChannelPWM(0)); // Should output 102 for -90° + + // Showing linearity for midpoint, 205 away from both -90° and 90° + Serial.println(pwmServo1.pwmForAngle(0)); // Should output 307 for 0° + + pwmController.setChannelPWM(0, pwmServo1.pwmForAngle(90)); + Serial.println(pwmController.getChannelPWM(0)); // Should output 512 for +90° + + + pwmController.setChannelPWM(1, pwmServo2.pwmForAngle(-90)); + Serial.println(pwmController.getChannelPWM(1)); // Should output 128 for -90° + + // Showing less resolution in the -90° to 0° range + Serial.println(pwmServo2.pwmForAngle(-45)); // Should output 225 for -45°, 97 away from -90° + + pwmController.setChannelPWM(1, pwmServo2.pwmForAngle(0)); + Serial.println(pwmController.getChannelPWM(1)); // Should output 324 for 0° + + // Showing more resolution in the 0° to +90° range + Serial.println(pwmServo2.pwmForAngle(45)); // Should output 424 for +45°, 102 away from +90° + + pwmController.setChannelPWM(1, pwmServo2.pwmForAngle(90)); + Serial.println(pwmController.getChannelPWM(1)); // Should output 526 for +90° +} + +``` + +### Software I2C Example + +In this example, we utilize the software I2C functionality for chips that do not have a hardware I2C bus. We must uncomment the PCA9685_ENABLE_SOFTWARE_I2C define in the libraries main header file for software I2C mode to be enabled. + +In PCA9685.h: +```Arduino +// Uncomment this define to enable use of the software i2c library (min 4MHz+ processor required). +#define PCA9685_ENABLE_SOFTWARE_I2C 1 // http://playground.arduino.cc/Main/SoftwareI2CLibrary +``` + +In main sketch: +```Arduino +#include "PCA9685.h" + #define SCL_PIN 2 // Setup defines are written before library include #define SCL_PORT PORTD #define SDA_PIN 0 @@ -235,45 +235,45 @@ In main sketch: #define I2C_FASTMODE 1 // Running a 16MHz processor allows us to use I2C fast mode #endif -#include "SoftI2CMaster.h" // Include must come after setup defines - -PCA9685 pwmController; // Library using default linear phase balancing scheme - -void setup() { - i2c_init(); // Software I2C must be started first - - pwmController.resetDevices(); // Software resets all PCA9685 devices on software I2C line - - pwmController.init(B000000); // Address pins A5-A0 set to B000000 - - pwmController.setChannelPWM(0, 2048); // Should see a 50% duty cycle along the 5ms phase width -} - -``` - -## Module Info - -If one uncomments the PCA9685_ENABLE_DEBUG_OUTPUT define in the libraries main header file (thus enabling debug output) the printModuleInfo() method becomes available, which will display information about the module itself, including initalized states, register values, current settings, etc. All calls being made will display internal debug information about the structure of the call itself. An example of this output is shown here: - -In PCA9685.h: -```Arduino +#include "SoftI2CMaster.h" // Include must come after setup defines + +PCA9685 pwmController; // Library using default linear phase balancing scheme + +void setup() { + i2c_init(); // Software I2C must be started first + + pwmController.resetDevices(); // Software resets all PCA9685 devices on software I2C line + + pwmController.init(B000000); // Address pins A5-A0 set to B000000 + + pwmController.setChannelPWM(0, 2048); // Should see a 50% duty cycle along the 5ms phase width +} + +``` + +## Module Info + +If one uncomments the PCA9685_ENABLE_DEBUG_OUTPUT define in the libraries main header file (thus enabling debug output) the printModuleInfo() method becomes available, which will display information about the module itself, including initalized states, register values, current settings, etc. All calls being made will display internal debug information about the structure of the call itself. An example of this output is shown here: + +In PCA9685.h: +```Arduino // Uncomment this define to enable debug output. -#define PCA9685_ENABLE_DEBUG_OUTPUT 1 -``` - -In main sketch: -```Arduino -PCA9685 pwmController; - -void setup() { - // ... - - pwmController.printModuleInfo(); -} -``` - -In serial monitor: -``` +#define PCA9685_ENABLE_DEBUG_OUTPUT 1 +``` + +In main sketch: +```Arduino +PCA9685 pwmController; + +void setup() { + // ... + + pwmController.printModuleInfo(); +} +``` + +In serial monitor: +``` ~~~ PCA9685 Module Info ~~~ i2c Address: @@ -313,5 +313,6 @@ SubAddress3 Register: AllCall Register: PCA9685::readRegister regAddress: 0x5 PCA9685::readRegister retVal: 0xE0 -0xE0 +0xE0 + ``` diff --git a/library.properties b/library.properties index 06418b0..cccf80d 100644 --- a/library.properties +++ b/library.properties @@ -1,5 +1,5 @@ name=PCA9685 16-Channel PWM Driver Module Library -version=1.2.7 +version=1.2.8 author=NachtRaveVL , Vitska, Kasper Skårhøj maintainer=NachtRaveVL sentence=Library to control a PCA9685 16-channel PWM driver module from an Arduino board. From e68dff2a7548f6d00884082a25aa397b020e3448 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Sun, 19 Mar 2017 18:27:37 -0700 Subject: [PATCH 30/57] Updating example code. Adding example code into examples folder by request. --- README.md | 20 ++++--- examples/BatchingExample/BatchingExample.ino | 42 +++++++++++++++ examples/ModuleInfo/ModuleInfo.ino | 19 +++++++ .../MultiDeviceProxyExample.ino | 38 +++++++++++++ .../ServoEvaluatorExample.ino | 53 +++++++++++++++++++ examples/SimpleExample/SimpleExample.ino | 22 ++++++++ .../SoftwareI2CExample/SoftwareI2CExample.ino | 32 +++++++++++ 7 files changed, 220 insertions(+), 6 deletions(-) create mode 100644 examples/BatchingExample/BatchingExample.ino create mode 100644 examples/ModuleInfo/ModuleInfo.ino create mode 100644 examples/MultiDeviceProxyExample/MultiDeviceProxyExample.ino create mode 100644 examples/ServoEvaluatorExample/ServoEvaluatorExample.ino create mode 100644 examples/SimpleExample/SimpleExample.ino create mode 100644 examples/SoftwareI2CExample/SoftwareI2CExample.ino diff --git a/README.md b/README.md index 370d35c..a531e02 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,6 @@ void setup() { pwmController.init(B000000); // Address pins A5-A0 set to B000000 pwmController.setPWMFrequency(100); // Default is 200Hz, supports 24Hz to 1526Hz - pwmController.setChannelPWM(0, 128 << 4); // Set PWM to 128/255, but in 4096 land Serial.println(pwmController.getChannelPWM(0)); // Should output 2048, which is 128 << 4 @@ -75,6 +74,8 @@ In this example, we randomly select PWM frequencies on all 12 outputs and allow PCA9685 pwmController; // Library using default Wire and default linear phase balancing scheme void setup() { + Serial.begin(115200); + Wire.begin(); // Wire must be started first Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz @@ -124,6 +125,7 @@ PCA9685 pwmControllerAll; // Not a real device, will act as a prox void setup() { Serial.begin(115200); + Wire.begin(); // Wire must be started first Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz @@ -132,7 +134,6 @@ void setup() { pwmController1.init(B000000); // Address pins A5-A0 set to B000000 pwmController2.init(B000001); // Address pins A5-A0 set to B000001 - pwmController1.setChannelOff(0); // Turn channel 0 off pwmController2.setChannelOff(0); // On both @@ -182,7 +183,6 @@ void setup() { pwmController.init(B000000); // Address pins A5-A0 set to B000000 pwmController.setPWMFrequency(50); // 50Hz provides 20ms standard servo phase length - pwmController.setChannelPWM(0, pwmServo1.pwmForAngle(-90)); Serial.println(pwmController.getChannelPWM(0)); // Should output 102 for -90° @@ -193,10 +193,9 @@ void setup() { pwmController.setChannelPWM(0, pwmServo1.pwmForAngle(90)); Serial.println(pwmController.getChannelPWM(0)); // Should output 512 for +90° - pwmController.setChannelPWM(1, pwmServo2.pwmForAngle(-90)); Serial.println(pwmController.getChannelPWM(1)); // Should output 128 for -90° - + // Showing less resolution in the -90° to 0° range Serial.println(pwmServo2.pwmForAngle(-45)); // Should output 225 for -45°, 97 away from -90° @@ -240,6 +239,8 @@ In main sketch: PCA9685 pwmController; // Library using default linear phase balancing scheme void setup() { + Serial.begin(115200); + i2c_init(); // Software I2C must be started first pwmController.resetDevices(); // Software resets all PCA9685 devices on software I2C line @@ -263,13 +264,20 @@ In PCA9685.h: In main sketch: ```Arduino +#include +#include "PCA9685.h" + PCA9685 pwmController; void setup() { - // ... + Serial.begin(115200); + + Wire.begin(); // Wire must be started first + Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz pwmController.printModuleInfo(); } + ``` In serial monitor: diff --git a/examples/BatchingExample/BatchingExample.ino b/examples/BatchingExample/BatchingExample.ino new file mode 100644 index 0000000..1d1c32f --- /dev/null +++ b/examples/BatchingExample/BatchingExample.ino @@ -0,0 +1,42 @@ +// PCA9685-Arduino Batching Example +// In this example, we randomly select PWM frequencies on all 12 outputs and allow them to drive for 5 seconds before changing them. + +#include +#include "PCA9685.h" + +PCA9685 pwmController; // Library using default Wire and default linear phase balancing scheme + +void setup() { + Serial.begin(115200); + + Wire.begin(); // Wire must be started first + Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz + + pwmController.resetDevices(); // Software resets all PCA9685 devices on Wire line + + pwmController.init(B010101); // Address pins A5-A0 set to B010101 + pwmController.setPWMFrequency(500); // Default is 200Hz, supports 24Hz to 1526Hz + + randomSeed(analogRead(0)); // Use white noise for our randomness +} + +void loop() { + word pwms[12]; + pwms[0] = random(0, 4096); + pwms[1] = random(0, 4096); + pwms[2] = random(0, 4096); + pwms[3] = random(0, 4096); + pwms[4] = random(0, 4096); + pwms[5] = random(0, 4096); + pwms[6] = random(0, 4096); + pwms[7] = random(0, 4096); + pwms[8] = random(0, 4096); + pwms[9] = random(0, 4096); + pwms[10] = random(0, 4096); + pwms[11] = random(0, 4096); + pwmController.setChannelsPWM(0, 12, pwms); + delay(5000); + + // Note: Only 7 channels can be written in one i2c transaction due to a + // BUFFER_LENGTH limit of 32, so 12 channels will take two i2c transactions. +} diff --git a/examples/ModuleInfo/ModuleInfo.ino b/examples/ModuleInfo/ModuleInfo.ino new file mode 100644 index 0000000..68be1f6 --- /dev/null +++ b/examples/ModuleInfo/ModuleInfo.ino @@ -0,0 +1,19 @@ +// PCA9685-Arduino Module Info +// If one uncomments the PCA9685_ENABLE_DEBUG_OUTPUT define in the libraries main header file (thus enabling debug output) the printModuleInfo() method becomes available, which will display information about the module itself, including initalized states, register values, current settings, etc. All calls being made will display internal debug information about the structure of the call itself. + +// Uncomment this define to enable debug output. +#define PCA9685_ENABLE_DEBUG_OUTPUT 1 + +#include +#include "PCA9685.h" + +PCA9685 pwmController; + +void setup() { + Serial.begin(115200); + + Wire.begin(); // Wire must be started first + Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz + + pwmController.printModuleInfo(); +} diff --git a/examples/MultiDeviceProxyExample/MultiDeviceProxyExample.ino b/examples/MultiDeviceProxyExample/MultiDeviceProxyExample.ino new file mode 100644 index 0000000..708af43 --- /dev/null +++ b/examples/MultiDeviceProxyExample/MultiDeviceProxyExample.ino @@ -0,0 +1,38 @@ +// PCA9685-Arduino Multi-Device Proxy Example +// In this example, we use a special instance to control other modules attached to it via the ALL_CALL register. + +#include +#include "PCA9685.h" + +PCA9685 pwmController1; // Library using default Wire and default linear phase balancing scheme +PCA9685 pwmController2; // Library using default Wire and default linear phase balancing scheme + +PCA9685 pwmControllerAll; // Not a real device, will act as a proxy to pwmController1 and pwmController2 + +void setup() { + Serial.begin(115200); + + Wire.begin(); // Wire must be started first + Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz + + pwmController1.resetDevices(); // Software resets all PCA9685 devices on Wire line (including pwmController2 in this case) + + pwmController1.init(B000000); // Address pins A5-A0 set to B000000 + pwmController2.init(B000001); // Address pins A5-A0 set to B000001 + + pwmController1.setChannelOff(0); // Turn channel 0 off + pwmController2.setChannelOff(0); // On both + + pwmController1.enableAllCallAddress(); // Default address of 0xE0 + pwmController2.enableAllCallAddress(); // Same default address + + pwmControllerAll.initAsProxyAddresser(); // Same default address of 0x0E as used in enable above + + pwmControllerAll.setChannelPWM(0, 4096); // Enables full on on both pwmController1 and pwmController2 + + Serial.println(pwmController1.getChannelPWM(0)); // Should output 4096 + Serial.println(pwmController2.getChannelPWM(0)); // Should also output 4096 + + // Note: Various parts of functionality of the proxy class instance are actually + // disabled - typically anything that involves a read command being issued. +} diff --git a/examples/ServoEvaluatorExample/ServoEvaluatorExample.ino b/examples/ServoEvaluatorExample/ServoEvaluatorExample.ino new file mode 100644 index 0000000..3909e7a --- /dev/null +++ b/examples/ServoEvaluatorExample/ServoEvaluatorExample.ino @@ -0,0 +1,53 @@ +// PCA9685-Arduino Servo Evaluator Example +// In this example, we utilize the ServoEvaluator class to assist with setting PWM frequencies when working with servos. We will be using Wire1, which is only available on boards with SDA1/SCL1 (Due, Zero, etc.) - change to Wire if Wire1 is unavailable. + +#include +#include "PCA9685.h" + +PCA9685 pwmController(Wire1, PCA9685_PhaseBalancer_Weaved); // Library using Wire1 and weaved phase balancing scheme + +// Linearly interpolates between standard 2.5%/12.5% phase length (102/512) for -90°/+90° +PCA9685_ServoEvaluator pwmServo1; + +// Testing our second servo has found that -90° sits at 128, 0° at 324, and +90° at 526. +// Since 324 isn't precisely in the middle, a cubic spline will be used to smoothly +// interpolate PWM values, which will account for said discrepancy. Additionally, since +// 324 is closer to 128 than 526, there is less resolution in the -90° to 0° range, and +// more in the 0° to +90° range. +PCA9685_ServoEvaluator pwmServo2(128,324,526); + +void setup() { + Serial.begin(115200); + + Wire1.begin(); // Wire must be started first + Wire1.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz + + pwmController.resetDevices(); // Software resets all PCA9685 devices on Wire line + + pwmController.init(B000000); // Address pins A5-A0 set to B000000 + pwmController.setPWMFrequency(50); // 50Hz provides 20ms standard servo phase length + + pwmController.setChannelPWM(0, pwmServo1.pwmForAngle(-90)); + Serial.println(pwmController.getChannelPWM(0)); // Should output 102 for -90° + + // Showing linearity for midpoint, 205 away from both -90° and 90° + Serial.println(pwmServo1.pwmForAngle(0)); // Should output 307 for 0° + + pwmController.setChannelPWM(0, pwmServo1.pwmForAngle(90)); + Serial.println(pwmController.getChannelPWM(0)); // Should output 512 for +90° + + pwmController.setChannelPWM(1, pwmServo2.pwmForAngle(-90)); + Serial.println(pwmController.getChannelPWM(1)); // Should output 128 for -90° + + // Showing less resolution in the -90° to 0° range + Serial.println(pwmServo2.pwmForAngle(-45)); // Should output 225 for -45°, 97 away from -90° + + pwmController.setChannelPWM(1, pwmServo2.pwmForAngle(0)); + Serial.println(pwmController.getChannelPWM(1)); // Should output 324 for 0° + + // Showing more resolution in the 0° to +90° range + Serial.println(pwmServo2.pwmForAngle(45)); // Should output 424 for +45°, 102 away from +90° + + pwmController.setChannelPWM(1, pwmServo2.pwmForAngle(90)); + Serial.println(pwmController.getChannelPWM(1)); // Should output 526 for +90° +} diff --git a/examples/SimpleExample/SimpleExample.ino b/examples/SimpleExample/SimpleExample.ino new file mode 100644 index 0000000..a46c73b --- /dev/null +++ b/examples/SimpleExample/SimpleExample.ino @@ -0,0 +1,22 @@ +// PCA9685-Arduino Simple Example + +#include +#include "PCA9685.h" + +PCA9685 pwmController; // Library using default Wire and default linear phase balancing scheme + +void setup() { + Serial.begin(115200); + + Wire.begin(); // Wire must be started first + Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz + + pwmController.resetDevices(); // Software resets all PCA9685 devices on Wire line + + pwmController.init(B000000); // Address pins A5-A0 set to B000000 + pwmController.setPWMFrequency(100); // Default is 200Hz, supports 24Hz to 1526Hz + + pwmController.setChannelPWM(0, 128 << 4); // Set PWM to 128/255, but in 4096 land + + Serial.println(pwmController.getChannelPWM(0)); // Should output 2048, which is 128 << 4 +} diff --git a/examples/SoftwareI2CExample/SoftwareI2CExample.ino b/examples/SoftwareI2CExample/SoftwareI2CExample.ino new file mode 100644 index 0000000..8c52712 --- /dev/null +++ b/examples/SoftwareI2CExample/SoftwareI2CExample.ino @@ -0,0 +1,32 @@ +// PCA9685-Arduino Software I2C Example +// In this example, we utilize the software I2C functionality for chips that do not have a hardware I2C bus. We must uncomment the PCA9685_ENABLE_SOFTWARE_I2C define in the libraries main header file for software I2C mode to be enabled. + +// Uncomment this define to enable use of the software i2c library (min 4MHz+ processor required). +#define PCA9685_ENABLE_SOFTWARE_I2C 1 // http://playground.arduino.cc/Main/SoftwareI2CLibrary + +#include "PCA9685.h" + +#define SCL_PIN 2 // Setup defines are written before library include +#define SCL_PORT PORTD +#define SDA_PIN 0 +#define SDA_PORT PORTC + +#if F_CPU >= 16000000 +#define I2C_FASTMODE 1 // Running a 16MHz processor allows us to use I2C fast mode +#endif + +#include "SoftI2CMaster.h" // Include must come after setup defines + +PCA9685 pwmController; // Library using default linear phase balancing scheme + +void setup() { + Serial.begin(115200); + + i2c_init(); // Software I2C must be started first + + pwmController.resetDevices(); // Software resets all PCA9685 devices on software I2C line + + pwmController.init(B000000); // Address pins A5-A0 set to B000000 + + pwmController.setChannelPWM(0, 2048); // Should see a 50% duty cycle along the 5ms phase width +} From f668b2596e218005007279f9d597bd956060cb1c Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Sun, 19 Mar 2017 18:47:33 -0700 Subject: [PATCH 31/57] Multi-lining comments. --- examples/BatchingExample/BatchingExample.ino | 3 ++- examples/ModuleInfo/ModuleInfo.ino | 6 +++++- .../MultiDeviceProxyExample/MultiDeviceProxyExample.ino | 3 ++- examples/ServoEvaluatorExample/ServoEvaluatorExample.ino | 4 +++- examples/SoftwareI2CExample/SoftwareI2CExample.ino | 4 +++- 5 files changed, 15 insertions(+), 5 deletions(-) diff --git a/examples/BatchingExample/BatchingExample.ino b/examples/BatchingExample/BatchingExample.ino index 1d1c32f..9366c65 100644 --- a/examples/BatchingExample/BatchingExample.ino +++ b/examples/BatchingExample/BatchingExample.ino @@ -1,5 +1,6 @@ // PCA9685-Arduino Batching Example -// In this example, we randomly select PWM frequencies on all 12 outputs and allow them to drive for 5 seconds before changing them. +// In this example, we randomly select PWM frequencies on all 12 outputs and allow them +// to drive for 5 seconds before changing them. #include #include "PCA9685.h" diff --git a/examples/ModuleInfo/ModuleInfo.ino b/examples/ModuleInfo/ModuleInfo.ino index 68be1f6..48d537d 100644 --- a/examples/ModuleInfo/ModuleInfo.ino +++ b/examples/ModuleInfo/ModuleInfo.ino @@ -1,5 +1,9 @@ // PCA9685-Arduino Module Info -// If one uncomments the PCA9685_ENABLE_DEBUG_OUTPUT define in the libraries main header file (thus enabling debug output) the printModuleInfo() method becomes available, which will display information about the module itself, including initalized states, register values, current settings, etc. All calls being made will display internal debug information about the structure of the call itself. +// If one uncomments the PCA9685_ENABLE_DEBUG_OUTPUT define in the libraries main header +// file (thus enabling debug output) the printModuleInfo() method becomes available, +// which will display information about the module itself, including initalized states, +// register values, current settings, etc. All calls being made will display internal +// debug information about the structure of the call itself. // Uncomment this define to enable debug output. #define PCA9685_ENABLE_DEBUG_OUTPUT 1 diff --git a/examples/MultiDeviceProxyExample/MultiDeviceProxyExample.ino b/examples/MultiDeviceProxyExample/MultiDeviceProxyExample.ino index 708af43..04c5cb0 100644 --- a/examples/MultiDeviceProxyExample/MultiDeviceProxyExample.ino +++ b/examples/MultiDeviceProxyExample/MultiDeviceProxyExample.ino @@ -1,5 +1,6 @@ // PCA9685-Arduino Multi-Device Proxy Example -// In this example, we use a special instance to control other modules attached to it via the ALL_CALL register. +// In this example, we use a special instance to control other modules attached to it via +// the ALL_CALL register. #include #include "PCA9685.h" diff --git a/examples/ServoEvaluatorExample/ServoEvaluatorExample.ino b/examples/ServoEvaluatorExample/ServoEvaluatorExample.ino index 3909e7a..a70b1be 100644 --- a/examples/ServoEvaluatorExample/ServoEvaluatorExample.ino +++ b/examples/ServoEvaluatorExample/ServoEvaluatorExample.ino @@ -1,5 +1,7 @@ // PCA9685-Arduino Servo Evaluator Example -// In this example, we utilize the ServoEvaluator class to assist with setting PWM frequencies when working with servos. We will be using Wire1, which is only available on boards with SDA1/SCL1 (Due, Zero, etc.) - change to Wire if Wire1 is unavailable. +// In this example, we utilize the ServoEvaluator class to assist with setting PWM +// frequencies when working with servos. We will be using Wire1, which is only available +// on boards with SDA1/SCL1 (Due, Zero, etc.) - change to Wire if Wire1 is unavailable. #include #include "PCA9685.h" diff --git a/examples/SoftwareI2CExample/SoftwareI2CExample.ino b/examples/SoftwareI2CExample/SoftwareI2CExample.ino index 8c52712..f0772ba 100644 --- a/examples/SoftwareI2CExample/SoftwareI2CExample.ino +++ b/examples/SoftwareI2CExample/SoftwareI2CExample.ino @@ -1,5 +1,7 @@ // PCA9685-Arduino Software I2C Example -// In this example, we utilize the software I2C functionality for chips that do not have a hardware I2C bus. We must uncomment the PCA9685_ENABLE_SOFTWARE_I2C define in the libraries main header file for software I2C mode to be enabled. +// In this example, we utilize the software I2C functionality for chips that do not have +// a hardware I2C bus. We must uncomment the PCA9685_ENABLE_SOFTWARE_I2C define in the +// libraries main header file for software I2C mode to be enabled. // Uncomment this define to enable use of the software i2c library (min 4MHz+ processor required). #define PCA9685_ENABLE_SOFTWARE_I2C 1 // http://playground.arduino.cc/Main/SoftwareI2CLibrary From 04dd168cc165948e62fed53292996ed84e2468ae Mon Sep 17 00:00:00 2001 From: Dominik Auras Date: Mon, 27 Mar 2017 14:41:52 +0200 Subject: [PATCH 32/57] Bugfix I2C address Arduino TWI library expects 7 bit addresses. The TWI library wrapped by the Wire library performs the address shift and adds the r/w bit to the address. See here https://github.com/esp8266/Arduino/blob/master/cores/esp8266/core_esp8266_si2c.c#L184 " if(!twi_write_byte(((address << 1) | 0) & 0xFF)) {" and "if(!twi_write_byte(((address << 1) | 1) & 0xFF)) {". Confirmed with three chained PCA9685 boards connected a NodeMCU. --- PCA9685.cpp | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/PCA9685.cpp b/PCA9685.cpp index f916691..8105a26 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -87,8 +87,9 @@ void PCA9685::resetDevices() { void PCA9685::init(byte i2cAddress, byte mode) { if (_isProxyAddresser) return; - // I2C address is B 1 A5 A4 A3 A2 A1 A0 {W=0, R=1} - _i2cAddress = PCA9685_I2C_BASE_ADDRESS | ((i2cAddress & 0x3F) << 1); + // I2C 7-bit address is B 1 A5 A4 A3 A2 A1 A0 + // RW bit added by Arduino core TWI library + _i2cAddress = PCA9685_I2C_BASE_ADDRESS | (i2cAddress & 0x3F); #ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print("PCA9685::init i2cAddress: 0x"); From 3d938d2fddd73cb22ea6addc847c0fac726c6c9c Mon Sep 17 00:00:00 2001 From: Dominik Auras Date: Mon, 27 Mar 2017 17:11:15 +0200 Subject: [PATCH 33/57] utf8 change to utf8 --- library.properties | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/library.properties b/library.properties index cccf80d..749d130 100644 --- a/library.properties +++ b/library.properties @@ -1,9 +1,10 @@ name=PCA9685 16-Channel PWM Driver Module Library version=1.2.8 -author=NachtRaveVL , Vitska, Kasper Skårhøj +author=NachtRaveVL , Vitska, Kasper SkÃ¥rhøj maintainer=NachtRaveVL sentence=Library to control a PCA9685 16-channel PWM driver module from an Arduino board. paragraph=This library allows communication with boards running a PCA6985 16-channel PWM driver module. It supports a wide range of available functionality, from setting the output PWM frequecy, allowing multi-device proxy addressing, and provides an assistant class for working with Servos. category=Device Control url=https://github.com/NachtRaveVL/PCA9685-Arduino architectures=* + From b7a6e6d942d8dfb90eb5e418e44f1dc84b73660d Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Mon, 27 Mar 2017 21:45:24 -0700 Subject: [PATCH 34/57] Upping to 1.2.9. --- PCA9685.cpp | 2 +- PCA9685.h | 2 +- README.md | 2 +- library.properties | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/PCA9685.cpp b/PCA9685.cpp index 8105a26..6332395 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -19,7 +19,7 @@ Forked by Vitska, June 18th, 2016. Forked by NachtRaveVL, July 29th, 2016. - PCA9685-Arduino - Version 1.2.8 + PCA9685-Arduino - Version 1.2.9 */ #include "PCA9685.h" diff --git a/PCA9685.h b/PCA9685.h index 764da47..ef16152 100644 --- a/PCA9685.h +++ b/PCA9685.h @@ -19,7 +19,7 @@ Forked by Vitska, June 18th, 2016. Forked by NachtRaveVL, July 29th, 2016. - PCA9685-Arduino - Version 1.2.8 + PCA9685-Arduino - Version 1.2.9 */ #ifndef PCA9685_H diff --git a/README.md b/README.md index a531e02..6ba378b 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # PCA9685-Arduino Arduino Library for the PCA9685 16-Channel PWM Driver Module. -**PCA9685-Arduino - Version 1.2.8** +**PCA9685-Arduino - Version 1.2.9** Library to control a PCA9685 16-channel PWM driver module from an Arduino board. Licensed under the copy-left GNU GPL v3 license. diff --git a/library.properties b/library.properties index 749d130..715ce5d 100644 --- a/library.properties +++ b/library.properties @@ -1,5 +1,5 @@ name=PCA9685 16-Channel PWM Driver Module Library -version=1.2.8 +version=1.2.9 author=NachtRaveVL , Vitska, Kasper SkÃ¥rhøj maintainer=NachtRaveVL sentence=Library to control a PCA9685 16-channel PWM driver module from an Arduino board. From 83d0525f0fd1035e88574690c8b817e7b640eac1 Mon Sep 17 00:00:00 2001 From: James Myatt Date: Mon, 10 Apr 2017 20:37:37 +0100 Subject: [PATCH 35/57] Fix full ON and full OFF phase calculations based on datasheet section 7.3.3 (#3) --- PCA9685.cpp | 52 ++++++++++++++++++++++++++++++++++------------------ 1 file changed, 34 insertions(+), 18 deletions(-) diff --git a/PCA9685.cpp b/PCA9685.cpp index 6332395..1dcfa18 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -156,7 +156,7 @@ void PCA9685::setChannelOn(int channel) { #endif writeChannelBegin(channel); - writeChannelPWM(0, PCA9685_PWM_FULL); + writeChannelPWM(PCA9685_PWM_FULL, 0); // time_on = FULL; time_off = 0; writeChannelEnd(); } @@ -168,7 +168,7 @@ void PCA9685::setChannelOff(int channel) { #endif writeChannelBegin(channel); - writeChannelPWM(PCA9685_PWM_FULL, 0); + writeChannelPWM(0, PCA9685_PWM_FULL); // time_on = 0; time_off = FULL; writeChannelEnd(); } @@ -229,7 +229,7 @@ void PCA9685::setAllChannelsPWM(uint16_t pwmAmount) { writeChannelBegin(-1); // Special value for ALLLED registers uint16_t phaseBegin, phaseEnd; - getPhaseCycle(0, pwmAmount, &phaseBegin, &phaseEnd); + getPhaseCycle(-1, pwmAmount, &phaseBegin, &phaseEnd); writeChannelPWM(phaseBegin, phaseEnd); @@ -280,14 +280,24 @@ uint16_t PCA9685::getChannelPWM(int channel) { Serial.println(phaseEnd); #endif + // See datasheet section 7.3.3 uint16_t retVal; - if (phaseBegin == PCA9685_PWM_FULL && phaseEnd == 0) + if (phaseEnd >= PCA9685_PWM_FULL) + // Full OFF + // Figure 11 Example 4: full OFF takes precedence over full ON + // See also remark after Table 7 retVal = 0; - else if (phaseBegin == 0 && phaseEnd == PCA9685_PWM_FULL) + else if (phaseBegin >= PCA9685_PWM_FULL) + // Full ON + // Figure 9 Example 3 retVal = PCA9685_PWM_FULL; else if (phaseBegin <= phaseEnd) + // start and finish in same cycle + // Section 7.3.3 example 1 retVal = phaseEnd - phaseBegin; else + // span cycles + // Section 7.3.3 example 2 retVal = (phaseEnd + PCA9685_PWM_FULL) - phaseBegin; #ifdef PCA9685_ENABLE_DEBUG_OUTPUT @@ -456,31 +466,37 @@ void PCA9685::checkForErrors() { #endif void PCA9685::getPhaseCycle(int channel, uint16_t pwmAmount, uint16_t *phaseBegin, uint16_t *phaseEnd) { - if (pwmAmount == 0) { - *phaseBegin = PCA9685_PWM_FULL; - *phaseEnd = 0; - } - else if (pwmAmount >= PCA9685_PWM_FULL - 1) { + // Set delay + if (channel < 0) { + // All channels *phaseBegin = 0; - *phaseEnd = PCA9685_PWM_FULL; } else if (_phaseBalancer == PCA9685_PhaseBalancer_Linear) { // Distribute high phase area over entire phase range to balance load. *phaseBegin = channel * (4096 / 16); - *phaseEnd = *phaseBegin + pwmAmount; - if (*phaseEnd >= PCA9685_PWM_FULL) - *phaseEnd -= PCA9685_PWM_FULL; } else if (_phaseBalancer == PCA9685_PhaseBalancer_Weaved) { // Distribute high phase area over entire phase range to balance load. *phaseBegin = phaseDistTable[channel]; - *phaseEnd = *phaseBegin + pwmAmount; - if (*phaseEnd >= PCA9685_PWM_FULL) - *phaseEnd -= PCA9685_PWM_FULL; } else { *phaseBegin = 0; - *phaseEnd = pwmAmount; + } + + // See datasheet section 7.3.3 + if (pwmAmount == 0) { + // Full OFF => time_off[12] = 1; + *phaseEnd = PCA9685_PWM_FULL; + } + else if (pwmAmount >= PCA9685_PWM_FULL) { + // Full ON => time_on[12] = 1; time_off = ignored; + *phaseBegin |= PCA9685_PWM_FULL; + *phaseEnd = 0; + } + else { + *phaseEnd = *phaseBegin + pwmAmount; + if (*phaseEnd >= PCA9685_PWM_FULL) + *phaseEnd -= PCA9685_PWM_FULL; } } From 96538fea65f4d7d97728e168513d64520ec673c6 Mon Sep 17 00:00:00 2001 From: James Myatt Date: Mon, 10 Apr 2017 20:38:06 +0100 Subject: [PATCH 36/57] Replace outdated datasheet with link to latest version (#4) --- README.md | 2 ++ support files/PCA9685 datasheet.pdf | Bin 245482 -> 0 bytes 2 files changed, 2 insertions(+) delete mode 100644 support files/PCA9685 datasheet.pdf diff --git a/README.md b/README.md index 6ba378b..74f4d2b 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,8 @@ Forked by NachtRaveVL, July 29th, 2016. This library allows communication with boards running a PCA6985 16-channel PWM driver module. It supports a wide range of available functionality, from setting the output PWM frequecy, allowing multi-device proxy addressing, and provides an assistant class for working with Servos. +The datasheet for the IC is available from . + ## Library Setup There are several defines inside of the library's header file that allows for more fine-tuned control. diff --git a/support files/PCA9685 datasheet.pdf b/support files/PCA9685 datasheet.pdf deleted file mode 100644 index 4e16abf2c8532629955baa65ff9f92e6a39b27f5..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 245482 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

-jy@oI_Bo`~CQ15v+V{n!DK|Jn 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�ws@LMR-h)P&_HceNqfVmzE1n`~>Bx@3-T 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

tL;CqPrJ``(z$@STLK&i7&7?OK#Lj#I~A1{)e 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�+e{24K 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 Date: Thu, 25 May 2017 15:57:02 -0700 Subject: [PATCH 37/57] Ensuring all examples have a void loop(). --- examples/ModuleInfo/ModuleInfo.ino | 3 +++ examples/MultiDeviceProxyExample/MultiDeviceProxyExample.ino | 3 +++ examples/ServoEvaluatorExample/ServoEvaluatorExample.ino | 3 +++ examples/SimpleExample/SimpleExample.ino | 3 +++ examples/SoftwareI2CExample/SoftwareI2CExample.ino | 3 +++ 5 files changed, 15 insertions(+) diff --git a/examples/ModuleInfo/ModuleInfo.ino b/examples/ModuleInfo/ModuleInfo.ino index 48d537d..6887a37 100644 --- a/examples/ModuleInfo/ModuleInfo.ino +++ b/examples/ModuleInfo/ModuleInfo.ino @@ -21,3 +21,6 @@ void setup() { pwmController.printModuleInfo(); } + +void loop() { +} diff --git a/examples/MultiDeviceProxyExample/MultiDeviceProxyExample.ino b/examples/MultiDeviceProxyExample/MultiDeviceProxyExample.ino index 04c5cb0..cfe8604 100644 --- a/examples/MultiDeviceProxyExample/MultiDeviceProxyExample.ino +++ b/examples/MultiDeviceProxyExample/MultiDeviceProxyExample.ino @@ -37,3 +37,6 @@ void setup() { // Note: Various parts of functionality of the proxy class instance are actually // disabled - typically anything that involves a read command being issued. } + +void loop() { +} diff --git a/examples/ServoEvaluatorExample/ServoEvaluatorExample.ino b/examples/ServoEvaluatorExample/ServoEvaluatorExample.ino index a70b1be..4d9f0ce 100644 --- a/examples/ServoEvaluatorExample/ServoEvaluatorExample.ino +++ b/examples/ServoEvaluatorExample/ServoEvaluatorExample.ino @@ -53,3 +53,6 @@ void setup() { pwmController.setChannelPWM(1, pwmServo2.pwmForAngle(90)); Serial.println(pwmController.getChannelPWM(1)); // Should output 526 for +90° } + +void loop() { +} diff --git a/examples/SimpleExample/SimpleExample.ino b/examples/SimpleExample/SimpleExample.ino index a46c73b..609d43c 100644 --- a/examples/SimpleExample/SimpleExample.ino +++ b/examples/SimpleExample/SimpleExample.ino @@ -20,3 +20,6 @@ void setup() { Serial.println(pwmController.getChannelPWM(0)); // Should output 2048, which is 128 << 4 } + +void loop() { +} diff --git a/examples/SoftwareI2CExample/SoftwareI2CExample.ino b/examples/SoftwareI2CExample/SoftwareI2CExample.ino index f0772ba..1c5b407 100644 --- a/examples/SoftwareI2CExample/SoftwareI2CExample.ino +++ b/examples/SoftwareI2CExample/SoftwareI2CExample.ino @@ -32,3 +32,6 @@ void setup() { pwmController.setChannelPWM(0, 2048); // Should see a 50% duty cycle along the 5ms phase width } + +void loop() { +} From 76d2ab967cf4d1069fe76773b4453e3068b3d3d4 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Thu, 8 Feb 2018 14:39:13 -0800 Subject: [PATCH 38/57] Fixed readByes to readBytes (thanks to @Shdwdrgn for the catch!) --- PCA9685.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/PCA9685.cpp b/PCA9685.cpp index 1dcfa18..f236f7b 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -642,7 +642,7 @@ uint8_t PCA9685::i2cWire_read(void) { return (uint8_t)(_i2cWire->read() & 0xFF); #else if (_readBytes > 1) { - _readByes -= 1; + _readBytes -= 1; return (uint8_t)(i2c_read(false) & 0xFF); } else { From 3f9bb743b2219155e96cb094d1ff3945c8a8deb1 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Thu, 8 Feb 2018 15:48:33 -0800 Subject: [PATCH 39/57] Fix for software i2c mode in which stop bit wasn't being sent after read operation (thanks to @svatoun for the catch!). --- PCA9685.cpp | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/PCA9685.cpp b/PCA9685.cpp index f236f7b..74ecea9 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -261,6 +261,9 @@ uint16_t PCA9685::getChannelPWM(int channel) { if (bytesRead != 4) { while (bytesRead-- > 0) i2cWire_read(); +#ifdef PCA9685_ENABLE_SOFTWARE_I2C + i2c_stop(); // Manually have to send stop bit in software i2c mode +#else _lastI2CError = 4; #ifdef PCA9685_ENABLE_DEBUG_OUTPUT checkForErrors(); @@ -273,6 +276,10 @@ uint16_t PCA9685::getChannelPWM(int channel) { uint16_t phaseEnd = (uint16_t)i2cWire_read(); phaseEnd |= (uint16_t)i2cWire_read() << 8; +#ifdef PCA9685_ENABLE_SOFTWARE_I2C + i2c_stop(); // Manually have to send stop bit in software i2c mode +#else + #ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print(" PCA9685::getChannelPWM phaseBegin: "); Serial.print(phaseBegin); @@ -578,6 +585,9 @@ byte PCA9685::readRegister(byte regAddress) { if (bytesRead != 1) { while (bytesRead-- > 0) i2cWire_read(); +#ifdef PCA9685_ENABLE_SOFTWARE_I2C + i2c_stop(); // Manually have to send stop bit in software i2c mode +#else _lastI2CError = 4; #ifdef PCA9685_ENABLE_DEBUG_OUTPUT checkForErrors(); @@ -587,6 +597,10 @@ byte PCA9685::readRegister(byte regAddress) { byte retVal = i2cWire_read(); +#ifdef PCA9685_ENABLE_SOFTWARE_I2C + i2c_stop(); // Manually have to send stop bit in software i2c mode +#else + #ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print(" PCA9685::readRegister retVal: 0x"); Serial.println(retVal, HEX); From f2106b19d7f745cd2ea92f7619bb9ab15f1463aa Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Thu, 8 Feb 2018 15:51:14 -0800 Subject: [PATCH 40/57] Upping version. Release for 1.2.10. --- PCA9685.cpp | 2 +- PCA9685.h | 2 +- README.md | 2 +- library.properties | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/PCA9685.cpp b/PCA9685.cpp index 74ecea9..4fcf79f 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -19,7 +19,7 @@ Forked by Vitska, June 18th, 2016. Forked by NachtRaveVL, July 29th, 2016. - PCA9685-Arduino - Version 1.2.9 + PCA9685-Arduino - Version 1.2.10 */ #include "PCA9685.h" diff --git a/PCA9685.h b/PCA9685.h index ef16152..0764430 100644 --- a/PCA9685.h +++ b/PCA9685.h @@ -19,7 +19,7 @@ Forked by Vitska, June 18th, 2016. Forked by NachtRaveVL, July 29th, 2016. - PCA9685-Arduino - Version 1.2.9 + PCA9685-Arduino - Version 1.2.10 */ #ifndef PCA9685_H diff --git a/README.md b/README.md index 74f4d2b..035d524 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # PCA9685-Arduino Arduino Library for the PCA9685 16-Channel PWM Driver Module. -**PCA9685-Arduino - Version 1.2.9** +**PCA9685-Arduino - Version 1.2.10** Library to control a PCA9685 16-channel PWM driver module from an Arduino board. Licensed under the copy-left GNU GPL v3 license. diff --git a/library.properties b/library.properties index 715ce5d..c043e08 100644 --- a/library.properties +++ b/library.properties @@ -1,5 +1,5 @@ name=PCA9685 16-Channel PWM Driver Module Library -version=1.2.9 +version=1.2.10 author=NachtRaveVL , Vitska, Kasper SkÃ¥rhøj maintainer=NachtRaveVL sentence=Library to control a PCA9685 16-channel PWM driver module from an Arduino board. From 8a6ed1cf90f3b31caf9f9d5ba26ccd51bb828700 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Mon, 12 Feb 2018 10:53:54 -0800 Subject: [PATCH 41/57] Fixing #endif --- PCA9685.cpp | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/PCA9685.cpp b/PCA9685.cpp index 4fcf79f..43651ea 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -263,7 +263,7 @@ uint16_t PCA9685::getChannelPWM(int channel) { i2cWire_read(); #ifdef PCA9685_ENABLE_SOFTWARE_I2C i2c_stop(); // Manually have to send stop bit in software i2c mode -#else +#endif _lastI2CError = 4; #ifdef PCA9685_ENABLE_DEBUG_OUTPUT checkForErrors(); @@ -278,7 +278,7 @@ uint16_t PCA9685::getChannelPWM(int channel) { #ifdef PCA9685_ENABLE_SOFTWARE_I2C i2c_stop(); // Manually have to send stop bit in software i2c mode -#else +#endif #ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print(" PCA9685::getChannelPWM phaseBegin: "); @@ -587,7 +587,7 @@ byte PCA9685::readRegister(byte regAddress) { i2cWire_read(); #ifdef PCA9685_ENABLE_SOFTWARE_I2C i2c_stop(); // Manually have to send stop bit in software i2c mode -#else +#endif _lastI2CError = 4; #ifdef PCA9685_ENABLE_DEBUG_OUTPUT checkForErrors(); @@ -599,7 +599,7 @@ byte PCA9685::readRegister(byte regAddress) { #ifdef PCA9685_ENABLE_SOFTWARE_I2C i2c_stop(); // Manually have to send stop bit in software i2c mode -#else +#endif #ifdef PCA9685_ENABLE_DEBUG_OUTPUT Serial.print(" PCA9685::readRegister retVal: 0x"); From 1c1627de7c028a89a633751a6011afaacf4cfe67 Mon Sep 17 00:00:00 2001 From: "Dipl.-Ing. Raoul Rubien, BSc" Date: Tue, 25 Feb 2020 07:02:58 +0100 Subject: [PATCH 42/57] fix comparison between signed and unsigned integer (#12) I suggest cast retVal to unsigned (or PCA9685_PWM_FULL to signed) to overcome comparison between signed and unsigned integer values. Compiler error: ``` Compiling .pio/build/leonardo/lib021/PCA9685 16-Channel PWM Driver Module Library_ID2100/PCA9685.cpp.o In file included from .pio/libdeps/leonardo/PCA9685 16-Channel PWM Driver Module Library_ID2100/PCA9685.h:56:0, from .pio/libdeps/leonardo/PCA9685 16-Channel PWM Driver Module Library_ID2100/PCA9685.cpp:25: .pio/libdeps/leonardo/PCA9685 16-Channel PWM Driver Module Library_ID2100/PCA9685.cpp: In member function 'uint16_t PCA9685_ServoEvaluator::pwmForAngle(float)': ~/.platformio/packages/framework-arduino-avr/cores/arduino/Arduino.h:95:58: error: comparison between signed and unsigned integer expressions [-Werror=sign-compare] #define constrain(amt,low,high) ((amt)<(low)?(low):((amt)>(high)?(high):(amt))) ^ .pio/libdeps/leonardo/PCA9685 16-Channel PWM Driver Module Library_ID2100/PCA9685.cpp:833:22: note: in expansion of macro 'constrain' return (uint16_t)constrain((int)roundf(retVal), 0, PCA9685_PWM_FULL); ``` --- PCA9685.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/PCA9685.cpp b/PCA9685.cpp index 43651ea..bc5ab56 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -844,7 +844,7 @@ uint16_t PCA9685_ServoEvaluator::pwmForAngle(float angle) { } } - return (uint16_t)constrain((int)roundf(retVal), 0, PCA9685_PWM_FULL); + return (uint16_t)constrain((uint16_t)roundf(retVal), 0, PCA9685_PWM_FULL); }; #endif From 83dfbc454fe5e8adab4df0b788f5a9fee73abfc8 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Thu, 12 Mar 2020 22:17:33 -0700 Subject: [PATCH 43/57] Fixing https://github.com/NachtRaveVL/PCA9685-Arduino/issues/13. Upping version. Compliments to CRprog. --- PCA9685.cpp | 2 +- PCA9685.h | 13 ++++++++++++- README.md | 2 +- examples/BatchingExample/BatchingExample.ino | 2 +- library.properties | 3 +-- 5 files changed, 16 insertions(+), 6 deletions(-) diff --git a/PCA9685.cpp b/PCA9685.cpp index bc5ab56..0f5a9be 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -19,7 +19,7 @@ Forked by Vitska, June 18th, 2016. Forked by NachtRaveVL, July 29th, 2016. - PCA9685-Arduino - Version 1.2.10 + PCA9685-Arduino - Version 1.2.11 */ #include "PCA9685.h" diff --git a/PCA9685.h b/PCA9685.h index 0764430..043a678 100644 --- a/PCA9685.h +++ b/PCA9685.h @@ -19,7 +19,7 @@ Forked by Vitska, June 18th, 2016. Forked by NachtRaveVL, July 29th, 2016. - PCA9685-Arduino - Version 1.2.10 + PCA9685-Arduino - Version 1.2.11 */ #ifndef PCA9685_H @@ -59,6 +59,17 @@ #endif #ifndef PCA9685_ENABLE_SOFTWARE_I2C #include + +// Define BUFFER_LENGTH on platforms that don't natively define such. +#ifndef BUFFER_LENGTH +#ifdef I2C_BUFFER_LENGTH +#define BUFFER_LENGTH I2C_BUFFER_LENGTH +#else +#warning "i2c BUFFER_LENGTH not defined - using default of 32. Check Wire.h (or similar) file for your hardware and manually define to remove this warning." +#define BUFFER_LENGTH 32 +#endif +#endif // /ifndefBUFFER_LENGTH + #endif #define PCA9685_MODE_INVRT (byte)0x10 // Inverts polarity of channel output signal diff --git a/README.md b/README.md index 035d524..fc0d6d6 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # PCA9685-Arduino Arduino Library for the PCA9685 16-Channel PWM Driver Module. -**PCA9685-Arduino - Version 1.2.10** +**PCA9685-Arduino - Version 1.2.11** Library to control a PCA9685 16-channel PWM driver module from an Arduino board. Licensed under the copy-left GNU GPL v3 license. diff --git a/examples/BatchingExample/BatchingExample.ino b/examples/BatchingExample/BatchingExample.ino index 9366c65..b42fd20 100644 --- a/examples/BatchingExample/BatchingExample.ino +++ b/examples/BatchingExample/BatchingExample.ino @@ -22,7 +22,7 @@ void setup() { } void loop() { - word pwms[12]; + uint16_t pwms[12]; pwms[0] = random(0, 4096); pwms[1] = random(0, 4096); pwms[2] = random(0, 4096); diff --git a/library.properties b/library.properties index c043e08..d4eecc2 100644 --- a/library.properties +++ b/library.properties @@ -1,5 +1,5 @@ name=PCA9685 16-Channel PWM Driver Module Library -version=1.2.10 +version=1.2.11 author=NachtRaveVL , Vitska, Kasper SkÃ¥rhøj maintainer=NachtRaveVL sentence=Library to control a PCA9685 16-channel PWM driver module from an Arduino board. @@ -7,4 +7,3 @@ paragraph=This library allows communication with boards running a PCA6985 16-cha category=Device Control url=https://github.com/NachtRaveVL/PCA9685-Arduino architectures=* - From 4a85c4401ad199fc07cffcbdb65b1c4ae0f29e22 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Sun, 15 Mar 2020 19:48:53 -0700 Subject: [PATCH 44/57] Switching to UTF8 encoding on readme. --- README.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index fc0d6d6..8e2b335 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Arduino Library for the PCA9685 16-Channel PWM Driver Module. Library to control a PCA9685 16-channel PWM driver module from an Arduino board. Licensed under the copy-left GNU GPL v3 license. -Created by Kasper Skårhøj, August 3rd, 2012. +Created by Kasper SkÃ¥rhøj, August 3rd, 2012. Forked by Vitska, June 18th, 2016. Forked by NachtRaveVL, July 29th, 2016. @@ -165,14 +165,14 @@ In this example, we utilize the ServoEvaluator class to assist with setting PWM PCA9685 pwmController(Wire1, PCA9685_PhaseBalancer_Weaved); // Library using Wire1 and weaved phase balancing scheme -// Linearly interpolates between standard 2.5%/12.5% phase length (102/512) for -90°/+90° +// Linearly interpolates between standard 2.5%/12.5% phase length (102/512) for -90°/+90° PCA9685_ServoEvaluator pwmServo1; -// Testing our second servo has found that -90° sits at 128, 0° at 324, and +90° at 526. +// Testing our second servo has found that -90° sits at 128, 0° at 324, and +90° at 526. // Since 324 isn't precisely in the middle, a cubic spline will be used to smoothly // interpolate PWM values, which will account for said discrepancy. Additionally, since -// 324 is closer to 128 than 526, there is less resolution in the -90° to 0° range, and -// more in the 0° to +90° range. +// 324 is closer to 128 than 526, there is less resolution in the -90° to 0° range, and +// more in the 0° to +90° range. PCA9685_ServoEvaluator pwmServo2(128,324,526); void setup() { @@ -187,28 +187,28 @@ void setup() { pwmController.setPWMFrequency(50); // 50Hz provides 20ms standard servo phase length pwmController.setChannelPWM(0, pwmServo1.pwmForAngle(-90)); - Serial.println(pwmController.getChannelPWM(0)); // Should output 102 for -90° + Serial.println(pwmController.getChannelPWM(0)); // Should output 102 for -90° - // Showing linearity for midpoint, 205 away from both -90° and 90° - Serial.println(pwmServo1.pwmForAngle(0)); // Should output 307 for 0° + // Showing linearity for midpoint, 205 away from both -90° and 90° + Serial.println(pwmServo1.pwmForAngle(0)); // Should output 307 for 0° pwmController.setChannelPWM(0, pwmServo1.pwmForAngle(90)); - Serial.println(pwmController.getChannelPWM(0)); // Should output 512 for +90° + Serial.println(pwmController.getChannelPWM(0)); // Should output 512 for +90° pwmController.setChannelPWM(1, pwmServo2.pwmForAngle(-90)); - Serial.println(pwmController.getChannelPWM(1)); // Should output 128 for -90° + Serial.println(pwmController.getChannelPWM(1)); // Should output 128 for -90° - // Showing less resolution in the -90° to 0° range - Serial.println(pwmServo2.pwmForAngle(-45)); // Should output 225 for -45°, 97 away from -90° + // Showing less resolution in the -90° to 0° range + Serial.println(pwmServo2.pwmForAngle(-45)); // Should output 225 for -45°, 97 away from -90° pwmController.setChannelPWM(1, pwmServo2.pwmForAngle(0)); - Serial.println(pwmController.getChannelPWM(1)); // Should output 324 for 0° + Serial.println(pwmController.getChannelPWM(1)); // Should output 324 for 0° - // Showing more resolution in the 0° to +90° range - Serial.println(pwmServo2.pwmForAngle(45)); // Should output 424 for +45°, 102 away from +90° + // Showing more resolution in the 0° to +90° range + Serial.println(pwmServo2.pwmForAngle(45)); // Should output 424 for +45°, 102 away from +90° pwmController.setChannelPWM(1, pwmServo2.pwmForAngle(90)); - Serial.println(pwmController.getChannelPWM(1)); // Should output 526 for +90° + Serial.println(pwmController.getChannelPWM(1)); // Should output 526 for +90° } ``` From 0697c462bd79b6f7568d6400ba4b5ca3535ad2e3 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Sun, 15 Mar 2020 20:41:29 -0700 Subject: [PATCH 45/57] Upping version. Fixed some commenting. Adding in swapping of beg/end (low/high) phase values since I noticed a fork containing such. Added library.json for platformIO. --- PCA9685.cpp | 20 +++++++++++++++++--- PCA9685.h | 7 +++++-- README.md | 2 +- library.json | 32 ++++++++++++++++++++++++++++++++ library.properties | 2 +- 5 files changed, 56 insertions(+), 7 deletions(-) create mode 100644 library.json diff --git a/PCA9685.cpp b/PCA9685.cpp index 0f5a9be..0b2a705 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -1,5 +1,5 @@ /* Arduino Library for the PCA9685 16-Channel PWM Driver Module. - Copyright (c) 2016 NachtRaveVL + Copyright (C) 2016 NachtRaveVL Copyright (C) 2012 Kasper SkÃ¥rhøj This program is free software: you can redistribute it and/or modify @@ -19,7 +19,7 @@ Forked by Vitska, June 18th, 2016. Forked by NachtRaveVL, July 29th, 2016. - PCA9685-Arduino - Version 1.2.11 + PCA9685-Arduino - Version 1.2.12 */ #include "PCA9685.h" @@ -271,11 +271,18 @@ uint16_t PCA9685::getChannelPWM(int channel) { return 0; } +#ifndef PCA9685_SWAP_PWM_BEG_END_REGS uint16_t phaseBegin = (uint16_t)i2cWire_read(); phaseBegin |= (uint16_t)i2cWire_read() << 8; uint16_t phaseEnd = (uint16_t)i2cWire_read(); phaseEnd |= (uint16_t)i2cWire_read() << 8; - +#else + uint16_t phaseEnd = (uint16_t)i2cWire_read(); + phaseEnd |= (uint16_t)i2cWire_read() << 8; + uint16_t phaseBegin = (uint16_t)i2cWire_read(); + phaseBegin |= (uint16_t)i2cWire_read() << 8; +#endif + #ifdef PCA9685_ENABLE_SOFTWARE_I2C i2c_stop(); // Manually have to send stop bit in software i2c mode #endif @@ -534,10 +541,17 @@ void PCA9685::writeChannelPWM(uint16_t phaseBegin, uint16_t phaseEnd) { Serial.println(phaseEnd); #endif +#ifndef PCA9685_SWAP_PWM_BEG_END_REGS i2cWire_write(lowByte(phaseBegin)); i2cWire_write(highByte(phaseBegin)); i2cWire_write(lowByte(phaseEnd)); i2cWire_write(highByte(phaseEnd)); +#else + i2cWire_write(lowByte(phaseEnd)); + i2cWire_write(highByte(phaseEnd)); + i2cWire_write(lowByte(phaseBegin)); + i2cWire_write(highByte(phaseBegin)); +#endif } void PCA9685::writeChannelEnd() { diff --git a/PCA9685.h b/PCA9685.h index 043a678..7173026 100644 --- a/PCA9685.h +++ b/PCA9685.h @@ -1,5 +1,5 @@ /* Arduino Library for the PCA9685 16-Channel PWM Driver Module. - Copyright (c) 2016 NachtRaveVL + Copyright (C) 2016 NachtRaveVL Copyright (C) 2012 Kasper SkÃ¥rhøj This program is free software: you can redistribute it and/or modify @@ -19,7 +19,7 @@ Forked by Vitska, June 18th, 2016. Forked by NachtRaveVL, July 29th, 2016. - PCA9685-Arduino - Version 1.2.11 + PCA9685-Arduino - Version 1.2.12 */ #ifndef PCA9685_H @@ -36,6 +36,9 @@ // Uncomment this define if wanting to exclude ServoEvaluator assistant from compilation. //#define PCA9685_EXCLUDE_SERVO_EVAL 1 +// Uncomment this define to swap PWM low(begin)/high(end) phase values in register reads/writes (needed for some chip manufacturers). +//#define PCA9685_SWAP_PWM_BEG_END_REGS 1 + // Uncomment this define to enable debug output. //#define PCA9685_ENABLE_DEBUG_OUTPUT 1 diff --git a/README.md b/README.md index 8e2b335..c01e59d 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ Created by Kasper SkÃ¥rhøj, August 3rd, 2012. Forked by Vitska, June 18th, 2016. Forked by NachtRaveVL, July 29th, 2016. -This library allows communication with boards running a PCA6985 16-channel PWM driver module. It supports a wide range of available functionality, from setting the output PWM frequecy, allowing multi-device proxy addressing, and provides an assistant class for working with Servos. +This library allows communication with boards running a PCA6985 16-channel PWM driver module. It supports a wide range of available functionality, from setting the output PWM frequecy, allowing multi-device proxy addressing, and provides an assistant class for working with Servos. Newer versions should work with PlatformIO, ESP32/8266, Teensy, and others (although one might want to ensure i2c BUFFER_LENGTH is properly defined for those architectures). The datasheet for the IC is available from . diff --git a/library.json b/library.json new file mode 100644 index 0000000..deac38b --- /dev/null +++ b/library.json @@ -0,0 +1,32 @@ +{ + "name": "PCA9685-Arduino", + "version": "1.2.12", + "keywords": "PCA9685, Arduino, PWM, controller, driver", + "description": "Library to control a PCA9685 16-channel PWM driver module from an Arduino board.", + "license": "GPL-3.0-or-later", + "authors": [ + { + "name": "NachtRaveVL", + "email": "nachtravevl@gmail.com", + "url": "https://github.com/NachtRaveVL", + "maintainer": true + }, + { + "name": "Vitska", + "url": "https://github.com/vitska" + }, + { + "name": "Kasper SkÃ¥rhøj", + "url": "https://github.com/kasperskaarhoj" + } + ], + "repository": { + "type": "git", + "url": "https://github.com/NachtRaveVL/PCA9685-Arduino.git" + }, + "export": { + "include": "Wire" + }, + "frameworks": "arduino", + "platforms": "*" +} diff --git a/library.properties b/library.properties index d4eecc2..d9ec198 100644 --- a/library.properties +++ b/library.properties @@ -1,5 +1,5 @@ name=PCA9685 16-Channel PWM Driver Module Library -version=1.2.11 +version=1.2.12 author=NachtRaveVL , Vitska, Kasper SkÃ¥rhøj maintainer=NachtRaveVL sentence=Library to control a PCA9685 16-channel PWM driver module from an Arduino board. From e99a0181aee666b2ea0a03c914e9d332f43bcd17 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Fri, 22 May 2020 00:16:48 -0700 Subject: [PATCH 46/57] Changing some defines. Setting default mode to 0x00. Adding more commenting. --- PCA9685.cpp | 12 ++--- PCA9685.h | 54 ++++++++++++------- README.md | 26 +++++---- examples/BatchingExample/BatchingExample.ino | 2 +- .../MultiDeviceProxyExample.ino | 4 +- .../ServoEvaluatorExample.ino | 2 +- examples/SimpleExample/SimpleExample.ino | 2 +- .../SoftwareI2CExample/SoftwareI2CExample.ino | 2 +- library.json | 2 +- library.properties | 2 +- 10 files changed, 65 insertions(+), 43 deletions(-) diff --git a/PCA9685.cpp b/PCA9685.cpp index 0b2a705..b4e2891 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -735,14 +735,14 @@ void PCA9685::printModuleInfo() { Serial.print(", Bitset:"); if (mode2Reg & PCA9685_MODE_INVRT) Serial.print(" PCA9685_MODE_INVRT"); - if (mode2Reg & PCA9685_MODE_OUTPUT_ONACK) - Serial.print(" PCA9685_MODE_OUTPUT_ONACK"); - if (mode2Reg & PCA9685_MODE_OUTPUT_TPOLE) - Serial.print(" PCA9685_MODE_OUTPUT_TPOLE"); + if (mode2Reg & PCA9685_MODE_OCH_ONACK) + Serial.print(" PCA9685_MODE_OCH_ONACK"); + if (mode2Reg & PCA9685_MODE_OUTDRV_TPOLE) + Serial.print(" PCA9685_MODE_OUTDRV_TPOLE"); if (mode2Reg & PCA9685_MODE_OUTNE_HIGHZ) Serial.print(" PCA9685_MODE_OUTNE_HIGHZ"); - if (mode2Reg & PCA9685_MODE_OUTNE_LOW) - Serial.print(" PCA9685_MODE_OUTNE_LOW"); + if (mode2Reg & PCA9685_MODE_OUTNE_TPHIGH) + Serial.print(" PCA9685_MODE_OUTNE_TPHIGH"); Serial.println(""); Serial.println(""); Serial.println("SubAddress1 Register:"); diff --git a/PCA9685.h b/PCA9685.h index 7173026..b12dce1 100644 --- a/PCA9685.h +++ b/PCA9685.h @@ -19,13 +19,14 @@ Forked by Vitska, June 18th, 2016. Forked by NachtRaveVL, July 29th, 2016. - PCA9685-Arduino - Version 1.2.12 + PCA9685-Arduino - Version 1.2.13 */ #ifndef PCA9685_H #define PCA9685_H -// Library Setup +// Library Setup +// NOTE: It is recommended to avoid editing library files directly and instead copy these into your own project and uncomment/define, as desired, before the include directive to this library, or through custom build flags. // Uncomment this define to enable use of the software i2c library (min 4MHz+ processor required). //#define PCA9685_ENABLE_SOFTWARE_I2C 1 // http://playground.arduino.cc/Main/SoftwareI2CLibrary @@ -42,18 +43,23 @@ // Uncomment this define to enable debug output. //#define PCA9685_ENABLE_DEBUG_OUTPUT 1 -// Servo Control Note +// Servo Control +// -PLEASE READ- // Many 180 degree controlled digital servos run on a 20ms pulse width (50Hz update // frequency) based duty cycle, and do not utilize the entire pulse width for their // -90/+90 degree control. Typically, 2.5% of the 20ms pulse width (0.5ms) is considered // -90 degrees, and 12.5% of the 20ms pulse width (2.5ms) is considered +90 degrees. This -// roughly translates to raw PCA9685 PWM values of 102 and 512 (out of the 4096 value +// /roughly/ translates to raw PCA9685 PWM values of 102 and 512 (out of the 4096 value // range) for -90 to +90 degree control, but may need to be adjusted to fit your specific -// servo (e.g. some I've tested run ~130 to ~525 for their -90/+90 degree control). Also -// be aware that driving some servos past their -90/+90 degrees of movement can cause a -// little plastic limiter pin to break off and get stuck inside of the gearing, which -// could potentially cause the servo to become jammed. See the PCA9685_ServoEvaluator -// class to assist with calculating PWM values from Servo angle values. +// servo (e.g. some I've tested run ~130 to ~525 for their -90/+90 degree control). +// +// -ALSO- +// Please be aware that driving some servos past their -90/+90 degrees of movement can +// cause a little plastic limiter pin to break off and get stuck inside of the gearing, +// which could potentially cause the servo to become jammed and -NO LONGER FUNCTION-. +// +// See the PCA9685_ServoEvaluator class to assist with calculating PWM values from Servo +// angle values, if you desire that level of fine tuning. #if defined(ARDUINO) && ARDUINO >= 100 #include @@ -68,18 +74,27 @@ #ifdef I2C_BUFFER_LENGTH #define BUFFER_LENGTH I2C_BUFFER_LENGTH #else -#warning "i2c BUFFER_LENGTH not defined - using default of 32. Check Wire.h (or similar) file for your hardware and manually define to remove this warning." +#warning "i2c BUFFER_LENGTH not defined - using default of 32, which may not be supported by your microcontroller's hardware. Check Wire.h (or similar) file for your hardware and manually define to remove this warning." #define BUFFER_LENGTH 32 #endif -#endif // /ifndefBUFFER_LENGTH +#endif // /ifndef BUFFER_LENGTH #endif -#define PCA9685_MODE_INVRT (byte)0x10 // Inverts polarity of channel output signal -#define PCA9685_MODE_OUTPUT_ONACK (byte)0x08 // Channel update happens upon ACK (post-set) rather than on STOP (endTransmission) -#define PCA9685_MODE_OUTPUT_TPOLE (byte)0x04 // Use a totem-pole (push-pull) style output, typical for boards using this chipset -#define PCA9685_MODE_OUTNE_HIGHZ (byte)0x02 // For active low output enable, sets channel output to high-impedance state -#define PCA9685_MODE_OUTNE_LOW (byte)0x01 // Similarly, sets channel output to high if in totem-pole mode, otherwise high-impedance state +// Channel update strategy used when multiple channels are being updated in batch: +#define PCA9685_MODE_OCH_ONACK (byte)0x08 // Channel updates commit after individual channel update ACK signal, instead of after full-transmission STOP signal + +// Output-enabled/active-low-OE=0 driver control modes (see datasheet Table 12 and Fig 13, 14, and 15 concerning correct usage of INVRT and OUTDRV): +#define PCA9685_MODE_INVRT (byte)0x10 // Enables channel output polarity inversion (applicable only when active-low-OE=0) +#define PCA9685_MODE_OUTDRV_TPOLE (byte)0x04 // Enables totem-pole (instead of open-drain) style structure to be used for driving channel output, allowing use of an external channel output driver +// NOTE: 1) Chipset's board must support this feature (most do, some don't) +// 2) When in this mode, INVRT mode should be set according to if an external N-type external driver (should use INVRT) or P-type external driver (should not use INVRT) is more optimal +// 3) From datasheet Table 6. subnote [1]: "Some newer LEDs include integrated Zener diodes to limit voltage transients, reduce EMI, and protect the LEDs, and these -MUST BE- driven only in the open-drain mode to prevent overheating the IC." + +// Output-not-enabled/active-low-OE=1 driver control modes (see datasheet Section 7.4 concerning correct usage of OUTNE): +// NOTE: Active-low-OE pin is typically used to synchronize multiple PCA9685 devices together to the same clock cycle. +#define PCA9685_MODE_OUTNE_HIGHZ (byte)0x02 // Sets all channel outputs to high-impedance state (applicable only when active-low-OE=1) +#define PCA9685_MODE_OUTNE_TPHIGH (byte)0x01 // Sets all channel outputs to HIGH (applicable only when in totem-pole mode and active-low-OE=1) #define PCA9685_MIN_CHANNEL 0 #define PCA9685_MAX_CHANNEL 15 @@ -92,6 +107,7 @@ typedef enum { PCA9685_PhaseBalancer_Count } PCA9685_PhaseBalancer; +// NOTE: Phase balancing essentially means that the start of the high phase cycle, for each channel, is shifted by some amount, so that a large sink doesn't occur all at once. class PCA9685 { public: @@ -116,7 +132,7 @@ class PCA9685 { // Called in setup(). The i2c address here is the value of the A0, A1, A2, A3, A4 and // A5 pins ONLY, as the class takes care of its internal base address. i2cAddress // should be a value between 0 and 61, since only 62 boards can be addressed. - void init(byte i2cAddress = 0, byte mode = PCA9685_MODE_OUTPUT_ONACK | PCA9685_MODE_OUTPUT_TPOLE); + void init(byte i2cAddress = 0, byte mode = 0x00); #ifndef PCA9685_EXCLUDE_EXT_FUNC // Called in setup(). Used when instance talks through to AllCall/Sub1-Sub3 instances @@ -128,7 +144,7 @@ class PCA9685 { byte getI2CAddress(); PCA9685_PhaseBalancer getPhaseBalancer(); - // Min: 24Hz, Max: 1526Hz, Default: 200Hz (resolution widens as Hz goes higher) + // Min: 24Hz, Max: 1526Hz, Default: 200Hz (as Hz increases channel resolution widens, but raw pre-scaler value, as computed per datasheet, also becomes less affected inversly) void setPWMFrequency(float pwmFrequency); // Turns channel either full on or full off @@ -173,7 +189,7 @@ class PCA9685 { TwoWire *_i2cWire; // Wire class instance to use #endif byte _i2cAddress; // Module's i2c address - PCA9685_PhaseBalancer _phaseBalancer; // Phase balancer scheme to distribute load + PCA9685_PhaseBalancer _phaseBalancer; // Phase balancer scheme to distribute load across phase range bool _isProxyAddresser; // Instance is a proxy for sub addressing (disables certain functionality) byte _lastI2CError; // Last i2c error diff --git a/README.md b/README.md index c01e59d..bce3701 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # PCA9685-Arduino Arduino Library for the PCA9685 16-Channel PWM Driver Module. -**PCA9685-Arduino - Version 1.2.11** +**PCA9685-Arduino - Version 1.2.13** Library to control a PCA9685 16-channel PWM driver module from an Arduino board. Licensed under the copy-left GNU GPL v3 license. @@ -18,6 +18,8 @@ The datasheet for the IC is available from , Vitska, Kasper SkÃ¥rhøj maintainer=NachtRaveVL sentence=Library to control a PCA9685 16-channel PWM driver module from an Arduino board. From 410ce9bb40c7e66f7d011ff8a9e4b61c96370816 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Fri, 22 May 2020 11:29:20 -0700 Subject: [PATCH 47/57] typo --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index bce3701..7184af3 100644 --- a/README.md +++ b/README.md @@ -296,7 +296,7 @@ i2c Address: 0x40 Phase Balancer: -PCA9685_PhaseBalancer_Weaved +PCA9685_PhaseBalancer_Linear Proxy Addresser: false @@ -308,8 +308,8 @@ Mode1 Register: Mode2 Register: PCA9685::readRegister regAddress: 0x1 - PCA9685::readRegister retVal: 0xC -0xC, Bitset: + PCA9685::readRegister retVal: 0x0 +0x0, Bitset: SubAddress1 Register: PCA9685::readRegister regAddress: 0x2 From 2bc34398fb4b3126f4eefc54114659324fb60de9 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Fri, 22 May 2020 11:58:00 -0700 Subject: [PATCH 48/57] More documentation updates --- PCA9685.h | 16 ++++++++-------- README.md | 23 +++++++++++++++++++++++ 2 files changed, 31 insertions(+), 8 deletions(-) diff --git a/PCA9685.h b/PCA9685.h index b12dce1..627c22a 100644 --- a/PCA9685.h +++ b/PCA9685.h @@ -84,17 +84,17 @@ // Channel update strategy used when multiple channels are being updated in batch: #define PCA9685_MODE_OCH_ONACK (byte)0x08 // Channel updates commit after individual channel update ACK signal, instead of after full-transmission STOP signal -// Output-enabled/active-low-OE=0 driver control modes (see datasheet Table 12 and Fig 13, 14, and 15 concerning correct usage of INVRT and OUTDRV): -#define PCA9685_MODE_INVRT (byte)0x10 // Enables channel output polarity inversion (applicable only when active-low-OE=0) -#define PCA9685_MODE_OUTDRV_TPOLE (byte)0x04 // Enables totem-pole (instead of open-drain) style structure to be used for driving channel output, allowing use of an external channel output driver +// Output-enabled/active-low-OE-pin=LOW driver control modes (see datasheet Table 12 and Fig 13, 14, and 15 concerning correct usage of INVRT and OUTDRV): +#define PCA9685_MODE_INVRT (byte)0x10 // Enables channel output polarity inversion (applicable only when active-low-OE-pin=LOW) +#define PCA9685_MODE_OUTDRV_TPOLE (byte)0x04 // Enables totem-pole (instead of open-drain) style structure to be used for driving channel output, allowing use of an external output driver // NOTE: 1) Chipset's board must support this feature (most do, some don't) // 2) When in this mode, INVRT mode should be set according to if an external N-type external driver (should use INVRT) or P-type external driver (should not use INVRT) is more optimal // 3) From datasheet Table 6. subnote [1]: "Some newer LEDs include integrated Zener diodes to limit voltage transients, reduce EMI, and protect the LEDs, and these -MUST BE- driven only in the open-drain mode to prevent overheating the IC." -// Output-not-enabled/active-low-OE=1 driver control modes (see datasheet Section 7.4 concerning correct usage of OUTNE): -// NOTE: Active-low-OE pin is typically used to synchronize multiple PCA9685 devices together to the same clock cycle. -#define PCA9685_MODE_OUTNE_HIGHZ (byte)0x02 // Sets all channel outputs to high-impedance state (applicable only when active-low-OE=1) -#define PCA9685_MODE_OUTNE_TPHIGH (byte)0x01 // Sets all channel outputs to HIGH (applicable only when in totem-pole mode and active-low-OE=1) +// Output-not-enabled/active-low-OE-pin=HIGH driver control modes (see datasheet Section 7.4 concerning correct usage of OUTNE): +// NOTE: Active-low-OE pin is typically used to synchronize multiple PCA9685 devices together, or as an external dimming control signal. +#define PCA9685_MODE_OUTNE_HIGHZ (byte)0x02 // Sets all channel outputs to high-impedance state (applicable only when active-low-OE-pin=HIGH) +#define PCA9685_MODE_OUTNE_TPHIGH (byte)0x01 // Sets all channel outputs to HIGH (applicable only when in totem-pole mode and active-low-OE-pin=HIGH) #define PCA9685_MIN_CHANNEL 0 #define PCA9685_MAX_CHANNEL 15 @@ -107,7 +107,7 @@ typedef enum { PCA9685_PhaseBalancer_Count } PCA9685_PhaseBalancer; -// NOTE: Phase balancing essentially means that the start of the high phase cycle, for each channel, is shifted by some amount, so that a large sink doesn't occur all at once. +// NOTE: Phase balancing essentially means that the start of the high phase cycle, for each channel, is shifted by some amount, so that a large voltage sink doesn't occur all at once. class PCA9685 { public: diff --git a/README.md b/README.md index 7184af3..894cb26 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,29 @@ It is recommended to avoid editing library files directly and instead copy these //#define PCA9685_ENABLE_DEBUG_OUTPUT 1 ``` +## Init Mode Flags + +There are several init mode flags exposed through this library that can also be used for more fine-tuned control. + +```Arduino +// Channel update strategy used when multiple channels are being updated in batch: +#define PCA9685_MODE_OCH_ONACK (byte)0x08 // Channel updates commit after individual channel update ACK signal, instead of after full-transmission STOP signal + +// Output-enabled/active-low-OE-pin=LOW driver control modes (see datasheet Table 12 and Fig 13, 14, and 15 concerning correct usage of INVRT and OUTDRV): +#define PCA9685_MODE_INVRT (byte)0x10 // Enables channel output polarity inversion (applicable only when active-low-OE-pin=LOW) +#define PCA9685_MODE_OUTDRV_TPOLE (byte)0x04 // Enables totem-pole (instead of open-drain) style structure to be used for driving channel output, allowing use of an external output driver +// NOTE: 1) Chipset's board must support this feature (most do, some don't) +// 2) When in this mode, INVRT mode should be set according to if an external N-type external driver (should use INVRT) or P-type external driver (should not use INVRT) is more optimal +// 3) From datasheet Table 6. subnote [1]: "Some newer LEDs include integrated Zener diodes to limit voltage transients, reduce EMI, and protect the LEDs, and these -MUST BE- driven only in the open-drain mode to prevent overheating the IC." + +// Output-not-enabled/active-low-OE-pin=HIGH driver control modes (see datasheet Section 7.4 concerning correct usage of OUTNE): +// NOTE: Active-low-OE pin is typically used to synchronize multiple PCA9685 devices together, or as an external dimming control signal. +#define PCA9685_MODE_OUTNE_HIGHZ (byte)0x02 // Sets all channel outputs to high-impedance state (applicable only when active-low-OE-pin=HIGH) +#define PCA9685_MODE_OUTNE_TPHIGH (byte)0x01 // Sets all channel outputs to HIGH (applicable only when in totem-pole mode and active-low-OE-pin=HIGH) +``` + +These init mode flags can be treated as a bitfield, and can be bitwise-OR'ed together to combine multiple flags together. The default init mode of the library (as of v1.2.13) is to not use any of these additional flags. See Section 7.3.2 of the datasheet for more details. + ## Servo Control Many 180 degree controlled digital servos run on a 20ms pulse width (50Hz update frequency) based duty cycle, and do not utilize the entire pulse width for their -90/+90 degree control. Typically, 2.5% of the 20ms pulse width (0.5ms) is considered -90 degrees, and 12.5% of the 20ms pulse width (2.5ms) is considered +90 degrees. This roughly translates to raw PCA9685 PWM values of 102 and 512 (out of the 4096 value range) for -90 to +90 degree control, but may need to be adjusted to fit your specific servo (e.g. some I've tested run ~130 to ~525 for their -90/+90 degree control). From 43bf9d13c96fae4b0be741acd08508ee4e53bcb2 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Sun, 9 Aug 2020 03:34:14 -0700 Subject: [PATCH 49/57] Updating documentation - clarifying some things, standardizing some things. --- PCA9685.h | 15 +++++----- README.md | 30 +++++++++++++------ examples/ModuleInfo/ModuleInfo.ino | 11 +++---- .../SoftwareI2CExample/SoftwareI2CExample.ino | 4 +-- 4 files changed, 37 insertions(+), 23 deletions(-) diff --git a/PCA9685.h b/PCA9685.h index 627c22a..7f87c24 100644 --- a/PCA9685.h +++ b/PCA9685.h @@ -48,15 +48,16 @@ // Many 180 degree controlled digital servos run on a 20ms pulse width (50Hz update // frequency) based duty cycle, and do not utilize the entire pulse width for their // -90/+90 degree control. Typically, 2.5% of the 20ms pulse width (0.5ms) is considered -// -90 degrees, and 12.5% of the 20ms pulse width (2.5ms) is considered +90 degrees. This -// /roughly/ translates to raw PCA9685 PWM values of 102 and 512 (out of the 4096 value -// range) for -90 to +90 degree control, but may need to be adjusted to fit your specific -// servo (e.g. some I've tested run ~130 to ~525 for their -90/+90 degree control). +// -90 degrees, and 12.5% of the 20ms pulse width (2.5ms) is considered +90 degrees. +// This roughly translates to raw PCA9685 PWM values of 102 and 512 (out of the 4096 +// value range) for -90 to +90 degree control, but may need to be adjusted to fit your +// specific servo (e.g. some I've tested run ~130 to ~525 for their -90/+90 degree +// control). // // -ALSO- // Please be aware that driving some servos past their -90/+90 degrees of movement can // cause a little plastic limiter pin to break off and get stuck inside of the gearing, -// which could potentially cause the servo to become jammed and -NO LONGER FUNCTION-. +// which could potentially cause the servo to become jammed and no longer function. // // See the PCA9685_ServoEvaluator class to assist with calculating PWM values from Servo // angle values, if you desire that level of fine tuning. @@ -79,7 +80,7 @@ #endif #endif // /ifndef BUFFER_LENGTH -#endif +#endif // /ifndef PCA9685_ENABLE_SOFTWARE_I2C // Channel update strategy used when multiple channels are being updated in batch: #define PCA9685_MODE_OCH_ONACK (byte)0x08 // Channel updates commit after individual channel update ACK signal, instead of after full-transmission STOP signal @@ -87,7 +88,7 @@ // Output-enabled/active-low-OE-pin=LOW driver control modes (see datasheet Table 12 and Fig 13, 14, and 15 concerning correct usage of INVRT and OUTDRV): #define PCA9685_MODE_INVRT (byte)0x10 // Enables channel output polarity inversion (applicable only when active-low-OE-pin=LOW) #define PCA9685_MODE_OUTDRV_TPOLE (byte)0x04 // Enables totem-pole (instead of open-drain) style structure to be used for driving channel output, allowing use of an external output driver -// NOTE: 1) Chipset's board must support this feature (most do, some don't) +// NOTE: 1) Chipset's breakout must support this feature (most do, some don't) // 2) When in this mode, INVRT mode should be set according to if an external N-type external driver (should use INVRT) or P-type external driver (should not use INVRT) is more optimal // 3) From datasheet Table 6. subnote [1]: "Some newer LEDs include integrated Zener diodes to limit voltage transients, reduce EMI, and protect the LEDs, and these -MUST BE- driven only in the open-drain mode to prevent overheating the IC." diff --git a/README.md b/README.md index 894cb26..6bb508a 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ There are several init mode flags exposed through this library that can also be // Output-enabled/active-low-OE-pin=LOW driver control modes (see datasheet Table 12 and Fig 13, 14, and 15 concerning correct usage of INVRT and OUTDRV): #define PCA9685_MODE_INVRT (byte)0x10 // Enables channel output polarity inversion (applicable only when active-low-OE-pin=LOW) #define PCA9685_MODE_OUTDRV_TPOLE (byte)0x04 // Enables totem-pole (instead of open-drain) style structure to be used for driving channel output, allowing use of an external output driver -// NOTE: 1) Chipset's board must support this feature (most do, some don't) +// NOTE: 1) Chipset's breakout must support this feature (most do, some don't) // 2) When in this mode, INVRT mode should be set according to if an external N-type external driver (should use INVRT) or P-type external driver (should not use INVRT) is more optimal // 3) From datasheet Table 6. subnote [1]: "Some newer LEDs include integrated Zener diodes to limit voltage transients, reduce EMI, and protect the LEDs, and these -MUST BE- driven only in the open-drain mode to prevent overheating the IC." @@ -70,6 +70,7 @@ See the PCA9685_ServoEvaluator class to assist with calculating PWM values from Below are several examples of library usage. ### Simple Example + ```Arduino #include #include "PCA9685.h" @@ -186,7 +187,9 @@ void setup() { ### Servo Evaluator Example -In this example, we utilize the ServoEvaluator class to assist with setting PWM frequencies when working with servos. We will be using Wire1, which is only available on boards with SDA1/SCL1 (Due, Zero, etc.) - change to Wire if Wire1 is unavailable. +In this example, we utilize the ServoEvaluator class to assist with setting PWM frequencies when working with servos. + +We will be using Wire1, which is only available on boards with SDA1/SCL1 (Due, Zero, etc.) - change to Wire if Wire1 is unavailable. ```Arduino #include @@ -244,16 +247,21 @@ void setup() { ### Software I2C Example -In this example, we utilize the software I2C functionality for chips that do not have a hardware I2C bus. We must uncomment the PCA9685_ENABLE_SOFTWARE_I2C define in the libraries main header file for software I2C mode to be enabled. +In this example, we utilize the software I2C functionality for chips that do not have a hardware I2C bus. -In PCA9685.h: +If one defines `PCA9685_ENABLE_SOFTWARE_I2C`, such as before the include directive to this library, as a compilation flag, or by directly editing the library headers (not recommended), software I2C mode will be enabled. + +From PCA9685.h: ```Arduino // Uncomment this define to enable use of the software i2c library (min 4MHz+ processor required). -#define PCA9685_ENABLE_SOFTWARE_I2C 1 // http://playground.arduino.cc/Main/SoftwareI2CLibrary +//#define PCA9685_ENABLE_SOFTWARE_I2C 1 // http://playground.arduino.cc/Main/SoftwareI2CLibrary ``` In main sketch: ```Arduino +// Uncomment this define to enable use of the software i2c library (min 4MHz+ processor required). +#define PCA9685_ENABLE_SOFTWARE_I2C 1 // http://playground.arduino.cc/Main/SoftwareI2CLibrary + #include "PCA9685.h" #define SCL_PIN 2 // Setup defines are written before library include @@ -285,17 +293,21 @@ void setup() { ## Module Info -If one uncomments the PCA9685_ENABLE_DEBUG_OUTPUT define in the libraries main header file (thus enabling debug output) the printModuleInfo() method becomes available, which will display information about the module itself, including initalized states, register values, current settings, etc. All calls being made will display internal debug information about the structure of the call itself. An example of this output is shown here: +In this example, we enable debug output support. + +If one defines `PCA9685_ENABLE_DEBUG_OUTPUT`, such as before the include directive to this library, as a compilation flag, or by directly editing the library headers (not recommended), debug output support will be enabled and the printModuleInfo() method becomes available. Calling this method will display information about the module itself, including initalized states, register values, current settings, etc. All library calls being made will also display internal debug information about the structure of the call itself. An example of this output is shown below. -In PCA9685.h: +From PCA9685.h: ```Arduino // Uncomment this define to enable debug output. -#define PCA9685_ENABLE_DEBUG_OUTPUT 1 +//#define PCA9685_ENABLE_DEBUG_OUTPUT 1 ``` In main sketch: ```Arduino -#include +// Uncomment this define to enable debug output. +#define PCA9685_ENABLE_DEBUG_OUTPUT 1 + #include "PCA9685.h" PCA9685 pwmController; diff --git a/examples/ModuleInfo/ModuleInfo.ino b/examples/ModuleInfo/ModuleInfo.ino index 6887a37..0d01d67 100644 --- a/examples/ModuleInfo/ModuleInfo.ino +++ b/examples/ModuleInfo/ModuleInfo.ino @@ -1,9 +1,10 @@ // PCA9685-Arduino Module Info -// If one uncomments the PCA9685_ENABLE_DEBUG_OUTPUT define in the libraries main header -// file (thus enabling debug output) the printModuleInfo() method becomes available, -// which will display information about the module itself, including initalized states, -// register values, current settings, etc. All calls being made will display internal -// debug information about the structure of the call itself. +// In this example, we enable debug output support. We copy the PCA9685_ENABLE_DEBUG_OUTPUT +// define from the libraries header file for debug output support to enable and the +// printModuleInfo() method to become available. Calling this method will display +// information about the module itself, including initalized states, register values, +// current settings, etc. All library calls being made will also display internal debug +// information about the structure of the call itself. // Uncomment this define to enable debug output. #define PCA9685_ENABLE_DEBUG_OUTPUT 1 diff --git a/examples/SoftwareI2CExample/SoftwareI2CExample.ino b/examples/SoftwareI2CExample/SoftwareI2CExample.ino index 768bd39..06bdc15 100644 --- a/examples/SoftwareI2CExample/SoftwareI2CExample.ino +++ b/examples/SoftwareI2CExample/SoftwareI2CExample.ino @@ -1,7 +1,7 @@ // PCA9685-Arduino Software I2C Example // In this example, we utilize the software I2C functionality for chips that do not have -// a hardware I2C bus. We must uncomment the PCA9685_ENABLE_SOFTWARE_I2C define in the -// libraries main header file for software I2C mode to be enabled. +// a hardware I2C bus. We copy the PCA9685_ENABLE_SOFTWARE_I2C define from the libraries +// header file for software I2C mode to be enabled. // Uncomment this define to enable use of the software i2c library (min 4MHz+ processor required). #define PCA9685_ENABLE_SOFTWARE_I2C 1 // http://playground.arduino.cc/Main/SoftwareI2CLibrary From cea4f6e960162c8c3b70e1e8f9fb812d6ba20ffe Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Sun, 9 Aug 2020 17:24:53 -0700 Subject: [PATCH 50/57] More standardization, updating library data --- PCA9685.h | 5 ++++- library.json | 6 ++---- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/PCA9685.h b/PCA9685.h index 7f87c24..5820865 100644 --- a/PCA9685.h +++ b/PCA9685.h @@ -26,7 +26,10 @@ #define PCA9685_H // Library Setup -// NOTE: It is recommended to avoid editing library files directly and instead copy these into your own project and uncomment/define, as desired, before the include directive to this library, or through custom build flags. + +// NOTE: It is recommended to avoid editing library files directly and instead copy these +// into your own project and uncomment/define, as desired, before the include directive +// to this library, or through custom build flags. // Uncomment this define to enable use of the software i2c library (min 4MHz+ processor required). //#define PCA9685_ENABLE_SOFTWARE_I2C 1 // http://playground.arduino.cc/Main/SoftwareI2CLibrary diff --git a/library.json b/library.json index 92f0d5a..8a13c52 100644 --- a/library.json +++ b/library.json @@ -1,7 +1,7 @@ { "name": "PCA9685-Arduino", "version": "1.2.13", - "keywords": "PCA9685, Arduino, PWM, controller, driver", + "keywords": "PCA9685, pwm, i2c, controller, driver", "description": "Library to control a PCA9685 16-channel PWM driver module from an Arduino board.", "license": "GPL-3.0-or-later", "authors": [ @@ -20,13 +20,11 @@ "url": "https://github.com/kasperskaarhoj" } ], + "homepage": "https://github.com/NachtRaveVL/PCA9685-Arduino/", "repository": { "type": "git", "url": "https://github.com/NachtRaveVL/PCA9685-Arduino.git" }, - "export": { - "include": "Wire" - }, "frameworks": "arduino", "platforms": "*" } From bc81b13506f4af94bb55d1a9dc0a1d197ab3ac7a Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Sun, 9 Aug 2020 17:35:49 -0700 Subject: [PATCH 51/57] Adding examples into library json --- library.json | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/library.json b/library.json index 8a13c52..538e83a 100644 --- a/library.json +++ b/library.json @@ -25,6 +25,38 @@ "type": "git", "url": "https://github.com/NachtRaveVL/PCA9685-Arduino.git" }, + "examples": [ + { + "name": "SimpleExample", + "base": "examples/SimpleExample", + "files": ["SimpleExample.ino"] + }, + { + "name": "BatchingExample", + "base": "examples/BatchingExample", + "files": ["BatchingExample.ino"] + }, + { + "name": "MultiDeviceProxyExample", + "base": "examples/MultiDeviceProxyExample", + "files": ["MultiDeviceProxyExample.ino"] + }, + { + "name": "ServoEvaluatorExample", + "base": "examples/ServoEvaluatorExample", + "files": ["ServoEvaluatorExample.ino"] + }, + { + "name": "SoftwareI2CExample", + "base": "examples/SoftwareI2CExample", + "files": ["SoftwareI2CExample.ino"] + }, + { + "name": "ModuleInfo", + "base": "examples/ModuleInfo", + "files": ["ModuleInfo.ino"] + } + ], "frameworks": "arduino", "platforms": "*" } From 5252745ed307b93c10d04b801ca613d7c6e1ad41 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Mon, 10 Aug 2020 04:34:40 -0700 Subject: [PATCH 52/57] Pushing version, correcting language. --- PCA9685.cpp | 2 +- PCA9685.h | 14 ++++---- README.md | 36 +++++++++---------- examples/ModuleInfo/ModuleInfo.ino | 20 ++++++----- .../SoftwareI2CExample/SoftwareI2CExample.ino | 11 +++--- library.json | 2 +- library.properties | 2 +- 7 files changed, 44 insertions(+), 43 deletions(-) diff --git a/PCA9685.cpp b/PCA9685.cpp index b4e2891..48a7533 100644 --- a/PCA9685.cpp +++ b/PCA9685.cpp @@ -19,7 +19,7 @@ Forked by Vitska, June 18th, 2016. Forked by NachtRaveVL, July 29th, 2016. - PCA9685-Arduino - Version 1.2.12 + PCA9685-Arduino - Version 1.2.14 */ #include "PCA9685.h" diff --git a/PCA9685.h b/PCA9685.h index 5820865..f3a6717 100644 --- a/PCA9685.h +++ b/PCA9685.h @@ -19,17 +19,17 @@ Forked by Vitska, June 18th, 2016. Forked by NachtRaveVL, July 29th, 2016. - PCA9685-Arduino - Version 1.2.13 + PCA9685-Arduino - Version 1.2.14 */ #ifndef PCA9685_H #define PCA9685_H -// Library Setup +// Library Setup -// NOTE: It is recommended to avoid editing library files directly and instead copy these -// into your own project and uncomment/define, as desired, before the include directive -// to this library, or through custom build flags. +// NOTE: It is recommended to avoid editing library files directly and instead use custom +// build flags. While most custom build systems support such, the Arduino IDE does not. +// Be aware that editing this file directly will affect all projects using this library. // Uncomment this define to enable use of the software i2c library (min 4MHz+ processor required). //#define PCA9685_ENABLE_SOFTWARE_I2C 1 // http://playground.arduino.cc/Main/SoftwareI2CLibrary @@ -46,7 +46,7 @@ // Uncomment this define to enable debug output. //#define PCA9685_ENABLE_DEBUG_OUTPUT 1 -// Servo Control +// Hookup Callout: Servo Control // -PLEASE READ- // Many 180 degree controlled digital servos run on a 20ms pulse width (50Hz update // frequency) based duty cycle, and do not utilize the entire pulse width for their @@ -136,7 +136,7 @@ class PCA9685 { // Called in setup(). The i2c address here is the value of the A0, A1, A2, A3, A4 and // A5 pins ONLY, as the class takes care of its internal base address. i2cAddress // should be a value between 0 and 61, since only 62 boards can be addressed. - void init(byte i2cAddress = 0, byte mode = 0x00); + void init(byte i2cAddress = 0, byte mode = PCA9685_MODE_OUTDRV_TPOLE); #ifndef PCA9685_EXCLUDE_EXT_FUNC // Called in setup(). Used when instance talks through to AllCall/Sub1-Sub3 instances diff --git a/README.md b/README.md index 6bb508a..23d3884 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # PCA9685-Arduino Arduino Library for the PCA9685 16-Channel PWM Driver Module. -**PCA9685-Arduino - Version 1.2.13** +**PCA9685-Arduino - Version 1.2.14** Library to control a PCA9685 16-channel PWM driver module from an Arduino board. Licensed under the copy-left GNU GPL v3 license. @@ -16,10 +16,11 @@ The datasheet for the IC is available from #include "PCA9685.h" diff --git a/examples/SoftwareI2CExample/SoftwareI2CExample.ino b/examples/SoftwareI2CExample/SoftwareI2CExample.ino index 06bdc15..c537e5a 100644 --- a/examples/SoftwareI2CExample/SoftwareI2CExample.ino +++ b/examples/SoftwareI2CExample/SoftwareI2CExample.ino @@ -1,10 +1,11 @@ // PCA9685-Arduino Software I2C Example // In this example, we utilize the software I2C functionality for chips that do not have -// a hardware I2C bus. We copy the PCA9685_ENABLE_SOFTWARE_I2C define from the libraries -// header file for software I2C mode to be enabled. - -// Uncomment this define to enable use of the software i2c library (min 4MHz+ processor required). -#define PCA9685_ENABLE_SOFTWARE_I2C 1 // http://playground.arduino.cc/Main/SoftwareI2CLibrary +// a hardware I2C bus. If one uncomments the line below inside the main header file (or +// defines it via custom build flag), software I2C mode for the library will be enabled. +// +// In PCA9685.h: +// // Uncomment this define to enable use of the software i2c library (min 4MHz+ processor required). +// #define PCA9685_ENABLE_SOFTWARE_I2C 1 // http://playground.arduino.cc/Main/SoftwareI2CLibrary #include "PCA9685.h" diff --git a/library.json b/library.json index 538e83a..bda4071 100644 --- a/library.json +++ b/library.json @@ -1,6 +1,6 @@ { "name": "PCA9685-Arduino", - "version": "1.2.13", + "version": "1.2.14", "keywords": "PCA9685, pwm, i2c, controller, driver", "description": "Library to control a PCA9685 16-channel PWM driver module from an Arduino board.", "license": "GPL-3.0-or-later", diff --git a/library.properties b/library.properties index 83c3551..f4c0ee2 100644 --- a/library.properties +++ b/library.properties @@ -1,5 +1,5 @@ name=PCA9685 16-Channel PWM Driver Module Library -version=1.2.13 +version=1.2.14 author=NachtRaveVL , Vitska, Kasper SkÃ¥rhøj maintainer=NachtRaveVL sentence=Library to control a PCA9685 16-channel PWM driver module from an Arduino board. From 59ed16f64c127febaa9a743f3c08d7630526990e Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Wed, 12 Aug 2020 00:57:40 -0700 Subject: [PATCH 53/57] More documentation --- README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/README.md b/README.md index 23d3884..43858cf 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,18 @@ Also, please be aware that driving some servos past their -90/+90 degrees of mov See the PCA9685_ServoEvaluator class to assist with calculating PWM values from Servo angle values, if you desire that level of fine tuning. +## Memory Callouts + +### Extended Functions + +This library has an extended list of functionality for those who care to dive into such, but isn't always particularly the most useful for various general use cases. If one uncomments the line below inside the main header file (or defines it via custom build flag), this extended functionality can be manually compiled-out. + +In PCA9685.h: +```Arduino +// Uncomment this define if wanting to exclude extended functionality from compilation. +#define PCA9685_EXCLUDE_EXT_FUNC 1 +``` + ## Example Usage Below are several examples of library usage. From 90ea652c7a54efedefe0cc3a993032124ae03fd7 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Wed, 12 Aug 2020 00:58:59 -0700 Subject: [PATCH 54/57] More doc updates --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 43858cf..c5c2bec 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ In PCA9685.h: ### Library Initialization -There are several initialization mode flags exposed through this library that are used for more fine-tuned control. These flags are expected to be provided to the library's 'init(...)' function, commonly called inside of the sketch's `setup()` function. These init mode flags can be treated as a bitfield, and can be bitwise-OR'ed together to combine multiple flags together. The default init mode of the library, if left unspecified, is `PCA9685_MODE_OUTDRV_TPOLE`, which seems to work for most of the PCA9685 breakouts on market, but may be incorrect for custom PCA9685 integrations. +There are several initialization mode flags exposed through this library that are used for more fine-tuned control. These flags are expected to be provided to the library's `init(...)` function, commonly called inside of the sketch's `setup()` function. These init mode flags can be treated as a bitfield, and can be bitwise-OR'ed together to combine multiple flags together. The default init mode of the library, if left unspecified, is `PCA9685_MODE_OUTDRV_TPOLE`, which seems to work for most of the PCA9685 breakouts on market, but may be incorrect for custom PCA9685 integrations. See Section 7.3.2 of the datasheet for more details. From c4e8dd957658e1b8bc8c2caa40eb980d591e5546 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Thu, 15 Oct 2020 21:02:33 -0700 Subject: [PATCH 55/57] 1.2.15 (#16) * - Upping version to 1.2.15 - Modified constructor/initializer pathways - Added convenience constructor/initializer - Expanded initialization mode settings - Removed extraneous 1 on defines - Standardized i2c buffer length determination - Expanded & standardized comments/documentation - Moved Wire begin into library (standardization across libraries) - Reworked examples - Added dyanmic phase balancer - Various other standardizations * Wording * Adding VS code settings, better debug output * Adding another datasheet * Standardizing i2c naming * Correct i2c datatype, adding getI2CSpeed * Wrong identifier * Refined getI2CSpeed to deal with software i2c, correcting returntype on i2c_init * Documentation updates. * Documentation updates * Documentation updates. * Documentation updates. * More documentation updates. * More doc updates. * fixing offset * Continuous servo support * More doc updates * Adding some spacing * Better Espressif support * Documentation updates. * Documentation updates. * Correcting tabs. Removing extraneous begin stuff. Almost code complete. * Lots of documentation updates, clarifications, and some better logging code. * Improved documentation. Corrected a few more things. Ready for release. * Last one Co-authored-by: NachtRaveVL --- .vscode/arduino.json | 3 + .vscode/c_cpp_properties.json | 31 + .vscode/settings.json | 27 + PCA9685.cpp | 864 ------------- PCA9685.h | 245 ---- README.md | 399 ++++-- examples/BatchingExample/BatchingExample.ino | 23 +- examples/ModuleInfo/ModuleInfo.ino | 34 +- .../MultiDeviceProxyExample.ino | 29 +- .../ServoEvaluatorExample.ino | 24 +- examples/SimpleExample/SimpleExample.ino | 16 +- .../SoftwareI2CExample/SoftwareI2CExample.ino | 46 +- library.json | 2 +- library.properties | 2 +- src/PCA9685.cpp | 1079 +++++++++++++++++ src/PCA9685.h | 338 ++++++ support files/PCA9685.pdf | Bin 0 -> 408783 bytes 17 files changed, 1845 insertions(+), 1317 deletions(-) create mode 100644 .vscode/arduino.json create mode 100644 .vscode/c_cpp_properties.json create mode 100644 .vscode/settings.json delete mode 100644 PCA9685.cpp delete mode 100644 PCA9685.h create mode 100644 src/PCA9685.cpp create mode 100644 src/PCA9685.h create mode 100644 support files/PCA9685.pdf diff --git a/.vscode/arduino.json b/.vscode/arduino.json new file mode 100644 index 0000000..82734bd --- /dev/null +++ b/.vscode/arduino.json @@ -0,0 +1,3 @@ +{ + "sketch": "examples\\ModuleInfo\\ModuleInfo.ino" +} \ No newline at end of file diff --git a/.vscode/c_cpp_properties.json b/.vscode/c_cpp_properties.json new file mode 100644 index 0000000..251a9ff --- /dev/null +++ b/.vscode/c_cpp_properties.json @@ -0,0 +1,31 @@ +{ + "configurations": [ + { + "name": "Win32", + "includePath": [ + "${workspaceFolder}/**", + "${LocalAppData}/Arduino15/packages/arduino/hardware/megaavr/1.8.6/**", + "${LocalAppData}/Arduino15/packages/arduino/tools/avr-gcc/7.3.0-atmel3.6.1-arduino5/avr/include/**", + "${LocalAppData}/Arduino15/packages/esp8266/tools/**", + "${LocalAppData}/Arduino15/packages/esp8266/hardware/esp8266/2.7.4/**", + "${USERPROFILE}/Documents/Arduino/libraries/**", + "${vcpkgRoot}/x86-windows/include/**" + ], + "defines": [ + "_DEBUG", + "UNICODE", + "_UNICODE", + "ARDUINO=100", + "F_CPU=64000000", + "PCA9685_ENABLE_DEBUG_OUTPUT" + ], + "windowsSdkVersion": "10.0.19041.0", + "compilerPath": "C:/Program Files (x86)/Microsoft Visual Studio/2019/Community/VC/Tools/MSVC/14.27.29110/bin/Hostx64/x64/cl.exe", + "cStandard": "c11", + "cppStandard": "c++17", + "intelliSenseMode": "msvc-x64", + "forcedInclude": [] + } + ], + "version": 4 +} \ No newline at end of file diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..73d5092 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,27 @@ +{ + "files.associations": { + "cstddef": "cpp", + "array": "cpp", + "deque": "cpp", + "initializer_list": "cpp", + "list": "cpp", + "vector": "cpp", + "xhash": "cpp", + "xstring": "cpp", + "xtree": "cpp", + "xutility": "cpp", + "future": "cpp", + "istream": "cpp", + "memory": "cpp", + "type_traits": "cpp", + "xlocmes": "cpp", + "xlocmon": "cpp", + "xlocnum": "cpp", + "xloctime": "cpp", + "algorithm": "cpp", + "regex": "cpp", + "tuple": "cpp", + "utility": "cpp", + "variant": "cpp" + } +} \ No newline at end of file diff --git a/PCA9685.cpp b/PCA9685.cpp deleted file mode 100644 index 48a7533..0000000 --- a/PCA9685.cpp +++ /dev/null @@ -1,864 +0,0 @@ -/* Arduino Library for the PCA9685 16-Channel PWM Driver Module. - Copyright (C) 2016 NachtRaveVL - Copyright (C) 2012 Kasper SkÃ¥rhøj - - This program is free software: you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation, either version 3 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . - - Created by Kasper SkÃ¥rhøj, August 3rd, 2012. - Forked by Vitska, June 18th, 2016. - Forked by NachtRaveVL, July 29th, 2016. - - PCA9685-Arduino - Version 1.2.14 -*/ - -#include "PCA9685.h" - -#define PCA9685_I2C_BASE_ADDRESS (byte)0x40 - -// Register addresses from data sheet -#define PCA9685_MODE1_REG (byte)0x00 -#define PCA9685_MODE2_REG (byte)0x01 -#define PCA9685_SUBADR1_REG (byte)0x02 -#define PCA9685_SUBADR2_REG (byte)0x03 -#define PCA9685_SUBADR3_REG (byte)0x04 -#define PCA9685_ALLCALL_REG (byte)0x05 -#define PCA9685_LED0_REG (byte)0x06 // Start of LEDx regs, 4B per reg, 2B on phase, 2B off phase, little-endian -#define PCA9685_PRESCALE_REG (byte)0xFE -#define PCA9685_ALLLED_REG (byte)0xFA - -// Mode1 register pin layout -#define PCA9685_MODE_RESTART (byte)0x80 -#define PCA9685_MODE_EXTCLK (byte)0x40 -#define PCA9685_MODE_AUTOINC (byte)0x20 -#define PCA9685_MODE_SLEEP (byte)0x10 -#define PCA9685_MODE_SUBADR1 (byte)0x08 -#define PCA9685_MODE_SUBADR2 (byte)0x04 -#define PCA9685_MODE_SUBADR3 (byte)0x02 -#define PCA9685_MODE_ALLCALL (byte)0x01 - -#define PCA9685_SW_RESET (byte)0x06 // Sent to address 0x00 to reset all devices on Wire line -#define PCA9685_PWM_FULL (uint16_t)0x01000 // Special value for full on/full off LEDx modes - -// To balance the load out in a weaved fashion, we use this offset table to distribute -// the load on the outputs in a more interleaving fashion than just a simple 16 offset -// per channel. We can set the off cycle value to be lower than the on cycle, which will -// put the high edge across the 0-4095 phase cycle range, which is supported by device. -static uint16_t phaseDistTable[16] = { 0, 2048, 1024, 3072, 512, 3584, 1536, 2560, 256, 3840, 1280, 2304, 3328, 768, 2816, 1792 }; - -#ifndef PCA9685_ENABLE_SOFTWARE_I2C -PCA9685::PCA9685(TwoWire& i2cWire, PCA9685_PhaseBalancer phaseBalancer) { - _i2cWire = &i2cWire; -#else -PCA9685::PCA9685(PCA9685_PhaseBalancer phaseBalancer) { -#endif - _i2cAddress = 0; - _phaseBalancer = phaseBalancer; - _isProxyAddresser = false; - _lastI2CError = 0; -} - -void PCA9685::resetDevices() { -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.println("PCA9685::resetDevices"); -#endif - - i2cWire_beginTransmission(0x00); - i2cWire_write(PCA9685_SW_RESET); - i2cWire_endTransmission(); - - delayMicroseconds(10); - -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - checkForErrors(); -#endif -} - -void PCA9685::init(byte i2cAddress, byte mode) { - if (_isProxyAddresser) return; - - // I2C 7-bit address is B 1 A5 A4 A3 A2 A1 A0 - // RW bit added by Arduino core TWI library - _i2cAddress = PCA9685_I2C_BASE_ADDRESS | (i2cAddress & 0x3F); - -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.print("PCA9685::init i2cAddress: 0x"); - Serial.println(_i2cAddress, HEX); -#endif - - writeRegister(PCA9685_MODE1_REG, PCA9685_MODE_RESTART | PCA9685_MODE_AUTOINC); - writeRegister(PCA9685_MODE2_REG, mode); -} - -#ifndef PCA9685_EXCLUDE_EXT_FUNC - -void PCA9685::initAsProxyAddresser(byte i2cAddress) { - _i2cAddress = i2cAddress & 0xFE; - _isProxyAddresser = true; - -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.print("PCA9685::initAsProxyAddresser i2cAddress: 0x"); - Serial.println(_i2cAddress, HEX); -#endif -} - -#endif - -byte PCA9685::getI2CAddress() { - return _i2cAddress; -} - -PCA9685_PhaseBalancer PCA9685::getPhaseBalancer() { - return _phaseBalancer; -} - -void PCA9685::setPWMFrequency(float pwmFrequency) { - if (pwmFrequency < 0 || _isProxyAddresser) return; - - // This equation comes from section 7.3.5 of the datasheet, but the rounding has been - // removed because it isn't needed. Lowest freq is 23.84, highest is 1525.88. - int preScalerVal = (25000000 / (4096 * pwmFrequency)) - 1; - if (preScalerVal > 255) preScalerVal = 255; - if (preScalerVal < 3) preScalerVal = 3; - -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.print("PCA9685::setPWMFrequency pwmFrequency: "); - Serial.print(pwmFrequency); - Serial.print(", preScalerVal: 0x"); - Serial.println(preScalerVal, HEX); -#endif - - // The PRE_SCALE register can only be set when the SLEEP bit of MODE1 register is set to logic 1. - byte mode1Reg = readRegister(PCA9685_MODE1_REG); - writeRegister(PCA9685_MODE1_REG, (mode1Reg = (mode1Reg & ~PCA9685_MODE_RESTART) | PCA9685_MODE_SLEEP)); - writeRegister(PCA9685_PRESCALE_REG, (byte)preScalerVal); - - // It takes 500us max for the oscillator to be up and running once SLEEP bit has been set to logic 0. - writeRegister(PCA9685_MODE1_REG, (mode1Reg = (mode1Reg & ~PCA9685_MODE_SLEEP) | PCA9685_MODE_RESTART)); - delayMicroseconds(500); -} - -void PCA9685::setChannelOn(int channel) { - if (channel < 0 || channel > 15) return; - -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.println("PCA9685::setChannelOn"); -#endif - - writeChannelBegin(channel); - writeChannelPWM(PCA9685_PWM_FULL, 0); // time_on = FULL; time_off = 0; - writeChannelEnd(); -} - -void PCA9685::setChannelOff(int channel) { - if (channel < 0 || channel > 15) return; - -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.println("PCA9685::setChannelOff"); -#endif - - writeChannelBegin(channel); - writeChannelPWM(0, PCA9685_PWM_FULL); // time_on = 0; time_off = FULL; - writeChannelEnd(); -} - -void PCA9685::setChannelPWM(int channel, uint16_t pwmAmount) { - if (channel < 0 || channel > 15) return; - -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.println("PCA9685::setChannelPWM"); -#endif - - writeChannelBegin(channel); - - uint16_t phaseBegin, phaseEnd; - getPhaseCycle(channel, pwmAmount, &phaseBegin, &phaseEnd); - - writeChannelPWM(phaseBegin, phaseEnd); - - writeChannelEnd(); -} - -void PCA9685::setChannelsPWM(int begChannel, int numChannels, const uint16_t *pwmAmounts) { - if (begChannel < 0 || begChannel > 15 || numChannels < 0) return; - if (begChannel + numChannels > 16) numChannels -= (begChannel + numChannels) - 16; - -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.print("PCA9685::setChannelsPWM numChannels: "); - Serial.println(numChannels); -#endif - - // In avr/libraries/Wire.h and avr/libraries/utility/twi.h, BUFFER_LENGTH controls - // how many channels can be written at once. Therefore, we loop around until all - // channels have been written out into their registers. - - while (numChannels > 0) { - writeChannelBegin(begChannel); - - int maxChannels = min(numChannels, (BUFFER_LENGTH - 1) / 4); - while (maxChannels-- > 0) { - uint16_t phaseBegin, phaseEnd; - getPhaseCycle(begChannel++, *pwmAmounts++, &phaseBegin, &phaseEnd); - - writeChannelPWM(phaseBegin, phaseEnd); - --numChannels; - } - - writeChannelEnd(); - if (_lastI2CError) return; - } -} - -#ifndef PCA9685_EXCLUDE_EXT_FUNC - -void PCA9685::setAllChannelsPWM(uint16_t pwmAmount) { -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.println("PCA9685::setAllChannelsPWM"); -#endif - - writeChannelBegin(-1); // Special value for ALLLED registers - - uint16_t phaseBegin, phaseEnd; - getPhaseCycle(-1, pwmAmount, &phaseBegin, &phaseEnd); - - writeChannelPWM(phaseBegin, phaseEnd); - - writeChannelEnd(); -} - -uint16_t PCA9685::getChannelPWM(int channel) { - if (channel < 0 || channel > 15 || _isProxyAddresser) return 0; - - byte regAddress = PCA9685_LED0_REG + (channel << 2); - -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.print("PCA9685::getChannelPWM channel: "); - Serial.print(channel); - Serial.print(", regAddress: 0x"); - Serial.println(regAddress, HEX); -#endif - - i2cWire_beginTransmission(_i2cAddress); - i2cWire_write(regAddress); - if (i2cWire_endTransmission()) { -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - checkForErrors(); -#endif - return 0; - } - - int bytesRead = i2cWire_requestFrom((uint8_t)_i2cAddress, (uint8_t)4); - if (bytesRead != 4) { - while (bytesRead-- > 0) - i2cWire_read(); -#ifdef PCA9685_ENABLE_SOFTWARE_I2C - i2c_stop(); // Manually have to send stop bit in software i2c mode -#endif - _lastI2CError = 4; -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - checkForErrors(); -#endif - return 0; - } - -#ifndef PCA9685_SWAP_PWM_BEG_END_REGS - uint16_t phaseBegin = (uint16_t)i2cWire_read(); - phaseBegin |= (uint16_t)i2cWire_read() << 8; - uint16_t phaseEnd = (uint16_t)i2cWire_read(); - phaseEnd |= (uint16_t)i2cWire_read() << 8; -#else - uint16_t phaseEnd = (uint16_t)i2cWire_read(); - phaseEnd |= (uint16_t)i2cWire_read() << 8; - uint16_t phaseBegin = (uint16_t)i2cWire_read(); - phaseBegin |= (uint16_t)i2cWire_read() << 8; -#endif - -#ifdef PCA9685_ENABLE_SOFTWARE_I2C - i2c_stop(); // Manually have to send stop bit in software i2c mode -#endif - -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.print(" PCA9685::getChannelPWM phaseBegin: "); - Serial.print(phaseBegin); - Serial.print(", phaseEnd: "); - Serial.println(phaseEnd); -#endif - - // See datasheet section 7.3.3 - uint16_t retVal; - if (phaseEnd >= PCA9685_PWM_FULL) - // Full OFF - // Figure 11 Example 4: full OFF takes precedence over full ON - // See also remark after Table 7 - retVal = 0; - else if (phaseBegin >= PCA9685_PWM_FULL) - // Full ON - // Figure 9 Example 3 - retVal = PCA9685_PWM_FULL; - else if (phaseBegin <= phaseEnd) - // start and finish in same cycle - // Section 7.3.3 example 1 - retVal = phaseEnd - phaseBegin; - else - // span cycles - // Section 7.3.3 example 2 - retVal = (phaseEnd + PCA9685_PWM_FULL) - phaseBegin; - -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.print(" PCA9685::getChannelPWM retVal: "); - Serial.println(retVal); -#endif - - return retVal; -} - -void PCA9685::enableAllCallAddress(byte i2cAddress) { - if (_isProxyAddresser) return; - - i2cAddress &= 0xFE; - -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.print("PCA9685::enableAllCallAddress i2cAddress: 0x"); - Serial.println(i2cAddress, HEX); -#endif - - writeRegister(PCA9685_ALLCALL_REG, i2cAddress); - - byte mode1Reg = readRegister(PCA9685_MODE1_REG); - writeRegister(PCA9685_MODE1_REG, (mode1Reg |= PCA9685_MODE_ALLCALL)); -} - -void PCA9685::enableSub1Address(byte i2cAddress) { - if (_isProxyAddresser) return; - - i2cAddress &= 0xFE; - -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.print("PCA9685::enableSub1Address i2cAddress: 0x"); - Serial.println(i2cAddress, HEX); -#endif - - writeRegister(PCA9685_SUBADR1_REG, i2cAddress); - - byte mode1Reg = readRegister(PCA9685_MODE1_REG); - writeRegister(PCA9685_MODE1_REG, (mode1Reg |= PCA9685_MODE_SUBADR1)); -} - -void PCA9685::enableSub2Address(byte i2cAddress) { - if (_isProxyAddresser) return; - - i2cAddress &= 0xFE; - -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.print("PCA9685::enableSub2Address i2cAddress: 0x"); - Serial.println(i2cAddress, HEX); -#endif - - writeRegister(PCA9685_SUBADR2_REG, i2cAddress); - - byte mode1Reg = readRegister(PCA9685_MODE1_REG); - writeRegister(PCA9685_MODE1_REG, (mode1Reg |= PCA9685_MODE_SUBADR2)); -} - -void PCA9685::enableSub3Address(byte i2cAddress) { - if (_isProxyAddresser) return; - - i2cAddress &= 0xFE; - -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.print("PCA9685::enableSub3Address i2cAddress: 0x"); - Serial.println(i2cAddress, HEX); -#endif - - writeRegister(PCA9685_SUBADR3_REG, i2cAddress); - - byte mode1Reg = readRegister(PCA9685_MODE1_REG); - writeRegister(PCA9685_MODE1_REG, (mode1Reg |= PCA9685_MODE_SUBADR3)); -} - -void PCA9685::disableAllCallAddress() { - if (_isProxyAddresser) return; - -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.println("PCA9685::disableAllCallAddress"); -#endif - - byte mode1Reg = readRegister(PCA9685_MODE1_REG); - writeRegister(PCA9685_MODE1_REG, (mode1Reg &= ~PCA9685_MODE_ALLCALL)); -} - -void PCA9685::disableSub1Address() { - if (_isProxyAddresser) return; - -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.println("PCA9685::disableSub1Address"); -#endif - - byte mode1Reg = readRegister(PCA9685_MODE1_REG); - writeRegister(PCA9685_MODE1_REG, (mode1Reg &= ~PCA9685_MODE_SUBADR1)); -} - -void PCA9685::disableSub2Address() { - if (_isProxyAddresser) return; - -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.println("PCA9685::disableSub2Address"); -#endif - - byte mode1Reg = readRegister(PCA9685_MODE1_REG); - writeRegister(PCA9685_MODE1_REG, (mode1Reg &= ~PCA9685_MODE_SUBADR2)); -} - -void PCA9685::disableSub3Address() { - if (_isProxyAddresser) return; - -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.println("PCA9685::disableSub3Address"); -#endif - - byte mode1Reg = readRegister(PCA9685_MODE1_REG); - writeRegister(PCA9685_MODE1_REG, (mode1Reg &= ~PCA9685_MODE_SUBADR3)); -} - -void PCA9685::enableExtClockLine() { -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.println("PCA9685::enableExtClockLine"); -#endif - - // The PRE_SCALE register can only be set when the SLEEP bit of MODE1 register is set to logic 1. - byte mode1Reg = readRegister(PCA9685_MODE1_REG); - writeRegister(PCA9685_MODE1_REG, (mode1Reg = (mode1Reg & ~PCA9685_MODE_RESTART) | PCA9685_MODE_SLEEP)); - writeRegister(PCA9685_MODE1_REG, (mode1Reg |= PCA9685_MODE_EXTCLK)); - - // It takes 500us max for the oscillator to be up and running once SLEEP bit has been set to logic 0. - writeRegister(PCA9685_MODE1_REG, (mode1Reg = (mode1Reg & ~PCA9685_MODE_SLEEP) | PCA9685_MODE_RESTART)); - delayMicroseconds(500); -} - -#endif - -byte PCA9685::getLastI2CError() { - return _lastI2CError; -} - -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - -static const char *textForI2CError(byte errorCode) { - switch (errorCode) { - case 0: - return "Success"; - case 1: - return "Data too long to fit in transmit buffer"; - case 2: - return "Received NACK on transmit of address"; - case 3: - return "Received NACK on transmit of data"; - default: - return "Other error"; - } -} - -void PCA9685::checkForErrors() { - if (_lastI2CError) { - Serial.print(" PCA9685::checkErrors lastI2CError: "); - Serial.print(_lastI2CError); - Serial.print(": "); - Serial.println(textForI2CError(getLastI2CError())); - } -} - -#endif - -void PCA9685::getPhaseCycle(int channel, uint16_t pwmAmount, uint16_t *phaseBegin, uint16_t *phaseEnd) { - // Set delay - if (channel < 0) { - // All channels - *phaseBegin = 0; - } - else if (_phaseBalancer == PCA9685_PhaseBalancer_Linear) { - // Distribute high phase area over entire phase range to balance load. - *phaseBegin = channel * (4096 / 16); - } - else if (_phaseBalancer == PCA9685_PhaseBalancer_Weaved) { - // Distribute high phase area over entire phase range to balance load. - *phaseBegin = phaseDistTable[channel]; - } - else { - *phaseBegin = 0; - } - - // See datasheet section 7.3.3 - if (pwmAmount == 0) { - // Full OFF => time_off[12] = 1; - *phaseEnd = PCA9685_PWM_FULL; - } - else if (pwmAmount >= PCA9685_PWM_FULL) { - // Full ON => time_on[12] = 1; time_off = ignored; - *phaseBegin |= PCA9685_PWM_FULL; - *phaseEnd = 0; - } - else { - *phaseEnd = *phaseBegin + pwmAmount; - if (*phaseEnd >= PCA9685_PWM_FULL) - *phaseEnd -= PCA9685_PWM_FULL; - } -} - -void PCA9685::writeChannelBegin(int channel) { - byte regAddress; - - if (channel != -1) - regAddress = PCA9685_LED0_REG + (channel * 0x04); - else - regAddress = PCA9685_ALLLED_REG; - -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.print(" PCA9685::writeChannelBegin channel: "); - Serial.print(channel); - Serial.print(", regAddress: 0x"); - Serial.println(regAddress, HEX); -#endif - - i2cWire_beginTransmission(_i2cAddress); - i2cWire_write(regAddress); -} - -void PCA9685::writeChannelPWM(uint16_t phaseBegin, uint16_t phaseEnd) { -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.print(" PCA9685::writeChannelPWM phaseBegin: "); - Serial.print(phaseBegin); - Serial.print(", phaseEnd: "); - Serial.println(phaseEnd); -#endif - -#ifndef PCA9685_SWAP_PWM_BEG_END_REGS - i2cWire_write(lowByte(phaseBegin)); - i2cWire_write(highByte(phaseBegin)); - i2cWire_write(lowByte(phaseEnd)); - i2cWire_write(highByte(phaseEnd)); -#else - i2cWire_write(lowByte(phaseEnd)); - i2cWire_write(highByte(phaseEnd)); - i2cWire_write(lowByte(phaseBegin)); - i2cWire_write(highByte(phaseBegin)); -#endif -} - -void PCA9685::writeChannelEnd() { - i2cWire_endTransmission(); - -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - checkForErrors(); -#endif -} - -void PCA9685::writeRegister(byte regAddress, byte value) { -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.print(" PCA9685::writeRegister regAddress: 0x"); - Serial.print(regAddress, HEX); - Serial.print(", value: 0x"); - Serial.println(value, HEX); -#endif - - i2cWire_beginTransmission(_i2cAddress); - i2cWire_write(regAddress); - i2cWire_write(value); - i2cWire_endTransmission(); - -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - checkForErrors(); -#endif -} - -byte PCA9685::readRegister(byte regAddress) { -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.print(" PCA9685::readRegister regAddress: 0x"); - Serial.println(regAddress, HEX); -#endif - - i2cWire_beginTransmission(_i2cAddress); - i2cWire_write(regAddress); - if (i2cWire_endTransmission()) { -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - checkForErrors(); -#endif - return 0; - } - - int bytesRead = i2cWire_requestFrom((uint8_t)_i2cAddress, (uint8_t)1); - if (bytesRead != 1) { - while (bytesRead-- > 0) - i2cWire_read(); -#ifdef PCA9685_ENABLE_SOFTWARE_I2C - i2c_stop(); // Manually have to send stop bit in software i2c mode -#endif - _lastI2CError = 4; -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - checkForErrors(); -#endif - return 0; - } - - byte retVal = i2cWire_read(); - -#ifdef PCA9685_ENABLE_SOFTWARE_I2C - i2c_stop(); // Manually have to send stop bit in software i2c mode -#endif - -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - Serial.print(" PCA9685::readRegister retVal: 0x"); - Serial.println(retVal, HEX); -#endif - - return retVal; -} - -#ifdef PCA9685_ENABLE_SOFTWARE_I2C -bool __attribute__((noinline)) i2c_start(uint8_t addr); -void __attribute__((noinline)) i2c_stop(void) asm("ass_i2c_stop"); -bool __attribute__((noinline)) i2c_write(uint8_t value) asm("ass_i2c_write"); -uint8_t __attribute__((noinline)) i2c_read(bool last); -#endif - -void PCA9685::i2cWire_beginTransmission(uint8_t addr) { - _lastI2CError = 0; -#ifndef PCA9685_ENABLE_SOFTWARE_I2C - _i2cWire->beginTransmission(addr); -#else - i2c_start(addr); -#endif -} - -uint8_t PCA9685::i2cWire_endTransmission(void) { -#ifndef PCA9685_ENABLE_SOFTWARE_I2C - return (_lastI2CError = _i2cWire->endTransmission()); -#else - i2c_stop(); - return (_lastI2CError = 0); -#endif -} - -uint8_t PCA9685::i2cWire_requestFrom(uint8_t addr, uint8_t len) { -#ifndef PCA9685_ENABLE_SOFTWARE_I2C - return _i2cWire->requestFrom(addr, len); -#else - i2c_start(addr | 0x01); - return (_readBytes = len); -#endif -} - -size_t PCA9685::i2cWire_write(uint8_t data) { -#ifndef PCA9685_ENABLE_SOFTWARE_I2C - return _i2cWire->write(data); -#else - return (size_t)i2c_write(data); -#endif -} - -uint8_t PCA9685::i2cWire_read(void) { -#ifndef PCA9685_ENABLE_SOFTWARE_I2C - return (uint8_t)(_i2cWire->read() & 0xFF); -#else - if (_readBytes > 1) { - _readBytes -= 1; - return (uint8_t)(i2c_read(false) & 0xFF); - } - else { - _readBytes = 0; - return (uint8_t)(i2c_read(true) & 0xFF); - } -#endif -} - -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - -void PCA9685::printModuleInfo() { - Serial.println(""); Serial.println(" ~~~ PCA9685 Module Info ~~~"); - - Serial.println(""); Serial.println("i2c Address:"); - Serial.print("0x"); - Serial.println(_i2cAddress, HEX); - - Serial.println(""); Serial.println("Phase Balancer:"); - switch (_phaseBalancer) { - case PCA9685_PhaseBalancer_None: - Serial.println("PCA9685_PhaseBalancer_None"); break; - case PCA9685_PhaseBalancer_Linear: - Serial.println("PCA9685_PhaseBalancer_Linear"); break; - case PCA9685_PhaseBalancer_Weaved: - Serial.println("PCA9685_PhaseBalancer_Weaved"); break; - default: - Serial.println(""); break; - } - - if (!_isProxyAddresser) { - Serial.println(""); Serial.println("Proxy Addresser:"); - Serial.println("false"); - - Serial.println(""); Serial.println("Mode1 Register:"); - byte mode1Reg = readRegister(PCA9685_MODE1_REG); - Serial.print("0x"); - Serial.print(mode1Reg, HEX); - Serial.print(", Bitset:"); - if (mode1Reg & PCA9685_MODE_RESTART) - Serial.print(" PCA9685_MODE_RESTART"); - if (mode1Reg & PCA9685_MODE_EXTCLK) - Serial.print(" PCA9685_MODE_EXTCLK"); - if (mode1Reg & PCA9685_MODE_AUTOINC) - Serial.print(" PCA9685_MODE_AUTOINC"); - if (mode1Reg & PCA9685_MODE_SLEEP) - Serial.print(" PCA9685_MODE_SLEEP"); - if (mode1Reg & PCA9685_MODE_SUBADR1) - Serial.print(" PCA9685_MODE_SUBADR1"); - if (mode1Reg & PCA9685_MODE_SUBADR2) - Serial.print(" PCA9685_MODE_SUBADR2"); - if (mode1Reg & PCA9685_MODE_SUBADR3) - Serial.print(" PCA9685_MODE_SUBADR3"); - if (mode1Reg & PCA9685_MODE_ALLCALL) - Serial.print(" PCA9685_MODE_ALLCALL"); - Serial.println(""); - - Serial.println(""); Serial.println("Mode2 Register:"); - byte mode2Reg = readRegister(PCA9685_MODE2_REG); - Serial.print("0x"); - Serial.print(mode2Reg, HEX); - Serial.print(", Bitset:"); - if (mode2Reg & PCA9685_MODE_INVRT) - Serial.print(" PCA9685_MODE_INVRT"); - if (mode2Reg & PCA9685_MODE_OCH_ONACK) - Serial.print(" PCA9685_MODE_OCH_ONACK"); - if (mode2Reg & PCA9685_MODE_OUTDRV_TPOLE) - Serial.print(" PCA9685_MODE_OUTDRV_TPOLE"); - if (mode2Reg & PCA9685_MODE_OUTNE_HIGHZ) - Serial.print(" PCA9685_MODE_OUTNE_HIGHZ"); - if (mode2Reg & PCA9685_MODE_OUTNE_TPHIGH) - Serial.print(" PCA9685_MODE_OUTNE_TPHIGH"); - Serial.println(""); - - Serial.println(""); Serial.println("SubAddress1 Register:"); - byte subAdr1Reg = readRegister(PCA9685_SUBADR1_REG); - Serial.print("0x"); - Serial.println(subAdr1Reg, HEX); - - Serial.println(""); Serial.println("SubAddress2 Register:"); - byte subAdr2Reg = readRegister(PCA9685_SUBADR2_REG); - Serial.print("0x"); - Serial.println(subAdr2Reg, HEX); - - Serial.println(""); Serial.println("SubAddress3 Register:"); - byte subAdr3Reg = readRegister(PCA9685_SUBADR3_REG); - Serial.print("0x"); - Serial.println(subAdr3Reg, HEX); - - Serial.println(""); Serial.println("AllCall Register:"); - byte allCallReg = readRegister(PCA9685_ALLCALL_REG); - Serial.print("0x"); - Serial.println(allCallReg, HEX); - } - else { - Serial.println(""); Serial.println("Proxy Addresser:"); - Serial.println("true"); - } -} - -#endif - - -#ifndef PCA9685_EXCLUDE_SERVO_EVAL - -PCA9685_ServoEvaluator::PCA9685_ServoEvaluator(uint16_t n90PWMAmount, uint16_t p90PWMAmount) { - n90PWMAmount = constrain(n90PWMAmount, 0, PCA9685_PWM_FULL); - p90PWMAmount = constrain(p90PWMAmount, n90PWMAmount, PCA9685_PWM_FULL); - - _coeff = new float[2]; - _isCSpline = false; - - _coeff[0] = n90PWMAmount; - _coeff[1] = (p90PWMAmount - n90PWMAmount) / 180.0f; -} - -PCA9685_ServoEvaluator::PCA9685_ServoEvaluator(uint16_t n90PWMAmount, uint16_t zeroPWMAmount, uint16_t p90PWMAmount) { - n90PWMAmount = constrain(n90PWMAmount, 0, PCA9685_PWM_FULL); - zeroPWMAmount = constrain(zeroPWMAmount, n90PWMAmount, PCA9685_PWM_FULL); - p90PWMAmount = constrain(p90PWMAmount, zeroPWMAmount, PCA9685_PWM_FULL); - - if (p90PWMAmount - zeroPWMAmount != zeroPWMAmount - n90PWMAmount) { - _coeff = new float[8]; - _isCSpline = true; - - // Cubic spline code adapted from: https://shiftedbits.org/2011/01/30/cubic-spline-interpolation/ - /* "THE BEER-WARE LICENSE" (Revision 42): Devin Lane wrote this [part]. As long as you retain - * this notice you can do whatever you want with this stuff. If we meet some day, and you - * think this stuff is worth it, you can buy me a beer in return. */ - - float x[3] = { 0, 90, 180 }; - float y[3] = { (float)n90PWMAmount, (float)zeroPWMAmount, (float)p90PWMAmount }; - float c[3], b[2], d[2], h[2], l[1], u[2], a[1], z[2]; // n = 3 - - h[0] = x[1] - x[0]; - u[0] = z[0] = 0; - c[2] = 0; - - for (int i = 1; i < 2; ++i) { - h[i] = x[i + 1] - x[i]; - l[i - 1] = (2 * (x[i + 1] - x[i - 1])) - h[i - 1] * u[i - 1]; - u[i] = h[i] / l[i - 1]; - a[i - 1] = (3 / h[i]) * (y[i + 1] - y[i]) - (3 / h[i - 1]) * (y[i] - y[i - 1]); - z[i] = (a[i - 1] - h[i - 1] * z[i - 1]) / l[i - 1]; - } - - for (int i = 1; i >= 0; --i) { - c[i] = z[i] - u[i] * c[i + 1]; - b[i] = (y[i + 1] - y[i]) / h[i] - (h[i] * (c[i + 1] + 2 * c[i])) / 3; - d[i] = (c[i + 1] - c[i]) / (3 * h[i]); - - _coeff[4 * i + 0] = y[i]; // a - _coeff[4 * i + 1] = b[i]; // b - _coeff[4 * i + 2] = c[i]; // c - _coeff[4 * i + 3] = d[i]; // d - } - } - else { - _coeff = new float[2]; - _isCSpline = false; - - _coeff[0] = n90PWMAmount; - _coeff[1] = (p90PWMAmount - n90PWMAmount) / 180.0f; - } -} - -PCA9685_ServoEvaluator::~PCA9685_ServoEvaluator() { - if (_coeff) delete[] _coeff; -} - -uint16_t PCA9685_ServoEvaluator::pwmForAngle(float angle) { - float retVal; - angle = constrain(angle + 90, 0, 180); - - if (!_isCSpline) { - retVal = _coeff[0] + (_coeff[1] * angle); - } - else { - if (angle <= 90) { - retVal = _coeff[0] + (_coeff[1] * angle) + (_coeff[2] * angle * angle) + (_coeff[3] * angle * angle * angle); - } - else { - angle -= 90; - retVal = _coeff[4] + (_coeff[5] * angle) + (_coeff[6] * angle * angle) + (_coeff[7] * angle * angle * angle); - } - } - - return (uint16_t)constrain((uint16_t)roundf(retVal), 0, PCA9685_PWM_FULL); -}; - -#endif diff --git a/PCA9685.h b/PCA9685.h deleted file mode 100644 index f3a6717..0000000 --- a/PCA9685.h +++ /dev/null @@ -1,245 +0,0 @@ -/* Arduino Library for the PCA9685 16-Channel PWM Driver Module. - Copyright (C) 2016 NachtRaveVL - Copyright (C) 2012 Kasper SkÃ¥rhøj - - This program is free software: you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation, either version 3 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . - - Created by Kasper SkÃ¥rhøj, August 3rd, 2012. - Forked by Vitska, June 18th, 2016. - Forked by NachtRaveVL, July 29th, 2016. - - PCA9685-Arduino - Version 1.2.14 -*/ - -#ifndef PCA9685_H -#define PCA9685_H - -// Library Setup - -// NOTE: It is recommended to avoid editing library files directly and instead use custom -// build flags. While most custom build systems support such, the Arduino IDE does not. -// Be aware that editing this file directly will affect all projects using this library. - -// Uncomment this define to enable use of the software i2c library (min 4MHz+ processor required). -//#define PCA9685_ENABLE_SOFTWARE_I2C 1 // http://playground.arduino.cc/Main/SoftwareI2CLibrary - -// Uncomment this define if wanting to exclude extended functionality from compilation. -//#define PCA9685_EXCLUDE_EXT_FUNC 1 - -// Uncomment this define if wanting to exclude ServoEvaluator assistant from compilation. -//#define PCA9685_EXCLUDE_SERVO_EVAL 1 - -// Uncomment this define to swap PWM low(begin)/high(end) phase values in register reads/writes (needed for some chip manufacturers). -//#define PCA9685_SWAP_PWM_BEG_END_REGS 1 - -// Uncomment this define to enable debug output. -//#define PCA9685_ENABLE_DEBUG_OUTPUT 1 - -// Hookup Callout: Servo Control -// -PLEASE READ- -// Many 180 degree controlled digital servos run on a 20ms pulse width (50Hz update -// frequency) based duty cycle, and do not utilize the entire pulse width for their -// -90/+90 degree control. Typically, 2.5% of the 20ms pulse width (0.5ms) is considered -// -90 degrees, and 12.5% of the 20ms pulse width (2.5ms) is considered +90 degrees. -// This roughly translates to raw PCA9685 PWM values of 102 and 512 (out of the 4096 -// value range) for -90 to +90 degree control, but may need to be adjusted to fit your -// specific servo (e.g. some I've tested run ~130 to ~525 for their -90/+90 degree -// control). -// -// -ALSO- -// Please be aware that driving some servos past their -90/+90 degrees of movement can -// cause a little plastic limiter pin to break off and get stuck inside of the gearing, -// which could potentially cause the servo to become jammed and no longer function. -// -// See the PCA9685_ServoEvaluator class to assist with calculating PWM values from Servo -// angle values, if you desire that level of fine tuning. - -#if defined(ARDUINO) && ARDUINO >= 100 -#include -#else -#include -#endif -#ifndef PCA9685_ENABLE_SOFTWARE_I2C -#include - -// Define BUFFER_LENGTH on platforms that don't natively define such. -#ifndef BUFFER_LENGTH -#ifdef I2C_BUFFER_LENGTH -#define BUFFER_LENGTH I2C_BUFFER_LENGTH -#else -#warning "i2c BUFFER_LENGTH not defined - using default of 32, which may not be supported by your microcontroller's hardware. Check Wire.h (or similar) file for your hardware and manually define to remove this warning." -#define BUFFER_LENGTH 32 -#endif -#endif // /ifndef BUFFER_LENGTH - -#endif // /ifndef PCA9685_ENABLE_SOFTWARE_I2C - -// Channel update strategy used when multiple channels are being updated in batch: -#define PCA9685_MODE_OCH_ONACK (byte)0x08 // Channel updates commit after individual channel update ACK signal, instead of after full-transmission STOP signal - -// Output-enabled/active-low-OE-pin=LOW driver control modes (see datasheet Table 12 and Fig 13, 14, and 15 concerning correct usage of INVRT and OUTDRV): -#define PCA9685_MODE_INVRT (byte)0x10 // Enables channel output polarity inversion (applicable only when active-low-OE-pin=LOW) -#define PCA9685_MODE_OUTDRV_TPOLE (byte)0x04 // Enables totem-pole (instead of open-drain) style structure to be used for driving channel output, allowing use of an external output driver -// NOTE: 1) Chipset's breakout must support this feature (most do, some don't) -// 2) When in this mode, INVRT mode should be set according to if an external N-type external driver (should use INVRT) or P-type external driver (should not use INVRT) is more optimal -// 3) From datasheet Table 6. subnote [1]: "Some newer LEDs include integrated Zener diodes to limit voltage transients, reduce EMI, and protect the LEDs, and these -MUST BE- driven only in the open-drain mode to prevent overheating the IC." - -// Output-not-enabled/active-low-OE-pin=HIGH driver control modes (see datasheet Section 7.4 concerning correct usage of OUTNE): -// NOTE: Active-low-OE pin is typically used to synchronize multiple PCA9685 devices together, or as an external dimming control signal. -#define PCA9685_MODE_OUTNE_HIGHZ (byte)0x02 // Sets all channel outputs to high-impedance state (applicable only when active-low-OE-pin=HIGH) -#define PCA9685_MODE_OUTNE_TPHIGH (byte)0x01 // Sets all channel outputs to HIGH (applicable only when in totem-pole mode and active-low-OE-pin=HIGH) - -#define PCA9685_MIN_CHANNEL 0 -#define PCA9685_MAX_CHANNEL 15 -#define PCA9685_CHANNEL_COUNT 16 - -typedef enum { - PCA9685_PhaseBalancer_None = -1, // Disables phase balancing, all high phase areas start at begining of cycle - PCA9685_PhaseBalancer_Linear = 0, // Balances all outputs linearly, 256 steps away from previous output - PCA9685_PhaseBalancer_Weaved, // Balances first few outputs better, steps away from previous shorten towards last output - - PCA9685_PhaseBalancer_Count -} PCA9685_PhaseBalancer; -// NOTE: Phase balancing essentially means that the start of the high phase cycle, for each channel, is shifted by some amount, so that a large voltage sink doesn't occur all at once. - -class PCA9685 { -public: -#ifndef PCA9685_ENABLE_SOFTWARE_I2C - // May use a different Wire instance than Wire. Some chipsets, such as Due/Zero/etc., - // have a Wire1 class instance that uses the SDA1/SCL1 lines instead. - // Supported i2c baud rates are 100kHz, 400kHz, and 1000kHz. - PCA9685(TwoWire& i2cWire = Wire, PCA9685_PhaseBalancer phaseBalancer = PCA9685_PhaseBalancer_Linear); -#else - // Minimum supported i2c baud rate is 100kHz, which means minimum supported processor - // speed is 4MHz+ while running i2c standard mode. For 400kHz i2c baud rate, minimum - // supported processor speed is 16MHz+ while running i2c fast mode. - PCA9685(PCA9685_PhaseBalancer phaseBalancer = PCA9685_PhaseBalancer_Linear); -#endif - - // Should be called only once in setup(), before any init()'s, but after Wire.begin(). - // Only should be called once on any Wire instance to do a software reset, which - // will affect all devices on that line. This helps when you're constantly rebuilding - // and reuploading to ensure all the devices on that line are reset properly. - void resetDevices(); - - // Called in setup(). The i2c address here is the value of the A0, A1, A2, A3, A4 and - // A5 pins ONLY, as the class takes care of its internal base address. i2cAddress - // should be a value between 0 and 61, since only 62 boards can be addressed. - void init(byte i2cAddress = 0, byte mode = PCA9685_MODE_OUTDRV_TPOLE); - -#ifndef PCA9685_EXCLUDE_EXT_FUNC - // Called in setup(). Used when instance talks through to AllCall/Sub1-Sub3 instances - // as a proxy object. Using this method will disable any method that performs a read - // or conflicts certain states. - void initAsProxyAddresser(byte i2cAddress = 0xE0); -#endif - - byte getI2CAddress(); - PCA9685_PhaseBalancer getPhaseBalancer(); - - // Min: 24Hz, Max: 1526Hz, Default: 200Hz (as Hz increases channel resolution widens, but raw pre-scaler value, as computed per datasheet, also becomes less affected inversly) - void setPWMFrequency(float pwmFrequency); - - // Turns channel either full on or full off - void setChannelOn(int channel); - void setChannelOff(int channel); - - // PWM amounts 0 - 4096, 0 full off, 4096 full on - void setChannelPWM(int channel, uint16_t pwmAmount); - void setChannelsPWM(int begChannel, int numChannels, const uint16_t *pwmAmounts); - -#ifndef PCA9685_EXCLUDE_EXT_FUNC - // Sets all channels, but won't distribute phases - void setAllChannelsPWM(uint16_t pwmAmount); - - // Returns PWM amounts 0 - 4096, 0 full off, 4096 full on - uint16_t getChannelPWM(int channel); - - // Enables multiple talk-through paths via i2c bus (lsb/bit0 must stay 0) - // To use, create a new class instance using initAsSubAddressed() with said address - void enableAllCallAddress(byte i2cAddress = 0xE0); - void enableSub1Address(byte i2cAddress = 0xE2); - void enableSub2Address(byte i2cAddress = 0xE4); - void enableSub3Address(byte i2cAddress = 0xE8); - void disableAllCallAddress(); - void disableSub1Address(); - void disableSub2Address(); - void disableSub3Address(); - - // Allows external clock line to be utilized (once enabled cannot be disabled) - void enableExtClockLine(); -#endif - - byte getLastI2CError(); - -#ifdef PCA9685_ENABLE_DEBUG_OUTPUT - void printModuleInfo(); - void checkForErrors(); -#endif - -private: -#ifndef PCA9685_ENABLE_SOFTWARE_I2C - TwoWire *_i2cWire; // Wire class instance to use -#endif - byte _i2cAddress; // Module's i2c address - PCA9685_PhaseBalancer _phaseBalancer; // Phase balancer scheme to distribute load across phase range - bool _isProxyAddresser; // Instance is a proxy for sub addressing (disables certain functionality) - byte _lastI2CError; // Last i2c error - - void getPhaseCycle(int channel, uint16_t pwmAmount, uint16_t *phaseBegin, uint16_t *phaseEnd); - - void writeChannelBegin(int channel); - void writeChannelPWM(uint16_t phaseBegin, uint16_t phaseEnd); - void writeChannelEnd(); - - void writeRegister(byte regAddress, byte value); - byte readRegister(byte regAddress); - -#ifdef PCA9685_ENABLE_SOFTWARE_I2C - uint8_t _readBytes; -#endif - void i2cWire_beginTransmission(uint8_t); - uint8_t i2cWire_endTransmission(void); - uint8_t i2cWire_requestFrom(uint8_t, uint8_t); - size_t i2cWire_write(uint8_t); - uint8_t i2cWire_read(void); -}; - -#ifndef PCA9685_EXCLUDE_SERVO_EVAL - -// Class to assist with calculating Servo PWM values from angle values -class PCA9685_ServoEvaluator { -public: - // Uses a linear interpolation method to quickly compute PWM output value. Uses - // default values of 2.5% and 12.5% of phase length for -90/+90. - PCA9685_ServoEvaluator(uint16_t n90PWMAmount = 102, uint16_t p90PWMAmount = 512); - - // Uses a cubic spline to interpolate due to an offsetted zero angle that isn't - // exactly between -90/+90. This takes more time to compute, but gives a more - // accurate PWM output value along the entire range. - PCA9685_ServoEvaluator(uint16_t n90PWMAmount, uint16_t zeroPWMAmount, uint16_t p90PWMAmount); - - ~PCA9685_ServoEvaluator(); - - // Returns the PWM value to use given the angle (-90 to +90) - uint16_t pwmForAngle(float angle); - -private: - float *_coeff; // a,b,c,d coefficient values - bool _isCSpline; // Cubic spline tracking, for _coeff length -}; - -#endif - -#endif diff --git a/README.md b/README.md index c5c2bec..852cc89 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # PCA9685-Arduino Arduino Library for the PCA9685 16-Channel PWM Driver Module. -**PCA9685-Arduino - Version 1.2.14** +**PCA9685-Arduino - Version 1.2.15** Library to control a PCA9685 16-channel PWM driver module from an Arduino board. Licensed under the copy-left GNU GPL v3 license. @@ -10,77 +10,197 @@ Created by Kasper SkÃ¥rhøj, August 3rd, 2012. Forked by Vitska, June 18th, 2016. Forked by NachtRaveVL, July 29th, 2016. -This library allows communication with boards running a PCA6985 16-channel PWM driver module. It supports a wide range of available functionality, from setting the output PWM frequecy, allowing multi-device proxy addressing, and provides an assistant class for working with Servos. Newer versions should work with PlatformIO, ESP32/8266, Teensy, and others (although one might want to ensure i2c BUFFER_LENGTH is properly defined for those architectures). +This library allows communication with boards running a PCA6985 16-channel PWM driver module. It supports a wide range of available functionality, from setting the output PWM frequecy, allowing multi-device proxy addressing, and provides an assistant class for working with Servos. -The datasheet for the IC is available from . +Made primarily for Arduino microcontrollers, but should work with PlatformIO, ESP32/8266, Teensy, and others - although one might want to ensure BUFFER_LENGTH (or I2C_BUFFER_LENGTH) and WIRE_INTERFACES_COUNT is properly defined for any architecture used. + +The datasheet for the IC is available at . ## Library Setup +### Installation + +The easiest way to install this library is to utilize the Arduino IDE library manager, or through a package manager such as PlatformIO. Otherwise, simply download this library and extract its files into a `PCA9685-Arduino` folder in your Arduino custom libraries folder, typically found in your `[My ]Documents\Arduino\libraries` folder (Windows), or `~/Documents/Arduino/libraries/` folder (Linux/OSX). + ### Header Defines -There are several defines inside of the library's main header file that allow for more fine-tuned control of the library. You may edit and uncomment these lines directly, or supply them as a compilation flag via custom build system. While editing the main header file isn't the most ideal, it is often the easiest way when using the Arduino IDE, as it doesn't support custom build flags. Be aware that editing this header file directly will affect all projects on your system using this library. +There are several defines inside of the library's main header file that allow for more fine-tuned control of the library. You may edit and uncomment these lines directly, or supply them via custom build flags. While editing the main header file isn't ideal, it is often the easiest given the Arduino IDE's limited custom build flag support. Note that editing the library's main header file directly will affect all projects compiled on your system using those modified library files. -In PCA9685.h: -```Arduino -// Uncomment this define to enable use of the software i2c library (min 4MHz+ processor required). -//#define PCA9685_ENABLE_SOFTWARE_I2C 1 // http://playground.arduino.cc/Main/SoftwareI2CLibrary +Alternatively, you may also refer to on how to define custom build flags manually via modifying the platform[.local].txt file. Note that editing such directly will affect all other projects compiled on your system using those modified platform framework files. -// Uncomment this define if wanting to exclude extended functionality from compilation. -//#define PCA9685_EXCLUDE_EXT_FUNC 1 +From PCA9685.h: +```Arduino +// Uncomment or -D this define to enable use of the software i2c library (min 4MHz+ processor). +//#define PCA9685_ENABLE_SOFTWARE_I2C // http://playground.arduino.cc/Main/SoftwareI2CLibrary -// Uncomment this define if wanting to exclude ServoEvaluator assistant from compilation. -//#define PCA9685_EXCLUDE_SERVO_EVAL 1 +// Uncomment or -D this define to swap PWM low(begin)/high(end) phase values in register reads/writes (needed for some chip manufacturers). +//#define PCA9685_SWAP_PWM_BEG_END_REGS -// Uncomment this define to enable debug output. -//#define PCA9685_ENABLE_DEBUG_OUTPUT 1 +// Uncomment or -D this define to enable debug output. +//#define PCA9685_ENABLE_DEBUG_OUTPUT ``` ### Library Initialization -There are several initialization mode flags exposed through this library that are used for more fine-tuned control. These flags are expected to be provided to the library's `init(...)` function, commonly called inside of the sketch's `setup()` function. These init mode flags can be treated as a bitfield, and can be bitwise-OR'ed together to combine multiple flags together. The default init mode of the library, if left unspecified, is `PCA9685_MODE_OUTDRV_TPOLE`, which seems to work for most of the PCA9685 breakouts on market, but may be incorrect for custom PCA9685 integrations. +There are several initialization mode settings exposed through this library that are used for more fine-tuned control. -See Section 7.3.2 of the datasheet for more details. +#### Class Instantiation -From PCA9685.h: +The library's class object must first be instantiated, commonly at the top of the sketch where pin setups are defined (or exposed through some other mechanism), which makes a call to the library's class constructor. The constructor allows one to set the module's i2c address, i2c Wire class instance, and lastly i2c clock speed (most i2c parameters being ommitted when in software i2c mode). The default constructor values of the library, if left unspecified, is i2c address `B000000`, and i2c Wire class instance `Wire` @`400k`Hz. + +From PCA9685.h, in class PCA9685, when in hardware i2c mode: ```Arduino -// Channel update strategy used when multiple channels are being updated in batch: -#define PCA9685_MODE_OCH_ONACK (byte)0x08 // Channel updates commit after individual channel update ACK signal, instead of after full-transmission STOP signal - -// Output-enabled/active-low-OE-pin=LOW driver control modes (see datasheet Table 12 and Fig 13, 14, and 15 concerning correct usage of INVRT and OUTDRV): -#define PCA9685_MODE_INVRT (byte)0x10 // Enables channel output polarity inversion (applicable only when active-low-OE-pin=LOW) -#define PCA9685_MODE_OUTDRV_TPOLE (byte)0x04 // Enables totem-pole (instead of open-drain) style structure to be used for driving channel output, allowing use of an external output driver -// NOTE: 1) Chipset's breakout must support this feature (most do, some don't) -// 2) When in this mode, INVRT mode should be set according to if an external N-type external driver (should use INVRT) or P-type external driver (should not use INVRT) is more optimal -// 3) From datasheet Table 6. subnote [1]: "Some newer LEDs include integrated Zener diodes to limit voltage transients, reduce EMI, and protect the LEDs, and these -MUST BE- driven only in the open-drain mode to prevent overheating the IC." - -// Output-not-enabled/active-low-OE-pin=HIGH driver control modes (see datasheet Section 7.4 concerning correct usage of OUTNE): -// NOTE: Active-low-OE pin is typically used to synchronize multiple PCA9685 devices together, or as an external dimming control signal. -#define PCA9685_MODE_OUTNE_HIGHZ (byte)0x02 // Sets all channel outputs to high-impedance state (applicable only when active-low-OE-pin=HIGH) -#define PCA9685_MODE_OUTNE_TPHIGH (byte)0x01 // Sets all channel outputs to HIGH (applicable only when in totem-pole mode and active-low-OE-pin=HIGH) + // Library constructor. Typically called during class instantiation, before setup(). + // The i2c address should be the value of the A5-A0 pins, as the class handles the + // module's base i2c address. It should be a value between 0 and 61, which gives a + // maximum of 62 modules that can be addressed on the same i2c line. + // Boards with more than one i2c line (e.g. Due/Mega/etc.) can supply a different + // Wire instance, such as Wire1 (using SDA1/SCL1), Wire2 (using SDA2/SCL2), etc. + // Supported i2c clock speeds are 100kHz, 400kHz (default), and 1000kHz. + PCA9685(byte i2cAddress = B000000, TwoWire& i2cWire = Wire, uint32_t i2cSpeed = 400000); + + // Convenience constructor for custom Wire instance. See main constructor. + PCA9685(TwoWire& i2cWire, uint32_t i2cSpeed = 400000, byte i2cAddress = B000000); ``` -## Hookup Callouts +From PCA9685.h, in class PCA9685, when in software i2c mode (see examples for sample usage): +```Arduino + // Library constructor. Typically called during class instantiation, before setup(). + // The i2c address should be the value of the A5-A0 pins, as the class handles the + // module's base i2c address. It should be a value between 0 and 61, which gives a + // maximum of 62 modules that can be addressed on the same i2c line. + // Minimum supported i2c clock speed is 100kHz, which sets minimum processor speed at + // 4MHz+ running in i2c standard mode. For up to 400kHz i2c clock speeds, minimum + // processor speed is 16MHz+ running in i2c fast mode. + PCA9685(byte i2cAddress = B000000); +``` -### Servo Control +#### Device Initialization -Many 180 degree controlled digital servos run on a 20ms pulse width (50Hz update frequency) based duty cycle, and do not utilize the entire pulse width for their -90/+90 degree control. Typically, 2.5% of the 20ms pulse width (0.5ms) is considered -90 degrees, and 12.5% of the 20ms pulse width (2.5ms) is considered +90 degrees. This roughly translates to raw PCA9685 PWM values of 102 and 512 (out of the 4096 value range) for -90 to +90 degree control, but may need to be adjusted to fit your specific servo (e.g. some I've tested run ~130 to ~525 for their -90/+90 degree control). +Additionally, a call is expected to be provided to the library class object's `init(...)` or `initAsProxyAddresser()` methods, commonly called inside of the sketch's `setup()` function. The `init(...)` method allows one to set the module's driver mode, enabled/disabled output settings, channel update mode, and phase balancer scheme, while the `initAsProxyAddresser()` method allows one to setup the object as a proxy addresser (see examples for sample usage). The default init values of the library, if left unspecified, is `PCA9685_OutputDriverMode_TotemPole`, `PCA9685_OutputEnabledMode_Normal`, `PCA9685_OutputDisabledMode_Low`, `PCA9685_ChannelUpdateMode_AfterStop`, and `PCA9685_PhaseBalancer_None` which seems to work for most of the PCA9685 breakouts on market, but should be set according to your setup. -Also, please be aware that driving some servos past their -90/+90 degrees of movement can cause a little plastic limiter pin to break off and get stuck inside of the gearing, which could potentially cause the servo to become jammed and no longer function. +See Section 7.3.2 of the datasheet for more details. -See the PCA9685_ServoEvaluator class to assist with calculating PWM values from Servo angle values, if you desire that level of fine tuning. +From PCA9685.h, in class PCA9685, for standard init: +```Arduino + // Initializes module. Typically called in setup(). + // See individual enums for more info. + void init(PCA9685_OutputDriverMode driverMode = PCA9685_OutputDriverMode_TotemPole, + PCA9685_OutputEnabledMode enabledMode = PCA9685_OutputEnabledMode_Normal, + PCA9685_OutputDisabledMode disabledMode = PCA9685_OutputDisabledMode_Low, + PCA9685_ChannelUpdateMode updateMode = PCA9685_ChannelUpdateMode_AfterStop, + PCA9685_PhaseBalancer phaseBalancer = PCA9685_PhaseBalancer_None); + + // Convenience initializer for custom phase balancer. See main init method. + void init(PCA9685_PhaseBalancer phaseBalancer, + PCA9685_OutputDriverMode driverMode = PCA9685_OutputDriverMode_TotemPole, + PCA9685_OutputEnabledMode enabledMode = PCA9685_OutputEnabledMode_Normal, + PCA9685_OutputDisabledMode disabledMode = PCA9685_OutputDisabledMode_Low, + PCA9685_ChannelUpdateMode updateMode = PCA9685_ChannelUpdateMode_AfterStop); +``` -## Memory Callouts +From PCA9685.h, in class PCA9685, for init as a proxy addresser (see examples for sample usage): +```Arduino + // Initializes module as a proxy addresser. Typically called in setup(). Used when + // instance talks through to AllCall/Sub1-Sub3 instances as a proxy object. Using + // this method will disable any method that performs a read or conflicts with certain + // states. Proxy addresser i2c addresses must be >= 0xE0, with defaults provided via + // PCA9685_I2C_DEF_[ALLCALL|SUB[1-3]]_PROXYADR defines. + void initAsProxyAddresser(); +``` -### Extended Functions +From PCA9685.h: +```Arduino +// Output driver control mode (see datasheet Table 12 and Fig 13, 14, and 15 concerning correct +// usage of OUTDRV). +enum PCA9685_OutputDriverMode { + PCA9685_OutputDriverMode_OpenDrain, // Module outputs in an open-drain (aka direct connection) style structure with 400mA @5v total sink current, useful for LEDs and low-power Servos + PCA9685_OutputDriverMode_TotemPole, // Module outputs in a totem-pole (aka push-pull) style structure with 400mA @5v total sink current and 160mA total source current, useful for external drivers (default) +}; +// NOTE: Totem-pole mode should be used when an external N-type or P-type driver is in +// use, which provides actual sourcing current while open-drain mode doesn't. At max +// channel capacity, the sink current limit is 25mA@5v per channel while the source +// current limit, in totem-pole mode, is 10mA@5v per channel. However, from datasheet +// Table 6. subnote [1]: "Some newer LEDs include integrated Zener diodes to limit +// voltage transients, reduce EMI, and protect the LEDs, and these -MUST- be driven only +// in the open-drain mode to prevent over-heating the IC." Also from datasheet, Section +// 10. question 5: "in the push-pull architecture there is a low resistance path to GND +// through the Zener and this [causes] the IC to overheat." + +// Output-enabled/active-low-OE-pin=LOW driver output mode (see datasheet Table 12 and +// Fig 13, 14, and 15 concerning correct usage of INVRT). +enum PCA9685_OutputEnabledMode { + PCA9685_OutputEnabledMode_Normal, // When OE is enabled/LOW, channels output a normal signal, useful for N-type external drivers (default) + PCA9685_OutputEnabledMode_Inverted, // When OE is enabled/LOW, channels output an inverted signal, useful for P-type external drivers or direct connection +}; +// NOTE: Polarity inversion is often set according to if an external N-type driver +// (should not use INVRT) or external P-type driver/direct connection (should use INVRT) +// is used. Most breakouts have just a 220Ω resistor between the individual channel +// outputs of the IC and PWM output pins, which is useful when powering LEDs. The V+ rail +// of most breakouts can connect through a 10v 1000μF decoupling capacitor, typically +// already installed on most breakouts, which can reduce voltage spikes and ground bounce +// during phase shifts at the start/end of the PWM high phase when many channel devices +// are connected together. See https://forums.adafruit.com/viewtopic.php?f=8&t=127421 and +// https://forums.adafruit.com/viewtopic.php?f=8&t=162688 for information on installing +// a decoupling capacitor if need arises. + +// Output-not-enabled/active-low-OE-pin=HIGH driver output mode (see datasheet Section +// 7.4 concerning correct usage of OUTNE). +enum PCA9685_OutputDisabledMode { + PCA9685_OutputDisabledMode_Low, // When OE is disabled/HIGH, channels output a LOW signal (default) + PCA9685_OutputDisabledMode_High, // When OE is disabled/HIGH, channels output a HIGH signal (only available in totem-pole mode) + PCA9685_OutputDisabledMode_Floating, // When OE is disabled/HIGH, channel outputs go into a floating (aka high-impedance/high-Z) state, which may be further refined via external pull-up/pull-down resistors +}; +// NOTE: Active-low-OE pin is typically used to synchronize multiple PCA9685 devices +// together, but can also be used as an external dimming control signal. + +// Channel update strategy used when multiple channels are being updated in batch. +enum PCA9685_ChannelUpdateMode { + PCA9685_ChannelUpdateMode_AfterStop, // Channel updates commit after full-transmission STOP signal (default) + PCA9685_ChannelUpdateMode_AfterAck, // Channel updates commit after individual channel update ACK signal +}; + +// Software-based phase balancing scheme. +enum PCA9685_PhaseBalancer { + PCA9685_PhaseBalancer_None, // Disables software-based phase balancing, relying on installed hardware to handle current sinkage (default) + PCA9685_PhaseBalancer_Linear, // Uses linear software-based phase balancing, with each channel being a preset 16 steps (out of the 4096/12-bit value range) away from previous channel (may cause LED flickering/skipped-cycles on PWM changes) +}; +// NOTE: Software-based phase balancing attempts to further mitigate ground bounce and +// voltage spikes during phase shifts at the start/end of the PWM high phase by shifting +// the leading edge of each successive PWM high phase by some amount. This helps make +// the current sinks occur over the entire duty cycle range instead of all together at +// once. Software-based phase balancing can be useful in certain situations, but in +// practice has been the source of many problems, including the case whereby the PCA9685 +// will skip a cycle between PWM changes when the leading/trailing edge is shifted past a +// certain point. While we may revisit this idea in the future, for now we're content on +// leaving None as the default, and limiting the shift that Linear applies. +``` -This library has an extended list of functionality for those who care to dive into such, but isn't always particularly the most useful for various general use cases. If one uncomments the line below inside the main header file (or defines it via custom build flag), this extended functionality can be manually compiled-out. +#### Device Reset -In PCA9685.h: +If you are constantly re-building and re-uploading during development, it may be wise to include a call to the library's `resetDevices()` method in order to reset all devices shared across the supplied Wire instance. This way you can ensure all devices on that i2c line start from a clean state. + +From PCA9685.h, in class PCA9685: ```Arduino -// Uncomment this define if wanting to exclude extended functionality from compilation. -#define PCA9685_EXCLUDE_EXT_FUNC 1 + // Resets modules. Typically called in setup(), before any init()'s. Calling will + // perform a software reset on all PCA9685 devices on the Wire instance, ensuring + // that all PCA9685 devices on that line are properly reset. + void resetDevices(); ``` +## Hookup Callouts + +### Servo Control + +* Many digital servos run on a 20ms pulse width (50Hz update frequency) based duty cycle, and do not utilize the entire pulse width for their control. +* Typically, 2.5% of the 20ms pulse width (0.5ms) represents -90° offset, and 12.5% of the 20ms pulse width (2.5ms) represents +90° offset. + * This roughly translates to raw PCA9685 PWM values of 102 and 512 (out of the 4096/12-bit value range) for their -90°/+90° offset control. + * However, these may need to be adjusted to fit your specific servo (e.g. some we've tested run ~130 to ~525 for their -90°/+90° offset control). +* Be aware that driving some 180° servos too far past their -90°/+90° operational range can cause a little plastic limiter pin to break off and get stuck inside of the servo's gearing, which could potentially cause the servo to become jammed and no longer function. +* Continuous servos operate in much the same fashion as 180° servos, but instead of the 2.5%/12.5% pulse width controlling a -90°/+90° offset it controls a -1x/+1x speed multiplier, with 0x being parked/no-movement and -1x/+1x being maximum speed in either direction. + +See the `PCA9685_ServoEval` class to assist with calculating PWM values from Servo angle/speed values, if you desire that level of fine tuning. + ## Example Usage Below are several examples of library usage. @@ -88,27 +208,28 @@ Below are several examples of library usage. ### Simple Example ```Arduino -#include #include "PCA9685.h" -PCA9685 pwmController; // Library using default Wire and default linear phase balancing scheme +PCA9685 pwmController; // Library using default B000000 (A5-A0) i2c address, and default Wire @400kHz void setup() { - Serial.begin(115200); + Serial.begin(115200); // Begin Serial and Wire interfaces + Wire.begin(); - Wire.begin(); // Wire must be started first - Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz + pwmController.resetDevices(); // Resets all PCA9685 devices on i2c line - pwmController.resetDevices(); // Software resets all PCA9685 devices on Wire line + pwmController.init(); // Initializes module using default totem-pole driver mode, and default disabled phase balancer - pwmController.init(B000000); // Address pins A5-A0 set to B000000, default mode settings - pwmController.setPWMFrequency(100); // Default is 200Hz, supports 24Hz to 1526Hz + pwmController.setPWMFrequency(100); // Set PWM freq to 100Hz (default is 200Hz, supports 24Hz to 1526Hz) - pwmController.setChannelPWM(0, 128 << 4); // Set PWM to 128/255, but in 4096 land + pwmController.setChannelPWM(0, 128 << 4); // Set PWM to 128/255, shifted into 4096-land Serial.println(pwmController.getChannelPWM(0)); // Should output 2048, which is 128 << 4 } +void loop() { +} + ``` ### Batching Example @@ -116,27 +237,25 @@ void setup() { In this example, we randomly select PWM frequencies on all 12 outputs and allow them to drive for 5 seconds before changing them. ```Arduino -#include #include "PCA9685.h" -PCA9685 pwmController; // Library using default Wire and default linear phase balancing scheme +PCA9685 pwmController(B010101); // Library using B010101 (A5-A0) i2c address, and default Wire @400kHz void setup() { - Serial.begin(115200); + Serial.begin(115200); // Begin Serial and Wire interfaces + Wire.begin(); - Wire.begin(); // Wire must be started first - Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz + pwmController.resetDevices(); // Resets all PCA9685 devices on i2c line - pwmController.resetDevices(); // Software resets all PCA9685 devices on Wire line + pwmController.init(); // Initializes module using default totem-pole driver mode, and default phase balancer - pwmController.init(B010101); // Address pins A5-A0 set to B010101, default mode settings - pwmController.setPWMFrequency(500); // Default is 200Hz, supports 24Hz to 1526Hz + pwmController.setPWMFrequency(500); // Set PWM freq to 500Hz (default is 200Hz, supports 24Hz to 1526Hz) randomSeed(analogRead(0)); // Use white noise for our randomness } void loop() { - word pwms[12]; + uint16_t pwms[12]; pwms[0] = random(0, 4096); pwms[1] = random(0, 4096); pwms[2] = random(0, 4096); @@ -152,44 +271,48 @@ void loop() { pwmController.setChannelsPWM(0, 12, pwms); delay(5000); - // Note: Only 7 channels can be written in one i2c transaction due to a - // BUFFER_LENGTH limit of 32, so 12 channels will take two i2c transactions. + // NOTE: Many chips use a BUFFER_LENGTH size of 32, and in that case writing 12 + // channels will take 2 i2c transactions because only 7 channels can fit in a single + // i2c buffer transaction at a time. This may cause a slight offset flicker between + // the first 7 and remaining 5 channels, but can be offset by experimenting with a + // channel update mode of PCA9685_ChannelUpdateMode_AfterAck. This will make each + // channel update immediately upon sending of the Ack signal after each PWM command + // is executed rather than at the Stop signal at the end of the i2c transaction. } ``` ### Multi-Device Proxy Example -In this example, we use a special instance to control other modules attached to it via the ALL_CALL register. +In this example, we use a special instance to control other modules attached to it via the `ALL_CALL` register. ```Arduino -#include #include "PCA9685.h" -PCA9685 pwmController1; // Library using default Wire and default linear phase balancing scheme -PCA9685 pwmController2; // Library using default Wire and default linear phase balancing scheme +PCA9685 pwmController1(B000000); // Library using B000000 (A5-A0) i2c address, and default Wire @400kHz +PCA9685 pwmController2(B000001); // Library using B000001 (A5-A0) i2c address, and default Wire @400kHz -PCA9685 pwmControllerAll; // Not a real device, will act as a proxy to pwmController1 and pwmController2 +// Not a real device, will act as a proxy to pwmController1 and pwmController2, using all-call i2c address 0xE0, and default Wire @400kHz +PCA9685 pwmControllerAll(PCA9685_I2C_DEF_ALLCALL_PROXYADR); void setup() { - Serial.begin(115200); + Serial.begin(115200); // Begin Serial and Wire interfaces + Wire.begin(); - Wire.begin(); // Wire must be started first - Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz + pwmControllerAll.resetDevices(); // Resets all PCA9685 devices on i2c line - pwmController1.resetDevices(); // Software resets all PCA9685 devices on Wire line (including pwmController2 in this case) + pwmController1.init(); // Initializes first module using default totem-pole driver mode, and default disabled phase balancer + pwmController2.init(); // Initializes second module using default totem-pole driver mode, and default disabled phase balancer - pwmController1.init(B000000); // Address pins A5-A0 set to B000000, default mode settings - pwmController2.init(B000001); // Address pins A5-A0 set to B000001, default mode settings + pwmControllerAll.initAsProxyAddresser(); // Initializes 'fake' module as all-call proxy addresser + + // Enables all-call support to module from 'fake' all-call proxy addresser + pwmController1.enableAllCallAddress(pwmControllerAll.getI2CAddress()); + pwmController2.enableAllCallAddress(pwmControllerAll.getI2CAddress()); // On both pwmController1.setChannelOff(0); // Turn channel 0 off pwmController2.setChannelOff(0); // On both - pwmController1.enableAllCallAddress(); // Default address of 0xE0 - pwmController2.enableAllCallAddress(); // Same default address - - pwmControllerAll.initAsProxyAddresser(); // Same default address of 0x0E as used in enable above - pwmControllerAll.setChannelPWM(0, 4096); // Enables full on on both pwmController1 and pwmController2 Serial.println(pwmController1.getChannelPWM(0)); // Should output 4096 @@ -199,40 +322,41 @@ void setup() { // disabled - typically anything that involves a read command being issued. } +void loop() { +} + ``` ### Servo Evaluator Example -In this example, we utilize the ServoEvaluator class to assist with setting PWM frequencies when working with servos. +In this example, we utilize the `PCA9685_ServoEval` class to assist with setting PWM frequencies when working with servos. -We will be using Wire1, which is only available on boards with SDA1/SCL1 (Due, Zero, etc.) - change to Wire if Wire1 is unavailable. +We will be using `Wire1`, which is only available on boards with SDA1/SCL1 (e.g. Due/Mega/etc.) - change to `Wire` if `Wire1` is unavailable. ```Arduino -#include #include "PCA9685.h" -PCA9685 pwmController(Wire1, PCA9685_PhaseBalancer_Weaved); // Library using Wire1 and weaved phase balancing scheme +PCA9685 pwmController(Wire1); // Library using Wire1 @400kHz, and default B000000 (A5-A0) i2c address // Linearly interpolates between standard 2.5%/12.5% phase length (102/512) for -90°/+90° -PCA9685_ServoEvaluator pwmServo1; +PCA9685_ServoEval pwmServo1; // Testing our second servo has found that -90° sits at 128, 0° at 324, and +90° at 526. // Since 324 isn't precisely in the middle, a cubic spline will be used to smoothly // interpolate PWM values, which will account for said discrepancy. Additionally, since -// 324 is closer to 128 than 526, there is less resolution in the -90° to 0° range, and -// more in the 0° to +90° range. -PCA9685_ServoEvaluator pwmServo2(128,324,526); +// 324 is closer to 128 than 526, there is slightly less resolution in the -90° to 0° +// range while slightly more in the 0° to +90° range. +PCA9685_ServoEval pwmServo2(128,324,526); void setup() { - Serial.begin(115200); + Serial.begin(115200); // Begin Serial and Wire1 interfaces + Wire1.begin(); - Wire1.begin(); // Wire must be started first - Wire1.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz + pwmController.resetDevices(); // Resets all PCA9685 devices on i2c line - pwmController.resetDevices(); // Software resets all PCA9685 devices on Wire line + pwmController.init(); // Initializes module using default totem-pole driver mode, and default disabled phase balancer - pwmController.init(B000000); // Address pins A5-A0 set to B000000, default mode settings - pwmController.setPWMFrequency(50); // 50Hz provides 20ms standard servo phase length + pwmController.setPWMFreqServo(); // 50Hz provides standard 20ms servo phase length pwmController.setChannelPWM(0, pwmServo1.pwmForAngle(-90)); Serial.println(pwmController.getChannelPWM(0)); // Should output 102 for -90° @@ -259,102 +383,123 @@ void setup() { Serial.println(pwmController.getChannelPWM(1)); // Should output 526 for +90° } +void loop() { +} + ``` -### Software I2C Example +### Software i2c Example -In this example, we utilize the software I2C functionality for chips that do not have a hardware I2C bus. +In this example, we utilize a popular software i2c library for chips that do not have a hardware i2c bus, available at . -If one uncomments the line below inside the main header file (or defines it via custom build flag), software I2C mode for the library will be enabled. +If one uncomments the line below inside the main header file (or defines it via custom build flag), software i2c mode for the library will be enabled. Additionally, you will need to correctly define `SCL_PIN`, `SCL_PORT`, `SDA_PIN`, and `SDA_PORT` according to your setup. `I2C_FASTMODE=1` should be set for 16MHz+ processors. Lastly note that, while in software i2c mode, the i2c clock speed returned by the library (via `getI2CSpeed()`) is only an upper bound and may not represent the actual i2c clock speed set nor achieved. In PCA9685.h: ```Arduino -// Uncomment this define to enable use of the software i2c library (min 4MHz+ processor required). -#define PCA9685_ENABLE_SOFTWARE_I2C 1 // http://playground.arduino.cc/Main/SoftwareI2CLibrary +// Uncomment or -D this define to enable use of the software i2c library (min 4MHz+ processor). +#define PCA9685_ENABLE_SOFTWARE_I2C // http://playground.arduino.cc/Main/SoftwareI2CLibrary +``` +Alternatively, in platform[.local].txt: +```Arduino +build.extra_flags=-DPCA9685_ENABLE_SOFTWARE_I2C ``` In main sketch: ```Arduino #include "PCA9685.h" -#define SCL_PIN 2 // Setup defines are written before library include -#define SCL_PORT PORTD +// Setup defines for SoftI2CMaster are written before library include. That is because +// its header contains the full code definition, and should thus be included only once. +// The values for SCL_PORT and SDA_PORT are dependent upon which pins are used - refer to +// http://www.arduino.cc/en/Reference/PortManipulation to determine what you should use. +#define SCL_PIN 2 +#define SCL_PORT PORTD #define SDA_PIN 0 -#define SDA_PORT PORTC +#define SDA_PORT PORTC #if F_CPU >= 16000000 -#define I2C_FASTMODE 1 // Running a 16MHz processor allows us to use I2C fast mode +#define I2C_FASTMODE 1 // Running a 16MHz processor allows us to use i2c fast mode #endif -#include "SoftI2CMaster.h" // Include must come after setup defines +#include "SoftI2CMaster.h" // Include must come after setup defines (see library setup) -PCA9685 pwmController; // Library using default linear phase balancing scheme +PCA9685 pwmController; // Library using default B000000 (A5-A0) i2c address void setup() { - Serial.begin(115200); - - i2c_init(); // Software I2C must be started first + Serial.begin(115200); // Begin Serial and SoftI2C interfaces + i2c_init(); - pwmController.resetDevices(); // Software resets all PCA9685 devices on software I2C line + pwmController.resetDevices(); // Resets all PCA9685 devices on i2c line - pwmController.init(B000000); // Address pins A5-A0 set to B000000, default mode settings + // Initializes module using software linear phase balancer, and open-drain style driver mode + pwmController.init(PCA9685_PhaseBalancer_Linear, + PCA9685_OutputDriverMode_OpenDrain); pwmController.setChannelPWM(0, 2048); // Should see a 50% duty cycle along the 5ms phase width } +void loop() { +} + ``` ## Module Info -In this example, we enable debug output support. +In this example, we enable debug output support to print out module diagnostic information. -If one uncomments the line below inside the main header file (or defines it via custom build flag), debug output support will be enabled and the printModuleInfo() method will become available. Calling this method will display information about the module itself, including initalized states, register values, current settings, etc. Additionally, all library calls being made will display internal debug information about the structure of the call itself. An example of this output is shown below. +If one uncomments the line below inside the main header file (or defines it via custom build flag), debug output support will be enabled and the `printModuleInfo()` method will become available. Calling this method will display information about the module itself, including initalized states, register values, current settings, etc. Additionally, all library calls being made will display internal debug information about the structure of the call itself. An example of this output is shown below. In PCA9685.h: ```Arduino -// Uncomment this define to enable debug output. -#define PCA9685_ENABLE_DEBUG_OUTPUT 1 +// Uncomment or -D this define to enable debug output. +#define PCA9685_ENABLE_DEBUG_OUTPUT +``` +Alternatively, in platform[.local].txt: +```Arduino +build.extra_flags=-DPCA9685_ENABLE_DEBUG_OUTPUT ``` In main sketch: ```Arduino #include "PCA9685.h" -PCA9685 pwmController; +PCA9685 pwmController; // Library using default B000000 (A5-A0) i2c address, and default Wire @400kHz void setup() { - Serial.begin(115200); + Serial.begin(115200); // Begin Serial and Wire interfaces + Wire.begin(); - Wire.begin(); // Wire must be started first - Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz + pwmController.init(); // Initializes module using default totem-pole driver mode, and default disabled phase balancer - pwmController.printModuleInfo(); + pwmController.printModuleInfo(); // Prints module diagnostic information +} + +void loop() { } ``` In serial monitor: ``` - ~~~ PCA9685 Module Info ~~~ + ~~~ PCA9685 Module Info ~~~ -i2c Address: -0x40 +i2c Address: 0x40 +i2c Instance: 0: Wire +i2c Speed: 400kHz -Phase Balancer: -PCA9685_PhaseBalancer_Linear +Phase Balancer: 0: PCA9685_PhaseBalancer_None -Proxy Addresser: -false +Proxy Addresser: false Mode1 Register: PCA9685::readRegister regAddress: 0x0 PCA9685::readRegister retVal: 0x20 -0x20, Bitset: PCA9685_MODE_AUTOINC +0x20, Bitset: PCA9685_MODE1_AUTOINC Mode2 Register: PCA9685::readRegister regAddress: 0x1 - PCA9685::readRegister retVal: 0x0 -0x0, Bitset: + PCA9685::readRegister retVal: 0x4 +0x4, Bitset: PCA9685_MODE2_OUTDRV_TPOLE SubAddress1 Register: PCA9685::readRegister regAddress: 0x2 diff --git a/examples/BatchingExample/BatchingExample.ino b/examples/BatchingExample/BatchingExample.ino index 806528c..701b72a 100644 --- a/examples/BatchingExample/BatchingExample.ino +++ b/examples/BatchingExample/BatchingExample.ino @@ -2,21 +2,19 @@ // In this example, we randomly select PWM frequencies on all 12 outputs and allow them // to drive for 5 seconds before changing them. -#include #include "PCA9685.h" -PCA9685 pwmController; // Library using default Wire and default linear phase balancing scheme +PCA9685 pwmController(B010101); // Library using B010101 (A5-A0) i2c address, and default Wire @400kHz void setup() { - Serial.begin(115200); + Serial.begin(115200); // Begin Serial and Wire interfaces + Wire.begin(); - Wire.begin(); // Wire must be started first - Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz + pwmController.resetDevices(); // Resets all PCA9685 devices on i2c line - pwmController.resetDevices(); // Software resets all PCA9685 devices on Wire line + pwmController.init(); // Initializes module using default totem-pole driver mode, and default phase balancer - pwmController.init(B010101); // Address pins A5-A0 set to B010101, default mode settings - pwmController.setPWMFrequency(500); // Default is 200Hz, supports 24Hz to 1526Hz + pwmController.setPWMFrequency(500); // Set PWM freq to 500Hz (default is 200Hz, supports 24Hz to 1526Hz) randomSeed(analogRead(0)); // Use white noise for our randomness } @@ -38,6 +36,11 @@ void loop() { pwmController.setChannelsPWM(0, 12, pwms); delay(5000); - // Note: Only 7 channels can be written in one i2c transaction due to a - // BUFFER_LENGTH limit of 32, so 12 channels will take two i2c transactions. + // NOTE: Many chips use a BUFFER_LENGTH size of 32, and in that case writing 12 + // channels will take 2 i2c transactions because only 7 channels can fit in a single + // i2c buffer transaction at a time. This may cause a slight offset flicker between + // the first 7 and remaining 5 channels, but can be offset by experimenting with a + // channel update mode of PCA9685_ChannelUpdateMode_AfterAck. This will make each + // channel update immediately upon sending of the Ack signal after each PWM command + // is executed rather than at the Stop signal at the end of the i2c transaction. } diff --git a/examples/ModuleInfo/ModuleInfo.ino b/examples/ModuleInfo/ModuleInfo.ino index 602d6c2..5704513 100644 --- a/examples/ModuleInfo/ModuleInfo.ino +++ b/examples/ModuleInfo/ModuleInfo.ino @@ -1,28 +1,32 @@ // PCA9685-Arduino Module Info -// In this example, we enable debug output support. If one uncomments the line below -// inside the main header file (or defines it via custom build flag), debug output -// support will be enabled and the printModuleInfo() method will become available. -// Calling this method will display information about the module itself, including -// initalized states, register values, current settings, etc. Additionally, all -// library calls being made will display internal debug information about the -// structure of the call itself. +// In this example, we enable debug output support to print out module diagnostic +// information. If one uncomments the line below inside the main header file (or defines +// it via custom build flag), debug output support will be enabled and the +// printModuleInfo() method will become available. Calling this method will display +// information about the module itself, including initalized states, register values, +// current settings, etc. Additionally, all library calls being made will display +// internal debug information about the structure of the call itself. You may refer to +// https://forum.arduino.cc/index.php?topic=602603.0 on how to define custom build flags +// manually via modifying platform[.local].txt. // // In PCA9685.h: -// // Uncomment this define to enable debug output. -// #define PCA9685_ENABLE_DEBUG_OUTPUT 1 +// // Uncomment or -D this define to enable debug output. +// #define PCA9685_ENABLE_DEBUG_OUTPUT +// +// Alternatively, in platform[.local].txt: +// build.extra_flags=-DPCA9685_ENABLE_DEBUG_OUTPUT -#include #include "PCA9685.h" -PCA9685 pwmController; +PCA9685 pwmController; // Library using default B000000 (A5-A0) i2c address, and default Wire @400kHz void setup() { - Serial.begin(115200); + Serial.begin(115200); // Begin Serial and Wire interfaces + Wire.begin(); - Wire.begin(); // Wire must be started first - Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz + pwmController.init(); // Initializes module using default totem-pole driver mode, and default disabled phase balancer - pwmController.printModuleInfo(); + pwmController.printModuleInfo(); // Prints module diagnostic information } void loop() { diff --git a/examples/MultiDeviceProxyExample/MultiDeviceProxyExample.ino b/examples/MultiDeviceProxyExample/MultiDeviceProxyExample.ino index 320e1ba..b8e0c76 100644 --- a/examples/MultiDeviceProxyExample/MultiDeviceProxyExample.ino +++ b/examples/MultiDeviceProxyExample/MultiDeviceProxyExample.ino @@ -2,33 +2,32 @@ // In this example, we use a special instance to control other modules attached to it via // the ALL_CALL register. -#include #include "PCA9685.h" -PCA9685 pwmController1; // Library using default Wire and default linear phase balancing scheme -PCA9685 pwmController2; // Library using default Wire and default linear phase balancing scheme +PCA9685 pwmController1(B000000); // Library using B000000 (A5-A0) i2c address, and default Wire @400kHz +PCA9685 pwmController2(B000001); // Library using B000001 (A5-A0) i2c address, and default Wire @400kHz -PCA9685 pwmControllerAll; // Not a real device, will act as a proxy to pwmController1 and pwmController2 +// Not a real device, will act as a proxy to pwmController1 and pwmController2, using all-call i2c address 0xE0, and default Wire @400kHz +PCA9685 pwmControllerAll(PCA9685_I2C_DEF_ALLCALL_PROXYADR); void setup() { - Serial.begin(115200); + Serial.begin(115200); // Begin Serial and Wire interfaces + Wire.begin(); - Wire.begin(); // Wire must be started first - Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz + pwmControllerAll.resetDevices(); // Resets all PCA9685 devices on i2c line - pwmController1.resetDevices(); // Software resets all PCA9685 devices on Wire line (including pwmController2 in this case) + pwmController1.init(); // Initializes first module using default totem-pole driver mode, and default disabled phase balancer + pwmController2.init(); // Initializes second module using default totem-pole driver mode, and default disabled phase balancer - pwmController1.init(B000000); // Address pins A5-A0 set to B000000, default mode settings - pwmController2.init(B000001); // Address pins A5-A0 set to B000001, default mode settings + pwmControllerAll.initAsProxyAddresser(); // Initializes 'fake' module as all-call proxy addresser + + // Enables all-call support to module from 'fake' all-call proxy addresser + pwmController1.enableAllCallAddress(pwmControllerAll.getI2CAddress()); + pwmController2.enableAllCallAddress(pwmControllerAll.getI2CAddress()); // On both pwmController1.setChannelOff(0); // Turn channel 0 off pwmController2.setChannelOff(0); // On both - pwmController1.enableAllCallAddress(); // Default address of 0xE0 - pwmController2.enableAllCallAddress(); // Same default address - - pwmControllerAll.initAsProxyAddresser(); // Same default address of 0x0E as used in enable above - pwmControllerAll.setChannelPWM(0, 4096); // Enables full on on both pwmController1 and pwmController2 Serial.println(pwmController1.getChannelPWM(0)); // Should output 4096 diff --git a/examples/ServoEvaluatorExample/ServoEvaluatorExample.ino b/examples/ServoEvaluatorExample/ServoEvaluatorExample.ino index aa48001..c3513fa 100644 --- a/examples/ServoEvaluatorExample/ServoEvaluatorExample.ino +++ b/examples/ServoEvaluatorExample/ServoEvaluatorExample.ino @@ -1,33 +1,31 @@ // PCA9685-Arduino Servo Evaluator Example // In this example, we utilize the ServoEvaluator class to assist with setting PWM // frequencies when working with servos. We will be using Wire1, which is only available -// on boards with SDA1/SCL1 (Due, Zero, etc.) - change to Wire if Wire1 is unavailable. +// on boards with SDA1/SCL1 (e.g. Due/Mega/etc.) - change to Wire if Wire1 is unavailable. -#include #include "PCA9685.h" -PCA9685 pwmController(Wire1, PCA9685_PhaseBalancer_Weaved); // Library using Wire1 and weaved phase balancing scheme +PCA9685 pwmController(Wire1); // Library using Wire1 @400kHz, and default B000000 (A5-A0) i2c address // Linearly interpolates between standard 2.5%/12.5% phase length (102/512) for -90°/+90° -PCA9685_ServoEvaluator pwmServo1; +PCA9685_ServoEval pwmServo1; // Testing our second servo has found that -90° sits at 128, 0° at 324, and +90° at 526. // Since 324 isn't precisely in the middle, a cubic spline will be used to smoothly // interpolate PWM values, which will account for said discrepancy. Additionally, since -// 324 is closer to 128 than 526, there is less resolution in the -90° to 0° range, and -// more in the 0° to +90° range. -PCA9685_ServoEvaluator pwmServo2(128,324,526); +// 324 is closer to 128 than 526, there is slightly less resolution in the -90° to 0° +// range while slightly more in the 0° to +90° range. +PCA9685_ServoEval pwmServo2(128,324,526); void setup() { - Serial.begin(115200); + Serial.begin(115200); // Begin Serial and Wire1 interfaces + Wire1.begin(); - Wire1.begin(); // Wire must be started first - Wire1.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz + pwmController.resetDevices(); // Resets all PCA9685 devices on i2c line - pwmController.resetDevices(); // Software resets all PCA9685 devices on Wire line + pwmController.init(); // Initializes module using default totem-pole driver mode, and default disabled phase balancer - pwmController.init(B000000); // Address pins A5-A0 set to B000000, default mode settings - pwmController.setPWMFrequency(50); // 50Hz provides 20ms standard servo phase length + pwmController.setPWMFreqServo(); // 50Hz provides standard 20ms servo phase length pwmController.setChannelPWM(0, pwmServo1.pwmForAngle(-90)); Serial.println(pwmController.getChannelPWM(0)); // Should output 102 for -90° diff --git a/examples/SimpleExample/SimpleExample.ino b/examples/SimpleExample/SimpleExample.ino index 42889ac..05e8e04 100644 --- a/examples/SimpleExample/SimpleExample.ino +++ b/examples/SimpleExample/SimpleExample.ino @@ -1,22 +1,20 @@ // PCA9685-Arduino Simple Example -#include #include "PCA9685.h" -PCA9685 pwmController; // Library using default Wire and default linear phase balancing scheme +PCA9685 pwmController; // Library using default B000000 (A5-A0) i2c address, and default Wire @400kHz void setup() { - Serial.begin(115200); + Serial.begin(115200); // Begin Serial and Wire interfaces + Wire.begin(); - Wire.begin(); // Wire must be started first - Wire.setClock(400000); // Supported baud rates are 100kHz, 400kHz, and 1000kHz + pwmController.resetDevices(); // Resets all PCA9685 devices on i2c line - pwmController.resetDevices(); // Software resets all PCA9685 devices on Wire line + pwmController.init(); // Initializes module using default totem-pole driver mode, and default disabled phase balancer - pwmController.init(B000000); // Address pins A5-A0 set to B000000, default mode settings - pwmController.setPWMFrequency(100); // Default is 200Hz, supports 24Hz to 1526Hz + pwmController.setPWMFrequency(100); // Set PWM freq to 100Hz (default is 200Hz, supports 24Hz to 1526Hz) - pwmController.setChannelPWM(0, 128 << 4); // Set PWM to 128/255, but in 4096 land + pwmController.setChannelPWM(0, 128 << 4); // Set PWM to 128/255, shifted into 4096-land Serial.println(pwmController.getChannelPWM(0)); // Should output 2048, which is 128 << 4 } diff --git a/examples/SoftwareI2CExample/SoftwareI2CExample.ino b/examples/SoftwareI2CExample/SoftwareI2CExample.ino index c537e5a..b02ac82 100644 --- a/examples/SoftwareI2CExample/SoftwareI2CExample.ino +++ b/examples/SoftwareI2CExample/SoftwareI2CExample.ino @@ -1,35 +1,47 @@ -// PCA9685-Arduino Software I2C Example -// In this example, we utilize the software I2C functionality for chips that do not have -// a hardware I2C bus. If one uncomments the line below inside the main header file (or -// defines it via custom build flag), software I2C mode for the library will be enabled. +// PCA9685-Arduino Software i2c Example +// In this example, we utilize a popular software i2c library for chips that do not have +// a hardware i2c bus. If one uncomments the line below inside the main header file (or +// defines it via custom build flag), software i2c mode for the library will be enabled. +// Additionally, you will need to correctly define SCL_PIN, SCL_PORT, SDA_PIN, and +// SDA_PORT according to your setup. I2C_FASTMODE=1 should be set for 16MHz+ processors. +// You may refer to https://forum.arduino.cc/index.php?topic=602603.0 on how to define +// custom build flags manually via modifying platform[.local].txt. // // In PCA9685.h: -// // Uncomment this define to enable use of the software i2c library (min 4MHz+ processor required). -// #define PCA9685_ENABLE_SOFTWARE_I2C 1 // http://playground.arduino.cc/Main/SoftwareI2CLibrary +// // Uncomment or -D this define to enable use of the software i2c library (min 4MHz+ processor). +// #define PCA9685_ENABLE_SOFTWARE_I2C // http://playground.arduino.cc/Main/SoftwareI2CLibrary +// +// Alternatively, in platform[.local].txt: +// build.extra_flags=-DPCA9685_ENABLE_SOFTWARE_I2C #include "PCA9685.h" -#define SCL_PIN 2 // Setup defines are written before library include -#define SCL_PORT PORTD +// Setup defines for SoftI2CMaster are written before library include. That is because +// its header contains the full code definition, and should thus be included only once. +// The values for SCL_PORT and SDA_PORT are dependent upon which pins are used - refer to +// http://www.arduino.cc/en/Reference/PortManipulation to determine what you should use. +#define SCL_PIN 2 +#define SCL_PORT PORTD #define SDA_PIN 0 -#define SDA_PORT PORTC +#define SDA_PORT PORTC #if F_CPU >= 16000000 -#define I2C_FASTMODE 1 // Running a 16MHz processor allows us to use I2C fast mode +#define I2C_FASTMODE 1 // Running a 16MHz processor allows us to use i2c fast mode #endif -#include "SoftI2CMaster.h" // Include must come after setup defines +#include "SoftI2CMaster.h" // Include must come after setup defines (see library setup) -PCA9685 pwmController; // Library using default linear phase balancing scheme +PCA9685 pwmController; // Library using default B000000 (A5-A0) i2c address void setup() { - Serial.begin(115200); - - i2c_init(); // Software I2C must be started first + Serial.begin(115200); // Begin Serial and SoftI2C interfaces + i2c_init(); - pwmController.resetDevices(); // Software resets all PCA9685 devices on software I2C line + pwmController.resetDevices(); // Resets all PCA9685 devices on i2c line - pwmController.init(B000000); // Address pins A5-A0 set to B000000, default mode settings + // Initializes module using software linear phase balancer, and open-drain style driver mode + pwmController.init(PCA9685_PhaseBalancer_Linear, + PCA9685_OutputDriverMode_OpenDrain); pwmController.setChannelPWM(0, 2048); // Should see a 50% duty cycle along the 5ms phase width } diff --git a/library.json b/library.json index bda4071..49cff25 100644 --- a/library.json +++ b/library.json @@ -1,6 +1,6 @@ { "name": "PCA9685-Arduino", - "version": "1.2.14", + "version": "1.2.15", "keywords": "PCA9685, pwm, i2c, controller, driver", "description": "Library to control a PCA9685 16-channel PWM driver module from an Arduino board.", "license": "GPL-3.0-or-later", diff --git a/library.properties b/library.properties index f4c0ee2..8a28f23 100644 --- a/library.properties +++ b/library.properties @@ -1,5 +1,5 @@ name=PCA9685 16-Channel PWM Driver Module Library -version=1.2.14 +version=1.2.15 author=NachtRaveVL , Vitska, Kasper SkÃ¥rhøj maintainer=NachtRaveVL sentence=Library to control a PCA9685 16-channel PWM driver module from an Arduino board. diff --git a/src/PCA9685.cpp b/src/PCA9685.cpp new file mode 100644 index 0000000..4167460 --- /dev/null +++ b/src/PCA9685.cpp @@ -0,0 +1,1079 @@ +/* Arduino Library for the PCA9685 16-Channel PWM Driver Module. + Copyright (C) 2016-2020 NachtRaveVL + Copyright (C) 2012 Kasper SkÃ¥rhøj + PCA9685 Main +*/ + +#include "PCA9685.h" +#include + +#define PCA9685_I2C_BASE_MODULE_ADDRESS (byte)0x40 +#define PCA9685_I2C_BASE_MODULE_ADRMASK (byte)0x3F +#define PCA9685_I2C_BASE_PROXY_ADDRESS (byte)0xE0 +#define PCA9685_I2C_BASE_PROXY_ADRMASK (byte)0xFE + +// Register addresses from data sheet +#define PCA9685_MODE1_REG (byte)0x00 +#define PCA9685_MODE2_REG (byte)0x01 +#define PCA9685_SUBADR1_REG (byte)0x02 +#define PCA9685_SUBADR2_REG (byte)0x03 +#define PCA9685_SUBADR3_REG (byte)0x04 +#define PCA9685_ALLCALL_REG (byte)0x05 +#define PCA9685_LED0_REG (byte)0x06 // Start of LEDx regs, 4B per reg, 2B on phase, 2B off phase, little-endian +#define PCA9685_PRESCALE_REG (byte)0xFE +#define PCA9685_ALLLED_REG (byte)0xFA + +// Mode1 register values +#define PCA9685_MODE1_RESTART (byte)0x80 +#define PCA9685_MODE1_EXTCLK (byte)0x40 +#define PCA9685_MODE1_AUTOINC (byte)0x20 +#define PCA9685_MODE1_SLEEP (byte)0x10 +#define PCA9685_MODE1_SUBADR1 (byte)0x08 +#define PCA9685_MODE1_SUBADR2 (byte)0x04 +#define PCA9685_MODE1_SUBADR3 (byte)0x02 +#define PCA9685_MODE1_ALLCALL (byte)0x01 + +// Mode2 register values +#define PCA9685_MODE2_OUTDRV_TPOLE (byte)0x04 +#define PCA9685_MODE2_INVRT (byte)0x10 +#define PCA9685_MODE2_OUTNE_TPHIGH (byte)0x01 +#define PCA9685_MODE2_OUTNE_HIGHZ (byte)0x02 +#define PCA9685_MODE2_OCH_ONACK (byte)0x08 + +#define PCA9685_SW_RESET (byte)0x06 // Sent to address 0x00 to reset all devices on Wire line +#define PCA9685_PWM_FULL (uint16_t)0x1000 // Special value for full on/full off LEDx modes +#define PCA9685_PWM_MASK (uint16_t)0x0FFF // Mask for 12-bit/4096 possible phase positions + +#define PCA9685_CHANNEL_COUNT 16 +#define PCA9685_MIN_CHANNEL 0 +#define PCA9685_MAX_CHANNEL (PCA9685_CHANNEL_COUNT - 1) +#define PCA9685_ALLLED_CHANNEL -1 // Special value for ALLLED registers + + +#ifdef PCA9685_USE_SOFTWARE_I2C +boolean __attribute__((noinline)) i2c_init(void); +bool __attribute__((noinline)) i2c_start(uint8_t addr); +void __attribute__((noinline)) PCA9685_i2c_stop(void) asm("ass_i2c_stop"); +bool __attribute__((noinline)) PCA9685_i2c_write(uint8_t value) asm("ass_i2c_write"); +uint8_t __attribute__((noinline)) i2c_read(bool last); +#endif + +#ifndef PCA9685_USE_SOFTWARE_I2C + +PCA9685::PCA9685(byte i2cAddress, TwoWire& i2cWire, uint32_t i2cSpeed) + // I2C 7-bit address is B 1 A5 A4 A3 A2 A1 A0 + // RW lsb bit added by Arduino core TWI library + : _i2cAddress(i2cAddress), + _i2cWire(&i2cWire), + _i2cSpeed(i2cSpeed), + _driverMode(PCA9685_OutputDriverMode_Undefined), + _enabledMode(PCA9685_OutputEnabledMode_Undefined), + _disabledMode(PCA9685_OutputDisabledMode_Undefined), + _updateMode(PCA9685_ChannelUpdateMode_Undefined), + _phaseBalancer(PCA9685_PhaseBalancer_Undefined), + _isProxyAddresser(false), + _lastI2CError(0) +{ } + +PCA9685::PCA9685(TwoWire& i2cWire, uint32_t i2cSpeed, byte i2cAddress) + : _i2cAddress(i2cAddress), + _i2cWire(&i2cWire), + _i2cSpeed(i2cSpeed), + _driverMode(PCA9685_OutputDriverMode_Undefined), + _enabledMode(PCA9685_OutputEnabledMode_Undefined), + _disabledMode(PCA9685_OutputDisabledMode_Undefined), + _updateMode(PCA9685_ChannelUpdateMode_Undefined), + _phaseBalancer(PCA9685_PhaseBalancer_Undefined), + _isProxyAddresser(false), + _lastI2CError(0) +{ } + +#else + +PCA9685::PCA9685(byte i2cAddress) + : _i2cAddress(i2cAddress), + _readBytes(0), + _driverMode(PCA9685_OutputDriverMode_Undefined), + _enabledMode(PCA9685_OutputEnabledMode_Undefined), + _disabledMode(PCA9685_OutputDisabledMode_Undefined), + _updateMode(PCA9685_ChannelUpdateMode_Undefined), + _phaseBalancer(PCA9685_PhaseBalancer_Undefined), + _isProxyAddresser(false), + _lastI2CError(0) +{ } + +#endif // /ifndef PCA9685_USE_SOFTWARE_I2C + +void PCA9685::resetDevices() { +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.println("PCA9685::resetDevices"); +#endif + + i2cWire_begin(); + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + checkForErrors(); +#endif + + i2cWire_beginTransmission(0x00); + i2cWire_write(PCA9685_SW_RESET); + i2cWire_endTransmission(); + + delayMicroseconds(10); + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + checkForErrors(); +#endif +} + +void PCA9685::init(PCA9685_OutputDriverMode driverMode, + PCA9685_OutputEnabledMode enabledMode, + PCA9685_OutputDisabledMode disabledMode, + PCA9685_ChannelUpdateMode updateMode, + PCA9685_PhaseBalancer phaseBalancer) { + if (_isProxyAddresser) return; + + _i2cAddress = PCA9685_I2C_BASE_MODULE_ADDRESS | (_i2cAddress & PCA9685_I2C_BASE_MODULE_ADRMASK); + + _driverMode = driverMode; + _enabledMode = enabledMode; + _disabledMode = disabledMode; + _updateMode = updateMode; + _phaseBalancer = phaseBalancer; + + assert(!(_driverMode == PCA9685_OutputDriverMode_OpenDrain && _disabledMode == PCA9685_OutputDisabledMode_High && "Unsupported combination")); + + byte mode2Val = getMode2Value(); + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.print("PCA9685::init mode2Val: 0x"); + Serial.print(mode2Val, HEX); + Serial.print(", i2cAddress: 0x"); + Serial.print(_i2cAddress, HEX); + Serial.print(", i2cWire#: "); + Serial.print(getWireInterfaceNumber()); + Serial.print(", i2cSpeed: "); + Serial.print(roundf(getI2CSpeed() / 1000.0f)); Serial.print("kHz"); + Serial.print(", driverMode: "); + switch(_driverMode) { + case PCA9685_OutputDriverMode_OpenDrain: Serial.print("OpenDrain"); break; + case PCA9685_OutputDriverMode_TotemPole: Serial.print("TotemPole"); break; + case PCA9685_OutputDriverMode_Count: + case PCA9685_OutputDriverMode_Undefined: + Serial.print(_driverMode); break; + } + Serial.print(", enabledMode: "); + switch (_enabledMode) { + case PCA9685_OutputEnabledMode_Normal: Serial.print("Normal"); break; + case PCA9685_OutputEnabledMode_Inverted: Serial.print("Inverted"); break; + case PCA9685_OutputEnabledMode_Count: + case PCA9685_OutputEnabledMode_Undefined: + Serial.print(_enabledMode); break; + } + Serial.print(", disabledMode: "); + switch (_disabledMode) { + case PCA9685_OutputDisabledMode_Low: Serial.print("Low"); break; + case PCA9685_OutputDisabledMode_High: Serial.print("High"); break; + case PCA9685_OutputDisabledMode_Floating: Serial.print("Floating"); break; + case PCA9685_OutputDisabledMode_Count: + case PCA9685_OutputDisabledMode_Undefined: + Serial.print(_disabledMode); break; + } + Serial.print(", updateMode: "); + switch (_updateMode) { + case PCA9685_ChannelUpdateMode_AfterStop: Serial.print("AfterStop"); break; + case PCA9685_ChannelUpdateMode_AfterAck: Serial.print("AfterAck"); break; + case PCA9685_ChannelUpdateMode_Count: + case PCA9685_ChannelUpdateMode_Undefined: + Serial.print(_updateMode); break; + } + Serial.print(", phaseBalancer: "); + switch(_phaseBalancer) { + case PCA9685_PhaseBalancer_None: Serial.print("None"); break; + case PCA9685_PhaseBalancer_Linear: Serial.print("Linear"); break; + case PCA9685_PhaseBalancer_Count: + case PCA9685_PhaseBalancer_Undefined: + Serial.print(_phaseBalancer); break; + } + Serial.println(""); +#endif + + i2cWire_begin(); + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + checkForErrors(); +#endif + + writeRegister(PCA9685_MODE1_REG, PCA9685_MODE1_RESTART | PCA9685_MODE1_AUTOINC); + writeRegister(PCA9685_MODE2_REG, mode2Val); +} + +void PCA9685::init(PCA9685_PhaseBalancer phaseBalancer, + PCA9685_OutputDriverMode driverMode, + PCA9685_OutputEnabledMode enabledMode, + PCA9685_OutputDisabledMode disabledMode, + PCA9685_ChannelUpdateMode updateMode) { + init(driverMode, enabledMode, disabledMode, updateMode, phaseBalancer); +} + +void PCA9685::initAsProxyAddresser() { + if (_driverMode != PCA9685_OutputDriverMode_Undefined) return; + + _i2cAddress = PCA9685_I2C_BASE_PROXY_ADDRESS | (_i2cAddress & PCA9685_I2C_BASE_PROXY_ADRMASK); + _isProxyAddresser = true; + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.println("PCA9685::initAsProxyAddresser i2cAddress: 0x"); + Serial.print(_i2cAddress, HEX); + Serial.print(", i2cWire#: "); + Serial.print(getWireInterfaceNumber()); + Serial.print(", i2cSpeed: "); + Serial.print(roundf(getI2CSpeed() / 1000.0f)); Serial.print("kHz"); + Serial.println(""); +#endif + + i2cWire_begin(); + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + checkForErrors(); +#endif +} + +byte PCA9685::getI2CAddress() { + return _i2cAddress; +} + +uint32_t PCA9685::getI2CSpeed() { +#ifndef PCA9685_USE_SOFTWARE_I2C + return _i2cSpeed; +#else +#if I2C_FASTMODE || F_CPU >= 16000000 + return 400000; +#else + return 100000; +#endif +#endif // ifndef PCA9685_USE_SOFTWARE_I2C +} + +PCA9685_OutputDriverMode PCA9685::getOutputDriverMode() { + return _driverMode; +} + +PCA9685_OutputEnabledMode PCA9685::getOutputEnabledMode() { + return _enabledMode; +} + +PCA9685_OutputDisabledMode PCA9685::getOutputDisabledMode() { + return _disabledMode; +} + +PCA9685_ChannelUpdateMode PCA9685::getChannelUpdateMode() { + return _updateMode; +} + +PCA9685_PhaseBalancer PCA9685::getPhaseBalancer() { + return _phaseBalancer; +} + +byte PCA9685::getMode2Value() { + byte mode2Val = (byte)0x00; + + if (_driverMode == PCA9685_OutputDriverMode_TotemPole) { + mode2Val |= PCA9685_MODE2_OUTDRV_TPOLE; + } + + if (_enabledMode == PCA9685_OutputEnabledMode_Inverted) { + mode2Val |= PCA9685_MODE2_INVRT; + } + + if (_disabledMode == PCA9685_OutputDisabledMode_High) { + mode2Val |= PCA9685_MODE2_OUTNE_TPHIGH; + } + else if (_disabledMode == PCA9685_OutputDisabledMode_Floating) { + mode2Val |= PCA9685_MODE2_OUTNE_HIGHZ; + } + + if (_updateMode == PCA9685_ChannelUpdateMode_AfterAck) { + mode2Val |= PCA9685_MODE2_OCH_ONACK; + } + + return mode2Val; +} + +void PCA9685::setPWMFrequency(float pwmFrequency) { + if (pwmFrequency < 0 || _isProxyAddresser) return; + + // This equation comes from section 7.3.5 of the datasheet, but the rounding has been + // removed because it isn't needed. Lowest freq is 23.84, highest is 1525.88. + int preScalerVal = (25000000 / (4096 * pwmFrequency)) - 1; + if (preScalerVal > 255) preScalerVal = 255; + if (preScalerVal < 3) preScalerVal = 3; + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.print("PCA9685::setPWMFrequency pwmFrequency: "); + Serial.print(pwmFrequency); + Serial.print(", preScalerVal: 0x"); + Serial.println(preScalerVal, HEX); +#endif + + // The PRE_SCALE register can only be set when the SLEEP bit of MODE1 register is set to logic 1. + byte mode1Reg = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Reg = (mode1Reg & ~PCA9685_MODE1_RESTART) | PCA9685_MODE1_SLEEP)); + writeRegister(PCA9685_PRESCALE_REG, (byte)preScalerVal); + + // It takes 500us max for the oscillator to be up and running once SLEEP bit has been set to logic 0. + writeRegister(PCA9685_MODE1_REG, (mode1Reg = (mode1Reg & ~PCA9685_MODE1_SLEEP) | PCA9685_MODE1_RESTART)); + delayMicroseconds(500); +} + +void PCA9685::setPWMFreqServo() { + setPWMFrequency(50); +} + +void PCA9685::setChannelOn(int channel) { + if (channel < 0 || channel > 15) return; + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.println("PCA9685::setChannelOn"); +#endif + + writeChannelBegin(channel); + writeChannelPWM(PCA9685_PWM_FULL, 0); // time_on = FULL; time_off = 0; + writeChannelEnd(); +} + +void PCA9685::setChannelOff(int channel) { + if (channel < 0 || channel > 15) return; + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.println("PCA9685::setChannelOff"); +#endif + + writeChannelBegin(channel); + writeChannelPWM(0, PCA9685_PWM_FULL); // time_on = 0; time_off = FULL; + writeChannelEnd(); +} + +void PCA9685::setChannelPWM(int channel, uint16_t pwmAmount) { + if (channel < 0 || channel > 15) return; + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.println("PCA9685::setChannelPWM"); +#endif + + writeChannelBegin(channel); + + uint16_t phaseBegin, phaseEnd; + getPhaseCycle(channel, pwmAmount, &phaseBegin, &phaseEnd); + + writeChannelPWM(phaseBegin, phaseEnd); + + writeChannelEnd(); +} + +void PCA9685::setChannelsPWM(int begChannel, int numChannels, const uint16_t *pwmAmounts) { + if (begChannel < 0 || begChannel > 15 || numChannels < 0) return; + if (begChannel + numChannels > 16) numChannels -= (begChannel + numChannels) - 16; + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.print("PCA9685::setChannelsPWM numChannels: "); + Serial.println(numChannels); +#endif + + // From avr/libraries/Wire.h and avr/libraries/utility/twi.h, BUFFER_LENGTH controls + // how many channels can be written at once. Therefore, we loop around until all + // channels have been written out into their registers. I2C_BUFFER_LENGTH is used in + // other architectures, so we rely on PCA9685_I2C_BUFFER_LENGTH logic to sort it out. + + while (numChannels > 0) { + writeChannelBegin(begChannel); + +#ifndef PCA9685_USE_SOFTWARE_I2C + int maxChannels = min(numChannels, (PCA9685_I2C_BUFFER_LENGTH - 1) / 4); +#else // TODO: Software I2C doesn't have buffer length restrictions? -NR + int maxChannels = numChannels; +#endif + while (maxChannels-- > 0) { + uint16_t phaseBegin, phaseEnd; + getPhaseCycle(begChannel++, *pwmAmounts++, &phaseBegin, &phaseEnd); + + writeChannelPWM(phaseBegin, phaseEnd); + --numChannels; + } + + writeChannelEnd(); + if (_lastI2CError) return; + } +} + +void PCA9685::setAllChannelsPWM(uint16_t pwmAmount) { +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.println("PCA9685::setAllChannelsPWM"); +#endif + + writeChannelBegin(PCA9685_ALLLED_CHANNEL); + + uint16_t phaseBegin, phaseEnd; + getPhaseCycle(PCA9685_ALLLED_CHANNEL, pwmAmount, &phaseBegin, &phaseEnd); + + writeChannelPWM(phaseBegin, phaseEnd); + + writeChannelEnd(); +} + +uint16_t PCA9685::getChannelPWM(int channel) { + if (channel < 0 || channel > 15 || _isProxyAddresser) return 0; + + byte regAddress = PCA9685_LED0_REG + (channel << 2); + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.print("PCA9685::getChannelPWM channel: "); + Serial.print(channel); + Serial.print(", regAddress: 0x"); + Serial.println(regAddress, HEX); +#endif + + i2cWire_beginTransmission(_i2cAddress); + i2cWire_write(regAddress); + if (i2cWire_endTransmission()) { +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + checkForErrors(); +#endif + return 0; + } + + int bytesRead = i2cWire_requestFrom((uint8_t)_i2cAddress, 4); + if (bytesRead != 4) { + while (bytesRead-- > 0) + i2cWire_read(); +#ifdef PCA9685_USE_SOFTWARE_I2C + PCA9685_i2c_stop(); // Manually have to send stop bit in software i2c mode +#endif + _lastI2CError = 4; +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + checkForErrors(); +#endif + return 0; + } + +#ifndef PCA9685_SWAP_PWM_BEG_END_REGS + uint16_t phaseBegin = (uint16_t)i2cWire_read(); + phaseBegin |= (uint16_t)i2cWire_read() << 8; + uint16_t phaseEnd = (uint16_t)i2cWire_read(); + phaseEnd |= (uint16_t)i2cWire_read() << 8; +#else + uint16_t phaseEnd = (uint16_t)i2cWire_read(); + phaseEnd |= (uint16_t)i2cWire_read() << 8; + uint16_t phaseBegin = (uint16_t)i2cWire_read(); + phaseBegin |= (uint16_t)i2cWire_read() << 8; +#endif + +#ifdef PCA9685_USE_SOFTWARE_I2C + PCA9685_i2c_stop(); // Manually have to send stop bit in software i2c mode +#endif + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.print(" PCA9685::getChannelPWM phaseBegin: "); + Serial.print(phaseBegin); + Serial.print(", phaseEnd: "); + Serial.println(phaseEnd); +#endif + + // See datasheet section 7.3.3 + uint16_t retVal; + if (phaseEnd >= PCA9685_PWM_FULL) + // Full OFF + // Figure 11 Example 4: full OFF takes precedence over full ON + // See also remark after Table 7 + retVal = 0; + else if (phaseBegin >= PCA9685_PWM_FULL) + // Full ON + // Figure 9 Example 3 + retVal = PCA9685_PWM_FULL; + else if (phaseBegin <= phaseEnd) + // start and finish in same cycle + // Section 7.3.3 example 1 + retVal = phaseEnd - phaseBegin; + else + // span cycles + // Section 7.3.3 example 2 + retVal = (phaseEnd + PCA9685_PWM_FULL) - phaseBegin; + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.print(" PCA9685::getChannelPWM retVal: "); + Serial.println(retVal); +#endif + + return retVal; +} + +void PCA9685::enableAllCallAddress(byte i2cAddressAllCall) { + if (_isProxyAddresser) return; + + byte i2cAddress = PCA9685_I2C_BASE_PROXY_ADDRESS | (i2cAddressAllCall & PCA9685_I2C_BASE_PROXY_ADRMASK); + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.print("PCA9685::enableAllCallAddress i2cAddressAllCall: 0x"); + Serial.println(i2cAddress, HEX); +#endif + + writeRegister(PCA9685_ALLCALL_REG, i2cAddress); + + byte mode1Reg = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Reg |= PCA9685_MODE1_ALLCALL)); +} + +void PCA9685::enableSub1Address(byte i2cAddressSub1) { + if (_isProxyAddresser) return; + + byte i2cAddress = PCA9685_I2C_BASE_PROXY_ADDRESS | (i2cAddressSub1 & PCA9685_I2C_BASE_PROXY_ADRMASK); + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.print("PCA9685::enableSub1Address i2cAddressSub1: 0x"); + Serial.println(i2cAddress, HEX); +#endif + + writeRegister(PCA9685_SUBADR1_REG, i2cAddress); + + byte mode1Reg = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Reg |= PCA9685_MODE1_SUBADR1)); +} + +void PCA9685::enableSub2Address(byte i2cAddressSub2) { + if (_isProxyAddresser) return; + + byte i2cAddress = PCA9685_I2C_BASE_PROXY_ADDRESS | (i2cAddressSub2 & PCA9685_I2C_BASE_PROXY_ADRMASK); + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.print("PCA9685::enableSub2Address i2cAddressSub2: 0x"); + Serial.println(i2cAddress, HEX); +#endif + + writeRegister(PCA9685_SUBADR2_REG, i2cAddress); + + byte mode1Reg = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Reg |= PCA9685_MODE1_SUBADR2)); +} + +void PCA9685::enableSub3Address(byte i2cAddressSub3) { + if (_isProxyAddresser) return; + + byte i2cAddress = PCA9685_I2C_BASE_PROXY_ADDRESS | (i2cAddressSub3 & PCA9685_I2C_BASE_PROXY_ADRMASK); + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.print("PCA9685::enableSub3Address i2cAddressSub3: 0x"); + Serial.println(i2cAddress, HEX); +#endif + + writeRegister(PCA9685_SUBADR3_REG, i2cAddress); + + byte mode1Reg = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Reg |= PCA9685_MODE1_SUBADR3)); +} + +void PCA9685::disableAllCallAddress() { + if (_isProxyAddresser) return; + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.println("PCA9685::disableAllCallAddress"); +#endif + + byte mode1Reg = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Reg &= ~PCA9685_MODE1_ALLCALL)); +} + +void PCA9685::disableSub1Address() { + if (_isProxyAddresser) return; + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.println("PCA9685::disableSub1Address"); +#endif + + byte mode1Reg = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Reg &= ~PCA9685_MODE1_SUBADR1)); +} + +void PCA9685::disableSub2Address() { + if (_isProxyAddresser) return; + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.println("PCA9685::disableSub2Address"); +#endif + + byte mode1Reg = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Reg &= ~PCA9685_MODE1_SUBADR2)); +} + +void PCA9685::disableSub3Address() { + if (_isProxyAddresser) return; + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.println("PCA9685::disableSub3Address"); +#endif + + byte mode1Reg = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Reg &= ~PCA9685_MODE1_SUBADR3)); +} + +void PCA9685::enableExtClockLine() { +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.println("PCA9685::enableExtClockLine"); +#endif + + // The PRE_SCALE register can only be set when the SLEEP bit of MODE1 register is set to logic 1. + byte mode1Reg = readRegister(PCA9685_MODE1_REG); + writeRegister(PCA9685_MODE1_REG, (mode1Reg = (mode1Reg & ~PCA9685_MODE1_RESTART) | PCA9685_MODE1_SLEEP)); + writeRegister(PCA9685_MODE1_REG, (mode1Reg |= PCA9685_MODE1_EXTCLK)); + + // It takes 500us max for the oscillator to be up and running once SLEEP bit has been set to logic 0. + writeRegister(PCA9685_MODE1_REG, (mode1Reg = (mode1Reg & ~PCA9685_MODE1_SLEEP) | PCA9685_MODE1_RESTART)); + delayMicroseconds(500); +} + +byte PCA9685::getLastI2CError() { + return _lastI2CError; +} + +void PCA9685::getPhaseCycle(int channel, uint16_t pwmAmount, uint16_t *phaseBegin, uint16_t *phaseEnd) { + if (channel == PCA9685_ALLLED_CHANNEL) { + *phaseBegin = 0; // ALLLED should not receive a phase shifted begin value + } else { + // Get phase delay begin + switch(_phaseBalancer) { + case PCA9685_PhaseBalancer_None: + case PCA9685_PhaseBalancer_Count: + case PCA9685_PhaseBalancer_Undefined: + *phaseBegin = 0; + break; + + case PCA9685_PhaseBalancer_Linear: + // Distribute high phase area over more of the duty cycle range to balance load + *phaseBegin = (channel * ((4096 / 16) / 16)) & PCA9685_PWM_MASK; + break; + } + } + + // See datasheet section 7.3.3 + if (pwmAmount == 0) { + // Full OFF -> time_end[bit12] = 1 + *phaseEnd = PCA9685_PWM_FULL; + } + else if (pwmAmount >= PCA9685_PWM_FULL) { + // Full ON -> time_beg[bit12] = 1, time_end[bit12] = + *phaseBegin |= PCA9685_PWM_FULL; + *phaseEnd = 0; + } + else { + *phaseEnd = (*phaseBegin + pwmAmount) & PCA9685_PWM_MASK; + } +} + +void PCA9685::writeChannelBegin(int channel) { + byte regAddress; + + if (channel != PCA9685_ALLLED_CHANNEL) + regAddress = PCA9685_LED0_REG + (channel * 0x04); + else + regAddress = PCA9685_ALLLED_REG; + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.print(" PCA9685::writeChannelBegin channel: "); + Serial.print(channel); + Serial.print(", regAddress: 0x"); + Serial.println(regAddress, HEX); +#endif + + i2cWire_beginTransmission(_i2cAddress); + i2cWire_write(regAddress); +} + +void PCA9685::writeChannelPWM(uint16_t phaseBegin, uint16_t phaseEnd) { +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.print(" PCA9685::writeChannelPWM phaseBegin: "); + Serial.print(phaseBegin); + Serial.print(", phaseEnd: "); + Serial.println(phaseEnd); +#endif + +#ifndef PCA9685_SWAP_PWM_BEG_END_REGS + i2cWire_write(lowByte(phaseBegin)); + i2cWire_write(highByte(phaseBegin)); + i2cWire_write(lowByte(phaseEnd)); + i2cWire_write(highByte(phaseEnd)); +#else + i2cWire_write(lowByte(phaseEnd)); + i2cWire_write(highByte(phaseEnd)); + i2cWire_write(lowByte(phaseBegin)); + i2cWire_write(highByte(phaseBegin)); +#endif +} + +void PCA9685::writeChannelEnd() { + i2cWire_endTransmission(); + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + checkForErrors(); +#endif +} + +void PCA9685::writeRegister(byte regAddress, byte value) { +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.print(" PCA9685::writeRegister regAddress: 0x"); + Serial.print(regAddress, HEX); + Serial.print(", value: 0x"); + Serial.println(value, HEX); +#endif + + i2cWire_beginTransmission(_i2cAddress); + i2cWire_write(regAddress); + i2cWire_write(value); + i2cWire_endTransmission(); + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + checkForErrors(); +#endif +} + +byte PCA9685::readRegister(byte regAddress) { +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.print(" PCA9685::readRegister regAddress: 0x"); + Serial.println(regAddress, HEX); +#endif + + i2cWire_beginTransmission(_i2cAddress); + i2cWire_write(regAddress); + if (i2cWire_endTransmission()) { +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + checkForErrors(); +#endif + return 0; + } + + int bytesRead = i2cWire_requestFrom((uint8_t)_i2cAddress, 1); + if (bytesRead != 1) { + while (bytesRead-- > 0) + i2cWire_read(); +#ifdef PCA9685_USE_SOFTWARE_I2C + PCA9685_i2c_stop(); // Manually have to send stop bit in software i2c mode +#endif + _lastI2CError = 4; +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + checkForErrors(); +#endif + return 0; + } + + byte retVal = i2cWire_read(); + +#ifdef PCA9685_USE_SOFTWARE_I2C + PCA9685_i2c_stop(); // Manually have to send stop bit in software i2c mode +#endif + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + Serial.print(" PCA9685::readRegister retVal: 0x"); + Serial.println(retVal, HEX); +#endif + + return retVal; +} + +void PCA9685::i2cWire_begin() { + _lastI2CError = 0; +#ifndef PCA9685_USE_SOFTWARE_I2C + _i2cWire->setClock(getI2CSpeed()); +#endif +} + +void PCA9685::i2cWire_beginTransmission(uint8_t addr) { + _lastI2CError = 0; +#ifndef PCA9685_USE_SOFTWARE_I2C + _i2cWire->beginTransmission(addr); +#else + i2c_start(addr); +#endif +} + +uint8_t PCA9685::i2cWire_endTransmission(void) { +#ifndef PCA9685_USE_SOFTWARE_I2C + return (_lastI2CError = _i2cWire->endTransmission()); +#else + PCA9685_i2c_stop(); // Manually have to send stop bit in software i2c mode + return (_lastI2CError = 0); +#endif +} + +uint8_t PCA9685::i2cWire_requestFrom(uint8_t addr, uint8_t len) { +#ifndef PCA9685_USE_SOFTWARE_I2C + return _i2cWire->requestFrom(addr, (size_t)len); +#else + i2c_start(addr | 0x01); + return (_readBytes = len); +#endif +} + +size_t PCA9685::i2cWire_write(uint8_t data) { +#ifndef PCA9685_USE_SOFTWARE_I2C + return _i2cWire->write(data); +#else + return (size_t)PCA9685_i2c_write(data); +#endif +} + +uint8_t PCA9685::i2cWire_read(void) { +#ifndef PCA9685_USE_SOFTWARE_I2C + return (uint8_t)(_i2cWire->read() & 0xFF); +#else + if (_readBytes > 1) { + _readBytes -= 1; + return (uint8_t)(i2c_read(false) & 0xFF); + } + else { + _readBytes = 0; + return (uint8_t)(i2c_read(true) & 0xFF); + } +#endif +} + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + +int PCA9685::getWireInterfaceNumber() { +#ifndef PCA9685_USE_SOFTWARE_I2C + if (_i2cWire == &Wire) return 0; +#if WIRE_INTERFACES_COUNT > 1 + if (_i2cWire == &Wire1) return 1; +#endif +#if WIRE_INTERFACES_COUNT > 2 + if (_i2cWire == &Wire2) return 2; +#endif +#if WIRE_INTERFACES_COUNT > 3 + if (_i2cWire == &Wire3) return 3; +#endif +#if WIRE_INTERFACES_COUNT > 4 + if (_i2cWire == &Wire4) return 4; +#endif +#if WIRE_INTERFACES_COUNT > 5 + if (_i2cWire == &Wire5) return 5; +#endif +#endif // /ifndef PCA9685_USE_SOFTWARE_I2C + return -1; +} + +static const char *textForWireInterfaceNumber(int wireNum) { +#ifndef PCA9685_USE_SOFTWARE_I2C + switch (wireNum) { + case 0: return "Wire"; + case 1: return "Wire1"; + case 2: return "Wire2"; + case 3: return "Wire3"; + case 4: return "Wire4"; + case 5: return "Wire5"; + default: return ""; + } +#else + return "SoftwareI2C"; +#endif // /ifndef PCA9685_USE_SOFTWARE_I2C +} + +void PCA9685::printModuleInfo() { + Serial.println(""); Serial.println(" ~~~ PCA9685 Module Info ~~~"); + + Serial.println(""); Serial.print("i2c Address: "); + Serial.print("0x"); Serial.println(_i2cAddress, HEX); + Serial.print("i2c Instance: "); + Serial.print(getWireInterfaceNumber()); Serial.print(": "); + Serial.println(textForWireInterfaceNumber(getWireInterfaceNumber())); + Serial.print("i2c Speed: "); + Serial.print(roundf(getI2CSpeed() / 1000.0f)); Serial.println("kHz"); + + Serial.println(""); Serial.print("Phase Balancer: "); + Serial.print(_phaseBalancer); Serial.print(": "); + switch (_phaseBalancer) { + case PCA9685_PhaseBalancer_None: + Serial.println("PCA9685_PhaseBalancer_None"); break; + case PCA9685_PhaseBalancer_Linear: + Serial.println("PCA9685_PhaseBalancer_Linear"); break; + case PCA9685_PhaseBalancer_Count: + case PCA9685_PhaseBalancer_Undefined: + Serial.println(""); break; + } + + if (!_isProxyAddresser) { + Serial.println(""); Serial.println("Proxy Addresser: false"); + + Serial.println(""); Serial.println("Mode1 Register:"); + const byte mode1Reg = readRegister(PCA9685_MODE1_REG); + Serial.print("0x"); Serial.print(mode1Reg, HEX); + Serial.print(", Bitset:"); + if (mode1Reg & PCA9685_MODE1_RESTART) + Serial.print(" PCA9685_MODE1_RESTART"); + if (mode1Reg & PCA9685_MODE1_EXTCLK) + Serial.print(" PCA9685_MODE1_EXTCLK"); + if (mode1Reg & PCA9685_MODE1_AUTOINC) + Serial.print(" PCA9685_MODE1_AUTOINC"); + if (mode1Reg & PCA9685_MODE1_SLEEP) + Serial.print(" PCA9685_MODE1_SLEEP"); + if (mode1Reg & PCA9685_MODE1_SUBADR1) + Serial.print(" PCA9685_MODE1_SUBADR1"); + if (mode1Reg & PCA9685_MODE1_SUBADR2) + Serial.print(" PCA9685_MODE1_SUBADR2"); + if (mode1Reg & PCA9685_MODE1_SUBADR3) + Serial.print(" PCA9685_MODE1_SUBADR3"); + if (mode1Reg & PCA9685_MODE1_ALLCALL) + Serial.print(" PCA9685_MODE1_ALLCALL"); + Serial.println(""); + + Serial.println(""); Serial.println("Mode2 Register:"); + const byte mode2Reg = readRegister(PCA9685_MODE2_REG); + Serial.print("0x"); Serial.print(mode2Reg, HEX); + Serial.print(", Bitset:"); + if (mode2Reg & PCA9685_MODE2_OUTDRV_TPOLE) + Serial.print(" PCA9685_MODE2_OUTDRV_TPOLE"); + if (mode2Reg & PCA9685_MODE2_INVRT) + Serial.print(" PCA9685_MODE2_INVRT"); + if (mode2Reg & PCA9685_MODE2_OUTNE_TPHIGH) + Serial.print(" PCA9685_MODE2_OUTNE_TPHIGH"); + if (mode2Reg & PCA9685_MODE2_OUTNE_HIGHZ) + Serial.print(" PCA9685_MODE2_OUTNE_HIGHZ"); + if (mode2Reg & PCA9685_MODE2_OCH_ONACK) + Serial.print(" PCA9685_MODE2_OCH_ONACK"); + Serial.println(""); + + Serial.println(""); Serial.println("SubAddress1 Register:"); + const byte subAdr1Reg = readRegister(PCA9685_SUBADR1_REG); + Serial.print("0x"); Serial.println(subAdr1Reg, HEX); + + Serial.println(""); Serial.println("SubAddress2 Register:"); + const byte subAdr2Reg = readRegister(PCA9685_SUBADR2_REG); + Serial.print("0x"); Serial.println(subAdr2Reg, HEX); + + Serial.println(""); Serial.println("SubAddress3 Register:"); + const byte subAdr3Reg = readRegister(PCA9685_SUBADR3_REG); + Serial.print("0x"); Serial.println(subAdr3Reg, HEX); + + Serial.println(""); Serial.println("AllCall Register:"); + const byte allCallReg = readRegister(PCA9685_ALLCALL_REG); + Serial.print("0x"); Serial.println(allCallReg, HEX); + } else { + Serial.println(""); Serial.println("Proxy Addresser: true"); + } +} + +static const char *textForI2CError(byte errorCode) { + switch (errorCode) { + case 0: + return "Success"; + case 1: + return "Data too long to fit in transmit buffer"; + case 2: + return "Received NACK on transmit of address"; + case 3: + return "Received NACK on transmit of data"; + default: + return "Other error"; + } +} + +void PCA9685::checkForErrors() { + if (_lastI2CError) { + Serial.print(" PCA9685::checkErrors lastI2CError: "); + Serial.print(_lastI2CError); + Serial.print(": "); + Serial.println(textForI2CError(getLastI2CError())); + } +} + +#endif // /ifdef PCA9685_ENABLE_DEBUG_OUTPUT + +PCA9685_ServoEval::PCA9685_ServoEval(uint16_t minPWMAmount, uint16_t maxPWMAmount) + : _coeff(NULL), _isCSpline(false) +{ + minPWMAmount = min(minPWMAmount, PCA9685_PWM_FULL); + maxPWMAmount = constrain(maxPWMAmount, minPWMAmount, PCA9685_PWM_FULL); + + _coeff = new float[2]; + _isCSpline = false; + + _coeff[0] = minPWMAmount; + _coeff[1] = (maxPWMAmount - minPWMAmount) / 180.0f; +} + +PCA9685_ServoEval::PCA9685_ServoEval(uint16_t minPWMAmount, uint16_t midPWMAmount, uint16_t maxPWMAmount) + : _coeff(NULL), _isCSpline(false) +{ + minPWMAmount = min(minPWMAmount, PCA9685_PWM_FULL); + midPWMAmount = constrain(midPWMAmount, minPWMAmount, PCA9685_PWM_FULL); + maxPWMAmount = constrain(maxPWMAmount, midPWMAmount, PCA9685_PWM_FULL); + + if (maxPWMAmount - midPWMAmount != midPWMAmount - minPWMAmount) { + _coeff = new float[8]; + _isCSpline = true; + + // Cubic spline code adapted from: https://shiftedbits.org/2011/01/30/cubic-spline-interpolation/ + /* "THE BEER-WARE LICENSE" (Revision 42): Devin Lane wrote this [part]. As long as you retain + * this notice you can do whatever you want with this stuff. If we meet some day, and you + * think this stuff is worth it, you can buy me a beer in return. */ + // TODO: Looks like I owe Devin Lane a beer. -NR + + float x[3] = { 0, 90, 180 }; + float y[3] = { (float)minPWMAmount, (float)midPWMAmount, (float)maxPWMAmount }; + float c[3], b[2], d[2], h[2], l[1], u[2], a[1], z[2]; // n = 3 + + h[0] = x[1] - x[0]; + u[0] = z[0] = 0; + c[2] = 0; + + for (int i = 1; i < 2; ++i) { + h[i] = x[i + 1] - x[i]; + l[i - 1] = (2 * (x[i + 1] - x[i - 1])) - h[i - 1] * u[i - 1]; + u[i] = h[i] / l[i - 1]; + a[i - 1] = (3 / h[i]) * (y[i + 1] - y[i]) - (3 / h[i - 1]) * (y[i] - y[i - 1]); + z[i] = (a[i - 1] - h[i - 1] * z[i - 1]) / l[i - 1]; + } + + for (int i = 1; i >= 0; --i) { + c[i] = z[i] - u[i] * c[i + 1]; + b[i] = (y[i + 1] - y[i]) / h[i] - (h[i] * (c[i + 1] + 2 * c[i])) / 3; + d[i] = (c[i + 1] - c[i]) / (3 * h[i]); + + _coeff[4 * i + 0] = y[i]; // a + _coeff[4 * i + 1] = b[i]; // b + _coeff[4 * i + 2] = c[i]; // c + _coeff[4 * i + 3] = d[i]; // d + } + } + else { + _coeff = new float[2]; + _isCSpline = false; + + _coeff[0] = minPWMAmount; + _coeff[1] = (maxPWMAmount - minPWMAmount) / 180.0f; + } +} + +PCA9685_ServoEval::~PCA9685_ServoEval() { + if (_coeff) { delete[] _coeff; _coeff = NULL; } +} + +uint16_t PCA9685_ServoEval::pwmForAngle(float angle) { + float retVal; + angle = constrain(angle + 90, 0, 180); + + if (!_isCSpline) { + retVal = _coeff[0] + (_coeff[1] * angle); + } + else { + if (angle <= 90) { + retVal = _coeff[0] + (_coeff[1] * angle) + (_coeff[2] * angle * angle) + (_coeff[3] * angle * angle * angle); + } + else { + angle -= 90; + retVal = _coeff[4] + (_coeff[5] * angle) + (_coeff[6] * angle * angle) + (_coeff[7] * angle * angle * angle); + } + } + + return (uint16_t)min((uint16_t)roundf(retVal), PCA9685_PWM_FULL); +}; + +uint16_t PCA9685_ServoEval::pwmForSpeed(float speed) { + return pwmForAngle(speed * 90.0f); +} diff --git a/src/PCA9685.h b/src/PCA9685.h new file mode 100644 index 0000000..893b9e3 --- /dev/null +++ b/src/PCA9685.h @@ -0,0 +1,338 @@ +/* Arduino Library for the PCA9685 16-Channel PWM Driver Module. + Copyright (C) 2016-2020 NachtRaveVL + Copyright (C) 2012 Kasper SkÃ¥rhøj + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . + + Created by Kasper SkÃ¥rhøj, August 3rd, 2012. + Forked by Vitska, June 18th, 2016. + Forked by NachtRaveVL, July 29th, 2016. + + PCA9685-Arduino - Version 1.2.15 +*/ + +#ifndef PCA9685_H +#define PCA9685_H + +// Library Setup + +// NOTE: While editing the main header file isn't ideal, it is often the easiest given +// the Arduino IDE's limited custom build flag support. Editing this header file directly +// will affect all projects compiled on your system using these library files. + +// Uncomment or -D this define to enable use of the software i2c library (min 4MHz+ processor). +//#define PCA9685_ENABLE_SOFTWARE_I2C // http://playground.arduino.cc/Main/SoftwareI2CLibrary + +// Uncomment or -D this define to swap PWM low(begin)/high(end) phase values in register reads/writes (needed for some chip manufacturers). +//#define PCA9685_SWAP_PWM_BEG_END_REGS + +// Uncomment or -D this define to enable debug output. +//#define PCA9685_ENABLE_DEBUG_OUTPUT + +// Hookup Callouts +// -PLEASE READ- +// Many digital servos run on a 20ms pulse width (50Hz update frequency) based duty cycle, +// and do not utilize the entire pulse width for their control. Typically, 2.5% of the +// 20ms pulse width (0.5ms) represents -90° offset, and 12.5% of the 20ms pulse width +// (2.5ms) represents +90° offset. This roughly translates to raw PCA9685 PWM values of +// 102 and 512 (out of the 4096/12-bit value range) for their -90°/+90° offset control. +// However, these may need to be adjusted to fit your specific servo (e.g. some we've +// tested run ~130 to ~525 for their -90°/+90° offset control). Be aware that driving +// some 180° servos too far past their -90°/+90° operational range can cause a little +// plastic limiter pin to break off and get stuck inside of the servo's gearing, which +// could potentially cause the servo to become jammed and no longer function. Continuous +// servos operate in much the same fashion as 180° servos, but instead of the 2.5%/12.5% +// pulse width controlling a -90°/+90° offset it controls a -1x/+1x speed multiplier, +// with 0x being parked/no-movement and -1x/+1x being maximum speed in either direction. + +#if defined(ARDUINO) && ARDUINO >= 100 +#include +#else +#include +#endif + +#ifndef PCA9685_ENABLE_SOFTWARE_I2C +#include +#if BUFFER_LENGTH +#define PCA9685_I2C_BUFFER_LENGTH BUFFER_LENGTH +#elif I2C_BUFFER_LENGTH +#define PCA9685_I2C_BUFFER_LENGTH I2C_BUFFER_LENGTH +#else +#warning "i2c buffer length not defined - using default value of 32, which may not be correct for your microcontroller. Check Wire.h (or similar) for your hardware and manually define BUFFER_LENGTH or I2C_BUFFER_LENGTH to remove this warning." +#define PCA9685_I2C_BUFFER_LENGTH 32 +#endif // /if BUFFER_LENGTH +#else +#include +#define PCA9685_USE_SOFTWARE_I2C +#endif // /ifndef PCA9685_ENABLE_SOFTWARE_I2C + + +// Default proxy addresser i2c addresses +#define PCA9685_I2C_DEF_ALLCALL_PROXYADR (byte)0xE0 // Default AllCall i2c proxy address +#define PCA9685_I2C_DEF_SUB1_PROXYADR (byte)0xE2 // Default Sub1 i2c proxy address +#define PCA9685_I2C_DEF_SUB2_PROXYADR (byte)0xE4 // Default Sub2 i2c proxy address +#define PCA9685_I2C_DEF_SUB3_PROXYADR (byte)0xE8 // Default Sub3 i2c proxy address + + +// Output driver control mode (see datasheet Table 12 and Fig 13, 14, and 15 concerning correct +// usage of OUTDRV). +enum PCA9685_OutputDriverMode { + PCA9685_OutputDriverMode_OpenDrain, // Module outputs in an open-drain (aka direct connection) style structure with 400mA @5v total sink current, useful for LEDs and low-power Servos + PCA9685_OutputDriverMode_TotemPole, // Module outputs in a totem-pole (aka push-pull) style structure with 400mA @5v total sink current and 160mA total source current, useful for external drivers (default) + + PCA9685_OutputDriverMode_Count, // Internal use only + PCA9685_OutputDriverMode_Undefined = -1 // Internal use only +}; +// NOTE: Totem-pole mode should be used when an external N-type or P-type driver is in +// use, which provides actual sourcing current while open-drain mode doesn't. At max +// channel capacity, the sink current limit is 25mA@5v per channel while the source +// current limit, in totem-pole mode, is 10mA@5v per channel. However, from datasheet +// Table 6. subnote [1]: "Some newer LEDs include integrated Zener diodes to limit +// voltage transients, reduce EMI, and protect the LEDs, and these -MUST- be driven only +// in the open-drain mode to prevent over-heating the IC." Also from datasheet, Section +// 10. question 5: "in the push-pull architecture there is a low resistance path to GND +// through the Zener and this [causes] the IC to overheat." + +// Output-enabled/active-low-OE-pin=LOW driver output mode (see datasheet Table 12 and +// Fig 13, 14, and 15 concerning correct usage of INVRT). +enum PCA9685_OutputEnabledMode { + PCA9685_OutputEnabledMode_Normal, // When OE is enabled/LOW, channels output a normal signal, useful for N-type external drivers (default) + PCA9685_OutputEnabledMode_Inverted, // When OE is enabled/LOW, channels output an inverted signal, useful for P-type external drivers or direct connection + + PCA9685_OutputEnabledMode_Count, // Internal use only + PCA9685_OutputEnabledMode_Undefined = -1 // Internal use only +}; +// NOTE: Polarity inversion is often set according to if an external N-type driver +// (should not use INVRT) or external P-type driver/direct connection (should use INVRT) +// is used. Most breakouts have just a 220Ω resistor between the individual channel +// outputs of the IC and PWM output pins, which is useful when powering LEDs. The V+ rail +// of most breakouts can connect through a 10v 1000μF decoupling capacitor, typically +// already installed on most breakouts, which can reduce voltage spikes and ground bounce +// during phase shifts at the start/end of the PWM high phase when many channel devices +// are connected together. See https://forums.adafruit.com/viewtopic.php?f=8&t=127421 and +// https://forums.adafruit.com/viewtopic.php?f=8&t=162688 for information on installing +// a decoupling capacitor if need arises. + +// Output-not-enabled/active-low-OE-pin=HIGH driver output mode (see datasheet Section +// 7.4 concerning correct usage of OUTNE). +enum PCA9685_OutputDisabledMode { + PCA9685_OutputDisabledMode_Low, // When OE is disabled/HIGH, channels output a LOW signal (default) + PCA9685_OutputDisabledMode_High, // When OE is disabled/HIGH, channels output a HIGH signal (only available in totem-pole mode) + PCA9685_OutputDisabledMode_Floating, // When OE is disabled/HIGH, channel outputs go into a floating (aka high-impedance/high-Z) state, which may be further refined via external pull-up/pull-down resistors + + PCA9685_OutputDisabledMode_Count, // Internal use only + PCA9685_OutputDisabledMode_Undefined = -1 // Internal use only +}; +// NOTE: Active-low-OE pin is typically used to synchronize multiple PCA9685 devices +// together, but can also be used as an external dimming control signal. + +// Channel update strategy used when multiple channels are being updated in batch. +enum PCA9685_ChannelUpdateMode { + PCA9685_ChannelUpdateMode_AfterStop, // Channel updates commit after full-transmission STOP signal (default) + PCA9685_ChannelUpdateMode_AfterAck, // Channel updates commit after individual channel update ACK signal + + PCA9685_ChannelUpdateMode_Count, // Internal use only + PCA9685_ChannelUpdateMode_Undefined = -1 // Internal use only +}; + +// Software-based phase balancing scheme. +enum PCA9685_PhaseBalancer { + PCA9685_PhaseBalancer_None, // Disables software-based phase balancing, relying on installed hardware to handle current sinkage (default) + PCA9685_PhaseBalancer_Linear, // Uses linear software-based phase balancing, with each channel being a preset 16 steps (out of the 4096/12-bit value range) away from previous channel (may cause LED flickering/skipped-cycles on PWM changes) + + PCA9685_PhaseBalancer_Count, // Internal use only + PCA9685_PhaseBalancer_Undefined = -1 // Internal use only +}; +// NOTE: Software-based phase balancing attempts to further mitigate ground bounce and +// voltage spikes during phase shifts at the start/end of the PWM high phase by shifting +// the leading edge of each successive PWM high phase by some amount. This helps make +// the current sinks occur over the entire duty cycle range instead of all together at +// once. Software-based phase balancing can be useful in certain situations, but in +// practice has been the source of many problems, including the case whereby the PCA9685 +// will skip a cycle between PWM changes when the leading/trailing edge is shifted past a +// certain point. While we may revisit this idea in the future, for now we're content on +// leaving None as the default, and limiting the shift that Linear applies. + + +class PCA9685 { +public: +#ifndef PCA9685_USE_SOFTWARE_I2C + + // Library constructor. Typically called during class instantiation, before setup(). + // The i2c address should be the value of the A5-A0 pins, as the class handles the + // module's base i2c address. It should be a value between 0 and 61, which gives a + // maximum of 62 modules that can be addressed on the same i2c line. + // Boards with more than one i2c line (e.g. Due/Mega/etc.) can supply a different + // Wire instance, such as Wire1 (using SDA1/SCL1), Wire2 (using SDA2/SCL2), etc. + // Supported i2c clock speeds are 100kHz, 400kHz (default), and 1000kHz. + PCA9685(byte i2cAddress = B000000, TwoWire& i2cWire = Wire, uint32_t i2cSpeed = 400000); + + // Convenience constructor for custom Wire instance. See main constructor. + PCA9685(TwoWire& i2cWire, uint32_t i2cSpeed = 400000, byte i2cAddress = B000000); + +#else + + // Library constructor. Typically called during class instantiation, before setup(). + // The i2c address should be the value of the A5-A0 pins, as the class handles the + // module's base i2c address. It should be a value between 0 and 61, which gives a + // maximum of 62 modules that can be addressed on the same i2c line. + // Minimum supported i2c clock speed is 100kHz, which sets minimum processor speed at + // 4MHz+ running in i2c standard mode. For up to 400kHz i2c clock speeds, minimum + // processor speed is 16MHz+ running in i2c fast mode. + PCA9685(byte i2cAddress = B000000); + +#endif + + // Resets modules. Typically called in setup(), before any init()'s. Calling will + // perform a software reset on all PCA9685 devices on the Wire instance, ensuring + // that all PCA9685 devices on that line are properly reset. + void resetDevices(); + + // Initializes module. Typically called in setup(). + // See individual enums for more info. + void init(PCA9685_OutputDriverMode driverMode = PCA9685_OutputDriverMode_TotemPole, + PCA9685_OutputEnabledMode enabledMode = PCA9685_OutputEnabledMode_Normal, + PCA9685_OutputDisabledMode disabledMode = PCA9685_OutputDisabledMode_Low, + PCA9685_ChannelUpdateMode updateMode = PCA9685_ChannelUpdateMode_AfterStop, + PCA9685_PhaseBalancer phaseBalancer = PCA9685_PhaseBalancer_None); + + // Convenience initializer for custom phase balancer. See main init method. + void init(PCA9685_PhaseBalancer phaseBalancer, + PCA9685_OutputDriverMode driverMode = PCA9685_OutputDriverMode_TotemPole, + PCA9685_OutputEnabledMode enabledMode = PCA9685_OutputEnabledMode_Normal, + PCA9685_OutputDisabledMode disabledMode = PCA9685_OutputDisabledMode_Low, + PCA9685_ChannelUpdateMode updateMode = PCA9685_ChannelUpdateMode_AfterStop); + + // Initializes module as a proxy addresser. Typically called in setup(). Used when + // instance talks through to AllCall/Sub1-Sub3 instances as a proxy object. Using + // this method will disable any method that performs a read or conflicts with certain + // states. Proxy addresser i2c addresses must be >= 0xE0, with defaults provided via + // PCA9685_I2C_DEF_[ALLCALL|SUB[1-3]]_PROXYADR defines. + void initAsProxyAddresser(); + + // Mode accessors + byte getI2CAddress(); + uint32_t getI2CSpeed(); + PCA9685_OutputDriverMode getOutputDriverMode(); + PCA9685_OutputEnabledMode getOutputEnabledMode(); + PCA9685_OutputDisabledMode getOutputDisabledMode(); + PCA9685_ChannelUpdateMode getChannelUpdateMode(); + PCA9685_PhaseBalancer getPhaseBalancer(); + + // Min: 24Hz, Max: 1526Hz, Default: 200Hz. As Hz increases channel resolution + // diminishes, as raw pre-scaler value, computed per datasheet, starts to require + // much larger frequency increases for single-digit increases of the raw pre-scaler + // value that ultimately controls the PWM frequency produced. + void setPWMFrequency(float pwmFrequency = 200); + // Sets standard servo frequency of 50Hz. + void setPWMFreqServo(); + + // Turns channel either full on or full off + void setChannelOn(int channel); + void setChannelOff(int channel); + + // PWM amounts 0 - 4096, 0 full off, 4096 full on + void setChannelPWM(int channel, uint16_t pwmAmount); + void setChannelsPWM(int begChannel, int numChannels, const uint16_t *pwmAmounts); + + // Sets all channels, but won't distribute phases + void setAllChannelsPWM(uint16_t pwmAmount); + + // Returns PWM amounts 0 - 4096, 0 full off, 4096 full on + uint16_t getChannelPWM(int channel); + + // Enables multiple talk-through paths via i2c bus (lsb/bit0 must stay 0). To use, + // create a new proxy instance using initAsProxyAddresser() with proper proxy i2c + // address >= 0xE0, and pass that instance's i2c address into desired method below. + void enableAllCallAddress(byte i2cAddressAllCall = PCA9685_I2C_DEF_ALLCALL_PROXYADR); + void enableSub1Address(byte i2cAddressSub1 = PCA9685_I2C_DEF_SUB1_PROXYADR); + void enableSub2Address(byte i2cAddressSub2 = PCA9685_I2C_DEF_SUB2_PROXYADR); + void enableSub3Address(byte i2cAddressSub3 = PCA9685_I2C_DEF_SUB3_PROXYADR); + void disableAllCallAddress(); + void disableSub1Address(); + void disableSub2Address(); + void disableSub3Address(); + + // Allows external clock line to be utilized (power reset required to disable) + void enableExtClockLine(); + + byte getLastI2CError(); + +#ifdef PCA9685_ENABLE_DEBUG_OUTPUT + int getWireInterfaceNumber(); + void printModuleInfo(); + void checkForErrors(); +#endif + +protected: + byte _i2cAddress; // Module's i2c address (default: B000000) +#ifndef PCA9685_USE_SOFTWARE_I2C + TwoWire* _i2cWire; // Wire class instance (unowned) (default: Wire) + uint32_t _i2cSpeed; // Module's i2c clock speed (default: 400000) +#endif + PCA9685_OutputDriverMode _driverMode; // Output driver mode + PCA9685_OutputEnabledMode _enabledMode; // OE enabled output mode + PCA9685_OutputDisabledMode _disabledMode; // OE disabled output mode + PCA9685_ChannelUpdateMode _updateMode; // Channel update mode + PCA9685_PhaseBalancer _phaseBalancer; // Phase balancer scheme + bool _isProxyAddresser; // Proxy addresser flag (disables certain functionality) + byte _lastI2CError; // Last module i2c error + + byte getMode2Value(); + void getPhaseCycle(int channel, uint16_t pwmAmount, uint16_t *phaseBegin, uint16_t *phaseEnd); + + void writeChannelBegin(int channel); + void writeChannelPWM(uint16_t phaseBegin, uint16_t phaseEnd); + void writeChannelEnd(); + + void writeRegister(byte regAddress, byte value); + byte readRegister(byte regAddress); + +#ifdef PCA9685_USE_SOFTWARE_I2C + uint8_t _readBytes; +#endif + void i2cWire_begin(); + void i2cWire_beginTransmission(uint8_t); + uint8_t i2cWire_endTransmission(void); + uint8_t i2cWire_requestFrom(uint8_t, uint8_t); + size_t i2cWire_write(uint8_t); + uint8_t i2cWire_read(void); +}; + +// Class to assist with calculating Servo PWM values from angle/speed values +class PCA9685_ServoEval { +public: + // Uses a linear interpolation method to quickly compute PWM output value. Uses + // default values of 2.5% and 12.5% of phase length for -90/+90 (or -1x/+1x). + PCA9685_ServoEval(uint16_t minPWMAmount = 102, uint16_t maxPWMAmount = 512); + + // Uses a cubic spline to interpolate due to an offsetted zero point that isn't + // exactly between -90/+90 (or -1x/+1x). This takes more time to compute, but gives a + // smoother PWM output value along the entire range. + PCA9685_ServoEval(uint16_t minPWMAmount, uint16_t midPWMAmount, uint16_t maxPWMAmount); + + ~PCA9685_ServoEval(); + + // Returns the PWM value to use given the angle offset (-90 to +90) + uint16_t pwmForAngle(float angle); + + // Returns the PWM value to use given the speed multiplier (-1 to +1) + uint16_t pwmForSpeed(float speed); + +private: + float *_coeff; // a,b,c,d coefficient values + bool _isCSpline; // Cubic spline tracking, for _coeff length +}; + +#endif // /ifndef PCA9685_H diff --git a/support files/PCA9685.pdf b/support files/PCA9685.pdf new file mode 100644 index 0000000000000000000000000000000000000000..a484c1f881b30f0bda1bd3acbd449ade6a2515da GIT binary patch literal 408783 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�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
    eqgT=D2T^ef5jaoKeITlj#}IR{~LR6 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 F{|D}nuzvsm literal 0 HcmV?d00001 From a70be39257e317d35e9118b385006a1e030e6452 Mon Sep 17 00:00:00 2001 From: NachtRaveVL Date: Fri, 16 Oct 2020 00:16:30 -0700 Subject: [PATCH 56/57] Ignoring pad. --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index df8bb78..6eddc09 100644 --- a/.gitignore +++ b/.gitignore @@ -8,6 +8,7 @@ Icon? ehthumbs.db Thumbs.db +pad # Generic: ############### From 456fe38a126440e9499625be31a1d049557a52b3 Mon Sep 17 00:00:00 2001 From: NachtRave Date: Wed, 22 Feb 2023 09:45:46 -0800 Subject: [PATCH 57/57] Create FUNDING.yml --- .github/FUNDING.yml | 1 + 1 file changed, 1 insertion(+) create mode 100644 .github/FUNDING.yml diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 0000000..da6009a --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1 @@ +patreon: nachtrave