Merge c962257488 into 4ff6973a4b

README.md

@@ -51,7 +51,7 @@ For developers who wish to quickly begin testing, or impatient users who want to
 
 ### "Flashlight" mode
 
-If the *UP* button is pressed and held when the Arduboy is powered on, it enters *flashlight* mode. This turns the RGB LED fully on, and all the pixels of the screen are lit, resulting in a bright white light suitable as a small flashlight. (For an incorrect RGB LED, only the screen will light). To exit *flashlight* mode, press the *DOWN* button to continue with the sketch.
+If the *UP* button is pressed and held when the Arduboy is powered on, it enters *flashlight* mode. This turns the RGB LED fully on, and all the pixels of the screen are lit, resulting in a bright white light suitable as a small flashlight. (For an incorrect RGB LED, only the screen will light). To exit *flashlight* mode the Arduboy must be restarted.
 
 *Flashlight* mode is also sometimes useful to allow uploading of new sketches, in case the sketch currently loaded uses a large amount of RAM which creates a bootloader problem.
 
@@ -209,6 +209,11 @@ For example: Let's say a sketch has its own code to enable, disable and save the
 
 This saves whatever code *blank()*, *systemButtons()* and *bootLogo()* would use.
 
+There are a few functions provided that are roughly equivalent to the standard functions used by *begin()* but which use less code space.
+
+- *bootLogoText()* can be used in place *bootLogo()* in the case where the sketch uses text functions. It renders the logo as text instead of as a bitmap (so doesn't look as good).
+- *safeMode()* can be used in place of *flashlight()* for cases where it's needed to allow uploading a new sketch when the bootloader "magic key" problem is an issue. It only lights the red RGB LED, so you don't get the bright light that is the primary purpose of *flashlight()*.
+
 ----------
 
 ## What's different from Arduboy library V1.1

examples/SetNameAndID/SetNameAndID.ino

@@ -14,7 +14,7 @@
   ----------------------------------------------------------------------------
 */
 
-// Version 1.0
+// Version 2.0
 
 /*
 ------------------------------------------------------------------------------
@@ -61,14 +61,20 @@ EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 // All the constant stings
 const char StrName[] PROGMEM = "NAME";
 const char StrID[] PROGMEM = "ID";
+const char StrYes[] PROGMEM = "YES";
+const char StrNo[] PROGMEM = "NO";
 const char StrSaveQ[] PROGMEM = "SAVE?";
+const char StrSaved[] PROGMEM = "SAVED";
+const char StrShowNameQ1[] PROGMEM = "Show Unit Name";
+const char StrShowNameQ2[] PROGMEM = "on logo screen?";
 const char StrBtnChangeName[] PROGMEM = "UP:change Unit Name";
 const char StrBtnChangeID[] PROGMEM = "DOWN:change Unit ID";
+const char StrBtnShowName[] PROGMEM = "LEFT:set \"show name\"";
 const char StrBtnMenu[] PROGMEM = "A:menu";
 const char StrBtnSave[] PROGMEM = "B:save";
 const char StrBtnYes[] PROGMEM = "A:yes";
 const char StrBtnNo[] PROGMEM = "B:no";
-const char StrBtnLogo[] PROGMEM = "LEFT:show boot logo";
+const char StrBtnTestLogo[] PROGMEM = "DOWN:test boot logo";
 const char StrHex[] PROGMEM = "hex";
 const char StrDecimal[] PROGMEM = "decimal";
 
@@ -91,8 +97,8 @@ const char StrDecimal[] PROGMEM = "decimal";
 #define MENU_ID_DECIMAL_X (centerStrLen(5) + (WIDTH / 4)) 
 #define MENU_ID_Y (MENU_HEADINGS_Y + CHAR_HEIGHT + 1)
 
-#define MENU_BTN_LOGO_X 0
+#define MENU_BTN_SHOW_NAME_X 0
-#define MENU_BTN_LOGO_Y 56
+#define MENU_BTN_SHOW_NAME_Y 56
 
 
 #define NAME_TITLE_X centerStr_P(StrName)
@@ -151,13 +157,32 @@ const char StrDecimal[] PROGMEM = "decimal";
 #define ID_SAVE_X (ID_SAVE_Q_X + ((strlen_P(StrSaveQ) * CHAR_WIDTH) + CHAR_WIDTH))
 #define ID_SAVE_Y (ID_LARGE_Y + 1)
 
+#define SHOW_NAME_BTN_MENU_X 0
+#define SHOW_NAME_BTN_MENU_Y 0
+#define SHOW_NAME_BTN_SAVE_X rightStr_P(StrBtnSave)
+#define SHOW_NAME_BTN_SAVE_Y SHOW_NAME_BTN_MENU_Y
+#define SHOW_NAME_Q_1_X centerStr_P(StrShowNameQ1)
+#define SHOW_NAME_Q_1_Y 12
+#define SHOW_NAME_Q_2_X centerStr_P(StrShowNameQ2)
+#define SHOW_NAME_Q_2_Y (SHOW_NAME_Q_1_Y + 8)
+#define SHOW_NAME_YES_X ((WIDTH / 2) - ((strlen_P(StrYes) + 1) * CHAR_WIDTH * 2))
+#define SHOW_NAME_YES_Y 34
+#define SHOW_NAME_NO_X ((WIDTH / 2) + (CHAR_WIDTH * 2))
+#define SHOW_NAME_NO_Y SHOW_NAME_YES_Y
+#define SHOW_NAME_TEST_X 0
+#define SHOW_NAME_TEST_Y 56
+#define SHOW_NAME_SAVED_X centerStr2_P(StrSaved)
+#define SHOW_NAME_SAVED_Y ((HEIGHT / 2) - CHAR_HEIGHT)
+
 // Calculation of the number of frames to wait before button auto-repeat starts
 #define DELAY_FRAMES (REPEAT_DELAY / (1000 / FRAME_RATE))
 
 // The Arduino "magic" has trouble creating prototypes for functions called
 // by pointers, so they're declared here manually
-void stateMain(), stateName(), stateID(), stateSaveName(), stateSaveID();
+void stateMain(), stateName(), stateID(), stateShowName();
-void screenMain(), screenName(), screenID(), screenSaveName(), screenSaveID();
+void stateSaveName(), stateSaveID();
+void screenMain(), screenName(), screenID(), screenShowName();
+void screenSaveName(), screenSaveID();
 
 Arduboy2 arduboy;
 
@@ -167,11 +192,14 @@ byte nameIndex;
 uint16_t unitID;
 byte idIndex;
 
+boolean showNameFlag;
+
 // Assign numbers for each state/screen
 enum State : byte {
   sMain,
   sName,
   sID,
+  sShowName,
   sSaveName,
   sSaveID,
   sMAX = sSaveID
@@ -184,6 +212,7 @@ void (*stateFunc[sMAX + 1])() = {
   stateMain,
   stateName,
   stateID,
+  stateShowName,
   stateSaveName,
   stateSaveID
 };
@@ -193,6 +222,7 @@ void (*screenFunc[sMAX + 1])() = {
   screenMain,
   screenName,
   screenID,
+  screenShowName,
   screenSaveName,
   screenSaveID
 };
@@ -246,9 +276,7 @@ void stateMain() {
     setState(sID);
   }
   else if (arduboy.justPressed(LEFT_BUTTON)) {
-    arduboy.bootLogo();
+    setState(sShowName);
-    delay(1000);
-    setState(sMain);
   }
 }
 
@@ -322,6 +350,29 @@ void stateID() {
   }
 }
 
+// STATE: Set "Show Unit Name" flag
+void stateShowName() {
+  if (arduboy.justPressed(RIGHT_BUTTON)) {
+    showNameToggle();
+  }
+  else if (arduboy.justPressed(LEFT_BUTTON)) {
+    showNameToggle();
+  }
+  else if (arduboy.justPressed(A_BUTTON)) {
+    setState(sMain);
+  }
+  else if (arduboy.justPressed(B_BUTTON)) {
+    saveShowName();
+    setState(sShowName);
+  }
+  else if (arduboy.justPressed(DOWN_BUTTON)) {
+    showNameFlag = arduboy.readShowUnitNameFlag();
+    arduboy.bootLogo();
+    delay(1000);
+    setState(sShowName);
+  }
+}
+
 // STATE: Prompt to save the unit name
 void stateSaveName() {
   if (arduboy.justPressed(A_BUTTON)) {
@@ -367,7 +418,7 @@ void screenMain() {
   printIDHex(MENU_ID_HEX_X, MENU_ID_Y);
   printIDDecimal(MENU_ID_DECIMAL_X, MENU_ID_Y);
 
-  printStr_P(MENU_BTN_LOGO_X, MENU_BTN_LOGO_Y, StrBtnLogo);
+  printStr_P(MENU_BTN_SHOW_NAME_X, MENU_BTN_SHOW_NAME_Y, StrBtnShowName);
 }
 
 // DISPLAY: Change unit name
@@ -389,6 +440,20 @@ void screenID() {
   printIDCursors();
 }
 
+// DISPLAY: Set "Show Unit Name" flag
+void screenShowName() {
+  printStr_P(SHOW_NAME_BTN_MENU_X, SHOW_NAME_BTN_MENU_Y, StrBtnMenu);
+  printStr_P(SHOW_NAME_BTN_SAVE_X, SHOW_NAME_BTN_SAVE_Y, StrBtnSave);
+  printStr_P(SHOW_NAME_Q_1_X, SHOW_NAME_Q_1_Y, StrShowNameQ1);
+  printStr_P(SHOW_NAME_Q_2_X, SHOW_NAME_Q_2_Y, StrShowNameQ2);
+  arduboy.setTextSize(2);
+  printStr_P(SHOW_NAME_YES_X, SHOW_NAME_YES_Y, StrYes);
+  printStr_P(SHOW_NAME_NO_X, SHOW_NAME_NO_Y, StrNo);
+  arduboy.setTextSize(1);
+  printShowNameCursor();
+  printStr_P(SHOW_NAME_TEST_X, SHOW_NAME_TEST_Y, StrBtnTestLogo);
+}
+
 // DISPLAY: Prompt to save the unit name
 void screenSaveName() {
   printNameScreenCommon();
@@ -407,6 +472,21 @@ void screenSaveID() {
   printIDLarge(ID_SAVE_X, ID_SAVE_Y);
 }
 
+// Save the "Show Unit Name" flag and overlay the "SAVED" message on the screen
+void saveShowName() {
+  arduboy.writeShowUnitNameFlag(showNameFlag);
+  arduboy.fillRect(SHOW_NAME_SAVED_X - 4, SHOW_NAME_SAVED_Y - 4,
+                   strlen_P(StrSaved) * CHAR_WIDTH * 2 + 6, CHAR_HEIGHT * 2 + 6);
+  arduboy.setTextColor(BLACK);
+  arduboy.setTextBackground(WHITE);
+  arduboy.setTextSize(2);
+  printStr_P(SHOW_NAME_SAVED_X, SHOW_NAME_SAVED_Y, StrSaved);
+  arduboy.setTextSize(1);
+  arduboy.setTextColor(WHITE);
+  arduboy.setTextBackground(BLACK);
+  arduboy.display();
+  delay(1000);
+}
 
 // --------------------- Printing Functions ------------------------------
 
@@ -458,6 +538,18 @@ void printIDCursors() {
                         ID_BINARY_Y + CHAR_HEIGHT + 1, CHAR_WIDTH * 4 - 1);
 }
 
+// Print the current "Show Unit Name" cursor
+void printShowNameCursor() {
+  if (showNameFlag) {
+    arduboy.fillRect(SHOW_NAME_YES_X, SHOW_NAME_YES_Y + (CHAR_HEIGHT * 2),
+                     (strlen_P(StrYes) * CHAR_WIDTH - 1) * 2, 2);
+  }
+  else {
+    arduboy.fillRect(SHOW_NAME_NO_X, SHOW_NAME_NO_Y + (CHAR_HEIGHT * 2),
+                     (strlen_P(StrNo) * CHAR_WIDTH - 1) * 2, 2);
+  }
+}
+
 // Print the unit name in normal size including an extent underline
 // at the given location
 void printName(int x, int y) {
@@ -621,11 +713,12 @@ void printBinaryNybble(int x, int y, byte val) {
 
 // ---------------- Control and Utility Functions ------------------------
 
-// Get the current unit name and ID from EEPROM
+// Get the current unit name and ID, and the "Show Unit Name" flag, from EEPROM
 void readEEPROM() {
   memset(unitName, 0, sizeof(unitName));
   arduboy.readUnitName(unitName);
   unitID = arduboy.readUnitID();
+  showNameFlag = arduboy.readShowUnitNameFlag();
 }
 
 // Increment the name character at the cursor position
@@ -701,6 +794,12 @@ void idCursorLeft() {
   drawScreen();
 }
 
+// Toggle the "Show Unit Name" selection
+void showNameToggle() {
+  showNameFlag = !showNameFlag;
+  drawScreen();
+}
+
 // Start the button auto-repeat delay
 void startButtonDelay() {
   delayCount = DELAY_FRAMES;
@@ -723,6 +822,12 @@ int centerStr_P(const char* str) {
   return (WIDTH / 2) - (strlen_P(str) * CHAR_WIDTH / 2);
 }
 
+// Calculate the X coordinate to center a size 2 string located in
+// program memory
+int centerStr2_P(const char* str) {
+  return (WIDTH / 2) - (strlen_P(str) * CHAR_WIDTH);
+}
+
 // Calculate the X coordinate to right justify a string in program memory
 int rightStr_P(const char* str) {
   return WIDTH - (strlen_P(str) * CHAR_WIDTH) + 1;

keywords.txt

@@ -19,6 +19,7 @@ begin	KEYWORD2
 blank	KEYWORD2
 boot	KEYWORD2
 bootLogo	KEYWORD2
+bootLogoText	KEYWORD2
 buttonsState	KEYWORD2
 clear	KEYWORD2
 collide	KEYWORD2
@@ -65,8 +66,10 @@ paint8Pixels	KEYWORD2
 paintScreen	KEYWORD2
 pollButtons	KEYWORD2
 pressed	KEYWORD2
+readShowUnitNameFlag	KEYWORD2
 readUnitID	KEYWORD2
 readUnitName	KEYWORD2
+safeMode	KEYWORD2
 saveOnOff	KEYWORD2
 setCursor	KEYWORD2
 setFrameRate	KEYWORD2
@@ -75,9 +78,11 @@ setTextColor	KEYWORD2
 setTextBackground	KEYWORD2
 setTextSize	KEYWORD2
 setTextWrap	KEYWORD2
+SPItransfer	KEYWORD2
 systemButtons	KEYWORD2
 toggle	KEYWORD2
 width	KEYWORD2
+writeShowUnitNameFlag	KEYWORD2
 writeUnitID	KEYWORD2
 writeUnitName	KEYWORD2
 

src/Arduboy2.cpp

@@ -61,41 +61,47 @@ void Arduboy2Base::flashlight()
   sendLCDCommand(OLED_ALL_PIXELS_ON); // smaller than allPixelsOn()
   digitalWriteRGB(RGB_ON, RGB_ON, RGB_ON);
 
-  while (!pressed(DOWN_BUTTON)) {
+  // prevent the bootloader magic number from being overwritten by timer 0
+  // when a timer variable overlaps the magic number location, for when
+  // flashlight mode is used for upload problem recovery
+  power_timer0_disable();
+
+  while (true) {
     idle();
   }
-
-  digitalWriteRGB(RGB_OFF, RGB_OFF, RGB_OFF);
-  sendLCDCommand(OLED_PIXELS_FROM_RAM);
 }
 
-void Arduboy2Base::systemButtons() {
+void Arduboy2Base::systemButtons()
+{
   while (pressed(B_BUTTON)) {
-    digitalWrite(BLUE_LED, RGB_ON); // turn on blue LED
+    digitalWriteRGB(BLUE_LED, RGB_ON); // turn on blue LED
     sysCtrlSound(UP_BUTTON + B_BUTTON, GREEN_LED, 0xff);
     sysCtrlSound(DOWN_BUTTON + B_BUTTON, RED_LED, 0);
     delay(200);
   }
 
-  digitalWrite(BLUE_LED, RGB_OFF); // turn off blue LED
+  digitalWriteRGB(BLUE_LED, RGB_OFF); // turn off blue LED
 }
 
-void Arduboy2Base::sysCtrlSound(uint8_t buttons, uint8_t led, uint8_t eeVal) {
+void Arduboy2Base::sysCtrlSound(uint8_t buttons, uint8_t led, uint8_t eeVal)
+{
   if (pressed(buttons)) {
-    digitalWrite(BLUE_LED, RGB_OFF); // turn off blue LED
+    digitalWriteRGB(BLUE_LED, RGB_OFF); // turn off blue LED
     delay(200);
-    digitalWrite(led, RGB_ON); // turn on "acknowledge" LED
+    digitalWriteRGB(led, RGB_ON); // turn on "acknowledge" LED
     EEPROM.update(EEPROM_AUDIO_ON_OFF, eeVal);
     delay(500);
-    digitalWrite(led, RGB_OFF); // turn off "acknowledge" LED
+    digitalWriteRGB(led, RGB_OFF); // turn off "acknowledge" LED
 
     while (pressed(buttons)) {} // Wait for button release
   }
 }
 
+// bootLogoText() should be kept in sync with bootLogo()
+// if changes are made to one, equivalent changes should be made to the other
 void Arduboy2Base::bootLogo()
 {
-  digitalWrite(RED_LED, RGB_ON);
+  digitalWriteRGB(RED_LED, RGB_ON);
 
   for (int8_t y = -18; y <= 24; y++) {
     if (pressed(RIGHT_BUTTON)) {
@@ -104,10 +110,12 @@ void Arduboy2Base::bootLogo()
     }
 
     if (y == -4) {
-      digitalWriteRGB(RGB_OFF, RGB_ON, RGB_OFF); // green LED on
+      digitalWriteRGB(RED_LED, RGB_OFF);    // red LED off
+      digitalWriteRGB(GREEN_LED, RGB_ON);   // green LED on
     }
     else if (y == 24) {
-      digitalWriteRGB(RGB_OFF, RGB_OFF, RGB_ON); // blue LED on
+      digitalWriteRGB(GREEN_LED, RGB_OFF);  // green LED off
+      digitalWriteRGB(BLUE_LED, RGB_ON);    // blue LED on
     }
 
     clear();
@@ -122,7 +130,7 @@ void Arduboy2Base::bootLogo()
   }
 
   delay(750);
-  digitalWrite(BLUE_LED, RGB_OFF);
+  digitalWriteRGB(BLUE_LED, RGB_OFF);
 
   bootLogoExtra();
 }
@@ -189,25 +197,16 @@ int Arduboy2Base::cpuLoad()
 void Arduboy2Base::initRandomSeed()
 {
   power_adc_enable(); // ADC on
-  randomSeed(~rawADC(ADC_TEMP) * ~rawADC(ADC_VOLTAGE) * ~micros() + micros());
+
+  // do an ADC read from an unconnected input pin
+  ADCSRA |= _BV(ADSC); // start conversion (ADMUX has been pre-set in boot())
+  while (bit_is_set(ADCSRA, ADSC)) { } // wait for conversion complete
+
+  randomSeed(((unsigned long)ADC << 16) + micros());
+
   power_adc_disable(); // ADC off
 }
 
-uint16_t Arduboy2Base::rawADC(uint8_t adc_bits)
-{
-  ADMUX = adc_bits;
-  // we also need MUX5 for temperature check
-  if (adc_bits == ADC_TEMP) {
-    ADCSRB = _BV(MUX5);
-  }
-
-  delay(2); // Wait for ADMUX setting to settle
-  ADCSRA |= _BV(ADSC); // Start conversion
-  while (bit_is_set(ADCSRA,ADSC)); // measuring
-
-  return ADC;
-}
-
 /* Graphics */
 
 void Arduboy2Base::clear()
@@ -975,6 +974,19 @@ void Arduboy2Base::writeUnitName(char* name)
   }
 }
 
