sbDriver.h

00001 //Low level driver for shiftbrite modules
00002 
00003 #ifndef SHIFTBTIRE
00004 #define SHIFTBTIRE
00005 #include "mbed.h"
00006 //REFER TO FRDM_LIGHTFX modules for hardware code
00007 
00008 //=============================================================================================  
00009 
00010 /** Colour class
00011 * Used as a base class for storing ShiftBrite colour information
00012 *
00013 * It is inherited by rgbLed class and is of little use if instanciated directly.
00014 * Please see class shiftBriteDisplay for intended use.
00015 */ 
00016  
00017 class colour{
00018 private:
00019     unsigned short int value; //0-1023 range
00020 
00021 public:
00022     void setColour(unsigned short int v){ v <= 1023 ? value = v : value = 1023;} // include range limiting
00023     unsigned short int getColour(void){return value;}
00024     colour operator =( unsigned short int v); //overload = relative to unsigned short int
00025     colour operator =( colour c); // overload = relative to colour
00026 };
00027 
00028 //=============================================================================================    
00029 /** rgbLed class
00030 * Used to instanciate a single rgb ShiftBrite object.
00031 *
00032 * ShiftBrite module consists of a single RGB led but
00033 * modules can be hooked in serial to form a chain of 2 or more modules
00034 *
00035 * This class is used as a dynamically allocated member in class shiftBriteDisplay.
00036 * It contains NO member functions for updating the physical shiftbright module so
00037 * is of limited use if instanciated directly. Please see class shiftBriteDisplay for intended use.
00038 */
00039 class rgbLed : public colour{//Inherit colour as a led consists of 3 colours
00040 private:
00041     colour red, green, blue;
00042     //Could add in 3 members here to track each module's individual current control (Dot correction)
00043     //but, this is not a critical app and I'd rather hang on to the extra memory so I elected
00044     //to have one set of Dot Corr values for ALL modules. This is handled by shiftBriteDisplay class. see below
00045 public:
00046 //    the constructors
00047     rgbLed(unsigned long int rgbValue); // constructor for RGB value e.g. 0xFFFFFF. Will expand 0XFF to 0x3FF as per colour range
00048     rgbLed(unsigned short int red, unsigned short int green, unsigned short int blue); //overload for  seperate r,g,b arguments
00049     rgbLed();//overload for no arguments
00050 
00051  //   the setters
00052     void setRgbLed(unsigned long int rgbValue); // RGB value e.g. 0xFFFFFF. Will expand 0XFF to 0x3FF as per colour range, also, update packet
00053     void setRgbLed(unsigned short int red, unsigned short int green, unsigned short int blue); //overload for  seperate r,g,b arguments, also update packet
00054     unsigned long int getPacket();
00055 
00056 //    the getters
00057     unsigned short int getRed(){return red.getColour();}
00058     unsigned short int getGreen(){return green.getColour();}
00059     unsigned short int getBlue(){return blue.getColour();}
00060     
00061 };
00062 
00063 //=============================================================================================    
00064 /** shiftBriteDisplay class.
00065 * Used to write data to one (or more) shiftBrite module(s) via the SPI port on FRDM KL25Z module.
00066 *
00067 * Dynamically allocates storage for each module, based on <moduleCount> provided to the constructor.
00068 * Takes in references for the required hardware: SPI, Latch, Enable, and, if implemented, Reset.
00069 * Shiftbrite modules does NOT have a reset line but can be reset by removing the power. The reset line
00070 * referenced will toggle to allow you to implement the required hardware.
00071 * @param Serial Pointer to instance of Serial object.
00072   @param Latch Pin used to control data latching on shiftbrite module.
00073   @param Enable Pin used to control LED output buffers of shiftbrite module.
00074   @param Reset Pin used to signal a circuit that control the +ve power to the shiftbrite modules. This can be ignored if no reset required.
00075   @param SPI Port to send serial data to shoftbrite module. (Data and Clock).
00076   @param moduleCount int, the number of connected modules.
00077 *
00078 *   Example:
00079 *   @code
00080     #include "mbed.h"
00081     #include "sbDriver.h"
00082     DigitalOut latch(PTC16);//to LI pin of shiftBrite module
00083     DigitalOut enable(PTA13);//to EI pin of shiftBrite module
00084     DigitalOut reset(PTC12);//to power control circuit of your doing - NOT MANDATORY
00085     SPI spi(PTD2,NC,PTD1);//PDT2 = MOSI to DI and PDT1 to CI of shiftBrite module
00086 
00087     shiftBriteDisplay sbDisplay(latch, enable, reset, spi,6);//for, say, 6 modules wired in SERIES.
00088     
00089     //If you wish to change the DOT CORR registers
00090     sbDisplay.setCurrentCorr(0x78,0x64,0x64);//use values you want to set as default. These are the suggested values
00091     
00092     //Now, you can either call a member function to update the actual display OR
00093     //set it up using a Ticker. This is how you setup a ticker
00094     Ticker t;
00095     t.attach_us(&sbDisplay,&shiftBriteDisplay::displayFrame,41666);//call updateFrame 24 times per second (every 41666uS)
00096     //Ticker will automatically call sbDisplay.displayFrame()
00097     while(1){
00098         //Now just fill in the colours you want
00099         sbDisplay.setLed(0,1023,0,0); //FULL on red on the LAST display in the chain
00100         sbDisplay.setLed(5,0,1023,0); //FULL on green on first (remember the display has 6 leds in this example) LED
00101         //etc......
00102     }
00103 
00104 *       @endcode
00105 *
00106 *       @note - Usage of shifBriteDisplay::setLed() member is as follows:
00107 *       @code object.setLed(LedModuleNum,red, green, blue); //where colours are in the range of 0-1023@endcode
00108 *       or
00109 *       @code object.setLed(LedModuleNnum,RGB);// where RGB is in a range from 0x000000 to 0XFFFFFF (0xRRGGBB)@endcode
00110 *       @note NB, In the second method each colour has a range of 0-255 (0-0xFF) but that is expanded to the full range. This can be convenient but
00111 *       I suggest the first method is the best.
00112 *       
00113 *
00114 *        @endnote
00115 */
00116 class shiftBriteDisplay{
00117 private:
00118     //Serial *serial_p; // for debug printing
00119     
00120     //Harware control lines - common to all leds in display
00121     DigitalOut sb_latch;
00122     DigitalOut sb_enable;  
00123     DigitalOut sb_reset;//Note, this effected by toggling power to the modules, it's not inherent shiftbrite functionality
00124     SPI spi;
00125     
00126     //Led module(s)
00127     rgbLed *module_p; // points to the array of modules with same number of elements as LED modules
00128     unsigned int moduleCount;
00129     unsigned char rCorr, gCorr, bCorr; //These are the 'global' values for the current correction reg. DOT CORRECTION.
00130     
00131     unsigned short int f_update;// flags that object is in an update cycle so that new req are ignored
00132     
00133     // hardware control member methods
00134     void priv_SBEnable(void){sb_enable = 0;}
00135     void priv_SBDisable(void){sb_enable = 1;}
00136     void priv_SBLatch(void){wait(0.0001);sb_latch = 1;wait(0.0001);sb_latch = 0;}
00137     void priv_reset(void);//{sb_reset=0;wait(0.1);sb_reset=1;
00138         
00139     // writes a single rgbLed RGB values as stored in the module_p array
00140     void send(rgbLed M, unsigned short int commandStatus=0); // accesses rgbLed.getPacket()
00141     
00142 public:
00143 //TO DO - Modify the constructor to initialise the spi PWM, and setup defaults for the SB control sinals (i.e. enable, latch and reset)
00144 // Also, initialize the SB current control registers(this WILL need to be done each time the SB modules are reset)
00145 
00146 /**Constructor
00147 See the example code for usage instructions.
00148 */
00149 //    shiftBriteDisplay (Serial *port,DigitalOut &latch, DigitalOut &enable, DigitalOut &reset, SPI &spiPort, unsigned int moduleCount); //constructor
00150 
00151     shiftBriteDisplay (DigitalOut &latch, DigitalOut &enable, DigitalOut &reset, SPI &spiPort, unsigned int moduleCount); //constructor
00152 //    Destructor
00153     ~shiftBriteDisplay();//destructor - needs to release module_p
00154     
00155 //    Setters 
00156 /**used to set the colour for a specific dot (LED) using the RGB system. e.g. 0XFF0000 is full blue. I would suggest not using this
00157 * unless you have no option because it only allows specifying 256 levels for each colour whereas the ShiftBright modules are 
00158 * capable of 1024. Use the overloaded member function. Example:
00159 *   @code
00160     myDisplay.setLed(ledNum,0X007F00);//Set led module 'ledNum' to  half brightness green
00161     myDisplay.setLed(ledNum+1,0X00FF00); // Set module 'ledNum+1' to full brightness green
00162     @endcode
00163 */
00164    void setLed(unsigned int moduleNum, unsigned long int rgbValue);
00165 
00166 
00167 /**used to set the colour for a specific dot (LED) using the full ability of the ShiftBrite modules. Each colour is supplied 
00168 * individualy in the range of 0-1023 (0-0x3FF). Example:
00169 *   @code
00170     myDisplay.setLed(ledNum,0,512,0);//Set led module 'ledNum' to  half brightness green using a decimal no
00171     myDisplay.setLed(ledNum+1,0,0x3FF,0); // Set module 'ledNum+1' to full brightness green using a hex no
00172     @endcode
00173 
00174 */
00175     void setLed(unsigned int moduleNum, unsigned short int red, unsigned short int green, unsigned short int blue);//Overloaded
00176 //    void setCurrentCorr( unsigned long int rgbValue=0x786464);//ALL modules
00177 
00178 /** used to adjust the maximum current to each colour. Consists of 3 values, one each for red, green and blue.
00179 * This allow you to adjust the brightness level of the reds, green and blues. Is usefull if one colour is brighter than the others
00180 * that causes colours to mix incorrectly. When used it will record the arguments as the default values. Range is from 0 to 127 for each colour.
00181 * This equated to rought 30% to 100% full brightness. NOTE, This is NOT for setting the brightness of the display (even though
00182 * it can be abused that way), it is intended for adjusting the brightness balance between colours so that, for example, 0X3FF red and 0X3FF
00183 * green makes yellow and not reddy-yellow or greeny-yellow etc.
00184 * @code
00185     myDisplay.setCurrentCorr(0x78,0x64,0x64); // set and record values as default. Retained only until master reset or powerdown.
00186   @endcode
00187 *   
00188 */
00189     void setCurrentCorr( unsigned short int red, unsigned short int green, unsigned short int blue);//ALL modules
00190 
00191 /**Overloaded version of above but calls up the stored values.
00192 * These can either be the default (as Suggested by the ShiftBrite manufacturer) if they were not overwritten
00193 * with the alternate member function (above).
00194 */
00195     void setCurrentCorr();//overload - meaning, read the vals from the class member and set accordingly
00196 
00197 //    Getters
00198     
00199 //    Display update  
00200 /** used to refresh the display. All colour values are written out.
00201 */  
00202     void displayFrame();// write a whole display's worth of data.
00203     unsigned int getModuleCount(){return moduleCount;}
00204     
00205 //    Basic effects
00206 /**rotateLeft()
00207 * is used to shift the whole display colours one step left.
00208 *The first colour is rotated around and shifted in the last dot.
00209 * @code
00210 for(loop=0; loop !=NumOfLeds; loop++){
00211     sbDisplay.rotateLeft();
00212     sbDisplay.displayFrame();
00213     wait(0.2);
00214 }
00215 * @endcode
00216 */
00217     void rotateLeft();
00218     
00219 /**shiftLeft()
00220 * is used to shift the whole display colours one step left.
00221 * A blank dot is shifted in unless a colour is given in the argument.
00222 * @code
00223 for(loop=0; loop !=NumOfLeds; loop++){
00224     sbDisplay.shiftLeft();//or, to shift in a colour .shiftLeft(1000,200,0);
00225     sbDisplay.displayFrame();
00226     wait(0.2);
00227 }
00228 * @endcode
00229 */
00230     void shiftLeft(unsigned short int inR=0,unsigned short int inG=0,unsigned short int inB=0);//info shifted out is lost
00231 
00232 /**rotateRight()
00233 * is used to shift the whole display colours one step right.
00234 *The first colour is rotated around and shifted in the last dot.
00235 * @code
00236 for(loop=0; loop !=NumOfLeds; loop++){
00237     sbDisplay.rotateRight();
00238     sbDisplay.displayFrame();
00239     wait(0.2);
00240 }
00241 * @endcode
00242 */
00243     void rotateRight();
00244 
00245 
00246 /**shiftRight()
00247 * is used to shift the whole display colours one step right.
00248 * A blank dot is shifted in unless a colour is given as an argument.
00249 * @code
00250 for(loop=0; loop !=NumOfLeds; loop++){
00251     sbDisplay.shiftRight(); // or, to feed in a colour sbDisplay.shiftRight(0,0XF0,0x30);
00252     sbDisplay.displayFrame();
00253     wait(0.2);
00254 }
00255 * @endcode
00256 */
00257     void shiftRight(unsigned short int inR=0,unsigned short int inG=0,unsigned short int inB=0);//info shifted out is lost
00258     
00259 /**Display output is turned enabled.
00260 */
00261     void turnOn();
00262     
00263 /**Display output is turned disabled.
00264 */    
00265     void turnOff();
00266     
00267 /**Used to exchange display values left to right and right to left.
00268 */
00269     void flip(); //swop positions
00270     
00271 /**Changes all display colours with it's mathematical opposite.
00272 */
00273     void invert(); //invert colours
00274     
00275     
00276 };
00277 #endif