Arduboy2 - The Recommended Development Library

Development
1

Update November 11, 2016: The Arduboy2 library can now be easily installed using the Arduino IDE Library Manager:

  • In the Arduino IDE select from the menus: Sketch > Include Library > Manage Libraries...
  • In the Library Manager Filter your search… field enter arduboy2.
  • Click somewhere within the Arduboy2 entry.
  • Click on the Install button.

Update October 20, 2016: V2.1.0 released with Team A.R.G. Arglib capabilities added.
Team A.R.G. uses their Arglib library (which is based on an early version of the standard Arduboy library) for all of their excellent Arduboy games. The Arduboy2 library now includes most of the extra functionality that has been added to Arglib. This includes sprite drawing, button handling, collision detection and compressed image drawing functions.

Since “the powers that be” can’t seem to decide how to continue with development of the Arduboy library past V1.1, I decided to fork the Arduboy V1.2 development code myself and turn into an alternative library, which I call Arduboy2 (for lack of a better name). Yes, I know Arduboy2 could be interpreted as being meant for some new “next generation” of the Arduboy system, but what can you do? :confused:

See the README.md file in the repository for all the details, but the main goals and features of this new library are:

  • Allow more code space to be made available to sketches by, among other things,

  • removing the tunes functions and creating a separate library for them

  • allowing the “text” functions to be removed

  • allowing for having a minimal boot sequence which can eliminate any or all of the boot features, such as the boot logo and “flashlight”.

  • some optimization of the existing code

  • Allow other sound generation libraries and functions to be used. The tunes functions took over timer interrupts, which made it impossible for other libraries, which needed these interrupts, to work. The tunes functionality can be added back in using the now separate ArduboyPlaytune library. I’ve also written a new library to generate tones and tone sequences called ArduboyTones, which is efficient and uses substantially less code space than the tunes functions (but has different features). You can now even just use Arduino tone() (but using ArduboyTones will generate less code).

  • Fix the “frame rate” bug. The nextFrame() function was calculating the time to the next frame incorrectly. This has been fixed in Arduboy2. Update: There actually wasn’t a bug so this has been reverted to the original code.

  • Added a new boot up feature which allows the state of the audio enabled flag to be set and saved in system EEPROM, so all sketches with compliant handling of the flag will either come up muted or with sound on, as configured. Like other boot up features, this one can be left out to save code space. See the Audio mute control heading in the README.md file for details.

  • Allow Arduboy2 to coexist in the Arduino IDE alongside Arduboy library V1.1, so existing sketches can still use the Arduboy library without breaking. This is accomplished by using the name Arduboy2 for the library and class, so it’s different from Arduboy.

  • Maintain as close as possible compatibility with the existing Arduboy V1.1 API. Most of the API is identical except for the tunes functionality, which is slightly different due to using a separate external library. Most existing sketches can be converted to using Arduboy2 with minimal effort (which is detailed in README.md).

The Arduboy2 library is available now for your use. Feel free to use it for new sketch development or for further development of existing sketches.

Update: I’ve decided to just maintain Aduboy2 in my own repository as given above, and it can now be installed using the Arduino IDE Library Manager.
@ekem and/or other people of authority,
If you want Arduboy2 to become an “official” library, just say the word and create a new Arduboy2 repository under the Arduboy user on GitHub. I’ll try to get it up and running as quickly as possible. We could then start the process of making it available through the Arduino IDE Library Manager.

Discuss this topic

If you would like to talk about the Arduboy2 library, you can do so in your own topic OR go to this one:

Moderator Note:
Links to Team ARG’s website have been removed due to malicious new owners.

12 Likes
2

93 posts were merged into an existing topic: [Discuss] Arduboy2 Development Library

37

Version 3.0.0 of the Arduboy2 library has been released. There are only a few changes but I’ve spent a lot of time formatting and adding the details of the API in the source comments, so that documentation can be generated using Doxygen. The HTML files generated can be found at:

https://MLXXXp.github.io/documents/Arduino/libraries/Arduboy2/Doxygen/html/index.html

A generated PDF file can be found at:

Any feedback on this documentation is welcome.

