Arduboy2 Library  6.0.0
Arduboy2 Class Reference

The main functions provided for writing sketches for the Arduboy, including text output. More...

#include <Arduboy2.h>

+ Inheritance diagram for Arduboy2:
+ Collaboration diagram for Arduboy2:

Public Member Functions

void begin ()
 Initialize the hardware, display the boot logo, provide boot utilities, etc. More...
 
void bootLogo ()
 Display the boot logo sequence using drawBitmap(). More...
 
void bootLogoCompressed ()
 Display the boot logo sequence using drawCompressed(). More...
 
void bootLogoSpritesSelfMasked ()
 Display the boot logo sequence using Sprites::drawSelfMasked(). More...
 
void bootLogoSpritesOverwrite ()
 Display the boot logo sequence using Sprites::drawOverwrite(). More...
 
void bootLogoSpritesBSelfMasked ()
 Display the boot logo sequence using SpritesB::drawSelfMasked(). More...
 
void bootLogoSpritesBOverwrite ()
 Display the boot logo sequence using SpritesB::drawOverwrite(). More...
 
void bootLogoText ()
 Display the boot logo sequence using printed text instead of a bitmap. More...
 
void bootLogoExtra ()
 Show the unit name at the bottom of the boot logo screen. More...
 
virtual size_t write (uint8_t)
 Write a single character at the current text cursor position. More...
 

Static Public Member Functions

static void drawChar (int16_t x, int16_t y, uint8_t c, uint8_t color, uint8_t bg, uint8_t size)
 Draw a single character at the specified location in the screen buffer. More...
 
static void setCursor (int16_t x, int16_t y)
 Set the location of the text cursor. More...
 
static void setCursorX (int16_t x)
 Set the X coordinate of the text cursor location. More...
 
static void setCursorY (int16_t y)
 Set the Y coordinate of the text cursor location. More...
 
static int16_t getCursorX ()
 Get the X coordinate of the current text cursor position. More...
 
static int16_t getCursorY ()
 Get the Y coordinate of the current text cursor position. More...
 
static void setTextColor (uint8_t color)
 Set the text foreground color. More...
 
static uint8_t getTextColor ()
 Get the currently set text foreground color. More...
 
static void setTextBackground (uint8_t bg)
 Set the text background color. More...
 
static uint8_t getTextBackground ()
 Get the currently set text background color. More...
 
static void setTextSize (uint8_t s)
 Set the text character size. More...
 
static uint8_t getTextSize ()
 Get the currently set text size. More...
 
static void setTextWrap (bool w)
 Set or disable text wrap mode. More...
 
static bool getTextWrap ()
 Get the currently set text wrap mode. More...
 
static void setTextRawMode (bool raw)
 Set or disable text raw mode, allowing special characters to be displayed. More...
 
static bool getTextRawMode ()
 Get the current state of text raw mode. More...
 
static void clear ()
 Clear the display buffer and set the text cursor to location 0, 0.
 
static constexpr uint8_t getCharacterWidth (uint8_t textSize=1)
 Get the width, in pixels, of a character in the library's font. More...
 
static constexpr uint8_t getCharacterSpacing (uint8_t textSize=1)
 Get the number of pixels added after each character to provide spacing. More...
 
static constexpr uint8_t getCharacterHeight (uint8_t textSize=1)
 Get the height, in pixels, of a character in the library's font. More...
 
static constexpr uint8_t getLineSpacing (uint8_t textSize=1)
 Get the number of pixels added below each character to provide line spacing. More...
 
static void beginDoFirst ()
 Helper function that calls the inital functions used by begin() More...
 
static void flashlight ()
 Turn the RGB LED and display fully on to act as a small flashlight/torch. More...
 
static void systemButtons ()
 Handle buttons held on startup for system control. More...
 
static bool bootLogoShell (void(&drawLogo)(int16_t))
 Display the boot logo sequence using the provided function. More...
 
static void waitNoButtons ()
 Wait until all buttons have been released. More...
 
static void fillScreen (uint8_t color=WHITE)
 Fill the screen buffer with the specified color. More...
 
static void display ()
 Copy the contents of the display buffer to the display. More...
 
static void display (bool clear)
 Copy the contents of the display buffer to the display. The display buffer can optionally be cleared. More...
 
static void drawPixel (int16_t x, int16_t y, uint8_t color=WHITE)
 Set a single pixel in the display buffer to the specified color. More...
 
static uint8_t getPixel (uint8_t x, uint8_t y)
 Returns the state of the given pixel in the screen buffer. More...
 
static void drawCircle (int16_t x0, int16_t y0, uint8_t r, uint8_t color=WHITE)
 Draw a circle of a given radius. More...
 
static void fillCircle (int16_t x0, int16_t y0, uint8_t r, uint8_t color=WHITE)
 Draw a filled-in circle of a given radius. More...
 
static void drawLine (int16_t x0, int16_t y0, int16_t x1, int16_t y1, uint8_t color=WHITE)
 Draw a line between two specified points. More...
 
static void drawFastVLine (int16_t x, int16_t y, uint8_t h, uint8_t color=WHITE)
 Draw a vertical line. More...
 
static void drawFastHLine (int16_t x, int16_t y, uint8_t w, uint8_t color=WHITE)
 Draw a horizontal line. More...
 
static void drawRect (int16_t x, int16_t y, uint8_t w, uint8_t h, uint8_t color=WHITE)
 Draw a rectangle of a specified width and height. More...
 
static void fillRect (int16_t x, int16_t y, uint8_t w, uint8_t h, uint8_t color=WHITE)
 Draw a filled-in rectangle of a specified width and height. More...
 
static void drawRoundRect (int16_t x, int16_t y, uint8_t w, uint8_t h, uint8_t r, uint8_t color=WHITE)
 Draw a rectangle with rounded corners. More...
 
static void fillRoundRect (int16_t x, int16_t y, uint8_t w, uint8_t h, uint8_t r, uint8_t color=WHITE)
 Draw a filled-in rectangle with rounded corners. More...
 
static void drawTriangle (int16_t x0, int16_t y0, int16_t x1, int16_t y1, int16_t x2, int16_t y2, uint8_t color=WHITE)
 Draw a triangle given the coordinates of each corner. More...
 
static void fillTriangle (int16_t x0, int16_t y0, int16_t x1, int16_t y1, int16_t x2, int16_t y2, uint8_t color=WHITE)
 Draw a filled-in triangle given the coordinates of each corner. More...
 
static void drawBitmap (int16_t x, int16_t y, const uint8_t *bitmap, uint8_t w, uint8_t h, uint8_t color=WHITE)
 Draw a bitmap from an array in program memory. More...
 
static void drawSlowXYBitmap (int16_t x, int16_t y, const uint8_t *bitmap, uint8_t w, uint8_t h, uint8_t color=WHITE)
 Draw a bitmap from a horizontally oriented array in program memory. More...
 
static void drawCompressed (int16_t sx, int16_t sy, const uint8_t *bitmap, uint8_t color=WHITE)
 Draw a bitmap from an array of compressed data. More...
 
static uint8_t * getBuffer ()
 Get a pointer to the display buffer in RAM. More...
 
static void initRandomSeed ()
 Seed the random number generator with a random value. More...
 
static void setFrameRate (uint8_t rate)
 Set the frame rate used by the frame control functions. More...
 
static void setFrameDuration (uint8_t duration)
 Set the frame rate, used by the frame control functions, by giving the duration of each frame. More...
 
static bool nextFrame ()
 Indicate that it's time to render the next frame. More...
 
static bool nextFrameDEV ()
 Indicate that it's time to render the next frame, and visually indicate if the code is running slower than the desired frame rate. FOR USE DURING DEVELOPMENT More...
 
static bool everyXFrames (uint8_t frames)
 Indicate if the specified number of frames has elapsed. More...
 
static int cpuLoad ()
 Return the load on the CPU as a percentage. More...
 
static bool pressed (uint8_t buttons)
 Test if the all of the specified buttons are pressed. More...
 
static bool anyPressed (uint8_t buttons)
 Test if any of the specified buttons are pressed. More...
 
static bool notPressed (uint8_t buttons)
 Test if the specified buttons are not pressed. More...
 
static void pollButtons ()
 Poll the buttons and track their state over time. More...
 
static bool justPressed (uint8_t button)
 Check if a button has just been pressed. More...
 
static bool justReleased (uint8_t button)
 Check if a button has just been released. More...
 
static bool collide (Point point, Rect rect)
 Test if a point falls within a rectangle. More...
 
static bool collide (Rect rect1, Rect rect2)
 Test if a rectangle is intersecting with another rectangle. More...
 
static uint16_t readUnitID ()
 Read the unit ID from system EEPROM. More...
 
static void writeUnitID (uint16_t id)
 Write a unit ID to system EEPROM. More...
 
static uint8_t readUnitName (char *name)
 Read the unit name from system EEPROM. More...
 
static void writeUnitName (const char *name)
 Write a unit name to system EEPROM. More...
 
static bool readShowBootLogoFlag ()
 Read the "Show Boot Logo" flag in system EEPROM. More...
 
static void writeShowBootLogoFlag (bool val)
 Write the "Show Boot Logo" flag in system EEPROM. More...
 
static bool readShowUnitNameFlag ()
 Read the "Show Unit Name" flag in system EEPROM. More...
 
static void writeShowUnitNameFlag (bool val)
 Write the "Show Unit Name" flag in system EEPROM. More...
 
static bool readShowBootLogoLEDsFlag ()
 Read the "Show LEDs with boot logo" flag in system EEPROM. More...
 
static void writeShowBootLogoLEDsFlag (bool val)
 Write the "Show LEDs with boot logo" flag in system EEPROM. More...
 
static void idle ()
 Idle the CPU to save power. More...
 
static void LCDDataMode ()
 Put the display into data mode. More...
 
static void LCDCommandMode ()
 Put the display into command mode. More...
 
static void SPItransfer (uint8_t data)
 Transfer a byte to the display. More...
 
static uint8_t SPItransferAndRead (uint8_t data)
 Transfer a byte to, and read a byte from, the SPI bus. More...
 
static void displayOff ()
 Turn the display off. More...
 
static void displayOn ()
 Turn the display on. More...
 
static constexpr uint8_t width ()
 Get the width of the display in pixels. More...
 
static constexpr uint8_t height ()
 Get the height of the display in pixels. More...
 
static uint8_t buttonsState ()
 Get the current state of all buttons as a bitmask. More...
 
static void paint8Pixels (uint8_t pixels)
 Paint 8 pixels vertically to the display. More...
 
static void paintScreen (const uint8_t *image)
 Paints an entire image directly to the display from program memory. More...
 
static void paintScreen (uint8_t image[], bool clear=false)
 Paints an entire image directly to the display from an array in RAM. More...
 
static void blank ()
 Blank the display screen by setting all pixels off. More...
 
static void invert (bool inverse)
 Invert the entire display or set it back to normal. More...
 
static void allPixelsOn (bool on)
 Turn all display pixels on or display the buffer contents. More...
 
static void flipVertical (bool flipped)
 Flip the display vertically or set it back to normal. More...
 
static void flipHorizontal (bool flipped)
 Flip the display horizontally or set it back to normal. More...
 
static void sendLCDCommand (uint8_t command)
 Send a single command byte to the display. More...
 
static void setRGBled (uint8_t red, uint8_t green, uint8_t blue)
 Set the light output of the RGB LED. More...
 
static void setRGBled (uint8_t color, uint8_t val)
 Set the brightness of one of the RGB LEDs without affecting the others. More...
 
static void freeRGBled ()
 Relinquish analog control of the RGB LED. More...
 
static void digitalWriteRGB (uint8_t red, uint8_t green, uint8_t blue)
 Set the RGB LEDs digitally, to either fully on or fully off. More...
 
