{"id":14963121,"url":"https://github.com/espressif/openocd-on-esp32","last_synced_at":"2025-10-19T08:31:49.159Z","repository":{"id":212454405,"uuid":"728590447","full_name":"espressif/openocd-on-esp32","owner":"espressif","description":"OpenOCD port running on ESP32-S3 microcontrollers","archived":false,"fork":false,"pushed_at":"2024-02-07T22:05:14.000Z","size":151,"stargazers_count":61,"open_issues_count":0,"forks_count":6,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-01-31T17:17:36.188Z","etag":null,"topics":["esp-idf","esp32","openocd"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/espressif.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-12-07T09:13:42.000Z","updated_at":"2025-01-24T20:58:54.000Z","dependencies_parsed_at":null,"dependency_job_id":"e5b678e3-fa7e-4085-a952-883ec8b95694","html_url":"https://github.com/espressif/openocd-on-esp32","commit_stats":null,"previous_names":["espressif/openocd-on-esp32"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/espressif%2Fopenocd-on-esp32","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/espressif%2Fopenocd-on-esp32/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/espressif%2Fopenocd-on-esp32/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/espressif%2Fopenocd-on-esp32/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/espressif","download_url":"https://codeload.github.com/espressif/openocd-on-esp32/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237092701,"owners_count":19254255,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esp-idf","esp32","openocd"],"created_at":"2024-09-24T13:31:03.244Z","updated_at":"2025-10-19T08:31:48.778Z","avatar_url":"https://github.com/espressif.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenOCD application for ESP32-S3\n\nThis repository contains a port of OpenOCD which runs on an ESP32-S3. It allows using an ESP32-S3 board as a stand-alone debugger for other chips, which exposes a GDB server port over Wi-Fi or Ethernet.\n\nThe repository also demonstrates how a complex application (such as OpenOCD) can be ported to ESP-IDF.\n\n## Prerequisites\n\n- This application only can run on ESP32-S3 boards which will function as a debugger. ESP32 is not supported due to the limited memory.\n- PSRAM is necessary for the ESP32-S3 boards.\n- Make sure to adjust Flash and PSRAM spi modes (DIO, QIO, OPI) from the menuconfig.\n- Target board should be flashed with an application.\n- Connect GPIOs from the debugger board to the target board using JTAG interface.\n\n  |Master pin | Function | Slave pin |\n  |-----------|----------|-----------|\n  | 38        | TCK      | 13        |\n  | 39        | TMS      | 14        |\n  | 40        | TDI      | 12        |\n  | 41        | TDO      | 15        |\n\nIf necessary, the master pins can be adjusted at run time using `esp_gpio_jtag_nums \u003ctck\u003e \u003ctms\u003e \u003ctdi\u003e \u003ctdo\u003e` OpenOCD command. For example,\n\n    esp_gpio_jtag_nums 38 39 40 41\n\nsets the configuration shown above. The default pins are set in `interface/esp_gpio_jtag.cfg` file (in the OpenOCD submodule).\n\n- Connect a led to see the JTAG tx/rx activity (optional)\n\n  If a led is connected to one of the GPIO pins, it can be activated with  `esp_gpio_blink_num \u003cled_pin_num\u003e` OpenOCD command inside `interface/esp_gpio_jtag.cfg`\n\nSWD interface is also supported. The target board can be connected from the SWD pins using `interface/esp_gpio_swd.cfg`\n\n|Master pin | Slave Pin Function |\n|-----------|--------------------|\n| 38        |       SWCLK        |\n| 39        |       SWDIO        |\n\n## Supported IDF versions\n\nAll components are expected to be usable with IDF 5.0 or later versions.\n\n## Build and flash\n\n1. Get the submodules: `git submodule update --init --recursive`.\n\n2. Configure Wi-Fi SSID and password in menuconfig.\n\n3. Run `idf.py flash monitor` to build and flash the application and the FATFS filesystem image (generated at build time). When flashing again, use `idf.py app-flash` to only flash the application.\n\n## Flash from jtag\n\nWith the help of OpenOCD, it is also possible to load application from the jtag. During the cmake configuration phase, openocd binary is beging searched in the installed idf tools directory. If the binary is found, 2 commands will be ready to run;\n\n1. Use `cmake --build build -t jtag-flasher-full`  to flash the application and the FATFS filesystem\n\n2. Use `cmake --build build -t jtag-flasher` to only flash the application to the specific locatioon. Which is 0x10000 by default.\n\n`board/esp32s3-builtin.cfg` is used as an OpenOCD config file by default.\n\n## Run\n\nOpen the monitor and check that the ESP32-S3 output ends with the following:\n\n```\nI (6393) example_common: - IPv4 address: 192.168.32.56,\nI (6393) example_common: - IPv6 address: fe80:0000:0000:0000:7edf:a1ff:fee0:104c, type: ESP_IP6_ADDR_IS_LINK_LOCAL\nOpen On-Chip Debugger 0.12.0 (2023-12-20-21:53)\nLicensed under GNU GPL v2\nFor bug reports, read\n        http://openocd.org/doc/doxygen/bugs.html\ndebug_level: 2\nWarn : Could not determine executable path, using configured BINDIR.\n1\nesp_gpio GPIO config: tck = 38, tms = 39, tdi = 40, tdo = 41\n3\nInfo : auto-selecting first available session transport \"jtag\". To override use 'transport select \u003ctransport\u003e'.\nInfo : Listening on port 6666 for tcl connections\nInfo : Listening on port 4444 for telnet connections\nInfo : esp_gpio GPIO JTAG/SWD bitbang driver\nInfo : clock speed 1000 kHz\nInfo : JTAG tap: esp32.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)\nInfo : JTAG tap: esp32.cpu1 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)\nInfo : [esp32.cpu0] Examination succeed\nInfo : [esp32.cpu1] Examination succeed\nInfo : starting gdb server for esp32.cpu0 on 3333\nInfo : Listening on port 3333 for gdb connections\nInfo : [esp32.cpu0] Target halted, PC=0x4008456A, debug_reason=00000000\nInfo : [esp32.cpu0] Reset cause (1) - (Power on reset)\nInfo : [esp32.cpu1] Target halted, PC=0x4008456A, debug_reason=00000000\nInfo : [esp32.cpu1] Reset cause (14) - (CPU1 reset by CPU0)\n```\n\nIf OpenOCD complains about the JTAG chain, 0x00's, 0x1f's, check the connections.\n\nNote the IP printed in the \"example_connect\" line before OpenOCD output starts.\n\nRun GDB and instruct it to connect to the debugger over TCP:\n\n    xtensa-esp32-elf-gdb  -ex \"set remotetimeout 30\" -ex \"target extended-remote 192.168.0.221:3333\" build/blink.elf\n\n(replace the IP address with the one you saw in the log).\n\n## Web server connection\n\nOn the first run, the application creates an access point with default SSID `esp-openocd` without password. You can access the web server by connecting to this network and typing the IP address `192.168.4.1` in a browser. Then, you will see the configuration menu to instantly change Wi-Fi settings and OpenOCD command line arguments.\n\n## ESP-BOX\n\nOpenOCD application has been ported to work on the ESP-BOX development board, with configuration screen and a provisioning feature.\nBy default, the ESP-BOX and UI functionality are disabled but can be enabled from the menuconfig.\n\n## OpenOCD configuration\n\nThe settings for OpenOCD can be configured either through the web page or the touch screen on the ESP-BOX. By default, only the configurations for Espressif chips are preloaded into the file system. However, it is also possible to use other chip configuration files by directly uploading them from the web page.\n\n## License\n\nThe code in this repository is Copyright (c) 2022-2023 Espressif Systems (Shanghai) Co. Ltd., and licensed under Apache 2.0 license, available in [LICENSE](LICENSE) file.\n\nOpenOCD source code added as a submodule is licensed under GPL v2.0 or later license.\n\n## Contributing\n\nWe welcome contributions to this project in the form of bug reports, feature requests and pull requests.\n\nIssue reports and feature requests can be submitted using Github Issues: https://github.com/espressif/openocd-on-esp32/issues. Please check if the issue has already been reported before opening a new one.\n\nContributions in the form of pull requests should follow ESP-IDF project's [contribution guidelines](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/contribute/index.html).\n\n## Pre-commit hooks\n\nOpenOCD-on-ESP32 project uses [pre-commit hooks](https://pre-commit.com/) to perform code formatting and other checks when you run `git commit`.\n\nTo install pre-commit hooks, run `pip install pre-commit \u0026\u0026 pre-commit install`.\n\nIf a pre-commit hook has modified any of the files when you run `git commit`, add these changes using `git add` and run `git commit` again.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fespressif%2Fopenocd-on-esp32","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fespressif%2Fopenocd-on-esp32","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fespressif%2Fopenocd-on-esp32/lists"}