+bool Arduboy2Base::readShowUnitNameFlag()
+{
+  return (EEPROM.read(EEPROM_SYS_FLAGS) & SYS_FLAG_UNAME_MASK);
+}
+
+void Arduboy2Base::writeShowUnitNameFlag(bool val)
+{
+  uint8_t flags = EEPROM.read(EEPROM_SYS_FLAGS);
+
+  bitWrite(flags, SYS_FLAG_UNAME, val);
+  EEPROM.update(EEPROM_SYS_FLAGS, flags);
+}
+
 void Arduboy2Base::swap(int16_t& a, int16_t& b)
 {
   int16_t temp = a;
@@ -997,9 +1009,60 @@ Arduboy2::Arduboy2()
   textWrap = 0;
 }
 
+// bootLogoText() should be kept in sync with bootLogo()
+// if changes are made to one, equivalent changes should be made to the other
+void Arduboy2::bootLogoText()
+{
+  digitalWriteRGB(RED_LED, RGB_ON);
+
+  textSize = 2;
+
+  for (int8_t y = -18; y <= 24; y++) {
+    if (pressed(RIGHT_BUTTON)) {
+      digitalWriteRGB(RGB_OFF, RGB_OFF, RGB_OFF); // all LEDs off
+      textSize = 1;
+      return;
+    }
+
+    if (y == -4) {
+      digitalWriteRGB(RED_LED, RGB_OFF);    // red LED off
+      digitalWriteRGB(GREEN_LED, RGB_ON);   // green LED on
+    }
+    else if (y == 24) {
+      digitalWriteRGB(GREEN_LED, RGB_OFF);  // green LED off
+      digitalWriteRGB(BLUE_LED, RGB_ON);    // blue LED on
+    }
+
+    clear();
+    cursor_x = 23;
+    cursor_y = y;
+    print("ARDUBOY");
+    display();
+    delay(27);
+    // longer delay post boot, we put it inside the loop to
+    // save the flash calling clear/delay again outside the loop
+    if (y==-16) {
+      delay(250);
+    }
+  }
+
+  delay(750);
+  digitalWriteRGB(BLUE_LED, RGB_OFF);
+  textSize = 1;
+
+  bootLogoExtra();
+}
+
 void Arduboy2::bootLogoExtra()
 {
-  uint8_t c = EEPROM.read(EEPROM_UNIT_NAME);
+  uint8_t c;
+
+  if (!readShowUnitNameFlag())
+  {
+    return;
+  }
+
+  c = EEPROM.read(EEPROM_UNIT_NAME);
 
   if (c != 0xFF && c != 0x00)
   {
@@ -1011,10 +1074,11 @@ void Arduboy2::bootLogoExtra()
     {
       write(c);
       c = EEPROM.read(++i);
-    } while (i < EEPROM_UNIT_NAME + ARDUBOY_UNIT_NAME_LEN);
+    }
+    while (i < EEPROM_UNIT_NAME + ARDUBOY_UNIT_NAME_LEN);
 
     display();
-    delay(1500);
+    delay(1000);
   }
 }
 

src/Arduboy2.h

@@ -38,13 +38,17 @@
 #define ARDUBOY_UNIT_NAME_LEN 6 /**< The maximum length of the unit name string. */
 
 #define EEPROM_VERSION 0
-#define EEPROM_BRIGHTNESS 1
+#define EEPROM_SYS_FLAGS 1
 #define EEPROM_AUDIO_ON_OFF 2
 #define EEPROM_UNIT_ID 8    // A uint16_t binary unit ID
 #define EEPROM_UNIT_NAME 10 // An up to 6 character unit name. Cannot contain
                             // 0x00 or 0xFF. Lengths less than 6 are padded
                             // with 0x00
 
+// EEPROM_SYS_FLAGS values
+#define SYS_FLAG_UNAME 0    // Display the unit name on the logo screen
+#define SYS_FLAG_UNAME_MASK _BV(SYS_FLAG_UNAME)
+
 /** \brief
  * Start of EEPROM storage space for sketches.
  *
@@ -78,11 +82,6 @@
 
 #define CLEAR_BUFFER true /**< Value to be passed to `display()` to clear the screen buffer. */
 
-// compare Vcc to 1.1 bandgap
-#define ADC_VOLTAGE (_BV(REFS0) | _BV(MUX4) | _BV(MUX3) | _BV(MUX2) | _BV(MUX1))
-// compare temperature to 2.5 internal reference and _BV(MUX5)
-#define ADC_TEMP (_BV(REFS0) | _BV(REFS1) | _BV(MUX2) | _BV(MUX1) | _BV(MUX0))
-
 
 /** \brief
  * A rectangle object for collision functions.
@@ -195,16 +194,30 @@ class Arduboy2Base : public Arduboy2Core
   void begin();
 
   /** \brief
-   * Flashlight mode turns the RGB LED and display fully on.
+   * Turn the RGB LED and display fully on to act as a small flashlight/torch.
    *
    * \details
    * Checks if the UP button is pressed and if so turns the RGB LED and all
-   * display pixels fully on. Pressing the DOWN button will exit flashlight mode.
+   * display pixels fully on. If the UP button is detected, this function
+   * does not exit. The Arduboy must be restarted after flashlight mode is used.
    *
    * This function is called by `begin()` and can be called by a sketch
    * after `boot()`.
    *
-   * \see begin() boot()
+   * \note
+   * \parblock
+   * This function also contains code to address a problem with uploading a new
+   * sketch, for sketches that interfere with the bootloader "magic number".
+   * This problem occurs with certain sketches that use large amounts of RAM.
+   * Being in flashlight mode when uploading a new sketch can fix this problem.
+   *
+   * Therefore, for sketches that potentially could cause this problem, and use
+   * `boot()` instead of `begin()`, it is recommended that a call to
+   * `flashlight()` be included after calling `boot()`. If program space is
+   * limited, `safeMode()` can be used instead of `flashlight()`.
+   * \endparblock
+   *
+   * \see begin() boot() safeMode()
    */
   void flashlight();
 
@@ -245,7 +258,7 @@ class Arduboy2Base : public Arduboy2Core
    * which derived classes can implement to add additional information to the
    * logo screen. The `Arduboy2` class uses this to display the unit name.
    *
-   * \see begin() boot() Arduboy2::bootLogoExtra()
+   * \see begin() boot() Arduboy2::bootLogoExtra() Arduboy2::bootLogoText()
    */
   void bootLogo();
 
@@ -694,9 +707,6 @@ class Arduboy2Base : public Arduboy2Core
    */
   int cpuLoad();
 
-  // Useful for getting raw approximate voltage values.
-  uint16_t rawADC(uint8_t adc_bits);
-
   /** \brief
    * Test if the specified buttons are pressed.
    *
@@ -945,6 +955,38 @@ class Arduboy2Base : public Arduboy2Core
    */
   void writeUnitName(char* name);
 
+  /** \brief
+   * Read the "Show Unit Name" flag in system EEPROM.
+   *
+   * \return `true` if the flag is set to indicate that the unit name should
+   * be displayed. `false` if the flag is set to not display the unit name.
+   *
+   * \details
+   * The "Show Unit Name" flag is used to determine whether the system
+   * unit name is to be displayed at the end of the boot logo sequence.
+   * This function returns the value of this flag.
+   *
+   * \see writeShowUnitNameFlag() writeUnitName() readUnitName()
+   * Arduboy2::bootLogoExtra()
+   */
+  bool readShowUnitNameFlag();
+
+  /** \brief
+   * Write the "Show Unit Name" flag in system EEPROM.
+   *
+   * \param val If `true` the flag is set to indicate that the unit name should
+   * be displayed. If `false` the flag is set to not display the unit name.
+   *
+   * \details
+   * The "Show Unit Name" flag is used to determine whether the system
+   * unit name is to be displayed at the end of the boot logo sequence.
+   * This function allows the flag to be saved with the desired value.
+   *
+   * \see readShowUnitNameFlag() writeUnitName() readUnitName()
+   * Arduboy2::bootLogoExtra()
+   */
+  void writeShowUnitNameFlag(bool val);
+
   /** \brief
    * A counter which is incremented once per frame.
    *
@@ -1069,21 +1111,44 @@ class Arduboy2 : public Print, public Arduboy2Base
    * \see Arduboy2::write()
    */
 
+  /** \brief
+   * Display the boot logo sequence using printed text instead of a bitmap.
+   *
+   * \details
+   * This function can be called by a sketch after `boot()` as an alternative
+   * to `bootLogo()`.
+   *
+   * The Arduboy logo scrolls down from the top of the screen to the center
+   * while the RGB LEDs light in sequence.
+   *
+   * This function is the same as `bootLogo()` except the logo is printed as
+   * text instead of being rendered as a bitmap. It can be used to save some
+   * code space in a case where the sketch is using the Print class functions
+   * to display text. However, the logo will not look as good when printed as
+   * text as it does with the bitmap used by `bootLogo()`.
+   *
+   * \see bootLogo() boot() Arduboy2::bootLogoExtra()
+   */
+  void bootLogoText();
+
   /** \brief
    * Show the unit name at the bottom of the boot logo screen.
    *
    * \details
-   * This function is called by the `bootLogo()` function.
+   * This function is called by `bootLogo()` and `bootlogoText()`.
    * 
    * If a unit name has been saved in system EEPROM, it will be displayed at
    * the bottom of the screen. This function pauses for a short time to allow
    * the name to be seen.
    *
+   * The name is not displayed if the "Show Unit Name" flag is not set.
+   *
    * \note
    * This function would not normally be called directly from within a sketch
    * itself.
    *
-   * \see readUnitName() writeUnitName() bootLogo() begin()
+   * \see readUnitName() writeUnitName() bootLogo() bootLogoText()
+   *  writeShowUnitNameFlag() begin()
    */
   virtual void bootLogoExtra();
 

src/Arduboy2Audio.cpp

