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

on	`true` 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

buttons A 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

drawLogo A 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

point	A structure describing the location of the point.
rect	A 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,rect2 Structures 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

ms	The 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

color	The name of the LED to set. The value given should be one of RED_LED, GREEN_LED or BLUE_LED.
val	Indicates 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,blue Use 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

clear If 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

x	The X coordinate of the top left pixel affected by the bitmap.
y	The Y coordinate of the top left pixel affected by the bitmap.
bitmap	A pointer to the bitmap array in program memory.
w	The width of the bitmap in pixels.
h	The height of the bitmap in pixels. Must be a multiple of 8.
color	The 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

x	The X coordinate, in pixels, for where to draw the character.
y	The Y coordinate, in pixels, for where to draw the character.
c	The value of the character to be drawn.
color	the forground color of the character.
bg	the background color of the character.
size	The 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

x0	The X coordinate of the circle's center.
y0	The Y coordinate of the circle's center.
r	The radius of the circle in pixels.
color	The 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

sx	The X coordinate of the top left pixel affected by the bitmap.
sy	The Y coordinate of the top left pixel affected by the bitmap.
bitmap	A pointer to the compressed bitmap array in program memory.
color	The 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

x	The X coordinate of the left start point.
y	The Y coordinate of the left start point.
w	The width of the line.
color	The 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

x	The X coordinate of the upper start point.
y	The Y coordinate of the upper start point.
h	The height of the line.
color	The 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,x1	The X coordinates of the line ends.
y0,y1	The Y coordinates of the line ends.
color	The 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

x	The X coordinate of the pixel.
y	The Y coordinate of the pixel.
color	The 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

x	The X coordinate of the upper left corner.
y	The Y coordinate of the upper left corner.
w	The width of the rectangle.
h	The height of the rectangle.
color	The 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

x	The X coordinate of the left edge.
y	The Y coordinate of the top edge.
w	The width of the rectangle.
h	The height of the rectangle.
r	The radius of the semicircles forming the corners.
color	The 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

x	The X coordinate of the top left pixel affected by the bitmap.
y	The Y coordinate of the top left pixel affected by the bitmap.
bitmap	A pointer to the bitmap array in program memory.
w	The width of the bitmap in pixels.
h	The height of the bitmap in pixels.
color	The 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,x2	The X coordinates of the corners.
y0,y1,y2	The Y coordinates of the corners.
color	The 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

frames The 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

x0	The X coordinate of the circle's center.
y0	The Y coordinate of the circle's center.
r	The radius of the circle in pixels.
color	The 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

x	The X coordinate of the upper left corner.
y	The Y coordinate of the upper left corner.
w	The width of the rectangle.
h	The height of the rectangle.
color	The 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

x	The X coordinate of the left edge.
y	The Y coordinate of the top edge.
w	The width of the rectangle.
h	The height of the rectangle.
r	The radius of the semicircles forming the corners.
color	The 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

color The 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,x2	The X coordinates of the corners.
y0,y1,y2	The Y coordinates of the corners.
color	The 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

flipped true 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

flipped true 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

textSize The 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

textSize The 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

textSize The 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

textSize The 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

x	The X coordinate of the pixel.
y	The 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

inverse true 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

button The 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

button The 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

buttons A 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

pixels A 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

image A 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

image	A byte array in RAM representing the entire contents of the display.
clear	If `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

buttons A 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

name A 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

char unitName[ARDUBOY_UNIT_NAME_BUFFER_SIZE];

// 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

command The 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

x	The X (horizontal) coordinate, in pixels, for the new location of the text cursor.
y	The 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

x	The 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

y	The 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

duration The 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

rate	The 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

color	The name of the LED to set. The value given should be one of RED_LED, GREEN_LED or BLUE_LED.
val	The 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,blue The 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

bg	The 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

color The 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

raw	`true` 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

s	The 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

w	`true` 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

data	The 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

data	The 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

c	The 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

val	If `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

val	If `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

val	If `true` the flag is set to indicate that the unit name should be displayed. If `false` the flag is set to not display the unit name.

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

id	The 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

name	A 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:

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Function Documentation

◆ allPixelsOn()

◆ anyPressed()

◆ begin()

◆ beginDoFirst()

◆ blank()

◆ boot()

◆ bootLogo()

◆ bootLogoCompressed()

◆ bootLogoExtra()

◆ bootLogoShell()

◆ bootLogoSpritesBOverwrite()

◆ bootLogoSpritesBSelfMasked()

◆ bootLogoSpritesOverwrite()

◆ bootLogoSpritesSelfMasked()

◆ bootLogoText()

◆ buttonsState()

◆ collide() [1/2]

◆ collide() [2/2]

◆ cpuLoad()

◆ delayShort()

◆ digitalWriteRGB() [1/2]

◆ digitalWriteRGB() [2/2]

◆ display() [1/2]

◆ display() [2/2]

◆ displayOff()

◆ displayOn()

◆ drawBitmap()

◆ drawChar()

◆ drawCircle()

◆ drawCompressed()

◆ drawFastHLine()

◆ drawFastVLine()

◆ drawLine()

◆ drawPixel()

◆ drawRect()

◆ drawRoundRect()

◆ drawSlowXYBitmap()

◆ drawTriangle()

◆ everyXFrames()

◆ exitToBootloader()

◆ fillCircle()

◆ fillRect()

◆ fillRoundRect()

◆ fillScreen()

◆ fillTriangle()

◆ flashlight()

◆ flipHorizontal()

◆ flipVertical()

◆ freeRGBled()

◆ generateRandomSeed()

◆ getBuffer()

◆ getCharacterHeight()

◆ getCharacterSpacing()

◆ getCharacterWidth()

◆ getCursorX()

◆ getCursorY()

◆ getLineSpacing()

◆ getPixel()

◆ getTextBackground()

◆ getTextColor()

◆ getTextRawMode()

◆ getTextSize()

◆ getTextWrap()

◆ height()

◆ idle()

◆ initRandomSeed()

◆ invert()

◆ justPressed()

◆ justReleased()

◆ LCDCommandMode()

◆ LCDDataMode()

◆ nextFrame()

◆ nextFrameDEV()

◆ notPressed()

◆ paint8Pixels()