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!

0.0.3 Beta

This release sweeps up a whole bunch of changes toward a better, brighter Blit.

Perhaps the most significant is the rewrite of the engine to use an RGB888 framebuffer for hires mode. At the expense of RAM, this brings lores and hires mode to the same pixel format and simplifies sharing code/techniques and assets between the two. It's even possible to switch between these modes on the fly.

• Changes to QSPI config to double or even quadruple the external flash throughput under certain circumstances - thanks @AndrewCapon for getting DDR mode working. (note: a flash-loader firmware built against this release will be incompatible with binaries built against any previous release, due to them smashing the QSPI pin configuration on startup)
• Switch from RGB565 to RGB888 for hires mode framebuffer- this includes changes to the linker reducing available RAM in RAM_D2 to 63K but the benefits far outweigh the drawbacks
• Dramatic rewrite of core blit/blend functions, with some minor change to surface area- screen.pen(RGBA()) is now screen.pen = Pen() and RGBA() is now Pen() to cover various surface types.
• Support for arbitrary font sizes- thanks @Daft-Freak
• Refined file-access including a list_files method for listing files- thanks @Daft-Freak
• New Profiling functionality- thanks @AndrewCapon - more functionality than I can describe here, see the example!
• A sprinkle of compiler warning fixes to the HAL itself

Thanks also to @ali1234, @shane-powell and @mylogon341 for improvements to the existing codebase and documentation.