@@ -11,12 +11,12 @@ bool Arduboy2Audio::audio_enabled = false;
 
 void Arduboy2Audio::on()
 {
-  // fire up audio pins
+  // fire up audio pins by seting them as outputs
 #ifdef ARDUBOY_10
-  pinMode(PIN_SPEAKER_1, OUTPUT);
+  bitSet(SPEAKER_1_DDR, SPEAKER_1_BIT);
-  pinMode(PIN_SPEAKER_2, OUTPUT);
+  bitSet(SPEAKER_2_DDR, SPEAKER_2_BIT);
 #else
-  pinMode(PIN_SPEAKER_1, OUTPUT);
+  bitSet(SPEAKER_1_DDR, SPEAKER_1_BIT);
 #endif
   audio_enabled = true;
 }
@@ -24,12 +24,12 @@ void Arduboy2Audio::on()
 void Arduboy2Audio::off()
 {
   audio_enabled = false;
-  // shut off audio pins
+  // shut off audio pins by setting them as inputs
 #ifdef ARDUBOY_10
-  pinMode(PIN_SPEAKER_1, INPUT);
+  bitClear(SPEAKER_1_DDR, SPEAKER_1_BIT);
-  pinMode(PIN_SPEAKER_2, INPUT);
+  bitClear(SPEAKER_2_DDR, SPEAKER_2_BIT);
 #else
-  pinMode(PIN_SPEAKER_1, INPUT);
+  bitClear(SPEAKER_1_DDR, SPEAKER_1_BIT);
 #endif
 }
 
@@ -50,6 +50,8 @@ void Arduboy2Audio::begin()
 {
   if (EEPROM.read(EEPROM_AUDIO_ON_OFF))
     on();
+  else
+    off();
 }
 
 bool Arduboy2Audio::enabled()

src/Arduboy2Core.cpp

@@ -6,40 +6,6 @@
 
 #include "Arduboy2Core.h"
 
-// need to redeclare these here since we declare them static in .h
-volatile uint8_t *Arduboy2Core::csport, *Arduboy2Core::dcport;
-uint8_t Arduboy2Core::cspinmask, Arduboy2Core::dcpinmask;
-
-const uint8_t PROGMEM pinBootProgram[] = {
-  // buttons
-  PIN_LEFT_BUTTON, INPUT_PULLUP,
-  PIN_RIGHT_BUTTON, INPUT_PULLUP,
-  PIN_UP_BUTTON, INPUT_PULLUP,
-  PIN_DOWN_BUTTON, INPUT_PULLUP,
-  PIN_A_BUTTON, INPUT_PULLUP,
-  PIN_B_BUTTON, INPUT_PULLUP,
-
-  // RGB LED (or single blue LED on the DevKit)
-#ifdef ARDUBOY_10
-  RED_LED, INPUT_PULLUP,  // set INPUT_PULLUP to make the pin high when
-  RED_LED, OUTPUT,        //   set to OUTPUT
-  GREEN_LED, INPUT_PULLUP,
-  GREEN_LED, OUTPUT,
-#endif
-  BLUE_LED, INPUT_PULLUP,
-  BLUE_LED, OUTPUT,
-
-  // audio is specifically not included here as those pins are handled
-  // separately by `audio.begin()`, `audio.on()` and `audio.off()` in order
-  // to respect the EEPROM audio settings
-
-  // OLED SPI
-  DC, OUTPUT,
-  CS, OUTPUT,
-  RST, OUTPUT,
-  0
-};
-
 const uint8_t PROGMEM lcdBootProgram[] = {
   // boot defaults are commented out but left here in case they
   // might prove useful for reference
@@ -114,15 +80,11 @@ void Arduboy2Core::boot()
   setCPUSpeed8MHz();
   #endif
 
-  SPI.begin();
+  // Select the ADC input here so a delay isn't required in initRandomSeed()
+  ADMUX = RAND_SEED_IN_ADMUX;
+
   bootPins();
   bootOLED();
-
-  #ifdef SAFE_MODE
-  if (buttonsState() == (LEFT_BUTTON | UP_BUTTON))
-    safeMode();
-  #endif
-
   bootPowerSaving();
 }
 
@@ -143,64 +105,150 @@ void Arduboy2Core::setCPUSpeed8MHz()
 }
 #endif
 
+// Pins are set to the proper modes and levels for the specific hardware.
+// This routine must be modified if any pins are moved to a different port
 void Arduboy2Core::bootPins()
 {
-  uint8_t pin, mode;
+#ifdef ARDUBOY_10
-  const uint8_t *i = pinBootProgram;
 
-  while(true) {
+  // Port B INPUT_PULLUP or HIGH
-    pin = pgm_read_byte(i++);
+  PORTB |= _BV(RED_LED_BIT) | _BV(GREEN_LED_BIT) | _BV(BLUE_LED_BIT) |
-    mode = pgm_read_byte(i++);
+           _BV(B_BUTTON_BIT);
-    if (pin==0) break;
+  // Port B INPUT or LOW (none)
-    pinMode(pin, mode);
+  // Port B inputs
-  }
+  DDRB &= ~(_BV(B_BUTTON_BIT));
+  // Port B outputs
+  DDRB |= _BV(RED_LED_BIT) | _BV(GREEN_LED_BIT) | _BV(BLUE_LED_BIT) |
+          _BV(SPI_MOSI_BIT) | _BV(SPI_SCK_BIT);
 
-  digitalWrite(RST, HIGH);
+  // Port C
-  delay(1);           // VDD (3.3V) goes high at start, lets just chill for a ms
+  // Speaker: Not set here. Controlled by audio class
-  digitalWrite(RST, LOW);   // bring reset low
+
-  delay(10);          // wait 10ms
+  // Port D INPUT_PULLUP or HIGH
-  digitalWrite(RST, HIGH);  // bring out of reset
+  PORTD |= _BV(CS_BIT);
+  // Port D INPUT or LOW
+  PORTD &= ~(_BV(RST_BIT));
+  // Port D inputs (none)
+  // Port D outputs
+  DDRD |= _BV(RST_BIT) | _BV(CS_BIT) | _BV(DC_BIT);
+
+  // Port E INPUT_PULLUP or HIGH
+  PORTE |= _BV(A_BUTTON_BIT);
+  // Port E INPUT or LOW (none)
+  // Port E inputs
+  DDRE &= ~(_BV(A_BUTTON_BIT));
+  // Port E outputs (none)
+
+  // Port F INPUT_PULLUP or HIGH
+  PORTF |= _BV(LEFT_BUTTON_BIT) | _BV(RIGHT_BUTTON_BIT) |
+           _BV(UP_BUTTON_BIT) | _BV(DOWN_BUTTON_BIT);
+  // Port F INPUT or LOW
+  PORTF &= ~(_BV(RAND_SEED_IN_BIT));
+  // Port F inputs
+  DDRF &= ~(_BV(LEFT_BUTTON_BIT) | _BV(RIGHT_BUTTON_BIT) |
+            _BV(UP_BUTTON_BIT) | _BV(DOWN_BUTTON_BIT) |
+            _BV(RAND_SEED_IN_BIT));
+  // Port F outputs (none)
+
+#elif defined(AB_DEVKIT)
+
+  // Port B INPUT_PULLUP or HIGH
+  PORTB |= _BV(LEFT_BUTTON_BIT) | _BV(UP_BUTTON_BIT) | _BV(DOWN_BUTTON_BIT) |
+           _BV(BLUE_LED_BIT);
+  // Port B INPUT or LOW (none)
+  // Port B inputs
+  DDRB &= ~(_BV(LEFT_BUTTON_BIT) | _BV(UP_BUTTON_BIT) | _BV(DOWN_BUTTON_BIT));
+  // Port B outputs
+  DDRB |= _BV(BLUE_LED_BIT) | _BV(SPI_MOSI_BIT) | _BV(SPI_SCK_BIT);
+
+  // Port C INPUT_PULLUP or HIGH
+  PORTE |= _BV(RIGHT_BUTTON_BIT);
+  // Port C INPUT or LOW (none)
+  // Port C inputs
+  DDRE &= ~(_BV(RIGHT_BUTTON_BIT));
+  // Port C outputs (none)
+
+  // Port D INPUT_PULLUP or HIGH
+  PORTD |= _BV(CS_BIT);
+  // Port D INPUT or LOW
+  PORTD &= ~(_BV(RST_BIT));
+  // Port D inputs (none)
+  // Port D outputs
+  DDRD |= _BV(RST_BIT) | _BV(CS_BIT) | _BV(DC_BIT);
+
+  // Port E (none)
+
+  // Port F INPUT_PULLUP or HIGH
+  PORTF |= _BV(A_BUTTON_BIT) | _BV(B_BUTTON_BIT);
+  // Port F INPUT or LOW
+  PORTF &= ~(_BV(RAND_SEED_IN_BIT));
+  // Port F inputs
+  DDRF &= ~(_BV(A_BUTTON_BIT) | _BV(B_BUTTON_BIT) | _BV(RAND_SEED_IN_BIT));
+  // Port F outputs (none)
+  // Speaker: Not set here. Controlled by audio class
+
+#endif
 }
 
 void Arduboy2Core::bootOLED()
 {
-  // setup the ports we need to talk to the OLED
+  // init SPI
-  csport = portOutputRegister(digitalPinToPort(CS));
+  // master, mode 0, MSB first, CPU clock / 2 (8MHz)
-  cspinmask = digitalPinToBitMask(CS);
+  SPCR = _BV(SPE) | _BV(MSTR);
-  dcport = portOutputRegister(digitalPinToPort(DC));
+  SPSR = _BV(SPI2X);
-  dcpinmask = digitalPinToBitMask(DC);
 
-  SPI.setClockDivider(SPI_CLOCK_DIV2);
+  // reset the display
+  delay(2); // reset pin should be low here. let it stay low a while
+  bitSet(RST_PORT, RST_BIT); // set high to come out of reset
+  delay(10); // wait a while
+
+  // select the display (permanently, since nothing else is using SPI)
+  bitClear(CS_PORT, CS_BIT);
 
-  LCDCommandMode();
   // run our customized boot-up command sequence against the
   // OLED to initialize it properly for Arduboy
+  LCDCommandMode();
   for (uint8_t i = 0; i < sizeof(lcdBootProgram); i++) {
-    SPI.transfer(pgm_read_byte(lcdBootProgram + i));
+    SPItransfer(pgm_read_byte(lcdBootProgram + i));
   }
   LCDDataMode();
 }
 
 void Arduboy2Core::LCDDataMode()
 {
-  *dcport |= dcpinmask;
+  bitSet(DC_PORT, DC_BIT);
-  *csport &= ~cspinmask;
 }
 
 void Arduboy2Core::LCDCommandMode()
 {
-  *csport |= cspinmask;
+  bitClear(DC_PORT, DC_BIT);
-  *dcport &= ~dcpinmask;
-  *csport &= ~cspinmask;
 }
 
