Mike R / Mbed 2 deprecated Pinscape_Controller_v1

Pinscape Controller version 1 fork. This is a fork to allow for ongoing bug fixes to the original controller version, from before the major changes for the expansion board project.

Dependencies:   FastIO FastPWM SimpleDMA mbed

Fork of Pinscape_Controller by Mike R

TLC5940/TLC5940.h@28:2097c6f8f2db, 2015-09-23 (annotated)

Committer:
mjr
Date:
Wed Sep 23 05:38:27 2015 +0000
Revision:
28:2097c6f8f2db
Parent:
26:cb71c4af2912
Child:
29:582472d0bc57
A few more tweaks in the TLC5940 setup.

Who changed what in which revision?

UserRevisionLine numberNew 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 26:cb71c4af2912 23 #include "mbed.h"
mjr 26:cb71c4af2912 24 #include "FastPWM.h"
mjr 26:cb71c4af2912 25
mjr 26:cb71c4af2912 26 /**
mjr 26:cb71c4af2912 27 * SPI speed used by the mbed to communicate with the TLC5940
mjr 26:cb71c4af2912 28 * The TLC5940 supports up to 30Mhz. It's best to keep this as
mjr 26:cb71c4af2912 29 * high as the microcontroller will allow, since a higher SPI
mjr 26:cb71c4af2912 30 * speed yields a faster grayscale data update. However, if
mjr 26:cb71c4af2912 31 * you have problems with unreliable signal transmission to the
mjr 26:cb71c4af2912 32 * TLC5940s, reducing this speed might help.
mjr 26:cb71c4af2912 33 *
mjr 26:cb71c4af2912 34 * The SPI clock must be fast enough that the data transmission
mjr 26:cb71c4af2912 35 * time for a full update is comfortably less than the blanking
mjr 26:cb71c4af2912 36 * cycle time. The grayscale refresh requires 192 bits per TLC5940
mjr 26:cb71c4af2912 37 * in the daisy chain, and each bit takes one SPI clock to send.
mjr 26:cb71c4af2912 38 * Our reference setup in the Pinscape controller allows for up to
mjr 26:cb71c4af2912 39 * 4 TLC5940s, so a full refresh cycle on a fully populated system
mjr 26:cb71c4af2912 40 * would be 768 SPI clocks. The blanking cycle is 4096 GSCLK cycles.
mjr 26:cb71c4af2912 41 *
mjr 26:cb71c4af2912 42 * t(blank) = 4096 * 1/GSCLK_SPEED
mjr 26:cb71c4af2912 43 * t(refresh) = 768 * 1/SPI_SPEED
mjr 26:cb71c4af2912 44 * Therefore: SPI_SPEED must be > 768/4096 * GSCLK_SPEED
mjr 26:cb71c4af2912 45 *
mjr 26:cb71c4af2912 46 * Since the SPI speed can be so high, and since we want to keep
mjr 26:cb71c4af2912 47 * the GSCLK speed relatively low, the constraint above simply
mjr 26:cb71c4af2912 48 * isn't a factor. E.g., at SPI=30MHz and GSCLK=500kHz,
mjr 26:cb71c4af2912 49 * t(blank) is 8192us and t(refresh) is 25us.
mjr 26:cb71c4af2912 50 */
mjr 26:cb71c4af2912 51 #define SPI_SPEED 3000000
mjr 26:cb71c4af2912 52
mjr 26:cb71c4af2912 53 /**
mjr 26:cb71c4af2912 54 * The rate at which the GSCLK pin is pulsed. This also controls
mjr 26:cb71c4af2912 55 * how often the reset function is called. The reset function call
mjr 26:cb71c4af2912 56 * rate is (1/GSCLK_SPEED) * 4096. The maximum reliable rate is
mjr 26:cb71c4af2912 57 * around 32Mhz. It's best to keep this rate as low as possible:
mjr 26:cb71c4af2912 58 * the higher the rate, the higher the refresh() call frequency,
mjr 26:cb71c4af2912 59 * so the higher the CPU load.
mjr 26:cb71c4af2912 60 *
mjr 26:cb71c4af2912 61 * The lower bound is probably dependent on the application. For
mjr 26:cb71c4af2912 62 * driving LEDs, the limiting factor is that lower rates will increase
mjr 26:cb71c4af2912 63 * visible flicker. 200 kHz seems to be a good lower bound for LEDs.
mjr 26:cb71c4af2912 64 * That provides about 48 cycles per second - that's about the same as
mjr 26:cb71c4af2912 65 * the 50 Hz A/C cycle rate in many countries, which was itself chosen
mjr 26:cb71c4af2912 66 * so that incandescent lights don't flicker. (This rate is a function
mjr 26:cb71c4af2912 67 * of human eye physiology, which has its own refresh cycle of sorts
mjr 26:cb71c4af2912 68 * that runs at about 50 Hz. If you're designing an LED system for
mjr 26:cb71c4af2912 69 * viewing by cats or drosophila, you might want to look into your
mjr 26:cb71c4af2912 70 * target species' eye physiology, since the persistence of vision
mjr 26:cb71c4af2912 71 * rate varies quite a bit from species to species.) Flicker tends to
mjr 26:cb71c4af2912 72 * be more noticeable in LEDs than in incandescents, since LEDs don't
mjr 26:cb71c4af2912 73 * have the thermal inertia of incandescents, so we use a slightly
mjr 26:cb71c4af2912 74 * higher default here. 500 kHz = 122 full grayscale cycles per
mjr 26:cb71c4af2912 75 * second = 122 reset calls per second (call every 8ms).
mjr 26:cb71c4af2912 76 */
mjr 26:cb71c4af2912 77 #define GSCLK_SPEED 500000
mjr 26:cb71c4af2912 78
mjr 26:cb71c4af2912 79 /**
mjr 26:cb71c4af2912 80 * This class controls a TLC5940 PWM driver IC.
mjr 26:cb71c4af2912 81 *
mjr 26:cb71c4af2912 82 * Using the TLC5940 class to control an LED:
mjr 26:cb71c4af2912 83 * @code
mjr 26:cb71c4af2912 84 * #include "mbed.h"
mjr 26:cb71c4af2912 85 * #include "TLC5940.h"
mjr 26:cb71c4af2912 86 *
mjr 26:cb71c4af2912 87 * // Create the TLC5940 instance
mjr 26:cb71c4af2912 88 * TLC5940 tlc(p7, p5, p21, p9, p10, p11, p12, 1);
mjr 26:cb71c4af2912 89 *
mjr 26:cb71c4af2912 90 * int main()
mjr 26:cb71c4af2912 91 * {
mjr 26:cb71c4af2912 92 * // Enable the first LED
mjr 26:cb71c4af2912 93 * tlc.set(0, 0xfff);
mjr 26:cb71c4af2912 94 *
mjr 26:cb71c4af2912 95 * while(1)
mjr 26:cb71c4af2912 96 * {
mjr 26:cb71c4af2912 97 * }
mjr 26:cb71c4af2912 98 * }
mjr 26:cb71c4af2912 99 * @endcode
mjr 26:cb71c4af2912 100 */
mjr 26:cb71c4af2912 101 class TLC5940
mjr 26:cb71c4af2912 102 {
mjr 26:cb71c4af2912 103 public:
mjr 26:cb71c4af2912 104 /**
mjr 26:cb71c4af2912 105 * Set up the TLC5940
mjr 26:cb71c4af2912 106 * @param SCLK - The SCK pin of the SPI bus
mjr 26:cb71c4af2912 107 * @param MOSI - The MOSI pin of the SPI bus
mjr 26:cb71c4af2912 108 * @param GSCLK - The GSCLK pin of the TLC5940(s)
mjr 26:cb71c4af2912 109 * @param BLANK - The BLANK pin of the TLC5940(s)
mjr 26:cb71c4af2912 110 * @param XLAT - The XLAT pin of the TLC5940(s)
mjr 26:cb71c4af2912 111 * @param nchips - The number of TLC5940s (if you are daisy chaining)
mjr 26:cb71c4af2912 112 */
mjr 26:cb71c4af2912 113 TLC5940(PinName SCLK, PinName MOSI, PinName GSCLK, PinName BLANK, PinName XLAT, int nchips)
mjr 26:cb71c4af2912 114 : spi(MOSI, NC, SCLK),
mjr 26:cb71c4af2912 115 gsclk(GSCLK),
mjr 26:cb71c4af2912 116 blank(BLANK),
mjr 26:cb71c4af2912 117 xlat(XLAT),
mjr 26:cb71c4af2912 118 nchips(nchips),
mjr 28:2097c6f8f2db 119 newGSData(true)
mjr 26:cb71c4af2912 120 {
mjr 26:cb71c4af2912 121 // allocate the grayscale buffer
mjr 26:cb71c4af2912 122 gs = new unsigned short[nchips*16];
mjr 28:2097c6f8f2db 123 memset(gs, 0, nchips*16*sizeof(gs[0]));
mjr 26:cb71c4af2912 124
mjr 26:cb71c4af2912 125 // Configure SPI format and speed. Note that KL25Z ONLY supports 8-bit
mjr 26:cb71c4af2912 126 // mode. The TLC5940 nominally requires 12-bit data blocks for the
mjr 26:cb71c4af2912 127 // grayscale levels, but SPI is ultimately just a bit-level serial format,
mjr 26:cb71c4af2912 128 // so we can reformat the 12-bit blocks into 8-bit bytes to fit the
mjr 26:cb71c4af2912 129 // KL25Z's limits. This should work equally well on other microcontrollers
mjr 26:cb71c4af2912 130 // that are more flexible. The TLC5940 appears to require polarity/phase
mjr 26:cb71c4af2912 131 // format 0.
mjr 26:cb71c4af2912 132 spi.format(8, 0);
mjr 26:cb71c4af2912 133 spi.frequency(SPI_SPEED);
mjr 26:cb71c4af2912 134
mjr 26:cb71c4af2912 135 // Set output pin states
mjr 26:cb71c4af2912 136 xlat = 0;
mjr 26:cb71c4af2912 137 blank = 1;
mjr 26:cb71c4af2912 138
mjr 26:cb71c4af2912 139 // Configure PWM output for GSCLK frequency at 50% duty cycle
mjr 26:cb71c4af2912 140 gsclk.period(1.0/GSCLK_SPEED);
mjr 26:cb71c4af2912 141 gsclk.write(.5);
mjr 26:cb71c4af2912 142 blank = 0;
mjr 28:2097c6f8f2db 143
mjr 26:cb71c4af2912 144 // Set up the first call to the reset function, which asserts BLANK to
mjr 26:cb71c4af2912 145 // end the PWM cycle and handles new grayscale data output and latching.
mjr 26:cb71c4af2912 146 // The original version of this library uses a timer to call reset
mjr 26:cb71c4af2912 147 // periodically, but that approach is somewhat problematic because the
mjr 26:cb71c4af2912 148 // reset function itself takes a small amount of time to run, so the
mjr 26:cb71c4af2912 149 // *actual* cycle is slightly longer than what we get from counting
mjr 26:cb71c4af2912 150 // GS clocks. Running reset on a timer therefore causes the calls to
mjr 26:cb71c4af2912 151 // slip out of phase with the actual full cycles, which causes
mjr 26:cb71c4af2912 152 // premature blanking that shows up as visible flicker. To get the
mjr 26:cb71c4af2912 153 // reset cycle to line up exactly with a full PWM cycle, it works
mjr 26:cb71c4af2912 154 // better to set up a new timer on each cycle, *after* we've finished
mjr 26:cb71c4af2912 155 // with the somewhat unpredictable overhead of the interrupt handler.
mjr 26:cb71c4af2912 156 // This ensures that we'll get much closer to exact alignment of the
mjr 26:cb71c4af2912 157 // cycle phase, and in any case the worst that happens is that some
mjr 26:cb71c4af2912 158 // cycles are very slightly too long or short (due to imperfections
mjr 26:cb71c4af2912 159 // in the timer clock vs the PWM clock that determines the GSCLCK
mjr 26:cb71c4af2912 160 // output to the TLC5940), which is far less noticeable than a
mjr 26:cb71c4af2912 161 // constantly rotating phase misalignment.
mjr 26:cb71c4af2912 162 reset_timer.attach(this, &TLC5940::reset, (1.0/GSCLK_SPEED)*4096.0);
mjr 26:cb71c4af2912 163 }
mjr 26:cb71c4af2912 164
mjr 26:cb71c4af2912 165 ~TLC5940()
mjr 26:cb71c4af2912 166 {
mjr 26:cb71c4af2912 167 delete [] gs;
mjr 26:cb71c4af2912 168 }
mjr 26:cb71c4af2912 169
mjr 26:cb71c4af2912 170 /**
mjr 26:cb71c4af2912 171 * Set the next chunk of grayscale data to be sent
mjr 26:cb71c4af2912 172 * @param data - Array of 16 bit shorts containing 16 12 bit grayscale data chunks per TLC5940
mjr 26:cb71c4af2912 173 * @note These must be in intervals of at least (1/GSCLK_SPEED) * 4096 to be sent
mjr 26:cb71c4af2912 174 */
mjr 26:cb71c4af2912 175 void set(int idx, unsigned short data)
mjr 26:cb71c4af2912 176 {
mjr 26:cb71c4af2912 177 // store the data, and flag the pending update for the interrupt handler to carry out
mjr 26:cb71c4af2912 178 gs[idx] = data;
mjr 26:cb71c4af2912 179 newGSData = true;
mjr 26:cb71c4af2912 180 }
mjr 26:cb71c4af2912 181
mjr 26:cb71c4af2912 182 private:
mjr 26:cb71c4af2912 183 // current level for each output
mjr 26:cb71c4af2912 184 unsigned short *gs;
mjr 26:cb71c4af2912 185
mjr 26:cb71c4af2912 186 // SPI port - only MOSI and SCK are used
mjr 26:cb71c4af2912 187 SPI spi;
mjr 26:cb71c4af2912 188
mjr 26:cb71c4af2912 189 // use a PWM out for the grayscale clock - this provides a stable
mjr 26:cb71c4af2912 190 // square wave signal without consuming CPU
mjr 26:cb71c4af2912 191 FastPWM gsclk;
mjr 26:cb71c4af2912 192
mjr 26:cb71c4af2912 193 // Digital out pins used for the TLC5940
mjr 26:cb71c4af2912 194 DigitalOut blank;
mjr 26:cb71c4af2912 195 DigitalOut xlat;
mjr 26:cb71c4af2912 196
mjr 26:cb71c4af2912 197 // number of daisy-chained TLC5940s we're controlling
mjr 26:cb71c4af2912 198 int nchips;
mjr 26:cb71c4af2912 199
mjr 26:cb71c4af2912 200 // Timeout to end each PWM cycle. This is a one-shot timer that we reset
mjr 26:cb71c4af2912 201 // on each cycle.
mjr 26:cb71c4af2912 202 Timeout reset_timer;
mjr 26:cb71c4af2912 203
mjr 26:cb71c4af2912 204 // Has new GS/DC data been loaded?
mjr 26:cb71c4af2912 205 volatile bool newGSData;
mjr 26:cb71c4af2912 206
mjr 26:cb71c4af2912 207 // Function to reset the display and send the next chunks of data
mjr 26:cb71c4af2912 208 void reset()
mjr 26:cb71c4af2912 209 {
mjr 26:cb71c4af2912 210 // turn off the grayscale clock, and assert BLANK to end the grayscale cycle
mjr 26:cb71c4af2912 211 gsclk.write(0);
mjr 26:cb71c4af2912 212 blank = 1;
mjr 26:cb71c4af2912 213
mjr 26:cb71c4af2912 214 // If we have new GS data, send it now
mjr 26:cb71c4af2912 215 if (newGSData)
mjr 26:cb71c4af2912 216 {
mjr 26:cb71c4af2912 217 // Send the new grayscale data.
mjr 26:cb71c4af2912 218 //
mjr 26:cb71c4af2912 219 // Note that ideally, we'd do this during the new PWM cycle
mjr 26:cb71c4af2912 220 // rather than during the blanking interval. The TLC5940 is
mjr 26:cb71c4af2912 221 // specifically designed to allow this. However, in my testing,
mjr 26:cb71c4af2912 222 // I found that sending new data during the PWM cycle was
mjr 26:cb71c4af2912 223 // unreliable - it seemed to cause a fair amount of glitching,
mjr 26:cb71c4af2912 224 // which as far as I can tell is signal noise coming from
mjr 26:cb71c4af2912 225 // crosstalk between the grayscale clock signal and the
mjr 26:cb71c4af2912 226 // SPI signal. This seems to be a common problem with
mjr 26:cb71c4af2912 227 // daisy-chained TLC5940s. It can in principle be solved with
mjr 26:cb71c4af2912 228 // careful high-speed circuit design (good ground planes,
mjr 26:cb71c4af2912 229 // short leads, decoupling capacitors), and indeed I was able
mjr 26:cb71c4af2912 230 // to improve stability to some extent with circuit tweaks,
mjr 26:cb71c4af2912 231 // but I wasn't able to eliminate it entirely. Moving the
mjr 26:cb71c4af2912 232 // data refresh into the blanking interval, on the other
mjr 26:cb71c4af2912 233 // hand, seems to entirely eliminate any instability.
mjr 26:cb71c4af2912 234 //
mjr 26:cb71c4af2912 235 // Note that there's no CPU performance penalty to this
mjr 26:cb71c4af2912 236 // approach. The KL25Z SPI implementation isn't capable of
mjr 26:cb71c4af2912 237 // asynchronous DMA, so the CPU has to wait for the
mjr 26:cb71c4af2912 238 // transmission no matter when it happens. The only downside
mjr 26:cb71c4af2912 239 // I see to this approach is that it decreases the duty cycle
mjr 26:cb71c4af2912 240 // of the PWM during updates - but very slightly. With the
mjr 26:cb71c4af2912 241 // SPI clock at 30 MHz and the PWM clock at 500 kHz, the full
mjr 26:cb71c4af2912 242 // PWM cycle is 8192us, and the data refresh time is 25us.
mjr 26:cb71c4af2912 243 // So by doing the data refersh in the blanking interval,
mjr 26:cb71c4af2912 244 // we're effectively extending the PWM cycle to 8217us,
mjr 26:cb71c4af2912 245 // which is 0.3% longer. Since the outputs are all off
mjr 26:cb71c4af2912 246 // during the blanking cycle, this is equivalent to
mjr 26:cb71c4af2912 247 // decreasing all of the output brightnesses by 0.3%. That
mjr 26:cb71c4af2912 248 // should be imperceptible to users.
mjr 26:cb71c4af2912 249 update();
mjr 26:cb71c4af2912 250
mjr 26:cb71c4af2912 251 // the chips are now in sync with our data, so we have no more
mjr 26:cb71c4af2912 252 // pending update
mjr 26:cb71c4af2912 253 newGSData = false;
mjr 26:cb71c4af2912 254
mjr 26:cb71c4af2912 255 // latch the new data while we're still blanked
mjr 26:cb71c4af2912 256 xlat = 1;
mjr 26:cb71c4af2912 257 xlat = 0;
mjr 26:cb71c4af2912 258 }
mjr 26:cb71c4af2912 259
mjr 26:cb71c4af2912 260 // end the blanking interval and restart the grayscale clock
mjr 26:cb71c4af2912 261 blank = 0;
mjr 26:cb71c4af2912 262 gsclk.write(.5);
mjr 26:cb71c4af2912 263
mjr 26:cb71c4af2912 264 // set up the next blanking interrupt
mjr 26:cb71c4af2912 265 reset_timer.attach(this, &TLC5940::reset, (1.0/GSCLK_SPEED)*4096.0);
mjr 26:cb71c4af2912 266 }
mjr 26:cb71c4af2912 267
mjr 26:cb71c4af2912 268 void update()
mjr 26:cb71c4af2912 269 {
mjr 26:cb71c4af2912 270 // Send GS data. The serial format orders the outputs from last to first
mjr 26:cb71c4af2912 271 // (output #15 on the last chip in the daisy-chain to output #0 on the
mjr 26:cb71c4af2912 272 // first chip). For each output, we send 12 bits containing the grayscale
mjr 26:cb71c4af2912 273 // level (0 = fully off, 0xFFF = fully on). Bit order is most significant
mjr 26:cb71c4af2912 274 // bit first.
mjr 26:cb71c4af2912 275 //
mjr 26:cb71c4af2912 276 // The KL25Z SPI can only send in 8-bit increments, so we need to divvy up
mjr 26:cb71c4af2912 277 // the 12-bit outputs into 8-bit bytes. Each pair of 12-bit outputs adds up
mjr 26:cb71c4af2912 278 // to 24 bits, which divides evenly into 3 bytes, so send each pairs of
mjr 26:cb71c4af2912 279 // outputs as three bytes:
mjr 26:cb71c4af2912 280 //
mjr 26:cb71c4af2912 281 // [ element i+1 bits ] [ element i bits ]
mjr 26:cb71c4af2912 282 // 11 10 9 8 7 6 5 4 3 2 1 0 11 10 9 8 7 6 5 4 3 2 1 0
mjr 26:cb71c4af2912 283 // [ first byte ] [ second byte ] [ third byte ]
mjr 26:cb71c4af2912 284 for (int i = (16 * nchips) - 2 ; i >= 0 ; i -= 2)
mjr 26:cb71c4af2912 285 {
mjr 26:cb71c4af2912 286 // first byte - element i+1 bits 4-11
mjr 26:cb71c4af2912 287 spi.write(((gs[i+1] & 0xFF0) >> 4) & 0xff);
mjr 26:cb71c4af2912 288
mjr 26:cb71c4af2912 289 // second byte - element i+1 bits 0-3, then element i bits 8-11
mjr 26:cb71c4af2912 290 spi.write((((gs[i+1] & 0x00F) << 4) | ((gs[i] & 0xF00) >> 8)) & 0xFF);
mjr 26:cb71c4af2912 291
mjr 26:cb71c4af2912 292 // third byte - element i bits 0-7
mjr 26:cb71c4af2912 293 spi.write(gs[i] & 0x0FF);
mjr 26:cb71c4af2912 294 }
mjr 26:cb71c4af2912 295 }
mjr 26:cb71c4af2912 296 };
mjr 26:cb71c4af2912 297
mjr 26:cb71c4af2912 298
mjr 26:cb71c4af2912 299 #endif