Development - ITheP/GamePad GitHub Wiki

General Config

General configuration can be found in the config.h file, including options for extra debugging, benchmarking, etc.

Debug/Benchmark options generally output to the serial device. Benchmarks give a general overview of the performance of components and can be used to help identify bottlenecks or areas for optimization. I tend to add/remove benchmarks as required as new developments are made.

Important - the project is set up so if Debug/Benchmarking/LEDs are enabled, their corresponding code is not compiled, leading to smaller faster code.

Controller Specific Config

At time of writing, individual device controller configurations are found in the src/devices/... folder. This is where you customize the configuration of each folder. Theoretically no code changes should be required, outside of the controllers ControllerConfig.h and ControllerConfig.cpp files.

Please look at examples to see what they do.

The controller you want to compile against for your physical device is defined in the DeviceConfig.h file. I.e. change the include path in the DeviceConfig.h to point to the correct controller.

Note that this may change per controller, per installation, per controller type - whatever is custom to your particular installation. Controller configurations are specific to the physical electronics/pins/LED's/buttons/etc. you put together.

Arduino IDE

Originally written using Arduino IDE. For reference, the following were needed...

  • My setup used ESP32S3 Dev Module
  • Remember to enable Tools -> USB CDC On Boot -> Enabled

VSCode IDE:

Project got migrated to VSCode using PlatformIO. More complicated but a far superior experience, and compilation times were far far FAR faster than the Arduino IDE.

To make this work, I made sure to configure the following in file platformio.ini

platform = espressif32
board = esp32-s3-devkitc-1
framework = arduino
monitor_speed = 921600
monitor_rts = 0
monitor_dtr = 0
build_flags = -DARDUINO_USB_CDC_ON_BOOT=1

The build flag there is the equivalent of enabling the USB CDC On Boot option in the Arduino IDE. If this isn't enabled, serial output would not work.

RRFont

Make sure the CONVERT_PL_CHARS in RREFont.h = 0 (else character mappings screw and you are going to get corrupt screen rendering for certain characters)

Processing latencies

Initial tests with LEDs enabled and processed every loop measured around 720-760 FPS i.e. < 1.3ms. FastLED.show() is a bottleneck.

Throttling LED updates (which does have implications for effects, but you can always tune this) delivered great results while running around 8-9000 FPS.

FPS always varies slightly as buttons get pressed and more code is executed.

But overall - should be super low latency!

Main latencies will be bluetooth itself, and de-bounce timescales for buttons.

Main overheads are FastLED when updating the LED's, and pushing updates to the screen (also throttled in code to help performance).

Multithreading

On the ESP32-S3 there are 2 cores. In general, the main loop runs on core 1. Core 0 runs bluetooth/wifi etc. operations.

This solution runs a couple of separate tasks to e.g. update the LED's outside of the main loop. Theoretically this can be targeted e.g. on core 0 to allow the main loop to run at maximum speed, but by default it is set to run on core 1 so it doesn't impact bluetooth operations.

Realistically it all runs so fast its pretty irrelevant.

Throttling

Display updates are throttled - no use in 1000 FPS display. By default the config is set to the equivalent of 60fps.

LED updates are run more frequently - the default is more like 180-200fps. There are effects that propagate along multiple LEDs over time, and refreshes that are too slow can bottleneck the effect.

Timing is generally based on time deltas rather than frames, so timing of effects etc. is independent to update rates.

References

Uses libraries including...

Further Interest

  • santroller - another fantastic gamepad library with a ton of controller info and advice on customising electronics in guitar hero etc. controllers