-
+// Write to the SPI bus (MOSI pin)
+void Arduboy2Core::SPItransfer(uint8_t data)
+{
+  SPDR = data;
+  /*
+   * The following NOP introduces a small delay that can prevent the wait
+   * loop form iterating when running at the maximum speed. This gives
+   * about 10% more speed, even if it seems counter-intuitive. At lower
+   * speeds it is unnoticed.
+   */
+  asm volatile("nop");
+  while (!(SPSR & _BV(SPIF))) { } // wait
+}
 
 void Arduboy2Core::safeMode()
 {
-  blank(); // too avoid random gibberish
+  if (buttonsState() == UP_BUTTON)
-  while (true) {
+  {
-    asm volatile("nop \n");
+    digitalWriteRGB(RED_LED, RGB_ON);
+
+    // prevent the bootloader magic number from being overwritten by timer 0
+    // when a timer variable overlaps the magic number location
+    power_timer0_disable();
+
+    while (true) { }
   }
 }
 
@@ -215,15 +263,11 @@ void Arduboy2Core::idle()
 
 void Arduboy2Core::bootPowerSaving()
 {
-  power_adc_disable();
+  // disable Two Wire Interface (I2C) and the ADC
-  power_usart0_disable();
+  PRR0 = _BV(PRTWI) | _BV(PRADC);
-  power_twi_disable();
+  // disable USART1
-  // timer 0 is for millis()
+  PRR1 = _BV(PRUSART1);
-  // timers 1 and 3 are for music and sounds
+  // All other bits will be written with 0 so will be enabled
-  power_timer2_disable();
-  power_usart1_disable();
-  // we need USB, for now (to allow triggered reboots to reprogram)
-  // power_usb_disable()
 }
 
 uint8_t Arduboy2Core::width() { return WIDTH; }
@@ -235,14 +279,14 @@ uint8_t Arduboy2Core::height() { return HEIGHT; }
 
 void Arduboy2Core::paint8Pixels(uint8_t pixels)
 {
-  SPI.transfer(pixels);
+  SPItransfer(pixels);
 }
 
 void Arduboy2Core::paintScreen(const uint8_t *image)
 {
   for (int i = 0; i < (HEIGHT*WIDTH)/8; i++)
   {
-    SPI.transfer(pgm_read_byte(image + i));
+    SPItransfer(pgm_read_byte(image + i));
   }
 }
 
@@ -288,13 +332,13 @@ void Arduboy2Core::paintScreen(uint8_t image[], bool clear)
 void Arduboy2Core::blank()
 {
   for (int i = 0; i < (HEIGHT*WIDTH)/8; i++)
-    SPI.transfer(0x00);
+    SPItransfer(0x00);
 }
 
 void Arduboy2Core::sendLCDCommand(uint8_t command)
 {
   LCDCommandMode();
-  SPI.transfer(command);
+  SPItransfer(command);
   LCDDataMode();
 }
 
@@ -334,19 +378,48 @@ void Arduboy2Core::setRGBled(uint8_t red, uint8_t green, uint8_t blue)
   analogWrite(GREEN_LED, 255 - green);
   analogWrite(BLUE_LED, 255 - blue);
 #elif defined(AB_DEVKIT)
-  // only blue on devkit
+  // only blue on DevKit, which is not PWM capable
-  digitalWrite(BLUE_LED, ~blue);
+  (void)red;    // parameter unused
+  (void)green;  // parameter unused
+  bitWrite(BLUE_LED_PORT, BLUE_LED_BIT, blue ? RGB_ON : RGB_OFF);
 #endif
 }
 
 void Arduboy2Core::digitalWriteRGB(uint8_t red, uint8_t green, uint8_t blue)
 {
 #ifdef ARDUBOY_10
-  digitalWrite(RED_LED, red);
+  bitWrite(RED_LED_PORT, RED_LED_BIT, red);
-  digitalWrite(GREEN_LED, green);
+  bitWrite(GREEN_LED_PORT, GREEN_LED_BIT, green);
-  digitalWrite(BLUE_LED, blue);
+  bitWrite(BLUE_LED_PORT, BLUE_LED_BIT, blue);
 #elif defined(AB_DEVKIT)
-  digitalWrite(BLUE_LED, blue);
+  // only blue on DevKit
+  (void)red;    // parameter unused
+  (void)green;  // parameter unused
+  bitWrite(BLUE_LED_PORT, BLUE_LED_BIT, blue);
+#endif
+}
+
+void Arduboy2Core::digitalWriteRGB(uint8_t color, uint8_t val)
+{
+#ifdef ARDUBOY_10
+  if (color == RED_LED)
+  {
+    bitWrite(RED_LED_PORT, RED_LED_BIT, val);
+  }
+  else if (color == GREEN_LED)
+  {
+    bitWrite(GREEN_LED_PORT, GREEN_LED_BIT, val);
+  }
+  else if (color == BLUE_LED)
+  {
+    bitWrite(BLUE_LED_PORT, BLUE_LED_BIT, val);
+  }
+#elif defined(AB_DEVKIT)
+  // only blue on DevKit
+  if (color == BLUE_LED)
+  {
+    bitWrite(BLUE_LED_PORT, BLUE_LED_BIT, val);
+  }
 #endif
 }
 

