Advertisement
Guest User

Arduboy2Core.h

a guest
Mar 25th, 2018
222
Never
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
C++ 30.39 KB | None
  1. /**
  2.  * @file Arduboy2Core.h
  3.  * \brief
  4.  * The Arduboy2Core class for Arduboy hardware initilization and control.
  5.  */
  6.  
  7. #ifndef ARDUBOY2_CORE_H
  8. #define ARDUBOY2_CORE_H
  9.  
  10. #include <Arduino.h>
  11. #include <avr/power.h>
  12. #include <avr/sleep.h>
  13. #include <avr/wdt.h>
  14. #include <limits.h>
  15.  
  16.  
  17. // main hardware compile flags
  18.  
  19. #if !defined(ARDUBOY_10) && !defined(AB_DEVKIT)
  20. /* defaults to Arduboy Release 1.0 if not using a boards.txt file
  21.  *
  22.  * we default to Arduboy Release 1.0 if a compile flag has not been
  23.  * passed to us from a boards.txt file
  24.  *
  25.  * if you wish to compile for the devkit without using a boards.txt
  26.  * file simply comment out the ARDUBOY_10 define and uncomment
  27.  * the AB_DEVKIT define like this:
  28.  *
  29.  *     // #define ARDUBOY_10
  30.  *     #define AB_DEVKIT
  31.  */
  32. #define ARDUBOY_10   //< compile for the production Arduboy v1.0
  33. // #define AB_DEVKIT    //< compile for the official dev kit
  34. #endif
  35.  
  36. #define RGB_ON LOW   /**< For digitially setting an RGB LED on using digitalWriteRGB() */
  37. #define RGB_OFF HIGH /**< For digitially setting an RGB LED off using digitalWriteRGB() */
  38.  
  39. // ----- Arduboy pins -----
  40. #ifdef ARDUBOY_10
  41.  
  42. #define PIN_CS 12       // Display CS Arduino pin number
  43. #define CS_PORT PORTD   // Display CS port
  44. #define CS_BIT PORTD6   // Display CS physical bit number
  45.  
  46. #define PIN_DC 4        // Display D/C Arduino pin number
  47. #define DC_PORT PORTD   // Display D/C port
  48. #define DC_BIT PORTD4   // Display D/C physical bit number
  49.  
  50. #define PIN_RST 13      // Display reset Arduino pin number
  51. #define RST_PORT PORTC  // Display reset port
  52. #define RST_BIT PORTC7  // Display reset physical bit number
  53.  
  54. #define RED_LED 10   /**< The pin number for the red color in the RGB LED. */
  55. #define GREEN_LED 11 /**< The pin number for the greem color in the RGB LED. */
  56. #define BLUE_LED 9   /**< The pin number for the blue color in the RGB LED. */
  57.  
  58. #define RED_LED_PORT PORTB
  59. #define RED_LED_BIT PORTB6
  60.  
  61. #define GREEN_LED_PORT PORTB
  62. #define GREEN_LED_BIT PORTB7
  63.  
  64. #define BLUE_LED_PORT PORTB
  65. #define BLUE_LED_BIT PORTB5
  66.  
  67. // bit values for button states
  68. // these are determined by the buttonsState() function
  69. #define LEFT_BUTTON _BV(5)  /**< The Left button value for functions requiring a bitmask */
  70. #define RIGHT_BUTTON _BV(6) /**< The Right button value for functions requiring a bitmask */
  71. #define UP_BUTTON _BV(7)    /**< The Up button value for functions requiring a bitmask */
  72. #define DOWN_BUTTON _BV(4)  /**< The Down button value for functions requiring a bitmask */
  73. #define A_BUTTON _BV(3)     /**< The A button value for functions requiring a bitmask */
  74. #define B_BUTTON _BV(2)     /**< The B button value for functions requiring a bitmask */
  75.  
  76. #define PIN_LEFT_BUTTON A2
  77. #define LEFT_BUTTON_PORT PORTF
  78. #define LEFT_BUTTON_PORTIN PINF
  79. #define LEFT_BUTTON_DDR DDRF
  80. #define LEFT_BUTTON_BIT PORTF5
  81.  
  82. #define PIN_RIGHT_BUTTON A1
  83. #define RIGHT_BUTTON_PORT PORTF
  84. #define RIGHT_BUTTON_PORTIN PINF
  85. #define RIGHT_BUTTON_DDR DDRF
  86. #define RIGHT_BUTTON_BIT PORTF6
  87.  
  88. #define PIN_UP_BUTTON A0
  89. #define UP_BUTTON_PORT PORTF
  90. #define UP_BUTTON_PORTIN PINF
  91. #define UP_BUTTON_DDR DDRF
  92. #define UP_BUTTON_BIT PORTF7
  93.  
  94. #define PIN_DOWN_BUTTON A3
  95. #define DOWN_BUTTON_PORT PORTF
  96. #define DOWN_BUTTON_PORTIN PINF
  97. #define DOWN_BUTTON_DDR DDRF
  98. #define DOWN_BUTTON_BIT PORTF4
  99.  
  100. #define PIN_A_BUTTON 7
  101. #define A_BUTTON_PORT PORTE
  102. #define A_BUTTON_PORTIN PINE
  103. #define A_BUTTON_DDR DDRE
  104. #define A_BUTTON_BIT PORTE6
  105.  
  106. #define PIN_B_BUTTON 8
  107. #define B_BUTTON_PORT PORTB
  108. #define B_BUTTON_PORTIN PINB
  109. #define B_BUTTON_DDR DDRB
  110. #define B_BUTTON_BIT PORTB4
  111.  
  112. #define PIN_SPEAKER_1 5  /**< The pin number of the first lead of the speaker */
  113. #define PIN_SPEAKER_2 6  /**< The pin number of the second lead of the speaker */
  114.  
  115. #define SPEAKER_1_PORT PORTC
  116. #define SPEAKER_1_DDR DDRC
  117. #define SPEAKER_1_BIT PORTC6
  118.  
  119. #define SPEAKER_2_PORT PORTD
  120. #define SPEAKER_2_DDR DDRD
  121. #define SPEAKER_2_BIT PORTD7
  122. // -----------------------
  123.  
  124. // ----- DevKit pins -----
  125. #elif defined(AB_DEVKIT)
  126.  
  127. #define PIN_CS 6        // Display CS Arduino pin number
  128. #define CS_PORT PORTD   // Display CS port
  129. #define CS_BIT PORTD7   // Display CS physical bit number
  130.  
  131. #define PIN_DC 4        // Display D/C Arduino pin number
  132. #define DC_PORT PORTD   // Display D/C port
  133. #define DC_BIT PORTD4   // Display D/C physical bit number
  134.  
  135. #define PIN_RST 12      // Display reset Arduino pin number
  136. #define RST_PORT PORTD  // Display reset port
  137. #define RST_BIT PORTD6  // Display reset physical bit number
  138.  
  139. #define SPI_MOSI_PORT PORTB
  140. #define SPI_MOSI_BIT PORTB2
  141.  
  142. #define SPI_SCK_PORT PORTB
  143. #define SPI_SCK_BIT PORTB1
  144.  
  145. // map all LEDs to the single TX LED on DEVKIT
  146. #define RED_LED 17
  147. #define GREEN_LED 17
  148. #define BLUE_LED 17
  149.  
  150. #define BLUE_LED_PORT PORTB
  151. #define BLUE_LED_BIT PORTB0
  152.  
  153. // bit values for button states
  154. // these are determined by the buttonsState() function
  155. #define LEFT_BUTTON _BV(5)
  156. #define RIGHT_BUTTON _BV(2)
  157. #define UP_BUTTON _BV(4)
  158. #define DOWN_BUTTON _BV(6)
  159. #define A_BUTTON _BV(1)
  160. #define B_BUTTON _BV(0)
  161.  
  162. // pin values for buttons, probably shouldn't use these
  163. #define PIN_LEFT_BUTTON 9
  164. #define LEFT_BUTTON_PORT PORTB
  165. #define LEFT_BUTTON_PORTIN PINB
  166. #define LEFT_BUTTON_DDR DDRB
  167. #define LEFT_BUTTON_BIT PORTB5
  168.  
  169. #define PIN_RIGHT_BUTTON 5
  170. #define RIGHT_BUTTON_PORT PORTC
  171. #define RIGHT_BUTTON_PORTIN PINC
  172. #define RIGHT_BUTTON_DDR DDRC
  173. #define RIGHT_BUTTON_BIT PORTC6
  174.  
  175. #define PIN_UP_BUTTON 8
  176. #define UP_BUTTON_PORT PORTB
  177. #define UP_BUTTON_PORTIN PINB
  178. #define UP_BUTTON_DDR DDRB
  179. #define UP_BUTTON_BIT PORTB4
  180.  
  181. #define PIN_DOWN_BUTTON 10
  182. #define DOWN_BUTTON_PORT PORTB
  183. #define DOWN_BUTTON_PORTIN PINB
  184. #define DOWN_BUTTON_DDR DDRB
  185. #define DOWN_BUTTON_BIT PORTB6
  186.  
  187. #define PIN_A_BUTTON A0
  188. #define A_BUTTON_PORT PORTF
  189. #define A_BUTTON_PORTIN PINF
  190. #define A_BUTTON_DDR DDRF
  191. #define A_BUTTON_BIT PORTF7
  192.  
  193. #define PIN_B_BUTTON A1
  194. #define B_BUTTON_PORT PORTF
  195. #define B_BUTTON_PORTIN PINF
  196. #define B_BUTTON_DDR DDRF
  197. #define B_BUTTON_BIT PORTF6
  198.  
  199. #define PIN_SPEAKER_1 A2
  200. #define SPEAKER_1_PORT PORTF
  201. #define SPEAKER_1_DDR DDRF
  202. #define SPEAKER_1_BIT PORTF5
  203. // SPEAKER_2 is purposely not defined for DEVKIT as it could potentially
  204. // be dangerous and fry your hardware (because of the devkit wiring).
  205. //
  206. // Reference: https://github.com/Arduboy/Arduboy/issues/108
  207.  
  208. #endif
  209. // --------------------
  210.  
  211. // ----- Pins common on Arduboy and DevKit -----
  212.  
  213. // Unconnected analog input used for noise by initRandomSeed()
  214. #define RAND_SEED_IN A4
  215. #define RAND_SEED_IN_PORT PORTF
  216. #define RAND_SEED_IN_BIT PORTF1
  217. // Value for ADMUX to read the random seed pin: 2.56V reference, ADC1
  218. #define RAND_SEED_IN_ADMUX (_BV(REFS0) | _BV(REFS1) | _BV(MUX0))
  219.  
  220. // SPI interface
  221. #define SPI_MISO_PORT PORTB
  222. #define SPI_MISO_BIT PORTB3
  223.  
  224. #define SPI_MOSI_PORT PORTB
  225. #define SPI_MOSI_BIT PORTB2
  226.  
  227. #define SPI_SCK_PORT PORTB
  228. #define SPI_SCK_BIT PORTB1
  229.  
  230. #define SPI_SS_PORT PORTB
  231. #define SPI_SS_BIT PORTB0
  232. // --------------------
  233.  
  234. // OLED hardware (SSD1306)
  235.  
  236. #define OLED_PIXELS_INVERTED 0xA7 // All pixels inverted
  237. #define OLED_PIXELS_NORMAL 0xA6 // All pixels normal
  238.  
  239. #define OLED_ALL_PIXELS_ON 0xA5 // all pixels on
  240. #define OLED_PIXELS_FROM_RAM 0xA4 // pixels mapped to display RAM contents
  241.  
  242. #define OLED_VERTICAL_FLIPPED 0xC0 // reversed COM scan direction
  243. #define OLED_VERTICAL_NORMAL 0xC8 // normal COM scan direction
  244.  
  245. #define OLED_HORIZ_FLIPPED 0xA0 // reversed segment re-map
  246. #define OLED_HORIZ_NORMAL 0xA1 // normal segment re-map
  247.  
  248. // -----
  249.  
  250. #define WIDTH 128 /**< The width of the display in pixels */
  251. #define HEIGHT 64 /**< The height of the display in pixels */
  252.  
  253. #define COLUMN_ADDRESS_END (WIDTH - 1) & 127   // 128 pixels wide
  254. #define PAGE_ADDRESS_END ((HEIGHT/8)-1) & 7    // 8 pages high
  255.  
  256. /** \brief
  257.  * Eliminate the USB stack to free up code space.
  258.  *
  259.  * \note
  260.  * **WARNING:** Removing the USB code will make it impossible for sketch
  261.  * uploader programs to automatically force a reset into the bootloader!
  262.  * This means that a user will manually have to invoke a reset in order to
  263.  * upload a new sketch, after one without USB has be been installed.
  264.  * Be aware that the timing for the point that a reset must be initiated can
  265.  * be tricky, which could lead to some frustration on the user's part.
  266.  *
  267.  * \details
  268.  * \parblock
  269.  * This macro will cause the USB code, normally included in the sketch as part
  270.  * of the standard Arduino environment, to be eliminated. This will free up a
  271.  * fair amount of program space, and some RAM space as well, at the expense of
  272.  * disabling all USB functionality within the sketch (except as power input).
  273.  *
  274.  * The macro should be placed before the `setup()` function definition:
  275.  *
  276.  * \code{.cpp}
  277.  * #include <Arduboy2.h>
  278.  *
  279.  * Arduboy2 arduboy;
  280.  *
  281.  * // (Other variable declarations, etc.)
  282.  *
  283.  * // Eliminate the USB stack
  284.  * ARDUBOY_NO_USB
  285.  *
  286.  * void setup() {
  287.  *   arduboy.begin();
  288.  *   // any additional setup code
  289.  * }
  290.  * \endcode
  291.  *
  292.  * As stated in the warning above, without the USB code an uploader program
  293.  * will be unable to automatically force a reset into the bootloader to upload
  294.  * a new sketch. The user will have to manually invoke a reset. In addition to
  295.  * eliminating the USB code, this macro will check if the DOWN button is held
  296.  * when the sketch first starts and, if so, will call `exitToBootloader()` to
  297.  * start the bootloader for uploading. This makes it easier for the user than
  298.  * having to press the reset button.
  299.  *
  300.  * However, to make it even more convenient for a user to invoke the bootloader
  301.  * it is highly recommended that a sketch using this macro include a menu or
  302.  * prompt that allows the user to press the DOWN button within the sketch,
  303.  * which should cause `exitToBootloader()` to be called.
  304.  *
  305.  * At a minimum, the documentation for the sketch should clearly state that a
  306.  * manual reset will be required, and give detailed instructions on what the
  307.  * user must do to upload a new sketch.
  308.  * \endparblock
  309.  *
  310.  * \see Arduboy2Core::exitToBootloader()
  311.  */
  312. #define ARDUBOY_NO_USB int main() __attribute__ ((OS_main)); \
  313. int main() { \
  314.   Arduboy2Core::mainNoUSB(); \
  315.   return 0; \
  316. }
  317.  
  318.  
  319. /** \brief
  320.  * Lower level functions generally dealing directly with the hardware.
  321.  *
  322.  * \details
  323.  * This class is inherited by Arduboy2Base and thus also Arduboy2, so wouldn't
  324.  * normally be used directly by a sketch.
  325.  *
  326.  * \note
  327.  * A friend class named _Arduboy2Ex_ is declared by this class. The intention
  328.  * is to allow a sketch to create an _Arduboy2Ex_ class which would have access
  329.  * to the private and protected members of the Arduboy2Core class. It is hoped
  330.  * that this may eliminate the need to create an entire local copy of the
  331.  * library, in order to extend the functionality, in most circumstances.
  332.  */
  333. class Arduboy2Core
  334. {
  335.   friend class Arduboy2Ex;
  336.  
  337.   public:
  338.     Arduboy2Core();
  339.  
  340.     /** \brief
  341.      * Idle the CPU to save power.
  342.      *
  343.      * \details
  344.      * This puts the CPU in _idle_ sleep mode. You should call this as often
  345.      * as you can for the best power savings. The timer 0 overflow interrupt
  346.      * will wake up the chip every 1ms, so even at 60 FPS a well written
  347.      * app should be able to sleep maybe half the time in between rendering
  348.      * it's own frames.
  349.      */
  350.     void static idle();
  351.  
  352.     /** \brief
  353.      * Put the display into data mode.
  354.      *
  355.      * \details
  356.      * When placed in data mode, data that is sent to the display will be
  357.      * considered as data to be displayed.
  358.      *
  359.      * \note
  360.      * This is a low level function that is not intended for general use in a
  361.      * sketch. It has been made public and documented for use by derived
  362.      * classes.
  363.      *
  364.      * \see LCDCommandMode() SPItransfer()
  365.      */
  366.     void static LCDDataMode();
  367.  
  368.     /** \brief
  369.      * Put the display into command mode.
  370.      *
  371.      * \details
  372.      * When placed in command mode, data that is sent to the display will be
  373.      * treated as commands.
  374.      *
  375.      * See the SSD1306 controller and OLED display documents for available
  376.      * commands and command sequences.
  377.      *
  378.      * Links:
  379.      *
  380.      * - https://www.adafruit.com/datasheets/SSD1306.pdf
  381.      * - http://www.buydisplay.com/download/manual/ER-OLED013-1_Series_Datasheet.pdf
  382.      *
  383.      * \note
  384.      * This is a low level function that is not intended for general use in a
  385.      * sketch. It has been made public and documented for use by derived
  386.      * classes.
  387.      *
  388.      * \see LCDDataMode() sendLCDCommand() SPItransfer()
  389.      */
  390.     void static LCDCommandMode();
  391.  
  392.     /** \brief
  393.      * Transfer a byte to the display.
  394.      *
  395.      * \param data The byte to be sent to the display.
  396.      *
  397.      * \details
  398.      * Transfer one byte to the display over the SPI port and wait for the
  399.      * transfer to complete. The byte will either be interpreted as a command
  400.      * or as data to be placed on the screen, depending on the command/data
  401.      * mode.
  402.      *
  403.      * \see LCDDataMode() LCDCommandMode() sendLCDCommand()
  404.      */
  405.     void static SPItransfer(uint8_t data);
  406.  
  407.     /** \brief
  408.      * Turn the display off.
  409.      *
  410.      * \details
  411.      * The display will clear and be put into a low power mode. This can be
  412.      * used to extend battery life when a game is paused or when a sketch
  413.      * doesn't require anything to be displayed for a relatively long period
  414.      * of time.
  415.      *
  416.      * \see displayOn()
  417.      */
  418.     void static displayOff();
  419.  
  420.     /** \brief
  421.      * Turn the display on.
  422.      *
  423.      * \details
  424.      * Used to power up and reinitialize the display after calling
  425.      * `displayOff()`.
  426.      *
  427.      * \note
  428.      * The previous call to `displayOff()` will have caused the display's
  429.      * buffer contents to be lost. The display will have to be re-painted,
  430.      * which is usually done by calling `display()`.
  431.      *
  432.      * \see displayOff()
  433.      */
  434.     void static displayOn();
  435.  
  436.     /** \brief
  437.      * Get the width of the display in pixels.
  438.      *
  439.      * \return The width of the display in pixels.
  440.      *
  441.      * \note
  442.      * In most cases, the defined value `WIDTH` would be better to use instead
  443.      * of this function.
  444.      */
  445.     uint8_t static width();
  446.  
  447.     /** \brief
  448.      * Get the height of the display in pixels.
  449.      *
  450.      * \return The height of the display in pixels.
  451.      *
  452.      * \note
  453.      * In most cases, the defined value `HEIGHT` would be better to use instead
  454.      * of this function.
  455.      */
  456.     uint8_t static height();
  457.  
  458.     /** \brief
  459.      * Get the current state of all buttons as a bitmask.
  460.      *
  461.      * \return A bitmask of the state of all the buttons.
  462.      *
  463.      * \details
  464.      * The returned mask contains a bit for each button. For any pressed button,
  465.      * its bit will be 1. For released buttons their associated bits will be 0.
  466.      *
  467.      * The following defined mask values should be used for the buttons:
  468.      *
  469.      * LEFT_BUTTON, RIGHT_BUTTON, UP_BUTTON, DOWN_BUTTON, A_BUTTON, B_BUTTON
  470.      */
  471.     uint8_t static buttonsState();
  472.  
  473.     /** \brief
  474.      * Paint 8 pixels vertically to the display.
  475.      *
  476.      * \param pixels A byte whose bits specify a vertical column of 8 pixels.
  477.      *
  478.      * \details
  479.      * A byte representing a vertical column of 8 pixels is written to the
  480.      * display at the current page and column address. The address is then
  481.      * incremented. The page/column address will wrap to the start of the
  482.      * display (the top left) when it increments past the end (lower right).
  483.      *
  484.      * The least significant bit represents the top pixel in the column.
  485.      * A bit set to 1 is lit, 0 is unlit.
  486.      *
  487.      * Example:
  488.      *
  489.      *     X = lit pixels, . = unlit pixels
  490.      *
  491.      *     blank()                          paint8Pixels() 0xFF, 0, 0xF0, 0, 0x0F
  492.      *     v TOP LEFT corner (8x9)          v TOP LEFT corner
  493.      *     . . . . . . . . (page 1)         X . . . X . . . (page 1)
  494.      *     . . . . . . . .                  X . . . X . . .
  495.      *     . . . . . . . .                  X . . . X . . .
  496.      *     . . . . . . . .                  X . . . X . . .
  497.      *     . . . . . . . .                  X . X . . . . .
  498.      *     . . . . . . . .                  X . X . . . . .
  499.      *     . . . . . . . .                  X . X . . . . .
  500.      *     . . . . . . . . (end of page 1)  X . X . . . . . (end of page 1)
  501.      *     . . . . . . . . (page 2)         . . . . . . . . (page 2)
  502.      */
  503.     void static paint8Pixels(uint8_t pixels);
  504.  
  505.     /** \brief
  506.      * Paints an entire image directly to the display from program memory.
  507.      *
  508.      * \param image A byte array in program memory representing the entire
  509.      * contents of the display.
  510.      *
  511.      * \details
  512.      * The contents of the specified array in program memory is written to the
  513.      * display. Each byte in the array represents a vertical column of 8 pixels
  514.      * with the least significant bit at the top. The bytes are written starting
  515.      * at the top left, progressing horizontally and wrapping at the end of each
  516.      * row, to the bottom right. The size of the array must exactly match the
  517.      * number of pixels in the entire display.
  518.      *
  519.      * \see paint8Pixels()
  520.      */
  521.     void static paintScreen(const uint8_t *image);
  522.  
  523.     /** \brief
  524.      * Paints an entire image directly to the display from an array in RAM.
  525.      *
  526.      * \param image A byte array in RAM representing the entire contents of
  527.      * the display.
  528.      * \param clear If `true` the array in RAM will be cleared to zeros upon
  529.      * return from this function. If `false` the RAM buffer will remain
  530.      * unchanged. (optional; defaults to `false`)
  531.      *
  532.      * \details
  533.      * The contents of the specified array in RAM is written to the display.
  534.      * Each byte in the array represents a vertical column of 8 pixels with
  535.      * the least significant bit at the top. The bytes are written starting
  536.      * at the top left, progressing horizontally and wrapping at the end of
  537.      * each row, to the bottom right. The size of the array must exactly
  538.      * match the number of pixels in the entire display.
  539.      *
  540.      * If parameter `clear` is set to `true` the RAM array will be cleared to
  541.      * zeros after its contents are written to the display.
  542.      *
  543.      * \see paint8Pixels()
  544.      */
  545.     void static paintScreen(uint8_t image[], bool clear = false);
  546.  
  547.     /** \brief
  548.      * Blank the display screen by setting all pixels off.
  549.      *
  550.      * \details
  551.      * All pixels on the screen will be written with a value of 0 to turn
  552.      * them off.
  553.      */
  554.     void static blank();
  555.  
  556.     /** \brief
  557.      * Invert the entire display or set it back to normal.
  558.      *
  559.      * \param inverse `true` will invert the display. `false` will set the
  560.      * display to no-inverted.
  561.      *
  562.      * \details
  563.      * Calling this function with a value of `true` will set the display to
  564.      * inverted mode. A pixel with a value of 0 will be on and a pixel set to 1
  565.      * will be off.
  566.      *
  567.      * Once in inverted mode, the display will remain this way
  568.      * until it is set back to non-inverted mode by calling this function with
  569.      * `false`.
  570.      */
  571.     void static invert(bool inverse);
  572.  
  573.     /** \brief
  574.      * Turn all display pixels on or display the buffer contents.
  575.      *
  576.      * \param on `true` turns all pixels on. `false` displays the contents
  577.      * of the hardware display buffer.
  578.      *
  579.      * \details
  580.      * Calling this function with a value of `true` will override the contents
  581.      * of the hardware display buffer and turn all pixels on. The contents of
  582.      * the hardware buffer will remain unchanged.
  583.      *
  584.      * Calling this function with a value of `false` will set the normal state
  585.      * of displaying the contents of the hardware display buffer.
  586.      *
  587.      * \note
  588.      * All pixels will be lit even if the display is in inverted mode.
  589.      *
  590.      * \see invert()
  591.      */
  592.     void static allPixelsOn(bool on);
  593.  
  594.     /** \brief
  595.      * Flip the display vertically or set it back to normal.
  596.      *
  597.      * \param flipped `true` will set vertical flip mode. `false` will set
  598.      * normal vertical orientation.
  599.      *
  600.      * \details
  601.      * Calling this function with a value of `true` will cause the Y coordinate
  602.      * to start at the bottom edge of the display instead of the top,
  603.      * effectively flipping the display vertically.
  604.      *
  605.      * Once in vertical flip mode, it will remain this way until normal
  606.      * vertical mode is set by calling this function with a value of `false`.
  607.      *
  608.      * \see flipHorizontal()
  609.      */
  610.     void static flipVertical(bool flipped);
  611.  
  612.     /** \brief
  613.      * Flip the display horizontally or set it back to normal.
  614.      *
  615.      * \param flipped `true` will set horizontal flip mode. `false` will set
  616.      * normal horizontal orientation.
  617.      *
  618.      * \details
  619.      * Calling this function with a value of `true` will cause the X coordinate
  620.      * to start at the left edge of the display instead of the right,
  621.      * effectively flipping the display horizontally.
  622.      *
  623.      * Once in horizontal flip mode, it will remain this way until normal
  624.      * horizontal mode is set by calling this function with a value of `false`.
  625.      *
  626.      * \see flipVertical()
  627.      */
  628.     void static flipHorizontal(bool flipped);
  629.  
  630.     /** \brief
  631.      * Send a single command byte to the display.
  632.      *
  633.      * \param command The command byte to send to the display.
  634.      *
  635.      * \details
  636.      * The display will be set to command mode then the specified command
  637.      * byte will be sent. The display will then be set to data mode.
  638.      * Multi-byte commands can be sent by calling this function multiple times.
  639.      *
  640.      * \note
  641.      * Sending improper commands to the display can place it into invalid or
  642.      * unexpected states, possibly even causing physical damage.
  643.      */
  644.     void static sendLCDCommand(uint8_t command);
  645.  
  646.     /** \brief
  647.      * Set the light output of the RGB LED.
  648.      *
  649.      * \param red,green,blue The brightness value for each LED.
  650.      *
  651.      * \details
  652.      * The RGB LED is actually individual red, green and blue LEDs placed
  653.      * very close together in a single package. By setting the brightness of
  654.      * each LED, the RGB LED can show various colors and intensities.
  655.      * The brightness of each LED can be set to a value from 0 (fully off)
  656.      * to 255 (fully on).
  657.      *
  658.      * \note
  659.      * \parblock
  660.      * Certain libraries that take control of the hardware timers may interfere
  661.      * with the ability of this function to properly control the RGB LED.
  662.      *_ArduboyPlaytune_ is one such library known to do this.
  663.      * The digitalWriteRGB() function will still work properly in this case.
  664.      * \endparblock
  665.      *
  666.      * \note
  667.      * \parblock
  668.      * Many of the Kickstarter Arduboys were accidentally shipped with the
  669.      * RGB LED installed incorrectly. For these units, the green LED cannot be
  670.      * lit. As long as the green led is set to off, setting the red LED will
  671.      * actually control the blue LED and setting the blue LED will actually
  672.      * control the red LED. If the green LED is turned fully on, none of the
  673.      * LEDs will light.
  674.      * \endparblock
  675.      *
  676.      * \see setRGBled(uint8_t, uint8_t) digitalWriteRGB() freeRGBled()
  677.      */
  678.     void static setRGBled(uint8_t red, uint8_t green, uint8_t blue);
  679.  
  680.     /** \brief
  681.      * Set the brightness of one of the RGB LEDs without affecting the others.
  682.      *
  683.      * \param color The name of the LED to set. The value given should be one
  684.      * of RED_LED, GREEN_LED or BLUE_LED.
  685.      *
  686.      * \param val The brightness value for the LED, from 0 to 255.
  687.      *
  688.      * \note
  689.      * In order to use this function, the 3 parameter version must first be
  690.      * called at least once, in order to initialize the hardware.
  691.      *
  692.      * \details
  693.      * This 2 parameter version of the function will set the brightness of a
  694.      * single LED within the RGB LED without affecting the current brightness
  695.      * of the other two. See the description of the 3 parameter version of this
  696.      * function for more details on the RGB LED.
  697.      *
  698.      * \see setRGBled(uint8_t, uint8_t, uint8_t) digitalWriteRGB() freeRGBled()
  699.      */
  700.     void static setRGBled(uint8_t color, uint8_t val);
  701.  
  702.  
  703.     /** \brief
  704.      * Relinquish analog control of the RGB LED.
  705.      *
  706.      * \details
  707.      * Using the RGB LED in analog mode prevents further use of the LED in
  708.      * digital mode. This function will restore the pins used for the LED, so
  709.      * it can be used in digital mode.
  710.      *
  711.      * \see digitalWriteRGB() setRGBled()
  712.      */
  713.     void static freeRGBled();
  714.  
  715.     /** \brief
  716.      * Set the RGB LEDs digitally, to either fully on or fully off.
  717.      *
  718.      * \param red,green,blue Use value RGB_ON or RGB_OFF to set each LED.
  719.      *
  720.      * \details
  721.      * The RGB LED is actually individual red, green and blue LEDs placed
  722.      * very close together in a single package. This 3 parameter version of the
  723.      * function will set each LED either on or off, to set the RGB LED to
  724.      * 7 different colors at their highest brightness or turn it off.
  725.      *
  726.      * The colors are as follows:
  727.      *
  728.      *     RED LED   GREEN_LED   BLUE_LED   COLOR
  729.      *     -------   ---------  --------    -----
  730.      *     RGB_OFF    RGB_OFF    RGB_OFF    OFF
  731.      *     RGB_OFF    RGB_OFF    RGB_ON     Blue
  732.      *     RGB_OFF    RGB_ON     RGB_OFF    Green
  733.      *     RGB_OFF    RGB_ON     RGB_ON     Cyan
  734.      *     RGB_ON     RGB_OFF    RGB_OFF    Red
  735.      *     RGB_ON     RGB_OFF    RGB_ON     Magenta
  736.      *     RGB_ON     RGB_ON     RGB_OFF    Yellow
  737.      *     RGB_ON     RGB_ON     RGB_ON     White
  738.      *
  739.      * \note
  740.      * \parblock
  741.      * Using the RGB LED in analog mode will prevent digital control of the
  742.      * LED. To restore the ability to control the LED digitally, use the
  743.      * `freeRGBled()` function.
  744.      * \endparblock
  745.      *
  746.      * \note
  747.      * \parblock
  748.      * Many of the Kickstarter Arduboys were accidentally shipped with the
  749.      * RGB LED installed incorrectly. For these units, the green LED cannot be
  750.      * lit. As long as the green led is set to off, turning on the red LED will
  751.      * actually light the blue LED and turning on the blue LED will actually
  752.      * light the red LED. If the green LED is turned on, none of the LEDs
  753.      * will light.
  754.      * \endparblock
  755.      *
  756.      * \see digitalWriteRGB(uint8_t, uint8_t) setRGBled() freeRGBled()
  757.      */
  758.     void static digitalWriteRGB(uint8_t red, uint8_t green, uint8_t blue);
  759.  
  760.     /** \brief
  761.      * Set one of the RGB LEDs digitally, to either fully on or fully off.
  762.      *
  763.      * \param color The name of the LED to set. The value given should be one
  764.      * of RED_LED, GREEN_LED or BLUE_LED.
  765.      *
  766.      * \param val Indicates whether to turn the specified LED on or off.
  767.      * The value given should be RGB_ON or RGB_OFF.
  768.      *
  769.      * \details
  770.      * This 2 parameter version of the function will set a single LED within
  771.      * the RGB LED either fully on or fully off. See the description of the
  772.      * 3 parameter version of this function for more details on the RGB LED.
  773.      *
  774.      * \see digitalWriteRGB(uint8_t, uint8_t, uint8_t) setRGBled() freeRGBled()
  775.      */
  776.     void static digitalWriteRGB(uint8_t color, uint8_t val);
  777.  
  778.     /** \brief
  779.      * Initialize the Arduboy's hardware.
  780.      *
  781.      * \details
  782.      * This function initializes the display, buttons, etc.
  783.      *
  784.      * This function is called by begin() so isn't normally called within a
  785.      * sketch. However, in order to free up some code space, by eliminating
  786.      * some of the start up features, it can be called in place of begin().
  787.      * The functions that begin() would call after boot() can then be called
  788.      * to add back in some of the start up features, if desired.
  789.      * See the README file or documentation on the main page for more details.
  790.      *
  791.      * \see Arduboy2Base::begin()
  792.      */
  793.     void static boot();
  794.  
  795.     /** \brief
  796.      * Allow upload when the bootloader "magic number" could be corrupted.
  797.      *
  798.      * \details
  799.      * If the UP button is held when this function is entered, the RGB LED
  800.      * will be lit and timer 0 will be disabled, then the sketch will remain
  801.      * in a tight loop. This is to address a problem with uploading a new
  802.      * sketch, for sketches that interfere with the bootloader "magic number".
  803.      * The problem occurs with certain sketches that use large amounts of RAM.
  804.      *
  805.      * This function should be called after `boot()` in sketches that
  806.      * potentially could cause the problem.
  807.      *
  808.      * It is intended to replace the `flashlight()` function when more
  809.      * program space is required. If possible, it is more desirable to use
  810.      * `flashlight()`, so that the actual flashlight feature isn't lost.
  811.      *
  812.      * \see Arduboy2Base::flashlight() boot()
  813.      */
  814.     void static safeMode();
  815.  
  816.     /** \brief
  817.      * Delay for the number of milliseconds, specified as a 16 bit value.
  818.      *
  819.      * \param ms The delay in milliseconds.
  820.      *
  821.      * \details
  822.      * This function works the same as the Arduino `delay()` function except
  823.      * the provided value is 16 bits long, so the maximum delay allowed is
  824.      * 65535 milliseconds (about 65.5 seconds). Using this function instead
  825.      * of Arduino `delay()` will save a few bytes of code.
  826.      */
  827.     void static delayShort(uint16_t ms) __attribute__ ((noinline));
  828.  
  829.     /** \brief
  830.      * Exit the sketch and start the bootloader
  831.      *
  832.      * \details
  833.      * The sketch will exit and the bootloader will be started in command mode.
  834.      * The effect will be similar to pressing the reset button.
  835.      *
  836.      * This function is intended to be used to allow uploading a new sketch,
  837.      * when the USB code has been removed to gain more code space.
  838.      * Ideally, the sketch would present a "New Sketch Upload" menu or prompt
  839.      * telling the user to "Press and hold the DOWN button when the procedure
  840.      * to upload a new sketch has been initiated". The sketch would then wait
  841.      * for the DOWN button to be pressed and then call this function.
  842.      *
  843.      * \see ARDUBOY_NO_USB
  844.      */
  845.     void static exitToBootloader();
  846.  
  847.     // Replacement main() that eliminates the USB stack code.
  848.     // Used by the ARDUBOY_NO_USB macro. This should not be called
  849.     // directly from a sketch.
  850.     void static mainNoUSB();
  851.  
  852.   protected:
  853.     // internals
  854.     void static setCPUSpeed8MHz();
  855.     void static bootSPI();
  856.     void static bootOLED();
  857.     void static bootPins();
  858.     void static bootPowerSaving();
  859. };
  860.  
  861. #endif
Advertisement
RAW Paste Data Copied
Advertisement