static void digitalWriteRGB (uint8_t color, uint8_t val)
 Set one of the RGB LEDs digitally, to either fully on or fully off. More...
 
static void boot ()
 Initialize the Arduboy's hardware. More...
 
static void safeMode ()
 Allow upload when the bootloader "magic number" could be corrupted. More...
 
static unsigned long generateRandomSeed ()
 Create a seed suitable for use with a pseudorandom number generator. More...
 
static void delayShort (uint16_t ms) __attribute__((noinline))
 Delay for the number of milliseconds, specified as a 16 bit value. More...
 
static void exitToBootloader ()
 Exit the sketch and start the bootloader. More...
 

Static Public Attributes

static const PROGMEM uint8_t font5x7 []
 The font used for text functions. More...
 
static Arduboy2Audio audio
 An object created to provide audio control functions within this class. More...
 
static uint16_t frameCount = 0
 A counter which is incremented once per frame. More...
 
static uint8_t currentButtonState = 0
 Used by pollButtons() to hold the current button state. More...
 
static uint8_t previousButtonState = 0
 Used by pollButtons() to hold the previous button state. More...
 
static uint8_t sBuffer [(HEIGHT *WIDTH)/8]
 The display buffer array in RAM. More...
 
static const PROGMEM uint8_t arduboy_logo []
 The bitmap for the ARDUBOY logo in drawBitmap() format. More...
 
static const PROGMEM uint8_t arduboy_logo_compressed []
 The bitmap for the ARDUBOY logo in drawCompressed() format. More...
 
static const PROGMEM uint8_t arduboy_logo_sprite []
 The bitmap for the ARDUBOY logo in Sprites class drawSelfMasked() or drawOverwrite() format. More...
 

Detailed Description

The main functions provided for writing sketches for the Arduboy, including text output.

This class is derived from Arduboy2Base. It provides text output functions in addition to all the functions inherited from Arduboy2Base.

Note
A friend class named Arduboy2Ex is declared by this class. The intention is to allow a sketch to create an Arduboy2Ex class which would have access to the private and protected members of the Arduboy2 class. It is hoped that this may eliminate the need to create an entire local copy of the library, in order to extend the functionality, in most circumstances.
See also
Arduboy2Base

Definition at line 1575 of file Arduboy2.h.

Member Function Documentation

◆ allPixelsOn()

void Arduboy2Core::allPixelsOn ( bool  on)
staticinherited

Turn all display pixels on or display the buffer contents.

Parameters
ontrue turns all pixels on. false displays the contents of the hardware display buffer.

Calling this function with a value of true will override the contents of the hardware display buffer and turn all pixels on. The contents of the hardware buffer will remain unchanged.

Calling this function with a value of false will set the normal state of displaying the contents of the hardware display buffer.

Note
All pixels will be lit even if the display is in inverted mode.
See also
invert()

Definition at line 422 of file Arduboy2Core.cpp.

◆ anyPressed()

bool Arduboy2Base::anyPressed ( uint8_t  buttons)
staticinherited

Test if any of the specified buttons are pressed.

Parameters
buttonsA bit mask indicating which buttons to test. (Can be a single button)
Returns
true if one or more of the buttons in the provided mask are currently pressed.

Read the state of the buttons and return true if one or more of the buttons in the specified mask are being pressed.

Example: if (anyPressed(RIGHT_BUTTON | LEFT_BUTTON))

Note
This function does not perform any button debouncing.
See also
pressed() notPressed()

Definition at line 1017 of file Arduboy2.cpp.

◆ begin()

void Arduboy2::begin ( )

Initialize the hardware, display the boot logo, provide boot utilities, etc.

This function should be called once near the start of the sketch, usually in setup(), before using any other functions in this class. It initializes the display, displays the boot logo, provides "flashlight" and system control features and initializes audio control.

Note

If it becomes necessary to free up some code space for use by the sketch, boot() can be used instead of begin() to allow the elimination of some of the things that aren't absolutely required.

See the README file or main page, in section Substitute or remove boot up features, for more details.

See also
boot()

Definition at line 1170 of file Arduboy2.cpp.

◆ beginDoFirst()

void Arduboy2Base::beginDoFirst ( )
staticinherited

Helper function that calls the inital functions used by begin()

This function calls all the functions used by begin() up to the point of calling bootLogo(). It could be called by a sketch to make it easy to use one of the alternative bootLogo...() functions or a user provided one.

For example, if a sketch uses Sprites class functions but doesn't use drawBitmap(), some program space may be saved by using the following in place of begin():

arduboy.beginDoFirst();
arduboy.bootLogoSpritesSelfMasked(); // or:
//arduboy.bootLogoSpritesOverwrite(); // (whatever saves more memory)
arduboy.waitNoButtons();
See also
begin() boot()

Definition at line 48 of file Arduboy2.cpp.

◆ blank()

void Arduboy2Core::blank ( )
staticinherited

Blank the display screen by setting all pixels off.

All pixels on the screen will be written with a value of 0 to turn them off.

Definition at line 400 of file Arduboy2Core.cpp.

◆ boot()

void Arduboy2Core::boot ( )
staticinherited

Initialize the Arduboy's hardware.

This function initializes the display, buttons, etc.

This function is called by begin() so isn't normally called within a sketch. However, in order to free up some code space, by eliminating some of the start up features, it can be called in place of begin(). The functions that begin() would call after boot() can then be called to add back in some of the start up features as space permits.

See the README file or main page, in section Substitute or remove boot up features, for more details.

Warning
If this function is used, it is recommended that at least flashlight() or safeMode() be called after it to provide a means to upload a new sketch if the bootloader "magic number" problem is encountered.
See also
Arduboy2::begin() Arduboy2Base::flashlight() safeMode()

Definition at line 81 of file Arduboy2Core.cpp.

◆ bootLogo()

void Arduboy2::bootLogo ( )

Display the boot logo sequence using drawBitmap().

This function is called by begin() and can be called by a sketch after boot().

The Arduboy logo scrolls down from the top of the screen to the center while the RGB LEDs light in sequence.

The bootLogoShell() helper function is used to perform the actual sequence. The documentation for bootLogoShell() provides details on how it operates.

See also
begin() boot() bootLogoShell() Arduboy2::bootLogoText()

Definition at line 1187 of file Arduboy2.cpp.

◆ bootLogoCompressed()

void Arduboy2::bootLogoCompressed ( )

Display the boot logo sequence using drawCompressed().

This function can be called by a sketch after boot() as an alternative to bootLogo(). This may reduce code size if the sketch itself uses drawCompressed().

See also
bootLogo() begin() boot()

Definition at line 1195 of file Arduboy2.cpp.

◆ bootLogoExtra()

void Arduboy2::bootLogoExtra ( )

Show the unit name at the bottom of the boot logo screen.

This function is called by the bootLogo...() functions if the logo sequence runs to completion.

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.

If the "Show Unit Name" flag in system EEPROM is cleared, this function will return without showing the unit name or pausing.

This function would not normally be called directly from within a sketch except from a sketch provided bootlogo...() function that renders the boot logo using a function that's not part of the Arduboy2 library. The README file or main page describes how this would be done, at the end of the Substitute or remove boot up features section.

See also
readUnitName() writeUnitName() bootLogo() bootLogoShell() bootLogoText() writeShowUnitNameFlag() begin()

Definition at line 1282 of file Arduboy2.cpp.

◆ bootLogoShell()

bool Arduboy2Base::bootLogoShell ( void(&)(int16_t)  drawLogo)
staticinherited

Display the boot logo sequence using the provided function.

Parameters
drawLogoA reference to a function which will draw the boot logo at the given Y position.
Returns
true if the sequence runs to completion. false if the sequence is aborted or bypassed.

This common function executes the sequence to display the boot logo. It is called by bootLogo() and other similar functions which provide it with a reference to a function which will do the actual drawing of the logo.

This function calls bootLogoExtra() after the logo stops scrolling down, which derived classes can implement to add additional information to the logo screen. The Arduboy2 class uses this to display the unit name.

If the RIGHT button is pressed while the logo is scrolling down, the boot logo sequence will be aborted. This can be useful for developers who wish to quickly start testing, or anyone else who is impatient and wants to go straight to the actual sketch.

If the "Show LEDs with boot logo" flag in system EEPROM is cleared, the RGB LEDs will not be flashed during the logo display sequence.

If the "Show Boot Logo" flag in system EEPROM is cleared, this function will return without executing the logo display sequence.

The prototype for the function provided to draw the logo is:

void drawLogo(int16_t y);

The y parameter is the Y offset for the top of the logo. It is expected that the logo will be 16 pixels high and centered horizontally. This will result in the logo stopping in the middle of the screen at the end of the sequence. If the logo height is not 16 pixels, the Y value can be adjusted to compensate.

See also
bootLogo() boot() Arduboy2::bootLogoExtra()

Definition at line 171 of file Arduboy2.cpp.

◆ bootLogoSpritesBOverwrite()

void Arduboy2::bootLogoSpritesBOverwrite ( )

Display the boot logo sequence using SpritesB::drawOverwrite().

This function can be called by a sketch after boot() as an alternative to bootLogo(). This may reduce code size if the sketch itself uses SpritesB class functions.

See also
bootLogo() begin() boot() SpritesB

Definition at line 1227 of file Arduboy2.cpp.

◆ bootLogoSpritesBSelfMasked()

void Arduboy2::bootLogoSpritesBSelfMasked ( )

Display the boot logo sequence using SpritesB::drawSelfMasked().

This function can be called by a sketch after boot() as an alternative to bootLogo(). This may reduce code size if the sketch itself uses SpritesB class functions.

See also
bootLogo() begin() boot() SpritesB

Definition at line 1219 of file Arduboy2.cpp.

◆ bootLogoSpritesOverwrite()

void Arduboy2::bootLogoSpritesOverwrite ( )

Display the boot logo sequence using Sprites::drawOverwrite().

This function can be called by a sketch after boot() as an alternative to bootLogo(). This may reduce code size if the sketch itself uses Sprites class functions.

See also
bootLogo() begin() boot() Sprites

Definition at line 1211 of file Arduboy2.cpp.

◆ bootLogoSpritesSelfMasked()

void Arduboy2::bootLogoSpritesSelfMasked ( )

Display the boot logo sequence using Sprites::drawSelfMasked().

This function can be called by a sketch after boot() as an alternative to bootLogo(). This may reduce code size if the sketch itself uses Sprites class functions.

See also
bootLogo() begin() boot() Sprites

Definition at line 1203 of file Arduboy2.cpp.

◆ bootLogoText()

void Arduboy2::bootLogoText ( )

Display the boot logo sequence using printed text instead of a bitmap.

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().

If the RIGHT button is pressed while the logo is scrolling down, the boot logo sequence will be aborted. This can be useful for developers who wish to quickly start testing, or anyone else who is impatient and wants to go straight to the actual sketch.

If the "Show LEDs with boot logo" flag in system EEPROM is cleared, the RGB LEDs will not be flashed during the logo display sequence.

If the "Show Boot Logo" flag in system EEPROM is cleared, this function will return without executing the logo display sequence.

See also
bootLogo() boot() Arduboy2::bootLogoExtra()

Definition at line 1237 of file Arduboy2.cpp.

◆ buttonsState()

uint8_t Arduboy2Core::buttonsState ( )
staticinherited

Get the current state of all buttons as a bitmask.

Returns
A bitmask of the state of all the buttons.

The returned mask contains a bit for each button. For any pressed button, its bit will be 1. For released buttons their associated bits will be 0.

The following defined mask values should be used for the buttons:

LEFT_BUTTON, RIGHT_BUTTON, UP_BUTTON, DOWN_BUTTON, A_BUTTON, B_BUTTON

Definition at line 536 of file Arduboy2Core.cpp.

◆ collide() [1/2]

bool Arduboy2Base::collide ( Point  point,
Rect  rect 
)
staticinherited

Test if a point falls within a rectangle.

Parameters
pointA structure describing the location of the point.
rectA structure describing the location and size of the rectangle.
Returns
true if the specified point is within the specified rectangle.

This function is intended to detemine if an object, whose boundaries are are defined by the given rectangle, is in contact with the given point.

See also
Point Rect

Definition at line 1043 of file Arduboy2.cpp.

◆ collide() [2/2]

bool Arduboy2Base::collide ( Rect  rect1,
Rect  rect2 
)
staticinherited

Test if a rectangle is intersecting with another rectangle.

Parameters
rect1,rect2Structures describing the size and locations of the rectangles.
Returns
true if the first rectangle is intersecting the second.

This function is intended to detemine if an object, whose boundaries are are defined by the given rectangle, is in contact with another rectangular object.

See also
Rect

Definition at line 1049 of file Arduboy2.cpp.

◆ cpuLoad()

int Arduboy2Base::cpuLoad ( )
staticinherited

Return the load on the CPU as a percentage.

Returns
The load on the CPU as a percentage of the total frame time.

The returned value gives the time spent processing a frame as a percentage the total time allotted for a frame, as determined by the frame rate.

This function normally wouldn't be used in the final program. It is intended for use during program development as an aid in helping with frame timing.

Note
The percentage returned can be higher than 100 if more time is spent processing a frame than the time allotted per frame. This would indicate that the frame rate should be made slower or the frame processing code should be optimized to run faster.
See also
nextFrameDEV() setFrameRate() setFrameDuration() nextFrame()

Definition at line 278 of file Arduboy2.cpp.

◆ delayShort()

void Arduboy2Core::delayShort ( uint16_t  ms)
staticinherited

Delay for the number of milliseconds, specified as a 16 bit value.

Parameters
msThe delay in milliseconds.

This function works the same as the Arduino delay() function except the provided value is 16 bits long, so the maximum delay allowed is 65535 milliseconds (about 65.5 seconds). Using this function instead of Arduino delay() will save a few bytes of code.

Definition at line 582 of file Arduboy2Core.cpp.

◆ digitalWriteRGB() [1/2]

void Arduboy2Core::digitalWriteRGB ( uint8_t  color,
uint8_t  val 
)
staticinherited

Set one of the RGB LEDs digitally, to either fully on or fully off.

Parameters
colorThe name of the LED to set. The value given should be one of RED_LED, GREEN_LED or BLUE_LED.
valIndicates whether to turn the specified LED on or off. The value given should be RGB_ON or RGB_OFF.

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 also
digitalWriteRGB(uint8_t, uint8_t, uint8_t) setRGBled() freeRGBled()

Definition at line 510 of file Arduboy2Core.cpp.

◆ digitalWriteRGB() [2/2]

void Arduboy2Core::digitalWriteRGB ( uint8_t  red,
uint8_t  green,
uint8_t  blue 
)
staticinherited

Set the RGB LEDs digitally, to either fully on or fully off.

Parameters
red,green,blueUse value RGB_ON or RGB_OFF to set each LED.

The RGB LED is actually individual red, green and blue LEDs placed very close together in a single package. This 3 parameter version of the function will set each LED either on or off, to set the RGB LED to 7 different colors at their highest brightness or turn it off.

The colors are as follows:

RED LED GREEN LED BLUE LED COLOR
RGB_OFF RGB_OFF RGB_OFF OFF
RGB_OFF RGB_OFF RGB_ON Blue
RGB_OFF RGB_ON RGB_OFF Green
RGB_OFF RGB_ON RGB_ON Cyan
RGB_ON RGB_OFF RGB_OFF Red
RGB_ON RGB_OFF RGB_ON Magenta
RGB_ON RGB_ON RGB_OFF Yellow
RGB_ON RGB_ON RGB_ON White
Note
Using the RGB LED in analog mode will prevent digital control of the LED. To restore the ability to control the LED digitally, use the freeRGBled() function.
Note
Many of the Kickstarter Arduboys were accidentally shipped with the RGB LED installed incorrectly. For these units, the green LED cannot be lit. As long as the green led is set to off, turning on the red LED will actually light the blue LED and turning on the blue LED will actually light the red LED. If the green LED is turned on, none of the LEDs will light.
See also
digitalWriteRGB(uint8_t, uint8_t) setRGBled() freeRGBled()

Definition at line 496 of file Arduboy2Core.cpp.

◆ display() [1/2]

void Arduboy2Base::display ( )
staticinherited

Copy the contents of the display buffer to the display.

The contents of the display buffer in RAM are copied to the display and will appear on the screen.

See also
display(bool)

Definition at line 997 of file Arduboy2.cpp.

◆ display() [2/2]

void Arduboy2Base::display ( bool  clear)
staticinherited

Copy the contents of the display buffer to the display. The display buffer can optionally be cleared.

Parameters
clearIf true the display buffer will be cleared to zero. The defined value CLEAR_BUFFER should be used instead of true to make it more meaningful.

Operation is the same as calling display() without parameters except additionally the display buffer will be cleared if the parameter evaluates to true. (The defined value CLEAR_BUFFER can be used for this)

Using display(CLEAR_BUFFER) is faster and produces less code than calling display() followed by clear().

See also
display() clear()

Definition at line 1002 of file Arduboy2.cpp.

◆ displayOff()

void Arduboy2Core::displayOff ( )
staticinherited

Turn the display off.

The display will clear and be put into a low power mode. This can be used to extend battery life when a game is paused or when a sketch doesn't require anything to be displayed for a relatively long period of time.

See also
displayOn()

Definition at line 295 of file Arduboy2Core.cpp.

◆ displayOn()

void Arduboy2Core::displayOn ( )
staticinherited

Turn the display on.

Used to power up and reinitialize the display after calling displayOff().

Note
The previous call to displayOff() will have caused the display's buffer contents to be lost. The display will have to be re-painted, which is usually done by calling display().
See also
displayOff()

Definition at line 306 of file Arduboy2Core.cpp.

◆ drawBitmap()

void Arduboy2Base::drawBitmap ( int16_t  x,
int16_t  y,
const uint8_t *  bitmap,
uint8_t  w,
uint8_t  h,
uint8_t  color = WHITE 
)
staticinherited

Draw a bitmap from an array in program memory.

Parameters
xThe X coordinate of the top left pixel affected by the bitmap.
yThe Y coordinate of the top left pixel affected by the bitmap.
bitmapA pointer to the bitmap array in program memory.
wThe width of the bitmap in pixels.
hThe height of the bitmap in pixels. Must be a multiple of 8.
colorThe color of pixels for bits set to 1 in the bitmap. If the value is INVERT, bits set to 1 will invert the corresponding pixel. (optional; defaults to WHITE).

Bits set to 1 in the provided bitmap array will have their corresponding pixel set to the specified color. For bits set to 0 in the array, the corresponding pixel will be left unchanged.

Each byte in the array specifies a vertical column of 8 pixels, with the least significant bit at the top. The height of the image must be a multiple of 8 pixels (8, 16, 24, 32, ...). The width can be any size.

The array must be located in program memory by using the PROGMEM modifier.

See also
drawCompressed() drawSlowXYBitmap() Sprites

Definition at line 803 of file Arduboy2.cpp.

◆ drawChar()

void Arduboy2::drawChar ( int16_t  x,
int16_t  y,
uint8_t  c,
uint8_t  color,
uint8_t  bg,
uint8_t  size 
)
static

Draw a single character at the specified location in the screen buffer.

Parameters
xThe X coordinate, in pixels, for where to draw the character.
yThe Y coordinate, in pixels, for where to draw the character.
cThe value of the character to be drawn.
colorthe forground color of the character.
bgthe background color of the character.
sizeThe size of the character to draw.

The specified character is drawn starting at the provided coordinate. The point specified by the X and Y coordinates will be the top left corner of the character. The character will be rendered using the library's font5x7 font.

Note
This is a low level function used by the write() function to draw a character. Although it's available as a public function, it wouldn't normally be used. In most cases the Arduino Print class should be used for writing text.
See also
Print write() font5x7

Definition at line 1334 of file Arduboy2.cpp.

◆ drawCircle()

void Arduboy2Base::drawCircle ( int16_t  x0,
int16_t  y0,
uint8_t  r,
uint8_t  color = WHITE 
)
staticinherited

Draw a circle of a given radius.

Parameters
x0The X coordinate of the circle's center.
y0The Y coordinate of the circle's center.
rThe radius of the circle in pixels.
colorThe circle's color (optional; defaults to WHITE).
See also
fillCircle()

Definition at line 362 of file Arduboy2.cpp.

◆ drawCompressed()

void Arduboy2Base::drawCompressed ( int16_t  sx,
int16_t  sy,
const uint8_t *  bitmap,
uint8_t  color = WHITE 
)
staticinherited

Draw a bitmap from an array of compressed data.

Parameters
sxThe X coordinate of the top left pixel affected by the bitmap.
syThe Y coordinate of the top left pixel affected by the bitmap.
bitmapA pointer to the compressed bitmap array in program memory.
colorThe color of pixels for bits set to 1 in the bitmap. (optional; defaults to WHITE).

Draw a bitmap starting at the given coordinates using an array that has been compressed using an RLE algorthm implemented by Team A.R.G.

The height of the image must be a multiple of 8 pixels (8, 16, 24, 32, ...). The width can be any size.

Bits set to 1 in the provided bitmap array (after decoding) will have their corresponding pixel set to the specified color. For bits set to 0 in the array, the corresponding pixel will be left unchanged.

The array must be located in program memory by using the PROGMEM modifier.

Note
C source code for a command line program named Cabi, which can convert a PNG bitmap image file to source code suitable for use with drawCompressed(), is included in the extras directory of the library.
See also
drawBitmap() drawSlowXYBitmap()

Definition at line 902 of file Arduboy2.cpp.

◆ drawFastHLine()

void Arduboy2Base::drawFastHLine ( int16_t  x,
int16_t  y,
uint8_t  w,
uint8_t  color = WHITE 
)
staticinherited

Draw a horizontal line.

Parameters
xThe X coordinate of the left start point.
yThe Y coordinate of the left start point.
wThe width of the line.
colorThe color of the line (optional; defaults to WHITE).
See also
drawFastVLine() drawLine()

Definition at line 557 of file Arduboy2.cpp.

◆ drawFastVLine()

void Arduboy2Base::drawFastVLine ( int16_t  x,
int16_t  y,
uint8_t  h,
uint8_t  color = WHITE 
)
staticinherited

Draw a vertical line.

Parameters
xThe X coordinate of the upper start point.
yThe Y coordinate of the upper start point.
hThe height of the line.
colorThe color of the line (optional; defaults to WHITE).
See also
drawFastHLine() drawLine()

Definition at line 547 of file Arduboy2.cpp.

◆ drawLine()

void Arduboy2Base::drawLine ( int16_t  x0,
int16_t  y0,
int16_t  x1,
int16_t  y1,
uint8_t  color = WHITE 
)
staticinherited

Draw a line between two specified points.

Parameters
x0,x1The X coordinates of the line ends.
y0,y1The Y coordinates of the line ends.
colorThe line's color (optional; defaults to WHITE).

Draw a line from the start point to the end point using Bresenham's algorithm. The start and end points can be at any location with respect to the other.

See also
drawFastHLine() drawFastVLine()

Definition at line 487 of file Arduboy2.cpp.

◆ drawPixel()

void Arduboy2Base::drawPixel ( int16_t  x,
int16_t  y,
uint8_t  color = WHITE 
)
staticinherited

Set a single pixel in the display buffer to the specified color.

Parameters
xThe X coordinate of the pixel.
yThe Y coordinate of the pixel.
colorThe color of the pixel (optional; defaults to WHITE).

