Skip to content

README.md

Latest commit

 

History

History
139 lines (110 loc) · 7.06 KB

README.md

File metadata and controls

139 lines (110 loc) · 7.06 KB
Raw

Software

Path What
VectorArcade/ The firmware. One sketch for both consoles
tools/wav2h.py Turns the WAV files into headers for the linked build, and writes their fingerprint
tools/img2bitmap.py Converts an image into a FabGL Bitmap in C++ source, as used for the splash screens. From FabGL, GPL-3.0

VectorArcade/ - the firmware

Files Responsibility
VectorArcade.ino setup of display, fuel gauge, IMU, filesystem and menu; the 25 FPS loop
Menu.*, MenuItem.*, MenuPage.* the main menu, its entries and the configuration page
DisplayObject.* base class of everything on screen, text and instruction helpers
InputController.*, Joystick2Axis.* the buttons, debounced in their own task, and the joystick
LunarLander.*, Eagle.*, LunarSurface.*, Camera.h, LunarLanderSounds.h Lunar Lander: game states, the lander, the endless surface, the scrolling and zooming view
Asteroids.*, AsteroidsGameObjects.*, AsteroidsSounds.h Asteroids: game states, ship, shots, asteroids and saucer
SoundClips.* loads the clips from LittleFS and checks their fingerprint
JoystickCalibration.*, IMUCalibration.*, SoundVolume.*, WipeAndReset.*, FPSToggle.* the configuration entries
BatteryStatus.*, IMUStatus.* the battery indicator and the IMU readout in the menu
Version.h the firmware version
BoardSelect.h.template the console to build for, and the sound source (see below)
Board.h, PinMap.h, Layout.h, AsteroidsSplash.h forward to the selected console's files in boards/
boards/<console>/ per console: GPIO (PinMap.h), display and features (Board.h), screen positions (Layout.h), the Asteroids splash image
data/ the sound clips as WAV files, and their fingerprint sounds.id
sounds/ the same clips as headers, generated by wav2h.py
build_opt.h extra compiler warnings
partitions.csv 6 MB app + 1.875 MB LittleFS; overrides the Tools menu

Choosing the console

The console is selected in BoardSelect.h. That file is not tracked by git, so switching consoles never shows up as a change. After cloning, copy BoardSelect.h.template to BoardSelect.h and set exactly one of these to 1:

#define BOARD_IS_LITTLEGAMECONSOLE()    1
#define BOARD_IS_TINTINROCKETSHOOTER()  0

The same file holds one build option, where the sound clips come from:

#define SOUNDS_FROM_LITTLEFS()          1
  • 1 (default): the WAV files are read from the littlefs partition into PSRAM at startup. The firmware is smaller, and a firmware upload does not rewrite the sounds. Needs PSRAM, and the files uploaded once (below).
  • 0: the clips are linked into the firmware from sounds/*.h. Works without PSRAM and without a file upload, at about 0.4 MB more firmware.

The build prints which console and which sound source it is building for.

Partition table

partitions.csv sits in the sketch folder, and the core uses it in preference to the Partition Scheme menu:

Name Type Offset Size
nvs data 0x9000 20 KB stored settings: calibration, volume, high scores
otadata data 0xE000 8 KB
factory app 0x10000 6 MB the firmware, single slot, no OTA
littlefs data 0x610000 1.875 MB the sound clips
coredump data 0x7F0000 64 KB a crash dump, readable with espcoredump.py

The littlefs partition keeps the subtype spiffs: ESP-IDF 4.4, which core 2.0.17 is built on, has no LittleFS subtype, and LittleFS finds the partition by its label.

The Partition Scheme menu still matters for one thing: the IDE takes the maximum upload size from it, so uploads are capped at 3,342,336 bytes although the partition holds 6 MB.

Setting up a new console

  1. Choose the console as above, compile and upload. The upload writes the partition table from partitions.csv together with the firmware.
  2. Let it boot once with the Serial Monitor open (115200 baud). The empty littlefs partition cannot be mounted yet, so the firmware formats it and reports LittleFS: partition cannot be mounted - formatting it as LittleFS. A partition that holds another filesystem (SPIFFS, FAT) is formatted the same way, and its files are lost.
  3. Upload the contents of data/ - the seven WAV files and sounds.id - into the root of the LittleFS partition, for example with the browser tool ESPConnect. File names are case-sensitive. Then restart.
  4. At startup the firmware compares sounds.id with the fingerprint compiled into it and reports LittleFS: sound files match, or tells you to upload data/ again.

Later firmware uploads keep the files, as long as Erase All Flash Before Sketch Upload stays disabled.

Changing a sound

data/*.wav is the single source of the sound clips: 16-bit PCM WAV, mono, 11,025 Hz. After changing, adding or removing a file, run

python3 software/tools/wav2h.py

It regenerates sounds/*.h for the linked build and writes a new fingerprint into data/sounds.id and sounds/SoundsId.h. Then rebuild, and upload data/ again, including sounds.id. wav2h.py --check only reports whether anything is out of date. The script needs nothing beyond the Python 3 standard library.

Boards without PSRAM, or with 4 MB flash

  • Without PSRAM, build with SOUNDS_FROM_LITTLEFS() set to 0. A LittleFS build without PSRAM is refused at compile time.
  • partitions.csv is laid out for 8 MB flash, so a 4 MB module needs a different partition table. The linked build is about 1.84 MB, so on 4 MB it fits only a partition scheme with a ~3 MB application ("Huge APP", no OTA), not the default 1.25 MB one.
  • Replace or remove partitions.csv accordingly. While it is present it overrides the Partition Scheme menu, and the IDE's size check still uses the menu's maximum, so select a scheme whose application size matches.

tools/img2bitmap.py - images for the display

The firmware cannot read image files: every picture is compiled in as a FabGL Bitmap, a byte array plus its size and pixel format. img2bitmap.py is FabGL's own converter, included unmodified. It needs Python 3 and Pillow (pip install pillow):

python3 software/tools/img2bitmap.py AsteroidsSplash.png -s 320 240 -f1 > AsteroidsSplash.h
Option
-s width height resize to this size - 320 240 for the LittleGameConsole, 240 240 for the TintinRocketShooter
-f0 / -f1 / -f2 pixel format: RGBA2222 (64 colours, the default), RGBA8888, or 1-bit monochrome
-d dither, for RGBA2222
-t x y take the colour of this pixel as transparent
-o0 / -o1 output as C++ source (the default) or as a plain hex string

The array and the bitmap are named after the input file, so AsteroidsSplash.png gives exactly the AsteroidsSplash_data and AsteroidsSplash that boards/<console>/AsteroidsSplash.h declares. The splash screens use RGBA8888: their colour gradients band or turn grainy in 64 colours.