diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f8a695b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,48 @@ +# Contribution Guidelines + +Please note that this project is released with a [Contributor Code of Conduct](Code-of-Conduct.md). By participating in this project you agree to abide by its terms. + +# The pull request should have a useful title. Pull requests with `Update readme.md` as title will be closed right away because I'm so tired of nobody reading this document. Please carefully read everything in `Adding to this list`. + +## Table of Contents + +- [Adding to this list](#adding-to-this-list) +- [Creating your own awesome list](#creating-your-own-awesome-list) +- [Adding something to an awesome list](#adding-something-to-an-awesome-list) +- [Updating your Pull Request](#updating-your-pull-request) + +## Adding to this list + +Please ensure your pull request adheres to the following guidelines: + +- Search previous suggestions before making a new one, as yours may be a duplicate. +- Make sure the item is useful before submitting. The awesome lists aim to list actually awesome projects, not collect the names of all projects in existence. +- Make an individual pull request for each suggestion. +- Use [title-casing](http://titlecapitalization.com) (AP style). +- Use the following format: `[Item Name](link) Description text` +- Link additions should be added to the bottom of the relevant alphabetical category. +- Check your spelling and grammar. +- Make sure your text editor is set to remove trailing whitespace. +- The pull request and commit should have a useful title. When you add a project - at least use `Add projectX` as title. See [this article](https://chris.beams.io/posts/git-commit/) on guidelines to good commit messages. +- The body of your commit message should contain a link to the repository. + +Thank you for your suggestions! + +## Adding something to an awesome list + +If you have something awesome to contribute to an awesome list, this is how you do it. + +You'll need a [GitHub account](https://github.com/join)! + +1. Access the awesome list's GitHub page. For example: https://github.com/berkus/awesome-embedded-rust +2. Click on the `readme.md` file: ![Step 2 Click on Readme.md](https://cloud.githubusercontent.com/assets/170270/9402920/53a7e3ea-480c-11e5-9d81-aecf64be55eb.png) +3. Now click on the edit icon. ![Step 3 - Click on Edit](https://cloud.githubusercontent.com/assets/170270/9402927/6506af22-480c-11e5-8c18-7ea823530099.png) +4. You can start editing the text of the file in the in-browser editor. Make sure you follow guidelines above. You can use [GitHub Flavored Markdown](https://help.github.com/articles/github-flavored-markdown/). ![Step 4 - Edit the file](https://cloud.githubusercontent.com/assets/170270/9402932/7301c3a0-480c-11e5-81f5-7e343b71674f.png) +5. Say why you're proposing the changes, and then click on "Propose file change". ![Step 5 - Propose Changes](https://cloud.githubusercontent.com/assets/170270/9402937/7dd0652a-480c-11e5-9138-bd14244593d5.png) +6. Submit the [pull request](https://help.github.com/articles/using-pull-requests/)! + +## Updating your Pull Request + +Sometimes, a maintainer of an awesome list will ask you to edit your Pull Request before it is included. This is normally due to spelling errors or because your PR didn't match the awesome-* list guidelines. + +[Here](https://github.com/RichardLitt/knowledge/blob/master/github/amending-a-commit-guide.md) is a write up on how to change a Pull Request, and the different ways you can do that. diff --git a/Code-of-Conduct.md b/Code-of-Conduct.md new file mode 100644 index 0000000..d954189 --- /dev/null +++ b/Code-of-Conduct.md @@ -0,0 +1,74 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at berkus@gmail.com. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ \ No newline at end of file diff --git a/README.md b/README.md index e36bcfc..2ecee6a 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,22 @@ -# `awesome-embedded-rust` +# Embedded Rust -> A curated list of crates useful for embedded development. +[![Awesome](https://awesome.re/badge.svg)](https://awesome.re) + +This is a curated list of resources related to embedded and low-level programming in the programming language Rust, including a list of useful crates. + +[](http://www.rust-embedded.org) ## Table of contents +* [Community](#community) +* [Books, blogs and training materials](#books-blogs-and-training-materials) +* [Tools](#tools) * [Device crates](#device-crates) + * [ARM](#arm) * [Nordic](#nordic) * [NXP](#nxp) * [STMicroelectronics](#stmicroelectronics) + * [MSP430](#msp430) * [HAL implementation crates](#hal-implementation-crates) * [OS](#os) * [Nordic](#nordic-1) @@ -21,8 +30,42 @@ * [Driver crates](#driver-crates) * [WIP](#wip) * [no-std crates](#no-std-crates) +* [Rust forks](#rust-forks) + - [AVR](#avr) * [License](#license) +## Community + +In 2018 Mozilla asked for creation of an embedded workgroup to help drive adoption in the Rust ecosystem. + +- [Embedded WG](https://github.com/rust-lang-nursery/embedded-wg/), including newsletters with progress updates. + +- [embedded.rs](https://t.me/embedded_rs) Telegram chat about Rust for microcontrollers in Russian language. + +## Books, blogs and training materials + +- [Discovery](https://japaric.github.io/discovery/) by @japaric — this book is an introductory course on microcontroller-based embedded systems that uses Rust as the teaching language. +- [Exploring Rust on Teensy](https://branan.github.io/teensy/) by @branan — Beginner set of articles on getting into embedded dev in Rust. +- [Pragmatic Bare Metal Rust](http://www.hashmismatch.net/pragmatic-bare-metal-rust/) A starter article about starting Rust development on STM32 microcontrollers (cubeMX + FFI). +- [Using Rust in an Embedded Project: A Simple Example](https://spin.atomicobject.com/2016/07/08/rust-embedded-project-example/#.V3-os-6qlZw.hackernews) Article and some links on setting up Rust cross-compiling. +- [Robigalia](https://robigalia.org) IoT operating system in Rust running on secure seL4 microkernel. +- [Tock](https://www.tockos.org) An embedded operating system designed for running multiple concurrent, mutually distrustful applications on low-memory and low-power microcontrollers +- [intermezzOS](http://intermezzos.github.io) A small teaching operating system in Rust. A book with some explanations is also included. +- [Raspberry Pi Bare Metal Programming with Rust](https://medium.com/@thiagopnts/raspberry-pi-bare-metal-programming-with-rust-a6f145e84024) A starter article on OSdev with Rust on RPi (cross-compiler setup and a very basic LED-blinking kernel). +- [Fearless concurrency](http://blog.japaric.io/fearless-concurrency/) by @japaric — How to easily develop Rust programs for pretty much any ARM Cortex-M microcontroller with memory-safe concurrency. +- [RTFM v2](http://blog.japaric.io/rtfm-v2/) Real-Time For the Masses — Cortex-M programming framework for building concurrent applications. +- [cortex-m rtfm](https://github.com/japaric/cortex-m-rtfm) RTFM framework for ARM Cortex-M microcontrollers +- [msp430 rtfm](https://github.com/japaric/msp430-rtfm) RTFM framework for MSP430 MCUs +- [FreeRTOS.rs](https://github.com/hashmismatch/freertos.rs) Rust interface for the FreeRTOS API + +## Tools + +- [xargo](https://github.com/japaric/xargo) Rust package manager with support for non-default std libraries — build rust runtime for your own embedded system. +- [svd2rust](https://github.com/japaric/svd2rust) Generate Rust structs with register mappings from SVD files. +- [μtest](https://github.com/japaric/utest) unit testing for microcontrollers and other no-std systems. +- [bindgen](https://crates.io/crates/bindgen) Automatically generates Rust FFI bindings to C and C++ libraries. +- [cortex-m semihosting](https://github.com/japaric/cortex-m-semihosting) Semihosting for ARM Cortex-M processors + ## Device crates Register definition for microcontroller families. Usually generated using [`svd2rust`]. @@ -34,9 +77,14 @@ Register definition for microcontroller families. Usually generated using [`svd2 [svd2rust-kw]: https://crates.io/keywords/svd2rust +### ARM + +- [`cortex-m`](https://github.com/japaric/cortex-m) Low level access to Cortex-M processors + ### Nordic -- [`nrf51`](https://crates.io/crates/nrf51) +- [`nrf51`](https://crates.io/crates/nrf51) Peripheral access API for nRF51 microcontrollers (generated using svd2rust) +- [`nrf51822` playground](https://github.com/japaric/nrf51822) A crate to play with the nrf51822 module ### NXP @@ -46,10 +94,16 @@ Register definition for microcontroller families. Usually generated using [`svd2 ### STMicroelectronics - [`stm32f042`](https://crates.io/crates/stm32f042) -- [`stm32f103xx`](https://crates.io/crates/stm32f103xx) -- [`stm32f30x`](https://crates.io/crates/stm32f30x) +- [`stm32f103xx`](https://crates.io/crates/stm32f103xx) Peripheral access API for STM32F103XX microcontrollers (generated using svd2rust) +- [`stm32f100xx`](https://github.com/japaric/stm32f100xx) Peripheral access API for STM32F100XX microcontrollers (generated using svd2rust) +- [`stm32f30x`](https://crates.io/crates/stm32f30x) Peripheral access API for STM32F30X microcontrollers (generated using svd2rust) - [`stm32l151`](https://crates.io/crates/stm32l151) +### MSP430 +- [`msp430g2553`](https://github.com/japaric/msp430g2553) Peripheral access API for MSP430G2553 microcontrollers (generated using svd2rust) +- [rust on msp](https://github.com/japaric/rust_on_msp) Simple blinking LED example that runs on MSP430. +- [msp430 quickstart](https://github.com/japaric/msp430-quickstart) some examples for msp430 + ## HAL implementation crates Implementations of [`embedded-hal`] for microcontroller families and systems running some OS. @@ -130,7 +184,8 @@ Crates tailored for specific development boards. - [`nucleo-f042k6`](https://github.com/therealprof/nucleo-f042k6.git) - [Nucleo-F042K6] - [`nucleo-f103rb`](https://github.com/therealprof/nucleo-f103rb.git) - [Nucleo-F103RB] -- [`f3`](https://crates.io/crates/f3) - [STM32F3DISCOVERY] +- [`f3`](https://crates.io/crates/f3) Board Support Crate for the [STM32F3DISCOVERY] +- [`blue-pill`](https://github.com/japaric/blue-pill) Board Support Crate for [Blue Pill]. ## Driver crates @@ -245,6 +300,11 @@ Work in progress drivers. Help the authors make these crates awesome! [no-std-category]: https://crates.io/categories/no-std [#2]: https://github.com/rust-embedded/awesome-embedded-rust/issues/2 +## Rust forks + +### AVR +- [AVR Rust](https://github.com/avr-rust/rust) Fork of Rust with AVR support. + ## License This list is licensed under diff --git a/rust-embedded-logo-256x256.png b/rust-embedded-logo-256x256.png new file mode 100644 index 0000000..63506dd Binary files /dev/null and b/rust-embedded-logo-256x256.png differ