src/Arduboy2Core.h

@@ -9,7 +9,6 @@
 
 #include <Arduino.h>
 #include <avr/power.h>
-#include <SPI.h>
 #include <avr/sleep.h>
 #include <limits.h>
 
@@ -33,35 +32,45 @@
 // #define AB_DEVKIT    //< compile for the official dev kit
 #endif
 
-
-#ifdef AB_DEVKIT
-#define SAFE_MODE    //< include safe mode (44 bytes)
-#endif
-
 #define RGB_ON LOW   /**< For digitially setting an RGB LED on using digitalWriteRGB() */
 #define RGB_OFF HIGH /**< For digitially setting an RGB LED off using digitalWriteRGB() */
 
+// ----- Arduboy pins -----
 #ifdef ARDUBOY_10
 
-#define CS 12
+#define PIN_CS 12       // Display CS Arduino pin number
-#define DC 4
+#define CS_PORT PORTD   // Display CS port
-#define RST 6
+#define CS_BIT PORTD6   // Display CS physical bit number
+
+#define PIN_DC 4        // Display D/C Arduino pin number
+#define DC_PORT PORTD   // Display D/C port
+#define DC_BIT PORTD4   // Display D/C physical bit number
+
+#define PIN_RST 6       // Display reset Arduino pin number
+#define RST_PORT PORTD  // Display reset port
+#define RST_BIT PORTD7  // Display reset physical bit number
+
+#define SPI_MOSI_PORT PORTB
+#define SPI_MOSI_BIT PORTB2
+
+#define SPI_SCK_PORT PORTB
+#define SPI_SCK_BIT PORTB1
 
 #define RED_LED 10   /**< The pin number for the red color in the RGB LED. */
 #define GREEN_LED 11 /**< The pin number for the greem color in the RGB LED. */
 #define BLUE_LED 9   /**< The pin number for the blue color in the RGB LED. */
-#define TX_LED 30    /**< The pin number for the transmit indicator LED. */
-#define RX_LED 17    /**< The pin number for the receive indicator LED. */
 
-// pin values for buttons, probably shouldn't use these
+#define RED_LED_PORT PORTB
-#define PIN_LEFT_BUTTON A2
+#define RED_LED_BIT PORTB6
-#define PIN_RIGHT_BUTTON A1
+
-#define PIN_UP_BUTTON A0
+#define GREEN_LED_PORT PORTB
-#define PIN_DOWN_BUTTON A3
+#define GREEN_LED_BIT PORTB7
-#define PIN_A_BUTTON 7
+
-#define PIN_B_BUTTON 8
+#define BLUE_LED_PORT PORTB
+#define BLUE_LED_BIT PORTB5
 
 // bit values for button states
+// these are determined by the buttonsState() function
 #define LEFT_BUTTON _BV(5)  /**< The Left button value for functions requiring a bitmask */
 #define RIGHT_BUTTON _BV(6) /**< The Right button value for functions requiring a bitmask */
 #define UP_BUTTON _BV(7)    /**< The Up button value for functions requiring a bitmask */
@@ -69,37 +78,79 @@
 #define A_BUTTON _BV(3)     /**< The A button value for functions requiring a bitmask */
 #define B_BUTTON _BV(2)     /**< The B button value for functions requiring a bitmask */
 
+#define PIN_LEFT_BUTTON A2
+#define LEFT_BUTTON_PORT PORTF
+#define LEFT_BUTTON_BIT PORTF5
+
+#define PIN_RIGHT_BUTTON A1
+#define RIGHT_BUTTON_PORT PORTF
+#define RIGHT_BUTTON_BIT PORTF6
+
+#define PIN_UP_BUTTON A0
+#define UP_BUTTON_PORT PORTF
+#define UP_BUTTON_BIT PORTF7
+
+#define PIN_DOWN_BUTTON A3
+#define DOWN_BUTTON_PORT PORTF
+#define DOWN_BUTTON_BIT PORTF4
+
+#define PIN_A_BUTTON 7
+#define A_BUTTON_PORT PORTE
+#define A_BUTTON_BIT PORTE6
+
+#define PIN_B_BUTTON 8
+#define B_BUTTON_PORT PORTB
+#define B_BUTTON_BIT PORTB4
+
 #define PIN_SPEAKER_1 5  /**< The pin number of the first lead of the speaker */
 #define PIN_SPEAKER_2 13 /**< The pin number of the second lead of the speaker */
 
-#define PIN_SPEAKER_1_PORT &PORTC
+#define SPEAKER_1_PORT PORTC
-#define PIN_SPEAKER_2_PORT &PORTC
+#define SPEAKER_1_DDR DDRC
+#define SPEAKER_1_BIT PORTC6
 
-#define PIN_SPEAKER_1_BITMASK _BV(6)
+#define SPEAKER_2_PORT PORTC
-#define PIN_SPEAKER_2_BITMASK _BV(7)
+#define SPEAKER_2_DDR DDRC
+#define SPEAKER_2_BIT PORTC7
 
+#define RAND_SEED_IN A4 // Open analog input used for noise by initRandomSeed()
+#define RAND_SEED_IN_PORTF
+#define RAND_SEED_IN_BIT PORTF1
+// Value for ADMUX to read the random seed pin: 2.56V reference, ADC1
+#define RAND_SEED_IN_ADMUX (_BV(REFS0) | _BV(REFS1) | _BV(MUX0))
+// -----------------------
+
+// ----- DevKit pins -----
 #elif defined(AB_DEVKIT)
 
-#define CS 6
+#define PIN_CS 6        // Display CS Arduino pin number
-#define DC 4
+#define CS_PORT PORTD   // Display CS port
-#define RST 12
+#define CS_BIT PORTD7   // Display CS physical bit number
+
+#define PIN_DC 4        // Display D/C Arduino pin number
+#define DC_PORT PORTD   // Display D/C port
+#define DC_BIT PORTD4   // Display D/C physical bit number
+
+#define PIN_RST 12      // Display reset Arduino pin number
+#define RST_PORT PORTD  // Display reset port
+#define RST_BIT PORTD6  // Display reset physical bit number
+
+#define SPI_MOSI_PORT PORTB
+#define SPI_MOSI_BIT PORTB2
+
+#define SPI_SCK_PORT PORTB
+#define SPI_SCK_BIT PORTB1
 
 // map all LEDs to the single TX LED on DEVKIT
 #define RED_LED 17
 #define GREEN_LED 17
 #define BLUE_LED 17
-#define TX_LED 17
-#define RX_LED 17
 