The actual changes to the code are:

  • Renamed class ArduboyCore to Arduboy2Core and class ArduboyAudio to Arduboy2Audio, to make things more consistent and avoid possible future conflicts with the original Arduboy library. This is the reason for bumping up the major version number from 2 to 3, since any current sketch using ArduboyCore or ArduboyAudio directly will be broken (although there probably aren’t any).
  • Added the ability to optionally clear the RAM buffer after updating the display for functions display() and paintScreen().
  • Classes Arduboy2, Arduboy2Base, Arduboy2Core and Arduboy2Audio all declare friend class Arduboy2Ex. Sketches can create a local Arduboy2Ex class that will have access to protected and private members of these classes, for advanced situations where this ability would be helpful.
5 Likes
51

Arduboy2 library version 3.1.0 has been released and is available through the Arduino Library Manager.

What’s New:

  • Added new functions writeUnitName(), readUnitName(), writeUnitID() and readUnitID(). These allow a 6 character (or less) unit name and a 16 bit unit ID to be saved to and retrieved from a reserved location in system EEPROM.
  • Added a new example sketch, SetNameAndID, which allows the unit name and unit ID to be set or changed.
  • The Arduboy2 class’s bootLogo() function will display the unit name at the bottom of the screen after the logo stops scrolling. This feature is not available when using the Arduboy2Base class because it doesn’t include the text functions.
  • The boot logo sequence can now be bypassed by holding the RIGHT D-pad button when powering up or by pressing it when the logo is scrolling down.
  • Added function audio.toggle() to toggle the audio mute state.
  • Made the display buffer, sBuffer[], public for easier and more efficient direct access, instead of using a pointer obtained from getBuffer().
  • Made the frameCount variable public so that a local counter may not be required for the purpose.
  • Added function nextFrameDEV() for use in place of nextFrame() during sketch development. This works the same as nextFrame() but additionally will light the yellow TX LED whenever a frame takes longer to render than the time allotted per frame.

The documentation has been updated with all the details:
https://mlxxxp.github.io/documents/Arduino/libraries/Arduboy2/Doxygen/html/index.html

4 Likes
61

Arduboy2 library version 4.0.0 has been released and is available through the Arduino Library Manager. The complimentary sound library ArduboyPlaytune has also been updated to release 1.0.3, which has changes to help achieve some of the memory size reductions described below.

Release notes:

The main purpose of this release is to reduce code produced by the library, leaving more code space for the sketch itself. The overall size of a sketch will be reduced by around 600 to 1100 bytes, with around 1000 bytes being typical. The actual operation of the sketch will not be affected. This size reduction was mainly achieved by directly controlling the I/O pins and on chip peripherals, instead of using pinMode(), digitalWrite() and other Arduino library functions. Also, existing functions were optimized to reduce size.

  • nextFrame(), drawChar(), drawPixel(), readUnitName(), writeUnitName() and Sprites::drawPlusMask() functions have been optimized to reduce size. Thanks to @Dreamer3 for this.
  • The initRandomSeed() function uses a different technique which produces less code.
  • New functions bootLogoCompressed(), bootLogoSpritesSelfMasked() and bootLogoSpritesOverwrite() can be used in place of bootLogo() to reduce code size in cases where their drawing functions are shared with the same functions used by the sketch. Also, a bootLogoText() function was added that renders the logo as text instead of a bitmap, which can reduce code size at the expense of showing a logo that doesn’t look as good.
  • delayShort() function added for delays up to 65535 milliseconds. Using it in place of the Arduino delay() function will save a few bytes.

Other additions and changes:

  • drawPixel() function optimized for speed. Thanks to @Dreamer3 for this.
  • In addition to the current version of digitalWriteRGB(), which takes 3 parameters to control all 3 of the LEDs simultaneously, a new 2 parameter version has been added to allow controlling each individual LED by specifying the LED color and whether to turn it on or off.
  • The displaying of the unit name at the end of the boot logo sequence has been made optional, controlled by a flag set in the system EEPROM area. Functions writeShowUnitNameFlag() and readShowUnitNameFlag() have been added to read and write this flag. The SetNameAndID example sketch has been modified to allow setting the flag.
  • The flashlight() function has been improved to do a better job of allowing a new sketch to be uploaded when the current sketch causes bootloader “magic key” issues. It no longer allows the Down button to be used to continue the sketch, so the unit must now be rebooted after use. Also, function safeMode() has been made available as a lower memory replacement for flashlight().
  • New function SPItransfer() added to be used instead of the SPI library SPI.transfer() function.
  • displayOff() and displayOn() functions added to allow putting the display in a blanked low power state.
8 Likes
70