The single pixel specified location in the display buffer is set to the specified color. The values WHITE or BLACK can be used for the color. If the color parameter isn't included, the pixel will be set to WHITE.

Definition at line 295 of file Arduboy2.cpp.

◆ drawRect()

void Arduboy2Base::drawRect ( int16_t  x,
int16_t  y,
uint8_t  w,
uint8_t  h,
uint8_t  color = WHITE 
)
staticinherited

Draw a rectangle of a specified width and height.

Parameters
xThe X coordinate of the upper left corner.
yThe Y coordinate of the upper left corner.
wThe width of the rectangle.
hThe height of the rectangle.
colorThe color of the pixel (optional; defaults to WHITE).
See also
fillRect() drawRoundRect() fillRoundRect()

Definition at line 538 of file Arduboy2.cpp.

◆ drawRoundRect()

void Arduboy2Base::drawRoundRect ( int16_t  x,
int16_t  y,
uint8_t  w,
uint8_t  h,
uint8_t  r,
uint8_t  color = WHITE 
)
staticinherited

Draw a rectangle with rounded corners.

Parameters
xThe X coordinate of the left edge.
yThe Y coordinate of the top edge.
wThe width of the rectangle.
hThe height of the rectangle.
rThe radius of the semicircles forming the corners.
colorThe color of the rectangle (optional; defaults to WHITE).
See also
fillRoundRect() drawRect() fillRect()

Definition at line 666 of file Arduboy2.cpp.

◆ drawSlowXYBitmap()

void Arduboy2Base::drawSlowXYBitmap ( int16_t  x,
int16_t  y,
const uint8_t *  bitmap,
uint8_t  w,
uint8_t  h,
uint8_t  color = WHITE 
)
staticinherited

Draw a bitmap from a horizontally oriented array in program memory.

Parameters
xThe X coordinate of the top left pixel affected by the bitmap.
yThe Y coordinate of the top left pixel affected by the bitmap.
bitmapA pointer to the bitmap array in program memory.
wThe width of the bitmap in pixels.
hThe height of the bitmap in pixels.
colorThe color of pixels for bits set to 1 in the bitmap. (optional; defaults to WHITE).

Bits set to 1 in the provided bitmap array will have their corresponding pixel set to the specified color. For bits set to 0 in the array, the corresponding pixel will be left unchanged.

Each byte in the array specifies a horizontal row of 8 pixels, with the most significant bit at the left end of the row.

The array must be located in program memory by using the PROGMEM modifier.

Note
This function requires a lot of additional CPU power and will draw images slower than drawBitmap(), which uses bitmaps that are stored in a format that allows them to be directly written to the screen. It is recommended you use drawBitmap() when possible.
See also
drawBitmap() drawCompressed()

Definition at line 849 of file Arduboy2.cpp.

◆ drawTriangle()

void Arduboy2Base::drawTriangle ( int16_t  x0,
int16_t  y0,
int16_t  x1,
int16_t  y1,
int16_t  x2,
int16_t  y2,
uint8_t  color = WHITE 
)
staticinherited

Draw a triangle given the coordinates of each corner.

Parameters
x0,x1,x2The X coordinates of the corners.
y0,y1,y2The Y coordinates of the corners.
colorThe triangle's color (optional; defaults to WHITE).

A triangle is drawn by specifying each of the three corner locations. The corners can be at any position with respect to the others.

See also
fillTriangle()

Definition at line 692 of file Arduboy2.cpp.

◆ everyXFrames()

bool Arduboy2Base::everyXFrames ( uint8_t  frames)
staticinherited

Indicate if the specified number of frames has elapsed.

Parameters
framesThe desired number of elapsed frames.
Returns
true if the specified number of frames has elapsed.

This function should be called with the same value each time for a given event. It will return true if the given number of frames has elapsed since the previous frame in which it returned true.

For example, if you wanted to fire a shot every 5 frames while the A button is being held down:

if (arduboy.everyXFrames(5)) {
if arduboy.pressed(A_BUTTON) {
fireShot();
}
}
See also
setFrameRate() setFrameDuration() nextFrame()

Definition at line 232 of file Arduboy2.cpp.

◆ exitToBootloader()

void Arduboy2Core::exitToBootloader ( )
staticinherited

Exit the sketch and start the bootloader.

The sketch will exit and the bootloader will be started in command mode. The effect will be similar to pressing the reset button.

This function is intended to be used to allow uploading a new sketch, when the USB code has been removed to gain more code space. Ideally, the sketch would present a "New Sketch Upload" menu or prompt telling the user to "Press and hold the DOWN button when the procedure to upload a new sketch has been initiated". The sketch would then wait for the DOWN button to be pressed and then call this function.

See also
ARDUBOY_NO_USB

Definition at line 587 of file Arduboy2Core.cpp.

◆ fillCircle()

void Arduboy2Base::fillCircle ( int16_t  x0,
int16_t  y0,
uint8_t  r,
uint8_t  color = WHITE 
)
staticinherited

Draw a filled-in circle of a given radius.

Parameters
x0The X coordinate of the circle's center.
y0The Y coordinate of the circle's center.
rThe radius of the circle in pixels.
colorThe circle's color (optional; defaults to WHITE).
See also
drawCircle()

Definition at line 444 of file Arduboy2.cpp.

◆ fillRect()

void Arduboy2Base::fillRect ( int16_t  x,
int16_t  y,
uint8_t  w,
uint8_t  h,
uint8_t  color = WHITE 
)
staticinherited

Draw a filled-in rectangle of a specified width and height.

Parameters
xThe X coordinate of the upper left corner.
yThe Y coordinate of the upper left corner.
wThe width of the rectangle.
hThe height of the rectangle.
colorThe color of the pixel (optional; defaults to WHITE).
See also
drawRect() drawRoundRect() fillRoundRect()

Definition at line 608 of file Arduboy2.cpp.

◆ fillRoundRect()

void Arduboy2Base::fillRoundRect ( int16_t  x,
int16_t  y,
uint8_t  w,
uint8_t  h,
uint8_t  r,
uint8_t  color = WHITE 
)
staticinherited

Draw a filled-in rectangle with rounded corners.

Parameters
xThe X coordinate of the left edge.
yThe Y coordinate of the top edge.
wThe width of the rectangle.
hThe height of the rectangle.
rThe radius of the semicircles forming the corners.
colorThe color of the rectangle (optional; defaults to WHITE).
See also
drawRoundRect() drawRect() fillRect()

Definition at line 681 of file Arduboy2.cpp.

◆ fillScreen()

void Arduboy2Base::fillScreen ( uint8_t  color = WHITE)
staticinherited

Fill the screen buffer with the specified color.

Parameters
colorThe fill color (optional; defaults to WHITE).
See also
clear()

Definition at line 618 of file Arduboy2.cpp.

◆ fillTriangle()

void Arduboy2Base::fillTriangle ( int16_t  x0,
int16_t  y0,
int16_t  x1,
int16_t  y1,
int16_t  x2,
int16_t  y2,
uint8_t  color = WHITE 
)
staticinherited

Draw a filled-in triangle given the coordinates of each corner.

Parameters
x0,x1,x2The X coordinates of the corners.
y0,y1,y2The Y coordinates of the corners.
colorThe triangle's color (optional; defaults to WHITE).

A triangle is drawn by specifying each of the three corner locations. The corners can be at any position with respect to the others.

See also
drawTriangle()

Definition at line 700 of file Arduboy2.cpp.

◆ flashlight()

void Arduboy2Base::flashlight ( )
staticinherited

Turn the RGB LED and display fully on to act as a small flashlight/torch.

Checks if the UP button is pressed and if so turns the RGB LED and all 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 should be called by a sketch after boot() unless safeMode() is called instead.

Note

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 use boot() instead of begin(), a call to flashlight() should be included after calling boot(). If program space is limited, safeMode() can be used instead of flashlight().

See also
begin() boot() safeMode()

Definition at line 62 of file Arduboy2.cpp.

◆ flipHorizontal()

void Arduboy2Core::flipHorizontal ( bool  flipped)
staticinherited

Flip the display horizontally or set it back to normal.

Parameters
flippedtrue will set horizontal flip mode. false will set normal horizontal orientation.

Calling this function with a value of true will cause the X coordinate to start at the left edge of the display instead of the right, effectively flipping the display horizontally.

Once in horizontal flip mode, it will remain this way until normal horizontal mode is set by calling this function with a value of false.

See also
flipVertical()

Definition at line 434 of file Arduboy2Core.cpp.

◆ flipVertical()

void Arduboy2Core::flipVertical ( bool  flipped)
staticinherited

Flip the display vertically or set it back to normal.

Parameters
flippedtrue will set vertical flip mode. false will set normal vertical orientation.

Calling this function with a value of true will cause the Y coordinate to start at the bottom edge of the display instead of the top, effectively flipping the display vertically.

Once in vertical flip mode, it will remain this way until normal vertical mode is set by calling this function with a value of false.

See also
flipHorizontal()

Definition at line 428 of file Arduboy2Core.cpp.

◆ freeRGBled()

void Arduboy2Core::freeRGBled ( )
staticinherited

Relinquish analog control of the RGB LED.

Using the RGB LED in analog mode prevents further use of the LED in digital mode. This function will restore the pins used for the LED, so it can be used in digital mode.

See also
digitalWriteRGB() setRGBled()

Definition at line 487 of file Arduboy2Core.cpp.

◆ generateRandomSeed()

unsigned long Arduboy2Core::generateRandomSeed ( )
staticinherited

Create a seed suitable for use with a pseudorandom number generator.

Returns
A random value that can be used to seed a pseudorandom number generator.

The returned value will be a random value derived from entropy from an ADC reading of a floating pin combined with the microseconds since boot.

Note
This function will be more effective if called after a semi-random time, such as after waiting for the user to press a button to start a game, or another event that takes a variable amount of time after boot.
See also
Arduboy2Base::initRandomSeed()

Definition at line 564 of file Arduboy2Core.cpp.

◆ getBuffer()

uint8_t * Arduboy2Base::getBuffer ( )
staticinherited

Get a pointer to the display buffer in RAM.

Returns
A pointer to the display buffer array in RAM.

The location of the display buffer in RAM, which is displayed using display(), can be gotten using this function. The buffer can then be read and directly manipulated.

Note
The display buffer array, sBuffer, is public. A sketch can access it directly. Doing so may be more efficient than accessing it via the pointer returned by getBuffer().
See also
sBuffer

Definition at line 1007 of file Arduboy2.cpp.

◆ getCharacterHeight()

static constexpr uint8_t Arduboy2::getCharacterHeight ( uint8_t  textSize = 1)
inlinestaticconstexpr

Get the height, in pixels, of a character in the library's font.

Parameters
textSizeThe text size the character would be drawn at (optional; defaults to 1).
Returns
The height, in pixels, that a character will occupy.

Returns the height, in pixels, that a character will occupy when drawn using the library text functions. The result will be based on the provided text size, or size 1 if not included.

See also
getCharacterWidth() getLineSpacing() getTextSize() setTextSize() font5x7

Definition at line 2129 of file Arduboy2.h.

◆ getCharacterSpacing()

static constexpr uint8_t Arduboy2::getCharacterSpacing ( uint8_t  textSize = 1)
inlinestaticconstexpr

Get the number of pixels added after each character to provide spacing.

Parameters
textSizeThe text size the character would be drawn at (optional; defaults to 1).
Returns
The number of pixels of space added after each character.

Returns the number of pixels added to the right of each character, to provide spacing, when drawn by the library text functions. The result will be based on the provided text size, or size 1 if not included.

See also
getCharacterWidth() getLineSpacing() getTextSize() setTextSize() font5x7

Definition at line 2108 of file Arduboy2.h.

◆ getCharacterWidth()

static constexpr uint8_t Arduboy2::getCharacterWidth ( uint8_t  textSize = 1)
inlinestaticconstexpr

