1
2
foo
bar

1
2
foo
bar

1
2
3
4
5
6
7
public class HelloWorld
{
    public static void main(String[] args)
    {
        System.out.println("Hello, World");
    }
}

1
2
3
4
5
6
7
8
9
public class HelloWorld {
    
    // Your program begins with a call to main()
    public static void main(String[] args)
    {
        // Prints "Hello, World" to the terminal window. Prints  "Hello, World
        System.out.println("Hello, World");
    }
}

I just got my first little SSD1306 OLED screen and wanted to do something cool with it after running some tests. So as any sane person would do, I decided to show Bad Apple on it; just to remember I don’t have enough brain cells left to pull it off by myself. So I searched the web and found this great project: hackffm/ESP32_BadApple. They deserve most of the credit, since everything I did was based on their excellent work.

The repo contains compressed video data, and an Arduino sketch along with a few C++ files to decompress and display the actual video frames, which are stored on the microcontroller’s flash as a separate filesystem called SPIFFS, along with the code that we upload to the microcontroller. The problem is that SPIFFS data need to be uploaded manually, as Arduino IDE itself is not quite aware of it.

Fortunately, the repo includes instructions for that, which points us to an Arduino plugin—but that plugin no longer works with the newer 2.x.x versions of the IDE. Still, nothing stops us from reading the plugins source code and replicating it’s functionality ourselves.

Getting our feet wet

A skim through ESP32FS.java reveals that we just need to figure out three steps:

1. Read the partition table by opening the selected partition table’s csv file and looking for the spiffs entry to figure out it’s size and offset into the flash.

2. Create an SPIFFS image. This is pretty straight forward: Just invoke mkspiffs on the sketch’s data/ directory as we see in the plugin code:

   if (listenOnProcess(new String[] {
       toolPath,                // Path to the mkspiffs binary
       "-c", dataPath,          // Path to the data directory
       "-p", spiPage+"",        // spiPage = 256 (constant)
       "-b", spiBlock+"",       // spiBlock = 4096 (constant)
       "-s", spiSize+"",        // Read from partition table
       imagePath
   }) != 0) // ...
   

3. Writing the image to ESP32’s flash with esptool.py (or send it over the network with espota.py, in which case we don’t need to explicitly specify the partition address):

   sysExec(new String[] {
       // Path to esptool.py (or a binary executable variant)
       esptool.getAbsolutePath(),
   
       "--chip", mcu,          // Chip variant (in this case, 'esp32s3'), read from Arduino's configuration
       "--baud", uploadSpeed,  // The upload speed to use, read from Arduino's configuration
   
       // The serial port that is connected to the micro, read from Arduino
       // (e.g. /dev/ttyACM0, /dev/ttyUSB0, or something else on other OSes)
       "--port", serialPort,
   
       "--before", "default_reset",
       "--after", "hard_reset",
       "write_flash",
       "-z",  // Compress data in transfer
   
       // The flash mode to use (and set), read from Arduino's configuration
       // (See https://docs.espressif.com/projects/esptool/en/latest/esp32/advanced-topics/spi-flash-modes.html)
       "--flash_mode", flashMode,
   
       // The flash frequency to use (and set), read from Arduino's configuration
       // (See https://docs.espressif.com/projects/esptool/en/latest/esp32s3/esptool/flash-modes.html#flash-frequency-flash-freq-ff)
       "--flash_freq", flashFreq,
   
       // The flash size to set
       // (See https://docs.espressif.com/projects/esptool/en/latest/esp32s3/esptool/flash-modes.html#flash-size-flash-size-fs)
       "--flash_size", "detect",
   
       // The address to begin writing the image to (read from the partition table)
       ""+spiStart,
           
       imagePath
   });
   

   Before panicking: many of these flags are not required. -z is enabled by default, flash options can be ommited to use device defaults, chip type can be detected automatically, and --before and --after flags are not quite necessary as the chip will be hard-reset after write_flash anyway.

Reading the partition table

The partition table is set by the Arduino IDE when writing the firmware on the flash. So to know what partition table is currently being written, There are a couple of options:

