sifteo/thundercracker

The software toolchain for Sifteo's 2nd generation product

Thundercracker

This repository contains the software toolchain and firmware for Sifteo's 2nd generation product, a tangible video game system based on a wireless network of STM32 and nRF24LE1 microcontrollers.

Foreword

by Micah Scott, firmware engineer formerly at Sifteo.

The code in this repository was our attempt to do something impossible. From late 2011 through early 2013, a very small team of engineers did their best to create a new kind of video game system. To keep costs down we needed to use the smallest and lowest-power chips we could. I took inspiration from the video game consoles and personal computers of the 1980s and 1990s, but we used modern compiler and compression technologies to get the most from our 8-bit CPUs and kilobytes of RAM.

• Article: How we built a Super Nintendo out of a wireless keyboard

The system's graphics and interaction come from a wireless network of "cubes" built using the same technologies that power other systems of wireless sensor nodes. Our cubes, however, needed to generate fluid real-time graphics with a minimum of CPU and battery power. As a result, the cube firmware became a highly optimized 2D graphics rendering machine. The simple hardware technique of sharing a single parallel bus between the CPU, LCD, and Flash memory enabled much faster graphics than a microcontroller could produce using a purely software approach.

This strange and unique graphics engine required a whole host of new tools to develop: a cycle-accurate CPU emulator and hardware emulator, a static binary translator and static verification tools, new compression protocols and new unit testing infrastructure.

• Sample code from deep inside the cube's graphics engine

These "cubes" act somewhat like a simple remote-controlled GPU. The game itself runs on a more powerful microcontroller, the "master" block. This is twice the size of a cube, with more battery power available. The master block runs games inside a new kind of virtual machine sandbox. Its simple operating system handles radio communications, storage, music, USB communications.

We wanted to create a robust "app" sandbox for running games, but we couldn't afford the price of hardware memory protection or the risk of allowing game code to have direct access to hardware that may be damaged by incorrect use. Our solution was strange and powerful. We called it "SVM". Most of a game's instructions ran natively at full speed, with some common operations implemented using privileged system calls. I wrote an LLVM backend to generate these specially formatted instructions and pack them into small blocks that could be cached and demand-paged in software from external serial flash memory.

• Sifteo VM Instruction Set Architecture document

Liam Staskawicz and I designed and built this monumental architecture. For better or worse, we were very careful about which other projects we depended on. Both of us come from an Open Source background and feel just a bit awful any time we have to use ambiguously-licensed code from some silicon vendor or another. So, when we built Thundercracker, we put in the extra time to build it all on a solid foundation. We created our own bootloader, our own platform support libraries, our own system simulator. We built on other open source tools, but in a way that we hoped could be eventually returned to the community.

That time has come. It saddens us that Sifteo Cubes were not the commercial success we hoped for, but at the same time I feel very grateful that we can share some of the amazing work we did to make the product real. I hope this code brings you some amusement at least, if not some utility.

Many of the components in this codebase are designed with reusability in mind. We've written a filesystem, operating system, several compression algorithms, graphics engine, simulator, linker, drivers for the nRF24L01 and nRF8001 radios, and so much more.

We can't provide any official support for this code, but I still care and I'll try to answer questions when I can. Who knows, perhaps Sifteo Cubes will live on as an Arduino shield or a swarm of remote control cars or maybe just a really esoteric easter egg.

Getting Started

If you aren't already familiar with the public documentation for the Sifteo SDK, best to check that out first. The Doxygen sources live in the docs directory, or you can view it online:

• Sifteo SDK documentation

Most of the tools necessary to build the SDK are included in this repository, in the deps directory. There are some exceptions, like Doxygen. On Mac OS, you can install this with "brew install doxygen".

In the top-level Thundercracker directory, type make. This will build the firmware, compiler, asset preparation tools, documentation, and unit tests. Most of the results will be in the sdk directory.

Otherwise, binaries are available (again, no longer officially supported, but hopefully helpful):

• OS X
• Windows
• Linux 64-bit
• Linux 32-bit

Parts