-// pin values for buttons, probably shouldn't use these
+#define BLUE_LED_PORT PORTB
-#define PIN_LEFT_BUTTON 9
+#define BLUE_LED_BIT PORTB0
-#define PIN_RIGHT_BUTTON 5
-#define PIN_UP_BUTTON 8
-#define PIN_DOWN_BUTTON 10
-#define PIN_A_BUTTON A0
-#define PIN_B_BUTTON A1
 
 // bit values for button states
+// these are determined by the buttonsState() function
 #define LEFT_BUTTON _BV(5)
 #define RIGHT_BUTTON _BV(2)
 #define UP_BUTTON _BV(4)
@@ -107,15 +158,48 @@
 #define A_BUTTON _BV(1)
 #define B_BUTTON _BV(0)
 
+// pin values for buttons, probably shouldn't use these
+#define PIN_LEFT_BUTTON 9
+#define LEFT_BUTTON_PORT PORTB
+#define LEFT_BUTTON_BIT PORTB5
+
+#define PIN_RIGHT_BUTTON 5
+#define RIGHT_BUTTON_PORT PORTC
+#define RIGHT_BUTTON_BIT PORTC6
+
+#define PIN_UP_BUTTON 8
+#define UP_BUTTON_PORT PORTB
+#define UP_BUTTON_BIT PORTB4
+
+#define PIN_DOWN_BUTTON 10
+#define DOWN_BUTTON_PORT PORTB
+#define DOWN_BUTTON_BIT PORTB6
+
+#define PIN_A_BUTTON A0
+#define A_BUTTON_PORT PORTF
+#define A_BUTTON_BIT PORTF7
+
+#define PIN_B_BUTTON A1
+#define B_BUTTON_PORT PORTF
+#define B_BUTTON_BIT PORTF6
+
 #define PIN_SPEAKER_1 A2
-#define PIN_SPEAKER_1_PORT &PORTF
+#define SPEAKER_1_PORT PORTF
-#define PIN_SPEAKER_1_BITMASK _BV(5)
+#define SPEAKER_1_DDR DDRF
+#define SPEAKER_1_BIT PORTF5
 // SPEAKER_2 is purposely not defined for DEVKIT as it could potentially
 // be dangerous and fry your hardware (because of the devkit wiring).
 //
 // Reference: https://github.com/Arduboy/Arduboy/issues/108
 
+#define RAND_SEED_IN A4 // Open analog input used for noise by initRandomSeed()
+#define RAND_SEED_IN_PORTF
+#define RAND_SEED_IN_BIT PORTF1
+// Value for ADMUX to read the random seed pin: 2.56V reference, ADC1
+#define RAND_SEED_IN_ADMUX (_BV(REFS0) | _BV(REFS1) | _BV(MUX0))
+
 #endif
+// --------------------
 
 // OLED hardware (SSD1306)
 
@@ -183,6 +267,8 @@ class Arduboy2Core
      * This is a low level function that is not intended for general use in a
      * sketch. It has been made public and documented for use by derived
      * classes.
+     *
+     * \see LCDCommandMode() SPItransfer()
      */
     void static LCDDataMode();
 
@@ -206,10 +292,25 @@ class Arduboy2Core
      * sketch. It has been made public and documented for use by derived
      * classes.
      *
-     * \see sendLCDCommand()
+     * \see LCDDataMode() sendLCDCommand() SPItransfer()
      */
     void static LCDCommandMode();
 
+    /** \brief
+     * Transfer a byte to the display.
+     *
+     * \param data The byte to be sent to the display.
+     *
+     * \details
+     * Transfer one byte to the display over the SPI port and wait for the
+     * transfer to complete. The byte will either be interpreted as a command
+     * or as data to be placed on the screen, depending on the command/data
+     * mode.
+     *
+     * \see LCDDataMode() LCDCommandMode() sendLCDCommand()
+     */
+    void static inline SPItransfer(uint8_t data);
+
     /** \brief
      * Get the width of the display in pixels.
      *
@@ -233,7 +334,7 @@ class Arduboy2Core
     uint8_t static height();
 
     /** \brief
-     * get current state of all buttons as a bitmask.
+     * Get the current state of all buttons as a bitmask.
      *
      * \return A bitmask of the state of all the buttons.
      *
@@ -461,9 +562,9 @@ class Arduboy2Core
      *
      * \details
      * The RGB LED is actually individual red, green and blue LEDs placed
-     * very close together in a single package. This function will set each
+     * very close together in a single package. This 3 parameter version of the
-     * LED either on or off, to set the RGB LED to 7 different colors at their
+     * function will set each LED either on or off, to set the RGB LED to
-     * highest brightness or turn it off.
+     * 7 different colors at their highest brightness or turn it off.
      *
      * The colors are as follows:
      *
@@ -486,10 +587,28 @@ class Arduboy2Core
      * light the red LED. If the green LED is turned on, none of the LEDs
      * will light.
      *
-     * \see setRGBled()
+     * \see digitalWriteRGB(uint8_t, uint8_t) setRGBled()
      */
     void static digitalWriteRGB(uint8_t red, uint8_t green, uint8_t blue);
 
+    /** \brief
+     * Set one of the RGB LEDs digitally, to either fully on or fully off.
+     *
+     * \param color The name of the LED to set. The value given should be one
+     * of RED_LED, GREEN_LED or BLUE_LED.
+     *
+     * \param val Indicates whether to turn the specified LED on or off.
+     * The value given should be RGB_ON or RGB_OFF.
+     *
+     * \details
+     * This 2 parameter version of the function will set a single LED within
+     * the RGB LED either fully on or fully off. See the description of the
+     * 3 parameter version of this function for more details on the RGB LED.
+     *
+     * \see digitalWriteRGB(uint8_t, uint8_t, uint8_t) setRGBled()
+     */
+    void static digitalWriteRGB(uint8_t color, uint8_t val);
+
     /** \brief
      * Initialize the Arduboy's hardware.
      *
@@ -507,30 +626,33 @@ class Arduboy2Core
      */
     void static boot();
 
-  protected:
+    /** \brief
-    /*
+     * Allow upload when the bootloader "magic number" could be corrupted.
-     * Safe Mode is engaged by holding down both the LEFT button and UP button
-     * when plugging the device into USB. It puts your device into a tight
-     * loop and allows it to be reprogrammed even if you have uploaded a very
-     * broken sketch that interferes with the normal USB triggered auto-reboot
-     * functionality of the device.
      *
-     * This is most useful on Devkits because they lack a built-in reset
+     * \details
-     * button.
+     * If the UP button is held when this function is entered, the RGB LED
+     * will be lit and timer 0 will be disabled, then the sketch will remain
+     * in a tight loop. This is to address a problem with uploading a new
+     * sketch, for sketches that interfere with the bootloader "magic number".
+     * The problem occurs with certain sketches that use large amounts of RAM.
+     *
+     * This function should be called after `boot()` in sketches that
+     * potentially could cause the problem.
+     *
+     * It is intended to replace the `flashlight()` function when more
+     * program space is required. If possible, it is more desirable to use
+     * `flashlight()`, so that the actual flashlight feature isn't lost.
+     *
+     * \see Arduboy2Base::flashlight() boot()
      */
-    void static inline safeMode() __attribute__((always_inline));
+    void static safeMode();
 
+  protected:
     // internals
     void static inline setCPUSpeed8MHz() __attribute__((always_inline));
     void static inline bootOLED() __attribute__((always_inline));
     void static inline bootPins() __attribute__((always_inline));
     void static inline bootPowerSaving() __attribute__((always_inline));
-
-
-  private:
-    volatile static uint8_t *csport, *dcport;
-    uint8_t static cspinmask, dcpinmask;
-
 };
 
 #endif