Provide real content at rust-embedded domains

[nastevens]

We currently have three domains available to the rust-embedded org, but all of them simply redirect to landing pages:

• www.rust-embedded.com
• www.rust-embedded.org
• www.areweembeddedyet.com

There are a lot of possibilities for content that could go on that site:

• List of useful crates for embedded dev (Survey: Crates you use for embedded development #12)
• List of frequently asked questions about embedded dev with Rust (Survey: Frequently Asked Questions #13)
• Getting started guides
• News feeds, similar to the various "This Week In..." publications
• Regular blogs or guest blogs
• Lots more!

I'm opening this issue to track the work that will go into those sites, and to put out a call for help. If you're interested in helping flesh out these sites, please let me know!

[cwoodall]

I would be interested in helping out on this front.

[japaric]

Next month, I can work on the getting started guides and the FAQ front.

Also, FYI, @jcsoo has an areweiotyet website, which is more focused on the "openwrt" ecosystem and embedded/IoT networking protocols, on the works. Let's coordinate with them to not duplicate content and to link to each other site where it makes sense. 😄

[japaric]

OK. I just realized that it's already November and I was supposed to do something about this issue :-).

Here's a sketch of what the areweembeddedyet website could contain:

---

Are we embedded yet?

You can hack stuff!

We are currently working on making things as straightforward as possible.

Supported architectures

• ARM Cortex-M is good

• AVR and MSP430 are being worked on.

Where do I start?

Beginner -> Discovery

Not a beginner -> cortex-m-template

More low level details -> Copper

And other up to date resources.

What works?

• C tooling: objdump, readelf, size, etc.

• Flashing and debugging with OpenOCD and GDB.

• Register manipulation. Zero cost and type safe.

• Dynamic memory allocation

• Exceptions and Interrupts

What's not quite there yet?

• IDE support

• An API for common peripherals

• Schedulers

• Memory safe and idiomatic interrupt handling

Crates

The crates.io ecosystem will provide all the functionality your application needs!

Categories:

• Development board specific crates. e.g. f3, teensy3

• CPU specific. e.g. cortex-m

• Memory maps. e.g. stm32f30x-memory-map

• Allocators. e.g. alloc-cortex-m, linked-list-allocator, alloc_buddy_simple

• Collections. e.g. fixedvec, intrusive-collections

• Tooling. svd2rust, xargo, itmdump, etc.

• ???. m, rlibc, compiler-builtins

---

Note that all this is microcontroller specific. I'm not quite sure how to incorporate the other sub-ecosystems here. We could have one page per sub-ecosystem or just have everything on a single page. But the latter will probably be harder to follow.

I'll try to expand and turn this into a markdown file and post it here. No ETA though.

[japaric]

I have finally come back to this and I have made a draft for the possible
contents of the areweembeddedyet.com site.

I'd like to get feedback on this draft. In particular:

• Is all the information you'd expect to find in there? Or is anything
  missing?

• In there anything that should be highlighted? Maybe some embedded
  applications, some GitHub projects, etc.

• What do you think about the organization of the contents? Right now
  information all the way from microcontrollers to SBC is in a single page.
  Should we have a more clearer separation of these sub-ecosystems as in one
  page for microcontrollers, one page for ARM Linux, etc.?

Note that this meant as a starting point. For instance the crate section could
be expanded in number and in per crate content (e.g. add more details about the
crate, pros, cons). My idea is that we should set up a repo with some initial
content and then progressively add more content and/or update the content based
on users' feedback.

Finally some bikeshedding: how should we render this content?

I vote keeping things simple and just using some existing static site generator
from Markdown files like hugo along with some existing theme. Unless someone
with front-end chops wants to stand up and make some custom site.

cc @vitiral

[digikata]

I'm not sure its fully gelled in my mind yet, but while the set of topics in the page is very interesting and relevant, I feel like it's a little difficult to load the page, hop to the relevant topic, and start working given some bit of hardware - at least without reading the whole page. Personally, I don't mind doing this as I'm interested in the whole state of Rust embedded-wise but a lot of programmers might want to drop in and get going a little more directly.

I would love to see a little more organization around "support package checklist" conventions. Mostly to be guide a reader in where to read if a specific bit of hardware is supported, but also what needs to be done if some hardware isn't listed. A little more specific thoughts are below:

1. Split info into generalized embedded "support package" levels or topics such as arch (Arm Cortex Mx), Processors (PSP: STM32xx or K2x..), Boards (BSP: teensy, etc), Unified tools (UTSP: gdb, jtag access etc), general embedded support crates characteristics (no_std, or no dynamic allocation required algos, etc).

2. Be able to use the category levels to describe some stages of a functional toolchain so we can describe status of usability along some string of Arch/PSP/BSP/tool groups.

3. Use the checklist to provide a roadmap for people to know where there are capability gaps so people can look and say "oh I just need to implement x & y to get BSP level support for this board because the PSP/tooling support is already good...". And, oh, I can look at tooling support for see std-out to serial peripheral mapping for this Processor to port it to a new processor or different peripheral output...

[japaric]

I feel like it's a little difficult to load the page, hop to the relevant topic, and start working given some bit of hardware

That may be more a problem of presentation rather than of content. This is what the page looks like with a table of contents.

---

Your three ideas sounds to good to me but I'm a bit afraid about maintenance cost of doing something like that down the road i.e. once more and more crates start to pop out.

Also it sounds like crates.io itself should be answering some of those questions: "general embedded support crates characteristics (no_std, or no dynamic allocation required algos, etc)" - this sounds exactly like crates.io categories.

3 sounds like something board support crate author / maintainer can answer better which sounds like quite some coordination work to do it right.

[vitiral]

Hi@japaric I LOVE the layout of your gist. The only thing that I think is missing is a "need to work on list".

I am the developer of artifact. It's a design documentation tool made for developers. One of the things I'd like to work on is "designing a microcontroller software suite" of libraries and tools. This will involve coming up with requirements (use cases) and specifications (the library APIs and abilities) as well as test architectures. I would like to start this and then get community involvement.

The artifact tool can define all of these as text files and render them as static html for viewing. The idea is to develop this ecosystem from a very high level so that new contributors can have a rough outline of what is needed by the community, as well as give anyone a detailed view of ecosystem completness. Library developers themselves (not us) will of course eventually be the ones to define the final API and implementation.

We can then use those requirements /specs to say how "complete" the ecosystem is in arewewebyet

[japaric]

I went through all the board support crates I know of (apologies if I missed your crate), collected information about what their HALs support (i.e. what peripherals do they support in their APIs) and sorted the information as per @digikata comment. The result was this.

This information could be better displayed as (comparison?) tables + a foldable tree or a table of contents in the sidebar to help navigation. I believe that a progress bar that indicates "this chip has A, B, C and D peripherals but its HAL only exposes an API for A and D" would also help. I sorted the board support crates per vendor rather than per microcontroller family as they latter seems to fine grained right now: each board support crate we have right now targets a different microcontroller family.

@vitiral that sounds fine to me but the community has given very little feedback (see #22) about what high level libraries they need / want. OTOH I always get questions about whether chip A or B is "supported by Rust".

[japaric]

re: previous comment. I think we should highlight what applications have been build with this or that board / device. People are always looking for example projects to use as reference.

[vi]

Shall there be red/yellow/green "needs a lot of work" / "getting there" / "support is awesome" icons like in arewewebyet.com?

They provide general feeling of readiness/nonreadiness when one glances over the page just to answer "Is Rust ready for embedded or not yet?" without wanting to know further details.

[afonso360]

Hi, i've been working a little on this.

I made a Jkelly page out of @japaric's gist. I thought about making a custom page, but using Jkelly other people can update it by using Markdown and YAML files.

A demo is available on my github.io. A lot of it is still broken, but its there. Let me know which other sections you guys would like me to add.

Also, with Jkelly we can do This Week in Embedded Rust just by dropping a md file in a folder

[jamesmunns]

I believe that we now have https://docs.rust-embedded.org, which meets the goals of this issue. Therefore I would propose that we close it.

Marking this for a cleanup sweep. If we would like this to stay open, please provide an update to what this issue should be focused on.

[jamesmunns]

I am closing this issue, please feel free to open another issue if you would like this discussed further.