• deps – Outside dependencies, included for convenience.
• docs – Build files for the SDK documentation, as well as other miscellaneous platform documentation.
• emulator – The Thundercracker hardware emulator. Includes an accurate hardware simulation of the cubes, and the necessary glue to execute "sim" builds of master firmware in lockstep with this hardware simulation. Also includes a unit testing framework.
• extras – Various userspace programs which are neither full games nor included in the SDK as "example" code. This directory can be used for internal tools and toys which aren't quite up to our standards for inclusion in the SDK.
• firmware – Firmware source for cubes and master.
• launcher – Source for the "launcher" app, the shell which contains the game selector menu and other non-game functionality that's packaged with the system. This is compiled with the SDK as an ELF binary.
• sdk – Development kit for game software, running on the master. This directory is intended to contain only redistributable components. During build, pre-packaged binaries, built binaries, and built docs are copied here.
• stir – Our asset preparation tool, the Sifteo Tiled Image Reducer.
• test – Unit tests for firmware, SDK, and simulator.
• tools – Internal tools for SDK packaging, factory tests, etc.
• vm – Tools and documentation for the virtual machine sandbox that games execute in. Includes "slinky", the Sifteo linker and code generator for LLVM.

Operating System

The code here should all run on Windows, Mac OS X, or Linux. Right now the Linux port is infrequently maintained, but in theory it should still work. In all cases, the build is Makefile based, and we compile with some flavor of GCC.

Build

Running "make" in this top-level directory will by default build all firmware as well as the SDK.

Various dependencies are required:

1. A build environment; make, shell, etc. Use MSYS on Windows.
2. GCC, for building native binaries. Should come with (1).
3. SDCC, a microcontroller cross-compiler used to build the cube firmware
4. gcc for ARM (arm-none-eabi-gcc), used to build master-cube firmware.
5. Python, for some of the code generation tools
6. Doxygen, to build the SDK documentation
7. UPX (Linux only) for packing executables

Optional dependencies:

1. OpenOCD, for installing and debugging master firmware
2. The Python Imaging Library, used by other code generation tools

Linux only:

• The UUID Library for the generation of Universally Unique Identifiers
• Libusb allows accessing to USB devices on most operating systems
• Mesa is an open-source OpenGL, it's used in the simulator
• GLU (OpenGL Utility Library), allows interfaces for building mipmaps
• Libasound, a library to use ALSA, Advanced Linux Sound Architecture
• The ia32-libs package is needed in 64 bits computers

On most debian-like distros, you still need the arm toolchain (see below) but the following command should install all of the useful deps (if you already have one it will be skipped)::

sudo apt-get install -y g++ doxygen upx-ucl python-imaging openocd \
             uuid-dev libusb-1.0-0-dev mesa-common-dev \
             libglu1-mesa-dev libasound2-dev ia32-libs

ARM toolchain

On all platforms, the ARM GCC Embedded distribution is preferred. Binaries are available at:

https://launchpad.net/gcc-arm-embedded

Environment Variables

BOOTLOADABLE Generate a binary compatible with the USB bootloader (Not JTAG)

BOARD Define the board to target. If unset, uses the default board in stm32/board.h

HAVE_NRF8001 If the current BOARD has an optional nRF8001 Bluetooth Low Energy controller, this enables support for it.

thundercracker's Issues

Extracting graphics from elf file/Decompiling elf files?

I'd like to know how to extract graphics from an .elf file? I can press [I] in Siftulator in order to view the graphics bank currently loaded. Unfortunately I can't quite get the Zoom level to perfectly align 1:1 in pixel ratio to the Asset flash.

How do I deploy elf files to the cubes, and is it possible to use Sifteo Sync without a log in?

Can you explain how to deploy elf files to the actual hardware, and can Sifteo Sync (or Sift Runner) be used without the log in to the now non-existent servers? I'm asking because I am trying to determine whether purchasing this old hardware is worthwhile.

sifteo resurrected

