Arduboy2 Library
Arduboy2Core Class Reference

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

#include <Arduboy2Core.h>

+ Inheritance diagram for Arduboy2Core:
+ Collaboration 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 void displayOff ()
 Turn the display off. More...
 
static void displayOn ()
 Turn the display on. More...
 
static uint8_t width ()
 Get the width of the display in pixels. More...
 
static 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 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 331 of file Arduboy2Core.h.

Member Function Documentation

void Arduboy2Core::allPixelsOn ( bool  on)
static

Turn all display pixels on or display the buffer contents.

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

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

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

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

Definition at line 416 of file Arduboy2Core.cpp.

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 394 of file Arduboy2Core.cpp.

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, if desired. See the README file or documentation on the main page for more details.

See also
Arduboy2Base::begin()

Definition at line 78 of file Arduboy2Core.cpp.

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 530 of file Arduboy2Core.cpp.

void Arduboy2Core::delayShort ( uint16_t  ms)
static

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

Parameters
msThe delay in milliseconds.

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

Definition at line 559 of file Arduboy2Core.cpp.

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,blueUse value RGB_ON or RGB_OFF to set each LED.

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

The colors are as follows:

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

Definition at line 490 of file Arduboy2Core.cpp.

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
colorThe name of the LED to set. The value given should be one of RED_LED, GREEN_LED or BLUE_LED.
valIndicates whether to turn the specified LED on or off. The value given should be RGB_ON or RGB_OFF.

This 2 parameter version of the function will set a single LED within the RGB LED either fully on or fully off. See the description of the 3 parameter version of this function for more details on the RGB LED.

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

Definition at line 504 of file Arduboy2Core.cpp.

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 285 of file Arduboy2Core.cpp.

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 296 of file Arduboy2Core.cpp.

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 564 of file Arduboy2Core.cpp.

void Arduboy2Core::flipHorizontal ( bool  flipped)
static

Flip the display horizontally or set it back to normal.

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

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

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

See also
flipVertical()

Definition at line 428 of file Arduboy2Core.cpp.

void Arduboy2Core::flipVertical ( bool  flipped)
static

Flip the display vertically or set it back to normal.

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

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

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

See also
flipHorizontal()

Definition at line 422 of file Arduboy2Core.cpp.

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 481 of file Arduboy2Core.cpp.

uint8_t Arduboy2Core::height ( )
static

Get the height of the display in pixels.

Returns
The height of the display in pixels.
Note
In most cases, the defined value HEIGHT would be better to use instead of this function.

Definition at line 303 of file Arduboy2Core.cpp.

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 268 of file Arduboy2Core.cpp.

void Arduboy2Core::invert ( bool  inverse)
static

Invert the entire display or set it back to normal.

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

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

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

Definition at line 409 of file Arduboy2Core.cpp.

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 222 of file Arduboy2Core.cpp.

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 217 of file Arduboy2Core.cpp.

void Arduboy2Core::paint8Pixels ( uint8_t  pixels)
static

Paint 8 pixels vertically to the display.

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

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

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

Example:

X = lit pixels, . = unlit pixels

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

Definition at line 308 of file Arduboy2Core.cpp.

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

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

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

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

See also
paint8Pixels()

Definition at line 313 of file Arduboy2Core.cpp.

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

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

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

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

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

See also
paint8Pixels()

Definition at line 327 of file Arduboy2Core.cpp.

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 potentially could cause the problem.

It is intended to replace the flashlight() function when more program space is required. If possible, it is more desirable to use flashlight(), so that the actual flashlight feature isn't lost.

See also
Arduboy2Base::flashlight() boot()

Definition at line 249 of file Arduboy2Core.cpp.

void Arduboy2Core::sendLCDCommand ( uint8_t  command)
static

Send a single command byte to the display.

Parameters
commandThe command byte to send to the display.

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

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

Definition at line 400 of file Arduboy2Core.cpp.

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

Set the light output of the RGB LED.

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

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

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

Definition at line 435 of file Arduboy2Core.cpp.

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

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

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

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

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

Definition at line 457 of file Arduboy2Core.cpp.

void Arduboy2Core::SPItransfer ( uint8_t  data)
static

Transfer a byte to the display.

Parameters
dataThe byte to be sent to the display.

Transfer one byte to the display over the SPI port and wait for the transfer to complete. The byte will either be interpreted as a command or as data to be placed on the screen, depending on the command/data mode.

See also
LCDDataMode() LCDCommandMode() sendLCDCommand()

Definition at line 236 of file Arduboy2Core.cpp.

uint8_t Arduboy2Core::width ( )
static

Get the width of the display in pixels.

Returns
The width of the display in pixels.
Note
In most cases, the defined value WIDTH would be better to use instead of this function.

Definition at line 301 of file Arduboy2Core.cpp.


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