The Embedded Rust Book #56
Comments
|
Oh fantastic! I've been thinking about how to document an embedded pet project of mine and it will be super useful to have an up to date book to point to for how to get started with microcontrollers and Rust. Regarding the audience, I could see many people coming from a traditional embedded background being interested, without them having much prior Rust experience. |
|
If you mean to take an audience survey, I'm in the "confident with µCs, new to Rust" quadrant. I think a significant "market" for embedded Rust is people who like Arduino but have the hump with C++. I think your points 1, 2 are a fantastic start, and I would consume them voraciously. One of the problems I've faced (and I've seen others mention) is that there are a number of "blink an LED with Rust!" blog posts/tutorials out there, but they all target different µCs, take different (from-scratch) approaches, and were written up to years apart, and therefore start with a different set of variously outdated assumptions. A canonical "this is how you get a functional embedded Rust environment" reference would be 💯. Of particular note for section 2 ii) is how to install the correct dependencies on macOS, Windows and Linux. On macOS particularly, anything trickier than Regarding section 3, I would first focus on a reference section for the existing, supported chip, feature and board support crates (or if this already exists, links to them). A how-to for writing new ones is a second-order consideration, I guess? Under "Concerns" point 2, is it really necessary to write a guide for people who are not going to use Thanks for leading this up! I'm watching with interest and keen to help out where I can. |
You are mentioning two points that came to my mind instantly.
For 1.1, I can see the advantage that a reader stays interested due to the one big project on which he can work. Here, focus could be on which language constructs of Rust fit for driving different kinds of peripherals and components. For 1.2, focus could be more on abstraction and frameworks like embedded-hal, and how to stay generic on top of different targets. Maybe also a hybrid approach is possible. Covering the part of booting a very basic system on multiple targets, but move on with more sophisticated content only with one target, e.g. one that is easily accessible like Raspberry Pi.
|
If it's all in Git it can be tagged periodically, with the current-at-the-time versions of Rust/Cargo/etc noted. Should be pretty simple to default the user to the latest version but allow them to select a previous tag relevant to their environment. |
|
Bounced here from Reddit. To quote a comment from there:
Speaking as someone who is the latter, I think what this ecosystem really needs right now are contributions from the former: experienced hardware developers who want to try Rust. In practical terms, that probably means lingering at the lower levels, and teaching good patterns for safe abstractions over As a side note, you might want to regularly check in with the portability initiative, because it seems like what they're doing is relevant to building on embedded platforms. |
|
I would love some content for "new to µCs, new to Rust" quadrant 😬 |
|
I think initially targeting the new to rust new to µC's is probably the best option. It includes everyone and readers can skip over paragraphs explaining concepts they are familiar with. |
|
@IGBC I agree, especially since a developed Rust ecosystem is far easier to use than a generic C/C++ ecosystem and specialised/vendor ecosystems may look great and easy at first glance but quite restrictive both in terms of moving to a different vendor and getting things one once you (inevitably) run into the restrictions of the particular choice. Establishing Rust as the choice for embedded programming would mean plenty of new Rust users, I even see potential for it to become something like a second "Arduino"... |
|
@jamesmunns As this moves forward, please let me know if you want to do anything with the rust-embedded.com, rust-embedded.org, and/or areweembeddedyet.com domains. I parked these a while ago and would love to see them actually get use. If someone wants to share responsibility for the DNS records themselves I'd be game as well - it'd be good to reduce the bus-factor. |
|
@nastevens that sounds great! I'll keep it in mind. Feel free to shoot me an email regarding the DNS records (its in my profile) |
|
As far as targets audiences go, I think we could take a look at how Rust itself has moved. There is The RPL book (intro/overview of the language), Rustonomicon (advanced/easier to shoot yourself in the foot), and soon to be the Rust Compiler Book (advanced). I'm not suggesting we start out with the idea to write 3 books, but that we think of it in the same fashion. We've already got Discovery which is a pretty darn good intro and with a few tweaks could be a perfect overview of the Rust Embedded Story (RES to the RPL). The HAL/driver initiative has already started off with some fantastic blog posts that could be compiled into a Rustonomicon, Rust By Example style, closer to the metal, "if you already know what you're doing", book. The compiler book part could be the the other side of things, writing an LLVM backend, When you break it apart like that it sounds like a lot more work, but I think it could make things a little more simple in the the near and far term (especially if we reuse some of resources already out there). Instead of trying to figure out how to write one chapter that can address those new to Rust and those new to embedded, you can focus on one, knowing that the other will be addressed in a separate section. I also believe, just from this thread alone where we've got enough people from both sides, that more people can contribute this way. |
For RTOS, I recommend TockOS. |
|
Sorry for taking a while here, @jamesmunns <3
So, I basically agree with what has been said above: the big concerns are "knows Rust vs not" and "knows embedded vs not". I think the two important audience are "knows Rust but not embedded" and "knows embedded but not Rust." What I would recommend is that you make your primary audience "knows embedded and Rust", with some small caveats. I think up-front you should talk about your audience. For example, in the book we say:
I think you should state up front that this book isn't for teaching Rust, but references material along the way. You should suggest that your readers read chapter 2, 3, and 4 of the Rust book as a pre-requisite, and go from there. 2 as a quick overview, 3 for common syntax, and 4 for the core of ownership. From there, when you come across a more advanced Rust concept, you should do a small aside giving a few sentence overview and cross-link to the relevant part of the book. |
|
I would love to help editing and proof-reading or trying to follow examples, if needed. I have some prior experience (AOSA books) |
|
STM32 development is primarily my bread-and-butter, but I've followed the Rust project with interest for a while. I'm excited about this project. One section that might be of interest is understanding how Rust fits in vs. Ada/SPARK and Frama-C, understanding the differences between provable code and embedded Rust, etc. |
|
(adding to the 2018 edition milestone as per last week's meeting) |
|
For anyone watching this issue, I have an initial skeleton PR, #74, of what I see as the initial version of the embedded rust book. Feedback is welcome, and once that is merged, contributions are very welcome! |
|
@jamesmunns I would like to help as I have to go through this process anyway, one question, how does this project differ from the embedonomicon? Also, as a newbie coming in who doesn't have the particular board the book is based around, it would be good if the book gave indications of the supporting rust libs which make the f3 attractive, and which might be missing for other boards. |
|
A reminder from the last WG meeting: To get more feedback on the UI of cargo-binutils (cf. #51) we'll start using cargo-binutils, instead of GNU binutils, in the embedded Rust book. I'll also update the Discovery book to do the same.
The three documents will contain this information and cross reference each other. |
|
Great summary, thank you!
…On Tue, Jul 3, 2018, 6:07 PM Jorge Aparicio ***@***.***> wrote:
A reminder from the last WG meeting:
To get more feedback on the UI of cargo-binutils (cf. #51
<#51>) we'll start
using cargo-binutils, instead of GNU binutils, in the embedded Rust book.
I'll also update the Discovery book to do the same.
------------------------------
@AJAnderson <https://github.com/AJAnderson>
I would like to help as I have to go through this process anyway, one
question, how does this project differ from the embedonomicon?
-
The embedded Rust book is for people that want to learn *embedded Rust*
but only know (some) embedded (C / Python / lua / node / etc.) and (some)
Rust.
-
The Discovery book is for people that know some Rust but know nothing
about embedded development and want to learn embedded development.
-
The embedonomicon documents how to build a no-std program for an
embedded target from scratch. This is useful if you intend to bootstrap
Rust support for a currently unsupported architecture (e.g. RISCV). You can
also read it if want to know how cortex-m-rt works and why it looks the way
it looks.
The three documents will contain this information and cross reference each
other.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#56 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AEu6EZMCr3zMzZGGocSpLwwFD2CDpT5sks5uCwoXgaJpZM4SW6cn>
.
|
|
Hi, I had a look at the proposed content in "Running and Debugging", do you want help to add for the Black Magic Probe debugger, to have some diversity rather than just OpenOCD? Link to Git and Wiki: https://github.com/blacksphere/blackmagic Tell me if you want some input there, I can help write that part if you'd like. |
|
@korken89 The BMP is by far not as versatile as OpenOCD and it exclusively works with GDB, not lldb (and possibly never will). If we add that content there probably should be a big caveat in there so people don't treat such content as recommendation to go out and buy one only to figure out that it doesn't work for their setup. |
|
Perhaps an "Other Hardware" section?
…On Wed, Jul 4, 2018 at 7:11 PM, Daniel Egger ***@***.***> wrote:
@korken89 <https://github.com/korken89> The BMP is by far not as
versatile as OpenOCD and it exclusively works with GDB, not lldb (and
possibly never will). If we add that content there probably should be a big
caveat in there so people don't treat such content as recommendation to go
out and buy one only to figure out that it doesn't work for their setup.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#56 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AEu6EW9CnQfGgJdYa1vzDg39nkdAoEy_ks5uDGq4gaJpZM4SW6cn>
.
|
|
@therealprof I would argue the it might not be as versatile in some corner cases (MCU support) but much less hassle than If @AJAnderson I think this would be fine as well, though I think that it still should be given a proper write up. |
I disagree but of course if it works for you that's great.
I agree. Just saying that if it is brought up there should be a disclaimer. There's a very good reason pretty much any other project is actively pushing OpenOCD or PyOCD support.
Err, the GDB protocol is notoriously under documented so implementations (including lldb) will differ. The BMP maintainer stated several times that the authoritative implementation of the gdb server protocol is GDB and he's not interested in making an effort to improve compatibility with anything else. So that is that. |
We can't agree on everything :)
Then I would say we are on the same page, just as
Indeed, and this is true. I just want to point out that parts of industry today is built on this foundation, and the more people we can pull to Rust the better. And to pull people the path has to have low resistance as most people want it to "just work" from what they are used to. But I think we have discussed this enough here, I don't want to start another "debugger vs debugger" :) If there is interest to add a part on different debuggers, wherever it might be placed in the end, I can help write that part. |
|
I'm in favour of documenting a few different debuggers, so people can use whatever they have on hand / are familiar with / is on their dev board / works. |
|
@ryankurte We need to be careful about mixing things here. Are we talking about software, protocols and/or hardware? BMP is a bit of an oddball here because it is hardware and software in one and provides a gdb-server protocol specific for GDB use; it's the only hardware I know which can not be used with OpenOCD, which is purely software speaking a number of protocols with different hardware. JLink can either refer to hardware and or the protocol but a firmware talking the JLink protocol can not only be flashed to JLink hardware but is also supported on various debuggers from vendors like STM and NXP. Similarly STLink is both hardware and protocol. And then there're also open (and proprietary) solutions around the CMSIS-DAP/DAPlink protocol standard and of course completely proprietary solutions... 😉 |
|
Second the importance of maintaining a clear distinction for newbies like
myself, also outlining (as you have Daniel) where the various bits and
pieces can interop with eachother.
…On Wed, Jul 4, 2018 at 9:53 PM, Daniel Egger ***@***.***> wrote:
@ryankurte <https://github.com/ryankurte> We need to be careful about
mixing things here. Are we talking about software, protocols and/or
hardware? BMP is a bit of an oddball here because it is hardware and
software in one and provides a gdb-server protocol specific for GDB use;
it's the only hardware I know which can not be used with OpenOCD, which is
purely software speaking a number of protocols with different hardware.
JLink can either refer to hardware and or the protocol but a firmware
talking the JLink protocol can not only be flashed to JLink hardware but is
also supported on various debuggers from vendors like STM and NXP.
Similarly STLink is both hardware and protocol. And then there're also open
(and proprietary) solutions around the CMSIS-DAP/DAPlink protocol standard
and of course completely proprietary solutions... 😉
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#56 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AEu6EYWmChW0vg72mitEqqD9Odf1JiZNks5uDJCzgaJpZM4SW6cn>
.
|
|
@therealprof fair point, for the purposes of the documentation I mean "how do I use this physical debugger in front of me to make the lights flash", whether that be JLink hw/sw, STLink hw/sw, BMP+GDB or any hw+OpenOCD, and GDB or LLDB as appropriate. I have never successfully got OpenOCD working, so I don't know how much it /could/ replace, but ime there are justifications for each of em. |
|
@ryankurte OpenOCD is a jack of all trades, unfortunately it is also not quite user friendly and might required some deep technical understanding, especially if you're looking for an exotic configuration or combination of interface and hardware. Many projects provide useful configuration and helper tools to simplify its use a lot. It would be great to have something like that in the Rust world, too. If you're curious how to use OpenOCD, you could check out my https://github.com/therealprof/microbit, https://github.com/therealprof/nucleo-f042k6 or even my (kind of orphaned) https://github.com/therealprof/atsamd20e15a repositories which all provide working configuration and a helper script to flash binaries via OpenOCD. |
|
@ryankurte @therealprof Are you aware of Bobbin-cli? It brings the awesomeness of cargo to programming/debugging microcontrollers. It's my clear first choice when doing embedded development in Rust. It provides a consistent interface similar to cargo for the most common debugging tool. I've used it with STLink (insert STLink is superior to all other debuggers rant), and it also supports tools with OpenOCD back-ends plus some other common debuggers. Perhaps you have something to add @jcsoo ? I think recommending this tool makes way more sense than documenting how to use a handful different debuggers with rust. |
|
@kjetilkjeka I do know bobbin-cli and agree it's a great tool. To me it certainly makes sense to focus on documenting its use, however it does not completely address the points I raised, since it cannot handle every situation automagically. Since I revisited it just now after a few months of abstinence I think we can even use it as a foundation to develop and document best practices to follow so people don't have to reinvent the wheel all the time when it comes to flashing and debugging. |
|
@therealprof thanks for the resources, tbqh I have a JLink workflow that works and is reproducible across different OSs and I'd rather worry about making things than shaving more yaks in debugger setups. @kjetilkjeka bobbin-cli looks neat, maybe that's a good default. I agree with @therealprof that it doesn't however handle all situations. Also, as not open-source as it is, $job almost exclusively use JLink because they're the only devices that work reliably with the cores we use. Shall we create another issue for working on the flashing/debugging components? |
|
@ryankurte Sounds like a plan. |
|
@ryankurte / @therealprof Please include me in this issue, I am very much interested in looking to unify and simplify the flashing/debugging step for users. |
|
This is superseded by the issues with the "book" label so I'm going to close this. |
653: Rename to embedded-alloc r=eldruin a=Jzow CC [#56](rust-embedded/embedded-alloc#56). Co-authored-by: James Zow <jameszow@163.com>
This is a tracking issue for an official guide to using rustlang on microcontroller targets.
For now, these are the major steps:
book/folder to this repository (until a better home is found)Audience
I think the first step is to decide the audience of this book. I think the major factors are:
This gives us four possible target audiences. I will leave it up to discussion which of these four audiences we would like to initially target. We may extend the Book to cover all four eventually, but we may try and target some subset to get something going at first.
Content
Once we have decided who the (initial) audience is, it will be necessary to determine the content of the book.
Initially, I would suggest the following organization:
3from start to finish, similar to the Guessing Game in the Rust BookConcerns
We must decide how existing documentation, guides, and tooling falls into the following categories:
#[no_std]elf/hex that can run on a given target. We should expect these items to be officially supported by the Rust organization properembedded-hal, etc. People should not expect these items to be officially supported or required. A parallel here would be nursery level crates like Futures, Tokio, Error Chain, etc.I say these items are a concern, because we must be careful to avoid "blessing" parts of the ecosystem that are not officially maintained, as it will cause us to update our documentation if these components fall out of maintenance or fashion (or expose our users to a "broken" experience).
Additionally, we must discuss what embedded targets we will use for these guides. Chips from different architectures and manufacturers have an extremely wide variance in how they act, and if the guide is only written for an STM32, developers may struggle with an nRF5x or AVR based chip. I think initially, we should at least cover the officially supported thumb* architectures, and if the MSP, AVR and/or RISC-V branches are merged upstream, we should expect to update the guide to cover them around the same time as they become officially supported by Rustlang (We could also cover them beforehand, but I would say we MUST cover them when officially supported).
Reuse of existing material
There are a lot of existing blog posts, projects, etc. that can be used. Care must be taken to make sure anything we integrate into the official guide must be up to date and correct. Additionally it may require editing to fit the "style" of the book, to make sure developers have a consistent experience.
Maintainers
We will need to have maintainers for the book. (@jamesmunns) is willing to take this up initially, but will absolutely need help. Additionally, we should probably reach out to the Docs working group for guidance here (CC @carols10cents @steveklabnik).
The text was updated successfully, but these errors were encountered: