Adjusting build options

Use the build helper to edit GhostESP configuration options.

build.py wraps Espressif’s build tools so you can change GhostESP feature flags without manual setup. Follow these steps to run menuconfig, persist changes, and rebuild.

Prerequisites

  • Python 3 installed with access to the command line.
  • ESP-IDF v5.4.1, v5.5 or v5.5.1 on disk. build.py can auto-detect common locations or also download it for you.
  • GhostESP repository cloned locally. Clone from GitHub and navigate into the project directory before running the script.

1. Launch the helper

From the project root:

python build.py

Skip the interactive picker if you know your targets:

python build.py --targets 2 3

Use --targets all to queue every board profile.

When prompted for ESP-IDF, confirm a detected path or allow the script to download v5.5. Use --idf-path <path> to skip the prompt.

2. Select a build target

GhostESP ships configs for multiple boards inside configs/. The helper lists them with numeric IDs. Enter the index for the target whose Kconfig you want to edit (for example esp32s3-generic).

The script copies that entry’s sdkconfig.* file into sdkconfig and sdkconfig.defaults, then runs idf.py set-target so menuconfig matches the board.

3. Run menuconfig for GhostESP options

After applying the base config, build.py launches:

idf.py menuconfig

Use the menu to browse GhostESP Options → GhostESP Features. Save and exit when finished.

Enabling NFC features

Open Ghost ESP Options → NFC Options to toggle the backends:

  • Enable PN532 NFC turns on the PN532 reader and exposes pin settings for SCL/SDA/IRQ/RST.
  • Enable Chameleon Ultra NFC lets GhostESP use a Chameleon Ultra over BLE as the NFC front-end. This option defaults to enabled when BLE is compiled in.

Turning on either backend automatically sets the internal HAS_NFC flag, which enables the UI and shared NFC code paths.

Enabling displays

Navigate to Ghost ESP Options → Display Options for screen hardware:

  • Toggle Enable Screen Support to bring the LCD driver into the build.
  • Adjust resolution via TFT Width and TFT Height, or enable board-specific panels such as Enable Waveshare LCD, Enable Crowtech LCD, Enable Sunton LCD, or Enable JC3248W535EN LCD depending on your hardware.
  • Optional helpers like Enable Touchscreen, Use 7-inch Display, and Enable Status Display expose extra pins and I2C settings when needed.

Status Display Configuration

When Enable Status Display is enabled, you can configure:

  • Status Display SDA Pin and Status Display SCL Pin: I2C pins for the OLED display (default: GPIO 6/7 for shared IO expander bus, or GPIO 17/18 for Heltec V3).
  • Status Display I2C Port: I2C controller port (0 or 1).
  • Status Display I2C Address: I2C address (default: 0x3C for most OLED displays).
  • Status Display Power Control Pin (Vext): GPIO pin for power control. For Heltec V3, set this to GPIO 36. Set to -1 to disable.
  • Status Display Reset Pin: GPIO pin for display reset. For Heltec V3, set this to GPIO 21. Set to -1 to disable.
  • Rotate status display 180 degrees: Optional rotation setting.

The status display shows system information, attack status, and idle animations when configured. It’s particularly useful for boards like the Heltec V3 which includes an onboard OLED display.

Configuring LVGL display driver

After enabling Enable Screen Support, navigate to Component config → LVGL to configure the display driver:

  • Under LVGL TFT Display, select your display controller (e.g., ILI9341, ST7789, etc.).
  • Configure LVGL Touch Input if your screen has a touchscreen.
  • Adjust LVGL Display Settings for rotation, color depth, and refresh rate as needed for your hardware.

4. Decide where to store your changes

Once menuconfig exits, build.py asks whether to write the new configuration back into the source tree:

  • Yes — Copies the generated sdkconfig into the original configs/sdkconfig.* file and into sdkconfig.defaults. Choose this when you want the board profile to permanently carry the new settings.
  • No — Keeps sdkconfig.defaults updated for the current build only without altering the source file. This is useful when experimenting.

Regardless of your choice, the helper syncs sdkconfig.defaults so the next build uses the options you just saved.

5. Rebuild firmware (optional)

If you continue through the prompts, build.py can clean, rebuild, and package artifacts automatically. Otherwise, rerun later with:

python build.py --targets <index>

The script will reuse the modified sdkconfig.defaults unless you overwrite it.

Tips

  • Running python build.py --no-auto-download disables the ESP-IDF fetch prompt if you prefer manual installs only.
  • Delete sdkconfig and sdkconfig.defaults to revert to the pristine profile before another run.
  • Use separate directories or virtual environments per ESP-IDF version to avoid mixing toolchains when switching targets.