Arduboy2 library version 4.0.1 has been released and is available through the Arduino Library Manager.

This fixes a problem reported by @SerendipityDoDa.

Thanks go to @Pharap for determining the problem and assisting with the fix.

3 Likes
71

Arduboy2 library version 4.1.0 has been released and is available through the Arduino Library Manager.

It adds functions for getting the values currently set that control text rendering:
getTextSize(), getTextColor(), getTextBackground() and getTextWrap()

(getCursorX() and getCursorY() were already there previously.)

1 Like
111

Arduboy2 library version 5.0.0 has been released and is available through the Arduino Library Manager.

As usual, one main goal was to make more code space available to sketches.

Release notes:

New features:

  • Classes BeepPin1 and BeepPin2 added. These can be used to play simple tones on the speaker. They are very code efficient.
  • New example sketch BeepDemo demonstrates the use of the BeepPin classes.
  • Class SpritesB added as an alternative to Sprites. This class has the same functions as Sprites but will produce less code in many cases (at the expense of slower execution speed). Thanks, @dxb (Delio Brignoli)
  • The ability to eliminate the USB code that is normally included in the Arduino environment. This will free up a significant amount of code space but will require the user to do a manual reset in order to upload a new sketch. Thanks, @Dreamer3 (Josh Goebel) for the concept.
  • The ability to set a flag in system EEPROM that will bypass the boot logo sequence and go straight to the sketch. New functions writeShowBootLogoFlag() and readShowBootLogoFlag() allow setting and reading this the flag.
  • Example sketch SetNameAndID has been renamed to SetSystemEEPROM. The ability to set the “show boot logo” flag has been added to it. It can now also be used to erase the entire system EEPROM or user EEPROM areas.
  • A new 2 parameter version of setRGBled() allows setting an individual RGB LED, given the color and brightness.
  • New function freeRGBled(). Using setRGBled() will take over the RGB LED pins so that digitalWriteRGB() will no longer work. Calling freeRGBled() will restore the pins for use by digitalWriteRGB().
  • New example sketch RGBled demonstrates the use of the RGB LED in both digital and analog modes.
  • New function setFrameDuration() can set the frame rate as the time per frame (in milliseconds), as an alternative to using setFrameRate() to set the frame rate in frames per second.
  • The loop at the end of the begin() function that waits for all buttons to be released has been replaced by function waitNoButtons(). This is to make it easier to add the functionality back in if boot() is used instead of begin().

Fixed a problem in the Sprites drawPlusMask() function that sometimes caused bitmaps to be drawn improperly. Thanks, @Dreamer3 (Josh Goebel)

The speed that the boot logo scrolls down has been increased, so that the actual sketch code begins faster.

The ArduBreakout example sketch has been modified to use the BeepPin1 class instead of Arduino tone().

Functions that have been refactored to optimize for size and usually speed:

  • paintScreen(), which is used by display(), has been re-written in assembler. Thanks, @Mr.Blinky and @veritazz (Michael Gollnick)
  • setRGBled() directly controls the hardware, instead of using the Arduino analogWrite() function.
  • bootLogoShell() and bootLogoText()
  • drawCompressed(). Thanks, @Pharap and @Mr.Blinky
  • buttonsState(). Thanks, @Mr.Blinky
  • nextFrame()
  • begin() (by using display() instead of blank() to clear the display).
  • idle()

Minor clarifications and corrections to previous README.md and Doxygen documentation, plus:

  • Thanks, @eried (Erwin Ried) for correcting a typo in the everyXFrames() example code.
  • Added info on sketch EEPROM use to README.md
  • Changed characters used for Sprites examples to make them more readable.

Some of the code savings available by using this release:

  • Just recompiling an existing sketch using this new release will reduce code size. Based on testing, typical savings will be about 150 bytes, compared to version 4.1.0, but it could be more or less depending on library functions that the sketch uses.

  • If a sketch uses more than one of the Sprites class functions, switching to SpritesB will save about 360 bytes, as long as the slower rendering speed of SpritesB is acceptable.

  • Sketches that currently use the setRGBled() function will see a significant reduction in code size, on the order of hundreds of bytes.

  • Removing the USB code will save about 2700 bytes or more but you should carefully consider if you need to do this, due to the inconvenience and possible frustration it can cause users because of the requirement to manually reset the Arduboy in order to upload a new sketch. Also, it’s recommended that some of the code freed up be used to add a menu item or prompt that allows the user to perform a reset using the DOWN button (by calling the new exitToBootloader() function).

