SD Card Support

Expert Topic for experienced builders.

Big idea

Add an SD card module to supported custom hardware to read exported animations and audio files without storing them in firmware code.

You can add an SD card module to a custom hardware driver and enable firmware modules that read files from it. This is useful for storing exported animations, and is required for I2S audio playback from an SD card.

Card Size and Format

Use an SD card that is 32 GB or smaller and formatted as FAT32, which is the required format for Bottango firmware.

Cards larger than 32 GB usually ship formatted as exFAT, and most operating systems will not offer FAT32 as an easy formatting option for cards that large. It is technically possible to format a larger SD card as FAT32 with special tools, but it is rarely worth the extra troubleshooting. A 32 GB or smaller card is the simpler recommendation.

Note

Even a 16 GB card is nearly always much larger than Bottango animation files and audio files require. You do not need a high-capacity card.

SD Card Quality

Use a good-quality, name-brand microSD card.

Very cheap or off-brand cards can fail frequently, corrupt files, behave inconsistently, or even cause hardware damage in extreme failures. If SD card behavior seems unreliable, swapping to a known good card is one of the simplest troubleshooting steps.

Hardware Requirements

SD card support requires a capable microcontroller, such as an ESP32, and a compatible SD card module. Arduino Uno, Nano, and Mega boards are not supported for SD card reading.

The SD card module communicates with the microcontroller over SPI. Connect the module’s MISO, MOSI, CLK, and CS pins to appropriate GPIO pins on your microcontroller.

Set those four pin assignments in BottangoArduinoConfig.h. See the Configuration File guide for more information about configuring module pins.

Exported Animations

The standard exported animation workflow enables USE_CODE_COMMAND_STREAM and reads animation data compiled into C++ code. To read exported animation data from an SD card instead, enable USE_SD_CARD_COMMAND_STREAM.

1. Export your animations from Bottango using the SD card files format. Bottango will generate an anim folder containing the exported animation files.

2. Place the entire anim folder at the root of the SD card.

3. In BottangoArduinoModules.h, enable USE_SD_CARD_COMMAND_STREAM:

   BottangoArduinoModules.h

   #define USE_SD_CARD_COMMAND_STREAM

4. Make sure USE_CODE_COMMAND_STREAM is disabled. The SD card command stream replaces the code command stream for this workflow.

5. Save your changes, then compile and reupload the firmware.

The resulting SD card layout should look like this:

I2S Audio

The AUDIO_SD_I2S module reads audio files from an SD card and plays them through I2S audio hardware. Use this module instead of AUDIO_TRIGGER_EVENT when the hardware driver itself should read and play the audio files.

The SD card requirement is included when you enable AUDIO_SD_I2S, so you do not need to enable USE_SD_CARD_COMMAND_STREAM unless you also want exported animations to read from the SD card. See the Hardware Audio - I2S guide for the complete i2s audio setup.