Get the width, in pixels, of a character in the library's font.

Parameters
textSizeThe text size the character would be drawn at (optional; defaults to 1).
Returns
The width, in pixels, that a character will occupy, not including inter-character spacing.

Returns the width, in pixels, occupied by a character in the font used by the library for text functions. The result will be based on the provided text size, or size 1 if not included. Since the font is monospaced, all characters will occupy the same width for a given text size.

The width does not include the spacing added after each character by the library text functions. The getCharacterSpacing() function can be used to obtain the character spacing value.

See also
getCharacterHeight() getCharacterSpacing() getTextSize() setTextSize() font5x7

Definition at line 2086 of file Arduboy2.h.

◆ getCursorX()

int16_t Arduboy2::getCursorX ( )
static

Get the X coordinate of the current text cursor position.

Returns
The X coordinate of the current text cursor position.

The X coordinate returned is a pixel location with 0 indicating the leftmost column.

See also
getCursorY() setCursor() setCursorX() setCursorY()

Definition at line 1433 of file Arduboy2.cpp.

◆ getCursorY()

int16_t Arduboy2::getCursorY ( )
static

Get the Y coordinate of the current text cursor position.

Returns
The Y coordinate of the current text cursor position.

The Y coordinate returned is a pixel location with 0 indicating the topmost row.

See also
getCursorX() setCursor() setCursorX() setCursorY()

Definition at line 1438 of file Arduboy2.cpp.

◆ getLineSpacing()

static constexpr uint8_t Arduboy2::getLineSpacing ( uint8_t  textSize = 1)
inlinestaticconstexpr

Get the number of pixels added below each character to provide line spacing.

Parameters
textSizeThe text size the character would be drawn at (optional; defaults to 1).
Returns
The number of pixels of space added below each character.

Returns the number of pixels added below each character, to provide spacing for wrapped lines, when drawn by the library text functions. The result will be based on the provided text size, or size 1 if not included.

Note
For this library, the value returned will be 0 because no spacing is added between lines. This function is included so that it can be used to write code that would be easily portable for use with a suite of equivalent functions that rendered text with added line spacing.
See also
getCharacterHeight() getCharacterSpacing() getTextSize() setTextSize() font5x7

Definition at line 2158 of file Arduboy2.h.

◆ getPixel()

uint8_t Arduboy2Base::getPixel ( uint8_t  x,
uint8_t  y 
)
staticinherited

Returns the state of the given pixel in the screen buffer.

Parameters
xThe X coordinate of the pixel.
yThe Y coordinate of the pixel.
Returns
WHITE if the pixel is on or BLACK if the pixel is off.

Definition at line 355 of file Arduboy2.cpp.

◆ getTextBackground()

uint8_t Arduboy2::getTextBackground ( )
static

Get the currently set text background color.

Returns
The background color that will be used to display any following text.
See also
setTextBackground() getTextColor()

Definition at line 1458 of file Arduboy2.cpp.

◆ getTextColor()

uint8_t Arduboy2::getTextColor ( )
static

Get the currently set text foreground color.

Returns
The color that will be used to display any following text.
See also
setTextColor() getTextBackground()

Definition at line 1448 of file Arduboy2.cpp.

◆ getTextRawMode()

bool Arduboy2::getTextRawMode ( )
static

Get the current state of text raw mode.

Returns
true if text raw mode is enabled, false if disabled.
See also
setTextRawMode()

Definition at line 1489 of file Arduboy2.cpp.

◆ getTextSize()

uint8_t Arduboy2::getTextSize ( )
static

Get the currently set text size.

Returns
The size that will be used for any following text.
See also
setTextSize() getCharacterWidth() getCharacterHeight() getCharacterSpacing() getLineSpacing() font5x7

Definition at line 1469 of file Arduboy2.cpp.

◆ getTextWrap()

bool Arduboy2::getTextWrap ( )
static

Get the currently set text wrap mode.

Returns
true if text wrapping is on, false if wrapping is off.
See also
setTextWrap()

Definition at line 1479 of file Arduboy2.cpp.

◆ height()

static constexpr uint8_t Arduboy2Core::height ( )
inlinestaticconstexprinherited

Get the height of the display in pixels.

Returns
The height of the display in pixels.

Definition at line 471 of file Arduboy2Core.h.

◆ idle()

void Arduboy2Core::idle ( )
staticinherited

Idle the CPU to save power.

This puts the CPU in idle sleep mode. You should call this as often as you can for the best power savings. The timer 0 overflow interrupt will wake up the chip every 1ms, so even at 60 FPS a well written app should be able to sleep maybe half the time in between rendering it's own frames.

Definition at line 278 of file Arduboy2Core.cpp.

◆ initRandomSeed()

void Arduboy2Base::initRandomSeed ( )
staticinherited

Seed the random number generator with a random value.

The Arduino pseudorandom number generator is seeded with the random value returned from a call to generateRandomSeed().

Note
This function will be more effective if called after a semi-random time, such as after waiting for the user to press a button to start a game, or another event that takes a variable amount of time after boot.
See also
generateRandomSeed()

Definition at line 283 of file Arduboy2.cpp.

◆ invert()

void Arduboy2Core::invert ( bool  inverse)
staticinherited

Invert the entire display or set it back to normal.

Parameters
inversetrue will invert the display. false will set the display to no-inverted.

Calling this function with a value of true will set the display to inverted mode. A pixel with a value of 0 will be on and a pixel set to 1 will be off.

Once in inverted mode, the display will remain this way until it is set back to non-inverted mode by calling this function with false.

Definition at line 415 of file Arduboy2Core.cpp.

◆ justPressed()

bool Arduboy2Base::justPressed ( uint8_t  button)
staticinherited

Check if a button has just been pressed.

Parameters
buttonThe button to test for. Only one button should be specified.
Returns
true if the specified button has just been pressed.

Return true if the given button was pressed between the latest call to pollButtons() and previous call to pollButtons(). If the button has been held down over multiple polls, this function will return false.

There is no need to check for the release of the button since it must have been released for this function to return true when pressed again.

This function should only be used to test a single button.

See also
pollButtons() justReleased()

Definition at line 1033 of file Arduboy2.cpp.

◆ justReleased()

bool Arduboy2Base::justReleased ( uint8_t  button)
staticinherited

Check if a button has just been released.

Parameters
buttonThe button to test for. Only one button should be specified.
Returns
true if the specified button has just been released.

Return true if the given button, having previously been pressed, was released between the latest call to pollButtons() and previous call to pollButtons(). If the button has remained released over multiple polls, this function will return false.

There is no need to check for the button having been pressed since it must have been previously pressed for this function to return true upon release.

This function should only be used to test a single button.

Note
There aren't many cases where this function would be needed. Wanting to know if a button has been released, without knowing when it was pressed, is uncommon.
See also
pollButtons() justPressed()

Definition at line 1038 of file Arduboy2.cpp.

◆ LCDCommandMode()

void Arduboy2Core::LCDCommandMode ( )
staticinherited

Put the display into command mode.

When placed in command mode, data that is sent to the display will be treated as commands.

See the SSD1306 controller and OLED display documents for available commands and command sequences.

Links:

Note
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 also
LCDDataMode() sendLCDCommand() SPItransfer()

Definition at line 225 of file Arduboy2Core.cpp.

◆ LCDDataMode()

void Arduboy2Core::LCDDataMode ( )
staticinherited

Put the display into data mode.

When placed in data mode, data that is sent to the display will be considered as data to be displayed.

Note
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 also
LCDCommandMode() SPItransfer()

Definition at line 220 of file Arduboy2Core.cpp.

◆ nextFrame()

bool Arduboy2Base::nextFrame ( )
staticinherited

Indicate that it's time to render the next frame.

Returns
true if it's time for the next frame.

When this function returns true, the amount of time has elapsed to display the next frame, as specified by setFrameRate() or setFrameDuration().

This function will normally be called at the start of the rendering loop which would wait for true to be returned before rendering and displaying the next frame.

example:

void loop() {
if (!arduboy.nextFrame()) {
return; // go back to the start of the loop
}
// render and display the next frame
}
See also
setFrameRate() setFrameDuration() nextFrameDEV()

Definition at line 237 of file Arduboy2.cpp.

◆ nextFrameDEV()

bool Arduboy2Base::nextFrameDEV ( )
staticinherited

Indicate that it's time to render the next frame, and visually indicate if the code is running slower than the desired frame rate. FOR USE DURING DEVELOPMENT

Returns
true if it's time for the next frame.

This function is intended to be used in place of nextFrame() during the development of a sketch. It does the same thing as nextFrame() but additionally will light the yellow TX LED (at the bottom, to the left of the USB connector) whenever a frame takes longer to generate than the time allotted per frame, as determined by the setFrameRate() or setFrameDuration() function.

Therefore, whenever the TX LED comes on (while not communicating over USB), it indicates that the sketch is running slower than the desired rate set by setFrameRate() or setFrameDuration(). In this case the developer may wish to set a slower frame rate, or reduce or optimize the code for such frames.

Note
Once a sketch is ready for release, it would be expected that nextFrameDEV() calls be restored to nextFrame().
See also
nextFrame() cpuLoad() setFrameRate() setFrameDuration()

Definition at line 265 of file Arduboy2.cpp.

◆ notPressed()

bool Arduboy2Base::notPressed ( uint8_t  buttons)
staticinherited

Test if the specified buttons are not pressed.

Parameters
buttonsA bit mask indicating which buttons to test. (Can be a single button)
Returns
true if all buttons in the provided mask are currently released.

Read the state of the buttons and return true if all the buttons in the specified mask are currently released.

Example: if (notPressed(UP_BUTTON))

Note
This function does not perform any button debouncing.
See also
pressed() anyPressed()

Definition at line 1022 of file Arduboy2.cpp.

◆ paint8Pixels()

void Arduboy2Core::paint8Pixels ( uint8_t  pixels)
staticinherited

Paint 8 pixels vertically to the display.

Parameters
pixelsA byte whose bits specify a vertical column of 8 pixels.

A byte representing a vertical column of 8 pixels is written to the display at the current page and column address. The address is then incremented. The page/column address will wrap to the start of the display (the top left) when it increments past the end (lower right).

The least significant bit represents the top pixel in the column. A bit set to 1 is lit, 0 is unlit.

Example:

X = lit pixels, . = unlit pixels

blank()                          paint8Pixels() 0xFF, 0, 0xF0, 0, 0x0F
v TOP LEFT corner (8x9)          v TOP LEFT corner
. . . . . . . . (page 1)         X . . . X . . . (page 1)
. . . . . . . .                  X . . . X . . .
. . . . . . . .                  X . . . X . . .
. . . . . . . .                  X . . . X . . .
. . . . . . . .                  X . X . . . . .
. . . . . . . .                  X . X . . . . .
. . . . . . . .                  X . X . . . . .
. . . . . . . . (end of page 1)  X . X . . . . . (end of page 1)
. . . . . . . . (page 2)         . . . . . . . . (page 2)

Definition at line 314 of file Arduboy2Core.cpp.

◆ paintScreen() [1/2]

void Arduboy2Core::paintScreen ( const uint8_t *  image)
staticinherited

Paints an entire image directly to the display from program memory.

Parameters
imageA byte array in program memory representing the entire contents of the display.

The contents of the specified array in program memory is written to the display. Each byte in the array represents a vertical column of 8 pixels with the least significant bit at the top. The bytes are written starting at the top left, progressing horizontally and wrapping at the end of each row, to the bottom right. The size of the array must exactly match the number of pixels in the entire display.

See also
paint8Pixels()

Definition at line 319 of file Arduboy2Core.cpp.

◆ paintScreen() [2/2]

void Arduboy2Core::paintScreen ( uint8_t  image[],
bool  clear = false 
)
staticinherited

