Arnaud VALLEY
Mirror with some correction
Dependencies: mbed FastIO FastPWM USBDevice
Diff: TLC59116/TLC59116.h
- Revision:
- 87:8d35c74403af
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/TLC59116/TLC59116.h Tue May 09 05:48:37 2017 +0000
@@ -0,0 +1,473 @@
+// TLC59116 interface
+//
+// The TLC59116 is a 16-channel constant-current PWM controller chip with
+// an I2C interface.
+//
+// Up to 14 of these chips can be connected to a single bus. Each chip needs
+// a unique address, configured via four pin inputs. (The I2C address is 7
+// bits, but the high-order 3 bits are fixed in the hardware, leaving 4 bits
+// to configure per chip. Two of the possible 16 addresses are reserved by
+// the chip hardware as broadcast addresses, leaving room for 14 unique chip
+// addresses per bus.)
+//
+// EXTERNAL PULL-UP RESISTORS ARE REQUIRED ON SDA AND SCL. The internal
+// pull-ups in the KL25Z GPIO ports will only work if the bus speed is
+// limited to 100kHz. Higher speeds require external pull-ups. Because
+// of the relatively high data rate required, we use the maximum 1MHz bus
+// speed, requiring external pull-ups. These are typically 2.2K.
+//
+// This chip is similar to the TLC5940, but has a more modern design with
+// several advantages, including a standardized and much more robust data
+// interface (I2C) and glitch-free startup. The only downside vs the TLC5940
+// is that it's only available in an SMD package, whereas the TLC5940 is
+// available in easy-to-solder DIP format. The DIP 5940 is longer being
+// manufactured, but it's still easy to find old stock; when those run out,
+// though, and the choice is between SMD 5940 and 59116, the 59116 will be
+// the clear winner.
+//
+
+#ifndef _TLC59116_H_
+#define _TLC59116_H_
+
+#include "mbed.h"
+#include "BitBangI2C.h"
+
+// Which I2C class are we using? We use this to switch between
+// BitBangI2C and MbedI2C for testing and debugging.
+#define I2C_Type BitBangI2C
+
+// register constants
+struct TLC59116R
+{
+ // control register bits
+ static const uint8_t CTL_AIALL = 0x80; // auto-increment mode, all registers
+ static const uint8_t CTL_AIPWM = 0xA0; // auto-increment mode, PWM registers only
+ static const uint8_t CTL_AICTL = 0xC0; // auto-increment mode, control registers only
+ static const uint8_t CTL_AIPWMCTL = 0xE0; // auto-increment mode, PWM + control registers only
+
+ // register addresses
+ static const uint8_t REG_MODE1 = 0x00; // MODE1
+ static const uint8_t REG_MODE2 = 0x01; // MODE2
+ static const uint8_t REG_PWM0 = 0x02; // PWM 0
+ static const uint8_t REG_PWM1 = 0x03; // PWM 1
+ static const uint8_t REG_PWM2 = 0x04; // PWM 2
+ static const uint8_t REG_PWM3 = 0x05; // PWM 3
+ static const uint8_t REG_PWM4 = 0x06; // PWM 4
+ static const uint8_t REG_PWM5 = 0x07; // PWM 5
+ static const uint8_t REG_PWM6 = 0x08; // PWM 6
+ static const uint8_t REG_PWM7 = 0x09; // PWM 7
+ static const uint8_t REG_PWM8 = 0x0A; // PWM 8
+ static const uint8_t REG_PWM9 = 0x0B; // PWM 9
+ static const uint8_t REG_PWM10 = 0x0C; // PWM 10
+ static const uint8_t REG_PWM11 = 0x0D; // PWM 11
+ static const uint8_t REG_PWM12 = 0x0E; // PWM 12
+ static const uint8_t REG_PWM13 = 0x0F; // PWM 13
+ static const uint8_t REG_PWM14 = 0x10; // PWM 14
+ static const uint8_t REG_PWM15 = 0x11; // PWM 15
+ static const uint8_t REG_GRPPWM = 0x12; // Group PWM duty cycle
+ static const uint8_t REG_GRPFREQ = 0x13; // Group frequency register
+ static const uint8_t REG_LEDOUT0 = 0x14; // LED driver output status register 0
+ static const uint8_t REG_LEDOUT1 = 0x15; // LED driver output status register 1
+ static const uint8_t REG_LEDOUT2 = 0x16; // LED driver output status register 2
+ static const uint8_t REG_LEDOUT3 = 0x17; // LED driver output status register 3
+
+ // MODE1 bits
+ static const uint8_t MODE1_AI2 = 0x80; // auto-increment mode enable
+ static const uint8_t MODE1_AI1 = 0x40; // auto-increment bit 1
+ static const uint8_t MODE1_AI0 = 0x20; // auto-increment bit 0
+ static const uint8_t MODE1_OSCOFF = 0x10; // oscillator off
+ static const uint8_t MODE1_SUB1 = 0x08; // subaddress 1 enable
+ static const uint8_t MODE1_SUB2 = 0x04; // subaddress 2 enable
+ static const uint8_t MODE1_SUB3 = 0x02; // subaddress 3 enable
+ static const uint8_t MODE1_ALLCALL = 0x01; // all-call enable
+
+ // MODE2 bits
+ static const uint8_t MODE2_EFCLR = 0x80; // clear error status flag
+ static const uint8_t MODE2_DMBLNK = 0x20; // group blinking mode
+ static const uint8_t MODE2_OCH = 0x08; // outputs change on ACK (vs Stop command)
+
+ // LEDOUTn states
+ static const uint8_t LEDOUT_OFF = 0x00; // driver is off
+ static const uint8_t LEDOUT_ON = 0x01; // fully on
+ static const uint8_t LEDOUT_PWM = 0x02; // individual PWM control via PWMn register
+ static const uint8_t LEDOUT_GROUP = 0x03; // PWM control + group dimming/blinking via PWMn + GRPPWM
+};
+
+
+// Individual unit object. We create one of these for each unit we
+// find on the bus. This keeps track of the state of each output on
+// a unit so that we can update outputs in batches, to reduce the
+// amount of time we spend in I2C communications during rapid updates.
+struct TLC59116Unit
+{
+ TLC59116Unit()
+ {
+ // start inactive, since we haven't been initialized yet
+ active = false;
+
+ // set all brightness levels to 0 intially
+ memset(bri, 0, sizeof(bri));
+
+ // mark all outputs as dirty to force an update after initializing
+ dirty = 0xFFFF;
+ }
+
+ // initialize
+ void init(int addr, I2C_Type &i2c)
+ {
+ // set all output drivers to individual PWM control
+ const uint8_t all_pwm =
+ TLC59116R::LEDOUT_PWM
+ | (TLC59116R::LEDOUT_PWM << 2)
+ | (TLC59116R::LEDOUT_PWM << 4)
+ | (TLC59116R::LEDOUT_PWM << 6);
+ static const uint8_t buf[] = {
+ TLC59116R::REG_LEDOUT0 | TLC59116R::CTL_AIALL,
+ all_pwm,
+ all_pwm,
+ all_pwm,
+ all_pwm
+ };
+ int err = i2c.write(addr << 1, buf, sizeof(buf));
+
+ // turn on the oscillator
+ static const uint8_t buf2[] = {
+ TLC59116R::REG_MODE1,
+ TLC59116R::MODE1_AI2 | TLC59116R::MODE1_ALLCALL
+ };
+ err |= i2c.write(addr << 1, buf2, sizeof(buf));
+
+ // mark the unit as active if the writes succeeded
+ active = !err;
+ }
+
+ // Set an output
+ void set(int idx, int val)
+ {
+ // validate the index
+ if (idx >= 0 && idx <= 15)
+ {
+ // record the new brightness
+ bri[idx] = val;
+
+ // set the dirty bit
+ dirty |= 1 << idx;
+ }
+ }
+
+ // Get an output's current value
+ int get(int idx) const
+ {
+ return idx >= 0 && idx <= 15 ? bri[idx] : -1;
+ }
+
+ // Send I2C updates
+ void send(int addr, I2C_Type &i2c)
+ {
+ // Scan all outputs. I2C sends are fairly expensive, so we
+ // minimize the send time by using the auto-increment mode.
+ // Optimizing this is a bit tricky. Suppose that the outputs
+ // are in this state, where c represents a clean output and D
+ // represents a dirty output:
+ //
+ // cccDcDccc...
+ //
+ // Clearly we want to start sending at the first dirty output
+ // so that we don't waste time sending the three clean bytes
+ // ahead of it. However, do we send output[3] as one chunk
+ // and then send output[5] as a separate chunk, or do we send
+ // outputs [3],[4],[5] as a single block to take advantage of
+ // the auto-increment mode? Based on I2C bus timing parameters,
+ // the answer is that it's cheaper to send this as a single
+ // contiguous block [3],[4],[5]. The reason is that the cost
+ // of starting a new block is a Stop/Start sequence plus another
+ // register address byte; the register address byte costs the
+ // same as a data byte, so the extra Stop/Start of the separate
+ // chunk approach makes the single continguous send cheaper.
+ // But how about this one?:
+ //
+ // cccDccDccc...
+ //
+ // This one is cheaper to send as two separate blocks. The
+ // break costs us a Start/Stop plus a register address byte,
+ // but the Start/Stop is only about 25% of the cost of a data
+ // byte, so Start/Stop+Register Address is cheaper than sending
+ // the two clean data bytes sandwiched between the dirty bytes.
+ //
+ // So: we want to look for sequences of contiguous dirty bytes
+ // and send those as a chunk. We furthermore will allow up to
+ // one clean byte in the midst of the dirty bytes.
+ uint8_t buf[17];
+ int n = 0;
+ for (int i = 0, bit = 1 ; i < 16 ; ++i, bit <<= 1)
+ {
+ // If this one is dirty, include it in the set of outputs to
+ // send to the chip. Also include this one if it's clean
+ // and the outputs on both sides are dirty - see the notes
+ // above about optimizing for the case where we have one clean
+ // output surrounded by dirty outputs.
+ if ((dirty & bit) != 0)
+ {
+ // it's dirty - add it to the dirty set under construction
+ buf[++n] = bri[i];
+ }
+ else if (n != 0 && n < 15 && (dirty & (bit << 1)) != 0)
+ {
+ // this one is clean, but the one before and the one after
+ // are both dirty, so keep it in the set anyway to take
+ // advantage of the auto-increment mode for faster sends
+ buf[++n] = bri[i];
+ }
+ else
+ {
+ // This one is clean, and it's not surrounded by dirty
+ // outputs. If the set of dirty outputs so far has any
+ // members, send them now.
+ if (n != 0)
+ {
+ // set the starting register address, including the
+ // auto-increment flag, and write the block
+ buf[0] = (TLC59116R::REG_PWM0 + i - n) | TLC59116R::CTL_AIALL;
+ i2c.write(addr << 1, buf, n + 1);
+
+ // empty the set
+ n = 0;
+ }
+ }
+ }
+
+ // if we finished the loop with dirty outputs to send, send them
+ if (n != 0)
+ {
+ // fill in the starting register address, and write the block
+ buf[0] = (TLC59116R::REG_PWM15 + 1 - n) | TLC59116R::CTL_AIALL;
+ i2c.write(addr << 1, buf, n + 1);
+ }
+
+ // all outputs are now clean
+ dirty = 0;
+ }
+
+ // Is the unit active? If we have trouble writing a unit,
+ // we can mark it inactive so that we know to stop wasting
+ // time writing to it, and so that we can re-initialize it
+ // if it comes back on later bus scans.
+ bool active;
+
+ // Output states. This records the latest brightness level
+ // for each output as set by the client. We don't actually
+ // send these values to the physical unit until the client
+ // tells us to do an I2C update.
+ uint8_t bri[16];
+
+ // Dirty output mask. Whenever the client changes an output,
+ // we record the new brightness in bri[] and set the
+ // corresponding bit here to 1. We use these bits to determine
+ // which outputs to send during each I2C update.
+ uint16_t dirty;
+};
+
+// TLC59116 public interface. This provides control over a collection
+// of units connected on a common I2C bus.
+class TLC59116
+{
+public:
+ // Initialize. The address given is the configurable part
+ // of the address, 0x0000 to 0x000F.
+ TLC59116(PinName sda, PinName scl, PinName reset)
+ : i2c(sda, scl, true), reset(reset)
+ {
+ // Use the fastest I2C speed possible, since we want to be able
+ // to rapidly update many outputs at once. The TLC59116 can run
+ // I2C at up to 1MHz.
+ i2c.frequency(1000000);
+
+ // assert !RESET until we're ready to go
+ this->reset.write(0);
+
+ // there are no units yet
+ memset(units, 0, sizeof(units));
+ nextUpdate = 0;
+ }
+
+ void init()
+ {
+ // un-assert reset
+ reset.write(1);
+ wait_us(10000);
+
+ // scan the bus for new units
+ scanBus();
+ }
+
+ // scan the bus
+ void scanBus()
+ {
+ // scan each possible address
+ for (int i = 0 ; i < 16 ; ++i)
+ {
+ // Address 8 and 11 are reserved - skip them
+ if (i == 8 || i == 11)
+ continue;
+
+ // Try reading register REG_MODE1
+ int addr = I2C_BASE_ADDR | i;
+ TLC59116Unit *u = units[i];
+ if (readReg8(addr, TLC59116R::REG_MODE1) >= 0)
+ {
+ // success - if the slot wasn't already populated, allocate
+ // a unit entry for it
+ if (u == 0)
+ units[i] = u = new TLC59116Unit();
+
+ // if the unit isn't already marked active, initialize it
+ if (!u->active)
+ u->init(addr, i2c);
+ }
+ else
+ {
+ // failed - if the unit was previously active, mark it
+ // as inactive now
+ if (u != 0)
+ u->active = false;
+ }
+ }
+ }
+
+ // set an output
+ void set(int unit, int output, int val)
+ {
+ if (unit >= 0 && unit <= 15)
+ {
+ TLC59116Unit *u = units[unit];
+ if (u != 0)
+ u->set(output, val);
+ }
+ }
+
+ // get an output's current value
+ int get(int unit, int output)
+ {
+ if (unit >= 0 && unit <= 15)
+ {
+ TLC59116Unit *u = units[unit];
+ if (u != 0)
+ return u->get(output);
+ }
+
+ return -1;
+ }
+
+ // Send I2C updates to the next unit. The client must call this
+ // periodically to send pending updates. We only update one unit on
+ // each call to ensure that the time per cycle is relatively constant
+ // (rather than scaling with the number of chips).
+ void send()
+ {
+ // look for a dirty unit
+ for (int i = 0, n = nextUpdate ; i < 16 ; ++i, ++n)
+ {
+ // wrap the unit number
+ n &= 0x0F;
+
+ // if this unit is populated and dirty, it's the one to update
+ TLC59116Unit *u = units[n];
+ if (u != 0 && u->dirty != 0)
+ {
+ // it's dirty - update it
+ u->send(I2C_BASE_ADDR | n, i2c);
+
+ // We only update one on each call, so we're done.
+ // Remember where to pick up again on the next update()
+ // call, and return.
+ nextUpdate = n + 1;
+ return;
+ }
+ }
+ }
+
+ // Enable/disable all outputs
+ void enable(bool f)
+ {
+ // visit each populated unit
+ for (int i = 0 ; i < 16 ; ++i)
+ {
+ // if this unit is populated, enable/disable it
+ TLC59116Unit *u = units[i];
+ if (u != 0)
+ {
+ // read the current MODE1 register
+ int m = readReg8(I2C_BASE_ADDR | i, TLC59116R::REG_MODE1);
+ if (m >= 0)
+ {
+ // Turn the oscillator off to disable, on to enable.
+ // Note that the bit is kind of backwards: SETTING the
+ // OSC bit turns the oscillator OFF.
+ if (f)
+ m &= ~TLC59116R::MODE1_OSCOFF; // enable - clear the OSC bit
+ else
+ m |= TLC59116R::MODE1_OSCOFF; // disable - set the OSC bit
+
+ // update MODE1
+ writeReg8(I2C_BASE_ADDR | i, TLC59116R::REG_MODE1, m);
+ }
+ }
+ }
+ }
+
+protected:
+ // TLC59116 base I2C address. These chips use an address of
+ // the form 110xxxx, where the the low four bits are set by
+ // external pins on the chip. The top three bits are always
+ // the same, so we construct the full address by combining
+ // the upper three fixed bits with the four-bit unit number.
+ //
+ // Note that addresses 1101011 (0x6B) and 1101000 (0x68) are
+ // reserved (for SWRSTT and ALLCALL, respectively), and can't
+ // be used for configured device addresses.
+ static const uint8_t I2C_BASE_ADDR = 0x60;
+
+ // Units. We populate this with active units we find in
+ // bus scans. Note that units 8 and 11 can't be used because
+ // of the reserved ALLCALL and SWRST addresses, but we allocate
+ // the slots anyway to keep indexing simple.
+ TLC59116Unit *units[16];
+
+ // next unit to update
+ int nextUpdate;
+
+ // read 8-bit register; returns the value read on success, -1 on failure
+ int readReg8(int addr, uint16_t registerAddr)
+ {
+ // write the request - register address + auto-inc mode
+ uint8_t data_write[1];
+ data_write[0] = registerAddr | TLC59116R::CTL_AIALL;
+ if (i2c.write(addr << 1, data_write, 1, true))
+ return -1;
+
+ // read the result
+ uint8_t data_read[1];
+ if (i2c.read(addr << 1, data_read, 1))
+ return -1;
+
+ // return the result
+ return data_read[0];
+ }
+
+ // write 8-bit register; returns true on success, false on failure
+ bool writeReg8(int addr, uint16_t registerAddr, uint8_t data)
+ {
+ uint8_t data_write[2];
+ data_write[0] = registerAddr | TLC59116R::CTL_AIALL;
+ data_write[1] = data;
+ return !i2c.write(addr << 1, data_write, 2);
+ }
+
+ // I2C bus interface
+ I2C_Type i2c;
+
+ // reset pin (active low)
+ DigitalOut reset;
+};
+
+#endif