{"id":15178666,"url":"https://github.com/ubaldot/vim-microdebugger","last_synced_at":"2025-10-26T17:31:00.580Z","repository":{"id":247622923,"uuid":"826182030","full_name":"ubaldot/vim-microdebugger","owner":"ubaldot","description":"A tiny plugin on top of Termdebug for remote debugging (docker, MCUs, etc)","archived":false,"fork":false,"pushed_at":"2025-08-25T15:25:39.000Z","size":405,"stargazers_count":6,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-25T17:35:42.965Z","etag":null,"topics":["microcontrollers","stm32","vim","vim-plugin","vim9","vim9-plugin"],"latest_commit_sha":null,"homepage":"","language":"Vim Script","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"vim","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ubaldot.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,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-07-09T08:21:14.000Z","updated_at":"2025-08-25T15:25:43.000Z","dependencies_parsed_at":"2024-09-23T10:02:50.418Z","dependency_job_id":"d19079bb-03a5-4200-8265-e4b3ef1e805b","html_url":"https://github.com/ubaldot/vim-microdebugger","commit_stats":{"total_commits":70,"total_committers":2,"mean_commits":35.0,"dds":"0.042857142857142816","last_synced_commit":"3d05e47a8431b8991c17d40326a65fd85b1c8103"},"previous_names":["ubaldot/vim-microdebugger"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ubaldot/vim-microdebugger","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ubaldot%2Fvim-microdebugger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ubaldot%2Fvim-microdebugger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ubaldot%2Fvim-microdebugger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ubaldot%2Fvim-microdebugger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ubaldot","download_url":"https://codeload.github.com/ubaldot/vim-microdebugger/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ubaldot%2Fvim-microdebugger/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281140927,"owners_count":26450542,"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","status":"online","status_checked_at":"2025-10-26T02:00:06.575Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["microcontrollers","stm32","vim","vim-plugin","vim9","vim9-plugin"],"created_at":"2024-09-27T15:21:15.951Z","updated_at":"2025-10-26T17:31:00.279Z","avatar_url":"https://github.com/ubaldot.png","language":"Vim Script","readme":"# vim-microdebugger\n\nA micro plugin built on top of Termdebug to facilitate remote gdb debugging.\nThrough this plugin, you should easily debug in docker\ncontainers, micro-controllers (MCUs) and everything that runs a gdbserver.\n\nIt is written in Vim9 and it requires Vim 9.1.0602.\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"/Microdebugger.png\" width=\"100%\" height=\"100%\"\u003e\n\u003c/p\u003e\n\nMicrodebugger starts a server in a hidden, unlisted buffer that you can\nconnect to by using Termdebug as a gdb client.\n\nThe server could be an `openocd` server or a docker container that runs a\ngdbserver.\n\nAt this point, you have pretty much the same interface as Termdebug with few\ndifferences: the `debugged-program` window is not used, the status lines are a\nbit different, the auxiliary buffers are unlisted, and the overall windows\nlayout is different. Furthermore, you can define more mappings and you have an\nextra window called `monitor` to run an external program, like for example `pyserial` to\nmonitor the traffic on the serial port.\n\nI'll try as much as I can to keep it in sync with Termdebug. For example, if\nsome of the mentioned changes will be included in Termdebug then they will be\nremoved from here.\n\n## Commands\n\nThe available commands in addition to those provided by Termdebug are the\nfollowing:\n\n```\n# Starts the microdebugger. Use this to start the microdebugger\n:MicroDebug\n\n# Create or jump to the monitor window\n:MicroDebugMonitor\n\n# Create or jump to the server window\n:MicroDebugServer\n\n# Equivalent to `monitor halt`\n:MicroDebugHalt\n\n# Equivalent to `monitor resume`\n:MicroDebugResume\n\n# Create or jump to the disassemble window\n:MicroDebugAsm\n\n# Create or jump to the variables window\n:MicroDebugVar\n```\n\nDo not use `:Termdebug` to start remote debugging but use `:MicroDebug`\ninstead.\n\nThe commands `:MicroDebugAsm` and `:MicroDebugVar` are wrappers around `:Asm`\nand `:Var` commands of Termdebug that you should use if you use this plugin.\nOtherwise, the windows layout will get messy.\n\n## Configuration\n\nThe configuration parameters are the following:\n\n```\n# Command to start the server\ng:microdebugger_server_command\n\n# If the server takes time to start up, increase this value (default 1000ms)\n# Note that g:termdebug_config['timeout'] is used in the client side,\n# whereas g:microdebugger_server_waiting_time is used in the server side\ng:microdebugger_server_waiting_time # [ms]\n\n# List of windows to include in the layout. Possible values: 'variables', 'asm', 'monitor', 'openocd'.\ng:microdebugger_aux_windows\n\n# Program to be executed in the monitor window\ng:microdebugger_monitor_command\n\n# If the program in the monitor window takes time to start up, increase this value (default 100ms)\ng:microdebugger_monitor_waiting_time\n\n# Height of gdb window (default '')\ng:microdebugger_gdb_win_height\n\n# Stacked aux windows position: 'L' or 'H' (default 'L')\ng:microdebugger_aux_win_pos\n\n# Width of the stacked aux windows (default \u0026columns / 3)\ng:microdebugger_aux_win_width\n\n# User-defined mappings\ng:microdebugger_mappings\n\n# Command for sending SIGINT (only for Windows)\ng:microdebugger_windows_CtrlC_program\n```\n\nAt the bare minimum, you have to establish how to fire up the server and how\nto connect to it. This is done through `g:microdebugger_server_command` and\n`g:termdebug_config['command']`, respectively.\n\nNote that `g:microdebugger_server_command`, which is executed on \nthe server side, may take some time to be completed. \nIf the client tries to connect to the gdb server before the gdb server is up \nand running, the debugger ends up in an *failed connection* error. \nThis means that before trying to connect to the gdb server, you must wait that \nthe gdb server is up and running and that is listening to some port.\n\n### Configuration for debugging in docker containers\n\nAn example follows:\n\n```\nvim9script\n\ng:termdebug_config = {}\ng:termdebug_config['command'] = ['gdb', '-ex', 'shell sleep 6', '-ex', 'target extended-remote localhost:1234',\n  '-ex', 'set substitute-path /app /home/ubaldot/projects/apollo15']\ng:termdebug_config['timeout'] = 800\n\ng:microdebugger_server_command = ['docker run --rm -i -p 1234:1234 my_image  gdbserver \"--once --no-startup-with-shell 0.0.0.0:1234 ./build/my_executable\"']\n```\n\n### Configuration for debugging MCU:s through an openocd server\n\nA good overview of how openocd works along with different clients is given\n[here](https://stackoverflow.com/questions/38033130/how-to-use-the-gdb-gnu-debugger-and-openocd-for-microcontroller-debugging-fr).\nAn example of initialization script could be the following. This time I also\ninclude some mappings.\n\n```\nvim9script\n\ng:termdebug_config['command'] = ['arm-none-eabi-gdb', '-ex', 'target extended-remote localhost:3333', '-ex', 'monitor reset']\ng:termdebug_config['timeout'] = 500\n\ng:microdebugger_windows_CtrlC_program = 'SendSignalCtrlC'\ng:microdebugger_openocd_command = ['openocd', '-f', 'stlink.cfg', '-f', 'stm32f4x.cfg']\n# Or something like g:microdebugger_openocd_command = ['cmd.exe', '/c', 'openocd_startup.bat']\ng:microdebugger_aux_windows = ['variables', 'monitor']\ng:microdebugger_monitor_command = ['screen', '/dev/ttyUSB0', '115200']\ng:microdebugger_gdb_win_height = 8\ng:microdebugger_server_waiting_time = 5000 # ms\n\n# Some mappings\ng:microdebugger_mappings = { C: '\u003cCmd\u003eContinue\u003cCR\u003e\u003ccmd\u003ecall TermDebugSendCommand(\"display\")\u003ccr\u003e',\n    B: '\u003cCmd\u003eBreak\u003cCR\u003e\u003ccmd\u003ecall TermDebugSendCommand(\"display\")\u003ccr\u003e',\n    D: '\u003cCmd\u003eClear\u003cCR\u003e\u003ccmd\u003ecall TermDebugSendCommand(\"display\")\u003ccr\u003e',\n    I: '\u003cCmd\u003eStep\u003cCR\u003e\u003ccmd\u003ecall TermDebugSendCommand(\"display\")\u003ccr\u003e',\n    O: '\u003cCmd\u003eOver\u003cCR\u003e\u003ccmd\u003ecall TermDebugSendCommand(\"display\")\u003ccr\u003e',\n    F: '\u003cCmd\u003eFinish\u003cCR\u003e\u003ccmd\u003ecall TermDebugSendCommand(\"display\")\u003ccr\u003e',\n    S: '\u003cCmd\u003eStop\u003cCR\u003e\u003ccmd\u003ecall TermDebugSendCommand(\"display\")\u003ccr\u003e',\n    U: '\u003cCmd\u003eUntil\u003cCR\u003e\u003ccmd\u003ecall TermDebugSendCommand(\"display\")\u003ccr\u003e',\n    T: '\u003cCmd\u003eTbreak\u003cCR\u003e\u003ccmd\u003ecall TermDebugSendCommand(\"display\")\u003ccr\u003e'}\n```\n\n## Events\n\nThe order of execution when launching MicroDebugger is to start the server,\nthen start Termdebug, and finally start the auxiliary buffers.\n\nIn addition to the events offered by Termdebug, you have an additional event\n`MicrodebuggerStartPost` that you can use in your auto-commands.\n\n## Known bugs\n\nThe plugin has been tested on macos, Windows (read below) and partially on\nLinux.\n\nSometimes you can get some `Termdebug` errors when launching `Microdebugger`.\nIn that case, manually add `Termdebug` with `:packadd termdebug`.\n\nWhen the plugin execution is terminated, you get an error message about\nOpenOCD. You can safely ignore it, it is only an `echo` message that is\nerroneously triggered.\n\n\u003e [!WARNING]\n\u003e\n\u003e **For Windows users.** When you run `continue` with no breakpoints it does\n\u003e not seem possible to take control back of the gdb console. Ideally, a\n\u003e `ctrl-c` should interrupt gdb but it is not the case. You must go on the gdb\n\u003e console and execute `\u003cc-w\u003e:close!` to shutoff everything.\n\u003e\n\u003e However, if you are willing to use an external program for sending `SIGINT`\n\u003e signals, then you can set `g:microdebugger_windows_CtrlC_program`. By doing\n\u003e that, `ctrl-c` would exploit such a program to interrupt the non-responding\n\u003e gdb.\n\u003e\n\u003e For example, if you use\n\u003e [SendSignalCtrlC.exe](https://github.com/SergeyPirogov/video-recorder-java/raw/master/core/src/main/resources/SendSignalCtrlC.exe),\n\u003e then you can set\n\u003e `g:microdebugger_windows_CtrlC_program = 'SendSignalCtrlC'`. Be sure that\n\u003e such a program is in your Windows path. Once done, you have a working\n\u003e `:Stop` command mapped locally to `\u003cc-c\u003e`.\n\u003e\n\u003e **BE CAREFUL** since the command may append garbage to the buffer opened in\n\u003e the `:Source` window.\n\n## Happy debugging!\n","funding_links":[],"categories":["Integrations","Vim Script"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fubaldot%2Fvim-microdebugger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fubaldot%2Fvim-microdebugger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fubaldot%2Fvim-microdebugger/lists"}