Mirror with some correction
Dependencies: mbed FastIO FastPWM USBDevice
TLC5940/TLC5940.h@48:058ace2aed1d, 2016-02-26 (annotated)
- Committer:
- mjr
- Date:
- Fri Feb 26 18:42:03 2016 +0000
- Revision:
- 48:058ace2aed1d
- Parent:
- 47:df7a88cd249c
- Child:
- 54:fd77a6b2f76c
New plunger processing 1
Who changed what in which revision?
User | Revision | Line number | New contents of line |
---|---|---|---|
mjr | 26:cb71c4af2912 | 1 | // Pinscape Controller TLC5940 interface |
mjr | 26:cb71c4af2912 | 2 | // |
mjr | 26:cb71c4af2912 | 3 | // Based on Spencer Davis's mbed TLC5940 library. Adapted for the |
mjr | 26:cb71c4af2912 | 4 | // KL25Z, and simplified to just the functions needed for this |
mjr | 26:cb71c4af2912 | 5 | // application. In particular, this version doesn't include support |
mjr | 26:cb71c4af2912 | 6 | // for dot correction programming or status input. This version also |
mjr | 26:cb71c4af2912 | 7 | // uses a different approach for sending the grayscale data updates, |
mjr | 26:cb71c4af2912 | 8 | // sending updates during the blanking interval rather than overlapping |
mjr | 26:cb71c4af2912 | 9 | // them with the PWM cycle. This results in very slightly longer |
mjr | 26:cb71c4af2912 | 10 | // blanking intervals when updates are pending, effectively reducing |
mjr | 26:cb71c4af2912 | 11 | // the PWM "on" duty cycle (and thus the output brightness) by about |
mjr | 26:cb71c4af2912 | 12 | // 0.3%. This shouldn't be perceptible to users, so it's a small |
mjr | 26:cb71c4af2912 | 13 | // trade-off for the advantage gained, which is much better signal |
mjr | 26:cb71c4af2912 | 14 | // stability when using multiple TLC5940s daisy-chained together. |
mjr | 26:cb71c4af2912 | 15 | // I saw a lot of instability when using the overlapped approach, |
mjr | 26:cb71c4af2912 | 16 | // which seems to be eliminated entirely when sending updates during |
mjr | 26:cb71c4af2912 | 17 | // the blanking interval. |
mjr | 26:cb71c4af2912 | 18 | |
mjr | 26:cb71c4af2912 | 19 | |
mjr | 26:cb71c4af2912 | 20 | #ifndef TLC5940_H |
mjr | 26:cb71c4af2912 | 21 | #define TLC5940_H |
mjr | 26:cb71c4af2912 | 22 | |
mjr | 38:091e511ce8a0 | 23 | // Data Transmission Mode. |
mjr | 38:091e511ce8a0 | 24 | // |
mjr | 38:091e511ce8a0 | 25 | // NOTE! This section contains a possible workaround to try if you're |
mjr | 38:091e511ce8a0 | 26 | // having data signal stability problems with your TLC5940 chips. If |
mjr | 40:cc0d9814522b | 27 | // things are working properly, you can ignore this part. |
mjr | 33:d832bcab089e | 28 | // |
mjr | 38:091e511ce8a0 | 29 | // The software has two options for sending data updates to the chips: |
mjr | 38:091e511ce8a0 | 30 | // |
mjr | 40:cc0d9814522b | 31 | // Mode 0: Send data *during* the grayscale cycle. This is the default, |
mjr | 40:cc0d9814522b | 32 | // and it's the standard method the chips are designed for. In this mode, |
mjr | 40:cc0d9814522b | 33 | // we start sending an update just after then blanking interval that starts |
mjr | 40:cc0d9814522b | 34 | // a new grayscale cycle. The timing is arranged so that the update is |
mjr | 40:cc0d9814522b | 35 | // completed well before the end of the grayscale cycle. At the next |
mjr | 40:cc0d9814522b | 36 | // blanking interval, we latch the new data, so the new brightness levels |
mjr | 40:cc0d9814522b | 37 | // will be shown starting on the next cycle. |
mjr | 40:cc0d9814522b | 38 | |
mjr | 38:091e511ce8a0 | 39 | // Mode 1: Send data *between* grayscale cycles. In this mode, we send |
mjr | 38:091e511ce8a0 | 40 | // each complete update during a blanking period, then latch the update |
mjr | 38:091e511ce8a0 | 41 | // and start the next grayscale cycle. This isn't the way the chips were |
mjr | 38:091e511ce8a0 | 42 | // intended to be used, but it works. The disadvantage is that it requires |
mjr | 40:cc0d9814522b | 43 | // the blanking interval to be extended long enough for the full data |
mjr | 40:cc0d9814522b | 44 | // update (192 bits * the number of chips in the chain). Since the |
mjr | 40:cc0d9814522b | 45 | // outputs are turned off throughout the blanking period, this reduces |
mjr | 38:091e511ce8a0 | 46 | // the overall brightness/intensity of the outputs by reducing the duty |
mjr | 38:091e511ce8a0 | 47 | // cycle. The TLC5940 chips can't achieve 100% duty cycle to begin with, |
mjr | 40:cc0d9814522b | 48 | // since they require a brief minimum time in the blanking interval |
mjr | 38:091e511ce8a0 | 49 | // between grayscale cycles; however, the minimum is so short that the |
mjr | 38:091e511ce8a0 | 50 | // duty cycle is close to 100%. With the full data transmission stuffed |
mjr | 38:091e511ce8a0 | 51 | // into the blanking interval, we reduce the duty cycle further below |
mjr | 38:091e511ce8a0 | 52 | // 100%. With four chips in the chain, a 28 MHz data clock, and a |
mjr | 38:091e511ce8a0 | 53 | // 500 kHz grayscale clock, the reduction is about 0.3%. |
mjr | 33:d832bcab089e | 54 | // |
mjr | 40:cc0d9814522b | 55 | // Mode 0 is the method documented in the manufacturer's data sheet. |
mjr | 40:cc0d9814522b | 56 | // It works well empirically with the Pinscape expansion boards. |
mjr | 40:cc0d9814522b | 57 | // |
mjr | 38:091e511ce8a0 | 58 | // So what's the point of Mode 1? In early testing, with a breadboard |
mjr | 38:091e511ce8a0 | 59 | // setup, I saw some problems with data signal stability, which manifested |
mjr | 38:091e511ce8a0 | 60 | // as sporadic flickering in the outputs. Switching to Mode 1 improved |
mjr | 38:091e511ce8a0 | 61 | // the signal stability considerably. I'm therefore leaving this code |
mjr | 38:091e511ce8a0 | 62 | // available as an option in case anyone runs into similar signal problems |
mjr | 38:091e511ce8a0 | 63 | // and wants to try the alternative mode as a workaround. |
mjr | 38:091e511ce8a0 | 64 | // |
mjr | 38:091e511ce8a0 | 65 | #define DATA_UPDATE_INSIDE_BLANKING 0 |
mjr | 33:d832bcab089e | 66 | |
mjr | 26:cb71c4af2912 | 67 | #include "mbed.h" |
mjr | 26:cb71c4af2912 | 68 | #include "FastPWM.h" |
mjr | 30:6e9902f06f48 | 69 | #include "SimpleDMA.h" |
mjr | 47:df7a88cd249c | 70 | #include "DMAChannels.h" |
mjr | 26:cb71c4af2912 | 71 | |
mjr | 26:cb71c4af2912 | 72 | /** |
mjr | 26:cb71c4af2912 | 73 | * SPI speed used by the mbed to communicate with the TLC5940 |
mjr | 26:cb71c4af2912 | 74 | * The TLC5940 supports up to 30Mhz. It's best to keep this as |
mjr | 33:d832bcab089e | 75 | * high as possible, since a higher SPI speed yields a faster |
mjr | 33:d832bcab089e | 76 | * grayscale data update. However, I've seen some slight |
mjr | 33:d832bcab089e | 77 | * instability in the signal in my breadboard setup using the |
mjr | 33:d832bcab089e | 78 | * full 30MHz, so I've reduced this slightly, which seems to |
mjr | 33:d832bcab089e | 79 | * yield a solid signal. The limit will vary according to how |
mjr | 33:d832bcab089e | 80 | * clean the signal path is to the chips; you can probably crank |
mjr | 33:d832bcab089e | 81 | * this up to full speed if you have a well-designed PCB, good |
mjr | 33:d832bcab089e | 82 | * decoupling capacitors near the 5940 VCC/GND pins, and short |
mjr | 33:d832bcab089e | 83 | * wires between the KL25Z and the PCB. A short, clean path to |
mjr | 33:d832bcab089e | 84 | * KL25Z ground seems especially important. |
mjr | 26:cb71c4af2912 | 85 | * |
mjr | 26:cb71c4af2912 | 86 | * The SPI clock must be fast enough that the data transmission |
mjr | 26:cb71c4af2912 | 87 | * time for a full update is comfortably less than the blanking |
mjr | 26:cb71c4af2912 | 88 | * cycle time. The grayscale refresh requires 192 bits per TLC5940 |
mjr | 26:cb71c4af2912 | 89 | * in the daisy chain, and each bit takes one SPI clock to send. |
mjr | 26:cb71c4af2912 | 90 | * Our reference setup in the Pinscape controller allows for up to |
mjr | 26:cb71c4af2912 | 91 | * 4 TLC5940s, so a full refresh cycle on a fully populated system |
mjr | 26:cb71c4af2912 | 92 | * would be 768 SPI clocks. The blanking cycle is 4096 GSCLK cycles. |
mjr | 26:cb71c4af2912 | 93 | * |
mjr | 26:cb71c4af2912 | 94 | * t(blank) = 4096 * 1/GSCLK_SPEED |
mjr | 26:cb71c4af2912 | 95 | * t(refresh) = 768 * 1/SPI_SPEED |
mjr | 26:cb71c4af2912 | 96 | * Therefore: SPI_SPEED must be > 768/4096 * GSCLK_SPEED |
mjr | 26:cb71c4af2912 | 97 | * |
mjr | 26:cb71c4af2912 | 98 | * Since the SPI speed can be so high, and since we want to keep |
mjr | 26:cb71c4af2912 | 99 | * the GSCLK speed relatively low, the constraint above simply |
mjr | 26:cb71c4af2912 | 100 | * isn't a factor. E.g., at SPI=30MHz and GSCLK=500kHz, |
mjr | 26:cb71c4af2912 | 101 | * t(blank) is 8192us and t(refresh) is 25us. |
mjr | 26:cb71c4af2912 | 102 | */ |
mjr | 38:091e511ce8a0 | 103 | #define SPI_SPEED 28000000 |
mjr | 26:cb71c4af2912 | 104 | |
mjr | 26:cb71c4af2912 | 105 | /** |
mjr | 26:cb71c4af2912 | 106 | * The rate at which the GSCLK pin is pulsed. This also controls |
mjr | 26:cb71c4af2912 | 107 | * how often the reset function is called. The reset function call |
mjr | 38:091e511ce8a0 | 108 | * interval is (1/GSCLK_SPEED) * 4096. The maximum reliable rate is |
mjr | 26:cb71c4af2912 | 109 | * around 32Mhz. It's best to keep this rate as low as possible: |
mjr | 26:cb71c4af2912 | 110 | * the higher the rate, the higher the refresh() call frequency, |
mjr | 40:cc0d9814522b | 111 | * so the higher the CPU load. Higher frequencies also make it more |
mjr | 40:cc0d9814522b | 112 | * challenging to wire the chips for clean signal transmission, so |
mjr | 40:cc0d9814522b | 113 | * minimizing the clock speed will help with signal stability. |
mjr | 26:cb71c4af2912 | 114 | * |
mjr | 40:cc0d9814522b | 115 | * The lower bound depends on the application. For driving lights, |
mjr | 40:cc0d9814522b | 116 | * the limiting factor is flicker: the lower the rate, the more |
mjr | 40:cc0d9814522b | 117 | * noticeable the flicker. Incandescents tend to look flicker-free |
mjr | 40:cc0d9814522b | 118 | * at about 50 Hz (205 kHz grayscale clock). LEDs need slightly |
mjr | 40:cc0d9814522b | 119 | * faster rates. |
mjr | 26:cb71c4af2912 | 120 | */ |
mjr | 40:cc0d9814522b | 121 | #define GSCLK_SPEED 350000 |
mjr | 26:cb71c4af2912 | 122 | |
mjr | 26:cb71c4af2912 | 123 | /** |
mjr | 26:cb71c4af2912 | 124 | * This class controls a TLC5940 PWM driver IC. |
mjr | 26:cb71c4af2912 | 125 | * |
mjr | 26:cb71c4af2912 | 126 | * Using the TLC5940 class to control an LED: |
mjr | 26:cb71c4af2912 | 127 | * @code |
mjr | 26:cb71c4af2912 | 128 | * #include "mbed.h" |
mjr | 26:cb71c4af2912 | 129 | * #include "TLC5940.h" |
mjr | 26:cb71c4af2912 | 130 | * |
mjr | 26:cb71c4af2912 | 131 | * // Create the TLC5940 instance |
mjr | 26:cb71c4af2912 | 132 | * TLC5940 tlc(p7, p5, p21, p9, p10, p11, p12, 1); |
mjr | 26:cb71c4af2912 | 133 | * |
mjr | 26:cb71c4af2912 | 134 | * int main() |
mjr | 26:cb71c4af2912 | 135 | * { |
mjr | 26:cb71c4af2912 | 136 | * // Enable the first LED |
mjr | 26:cb71c4af2912 | 137 | * tlc.set(0, 0xfff); |
mjr | 26:cb71c4af2912 | 138 | * |
mjr | 26:cb71c4af2912 | 139 | * while(1) |
mjr | 26:cb71c4af2912 | 140 | * { |
mjr | 26:cb71c4af2912 | 141 | * } |
mjr | 26:cb71c4af2912 | 142 | * } |
mjr | 26:cb71c4af2912 | 143 | * @endcode |
mjr | 26:cb71c4af2912 | 144 | */ |
mjr | 26:cb71c4af2912 | 145 | class TLC5940 |
mjr | 26:cb71c4af2912 | 146 | { |
mjr | 26:cb71c4af2912 | 147 | public: |
mjr | 26:cb71c4af2912 | 148 | /** |
mjr | 26:cb71c4af2912 | 149 | * Set up the TLC5940 |
mjr | 26:cb71c4af2912 | 150 | * @param SCLK - The SCK pin of the SPI bus |
mjr | 26:cb71c4af2912 | 151 | * @param MOSI - The MOSI pin of the SPI bus |
mjr | 26:cb71c4af2912 | 152 | * @param GSCLK - The GSCLK pin of the TLC5940(s) |
mjr | 26:cb71c4af2912 | 153 | * @param BLANK - The BLANK pin of the TLC5940(s) |
mjr | 26:cb71c4af2912 | 154 | * @param XLAT - The XLAT pin of the TLC5940(s) |
mjr | 26:cb71c4af2912 | 155 | * @param nchips - The number of TLC5940s (if you are daisy chaining) |
mjr | 26:cb71c4af2912 | 156 | */ |
mjr | 26:cb71c4af2912 | 157 | TLC5940(PinName SCLK, PinName MOSI, PinName GSCLK, PinName BLANK, PinName XLAT, int nchips) |
mjr | 47:df7a88cd249c | 158 | : sdma(DMAch_TLC5940), |
mjr | 47:df7a88cd249c | 159 | spi(MOSI, NC, SCLK), |
mjr | 26:cb71c4af2912 | 160 | gsclk(GSCLK), |
mjr | 26:cb71c4af2912 | 161 | blank(BLANK), |
mjr | 26:cb71c4af2912 | 162 | xlat(XLAT), |
mjr | 33:d832bcab089e | 163 | nchips(nchips) |
mjr | 26:cb71c4af2912 | 164 | { |
mjr | 40:cc0d9814522b | 165 | // start up initially disabled |
mjr | 40:cc0d9814522b | 166 | enabled = false; |
mjr | 40:cc0d9814522b | 167 | |
mjr | 33:d832bcab089e | 168 | // set XLAT to initially off |
mjr | 30:6e9902f06f48 | 169 | xlat = 0; |
mjr | 33:d832bcab089e | 170 | |
mjr | 33:d832bcab089e | 171 | // Assert BLANK while starting up, to keep the outputs turned off until |
mjr | 33:d832bcab089e | 172 | // everything is stable. This helps prevent spurious flashes during startup. |
mjr | 33:d832bcab089e | 173 | // (That's not particularly important for lights, but it matters more for |
mjr | 33:d832bcab089e | 174 | // tactile devices. It's a bit alarming to fire a replay knocker on every |
mjr | 33:d832bcab089e | 175 | // power-on, for example.) |
mjr | 30:6e9902f06f48 | 176 | blank = 1; |
mjr | 30:6e9902f06f48 | 177 | |
mjr | 26:cb71c4af2912 | 178 | // Configure SPI format and speed. Note that KL25Z ONLY supports 8-bit |
mjr | 26:cb71c4af2912 | 179 | // mode. The TLC5940 nominally requires 12-bit data blocks for the |
mjr | 26:cb71c4af2912 | 180 | // grayscale levels, but SPI is ultimately just a bit-level serial format, |
mjr | 26:cb71c4af2912 | 181 | // so we can reformat the 12-bit blocks into 8-bit bytes to fit the |
mjr | 26:cb71c4af2912 | 182 | // KL25Z's limits. This should work equally well on other microcontrollers |
mjr | 38:091e511ce8a0 | 183 | // that are more flexible. The TLC5940 requires polarity/phase format 0. |
mjr | 26:cb71c4af2912 | 184 | spi.format(8, 0); |
mjr | 26:cb71c4af2912 | 185 | spi.frequency(SPI_SPEED); |
mjr | 33:d832bcab089e | 186 | |
mjr | 33:d832bcab089e | 187 | // Send out a full data set to the chips, to clear out any random |
mjr | 33:d832bcab089e | 188 | // startup data from the registers. Include some extra bits - there |
mjr | 33:d832bcab089e | 189 | // are some cases (such as after sending dot correct commands) where |
mjr | 33:d832bcab089e | 190 | // an extra bit per chip is required, and the initial state is |
mjr | 33:d832bcab089e | 191 | // somewhat unpredictable, so send extra just to make sure we cover |
mjr | 33:d832bcab089e | 192 | // all bases. This does no harm; extra bits just fall off the end of |
mjr | 33:d832bcab089e | 193 | // the daisy chain, and since we want all registers set to 0, we can |
mjr | 33:d832bcab089e | 194 | // send arbitrarily many extra 0's. |
mjr | 33:d832bcab089e | 195 | for (int i = 0 ; i < nchips*25 ; ++i) |
mjr | 33:d832bcab089e | 196 | spi.write(0); |
mjr | 33:d832bcab089e | 197 | |
mjr | 33:d832bcab089e | 198 | // do an initial XLAT to latch all of these "0" values into the |
mjr | 33:d832bcab089e | 199 | // grayscale registers |
mjr | 33:d832bcab089e | 200 | xlat = 1; |
mjr | 33:d832bcab089e | 201 | xlat = 0; |
mjr | 29:582472d0bc57 | 202 | |
mjr | 39:b3815a1c3802 | 203 | // Allocate our DMA buffers. The transfer on each cycle is 192 bits per |
mjr | 40:cc0d9814522b | 204 | // chip = 24 bytes per chip. Allocate two buffers, so that we have a |
mjr | 40:cc0d9814522b | 205 | // stable buffer that we can send to the chips, and a separate working |
mjr | 40:cc0d9814522b | 206 | // copy that we can asynchronously update. |
mjr | 40:cc0d9814522b | 207 | dmalen = nchips*24; |
mjr | 48:058ace2aed1d | 208 | livebuf = new uint8_t[dmalen*2]; |
mjr | 48:058ace2aed1d | 209 | memset(livebuf, 0, dmalen*2); |
mjr | 40:cc0d9814522b | 210 | |
mjr | 40:cc0d9814522b | 211 | // start with buffer 0 live, with no new data pending |
mjr | 48:058ace2aed1d | 212 | workbuf = livebuf + dmalen; |
mjr | 40:cc0d9814522b | 213 | dirty = false; |
mjr | 40:cc0d9814522b | 214 | |
mjr | 30:6e9902f06f48 | 215 | // Set up the Simple DMA interface object. We use the DMA controller to |
mjr | 30:6e9902f06f48 | 216 | // send grayscale data updates to the TLC5940 chips. This lets the CPU |
mjr | 30:6e9902f06f48 | 217 | // keep running other tasks while we send gs updates, and importantly |
mjr | 30:6e9902f06f48 | 218 | // allows our blanking interrupt handler return almost immediately. |
mjr | 30:6e9902f06f48 | 219 | // The DMA transfer is from our internal DMA buffer to SPI0, which is |
mjr | 30:6e9902f06f48 | 220 | // the SPI controller physically connected to the TLC5940s. |
mjr | 40:cc0d9814522b | 221 | sdma.source(livebuf, true, 8); |
mjr | 48:058ace2aed1d | 222 | sdma.destination(&SPI0->D, false, 8); |
mjr | 30:6e9902f06f48 | 223 | sdma.trigger(Trigger_SPI0_TX); |
mjr | 30:6e9902f06f48 | 224 | sdma.attach(this, &TLC5940::dmaDone); |
mjr | 30:6e9902f06f48 | 225 | |
mjr | 30:6e9902f06f48 | 226 | // Configure the GSCLK output's frequency |
mjr | 26:cb71c4af2912 | 227 | gsclk.period(1.0/GSCLK_SPEED); |
mjr | 33:d832bcab089e | 228 | |
mjr | 33:d832bcab089e | 229 | // mark that we need an initial update |
mjr | 40:cc0d9814522b | 230 | dirty = true; |
mjr | 33:d832bcab089e | 231 | needXlat = false; |
mjr | 40:cc0d9814522b | 232 | } |
mjr | 40:cc0d9814522b | 233 | |
mjr | 40:cc0d9814522b | 234 | // Global enable/disble. When disabled, we assert the blanking signal |
mjr | 40:cc0d9814522b | 235 | // continuously to keep all outputs turned off. This can be used during |
mjr | 40:cc0d9814522b | 236 | // startup and sleep mode to prevent spurious output signals from |
mjr | 40:cc0d9814522b | 237 | // uninitialized grayscale registers. The chips have random values in |
mjr | 40:cc0d9814522b | 238 | // their internal registers when power is first applied, so we have to |
mjr | 40:cc0d9814522b | 239 | // explicitly send the initial zero levels after power cycling the chips. |
mjr | 40:cc0d9814522b | 240 | // The chips might not have power even when the KL25Z is running, because |
mjr | 40:cc0d9814522b | 241 | // they might be powered from a separate power supply from the KL25Z |
mjr | 40:cc0d9814522b | 242 | // (the Pinscape Expansion Boards work this way). Global blanking helps |
mjr | 40:cc0d9814522b | 243 | // us start up more cleanly by suppressing all outputs until we can be |
mjr | 40:cc0d9814522b | 244 | // reasonably sure that the various chip registers are initialized. |
mjr | 40:cc0d9814522b | 245 | void enable(bool f) |
mjr | 40:cc0d9814522b | 246 | { |
mjr | 40:cc0d9814522b | 247 | // note the new setting |
mjr | 40:cc0d9814522b | 248 | enabled = f; |
mjr | 40:cc0d9814522b | 249 | |
mjr | 40:cc0d9814522b | 250 | // if disabled, apply blanking immediately |
mjr | 40:cc0d9814522b | 251 | if (!f) |
mjr | 40:cc0d9814522b | 252 | { |
mjr | 40:cc0d9814522b | 253 | gsclk.write(0); |
mjr | 40:cc0d9814522b | 254 | blank = 1; |
mjr | 40:cc0d9814522b | 255 | } |
mjr | 40:cc0d9814522b | 256 | |
mjr | 40:cc0d9814522b | 257 | // do a full update with the new setting |
mjr | 40:cc0d9814522b | 258 | dirty = true; |
mjr | 40:cc0d9814522b | 259 | } |
mjr | 29:582472d0bc57 | 260 | |
mjr | 30:6e9902f06f48 | 261 | // Start the clock running |
mjr | 29:582472d0bc57 | 262 | void start() |
mjr | 29:582472d0bc57 | 263 | { |
mjr | 26:cb71c4af2912 | 264 | // Set up the first call to the reset function, which asserts BLANK to |
mjr | 26:cb71c4af2912 | 265 | // end the PWM cycle and handles new grayscale data output and latching. |
mjr | 26:cb71c4af2912 | 266 | // The original version of this library uses a timer to call reset |
mjr | 26:cb71c4af2912 | 267 | // periodically, but that approach is somewhat problematic because the |
mjr | 26:cb71c4af2912 | 268 | // reset function itself takes a small amount of time to run, so the |
mjr | 26:cb71c4af2912 | 269 | // *actual* cycle is slightly longer than what we get from counting |
mjr | 26:cb71c4af2912 | 270 | // GS clocks. Running reset on a timer therefore causes the calls to |
mjr | 26:cb71c4af2912 | 271 | // slip out of phase with the actual full cycles, which causes |
mjr | 26:cb71c4af2912 | 272 | // premature blanking that shows up as visible flicker. To get the |
mjr | 26:cb71c4af2912 | 273 | // reset cycle to line up exactly with a full PWM cycle, it works |
mjr | 26:cb71c4af2912 | 274 | // better to set up a new timer on each cycle, *after* we've finished |
mjr | 26:cb71c4af2912 | 275 | // with the somewhat unpredictable overhead of the interrupt handler. |
mjr | 48:058ace2aed1d | 276 | // This seems to get us close enough to exact alignment with the cycle |
mjr | 48:058ace2aed1d | 277 | // phase to eliminate visible artifacts. |
mjr | 38:091e511ce8a0 | 278 | resetTimer.attach(this, &TLC5940::reset, (1.0/GSCLK_SPEED)*4096.0); |
mjr | 26:cb71c4af2912 | 279 | } |
mjr | 26:cb71c4af2912 | 280 | |
mjr | 39:b3815a1c3802 | 281 | /* |
mjr | 39:b3815a1c3802 | 282 | * Set an output |
mjr | 26:cb71c4af2912 | 283 | */ |
mjr | 26:cb71c4af2912 | 284 | void set(int idx, unsigned short data) |
mjr | 26:cb71c4af2912 | 285 | { |
mjr | 39:b3815a1c3802 | 286 | // validate the index |
mjr | 39:b3815a1c3802 | 287 | if (idx >= 0 && idx < nchips*16) |
mjr | 39:b3815a1c3802 | 288 | { |
mjr | 40:cc0d9814522b | 289 | // this is a critical section, since we're updating a static buffer and |
mjr | 40:cc0d9814522b | 290 | // can call this routine from application context or interrupt context |
mjr | 40:cc0d9814522b | 291 | __disable_irq(); |
mjr | 40:cc0d9814522b | 292 | |
mjr | 40:cc0d9814522b | 293 | // If the buffer isn't dirty, it means that the previous working buffer |
mjr | 40:cc0d9814522b | 294 | // was swapped into the live buffer on the last blanking interval. This |
mjr | 40:cc0d9814522b | 295 | // means that the working buffer hasn't been updated to the live data yet, |
mjr | 40:cc0d9814522b | 296 | // so we need to copy it now. |
mjr | 40:cc0d9814522b | 297 | if (!dirty) |
mjr | 40:cc0d9814522b | 298 | { |
mjr | 40:cc0d9814522b | 299 | memcpy(workbuf, livebuf, dmalen); |
mjr | 40:cc0d9814522b | 300 | dirty = true; |
mjr | 40:cc0d9814522b | 301 | } |
mjr | 40:cc0d9814522b | 302 | |
mjr | 39:b3815a1c3802 | 303 | // Figure the DMA buffer location of the data. The DMA buffer has the |
mjr | 39:b3815a1c3802 | 304 | // packed bit format that we send across the wire, with 12 bits per output, |
mjr | 39:b3815a1c3802 | 305 | // arranged from last output to first output (N = number of outputs = nchips*16): |
mjr | 39:b3815a1c3802 | 306 | // |
mjr | 39:b3815a1c3802 | 307 | // byte 0 = high 8 bits of output N-1 |
mjr | 39:b3815a1c3802 | 308 | // 1 = low 4 bits of output N-1 | high 4 bits of output N-2 |
mjr | 39:b3815a1c3802 | 309 | // 2 = low 8 bits of N-2 |
mjr | 39:b3815a1c3802 | 310 | // 3 = high 8 bits of N-3 |
mjr | 39:b3815a1c3802 | 311 | // 4 = low 4 bits of N-3 | high 4 bits of N-2 |
mjr | 39:b3815a1c3802 | 312 | // 5 = low 8bits of N-4 |
mjr | 39:b3815a1c3802 | 313 | // ... |
mjr | 39:b3815a1c3802 | 314 | // 24*nchips-3 = high 8 bits of output 1 |
mjr | 39:b3815a1c3802 | 315 | // 24*nchips-2 = low 4 bits of output 1 | high 4 bits of output 0 |
mjr | 39:b3815a1c3802 | 316 | // 24*nchips-1 = low 8 bits of output 0 |
mjr | 39:b3815a1c3802 | 317 | // |
mjr | 39:b3815a1c3802 | 318 | // So this update will affect two bytes. If the output number if even, we're |
mjr | 39:b3815a1c3802 | 319 | // in the high 4 + low 8 pair; if odd, we're in the high 8 + low 4 pair. |
mjr | 39:b3815a1c3802 | 320 | int di = nchips*24 - 3 - (3*(idx/2)); |
mjr | 39:b3815a1c3802 | 321 | if (idx & 1) |
mjr | 39:b3815a1c3802 | 322 | { |
mjr | 39:b3815a1c3802 | 323 | // ODD = high 8 | low 4 |
mjr | 40:cc0d9814522b | 324 | workbuf[di] = uint8_t((data >> 4) & 0xff); |
mjr | 40:cc0d9814522b | 325 | workbuf[di+1] &= 0x0F; |
mjr | 40:cc0d9814522b | 326 | workbuf[di+1] |= uint8_t((data << 4) & 0xf0); |
mjr | 39:b3815a1c3802 | 327 | } |
mjr | 39:b3815a1c3802 | 328 | else |
mjr | 39:b3815a1c3802 | 329 | { |
mjr | 39:b3815a1c3802 | 330 | // EVEN = high 4 | low 8 |
mjr | 40:cc0d9814522b | 331 | workbuf[di+1] &= 0xF0; |
mjr | 40:cc0d9814522b | 332 | workbuf[di+1] |= uint8_t((data >> 8) & 0x0f); |
mjr | 40:cc0d9814522b | 333 | workbuf[di+2] = uint8_t(data & 0xff); |
mjr | 39:b3815a1c3802 | 334 | } |
mjr | 39:b3815a1c3802 | 335 | |
mjr | 40:cc0d9814522b | 336 | // end the critical section |
mjr | 40:cc0d9814522b | 337 | __enable_irq(); |
mjr | 39:b3815a1c3802 | 338 | } |
mjr | 26:cb71c4af2912 | 339 | } |
mjr | 40:cc0d9814522b | 340 | |
mjr | 40:cc0d9814522b | 341 | // Update the outputs. We automatically update the outputs on the grayscale timer |
mjr | 40:cc0d9814522b | 342 | // when we have pending changes, so it's not necessary to call this explicitly after |
mjr | 40:cc0d9814522b | 343 | // making a change via set(). This can be called to force an update when the chips |
mjr | 40:cc0d9814522b | 344 | // might be out of sync with our internal state, such as after power-on. |
mjr | 40:cc0d9814522b | 345 | void update(bool force = false) |
mjr | 40:cc0d9814522b | 346 | { |
mjr | 40:cc0d9814522b | 347 | if (force) |
mjr | 40:cc0d9814522b | 348 | dirty = true; |
mjr | 40:cc0d9814522b | 349 | } |
mjr | 26:cb71c4af2912 | 350 | |
mjr | 26:cb71c4af2912 | 351 | private: |
mjr | 26:cb71c4af2912 | 352 | // current level for each output |
mjr | 26:cb71c4af2912 | 353 | unsigned short *gs; |
mjr | 26:cb71c4af2912 | 354 | |
mjr | 30:6e9902f06f48 | 355 | // Simple DMA interface object |
mjr | 30:6e9902f06f48 | 356 | SimpleDMA sdma; |
mjr | 30:6e9902f06f48 | 357 | |
mjr | 40:cc0d9814522b | 358 | // DMA transfer buffers - double buffer. Each time we have data to transmit to the |
mjr | 40:cc0d9814522b | 359 | // TLC5940 chips, we format the data into the working half of this buffer exactly as |
mjr | 40:cc0d9814522b | 360 | // it will go across the wire, then hand the buffer to the DMA controller to move |
mjr | 40:cc0d9814522b | 361 | // through the SPI port. This memory block is actually two buffers, one live and |
mjr | 40:cc0d9814522b | 362 | // one pending. When we're ready to send updates to the chips, we swap the working |
mjr | 40:cc0d9814522b | 363 | // buffer into the live buffer so that we can send the latest updates. We keep a |
mjr | 40:cc0d9814522b | 364 | // separate working copy so that our live copy is stable, so that we don't alter |
mjr | 40:cc0d9814522b | 365 | // any data in the midst of an asynchronous DMA transmission to the chips. |
mjr | 48:058ace2aed1d | 366 | uint8_t *volatile livebuf; |
mjr | 48:058ace2aed1d | 367 | uint8_t *volatile workbuf; |
mjr | 40:cc0d9814522b | 368 | |
mjr | 40:cc0d9814522b | 369 | // length of each DMA buffer, in bytes - 12 bits = 1.5 bytes per output, 16 outputs |
mjr | 40:cc0d9814522b | 370 | // per chip -> 24 bytes per chip |
mjr | 40:cc0d9814522b | 371 | uint16_t dmalen; |
mjr | 40:cc0d9814522b | 372 | |
mjr | 40:cc0d9814522b | 373 | // Dirty: true means that the non-live buffer has new pending data. False means |
mjr | 40:cc0d9814522b | 374 | // that the non-live buffer is empty. |
mjr | 40:cc0d9814522b | 375 | bool dirty; |
mjr | 40:cc0d9814522b | 376 | |
mjr | 40:cc0d9814522b | 377 | // Enabled: this enables or disables all outputs. When this is true, we assert the |
mjr | 40:cc0d9814522b | 378 | // BLANK signal continuously. |
mjr | 40:cc0d9814522b | 379 | bool enabled; |
mjr | 30:6e9902f06f48 | 380 | |
mjr | 26:cb71c4af2912 | 381 | // SPI port - only MOSI and SCK are used |
mjr | 26:cb71c4af2912 | 382 | SPI spi; |
mjr | 26:cb71c4af2912 | 383 | |
mjr | 26:cb71c4af2912 | 384 | // use a PWM out for the grayscale clock - this provides a stable |
mjr | 26:cb71c4af2912 | 385 | // square wave signal without consuming CPU |
mjr | 48:058ace2aed1d | 386 | PwmOut gsclk; |
mjr | 26:cb71c4af2912 | 387 | |
mjr | 26:cb71c4af2912 | 388 | // Digital out pins used for the TLC5940 |
mjr | 26:cb71c4af2912 | 389 | DigitalOut blank; |
mjr | 26:cb71c4af2912 | 390 | DigitalOut xlat; |
mjr | 26:cb71c4af2912 | 391 | |
mjr | 26:cb71c4af2912 | 392 | // number of daisy-chained TLC5940s we're controlling |
mjr | 26:cb71c4af2912 | 393 | int nchips; |
mjr | 26:cb71c4af2912 | 394 | |
mjr | 26:cb71c4af2912 | 395 | // Timeout to end each PWM cycle. This is a one-shot timer that we reset |
mjr | 26:cb71c4af2912 | 396 | // on each cycle. |
mjr | 38:091e511ce8a0 | 397 | Timeout resetTimer; |
mjr | 26:cb71c4af2912 | 398 | |
mjr | 33:d832bcab089e | 399 | // Do we need an XLAT signal on the next blanking interval? |
mjr | 33:d832bcab089e | 400 | volatile bool needXlat; |
mjr | 40:cc0d9814522b | 401 | volatile bool newGSData;//$$$ |
mjr | 26:cb71c4af2912 | 402 | |
mjr | 40:cc0d9814522b | 403 | // Reset the grayscale cycle and send the next data update |
mjr | 26:cb71c4af2912 | 404 | void reset() |
mjr | 26:cb71c4af2912 | 405 | { |
mjr | 30:6e9902f06f48 | 406 | // start the blanking cycle |
mjr | 30:6e9902f06f48 | 407 | startBlank(); |
mjr | 33:d832bcab089e | 408 | |
mjr | 40:cc0d9814522b | 409 | // if we have pending grayscale data, update the DMA data |
mjr | 40:cc0d9814522b | 410 | /*$$$bool*/ newGSData = false; |
mjr | 48:058ace2aed1d | 411 | uint8_t *dmasrc; |
mjr | 40:cc0d9814522b | 412 | if (dirty) |
mjr | 40:cc0d9814522b | 413 | { |
mjr | 40:cc0d9814522b | 414 | // swap live and working buffers |
mjr | 40:cc0d9814522b | 415 | uint8_t *tmp = livebuf; |
mjr | 40:cc0d9814522b | 416 | livebuf = workbuf; |
mjr | 40:cc0d9814522b | 417 | workbuf = tmp; |
mjr | 40:cc0d9814522b | 418 | |
mjr | 48:058ace2aed1d | 419 | // Set the new DMA source. Set the starting address in the |
mjr | 48:058ace2aed1d | 420 | // DMA controller to the *second* byte, since we have to send |
mjr | 48:058ace2aed1d | 421 | // the first byte via the CPU instead of DMA - this is required |
mjr | 48:058ace2aed1d | 422 | // because of a problematic interaction that occurs if the DMA |
mjr | 48:058ace2aed1d | 423 | // controller initiates the transfer; the problem is outlined |
mjr | 48:058ace2aed1d | 424 | // in the KL25Z hardware reference manual. |
mjr | 48:058ace2aed1d | 425 | dmasrc = livebuf; |
mjr | 48:058ace2aed1d | 426 | sdma.source(livebuf + 1, true, 8); |
mjr | 40:cc0d9814522b | 427 | |
mjr | 40:cc0d9814522b | 428 | // no longer dirty |
mjr | 40:cc0d9814522b | 429 | dirty = false; |
mjr | 40:cc0d9814522b | 430 | |
mjr | 40:cc0d9814522b | 431 | // note the new data |
mjr | 40:cc0d9814522b | 432 | newGSData = true; |
mjr | 40:cc0d9814522b | 433 | } |
mjr | 48:058ace2aed1d | 434 | else //$$$ |
mjr | 48:058ace2aed1d | 435 | { |
mjr | 48:058ace2aed1d | 436 | // send all 1 bits for diagnostics - in case of XLAT |
mjr | 48:058ace2aed1d | 437 | // glitches, this turns all outputs on, which makes the |
mjr | 48:058ace2aed1d | 438 | // glitch immediately apparent |
mjr | 48:058ace2aed1d | 439 | static uint8_t dummy = 0xff; |
mjr | 48:058ace2aed1d | 440 | dmasrc = &dummy; |
mjr | 48:058ace2aed1d | 441 | sdma.source(&dummy, false, 8); |
mjr | 48:058ace2aed1d | 442 | } //$$$ |
mjr | 48:058ace2aed1d | 443 | |
mjr | 48:058ace2aed1d | 444 | #ifndef DATA_UPDATE_INSIDE_BLANKING |
mjr | 48:058ace2aed1d | 445 | // We're configured to send new GS data during the GS cycle, |
mjr | 48:058ace2aed1d | 446 | // not during the blanking interval, so end the blanking |
mjr | 48:058ace2aed1d | 447 | // interval now, before we start sending the new data. Ending |
mjr | 48:058ace2aed1d | 448 | // the blanking interval starts the new GS cycle. |
mjr | 33:d832bcab089e | 449 | // |
mjr | 48:058ace2aed1d | 450 | // (For the other configuration, we send GS data during the |
mjr | 48:058ace2aed1d | 451 | // blanking interval, so in that case we DON'T end the blanking |
mjr | 48:058ace2aed1d | 452 | // interval yet - we defer that until the end-of-DMA interrupt |
mjr | 48:058ace2aed1d | 453 | // handler, which fires after the GS data send has completed.) |
mjr | 33:d832bcab089e | 454 | endBlank(); |
mjr | 48:058ace2aed1d | 455 | #endif |
mjr | 48:058ace2aed1d | 456 | |
mjr | 40:cc0d9814522b | 457 | // send out the DMA contents if we have new data |
mjr | 48:058ace2aed1d | 458 | //$$$if (newGSData) |
mjr | 48:058ace2aed1d | 459 | { |
mjr | 48:058ace2aed1d | 460 | // The hardware reference manual says that the CPU has to send |
mjr | 48:058ace2aed1d | 461 | // the first byte of a DMA transfer explicitly. This is required |
mjr | 48:058ace2aed1d | 462 | // to avoid a hardware deadlock condition that happens due to |
mjr | 48:058ace2aed1d | 463 | // a timing interaction between the SPI and DMA controllers. |
mjr | 48:058ace2aed1d | 464 | // The correct sequence per the manual is: |
mjr | 48:058ace2aed1d | 465 | // |
mjr | 48:058ace2aed1d | 466 | // - set up the DMA registers, starting at the 2nd byte to send |
mjr | 48:058ace2aed1d | 467 | // - write the first byte directly to the SPI data register |
mjr | 48:058ace2aed1d | 468 | // - enable TXDMAE in the SPI controller |
mjr | 48:058ace2aed1d | 469 | sdma.start(dmalen - 1); |
mjr | 48:058ace2aed1d | 470 | spi.write(dmasrc[0]); |
mjr | 48:058ace2aed1d | 471 | SPI0->C2 |= SPI_C2_TXDMAE_MASK; |
mjr | 48:058ace2aed1d | 472 | } |
mjr | 30:6e9902f06f48 | 473 | } |
mjr | 30:6e9902f06f48 | 474 | |
mjr | 30:6e9902f06f48 | 475 | void startBlank() |
mjr | 30:6e9902f06f48 | 476 | { |
mjr | 30:6e9902f06f48 | 477 | // turn off the grayscale clock, and assert BLANK to end the grayscale cycle |
mjr | 30:6e9902f06f48 | 478 | gsclk.write(0); |
mjr | 40:cc0d9814522b | 479 | blank = 0; // for a slight delay - chip requires 20ns GSCLK up to BLANK up |
mjr | 30:6e9902f06f48 | 480 | blank = 1; |
mjr | 30:6e9902f06f48 | 481 | } |
mjr | 26:cb71c4af2912 | 482 | |
mjr | 33:d832bcab089e | 483 | void endBlank() |
mjr | 30:6e9902f06f48 | 484 | { |
mjr | 33:d832bcab089e | 485 | // if we've sent new grayscale data since the last blanking |
mjr | 33:d832bcab089e | 486 | // interval, latch it by asserting XLAT |
mjr | 33:d832bcab089e | 487 | if (needXlat) |
mjr | 30:6e9902f06f48 | 488 | { |
mjr | 26:cb71c4af2912 | 489 | // latch the new data while we're still blanked |
mjr | 26:cb71c4af2912 | 490 | xlat = 1; |
mjr | 26:cb71c4af2912 | 491 | xlat = 0; |
mjr | 33:d832bcab089e | 492 | needXlat = false; |
mjr | 26:cb71c4af2912 | 493 | } |
mjr | 26:cb71c4af2912 | 494 | |
mjr | 40:cc0d9814522b | 495 | // End the blanking interval and restart the grayscale clock. Note |
mjr | 40:cc0d9814522b | 496 | // that we keep the blanking on if the chips are globally disabled. |
mjr | 40:cc0d9814522b | 497 | blank = enabled ? 0 : 1; |
mjr | 26:cb71c4af2912 | 498 | gsclk.write(.5); |
mjr | 26:cb71c4af2912 | 499 | |
mjr | 26:cb71c4af2912 | 500 | // set up the next blanking interrupt |
mjr | 38:091e511ce8a0 | 501 | resetTimer.attach(this, &TLC5940::reset, (1.0/GSCLK_SPEED)*4096.0); |
mjr | 26:cb71c4af2912 | 502 | } |
mjr | 26:cb71c4af2912 | 503 | |
mjr | 30:6e9902f06f48 | 504 | // Interrupt handler for DMA completion. The DMA controller calls this |
mjr | 30:6e9902f06f48 | 505 | // when it finishes with the transfer request we set up above. When the |
mjr | 30:6e9902f06f48 | 506 | // transfer is done, we simply end the blanking cycle and start a new |
mjr | 30:6e9902f06f48 | 507 | // grayscale cycle. |
mjr | 30:6e9902f06f48 | 508 | void dmaDone() |
mjr | 30:6e9902f06f48 | 509 | { |
mjr | 48:058ace2aed1d | 510 | // disable DMA triggering in the SPI controller until we set |
mjr | 48:058ace2aed1d | 511 | // up the next transfer |
mjr | 48:058ace2aed1d | 512 | SPI0->C2 &= ~SPI_C2_TXDMAE_MASK; |
mjr | 48:058ace2aed1d | 513 | |
mjr | 33:d832bcab089e | 514 | // mark that we need to assert XLAT to latch the new |
mjr | 33:d832bcab089e | 515 | // grayscale data during the next blanking interval |
mjr | 40:cc0d9814522b | 516 | needXlat = newGSData;//$$$ true; |
mjr | 33:d832bcab089e | 517 | |
mjr | 33:d832bcab089e | 518 | #if DATA_UPDATE_INSIDE_BLANKING |
mjr | 33:d832bcab089e | 519 | // we're doing the gs update within the blanking cycle, so end |
mjr | 33:d832bcab089e | 520 | // the blanking cycle now that the transfer has completed |
mjr | 33:d832bcab089e | 521 | endBlank(); |
mjr | 33:d832bcab089e | 522 | #endif |
mjr | 30:6e9902f06f48 | 523 | } |
mjr | 30:6e9902f06f48 | 524 | |
mjr | 26:cb71c4af2912 | 525 | }; |
mjr | 26:cb71c4af2912 | 526 | |
mjr | 26:cb71c4af2912 | 527 | #endif |