7 Likes
136

Arduboy2 library version 5.1.0 has been released and is available through the Arduino Library Manager.

There is only one significant change for this release:
A flag has been added to system EEPROM that will allow the RGB LED to remain off while the boot logo is being displayed. This flag can be set by uploading the SetSystemEEPROM example sketch.
File > Examples > Arduboy2 > SetSystemEEPROM

Functions writeShowBootLogoLEDsFlag() and readShowBootLogoLEDsFlag() have been added to the library, to allow manipulating the new flag.

For all sketches using the Arduboy2 library that include the boot logo, users can now customize each individual Arduboy so that it will do one of the following:

  • Perform all features of the boot logo sequence:

    • The logo scrolls down.
    • The RGB LED flashes red, green, blue.
    • If set, a custom Unit Name is displayed at the bottom of the screen after the logo stops scrolling.

    This is the default setting.

  • Display the logo and Unit Name but don’t flash the LEDs. The LEDs remain off.

  • Display the logo and LEDs but don’t show the Unit Name.

  • Display the logo only, not the Unit Name or LEDs.

  • Don’t display the boot logo sequence at all. Go straight to the sketch when the Arduboy is powered up or reset.

Note that for sketches that leave out the text functions of the library by using the Arduboy2Base class instead of the Arduboy2 class, the Unit Name won’t be displayed regardless of the “show Unit Name” EEPROM flag setting.

Note also that even if the logo is left enabled, it can be bypassed or aborted by pressing the RIGHT button when powering up or while the logo is scrolling down.

P.S. The Unit Name (up to 6 characters) can be set using the aforementioned SetSystemEEPROM example sketch.

1 Like
137

Arduboy2 library version 5.2.0 has been released and is available through the Arduino Library Manager.

Release change notes:

  • Added function generateRandomSeed(), which will return a random value suitable for seeding random number generators. (This new function is now used by the initRandomSeed() function.) Thanks @Pharap

  • Function drawPixel() has been rewritten to address an issue with the compiler introduced in Arduino V1.8.6. It has also been made static. Plus, it saves a few bytes of program memory. Thanks @Mr.Blinky

  • Constructors were added to the Point and Rect objects used for collision detection features. The collide() functions were made static. Thanks @Pharap

  • Minor cleanup of #include statements. Thanks @Pharap

7 Likes
138

Arduboy2 library version 5.2.1 has been released and is available through the Arduino Library Manager.

This release has only a few minor changes, which won’t affect the majority of users.

Release change notes:

  • Changed the loopto label in fillScreen() to a local label, to prevent a “symbol already defined” error under some circumstances. Thanks @blakewford

  • Exposed all Print::write() overloads in the inherited Print class. Thanks @Pharap

  • Added a CONTRIBUTING.md file, to specify how commit messages should be formatted.

3 Likes
143
144

Arduboy2 library version 5.3.0 has been released and is available through the Arduino Library Manager.

Release notes:

This is mainly just a general cleanup release.

A few functions have been added. Some existing functions have been improved but remain backwards compatible. Some code not considered part of the API has been isolated from public access. Many corrections, updates and additions were made to the documentation.

Unless they used certain undocumented parts of the library, existing sketches should compile properly using this release, with little or no changes in program size.