1. See what Arduino is configured to use by looking in the Tools menu: then search Arduino package files for the partition table’s csv file. They are located somewhere like ~/.arduino15/packages/esp32/hardware/esp32/x.y.z/tools/partitions/:

    $ ls ~/.arduino15/packages/esp32/hardware/esp32/3.2.0/tools/partitions/
    app3M_fat9M_16MB.csv              esp_sr_16.csv                               minimal.csv                  tinyuf2-partitions-16MB-noota.csv
    app3M_fat9M_fact512k_16MB.csv     ffat.csv                                    min_spiffs.csv               tinyuf2-partitions-4MB.csv
    app3M_spiffs9M_fact512k_16MB.csv  huge_app.csv                                no_fs.csv                    tinyuf2-partitions-4MB-noota.csv
    bare_minimum_2MB.csv              large_fat_32MB.csv                          noota_3g.csv                 tinyuf2-partitions-8MB.csv
    boot_app0.bin                     large_ffat_8MB.csv                          noota_3gffat.csv             tinyuf2-partitions-8MB-noota.csv
    default_16MB.csv                  large_littlefs_32MB.csv                     no_ota.csv                   zigbee_2MB.csv
    default_32MB.csv                  large_spiffs_16MB.csv                       noota_ffat.csv               zigbee_8MB.csv
    default_8MB.csv                   large_spiffs_8MB.csv                        ota_nofs_4MB.csv             zigbee.csv
    default.bin                       m5stack_partitions_16MB_factory_4_apps.csv  rainmaker_4MB_no_ota.csv     zigbee_zczr_2MB.csv
    default.csv                       m5stack_partitions_16MB_factory_6_apps.csv  rainmaker_8MB.csv            zigbee_zczr_8MB.csv
    default_ffat_8MB.csv              max_app_4MB.csv                             rainmaker.csv                zigbee_zczr.csv
    default_ffat.csv                  max_app_8MB.csv                             tinyuf2-partitions-16MB.csv
   

   In this case, it is the default.csv. However if you are unsure, you can use the second method below.

2. or Read the partition table directly from the flash. There is an offset into the flash where the partition table is written in binary which varies between different configurations, but the default offset is 0x8000 and the table size is 0xC00 bytes.

Knowing that, we can continue by dumping that section into a file:

esptool.py --port /dev/ttyACM0 read_flash 0x8000 0xc00 partition-table.bin

Then, we parse the binary to csv:

gen_esp32part.py partition-table.bin

(The gen_esp32part.py script is included with ESP-IDF and Arduino’s ESP32 package. You can try searching for it in the Arduino package files if you have trouble finding it)

Anyhow, we now have a csv file which looks like this:

1
2
3
4
5
6
7
# Name,   Type, SubType, Offset,  Size, Flags
nvs,      data, nvs,     0x9000,  0x5000,
otadata,  data, ota,     0xe000,  0x2000,
app0,     app,  ota_0,   0x10000, 0x140000,
app1,     app,  ota_1,   0x150000,0x140000,
spiffs,   data, spiffs,  0x290000,0x160000,
coredump, data, coredump,0x3F0000,0x10000,

Just note down the Offset and Size fields of the spiffs partition. Depending on the method used to get this csv table, these numbers might be in hex, decimal and may or may not have postfixes. Remember to assume binary prefixes (e.g 1024 instead of 1000) for the postfixes. Also, all these values are in bytes.

Creating the SPIFFS image

Easy, just run this and make sure to replace the number after -s with whatever SPIFFS partition size you had:

mkspiffs -c data/ -p 256 -b 4096 -s 1441792 spiffs.bin

(Again, mkspiffs is included in Arduino package files)

Write the image to ESP32’s flash

At this point, this is also pretty easy to do (Don’t froget to replace 2686976 with your SPIFFS partition offset):

esptool.py               \
  --chip esp32s3         \
  --baud 921600          \
  --port /dev/ttyACM0    \
  --before default_reset \
  --after hard_reset     \
  write_flash            \
  -z                     \
  --flash_mode qio       \
  --flash_freq 80m       \
  --flash_size detect    \
  2686976 ./spiffs.bin

All these values can be gathered from the same Tools menu mentioned above. But remember, this command can be simplified since alot of these flags are not mandatory:

esptool.py --baud 921600 --port /dev/ttyACM0 write_flash 2686976 ./spiffs.bin

(I kept --baud because the default rate was too slow. If you experience any weired behavior, consider removing this flag or using lower baud rates.)

Final thoughts

Although this method works perfectly fine for this example, there are many other options when it comes to mounting a filesystem on the ESP32, such as FatFS or LittleFS which can both operate on the SPI flash as well as on an SD card. They also perform differently. So you might want to choose a different one depending on your needs.

Epilogueealisdjaewr?

Finally, it’s time to enjoy watching Bad Apple on the OLED screen with a cup of warm coffee ☕.

The only thing it lacks, is the audio that was added on top of the video with editing software. I really hope some day I comeback to this type of stuff and maybe make a version with audio. Until then!

1. Foo
2. Bar

   baz
   

boo

1. First item

2. Second item with code:

   #include <iostream>
   int main() {
       std::cout << "Hello, world!" << std::endl;
       return 0;
   }
   

3. Third item

#include <iostream>
int main() {
    std::cout << "Hello, world!" << std::endl;
    return 0;
}

Getting started

To follow this guide, you are going to an emulator to emulate a real Atari device and the River Raid ROM (RRR? :) file. I’ve decided to use the Stella emulator and I found a copy of the ROM file here.

Now, run Stella and find the downloaded ROM file (It is probably a .zip file), you should see something like this:

NOTE: If you are using an older version of Stella, you might need to manually unzip the file and look for the .bin file inside it.

Then, load the ROM by double-clicking on it. The game should start running:

But, to really start the game on a real Atari, you need to press the reset button. On Stella, this key is mapped to F2 by default. So press it and start playing the game. Right and left arrows will move the player and space will fire some missiles.

There are three ways to lose the game:

1. Colliding with ships, aircrafts and bridges 🚁
2. Colliding with hills 🌲 (green parts)
3. Running out of fuel ⛽

Two first “ways” of losing are pretty similar, but are handled quite differently in the game.

Collision detection

Unlike modern games which usually use seprated systems for rendering and physics, older games detected collisions between different objects while rendering. Atari lets you define a limited number of sprites, with limited sizes. Then you can tell the system where to render these sprites. During rendering, when the scanline “scans” the screen, the system also checks for collision between those sprites and changes some registers accordingly. To explore this, press the ~ key (next to 1) to enter Stella’s debug mode. the game will be paused automatically.

Head over to TIA tab to see graphics and collision information. Then, check the Debug Colors option. It will allow us to detect where sprites are rendered on the screen. To see the changes, click the Frame +1 button to render the next frame with debug colors.

It will show us a weird looking image. As you can see:

1. Player is rendered in red.
2. Enemies and fuel (gas) stations are rendered in yellow.
3. Hills are rendered in purple.

By looking at the colors under the Debug Colors checkbox, You can see which sprite code is associated with each part of the screen.

We can use the sprite ID of each object to check for collisions of that object. For example to check for collisions between Player and Enemies, you can check for collision between P0 and P1.

Collision Registers

There are a few registers which store collision information. And here they are:

This table shows what is stored in each bit of each register. For example, if P0 and P1 are colliding, 7th (last) bit of the CXPPMM register will be set to 1.

Passing through enemies

Now that we know which register stores P0-P1 collision; We can search the disassembly to see when it is read.

Unfortunately I couldn’t find a way to do that automatically in Stella (like the “find” operation in many text editors). But there are two other ways for doing that:

1. Scrolling throw the disassembly section of the Stella and look for CXPPMM (It actually works because the program is pretty small)
2. Write a code to do that for us

First way is pretty straight forward. But second one is a bit harder. Because if you want to search for a bit with value of 0x7 (0x7 is the address of CXPPMM); You will get alot of matches which do not actually mean CXPPMM. Like this one:

Here, 0x07 is interpreted as COLUP1 instead of CXPPMM.

By following first way, you will find the first match at address 0x2f3 (aka f2f3):

Great! But what does it mean?

Looking at here, it says:

Bit 7 (…) is transferred directly into the negative flag.

Did you notice that?!

bit CXPPMM will do alot of stuff. One of which is moving 7th bit of the CXPPMM register to proccessor’s negative flag.

So if the value stored in the negative flag is 1, then P0 is colliding with P1!

The next instruction is bpl Lf2f9. bpl means “jump if positive”. Being positive means that the negative flag is set to 0. So if the negative flag is set to 0, it will jump to the instruction at location 0x2f9.

These two instructions can roughly be translated to plain English as:

If P0 and P1 are not colliding, jump to 0x2f9 and continue execution from there.

Doing the jumps means skipping the code between 0x2f5 and 0x2f9 (Which happens to be only a single instruction: stx ram_E8). So it is probably where increasing fuel and/or losing the game by hitting enemies is handled. (Remember, both enemies and fuel stations(?) as rendered as P1) So we probably need to remove that code!

But we can’t just delete those two bytes, because it will mess up code layout and jump locations. So we should replace them with something which does nothing.

Hopefully, there is a nop instruction which means “No Operation”. It does nothing. We can change stx ram_E8 to nop nop. (Instructions can have different sizes. stx ... needs 2 bytes but nop can be stored in a single byte. It means we need two of them to fill the entire 2 bytes of the previous stx.)

You can’t directly write assembly code in Stella, as it only allows you to modify the assembly directly in hex. But I’ve got you covered! The hex equivalent to nop is 0xEA. So just double click on the hex on the right side and replace 86 e8 with ea ea. (Why don’t we have a Valve instruction? 🤔)

Similarly, repeat the same replacement at location 0x487.

Now hit the Run button (or the Exit button on older versions) at the top-right corner and enjoy playing game without ever losing by hitting enemies!

Passing through hills

Likewise, you can tell that collision between the player and hills (P0-PF) is stored in the 7th bit of the CXP0FB register. After searching for bit CXP0FB, you can find two matches at 0x2E7 and 0x462. Both are followed by a bpl instruction; So replacing next two bytes after the bpl instructions with ea ea will make us fly through hills as well.

Endless fuel

By tracking values stored in the RAM, you will be able to guess where the fuel level is stored. Test your guesses by modifying that value (try double-clicking!) and observing what happens next.

So here is my try (spoiler alert!):

After trail and error, it tured out that byte 0xb7 is the correct address. Now by searching the code for that ram address, I found a dec ram_B7 instruction at address 0x64c. It basically decrements the value stored at the RAM at address 0xb7. Replace that with ea ea and we are done.

Summary

Overriding the 2 bytes these address are pointing to with ea ea:

1. 0x2eb (for hills)
2. 0x2f7 (for enemies)
3. 0x466 (for hills)
4. 0x487 (for enemies)
5. 0x64c (for fuel)

Will eventually turn one of the most iconic and popular games of the 1980s to a boring, possibly zero-player game. Bye!