Paints an entire image directly to the display from an array in RAM.

Parameters
imageA byte array in RAM representing the entire contents of the display.
clearIf true the array in RAM will be cleared to zeros upon return from this function. If false the RAM buffer will remain unchanged. (optional; defaults to false)

The contents of the specified array in RAM is written to the display. Each byte in the array represents a vertical column of 8 pixels with the least significant bit at the top. The bytes are written starting at the top left, progressing horizontally and wrapping at the end of each row, to the bottom right. The size of the array must exactly match the number of pixels in the entire display.

If parameter clear is set to true the RAM array will be cleared to zeros after its contents are written to the display.

See also
paint8Pixels()

Definition at line 333 of file Arduboy2Core.cpp.

◆ pollButtons()

void Arduboy2Base::pollButtons ( )
staticinherited

Poll the buttons and track their state over time.

Read and save the current state of the buttons and also keep track of the button state when this function was previously called. These states are used by the justPressed() and justReleased() functions to determine if a button has changed state between now and the previous call to pollButtons().

This function should be called once at the start of each new frame.

The justPressed() and justReleased() functions rely on this function.

example:

void loop() {
if (!arduboy.nextFrame()) {
return;
}
arduboy.pollButtons();
// use justPressed() as necessary to determine if a button was just pressed
Note
As long as the elapsed time between calls to this function is long enough, buttons will be naturally debounced. Calling it once per frame at a frame rate of 60 or lower (or possibly somewhat higher), should be sufficient.
See also
justPressed() justReleased() currentButtonState previousButtonState

Definition at line 1027 of file Arduboy2.cpp.

◆ pressed()

bool Arduboy2Base::pressed ( uint8_t  buttons)
staticinherited

Test if the all of the specified buttons are pressed.

Parameters
buttonsA bit mask indicating which buttons to test. (Can be a single button)
Returns
true if all buttons in the provided mask are currently pressed.

Read the state of the buttons and return true if all of the buttons in the specified mask are being pressed.

Example: if (pressed(LEFT_BUTTON | A_BUTTON))

Note
This function does not perform any button debouncing.
See also
anyPressed() notPressed()

Definition at line 1012 of file Arduboy2.cpp.

◆ readShowBootLogoFlag()

bool Arduboy2Base::readShowBootLogoFlag ( )
staticinherited

Read the "Show Boot Logo" flag in system EEPROM.

Returns
true if the flag is set to indicate that the boot logo sequence should be displayed. false if the flag is set to not display the boot logo sequence.

The "Show Boot Logo" flag is used to determine whether the system boot logo sequence is to be displayed when the system boots up. This function returns the value of this flag.

See also
writeShowBootLogoFlag() bootLogo()

Definition at line 1105 of file Arduboy2.cpp.

◆ readShowBootLogoLEDsFlag()

bool Arduboy2Base::readShowBootLogoLEDsFlag ( )
staticinherited

Read the "Show LEDs with boot logo" flag in system EEPROM.

Returns
true if the flag is set to indicate that the RGB LEDs should be flashed. false if the flag is set to leave the LEDs off.

The "Show LEDs with boot logo" flag is used to determine whether the RGB LEDs should be flashed in sequence while the boot logo is being displayed. This function returns the value of this flag.

See also
writeShowBootLogoLEDsFlag()

Definition at line 1131 of file Arduboy2.cpp.

◆ readShowUnitNameFlag()

bool Arduboy2Base::readShowUnitNameFlag ( )
staticinherited

Read the "Show Unit Name" flag in system EEPROM.

Returns
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.

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 also
writeShowUnitNameFlag() writeUnitName() readUnitName() Arduboy2::bootLogoExtra()

Definition at line 1118 of file Arduboy2.cpp.

◆ readUnitID()

uint16_t Arduboy2Base::readUnitID ( )
staticinherited

Read the unit ID from system EEPROM.

Returns
The value of the unit ID stored in system EEPROM.

This function reads the unit ID that has been set in system EEPROM. The ID can be any value. It is intended to allow different units to be uniquely identified.

See also
writeUnitID() readUnitName()

Definition at line 1057 of file Arduboy2.cpp.

◆ readUnitName()

uint8_t Arduboy2Base::readUnitName ( char *  name)
staticinherited

Read the unit name from system EEPROM.

Parameters
nameA pointer to the first element of a char array in which the unit name will be written. The name will be up to ARDUBOY_UNIT_NAME_LEN characters in length and additionally terminated with a null (0x00) character, so the provided array MUST be at least ARDUBOY_UNIT_NAME_BUFFER_SIZE characters long. Using ARDUBOY_UNIT_NAME_BUFFER_SIZE to specify the array length is the proper way to do this, although any array larger than ARDUBOY_UNIT_NAME_BUFFER_SIZE is also acceptable.
Returns
The length of the string (between 0 and ARDUBOY_UNIT_NAME_LEN inclusive).

This function reads the unit name that has been set in system EEPROM. The name represents characters in the library's font5x7 font. It can contain any values except 0xFF and the null (0x00) terminator value, plus the ASCII newline/line feed character (\n, 0x0A, inverse white circle) and ASCII carriage return character (\r, 0x0D, musical eighth note).

The name can be used for any purpose. It could identify the owner or give the unit itself a nickname. A sketch could use it to automatically fill in a name or initials in a high score table, or display it as the "player" when the opponent is the computer.

Note
The defined value ARDUBOY_UNIT_NAME_BUFFER_SIZE should be used to allocate an array to hold the unit name string, instead of using a hard coded value for the size. For example, to allocate a buffer and read the unit name into it:
// Buffer large enough to hold the unit name and a null terminator
// After the call, unitNameLength will contain the actual name length,
// not including the null terminator.
uint8_t unitNameLength = arduboy.readUnitName(unitName);
See also
writeUnitName() readUnitID() Arduboy2::bootLogoExtra() ARDUBOY_UNIT_NAME_BUFFER_SIZE ARDUBOY_UNIT_NAME_LEN Arduboy2::font5x7

Definition at line 1069 of file Arduboy2.cpp.

◆ safeMode()

void Arduboy2Core::safeMode ( )
staticinherited

Allow upload when the bootloader "magic number" could be corrupted.

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 don't call flashlight().

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 also
Arduboy2Base::flashlight() boot()

Definition at line 259 of file Arduboy2Core.cpp.

◆ sendLCDCommand()

void Arduboy2Core::sendLCDCommand ( uint8_t  command)
staticinherited

Send a single command byte to the display.

Parameters
commandThe command byte to send to the display.

The display will be set to command mode then the specified command byte will be sent. The display will then be set to data mode. Multi-byte commands can be sent by calling this function multiple times.

Note
Sending improper commands to the display can place it into invalid or unexpected states, possibly even causing physical damage.

Definition at line 406 of file Arduboy2Core.cpp.

◆ setCursor()

void Arduboy2::setCursor ( int16_t  x,
int16_t  y 
)
static

Set the location of the text cursor.

Parameters
xThe X (horizontal) coordinate, in pixels, for the new location of the text cursor.
yThe Y (vertical) coordinate, in pixels, for the new location of the text cursor.

The location of the text cursor is set the the specified coordinates. The coordinates are in pixels. Since the coordinates can specify any pixel location, the text does not have to be placed on specific rows. As with all drawing functions, location 0, 0 is the top left corner of the display. The cursor location represents the top left corner of the next character written.

See also
setCursorX() setCursorY() getCursorX() getCursorY()

Definition at line 1417 of file Arduboy2.cpp.

◆ setCursorX()

void Arduboy2::setCursorX ( int16_t  x)
static

Set the X coordinate of the text cursor location.

Parameters
xThe X (horizontal) coordinate, in pixels, for the new location of the text cursor.

The X coordinate for the location of the text cursor is set to the specified value, leaving the Y coordinate unchanged. For more details about the text cursor, see the setCursor() function.

See also
setCursor() setCursorY() getCursorX() getCursorY()

Definition at line 1423 of file Arduboy2.cpp.

◆ setCursorY()

void Arduboy2::setCursorY ( int16_t  y)
static

Set the Y coordinate of the text cursor location.

Parameters
yThe Y (vertical) coordinate, in pixels, for the new location of the text cursor.

The Y coordinate for the location of the text cursor is set to the specified value, leaving the X coordinate unchanged. For more details about the text cursor, see the setCursor() function.

See also
setCursor() setCursorX() getCursorX() getCursorY()

Definition at line 1428 of file Arduboy2.cpp.

◆ setFrameDuration()

void Arduboy2Base::setFrameDuration ( uint8_t  duration)
staticinherited

Set the frame rate, used by the frame control functions, by giving the duration of each frame.

Parameters
durationThe desired duration of each frame in milliseconds.

Set the frame rate by specifying the duration of each frame in milliseconds. This is used by nextFrame() to update frames at a given rate. If this function or setFrameRate() isn't used, the default will be 16ms per frame.

Normally, the frame rate would be set to the desired value once, at the start of the game, but it can be changed at any time to alter the frame update rate.

See also
nextFrame() setFrameRate()

Definition at line 227 of file Arduboy2.cpp.

◆ setFrameRate()

void Arduboy2Base::setFrameRate ( uint8_t  rate)
staticinherited

Set the frame rate used by the frame control functions.

Parameters
rateThe desired frame rate in frames per second.

Set the frame rate, in frames per second, used by nextFrame() to update frames at a given rate. If this function or setFrameDuration() isn't used, the default rate will be 60 (actually 62.5; see note below).

Normally, the frame rate would be set to the desired value once, at the start of the game, but it can be changed at any time to alter the frame update rate.

Note

The given rate is internally converted to a frame duration in milliseconds, rounded down to the nearest integer. Therefore, the actual rate will be equal to or higher than the rate given.

For example, 60 FPS would be 16.67ms per frame. This will be rounded down to 16ms, giving an actual frame rate of 62.5 FPS.

See also
nextFrame() setFrameDuration()

Definition at line 222 of file Arduboy2.cpp.

◆ setRGBled() [1/2]

void Arduboy2Core::setRGBled ( uint8_t  color,
uint8_t  val 
)
staticinherited

Set the brightness of one of the RGB LEDs without affecting the others.

Parameters
colorThe name of the LED to set. The value given should be one of RED_LED, GREEN_LED or BLUE_LED.
valThe brightness value for the LED, from 0 to 255.
Note
In order to use this function, the 3 parameter version must first be called at least once, in order to initialize the hardware.

This 2 parameter version of the function will set the brightness of a single LED within the RGB LED without affecting the current brightness of the other two. See the description of the 3 parameter version of this function for more details on the RGB LED.

See also
setRGBled(uint8_t, uint8_t, uint8_t) digitalWriteRGB() freeRGBled()

Definition at line 463 of file Arduboy2Core.cpp.

◆ setRGBled() [2/2]

void Arduboy2Core::setRGBled ( uint8_t  red,
uint8_t  green,
uint8_t  blue 
)
staticinherited

Set the light output of the RGB LED.

Parameters
red,green,blueThe brightness value for each LED.

The RGB LED is actually individual red, green and blue LEDs placed very close together in a single package. By setting the brightness of each LED, the RGB LED can show various colors and intensities. The brightness of each LED can be set to a value from 0 (fully off) to 255 (fully on).

Note
Certain libraries that take control of the hardware timers may interfere with the ability of this function to properly control the RGB LED. ArduboyPlaytune is one such library known to do this. The digitalWriteRGB() function will still work properly in this case.
Note
Many of the Kickstarter Arduboys were accidentally shipped with the RGB LED installed incorrectly. For these units, the green LED cannot be lit. As long as the green led is set to off, setting the red LED will actually control the blue LED and setting the blue LED will actually control the red LED. If the green LED is turned fully on, none of the LEDs will light.
See also
setRGBled(uint8_t, uint8_t) digitalWriteRGB() freeRGBled()

Definition at line 441 of file Arduboy2Core.cpp.

◆ setTextBackground()

void Arduboy2::setTextBackground ( uint8_t  bg)
static

Set the text background color.

Parameters
bgThe background color to be used for following text. The values WHITE or BLACK should be used.

The background pixels of following characters will be set to the specified color.

However, if the background color is set to be the same as the text color, the background will be transparent. Only the foreground pixels will be drawn. The background pixels will remain as they were before the character was drawn.

See also
setTextColor() getTextBackground()

Definition at line 1453 of file Arduboy2.cpp.

◆ setTextColor()

void Arduboy2::setTextColor ( uint8_t  color)
static

Set the text foreground color.

Parameters
colorThe color to be used for following text. The values WHITE or BLACK should be used.
See also
setTextBackground() getTextColor()

Definition at line 1443 of file Arduboy2.cpp.

◆ setTextRawMode()

void Arduboy2::setTextRawMode ( bool  raw)
static

Set or disable text raw mode, allowing special characters to be displayed.

Parameters
rawtrue enables text raw mode. false disables it.

In text raw mode, character values that would normally be treated specially will instead be displayed. The special characters are:

  • ASCII newline/line feed (\n, 0x0A, inverse white circle).
  • ASCII carriage return (\r, 0x0D, musical eighth note).

All other characters can be displayed regardless of whether raw mode is enabled or not.

See also
getTextRawMode() Print

Definition at line 1484 of file Arduboy2.cpp.

◆ setTextSize()

void Arduboy2::setTextSize ( uint8_t  s)
static

Set the text character size.

Parameters
sThe text size multiplier. Must be 1 or higher.

Setting a text size of 1 will result in standard size characters with one pixel for each bit in the bitmap for a character. The value specified is a multiplier. A value of 2 will double the width and height. A value of 3 will triple the dimensions, etc.

See also
getTextSize() getCharacterWidth() getCharacterHeight() getCharacterSpacing() getLineSpacing() font5x7

Definition at line 1463 of file Arduboy2.cpp.

◆ setTextWrap()

void Arduboy2::setTextWrap ( bool  w)
static

Set or disable text wrap mode.

Parameters
wtrue enables text wrap mode. false disables it.

Text wrap mode is enabled by specifying true. In wrap mode, if a character to be drawn would end up partially or fully past the right edge of the screen (based on the current text size), it will be placed at the start of the next line. The text cursor will be adjusted accordingly.

If wrap mode is disabled, characters will always be written at the current text cursor position. A character near the right edge of the screen may only be partially displayed and characters drawn at a position past the right edge of the screen will remain off screen.

See also
getTextWrap()

Definition at line 1474 of file Arduboy2.cpp.

◆ SPItransfer()

void Arduboy2Core::SPItransfer ( uint8_t  data)
staticinherited

Transfer a byte to the display.

Parameters
dataThe byte to be sent to the display.

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 also
LCDDataMode() LCDCommandMode() sendLCDCommand() SPItransferAndRead()

Definition at line 239 of file Arduboy2Core.cpp.

◆ SPItransferAndRead()

uint8_t Arduboy2Core::SPItransferAndRead ( uint8_t  data)
staticinherited

Transfer a byte to, and read a byte from, the SPI bus.

Parameters
dataThe byte to be sent.
Returns
The byte that was received.

This function does the same as the SPItransfer() function but also reads and returns the byte of data that was received during the transfer.

This function is of no use for a standard Arduboy, since only the display is connected to the SPI bus and data cannot be received from the display. It has been provided for use with homemade or expanded units that have had additional peripherals added to the SPI bus that are capable of sending data.

See also
SPItransfer()

Definition at line 253 of file Arduboy2Core.cpp.

◆ systemButtons()

void Arduboy2Base::systemButtons ( )
staticinherited

Handle buttons held on startup for system control.

This function is called by begin() and can be called by a sketch after boot().

Hold the B button when booting to enter system control mode. The B button must be held continuously to remain in this mode. Then, pressing other buttons will perform system control functions:

  • UP: Set "sound enabled" in EEPROM
  • DOWN: Set "sound disabled" (mute) in EEPROM
See also
begin() boot()

Definition at line 83 of file Arduboy2.cpp.

◆ waitNoButtons()

void Arduboy2Base::waitNoButtons ( )
staticinherited

Wait until all buttons have been released.

This function is called by begin() and can be called by a sketch after boot().

It won't return unless no buttons are being pressed. A short delay is performed each time before testing the state of the buttons to do a simple button debounce.

This function is called at the end of begin() to make sure no buttons used to perform system start up actions are still being pressed, to prevent them from erroneously being detected by the sketch code itself.

See also
begin() boot()

Definition at line 213 of file Arduboy2.cpp.

◆ width()

static constexpr uint8_t Arduboy2Core::width ( )
inlinestaticconstexprinherited

Get the width of the display in pixels.

Returns
The width of the display in pixels.

Definition at line 464 of file Arduboy2Core.h.

◆ write()

size_t Arduboy2::write ( uint8_t  c)
virtual

Write a single character at the current text cursor position.

Parameters
cThe value of the character to be written.
Returns
The number of characters written (will always be 1).

This is the Arduboy implemetation of the Arduino virtual write() function. The single character specified is written to the the screen buffer at the current text cursor position or possibly the start of the next line if text wrap mode is on. The text cursor is then set to the next character position.

Characters are rendered using the library's font5x7 font. Two character values are handled specially:

  • ASCII newline/line feed (\n, 0x0A, inverse white circle). This will move the text cursor position to the start of the next line, based on the current text size.
  • ASCII carriage return (\r, 0x0D, musical eighth note). This character will be ignored.

To override the special handling of the above values, to allow the characters they represent to be printed, text raw mode can be selected using the setTextRawMode() function.

Note
This function is rather low level and, although it's available as a public function, it wouldn't normally be used. In most cases the Arduino Print class should be used for writing text.
See also
Print setTextSize() setTextColor() setTextBackground() setTextWrap() setTextRawMode() drawChar() font5x7

Definition at line 1311 of file Arduboy2.cpp.

◆ writeShowBootLogoFlag()

void Arduboy2Base::writeShowBootLogoFlag ( bool  val)
staticinherited

Write the "Show Boot Logo" flag in system EEPROM.

Parameters
valIf true the flag is set to indicate that the boot logo sequence should be displayed. If false the flag is set to not display the boot logo sequence.

The "Show Boot Logo" flag is used to determine whether the system boot logo sequence is to be displayed when the system boots up. This function allows the flag to be saved with the desired value.

See also
readShowBootLogoFlag() bootLogo()

Definition at line 1110 of file Arduboy2.cpp.

◆ writeShowBootLogoLEDsFlag()

void Arduboy2Base::writeShowBootLogoLEDsFlag ( bool  val)
staticinherited

Write the "Show LEDs with boot logo" flag in system EEPROM.

Parameters
valIf true the flag is set to indicate that the RGB LEDs should be flashed. If false the flag is set to leave the LEDs off.

The "Show LEDs with boot logo" flag is used to determine whether the RGB LEDs should be flashed in sequence while the boot logo is being displayed. This function allows the flag to be saved with the desired value.

See also
readShowBootLogoLEDsFlag()

Definition at line 1136 of file Arduboy2.cpp.

◆ writeShowUnitNameFlag()

void Arduboy2Base::writeShowUnitNameFlag ( bool  val)
staticinherited

Write the "Show Unit Name" flag in system EEPROM.

Parameters
valIf 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.

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 also
readShowUnitNameFlag() writeUnitName() readUnitName() Arduboy2::bootLogoExtra()

Definition at line 1123 of file Arduboy2.cpp.

◆ writeUnitID()

void Arduboy2Base::writeUnitID ( uint16_t  id)
staticinherited

Write a unit ID to system EEPROM.

Parameters
idThe value of the unit ID to be stored in system EEPROM.

This function writes a unit ID to a reserved location in system EEPROM. The ID can be any value. It is intended to allow different units to be uniquely identified.

See also
readUnitID() writeUnitName()

Definition at line 1063 of file Arduboy2.cpp.

◆ writeUnitName()

void Arduboy2Base::writeUnitName ( const char *  name)
staticinherited

Write a unit name to system EEPROM.

Parameters
nameA pointer to the first element of a C-style null-terminated string containing the unit name to be saved. The name can be up to ARDUBOY_UNIT_NAME_LEN characters long and must be terminated with a null (0x00) character.

This function writes a unit name to a reserved area in system EEPROM. The name represents characters in the library's font5x7 font. It can contain any values except 0xFF and the null (0x00) terminator value, plus the ASCII newline/line feed character (\n, 0x0A, inverse white circle) and ASCII carriage return character (\r, 0x0D, musical eighth note) because of their special use by the library's text handling functions.

The name can be used for any purpose. It could identify the owner or give the unit itself a nickname. A sketch could use it to automatically fill in a name or initials in a high score table, or display it as the "player" when the opponent is the computer.

Note
The defined value ARDUBOY_UNIT_NAME_BUFFER_SIZE should be used to allocate an array to hold the unit name string, instead of using a hard coded value for the size.
See also
readUnitName() writeUnitID() Arduboy2::bootLogoExtra() ARDUBOY_UNIT_NAME_BUFFER_SIZE ARDUBOY_UNIT_NAME_LEN Arduboy2::font5x7

Definition at line 1089 of file Arduboy2.cpp.

Member Data Documentation

◆ arduboy_logo

const PROGMEM uint8_t Arduboy2Base::arduboy_logo
staticinherited
Initial value:
= {
0xF0, 0xF8, 0x9C, 0x8E, 0x87, 0x83, 0x87, 0x8E, 0x9C, 0xF8,
0xF0, 0x00, 0x00, 0xFE, 0xFF, 0x03, 0x03, 0x03, 0x03, 0x03,
0x07, 0x0E, 0xFC, 0xF8, 0x00, 0x00, 0xFE, 0xFF, 0x03, 0x03,
0x03, 0x03, 0x03, 0x07, 0x0E, 0xFC, 0xF8, 0x00, 0x00, 0xFF,
0xFF, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xFF, 0xFF,
0x00, 0x00, 0xFE, 0xFF, 0x83, 0x83, 0x83, 0x83, 0x83, 0xC7,
0xEE, 0x7C, 0x38, 0x00, 0x00, 0xF8, 0xFC, 0x0E, 0x07, 0x03,
0x03, 0x03, 0x07, 0x0E, 0xFC, 0xF8, 0x00, 0x00, 0x3F, 0x7F,
0xE0, 0xC0, 0x80, 0x80, 0xC0, 0xE0, 0x7F, 0x3F, 0xFF, 0xFF,
0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0xFF, 0xFF, 0x00,
0x00, 0xFF, 0xFF, 0x0C, 0x0C, 0x0C, 0x0C, 0x1C, 0x3E, 0x77,
0xE3, 0xC1, 0x00, 0x00, 0x7F, 0xFF, 0xC0, 0xC0, 0xC0, 0xC0,
0xC0, 0xE0, 0x70, 0x3F, 0x1F, 0x00, 0x00, 0x1F, 0x3F, 0x70,
0xE0, 0xC0, 0xC0, 0xC0, 0xE0, 0x70, 0x3F, 0x1F, 0x00, 0x00,
0x7F, 0xFF, 0xC1, 0xC1, 0xC1, 0xC1, 0xC1, 0xE3, 0x77, 0x3E,
0x1C, 0x00, 0x00, 0x1F, 0x3F, 0x70, 0xE0, 0xC0, 0xC0, 0xC0,
0xE0, 0x70, 0x3F, 0x1F, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
0xFF, 0xFF, 0x01, 0x00, 0x00, 0x00
}

The bitmap for the ARDUBOY logo in drawBitmap() format.

See also
bootLogo() drawBitmap()

Definition at line 1472 of file Arduboy2.h.

◆ arduboy_logo_compressed

const PROGMEM uint8_t Arduboy2Base::arduboy_logo_compressed
staticinherited
Initial value:
= {
0x57, 0x0F, 0x9C, 0x53, 0x72, 0x75, 0x29, 0xE5, 0x9C, 0x92,
0xCE, 0x95, 0x52, 0xAD, 0x4E, 0x49, 0xE7, 0x08, 0x09, 0xED,
0x76, 0xBB, 0xDD, 0x2A, 0xAB, 0xAC, 0x55, 0x92, 0x90, 0xD0,
0x6E, 0xB7, 0xDB, 0xAD, 0xB2, 0xCA, 0x5A, 0x25, 0xF9, 0xF8,
0xF0, 0xC6, 0x47, 0x48, 0x28, 0x95, 0x54, 0x52, 0x49, 0x25,
0x9D, 0x3A, 0x95, 0x5A, 0x3A, 0x45, 0x2A, 0xB7, 0x29, 0xA7,
0xE4, 0x76, 0xBB, 0x55, 0x56, 0x59, 0xAB, 0x24, 0x9F, 0x5D,
0x5B, 0x65, 0xD7, 0xE9, 0xEC, 0x92, 0x29, 0x3B, 0xA1, 0x4E,
0xA7, 0xD3, 0xE9, 0x74, 0x9A, 0x8F, 0x8F, 0xEF, 0xED, 0x76,
0xBB, 0x55, 0x4E, 0xAE, 0x52, 0xAD, 0x9C, 0x9C, 0x4F, 0xE7,
0xED, 0x76, 0xBB, 0xDD, 0x2E, 0x95, 0x53, 0xD9, 0x25, 0xA5,
0x54, 0xD6, 0x2A, 0xAB, 0xEC, 0x76, 0xBB, 0x54, 0x4E, 0x65,
0x97, 0x94, 0x3A, 0x22, 0xA9, 0xA4, 0x92, 0x4A, 0x2A, 0xE9,
0x94, 0x4D, 0x2D, 0x9D, 0xA2, 0x94, 0xCA, 0x5A, 0x65, 0x95,
0xDD, 0x6E, 0x97, 0xCA, 0xA9, 0xEC, 0x12, 0x55, 0x69, 0x42,
0x7A
}

The bitmap for the ARDUBOY logo in drawCompressed() format.

See also
bootLogoCompressed() drawCompressed()

Definition at line 1479 of file Arduboy2.h.

◆ arduboy_logo_sprite

const PROGMEM uint8_t Arduboy2Base::arduboy_logo_sprite
staticinherited
Initial value:
= {
88, 16,
0xF0, 0xF8, 0x9C, 0x8E, 0x87, 0x83, 0x87, 0x8E, 0x9C, 0xF8,
0xF0, 0x00, 0x00, 0xFE, 0xFF, 0x03, 0x03, 0x03, 0x03, 0x03,
0x07, 0x0E, 0xFC, 0xF8, 0x00, 0x00, 0xFE, 0xFF, 0x03, 0x03,
0x03, 0x03, 0x03, 0x07, 0x0E, 0xFC, 0xF8, 0x00, 0x00, 0xFF,
0xFF, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xFF, 0xFF,
0x00, 0x00, 0xFE, 0xFF, 0x83, 0x83, 0x83, 0x83, 0x83, 0xC7,
0xEE, 0x7C, 0x38, 0x00, 0x00, 0xF8, 0xFC, 0x0E, 0x07, 0x03,
0x03, 0x03, 0x07, 0x0E, 0xFC, 0xF8, 0x00, 0x00, 0x3F, 0x7F,
0xE0, 0xC0, 0x80, 0x80, 0xC0, 0xE0, 0x7F, 0x3F, 0xFF, 0xFF,
0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0xFF, 0xFF, 0x00,
0x00, 0xFF, 0xFF, 0x0C, 0x0C, 0x0C, 0x0C, 0x1C, 0x3E, 0x77,
0xE3, 0xC1, 0x00, 0x00, 0x7F, 0xFF, 0xC0, 0xC0, 0xC0, 0xC0,
0xC0, 0xE0, 0x70, 0x3F, 0x1F, 0x00, 0x00, 0x1F, 0x3F, 0x70,
0xE0, 0xC0, 0xC0, 0xC0, 0xE0, 0x70, 0x3F, 0x1F, 0x00, 0x00,
0x7F, 0xFF, 0xC1, 0xC1, 0xC1, 0xC1, 0xC1, 0xE3, 0x77, 0x3E,
0x1C, 0x00, 0x00, 0x1F, 0x3F, 0x70, 0xE0, 0xC0, 0xC0, 0xC0,
0xE0, 0x70, 0x3F, 0x1F, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
0xFF, 0xFF, 0x01, 0x00, 0x00, 0x00
}

The bitmap for the ARDUBOY logo in Sprites class drawSelfMasked() or drawOverwrite() format.

See also
bootLogoSpritesSelfMasked() bootLogoSpritesOverwrite() bootLogoSpritesBSelfMasked() bootLogoSpritesBOverwrite()

Definition at line 1488 of file Arduboy2.h.

◆ audio

Arduboy2Audio Arduboy2Base::audio
staticinherited

An object created to provide audio control functions within this class.

This object is created to eliminate the need for a sketch to create an Arduboy2Audio class object itself.

See also
Arduboy2Audio

Definition at line 227 of file Arduboy2.h.

◆ currentButtonState

uint8_t Arduboy2Base::currentButtonState = 0
staticinherited

Used by pollButtons() to hold the current button state.

Holds the last button state read by the pollButtons() function.

A sketch normally does not need to read or manipulate this variable and just lets pollButtons() handle it. Access to it is provided for special circumstances. See previousButtonState for further discussion.

See also
previousButtonState pollButtons() justPressed() justReleased()

Definition at line 1395 of file Arduboy2.h.

◆ font5x7

const PROGMEM uint8_t Arduboy2::font5x7
static

The font used for text functions.

This is a 5 pixel by 7 pixel font. Each character is actually coded as 8 pixels high to allow a 1 pixel descender below the baseline. Many symbols also use the 8th pixel. The library functions add a 1 pixel space after each character to separate them, so characters written at size 1 will occupy a 6 x 8 pixel area when drawn.

The character set represented is code page 437, also known as OEM 437, OEM-US, PC-8 or DOS Latin US. This is an 8 bit set which includes all printable ASCII characters plus many accented characters, symbols and line drawing characters.

The data for this font is from file glcdfont.c in the Adafruit GFX graphics library.

Note
With the library's text functions, the line drawing characters in the font won't touch on the left and right sides, as originally intended, because of the extra blank pixel added to the right of each character.
Note

The library's text functions, except drawChar(), handle two character values specially:

  • ASCII newline/line feed (\n, 0x0A, inverse white circle). This will move the text cursor position to the start of the next line, based on the current text size.
  • ASCII carriage return (\r, 0x0D, musical eighth note). This character will be ignored.

To override the special handling of the above values, to allow the characters they represent to be printed, text raw mode can be selected using the setTextRawMode() function.

See also
Print write() drawChar() setTextRawMode() getCharacterWidth() getCharacterHeight() getCharacterSpacing() getLineSpacing() readUnitName() writeUnitName()

Definition at line 2208 of file Arduboy2.h.

◆ frameCount

uint16_t Arduboy2Base::frameCount = 0
staticinherited

A counter which is incremented once per frame.

This counter is incremented once per frame when using the nextFrame() function. It will wrap to zero when it reaches its maximum value.

It could be used to have an event occur for a given number of frames, or a given number of frames later, in a way that wouldn't be quantized the way that using everyXFrames() might.

example:

// move for 10 frames when right button is pressed, if not already moving
if (!moving) {
if (arduboy.justPressed(RIGHT_BUTTON)) {
endMoving = arduboy.frameCount + 10;
moving = true;
}
} else {
movePlayer();
if (arduboy.frameCount == endMoving) {
moving = false;
}
}

This counter could also be used to determine the number of frames that have elapsed between events but the possibility of the counter wrapping would have to be accounted for.

See also
nextFrame() everyXFrames()

Definition at line 1381 of file Arduboy2.h.

◆ previousButtonState

uint8_t Arduboy2Base::previousButtonState = 0
staticinherited

Used by pollButtons() to hold the previous button state.

Holds the button state saved by the pollButtons() function from the previous to last call to it.

A sketch normally does not need to read or manipulate this variable and just lets pollButtons() handle it. Access to it is provided for special circumstances.

For example, the time between calls to pollButtons() must be long enough to allow sufficient time to "debounce" the buttons. pollButtons() is normally called once every frame but at a high frame rate the time between frames may be too short for this. Calling pollButtons() every 2nd frame could provide a long enough time but then a call to justPressed() in each frame would make it look like a button was pressed twice. To remedy this, after justPressed() detects a press, previousButtonState could be modified to acknowledge the button press.

void setup() {
arduboy.begin();
arduboy.setFrameRate(120); // too fast for button debounce
}
void loop() {
if (!arduboy.nextFrame()) {
return;
}
if (arduboy.everyXFrames(2)) { // only poll every 2nd frame
arduboy.pollButtons(); // to slow down poll frequency
}
if (justPressedOnce(A_BUTTON)) {
// handle button press as normal...
}
// remainder of loop() code...
}
bool justPressedOnce(uint8_t button) {
bool pressed = arduboy.justPressed(button);
if (pressed) {
arduboy.previousButtonState |= button; // set state as pressed
}
return pressed;
}
See also
currentButtonState pollButtons() justPressed() justReleased()

Definition at line 1451 of file Arduboy2.h.

◆ sBuffer

uint8_t Arduboy2Base::sBuffer
staticinherited

The display buffer array in RAM.

The display buffer (also known as the screen buffer) contains an image bitmap of the desired contents of the display, which is written to the display using the display() function. The drawing functions of this library manipulate the contents of the display buffer. A sketch can also access the display buffer directly.

See also
getBuffer()

Definition at line 1465 of file Arduboy2.h.


The documentation for this class was generated from the following files:
Arduboy2Base::pollButtons
static void pollButtons()
Poll the buttons and track their state over time.
Definition: Arduboy2.cpp:1027
Arduboy2Base::everyXFrames
static bool everyXFrames(uint8_t frames)
Indicate if the specified number of frames has elapsed.
Definition: Arduboy2.cpp:232
RIGHT_BUTTON
#define RIGHT_BUTTON
Definition: Arduboy2Core.h:68
A_BUTTON
#define A_BUTTON
Definition: Arduboy2Core.h:71
Arduboy2::bootLogoSpritesSelfMasked
void bootLogoSpritesSelfMasked()
Display the boot logo sequence using Sprites::drawSelfMasked().
Definition: Arduboy2.cpp:1203
Arduboy2Base::nextFrame
static bool nextFrame()
Indicate that it's time to render the next frame.
Definition: Arduboy2.cpp:237
ARDUBOY_UNIT_NAME_BUFFER_SIZE
#define ARDUBOY_UNIT_NAME_BUFFER_SIZE
The mininum number of characters required to store a null-terminated unit name.
Definition: Arduboy2.h:65
Arduboy2Base::pressed
static bool pressed(uint8_t buttons)
Test if the all of the specified buttons are pressed.
Definition: Arduboy2.cpp:1012
Arduboy2Base::readUnitName
static uint8_t readUnitName(char *name)
Read the unit name from system EEPROM.
Definition: Arduboy2.cpp:1069
Arduboy2Base::waitNoButtons
static void waitNoButtons()
Wait until all buttons have been released.
Definition: Arduboy2.cpp:213
Arduboy2Base::beginDoFirst
static void beginDoFirst()
Helper function that calls the inital functions used by begin()
Definition: Arduboy2.cpp:48