1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

//! How to use rmicrobit.
//!
//! # How to use rmicrobit
//!
//! ## Setting up a new project
//!
//! You will typically need:
//!  - a linker that can work with ARM binaries
//!  - a debugger that can work with ARM binaries
//!  - an OCD server
//!
//! The following instructions are written for Debian 10 ('Buster'). For other
//! platforms, see [The Embedded Rust Book].
//!
//! Install the following packages:
//!  - `binutils-arm-none-eabi`
//!  - `gdb-multiarch`
//!  - `openocd`
//!
//! Create a new project using the `rmicrobit-quickstart` template:
//! ```text
//! cargo install cargo-generate
//! ```
//! then
//! ```text
//! cargo generate --git https://mjw.woodcraft.me.uk/rmicrobit-quickstart/git/
//! ```
//! or
//! ```text
//! cargo generate --git https://github.com/mattheww/rmicrobit-quickstart
//! ```
//!
//! The template provides the following files:
//! -  `Cargo.toml`
//! - `.cargo/config`
//! - `microbit.gdb`
//! - `src/main.rs`
//!
//! The example `main.rs` uses `cortex-m-rtfm` and `cortex-m-semihosting`, but
//! projects using rmicrobit don't have to do so; you can remove them from
//! `Cargo.toml` if you don't need them.
//!
//! ### Running the new project
//!
//! Connect your micro:bit to your development machine by USB.
//!
//! In a separate shell session:
//! ```text
//! openocd -f interface/cmsis-dap.cfg -f target/nrf51.cfg
//! ```
//!
//! In the new project directory:
//! ```text
//! cargo run
//! ```
//!
//! This should launch `gdb`, which should tell the OCD server to flash the
//! program onto the micro:bit and run it. Use `Ctrl-C` followed by `Ctrl-D`
//! to exit.
//!
//! To change which version of `gdb` it runs, edit `.cargo/config`. To change
//! the instructions that `gdb` follows, edit `microbit.gdb`.
//!
//! ### Tips
//!
//! If you use `panic_semihosting`, as the example `main.rs` from the template
//! does, messages from any panics should appear in the output from openocd.
//! If other output from openocd is getting in the way, add something like `-l
//! /tmp/openocd.log` to the command line used to launch openocd.
//!
//! [The Embedded Rust Book]: https://rust-embedded.github.io/book/intro/install.html