A streamlined framework to assist in patching proprietary ESP32 libraries from Xtensa ELF file or user's code.

• Requirements
  • Linux/Ubuntu
  • Windows 7/10
• Quick Start Template Project
• Sample Project - Bluetooth BR/EDR Patching
  • Build Patched Firmware
  • Flash Firmware
• Framework - Patching ESP32 from Inside and Outside
  • 1. Patching Proprietary Libraries (Inside/Outside user code)
  • 2. Runtime Patching (Inside user code)
  • 3. ROM Patching (Inside user code)
• Reverse Engineering while Debugging
  • Required Tools
  • GDB & Ghidra Live Synchronization

This project was tested to work on the Windows 7/10 or Ubuntu 18.04, but it should work in any system that has Python 3 installed.

Run the following to install Python 3 if you don't have it installed on your system yet:

sudo apt-get install python3

You can either manually install Python 3 or run the provided batch file requirements.bat on the root folder of this project.

# On Windows 7/10 command prompt
requirements.bat

If Windows store opens when you type python on the command prompt, disable python in "App execution aliases" in settings.

TODO

The provided firmware.py automates the firmware building & patching process. Under the hood, it calls Platformio Framework to:

1. Download Xtensa toolchain, ESP-IDF SDK and openocd debugger. This can be configured on platformio.ini;

2. Compile the main code in src/ folder;

2. Patch the final ELF binary via user provided patch script UserPatch.py, which uses this framework's patching library.

You can build the sample patching project for Bluetooth BR/EDR by running the following:

# On Linux/Ubuntu bash
python3 firmware.py build
# On Windows 7/10 command prompt
python firmware.py build

First time building the firmware will take some time. A successful build output should give you the following output:

firmware.py provides a facility to flash the built firmware. If previous step is successful, you can flash the final patched firmware on ESP32 as follows:

# On Linux/Ubuntu bash
./firmware.py flash /dev/ttyUSB0 # Change /dev/ttyUSB0 to match your port name
# On Windows 7/10 command prompt
python firmware.py flash COM4 # Change COM4 to match your port name

TODO

TODO

TODO

TODO

TODO

TODO