{"id":16897734,"url":"https://github.com/texitoi/blue-pill-quickstart","last_synced_at":"2025-07-12T08:38:27.690Z","repository":{"id":66120848,"uuid":"142625231","full_name":"TeXitoi/blue-pill-quickstart","owner":"TeXitoi","description":"Quickstart a Rust project for the blue pill board","archived":false,"fork":false,"pushed_at":"2020-08-26T08:09:53.000Z","size":289,"stargazers_count":111,"open_issues_count":2,"forks_count":14,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-02-27T19:26:32.642Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TeXitoi.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}},"created_at":"2018-07-27T21:31:00.000Z","updated_at":"2025-02-07T10:27:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"b8d16cf8-b99c-4f0f-9d6a-b86c3c4cf648","html_url":"https://github.com/TeXitoi/blue-pill-quickstart","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TeXitoi%2Fblue-pill-quickstart","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TeXitoi%2Fblue-pill-quickstart/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TeXitoi%2Fblue-pill-quickstart/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TeXitoi%2Fblue-pill-quickstart/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TeXitoi","download_url":"https://codeload.github.com/TeXitoi/blue-pill-quickstart/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243847061,"owners_count":20357317,"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":[],"created_at":"2024-10-13T17:39:34.388Z","updated_at":"2025-03-17T06:31:57.852Z","avatar_url":"https://github.com/TeXitoi.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# blue-pill-quickstart [![Build status](https://travis-ci.org/TeXitoi/blue-pill-quickstart.svg?branch=master)](https://travis-ci.org/TeXitoi/blue-pill-quickstart)\n\nQuickstart a Rust project for the [blue pill](https://wiki.stm32duino.com/index.php?title=Blue_Pill), or any similar STM32F103xx board.\n\n## Quickstart a new project\n\nThis section assumes your computer is ready to hack on a blue pill.\n\nGet and cleanup:\n\n```shell\ngit clone https://github.com/TeXitoi/blue-pill-quickstart.git my-new-project\ncd my-new-project\nrm -fr .git LICENSE README.md st-link-v2-blue-pill.jpg\ngit init\n```\n\nEdit `Cargo.toml` for author and project name, and you're ready to go.\n\n## Setting up your machine\n\nFirst, you need hardware. Buy a [blue pill](https://www.aliexpress.com/w/wholesale-stm32f103c8t6.html?\u0026SortType=total_tranpro_desc) and an [ST-Link V2](https://www.aliexpress.com/w/wholesale-st-link-v2.html?SortType=total_tranpro_desc). You also need a computer, the commands below are for a Debian based distribution. It should be easy to adapt the instructions to other operating systems (Linux, MacOSX, Windows).\n\nInstall rust and gdb support to compile and debug code for the Cortex-M3 which is the basis of the STM32F103xx MCU:\n\n```shell\ncurl https://sh.rustup.rs -sSf | sh\nrustup target add thumbv7m-none-eabi\nsudo apt-get install gdb-arm-none-eabi openocd\n```\n\nIf your distribution doesn't offer `gdb-arm-none-eabi`, you can try `gdb-multiarch` (on Ubuntu 18.04 for example) or `gdb`. In these cases, you'll have to update `.cargo/config` accordingly.\n\nClone the repository:\n\n```shell\ngit clone https://github.com/TeXitoi/blue-pill-quickstart.git\ncd blue-pill-quickstart\n```\n\nFirst connect your ST-Link to your blue pill, then connect the ST-Link to your computer.\n\n![ST-Link V2 to blue pill](st-link-v2-blue-pill.jpg)\n\nLaunch openocd in the `blue-pill-quickstart` directory:\n\n```shell\nopenocd\n```\n\nYou should see terminal output like this:\n\n```\nOpen On-Chip Debugger 0.10.0\n[...]\nInfo : stm32f1x.cpu: hardware has 6 breakpoints, 4 watchpoints\n```\n \nOpen a new terminal, compile and flash\n\n```shell\ncd blue-pill-quickstart\ncargo run\n```\n\nNow, the program is flashed, and you are on a gdb prompt. Type `c` (for continue) you can see the on board LED blinking.\n\n## Trouble Shooting\n\n### Wrong connection of the ST-Link\n\nThe pin mapping which is shown on the outer shell of your ST-Link might not be correct. If `openocd` returns `unknown code 0x9`, check the pin mapping by removing the ST-Link's shell, and check if the pin mapping printed on its PCB matches the mapping printed on the outer case.  If they differ, then use the mapping printed on the PCB.\n\nIf you're unable to remove the shell or the PCB is not readable, you can try one of these pin mappings which are known to exist:\n\n|pin|      |pin|       | \n|---|------|---|-------|\n| 1 | RST  | 2 | SWDIO |\n| 3 | GND  | 4 | GND   |\n| 5 | SWIM | 6 | SWCLK |\n| 7 | 3.3V | 8 | 3.3V  |\n| 9 | 5.0V |10 | 5.0V  |\n\n|pin|      |pin|       | \n|---|------|---|-------|\n| 1 | RST  | 2 | SWCLK |\n| 3 | SWIM | 4 | SWDIO |\n| 5 | GND  | 6 | GND   |\n| 7 | 3.3V | 8 | 3.3V  |\n| 9 | 5.0V |10 | 5.0V  |\n\n### Flash protected\n\nWhen flashing your blue pill for the first time, flashing may fail with the following messages in the openocd console:\n\n```\nError: stm32x device protected\nError: failed erasing sectors 0 to 23\nError: flash_erase returned -4\n```\n\nThis means your blue pill's flash is read-only protected. To unlock it, you can connect to your openocd session with:\n\n```shell\ntelnet localhost 4444\n```\n\n... and type the following commands:\n\n```\nreset halt\nstm32f1x unlock 0\nreset halt\n```\n\n### MCU in low power state\n\nIf the software which was already flashed to the Blue pill has put the processor core into a low power state, then this prevents the hardware debug interface from operating.  In this case, then OpenOCD will create output like this:\n\n```\nError: jtag status contains invalid mode value - communication failure\nPolling target stm32f1x.cpu failed, trying to reexamine\nExamination failed, GDB will be halted. Polling again in 100ms\nInfo : Previous state query failed, trying to reconnect\n```\n\nTo workaround this, press the reset button on the blue pill board whilst starting openocd.  If the software that you've flashed to the STM32F103xx is putting it into the low power mode (e.g. by using the `wfi` instruction), then you might want to disable this (e.g. by busy-looping instead) when building the code in development mode instead of release mode.\n\n\n## Sources\n\nThis quickstart is inspired by the [cortex-m-quickstart](https://github.com/japaric/cortex-m-quickstart) and [Discovery](https://rust-embedded.github.io/discovery/). I recommend reading them.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftexitoi%2Fblue-pill-quickstart","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftexitoi%2Fblue-pill-quickstart","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftexitoi%2Fblue-pill-quickstart/lists"}