alex/GY-63_MS5611
1
0
Fork 0
mirror of https://github.com/RobTillaart/Arduino.git synced 2024-10-03 18:09:02 -04:00
Code Issues Actions Packages Projects Releases Wiki Activity
dbdfc55988
GY-63_MS5611/libraries/PCA9685_RT/README.md
rob tillaart 7fdc79cf82 0.4.1 PCA9685_RT
2022-11-19 17:04:25 +01:00

9.0 KiB
Raw Blame History

Arduino CI Arduino-lint JSON check License: MIT GitHub release

PCA9685_RT

Arduino library for PCA9685 I2C 12 bit PWM LED driver, 16 channel.

Description

This library is to control the I2C PCA9685 PWM extender. The 16 channels are independently configurable in steps of 1/4096. This allows for better than 0.1% fine tuning of the duty-cycle of the PWM signal.

The PWM's of the different channels have individual start and stop moments. This can be used to distribute the power more evenly over multiple servo's or give special effects when used in an RGB LED.

The frequency of the PWM can be set from 24 to 1526 according to the datasheet, however in practice not all frequencies are set accurate. Lower frequencies do better than higher frequencies.

Interface

Constructor

  • PCA9685(uint8_t deviceAddress, TwoWire * wire = &Wire) Constructor with I2C device address, and optional the Wire interface as parameter.
  • bool begin(uint8_t mode1_mask = PCA9685_MODE1_AUTOINCR | PCA9685_MODE1_ALLCALL, uint8_t mode2_mask = PCA9685_MODE2_TOTEMPOLE) initializes the library after startup. Optionally setting the MODE1 and MODE2 configuration registers. See PCA9685.h and datasheet for settings possible.
  • bool begin(uint8_t sda, uint8_t scl, uint8_t mode1_mask = PCA9685_MODE1_AUTOINCR | PCA9685_MODE1_ALLCALL, uint8_t mode2_mask = PCA9685_MODE2_TOTEMPOLE) idem, ESP32 ESP8266 only.
  • void configure(uint8_t mode1_mask, uint8_t mode2_mask) To configure the library after startup one can set the MODE1 and MODE2 configuration registers. See PCA9685.h and datasheet for settings possible.
  • bool isConnected() checks if address is available on I2C bus.
  • uint8_t channelCount() returns the number of channels = 16.

Mode registers

Used to configure the PCA9685 general behaviour.

  • uint8_t writeMode(uint8_t reg, uint8_t value) configuration of one of the two configuration registers. Check datasheet for details.
  • uint8_t readMode(uint8_t reg) reads back the configured mode, useful to add or remove a single flag (bit masking).
  • uint8_t setMode1(uint8_t value) convenience wrapper.
  • uint8_t setMode2(uint8_t value) convenience wrapper.
  • uint8_t getMode1() convenience wrapper.
  • uint8_t getMode2() convenience wrapper.

Constants for mode registers

(added 0.4.0)

Name Value Description
PCA9685_MODE1_RESTART 0x80 0 = disable 1 = enable
PCA9685_MODE1_EXTCLK 0x40 0 = internal 1 = external
PCA9685_MODE1_AUTOINCR 0x20 0 = disable 1 = enable
PCA9685_MODE1_SLEEP 0x10 0 = normal 1 = sleep
PCA9685_MODE1_SUB1 0x08 0 = disable 1 = enable
PCA9685_MODE1_SUB2 0x04 0 = disable 1 = enable
PCA9685_MODE1_SUB3 0x02 0 = disable 1 = enable
PCA9685_MODE1_ALLCALL 0x01 0 = disable 1 = enable
PCA9685_MODE1_NONE 0x00
PCA9685_MODE2_BLINK 0x20 0 = dim 1 = blink
PCA9685_MODE2_INVERT 0x10 0 = normal 1 = inverted
PCA9685_MODE2_STOP 0x08 0 = on STOP 1 = on ACK
PCA9685_MODE2_TOTEMPOLE 0x04 0 = open drain 1 = totem-pole
PCA9685_MODE2_OUTNE 0x03 check datasheet
PCA9685_MODE2_NONE 0x00

These constants makes it easier to set modes without using a non descriptive bit mask. The constants can be merged by OR-ing them together, see snippet:

ledArray.writeMode(PCA9685_MODE2, 0b00110100);

// would become

uint8_t mode2_mask = PCA9685_MODE2_BLINK | PCA9685_MODE2_INVERT | PCA9685_MODE2_TOTEMPOLE;
ledArray.writeMode(PCA9685_MODE2, mode2_mask);

// or even

ledArray.setMode2(PCA9685_MODE2_BLINK | PCA9685_MODE2_INVERT | PCA9685_MODE2_TOTEMPOLE);

PWM

  • void setPWM(uint8_t channel, uint16_t onTime, uint16_t offTime) The chip has 16 channels to do PWM. The signal is divided in 4096 steps, 0..4095. The pulse can begin onTime on any step and it can stop on any step offTime. This allows e.g. to distribute the power over the 16 channels, e.g. the channels do not need to start at the same moment with HIGH.
  • void setPWM(uint8_t channel, offTime) simple PWM that always start on onTime = 0.
  • void getPWM(uint8_t channel, uint16_t * onTime, uint16_t * offTime) read back the configuration of the channel.
  • void allOFF() switches all PWM channels OFF. Experimental in 0.3.0. To "undo" the allOFF one can call the reset() function and set all PWM channels again.
  • void digitalWrite(channel, mode) mode = HIGH or LOW, just use the PCA9685 as a digital pin. This single function replaces the setON() and setOFF() that will become obsolete in the future.

Frequency

  • void setFrequency(uint16_t freq, int offset = 0) set the update speed of the channels. This value is set the same for all channels at once.
  • int getFrequency(bool cache = true) get the current update frequency of the channels. This is same for all channels. If cache is false, the frequency is fetched and calculated from the preScaler register and will probably differ from the value set with setFrequency().

The frequency is constrained to be between 24 and 1526 Hz. As the frequency is converted to an 8 bit preScaler, the frequency set will seldom be exact. After changing the frequency, one must set all channels (again), so one should set the frequency in setup()

The parameter offset can be used to tune the preScaler to get a frequency closer to the requested value. See PCA9685_setFrequency_offset example. Default the offset = 0. As the preScaler is smaller at higher frequencies higher frequencies are less accurate. Making offset too large can result in very incorrect frequencies.

When using offset, the getFrequency(false) will return the adjusted preScaler.

Miscellaneous

  • int lastError() returns PCA9685_OK = 0 if all is OK, and
Error code Value Description
PCA9685_OK 0x00 Everything went well
PCA9685_ERROR 0xFF generic error
PCA9685_ERR_CHANNEL 0xFE Channel out of range
PCA9685_ERR_MODE 0xFD Invalid mode register chosen
PCA9685_ERR_I2C 0xFC PCA9685 I2C communication error

SUB CALL and ALL CALL

(new since 0.4.0)

Please read the datasheet to understand the working of SUB CALL and ALL CALL.

Since version 0.4.0 there is (experimental) support for the SUB CALL and ALL CALL functions. It needs more testing and if there are issues, please report.

AllCall is automatically activated for each device on startup.

Description

SUB CALL allows one to make groups of PCA9685 devices and control them on group level. The number of groups one can make depends on free I2C addresses on one I2C bus. Using multiple I2C buses or multiplexers will even increase the possible number. Every PCA9685 device can be member of up to three of these groups. To become member one needs to set the setSubCallAddress(nr, address) and enable it with enableSubCall(nr).

In the same way one can become member of an ALL CALL group. Typically there is only one such group but one can configure more of them by applying different addresses.

Interface

The functions to enable all/sub-addresses are straightforward:

  • bool enableSubCall(uint8_t nr) nr = 1,2,3

  • bool disableSubCall(uint8_t nr) nr = 1,2,3

  • bool isEnabledSubCall(uint8_t nr) nr = 1,2,3

  • bool setSubCallAddress(uint8_t nr, uint8_t address)

  • uint8_t getSubCallAddress(uint8_t nr)

  • bool enableAllCall()

  • bool disableAllCall()

  • bool isEnabledAllCall()

  • bool setAllCallAddress(uint8_t address)

  • uint8_t getAllCallAddress()

Operation

See examples

Future

must

  • improve documentation

should

  • add unit tests (if possible)

could

  • investigate int vs uint16_t ?
    • setFrequency(), getFrequency(), _freq
  • sync with PCA9634/35/85 where possible
    • error handling?