v0.1.3 Beta

Tidyup, Better Releases, Breaking The API, Refinements & MAGIC!

Momentum on the firmware development front has continued, with many improvements both small and large finding their way into this release.

Prepare To Launcher

Thanks to @mikerr the Launcher now supports the analog stick and shows game version info.

I've also overhauled the D-Pad handling to avoid an issue where you could skip over multiple games if you were scrolling through quickly. This infuriated me!

As always @Daft-Freak is bashing the rough edges off things and has made multiple improvements to the Launcher (which is still part of the firmware at the moment) including handing duplicate game flashes and moving Mass Storage mode to a menu option (I'd press that button by accident every darn time).

Many of these tweaks lay the groundwork for removing the Launcher from firmware and making it a separate app that you can - if you wish - replace with your own. Crucially this allows the launcher to be big and fancy, beyond the confines of the small internal flash.

Precious Bytes

@Daft-Freak as added RLE - Run Length Encoding - support to packed spritesheets, with a counterpart change to the 32blit tool. You don't have to worry or think about it- it just happens. Turns out low-entropy, low-colour sprites pack well- who knew!?

Here's the size of some assets before/after compression:

tunnel                          18678    7755    -10923
gadgetoid_raycaster             19474    9756     -9718
flight                          10386    1279     -9107
s4m_ur4i_space_shooter_ships    10386    4544     -5842
s4m_ur4i_space_shooter_backdrop 10386    4597     -5789
s4m_ur4i_top_down_shooter       10374    5268     -5106
no_image                         6206    1289     -4917
s4m_ur4i_pirate_tilemap         10386    6778     -3608
s4m_ur4i_dingbads               12438    9000     -3438
babblesheet                      3250     754     -2496
s4m_ur4i_pirate_characters      12450    9958     -2492
s4m_ur4i_platformer             10386    7896     -2490
fire                             3226    1583     -1643
ship                             1106     558      -548
palette_swap                      838     494      -344
no_icon                            34      42         8
water                            2706    3024       318

You might notice that no_icon and water don't compress well- the tool will automatically output the non-RLE version for assets like this.

Precious Cycles

@zenodante has swooped in and fixed some bug in the dma2d flip, ekeing some more performance out of the blit. They also provided significant insight into my reworking of the System/Charge LED- which is now driven by SysTick_Handler saving a whole bunch of timer and interrupt faff and a chunk of CPU time. Not to mention saving a few bytes of that scarce internal flash.

Cleanup & Breaking API Changes

@Daft-Freak has cleaned up some API warts, giving us a debug function that supports all the good stuff without burdening the firmware.

If you use any of the API - that is the interface that handles calls into firmware functions like loading/saving files - in your game, you'll need to recompile it against this new release or it'll crash back to the Launcher.

Tooling Tweaks

The CMake tooling is a bit more explicit about what mystery meat it's downloading when you first configure your project. Hint: It's the position-independent custom stdlib required to get PIC games working.

@Daft-Freak has done some spring cleaning and purged old/defunct files. I've been wrangling CMake on some slower systems and have made it print which example it's configuring to avoid a long, awkward pause.

Could it be magic? Oh, OH!

@Daft-Freak has dropped another blit bombshell and tackled #192 - building a firmware update .blit that... uh... updates your firmware? It's ended up with the dry and descriptive name firmware-update, but we'll always know it as "magic". Remind me to make some sassy cover art to pay homage to that.

Right now the "firmware" is both the core 32blit device features - such as handling input, battery monitoring and other sundry operations not directly related to games - and the launcher, which installs and launches games. Being able to update this with one easy .blit package is enormously handy since it means no more messing around with DFU unless something goes truly awry.

You can drop firmware-update.blit on your SD card and run it with the launcher, or fire it at your 32blit with the tools using 32blit flash flash --file firmare-update.blit (or, as of v0.3.0, 32blit firmware-update.blit).

All firmware as of v0.1.3 should have a visble version number in the bottom right of the system menu.

Platform Shoes

You can now walk around, jump, swim, climb ladders and fall out of the level into a ceaseless oblivion in Platformer. Enjoy!

Complete list of changes...

As usual, for the complete list of changes see - v0.1.2...v0.1.3

v0.1.2 Beta

Bin to Blit, Bug Bashing ... mp3 support!?!?

There's probably a law against including significant new features in point releases, but we'd run out of numbers otherwise.

This release finally includes @Daft-Freak's mp3 playback support, which was so awesome it easily qualified as a core API feature. Can't be fussed to score your game in retro C64 style? Stick some mp3 intro music onto it!

We've also added a version check against the 32Blit tools, so you'll be warned if they're out of date, in addition to the old warning when they were not instaled.

Bin to Blit

Since we had .bin and .reloc.bin confusing everyone, it was finally time to settle upon a 32Blit file extension. By general Discord consensus we arrived at .blit. Succinct. Punchy. Short. Games are now game.blit instead of game.bin and the firmware has changed to reflect this.

You can rename old games from .bin to .blit and they will work, but you should probably recompile/rebuild.

Fixes

• Fixed my silly code in palette-swap so that ships are no longer 0px wide and invisible
• Unbroke matrix-test (thanks @Daft-Freak)

v0.1.1...v0.1.2

v0.1.1 Beta

Whoops

Slight bump over v0.1.0 to include .relo.bin files instead of .bin so they work correctly and support PIC! Whoops. (Thanks for noticing this @Daft-Freak)

v0.1.0 Beta

⚠️ Note: grab release files from v0.1.1 instead - https://github.com/pimoroni/32blit-beta/releases/tag/v0.1.1

Position-independent Code Extravaganza

We've finally bumped to our first minor release. Not only because I don't like hitting double-digit patch numbers, but because PIC - Position-independent Code - has finally been merged.

What, pray tell, does this mean? Well the concept of "PIC" in terms of 32Blit boils down to this: you can install more than one game at a time to external flash.

Normally code targeted at an embedded platform like this would have every "jump" from one place in code to another hard-coded as an absolute address in memory. This is fine when you're running one application, but if you try to flash a second game somewhere else in external flash- where it doesn't expect to be- then everything will quickly go awry. Position-independent jumps fix this problem by either jumping to a position relative to the current program counter, or - the somewhat more complicated approach - jumping via the GOT (Global Offset Table). I'll save a more detailed and technical (read: accurate) explanation for a separate article.

@Daft-Freak has undertaken a herculean effort to get "PIC" working on 32Blit, this involves a custom build of the C standard libraries, juggling code offsets, creatine the GOT, patching binaries on the fly as they get flashed from SD card to external flash and - really - more plumbing than you could shake a pointy stick at.

Since games on external flash launch instantly this means you can have your favourite games installed and ready to go.

Backward-compatibility

This release will still run binaries compiled against v0.0.9, but they will necessarily be flashed to the start of external flash and will make a mockery of your carefully curated list of favourites. This problem should correct itself quickly.

Changes

• PIC! Relocations, offsets, sorcery! (Thank you @Daft-Freak)
• sdl2-config.cmake will now auto-fetch the requires SDL libraries for Visual Studio
• Game save API! A more formal approach to handling savegames. (Thank you @Daft-Freak)
• Metadata title now set as window title for SDL builds
• Game flashes from SD card to external flash are now even faster (Thank you @Daft-Freak)

As usual for a full list of changes see: v0.0.9...v0.1.0

v0.0.9 Beta

A Timely Release of Bugfixes & Improvements

Every time I tag a new release, I vow to merge PIC and it never happens. (Edit: Update... It's been merged! AAAAAAA!)

Every time I tag a new release, I vow to do them more frequently and it never happens.

It's been a strange year.

I added silly images to the docs to make myself feel better.

Attention people with a final unit in your hands!

Your firmware was built against v0.0.8 Beta and that's where you should grab examples.

Your blit will also run Rocks And Diamonds v0.0.1 out of the box.

You're really going to want to familiarise yourself with flashing the firmware on your 32blit since the pace of development hasn't slowed, and we sadly didn't have something truly final to ship out with your units.

The feature creep has been truly real with this one, but every little extra step has been a truly killer feature and I challenge anyone to say the beta users haven't helped us turn the 32blit into a mind-boggling marvel considering it's just a wee microcontroller at heart.

Exciting things on the horizon

As if we haven't already seen more awesome things than we ever expected 32blit to do, the hard work is still not quite done.

PIC

PIC has been looming for too long now and it really is a huge, big deal for 32blit and it's the key that makes full use of the external flash possible along with some other cool things such as interpreters for script files (or.. cough.. dumps of games) and splitting the Launcher (user-facing main menu) out of the Firmware (gooey bits that make everything work).

See #435 for discussion.

Multiplayer

Another thing we didn't expect is multiplayer. Thanks to the hard work of @Daft-Freak I've got two 32blit handhelds talking to each other through a suspicious microUSB to microUSB OTG cable I acquired from a certain jungle-themed internet seller. Multiplayer is another thing that's been in the pipeline for a long time, and there's still a way to go with it- but it's coming!

See #320 for details and discussion.

Fixes

This really is just a small quality of life release with some key fixes and improvements.

• System Status/Power LED now works on final units
• Build tooling now uses .icns files in macOS bundles, oooh! (thanks @Daft-Freak)
• SD card access is NOW EVEN FASTER (thanks @Daft-Freak)
• Home+Reset and crash reset bug fixed, no more AAAH IT'S BRICKED? (It's not bricked) (thanks @Daft-Freak)
• Folders starting with "." are now hidden in the browser so you can hide your secrets (or game data?) in there

As usual you can see the difference between this release and the last, here: v0.0.8...v0.0.9

v0.0.8 Beta

So, many, changes

While I vowed to keep a monthly release schedule so I wasn't overwhelmed with changes every time I tag a new release, my workload got te better of me. It's been two months since v0.0.7 and there have been so many changes that GitHub's "compare" complaints and will only show me the most recent 250 commits.

What, no firmware?

The biggest change since v0.0.7 is the merge of #269, the culmination of a herculean multi-part effort from @Daft-Freak, with assists from us, to avoid compiling and linking the firmware against every game build. This means that 32blit .bin files are effectively "applications" which execute out of external flash (XiP) and the firmware is the "os" which executes out of the STM32s onboard flash.

This change is huge and shapes the future of 32blit and our eventual move into supporting multiple games saved onto external flash using position-independent code and some super clever on-the-fly patching (see #388).

Communication between games and firmware is facilitated by the 32blit API, a region of memory that both agree upon the location and contents of. You don't need to worry how this works under the hood- though- the 32blit engine takes care of it for you.

In summary this gives us:

1. Smaller .bin files
2. No need for you to compile all the heinous STM 32 HAL stuff to build a game
3. The ability for firmware to provide always-there features such as screenshots, power off, battery monitoring, input handling, etc
4. The groundwork for multiple games saved to external flash
5. The feeling of having accomplished something truly nutty on a microcontroller

Meta!

The second biggest change since v0.0.7 is metadata! A combo effort between myself and @Daft-Freak to append a title, description, author, version, cover art and icon to the .bin files saved to 32blit. More importantly- however, 32blit's firmware has been updated to parse and display this metadata so that browsing through a collection of games is easier and entirely more satisfying:

Oh and - thanks to some awesome macOS bundle efforts by @Daft-Freak - the same images can be used as 128x128 "icns" format icons in macOS too:

The metadata "splash" or "cover" image is 128x96 pixels and I've pixeled an adorable little 32blit console to fill some of that space if you're not feeling particularly artistic.

Continuous Integration

For reason we have switched from Travis to GitHub actions for CI and automated testing. Thank you to @Daft-Freak for making this happen while I was still wondering why builds were all stuck.

Update Your Tooling

The metadata building requires an up-to-date version of the 32blit Python tool. Don't forget to grab it!

Additionally we're considering dropping the Visual Studio solution files, since Visual Studio can open the CMake project directly and save something of a maintenance headache on all of the individual projects. If you're a VS user, your thoughts about this would be appreciated!

TLDR

Documentation:

In anticipation of 32blit consoles shipping out to regular backers, some beta users have also thrown themselves at the documentation and wider codebase fixing warts and bugs. Thanks to @shane-powell, @ahnlak and @Daft-Freak

For brevity mentally add (thanks @Daft-Freak) to most of the list items below.

New Stuff

• Metadata support for title, author, version, description and images
• SDL window title should be set from metadata title
• Added support for the LIS3DH accelerometer in the latest units
• Added support for reading spritesheets from a file
• You can now organise games into directories (1 level deep)
• UI for errors, and little UI hint icons to indicate which buttons do what
• Menu can now handle ALL THE ITEMS with scrolling and other fanciness
• Delete game button

Fixes

• Improvements to fixed-width text rendering (thanks @ahnlak)
• Fixed sprite unpacking to RGBA
• Screen now cleared in firmware init
• QSPI slightly unborked
• Handle SD card insert/remove
• Images with 256 colours? You bet!
• Fixes to function default arguments (thanks @ahnlak)

Tidyup

• Metadata everywhere!
• All examples converted to the "asset pipeline"
• GPIO init ... tidied up
• Battery bar tidied up a little
• Darwin toolchain and rogue VS solution files swept away
• Squashed. Many. Warnings.

Examples

• New tween demo to graph tween functions
• Shiny icons for most examples... some are lazy until inspiration strikes

As usual, the truncated list (well as many as GitHub will show anyway) of changes can be seen here: v0.0.7...v0.0.8

And changes prior to September 29th but since v0.0.7 can be seen here: v0.0.7...75b8330

v0.0.7 Beta

It's been a long time coming

It's been about 6 months since I tagged a new release and a lot has changed.

Daft Freak has, as usual, been an absolute legend; carrying the torch with numerous 32Blit software improvements while we've been tangled up surviving lockdown.

The codebase has moved forward to embrace C++17 features such as string_view, which now requires a minimum GCC version of 7, which added experimental support for these features. Ubuntu 20.04 is recommended and includes GCC 9. @Daft-Freak also supplies a PPA with a GCC backport for 18.04 users.

New Tooling Requirements

• CMake minimum version is now 3.8
• GCC minimum version is now GCC 7
• Python minimum version is 3.6

Screenshots

@Daft-Freak has graced 32Blit's firmware with the ability to dump the framebuffer into a .bmp file.

Just use the "Take Screenshot" option in the menu, and a numerically ordered "screenshotX.bmp" will be saved to the SD card.

Palette Mode

Also gracing this release, albeit it's been around for a while, is palette mode. We don't know if this is its final form but it makes a lot of sense for DOS ports. If my lockdown-addled, tired and rusty memory serves it was added by @Daft-Freak to support his DOOM port - https://github.com/Daft-Freak/32BlitDoom

Nicer Firmware Menu

@Daft-Freak has also ported some of our firmware menu enhancements into the master branch, this - at long last - brings the ability to have more games on 32Blit than is possible to fit on a single screen.

TLDR

Documentation:

Thank you to @shane-powell, @ahnlak and @mylogon341 for contributing to the documentation.

New stuff:

• new paletted screen mode! (thanks @Daft-Freak)
• Embedded/concatenated assets can be treated as files (thanks @Daft-Freak)
• Rename/remove added to file API (thanks @Daft-Freak)
• vec2 * vec2 (multiply operator) (thanks @Daft-Freak)
• firmware menu has a screenshot button! (thanks @Daft-Freak)
• firmware game list now scrolls, whee! (thanks @lowfatcode and @Daft-Freak)
• hard faults will now reset back to firmware, with an error screen (thanks @Daft-Freak)

API changes:

• blit::pi is the new math_pi or M_PI (thanks @Daft-Freak)
• all basic types are moved into the blit namespace (thanks @Daft-Freak)
• various methods converted to snake_case and other tidying (clang-tidy) (thanks @Daft-Freak)
• clip argument removed from text, now uses global clipping rect (thanks @Daft-Freak)
• blit::buttons is now a struct with .pressed and .released tracking (thanks @Daft-Freak)

Fixes, tweaks & tidyup:

• QSPI switched to 4-byte addressing for those tasty tasy high bytes (thanks @Daft-Freak)
• i2c bus speed bumped to 400KHz
• fixes to battery voltage ADC reading, increasing integration time
• multiple tweaks for code size reduction (thanks @Daft-Freak)
• fixed overflow/loading bugs in Surface (thanks @ymauray)
• fix audio timing from ~21633Hz to ~22048Hz (thanks @Daft-Freak)
• numerous SD card tweaks, fixes and performance enhancements (thanks @Daft-Freak)
• fixes & tweaks to 32Blit uploader tool (cpp) (thanks @illbewithee & @sminifie2)
• fixed game template not compiling with VS2019 (thanks @lenardg)
• tweaks to mass storage- can manually exit if not mounted, resets when USB disconnected (thanks @Daft-Freak)

Examples:

• Flight and Platformer now use asset pipeline (thanks @Daft-Freak)
• New jpeg example (thanks @Daft-Freak)

I've tried to highlight everything noteworthy- but it's a huge changeset. For a complete list of commits in this release, see: v0.0.6...v0.0.7

0.0.6 Beta

USB Mass Storage support is here, thank you to @AndrewCapon and @Daft-Freak for making this possible and spending countless hours negotiating its nuances and debugging its... uh... bugs.

UX Notes

• Pressing reset will no longer always take you back to the firmware. Hold HOME (left system button) and hit reset to reboot to firmware.
• Long pressing HOME will exit the current game and return to the firmware.
• Pressing "Menu" while in the firmware will enter USB Mass Storage Mode. Your 32Blit's SD card should mount as a disk on your host computer.

RGB888 Everywhere

After months and months of deliberation about what graphics modes are best for 32Blit and how to balance graphics modes with RAM availability we've landed on RGB888 everywhere.

The practical upshot of this is that, by default, the largest contiguous user RAM region is only 287K.

The reasons for this choice are:

1. It simplifies a lot of the code and lets us only care about one pixel format at once
2. It looks much better keeping everything 32bit throughout the system, instead of going from RGB888 -> RGB565 -> 18-bit LTDC -> Display.
3. It simplifies the tradeoff between Lores and Hires to just pixel-pushing performance.

We're investigating bringing true paletted mode to 32Blit based upon the LTDC palette support- this should give users an option to sacrifice colour depth for memory. Lots of memory.

Some good examples of why you might want to do this include the Another World and DOOM ports which both originated on paletted systems and gain no benefit from RGB888 mode.

TLDR

• USB Mass Storage! (thanks @AndrewCapon & @Daft-Freak)
• USB Serial now has a "SWIT" command to switch between firmware/game remotely
• Improvements to the Flight demo (except Mode7 support is still broken!) (thanks @mylogon341)
• Persistence has been moved to Backup SRAM, and 32Blit boots into the last used mode (Internal/External Flash) (thanks @AndrewCapon)
• Firmware shows filesize (useful for debugging) (thanks @ymauray)
• std::to_string(<float>) now works in ext flash builds (thanks @Daft-Freak)
• Tweaks, fixes, additions and improvements to the File API (thanks @Daft-Freak)
• New Font constructor to support loading of custom fonts (thanks @Daft-Freak)
• Audio Amp is now disabled unless audio is being played
• Engine builds are tagged with build info (thanks @Daft-Freak)
• System Menu now debounced a little better, and long pressing Home will exit the current game
• Visual Studio template now actually compiles! (thanks @ymauray)
• Prevented the firmware showing behind the system menu
• 32Blit hardware API has moved into a shared-memory region to prepare for PIC binaries!
• I2C - chiefly the battery management IC and accelerometer - has moved to an interrupt-driven state machine
• System menu now shows battery voltage, charge status and VBus status

Thanks to @ntwyman, @Daft-Freak and @mylogon341 for giving the documentation some TLC.

Known Issues

• Voxel is currently broken on device! This is either due to memory or compiler changes.

0.0.5 Beta

We're on the cusp of introducing Mass Storage support, thanks to another gargantuan effort from @AndrewCapon and support from @Daft-Freak.

As such there aren't a lot of new features. This release serves to roundup all of the changes and fixes to date and introduces the Voxel demo.

Asset Pipeline

The asset pipeline, including the ability to convert and pack raw/binary, map and image files has been moved to a new toolset which you can find here: https://github.com/pimoroni/32blit-tools/

We're a little thin on the ground with documentation, but @Gadgetoid's Rocks And Diamonds clone shows the use of the new blit_assets_yaml function in CMakeLists.txt.

In short, assets are now configured via a .yml file which can define any number/permutation of images, sprites, maps and more to be packed into a C++-compatible header file for your project.

The old method of asset building using blit_assets or blit_asset is now deprecated along with asset-builder, sprite-builder, map-builder and asset-packer which have been replaced by the new toolset.

USB CDC & Mass Storage

@AndrewCapon has been working tirelessly on USB Mass Storage support that's now waiting to be merged upstream. As a result of this effort several elusive bugs in the USB Serial and SD card implementations have been fixed. Hooray!

JPEG Decoding Support

As part of his marathon of making music and video play on the 32Blit @Daft-Freak has brought the STM32's built-in JPEG decoder online and added some userland functions for JPEG decoding.

It's one of those "we don't know who might have a use for this" additions, but on the off chance it makes a port easier, or enables some other cool project it's now upstream for your cat-picture-viewing pleasure.

TLDRBATITL

• Neat Class wrapper for the file API (thanks @Daft-Freak)
• Bugfix to file API to resolve symlinks correctly
• Tweaks to CDC Command Stream FIFO to fix uploads stalling at 99%
• Font now constexpr so unused fonts are discarded
• Int/Ext Linker script is now unified into one so it's much easier to hack on (thanks @ali1234)
• Support for decoding jpeg files (SDLimage now required for SDL builds)
• New demo: Voxel

As part of his work on USB Mass Storage @AndrewCapon (with assists from @Daft-Freak) gave the SD-card implementation a good thrashing, finding and fixing a multitude of small bugs:

• Patch SD_RxDataBlock() in fatfs_sd.c to avoid reading one byte too many
• Revert all @Gadgetoid's garbage changes to fatfs_sd.c (they caused issues with Mass Storage implementation)
• Patch fatfs_sd.c to correctly report larger card sizes

Thanks to @Daft-Freak this will be the first release using the much smaller Visual Studio based Windows builds!

0.0.4 Beta

Another release to wrap up some of the changes toward the end of this surprisingly eventful week.

First and foremost thank you @mylogon341 who has overhauled the guts of the system menu, making it a little easier to parse. I've taken the torch here and gutted even more repeated code. To be frank, it's probably all going to be re-written but it'll keep us going for now!

Ever busy @Daft-Freak has given us glorious new cross-platform asset pipeline that builds upon my quick-and-dirty linker kludge to provide full source-file to C-include build-time asset conversion. That means you can add your sprites.png image to your project via your CMakeLists.txt and it'll be converted by our sprite builder and compiled into your project for you to use. If your image changes, or the tool changes then your assets will be rebuilt automagically. This is an epic change that really simplifies maintaining your assets, so you should read about it here: #197

@Daft-Freak has also given us get_file_length for getting the size of files on the SD card. This joins open_file, read_file, close_file and list_files for a fairly comprehensive low-level SD-card access API. If you're wondering why he wants all this goodness then you should check out the source for his 32Blit Music Player here- https://github.com/Daft-Freak/32blit-music-player

@tinwhisker has tweaked the audio-wave example sample rate to 22050 to match the internal rate for simplicity.

I've introduced "persistence" which is a simple convinience wrapper in the 32Blit HAL (that's the code that glues our engine with the STM32) around 1K of RAM at the end of RAM_D3. By not initialising this RAM we can rely on it to stay set between resets and applications, using a "magic word" value we can tell whether it's been set before and set some defaults. The practical upshot of this is that if you set your "brightness" or "volume" they will stay set until you power cycle. Yay! (only applies to apps compiled with this feature)

TLDR

• New persistence feature to preserve volume/brightness across reboots
• New awesome asset pipeline please read: #197
• File API now has get_file_length so it's nicely rounded off
• sprite-builder now generates sprites with the correct pixel format (0x02 instead of 0x03)
• Various fixes, tweaks and improvements under the hood

As always the beta backers have brought us more enthusiasm and good times than we could have hoped for. To say nothing of the amazing features, tools and insight they've brought to the mix. Thanks all!