Lower level functions generally dealing directly with the hardware. More...

#include <Arduboy2Core.h>

Inheritance diagram for Arduboy2Core:

Static Public Member Functions
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...

Detailed Description

Lower level functions generally dealing directly with the hardware.

This class is inherited by Arduboy2Base and thus also Arduboy2, so wouldn't normally be used directly by a sketch.

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

Definition at line 335 of file Arduboy2Core.h.

Member Function Documentation

◆ allPixelsOn()

void Arduboy2Core::allPixelsOn ( bool on )

static

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.

◆ blank()

void Arduboy2Core::blank ( )

static

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

static

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.

◆ buttonsState()

uint8_t Arduboy2Core::buttonsState ( )

static

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.

◆ delayShort()

void Arduboy2Core::delayShort ( uint16_t ms )

static

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
	)

static

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
	)

static

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.

◆ displayOff()

void Arduboy2Core::displayOff ( )

static

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

static

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.

◆ exitToBootloader()

void Arduboy2Core::exitToBootloader ( )

static

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.

◆ flipHorizontal()

void Arduboy2Core::flipHorizontal ( bool flipped )

static

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 )

static

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

static

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

static

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.

◆ height()

static constexpr uint8_t Arduboy2Core::height ( )

inlinestaticconstexpr

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

static

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.

◆ invert()

void Arduboy2Core::invert ( bool inverse )

static

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.

◆ LCDCommandMode()

void Arduboy2Core::LCDCommandMode ( )

static

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

static

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.

◆ paint8Pixels()

void Arduboy2Core::paint8Pixels ( uint8_t pixels )

static

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 )

static

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`
	)

static

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.

◆ safeMode()

void Arduboy2Core::safeMode ( )

static

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 )

static

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.

◆ setRGBled() [1/2]

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

static

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
	)

static

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.

◆ SPItransfer()

void Arduboy2Core::SPItransfer ( uint8_t data )

static

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 )

static

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.

◆ width()

static constexpr uint8_t Arduboy2Core::width ( )

inlinestaticconstexpr

Get the width of the display in pixels.

Returns: The width of the display in pixels.

Definition at line 464 of file Arduboy2Core.h.

The documentation for this class was generated from the following files:

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ allPixelsOn()

◆ blank()

◆ boot()

◆ buttonsState()

◆ delayShort()

◆ digitalWriteRGB() [1/2]

◆ digitalWriteRGB() [2/2]

◆ displayOff()

◆ displayOn()

◆ exitToBootloader()

◆ flipHorizontal()

◆ flipVertical()

◆ freeRGBled()

◆ generateRandomSeed()

◆ height()

◆ idle()

◆ invert()

◆ LCDCommandMode()

◆ LCDDataMode()

◆ paint8Pixels()

◆ paintScreen() [1/2]

◆ paintScreen() [2/2]

◆ safeMode()

◆ sendLCDCommand()

◆ setRGBled() [1/2]

◆ setRGBled() [2/2]

◆ SPItransfer()

◆ SPItransferAndRead()

◆ width()