Changes of note:

  • Added new functions anyPressed(), setCursorX(), setCursorY(). Suggested by @Pharap

  • Added new function SPItransferAndRead(). Suggested by @Mr.Blinky

  • Made width() and height() functions constexpr. Thanks @Pharap

  • Made Rect and Point class constructors constexpr. Thanks @Pharap

  • Made writeUnitName() const-correct. Thanks @Pharap

  • Moved function generateRandomSeed() from Arduboy2Base to Arduboy2Core. Suggested by @Dreamer3 (yyyc514 on GitHub) (Josh Goebel)

  • Changed the font and boot logo arrays from being standalone to being public class members. With help and guidance from @Pharap

  • Changed the lcdBootProgram[] array from being standalone to being a protected member of Arduboy2Core.

  • Changed the values used to map system EEPROM from #define macros to protected constexpr members of Arduboy2Base.

  • Refactored the code provided for removing the USB stack. Suggested and developed by @Pharap

  • Fixed functions drawBitmap(), drawSlowXYBitmap() and drawCompressed(), which would sometimes wastefully execute code to draw when the bitmap was entirely off screen by just one pixel. Issue reported by @Mr.Blinky

  • Fixed portability issues in the Sprites classes. (This doesn’t change compiles for the Arduboy in any way.) Issues discovered and fixes developed by @Pharap

  • Fixed a minor visual glitch in the ArduBreakout example sketch. Submitted by @uXe (uXeBoy on GitHub) (Dan O’Shea)

  • Changed the ArduBreakout example sketch to use precomputed values for Beep function parameters, to reduce program size. Also did additional cleanup.

  • Added the Team A.R.G. Cabi program code into the extras directory. This is used to convert PNG files to bitmap arrays for the drawCompressed() function. With the demise of Team A.R.G. this program is no longer publicly available from them. The program has been cleaned up somewhat and more detailed documentation has been provided.

  • Applied the CC0 public domain dedication to the BeepDemo and RGBled example sketches.

  • Updated or removed outdated URLs in the documentation.

  • Added file VERSIONING.txt to document the files containing the release version number, which need to be updated for a new release.

  • Updated file Doxyfile to that of Doxygen version 1.8.18

Additional changes are noted in the commits.

Thanks to all those who contributed to this release.

The library documentation has been generated using a newer Doxygen version, 1.8.18 (Previously 1.8.11 was used), and a few values in the configuration file have been altered, so there are some changes in its appearance and operation.

5 Likes
145

Arduboy2 library version 6.0.0 has been released and is available through the Arduino Library Manager.

Many thanks go to @Pharap for suggestions and guidance with much of what has been done for this release.

Changes for this release:

  • All functions and variables that could be made static have been. The main purpose for doing this is that it reduces program size and RAM usage. Program savings can be anywhere from a just few bytes to a few thousand but it appears to typically be around 400 bytes for a sketch that uses the Arduboy2 class. Program savings aren’t as great for sketches using the Arduboy2Base class. RAM savings are generally around 15 bytes.

  • Added functions getCharacterWidth() getCharacterHeight() getCharacterSpacing() and getLineSpacing() to programmatically get the dimensions of characters rendered using the library text functions, given the desired text size. Sketches using these functions, rather than hard coding values in the sketch itself, may be clearer and more portable.

  • Added functions setTextRawMode() and getTextRawMode(). Text raw mode allows specially handled characters to be printed rather than them performing their usual action. Value \n (0x0a) will be drawn as an “inverse white circle” instead of performing a newline. Value \r (0x0d) will be drawn as a “musical eighth note” instead of it being ignored.

  • Functions write() and drawChar() were refactored for smaller code size, to handle raw mode, and changed slightly in the way they operate:

    • Checking if line wrap is necessary is done before drawing a character, instead of doing it after drawing to prepare for the next character. This fixed a problem with requested line feeds interacting with wrapping, resulting in unexpected blank lines.
    • Spacing added at the end of each character is no longer factored in when determining if a character will fit on screen at the end of a line.
    • Fixed a bug that caused the drawing of characters with a transparent background to not work properly. (This is selected by setting the background color to be the same as the text color.)

  • Made variables currentButtonState and previousButtonState public. This allows them to be used for special circumstances without needing to create a child class or alternative functions. An example of one possible use is given in the documentation for previousButtonState.

  • Added the array lengths to the comments for the boot logo bitmap arrays. Submitted by @ace-dent (forum user @acedent).

  • Added keywords for public variables to file keywords.txt

  • Added a check for the image height to the Cabi bitmap converter utility. It now exits with an error if the height isn’t the required multiple of 8 pixels. Also added this requirement to the documentation. Thanks to @unwiredben for suggesting this.

  • Added a new example sketch, FontDemo. This displays the entire library font and allows it to be moved around to demonstrate how text wrapping and raw mode works.

  • Fixed a bug in the BeepDemo example sketch where text on the screen was not positioned properly.

  • Refactored the SetSystemEEPROM utility sketch to use more C++ features and use the new library functions for character sizes.

  • Some additional enhancements and clarifications were made to the documentation.

  • A few other minor changes aren’t documented here, since they don’t affect anything regarding the API. See the repository commit messages for these.

Note that this release has the major version number changed, indicating some aspect of the API is not backwards compatible. This is only because there’s a chance that a sketch that enables text wrapping might behave differently, due to the changes in the way wrapping is now handled.

6 Likes