Skip to content

Developer Notes

Creating a new release

  • update src/version.txt and uni_version.h
  • update CHANGELOG.md
  • update AUTHORS
  • merge main into develop... and solve possible conflicts on develop first
  • then merge develop into main
git merge main
# Solve possible conflicts
git checkout main
git merge develop
  • generate a new tag
git tag -a 4.0
  • push changes both to Gitlab and GitHub:
git push gitlab
git push gitlab --tags
git push github
git push github --tags
  • Generate binaries
cd tools/fw
./build.py --set-version v2.4.0 all
  • And generate the release both in Gitlab and GitHub, and upload the already generated binaries

Analyzing a core dump

Since v2.4.0, core dumps are stored in flash. And they can be retrieved using:

# Using just one command
espcoredump.py --port /dev/ttyUSB0 --baud 921600 info_corefile build/bluepad32-app.elf

# Or it can be done in two parts
esptool.py --port /dev/ttyUSB0 read_flash 0x110000 0x10000 /tmp/core.bin
espcoredump.py info_corefile --core /tmp/core.bin --core-format raw build/bluepad32-app.elf 
 ```

## Analyzing Bluetooth packets

Use the "posix" platform:

```sh
cd example/posix
mkdir build && cd build
cmake ..
make -j
sudo ./bluepad32_posix_example_app

Let it run... stop it... and open the logs using:

wireshark /tmp/hci_dump.pklg

Using OpenOCD with Pico W

Detailed instructions here: https://www.raspberrypi.com/documentation/microcontrollers/debug-probe.html

Recompile by using UART as output. In the CMakeLists.txt do this: 

# Disable USB output
pico_enable_stdio_usb(bluepad32_picow_example_app 0)
# Enable UART output
pico_enable_stdio_uart(bluepad32_picow_example_app 1)

Program Pico W

sudo openocd -f interface/cmsis-dap.cfg -f target/rp2040.cfg -c "adapter speed 5000" -c "program bluepad32_picow_example_app.elf verify reset exit"

Debug Pico W

Have four terminals.

In terminal 1:

sudo openocd -f interface/cmsis-dap.cfg -f target/rp2040.cfg -c "adapter speed 5000"

In terminal 2:

arm-none-eabi-gdb bluepad32_picow_example_app.elf
(gdb) target remote localhost:3333
(gdb) cont

In terminal 3:

arm-none-eabi-gdb bluepad32_picow_example_app.elf
(gdb) target remote localhost:3334
(gdb) monitor reset init
(gdb) cont

In terminal 4:

tio /dev/ttyACM0

Creating a template project from scratch

It is split in four parts:

  • Create an empty project
  • Install the needed components
  • Update configuration
  • Copy the "main Arduino" files to your project

Create an empty ESP-IDF project

Create an ESP-IDF project from template:

# One simple way to start a new ESP-IDF project, is to clone the "template" project
git clone --recursive https://github.com/espressif/esp-idf-template my_project

Installing components

Include the following components in your project's components folder:

  • arduino
  • bluepad32
  • bluepad32_arduino
  • btstack

Arduino component:

cd ${MYPROJECT}/components/
git clone --recursive https://github.com/espressif/arduino-esp32.git arduino

Bluepad32 / Bluepad32_arduino component:

# Just copy bluepad32 component to your project's component folder
cp -r ${BLUEPAD32}/src/components/bluepad32 ${MYPROJECT}/components
cp -r ${BLUEPAD32}/src/components/bluepad32_arduino ${MYPROJECT}/components

BTStack component:

cd ${BLUEPAD32}/external/btstack/port/esp32
# This will install BTstack as a component inside Bluepad32 source code (recommended).
# Remove "IDF_PATH=${BLUEPAD32}/src/" if you want it installed in the ESP-IDF folder
IDF_PATH=${BLUEPAD32}/src/ ./integrate_btstack.py

Update configuration

And then do:

  1. idf.py menuconfig

  2. And set these Arduino options from Arduino Configuration:

  3. "Autostart Arduino setup and loop on boot" must be OFF

  4. "Core on which Arduino's setup() and loop() are running" must be "Core 1"
    • Same for the remaining "Core" options
  5. "Loop thread stack size": depends on what you do. 8192 is a good default value.
  6. "Include only specific Arduino libraries" must ON
    • "Enable BLE" must be OFF
    • "Enable BluetoothSerial" must be OFF

sdk-config

  1. Set these Bluetooth options:

  2. "Component Config" -> "Bluetooth" -> "Bluetooth Controller"

    • "Bluetooth Controller Mode": Bluetooth Dual Mode
    • "BLE Max Connections": 3
    • "BR/EDR ACL Max Connections": 7
    • "BR/EDR Sync (SCO/eSCO) Max Connections": 3
  3. "Component Config" -> "Bluetooth" -> "Bluetooth Host"
    • "Controller only"

sdkconfig-bluetooth

sdkconfig-bluetooth2

  1. Set these ESP32 options:

  2. "Component Config" -> "ESP32-specific"

    • "Main XTAL frequency": Autodetect

sdkconfig-esp32

  1. Set Serial flasher config:

  2. "Serial flasher cofnig"

    • "Flash size": 4MB (or choose the right for your module)

Copy Bluepad32-Arduino API files

And in your main project, you must include the files that are located in ${BLUEPAD32}/src/main/*

cd my_project/main
cp -r ${BLUEPAD32}/src/main/* .

Further reading: