{"id":13423288,"url":"https://github.com/rp-rs/rp-hal","last_synced_at":"2025-05-12T20:50:10.412Z","repository":{"id":37014100,"uuid":"331967192","full_name":"rp-rs/rp-hal","owner":"rp-rs","description":"A Rust Embedded-HAL for the rp series microcontrollers","archived":false,"fork":false,"pushed_at":"2025-03-13T19:36:32.000Z","size":2435,"stargazers_count":1614,"open_issues_count":75,"forks_count":256,"subscribers_count":25,"default_branch":"main","last_synced_at":"2025-05-05T21:14:41.535Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://crates.io/crates/rp2040-hal","language":"Rust","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/rp-rs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2021-01-22T14:19:17.000Z","updated_at":"2025-05-05T18:43:15.000Z","dependencies_parsed_at":"2023-10-02T06:28:37.093Z","dependency_job_id":"aedf44bc-8394-430e-88f2-bc856e8aa404","html_url":"https://github.com/rp-rs/rp-hal","commit_stats":{"total_commits":1084,"total_committers":125,"mean_commits":8.672,"dds":0.7020295202952029,"last_synced_commit":"e87e2acc233a9e3b54a9287dc2a7285db1969cad"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rp-rs%2Frp-hal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rp-rs%2Frp-hal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rp-rs%2Frp-hal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rp-rs%2Frp-hal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rp-rs","download_url":"https://codeload.github.com/rp-rs/rp-hal/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253820599,"owners_count":21969548,"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-07-31T00:00:28.056Z","updated_at":"2025-05-12T20:50:10.389Z","avatar_url":"https://github.com/rp-rs.png","language":"Rust","readme":"\u003c!-- PROJECT LOGO --\u003e\n\u003cbr /\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/rp-rs/rp-hal\"\u003e\n    \u003cimg src=\"https://www.svgrepo.com/show/281119/microchip.svg\" alt=\"Logo\" width=\"140\" height=\"140\"\u003e\n  \u003c/a\u003e\n\n   \u003ch3 align=\"center\"\u003erp-hal\u003c/h3\u003e\n\n  \u003cp align=\"center\"\u003e\n    Rust support for the \"Raspberry Silicon\" family of microcontrollers\n    \u003cbr /\u003e\n    \u003ca href=\"https://docs.rs/rp2040-hal\"\u003e\u003cstrong\u003eExplore the API docs »\u003c/strong\u003e\u003c/a\u003e\n    \u003cbr /\u003e\n    \u003cbr /\u003e\n    \u003ca href=\"https://github.com/rp-rs/rp-hal-boards/tree/main/boards/rp-pico/examples\"\u003eView Demos\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/rp-rs/rp-hal/issues\"\u003eReport a Bug\u003c/a\u003e\n    ·\n    \u003ca href=\"https://matrix.to/#/#rp-rs:matrix.org\"\u003eChat on Matrix\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n\n\u003c!-- TABLE OF CONTENTS --\u003e\n\u003cdetails open=\"open\"\u003e\n  \u003csummary\u003e\u003ch2 style=\"display: inline-block\"\u003eTable of Contents\u003c/h2\u003e\u003c/summary\u003e\n  \u003col\u003e\n    \u003cli\u003e\u003ca href=\"#getting-started\"\u003eGetting Started\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#programming\"\u003eProgramming\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#roadmap\"\u003eRoadmap\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#license\"\u003eLicense\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#contact\"\u003eContact\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#acknowledgements\"\u003eAcknowledgements\u003c/a\u003e\u003c/li\u003e\n  \u003c/ol\u003e\n\u003c/details\u003e\n\n\u003c!-- GETTING STARTED --\u003e\n\n## Getting Started\n\nSo, you want to program your new Raspberry Silicon microcontroller, using the\nRust programming language. You've come to the right place!\n\nThis repository is `rp-hal` - a collection of high-level drivers for the\nRaspberry Silicon RP2040 microcontroller and various associated boards, like\nthe Raspberry Pi Pico and the Adafruit Feather RP2040.\n\nIf you want to write an application for Raspberry Silicon, check out our\n[RP2040 Project Template](https://github.com/rp-rs/rp2040-project-template).\n\nIf you want to write code that uses the Raspberry Silicon PIO State Machines,\ncheck out [pio-rs](https://github.com/rp-rs/pio-rs). You can even compile PIO\nprograms at run-time, on the RP2040 itself!\n\nIf you want to try out some examples on one of our supported boards, check out\nthe list of [*Board Support Packages*][BSPs], and click through to see the various\nexamples for each board.\n\nBefore trying any of the examples, please ensure you have the latest stable\nversion of Rust installed, along with the right target support:\n\n```sh\nrustup self update\nrustup update stable\nrustup target add thumbv6m-none-eabi\n```\n\nYou may also want to install these helpful tools:\n\n```sh\n# Useful to creating UF2 images for the RP2040 USB Bootloader\ncargo install elf2uf2-rs --locked\n# Useful for flashing over the SWD pins using a supported JTAG probe\ncargo install --locked probe-rs-tools\n```\n\n## Packages\n\nThere is a _Hardware Abstraction Layer_ (or HAL) crate for the RP2040 chip,\nand _Board Support Package_ crates for a number of RP2040 based PCBs. If you\nare writing code that should run on any microcontroller, consider using the\ngeneric Rust Embedded Working Group's [Embedded HAL].\n\nIf you are writing code that should work on any RP2040 device, use the _HAL_\ncrate. If you are running code on a specific board, use the appropriate _BSP_\ncrate (which will include the _HAL_ crate for you). Please note, you cannot\ndepend on multiple _BSP_ crates; you have to pick one, or use [Cargo Features]\nto select one at build time.\n\nEach BSP includes some examples to show off the features of that particular board.\n\n[Cargo Workspace]: https://doc.rust-lang.org/cargo/reference/workspaces.html\n[Embedded HAL]: https://github.com/rust-embedded/embedded-hal\n[Cargo Features]: https://doc.rust-lang.org/cargo/reference/features.html\n\n### [rp2040-hal] - The HAL for the [Raspberry Silicon RP2040]\n\nYou should include this crate in your project if you want to write a driver or\nlibrary that runs on the [Raspberry Silicon RP2040], or if you are writing a Board\nSupport Package (see later on).\n\nThe crate provides high-level drivers for the RP2040's internal peripherals,\nsuch as the SPI Controller and the I²C Controller. It doesn't know anything\nabout how your particular board is wired up (such as what each IO pin of the\nRP2040 is connected to).\n\nThere are examples in this crate to show how to use various peripherals\n(GPIO, I²C, SPI, UART, etc) but note that the pin-outs may not match any\nparticular board.\n\n### [BSPs] - Board support packages\n\nThere are BSPs for various boards based on the RP2040 available in\na [separate repository][BSPs].\n\n[rp2040-hal]: https://github.com/rp-rs/rp-hal/tree/main/rp2040-hal\n[Raspberry Silicon RP2040]: https://www.raspberrypi.org/products/rp2040/\n[BSPs]: https://github.com/rp-rs/rp-hal-boards/\n\n\u003c!-- PROGRAMMING --\u003e\n## Programming\n\nRust generates standard Arm ELF files, which you can load onto your Raspberry Pi\nSilicon device with your favourite Arm flashing/debugging tool. In addition, the\nRP2040 contains a ROM bootloader which appears as a Mass Storage Device over USB\nthat accepts UF2 format images. You can use the `elf2uf2-rs` package to convert\nthe Arm ELF file to a UF2 format image.\n\nFor boards with USB Device support like the Raspberry Pi Pico, we recommend you\nuse the UF2 process.\n\nThe RP2040 contains two Cortex-M0+ processors, which execute Thumb-2 encoded\nARMv6-M instructions. There are no operating-specific features in the binaries\nproduced - they are for 'bare-metal' systems. For compatibility with other Arm\ncode (e.g. as produced by GCC), Rust uses the *Arm Embedded-Application Binary\nInterface* standard or EABI. Therefore, any Rust code for the RP2040 should be\ncompiled with the target *`thumbv6m-none-eabi`*.\n\nMore details can be found in the [Project Template].\n\n### Linker flags\n\nBesides the correct target, which mainly defines the instruction set,\nit's also necessary to use a certain memory layout compatible with\nthe rp2040. To achieve that, rustc must be called with appropriate\nlinker flags. In the [Project Template], those flags are defined in\n[`.cargo/config.toml`](https://github.com/rp-rs/rp2040-project-template/blob/main/.cargo/config.toml).\nAnother necessary file is\n[`memory.x`](https://github.com/rp-rs/rp2040-project-template/blob/main/memory.x).\n\nMore detailed information on how the linker flags work can be found in\n[the cortex_m_rt docs](https://docs.rs/cortex-m-rt/latest/cortex_m_rt/).\n\nIn most cases, it should be sufficient to use the example files from the\n[Project Template].\n\n### Loading a UF2 over USB\n\n*Step 1* - Install [`elf2uf2-rs`](https://github.com/JoNil/elf2uf2-rs):\n\n```console\n$ cargo install elf2uf2-rs --locked\n```\n\n*Step 2* - Make sure your .cargo/config contains the following (it should by\ndefault if you are working in this repository):\n\n```toml\n[target.thumbv6m-none-eabi]\nrunner = \"elf2uf2-rs -d\"\n```\n\nThe `thumbv6m-none-eabi` target may be replaced by the all-Arm wildcard\n`'cfg(all(target_arch = \"arm\", target_os = \"none\"))'`.\n\n*Step 3* - Boot your RP2040 into \"USB Bootloader mode\", typically by rebooting\nwhilst holding some kind of \"Boot Select\" button. On Linux, you will also need\nto 'mount' the device, like you would a USB Thumb Drive.\n\n*Step 4* - Use `cargo run`, which will compile the code and started the\nspecified 'runner'. As the 'runner' is the elf2uf2-rs tool, it will build a UF2\nfile and copy it to your RP2040.\n\n```console\n$ cargo run --release --features \"critical-section-impl,rt,defmt\" --example pwm_blink\n```\n\n(The `pwm_blink` example doesn't need all these feature flags. They are listed here\nso you can use the same command for all examples.)\n\n### Loading with probe-rs\n[probe-rs](https://github.com/probe-rs/probe-rs) is a library and a\ncommand-line tool which can flash a wide variety of microcontrollers\nusing a wide variety of debug/JTAG probes. Unlike using, say, OpenOCD,\nprobe-rs can autodetect your debug probe, which can make it easier to use.\n\n*Step 1* - Install `probe-rs`:\n\n```console\n$ cargo install --locked probe-rs-tools\n```\n\nAlternatively, follow the installation instructions on https://probe.rs/.\n\n*Step 2* - Make sure your .cargo/config contains the following:\n\n```toml\n[target.thumbv6m-none-eabi]\nrunner = \"probe-rs run --chip RP2040\"\n```\n\n*Step 3* - Connect your USB JTAG/debug probe (such as a Raspberry Pi Pico\nrunning [this firmware](https://github.com/majbthrd/DapperMime)) to the SWD\nprogramming pins on your RP2040 board. Check the probe has been found by\nrunning:\n\n```console\n$ probe-rs list\nThe following debug probes were found:\n[0]: J-Link (J-Link) (VID: 1366, PID: 0101, Serial: 000099999999, JLink)\n```\n\nThere is a SEGGER J-Link connected in the example above - the message you see\nwill reflect the probe you have connected.\n\n*Step 4* - Use `cargo run`, which will compile the code and start the specified\n'runner'. As the 'runner' is the `probe-rs` tool, it will connect to the\nRP2040 via the first probe it finds, and install your firmware into the Flash\nconnected to the RP2040.\n\n```console\n$ cargo run --release --example pwm_blink\n```\n\n### Loading with picotool\n\nAs ELF files produced by compiling Rust code are completely compatible with ELF\nfiles produced by compiling C or C++ code, you can also use the Raspberry Pi\ntool [picotool](https://github.com/raspberrypi/picotool). The only thing to be\naware of is that picotool expects your ELF files to have a `.elf` extension, and\nby default Rust does not give the ELF files any extension. You can fix this by\nsimply renaming the file.\n\nAlso of note is that the special\n[pico-sdk](https://github.com/raspberrypi/pico-sdk) macros which hide\ninformation in the ELF file in a way that `picotool info` can read it out, are\nnot supported in Rust. An alternative is TBC.\n\n[Project Template]: https://github.com/rp-rs/rp2040-project-template\n\n\u003c!-- ROADMAP --\u003e\n## Roadmap\n\nNOTE These packages are under active development. As such, it is likely to\nremain volatile until a 1.0.0 release.\n\nSee the [open issues](https://github.com/rp-rs/rp-hal/issues) for a list of\nproposed features (and known issues).\n\n\u003c!-- CONTRIBUTING --\u003e\n## Contributing\n\nContributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are **greatly appreciated**.\n\nThe steps are:\n\n1. Fork the Project by clicking the 'Fork' button at the top of the page.\n2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)\n3. Make some changes to the code or documentation.\n4. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)\n5. Push to the Feature Branch (`git push origin feature/AmazingFeature`)\n6. Create a [New Pull Request](https://github.com/rp-rs/rp-hal/pulls)\n7. An admin will review the Pull Request and discuss any changes that may be required.\n8. Once everyone is happy, the Pull Request can be merged by an admin, and your work is part of our project!\n\n\u003c!-- CODE OF CONDUCT --\u003e\n## Code of Conduct\n\nContribution to this crate is organized under the terms of the [Rust Code of\nConduct][CoC], and the maintainer of this crate, the [rp-rs team], promises\nto intervene to uphold that code of conduct.\n\n[CoC]: CODE_OF_CONDUCT.md\n[rp-rs team]: https://github.com/orgs/rp-rs/people\n\n\u003c!-- LICENSE --\u003e\n## License\n\nThe contents of this repository are dual-licensed under the _MIT OR Apache 2.0_\nLicense. That means you can choose either the MIT license or the Apache 2.0\nlicense when you re-use this code. See [`LICENSE-MIT`](./LICENSE-MIT) or\n[`LICENSE-APACHE`](./LICENSE-APACHE) for more information on each specific\nlicense. Our Apache 2.0 notices can be found in [`NOTICE`](./NOTICE).\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in the work by you, as defined in the Apache-2.0 license, shall be\ndual licensed as above, without any additional terms or conditions.\n\n\u003c!-- CONTACT --\u003e\n## Contact\n\nRaise an issue: [https://github.com/rp-rs/rp-hal/issues](https://github.com/rp-rs/rp-hal/issues)\nChat to us on Matrix: [#rp-rs:matrix.org](https://matrix.to/#/#rp-rs:matrix.org)\n\n\u003c!-- ACKNOWLEDGEMENTS --\u003e\n## Acknowledgements\n\n* [Othneil Drew's README template](https://github.com/othneildrew)\n* [Rust Embedded Working Group](https://github.com/rust-embedded)\n* [Raspberry Pi](https://raspberrypi.org) and the [Pico SDK](https://github.com/raspberrypi/pico-sdk)\n","funding_links":[],"categories":["Rust","Board support crates"],"sub_categories":["Sparkfun"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frp-rs%2Frp-hal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frp-rs%2Frp-hal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frp-rs%2Frp-hal/lists"}