Recently posted on reddit:
https://www.reddit.com/r/sifteo/comments/5rv33t/sifteo_resurrected/
"I’d like to humbly announce the following page: http://doctormikereddy.com/sifteo-resurrecting-a-legend/ which contains a (growing) number of resources for those people lucky enough to own (or unlucky enough to have recently bought second hand) the wonderful Sifteo Cubes; either V1 with the dongle, or V2 with the base station. On that site you can download the software (with hacks to get it to run without the long gone sifteo.com server), all the games officially released, and SDKs to make your own, either for physical cubes or for the simulators. There will be more to come, including how to set up the SDKs - for now there are a few sites still out there on Google - and how to make games for this unique platform. Thank you for your patience!"

Hopefully, this will serve to provide practical guides and resources for those wanting to use these amazing devices, and open source tools.

DoctorMike

A doubt in BG1Drawable::maskedImage()

Hello developer,
Firstly, thank you very much for making those sifteo cubes.
Recently, I try to start developing with your SDK. When I want to use the BG1 layer for painting, I noticed the function maskedImage:
void maskedImage(const AssetImage &image, const PinnedAssetImage &key, unsigned frame = 0)
(full function is here)
I don't know why we have to pass both AssetImage and PinnedAssetImage to call this function. Do you know anything about it?
(Sorry for my poor English)
Many thanks,
Alex

Linking error when building launcher

Hi,

I've tried to build the project for 2 weeks, and today I'm requiring your help.
The process stop because of a Slinky error.

The displayed message is :
taking address of undefined symbol : "_call_$"

I've tried both on linux (64) and windows and the result is the same.

I am far from beeing a cross-compilation expert, and I can't assert nothing about the origin of the problem.
Maybe some of the provided binaries are outdated.

I hope you to see this issue one day.

Green

how to generate bootloader.bin?

hi,

I've tried to build the project with commod "make BOOTLOADABLE=1",but there is no bootloader.bin or bootloader.elf generate.

Any problem with commod? and how to generate bootloader.bin

I hope you to see this issue one day

NullaryEventVector for USB

Hello dear Sir,

i'm implementing one program with sifteoSDK an i have a problem with NullaryEventVector. Each USB event (usbConnect, usbDisconnect, usbReadAvailable, usbWriteAvailable) doesn't work. It shows a fault during the siftulation, but during Make no errors at all.
The code is 15. - Other bad parameter ins system call.
Here is a piece of code:

static void onConnect(){
LOG("Connected");
}
void main(){
...
Events::usbConnect.set(onConnect);
...
}

As You see, nothing special. Could you help me?

With kind regards,
Ruzalin

We are ready to bring the HW back -- Joyscube

Hello Everyone,

I’m Mark, co-founder of Joyscube. In fact, I am just an ordinary programmer. Out of my fascination at these cubes, I started the adventure of Joyscube, even if this journey is complicated for a programmer :). We have achieved our funding goal in Kickstarter, so there is a good chance that we will stop losing money. But one thing that can be determined is that we will begin our mass production. Two years ago, we started this project and thus our dream. Up till now, I do believe that it is still remembered and loved by a lot of people. I think it is necessary to tell everyone here that we are ready to bring the HW back (with new BLE function) and our FW is also open source.

“No matter what you do, it will never amount to anything more than a single drop in a limitless ocean. What is an ocean but a multitude of drops?” — Cloud Atlas

We just began the first step, we need more time and support to go further.

Thank you!
//BR Mark

update only for Sifteo Cubes 2.0?

Hey I got the 2.0 cubes back in 2013. My 2 year old loves them! I'm wondering if there's any chance there's an updated firmware that might help with some of the bugs, signal dropping, etc? And if so, a straightforward way to get it onto my base station?

Thanks!

Adding cubes does not sync up with the current game.

In Siftulator, the player can add more cubes by pressing + and -. Unfortunately, I can't get it to work. Either the new cubes are immune to the base OR you have to add at least 4 cubes (and lag up whilst adding them) for the 7th one to actually sync up.

How can I fix this?

ALSO, How can I retain save data of any game upon exiting?

Open letter to Sifteo Devs

