Initial Embedded Book Skeleton

[jamesmunns]

Hey, here is an initial check in for #56. No CI yet, no rendered copy, no content.
Just some markdown pages with my initial thoughts on them :)

[jamesmunns]

CC: @dvc94ch, @dylanmckay, @hannobraun, @japaric, @jcsoo, @pftbest, @thejpster

I would really appreciate any organizational comments, or anything you think should be a "must have" in the initial version of the book.

[jamesmunns]

Also @japaric I made the path embedded-rust-book so that the embeddednomicon can coexist in this repo.

[jamesmunns]

Note to self: Find somewhere to introduce the concept of #![no_std]. Probably good to introduce early (maybe in the Introduction section, or Blinking your first LED > Project Setup, and then follow up later, when discussing how to integrate more crates in the Your Application Code section, mostly to cover how to find no_std crates, and whether they are acceptable for use on embedded.

[cldershem]

I believe this should be port 3000 by default.

[thejpster]

I'd prefer CC-BY-SA, but I note TRPL book is dual MIT/Apache-2 like rustc itself. Maybe the latter makes more sense if the book contains lots of example code people might wish to re-use.

[andre-richter]

+1 for MIT/Apache. Using Code from CC attribution licenses is awkward and tedious because you gave to indicate changes as well.

Same problem with the embedonomicon. I'm planing to use some stuff from the code samples, and figuring out a correct attribution is not that easy.

[jamesmunns]

@thejpster that is exactly what I found.

@andre-richter I totally agree for code snippets, though I remember some discussion about using MIT or similar

@japaric @steveklabnik any thoughts on these options/possible combos?

[andre-richter]

CC for book-text and MIT/Apache for code snippets might be a good combo. If that is legally possbile?

[thejpster]

Step 0 is surely getting some hardware? Should we make some recomendations for people who want the lowest hassle way of following along? Is QEMU sufficient (Phil Opperman does this with his OS blog for x86 with great results), or will people need actual hardware?

[thejpster]

Oh, these files aren't in the same order as the ToC. I'll copy this to the Hardware section ;)

[therealprof]

Hardware options are rather cheap. I don't think using Qemu instead would be worth the hassle. It also doesn't yield the same level of satisfaction.

[jamesmunns]

@thejpster teaching with QEMU is an interesting idea! Right now the plan is to focus on one board (probably the Discovery used by japaric), though it would be nice to have support for more devices, including QEMU.

@therealprof I agree the primary focus should be on actual hardware, though QEMU may be a secondary goal.

[therealprof]

My suggestion would be cheap and accessible hardware, like Bluepill, Nucleo and/or Micro:bit. For all of these board support crates are available and I'd be happy to provide examples, also highlighting the slight differences in HAL use. The discovery boards are okay but quite a bit more expensive, a tad harder to obtain and less flexible for own experiments.

[therealprof]

Would be great if we could get this up and running so this is open to content contributions.

[jamesmunns]

Hey all, there are a couple smaller comments, but nothing big, and I had an in-person chat with @japaric who gave a general thumbs up. If there are no huge comments, I will plan on merging this about 24 hours from now.

EDIT: 24 hours from "now" is 2018-04-01 12:20:00+00:00

Largest issues presented so far:

1. License
2. What board(s) to use

Regarding License, I will plan on making the book CC-BY-SA for the book text, and dual MIT/Apache for the text. I think this covers our wishes of a) wanting people to use the code we present, and b) not wanting people to republish our changes to the book without making their changes similarly open. Some day I hope this book could be published similarly to the Rust PL book, and I believe this is an acceptable license for this. The risk for getting our choices of licenses wrong now would be requiring confirmation from all contributors to re-license in the future, or rewrite their contributions.

Regarding boards: I think we should focus on one board. The board should have everything needed for the book, so I would say the uC, a built in debugger that works with OpenOCD or free to use tools like JLinkGDB, built in human-interactable stuff like buttons and LEDs, and ideally some kind of external component using I2C, UART, or SPI. I would also like the board to be <= $15-20, to prevent the cost of entry from being too high.

I would prefer NOT requiring people to wire things together, at least initially, so I would disqualify the Blue Pill board. The micro bit is interesting, because it does use the nrf51, though the KL26Z is used only as a programmer, which isn't a blocker, but wouldn't let the user program both chips without a discrete debugger. Also there is not a good "pure rust" bluetooth story at the moment (though some work has been done with Tock-OS).

@therealprof do you have any nucleo boards you would suggest that is at a lower price point than the ~$15 of the micro bit or discoveryF3 board?

[therealprof]

There're plenty of Nucleos around, among the best supported are the Nucleo-F103RB (which uses the same chip as the Bluepill) and comes with Arduino and Morpho headers so it's great for extensibility but it only has a LED and a user configurable button in terms of built-in peripherals. Should be around $10. I can also recommend the Nucleo-F042K6 which typically is even cheaper though the form factor is less convenient and flexible but I feel the chip is a better starting point for own creations. Perhaps not surprisingly I'm maintaining the BSP crate for both. ;)

[thejpster]

I vote we go with the F3 Discovery for now, as it's the one we collectively have the most experience with (I don't, but I don't mind buying one!). In the future, I'd love to see support for multiple boards in the book, perhaps with a little drop down at the top of each page which selects the appropriate text/code where the boards differ. One hopes that the diff between say an EK-TM4C123 and an F3 Discovery would actually be fairly small.

For clarity I assume "and dual MIT/Apache for the text" is meant to say "and dual MIT/Apache for the code".

[therealprof]

I vote we go with the F3 Discovery for now, as it's the one we collectively have the most experience with (I don't, but I don't mind buying one!).

Is that so? I actually have one but I've never really used it since the discovery boards are a bit limiting in what you can do with them apart from the onboard peripherals. I'd say the most experience is available for the Bluepill since it is so dirt cheap (and most seem to really have 128kB flash instead of the advertised 64kB). The F103RB is quite likely one of the most available chips from ST since it is used for every ST-Link (v2) debugger out there.

[thejpster]

@therealprof - yeah, it's the one @japaric used in his tutorials :)

[jamesmunns]

I have made the changes discussed here, particularly using the triple licenses (CC-BY-SA for text, MIT+APACHE for code), explicitly using the F3 Discovery board for now, and correcting the default port used by mdbook.

Thank you @cldershem, @therealprof, and @thejpster for your comments.

@therealprof PRs to add support for additional boards, or to switch the board would definitely be welcome. I have initially selected the F3 board because there is so much usage of it already, and for version one of the book, I would like to borrow as much existing content as possible so we can get this released by August.