[Going to post this here, on bitBucket, and try to email relevant ex-Sifteo people directly, if I can, so please accept my apologies if you get this more than once. I know you've all moved on to 3D Robotics now, and this is ancient history; strange how a couple of years is enough for things to be obscured by virtual dust...]
Hello,
My name is Dr. Mike Reddy, and I am a UK academic researcher in games, toys and gadgets. I've JUST recently acquired a 'new' set of the original Sifteo cubes - by way of a Seattle thrift shop sale (a long story!) - but, of course, support for these is lacking compared to the 2nd generation cubes. At least they got an open source parting shot from yourselves, which if not complete is still enough to do some development work. However, the original cubes seems to require a log in, and I have been unable to get the Siftulator simulator working with Siftrunner.

It is possible to get past the log in page by choosing Help from the Toolbar, then clicking on My Games, but when I try to run an app from the dev kit, it never seems to load in Siftrunner for me to deploy to Siftulator; the actual cubes are on their way from the US, so I've not been able to try them with the actual hardware yet. It is, of course, possible that not getting the apps to load in Siftrunner requires an unlock by connecting with physical cubes, but I suspect it is more likely to be due to the lack of the remote server. At this stage, it is possible that I won't be able to easily develop for these cubes, so I am contacting you to see if you could be of some help.

I've been doing a lot of digging, including a bit of archive.org trawling through the original Sifteo web site, along with reaching out to people who developed for both versions of Sifteo, to try to piece together documentation and software for the 'originals' as much as the later incarnation. Currently, there are some obvious gaps - only the SDK for the 2nd version is easily available - but I've managed to get the Sifteo Sync beta 0.9.10 for Mac, the last version of SiftRunner for Mac and PC, and the original SDK for v1 Cubes; mostly from the WayBack Machine archive, with a little help from redditors :-) However, I don't have the PC (or any of the Linux incarnations) of Sifteo Sync , and most importantly, all of the games originally offered on the Sifteo web site are gone :-(

I am aware that they were all made 'free' towards the end of the product support phase (mid 2015), so I missed my opportunity to get hold of some of the existing apps created for either set of cubes. Amazingly, I only recently became aware of these things - a chance view of an old Extra Credits YouTube video, where they were mentioned - but in my defence the mid 2010s were a very busy time for me, with me fighting just to keep my job, during a difficult merger with another university, and games/gaming (my main teaching area before and since) were the last things on my mind.

Although the product, and the company are now a memory, I think that Sifteo Cubes were an amazing idea, truly before their time! To that end, I would like to find any way possible to archive and advocate the importance of these clever little cubes as a historical milestone. Any help you can provide would be gratefully appreciated. For example, having open source access to Siftrunner and SifteoSync would allow me to modify them, so they did not need remote server log ins. I am aware from a 2011 Android presentation that at least a test app for tablets could communicate with the original cubes; access to even this test code would provide a great stepping stone for resurrecting the v1 cubes. Of course, it would be excellent if executables (if not the whole source) for some or all of the games, in parallel with a decoupled Siftrunner, would allow these to be run in emulation even if interested people did not have access to the hardware. Similarly for the v2 cubes, although the open source sdk allows homebrewed apps to run already. Seeing the source code, etc, for the v2 games would also be of significant historical interest. What amazes me, apart from the sadly unsuccessful demise of the sifteo, was how quickly it seemed to disappear from the Internet Consciousness; I'd like to reverse that trend if at all possible.

It is possible that you are not in any position to be able to help me, so I might have to keep reaching out to other Sifteo owners and/or attempt reverse engineering the PC/Mac software for controlling the Sifteos, for a full rewrite - what I'm now going to call "Softeo" - but I'm determined to resurrect my old Sifteos!. Although this might be quite challenging, I have a vested interest: I have some original cubes on their way from a friend in the States! I would love to get a copy of the v2 cubes one day, but they are bizarrely scarce; maybe one day if I am lucky.

Either way, with the v2 SDK and the more polished emulator, I am going to be setting student coursework and projects using Sifteo, as I don't think all the nuances of this unique platform were really fully explored. They really were ahead of their time. Amazing to think that they evolved from a 2009 project (I loved the TED talk at the time, but never realised they had been commercially released; so many miraculous things come out of MIT, etc, that never see the light of day for the rest of us). Whatever happens, how ever you can help, I'd like to thank you for creating a wonderful idea.

Dr. Mike Reddy
Course Tutor in Computer Games Development
University of South Wales, UK