diff --git a/mdbook/src/03-setup/README.md b/mdbook/src/03-setup/README.md index b7b09f4..e70d83c 100644 --- a/mdbook/src/03-setup/README.md +++ b/mdbook/src/03-setup/README.md @@ -6,35 +6,32 @@ different from your computer's and we'll have to run and debug programs on a "re ## Documentation Tooling is not everything though. Without documentation, it is pretty much impossible to work with -microcontrollers. - -We'll be referring to all these documents throughout this book: - -- [LSM303AGR] - -[LSM303AGR]: https://www.st.com/resource/en/datasheet/lsm303agr.pdf +microcontrollers. The official MB2 technical documentation is at . We +will reference other technical documentation throughout the book. ## Tools We'll use all the tools listed below. Where a minimum version is not specified, any recent version should work but we have listed the version we have tested. -- Rust 1.57.0 or a newer toolchain. +- Rust 1.79.0 or a newer toolchain. -- `gdb-multiarch`. Tested version: 10.2. Other versions will most likely work as well though - If your distribution/platform does not have `gdb-multiarch` available `arm-none-eabi-gdb` - will do the trick as well. Furthermore, some normal `gdb` binaries are built with multiarch - capabilities as well, you can find further information about this in the sub chapters. +- `gdb-multiarch`. This is a debugging tool. The oldest tested version is10.2, but other versions + will most likely work as well. If your distribution/platform does not have `gdb-multiarch` + available `arm-none-eabi-gdb` will do the trick as well. Furthermore, some normal `gdb` binaries + are built with multiarch capabilities as well: you can find further information about this in the + debugging chapter of this book. -- [`cargo-binutils`]. Version 0.3.3 or newer. +- [`cargo-binutils`]. Version 0.3.6 or newer. -[`cargo-binutils`]: https://github.com/rust-embedded/cargo-binutils + [`cargo-binutils`]: https://github.com/rust-embedded/cargo-binutils -- [`cargo-embed`]. Version 0.24.0 or newer. +- [`probe-rs-tools`]. Version 0.24.0. -[`cargo-embed`]: https://probe.rs/docs/tools/cargo-embed/ + [`probe-rs-tools`]: https://probe.rs/docs/overview/about-probe-rs/ -- `minicom` on Linux and macOS. Tested version: 2.7.1. Other versions will most likely work as well though +- `minicom` on Linux and macOS. Tested version: 2.7.1. Other versions will most likely work as well + though. - `PuTTY` on Windows. @@ -44,46 +41,53 @@ Next, follow OS-agnostic installation instructions for a few of the tools: Install rustup by following the instructions at [https://rustup.rs](https://rustup.rs). -If you already have rustup installed double check that you are on the stable -channel and your stable toolchain is up-to-date. `rustc -V` should return a date -newer than the one shown below: +If you already have rustup installed, double check that you are on the stable channel and your +stable toolchain is up-to-date. `rustc -V` should return a date and version no older than the one +shown below: ``` console $ rustc -V -rustc 1.53.0 (53cb7b09b 2021-06-17) +rustc 1.79.0 (129f3b996 2024-06-10) ``` ### `cargo-binutils` ``` console $ rustup component add llvm-tools - $ cargo install cargo-binutils --vers 0.3.3 - $ cargo size --version -cargo-size 0.3.3 +cargo-size 0.3.6 ``` -### `cargo-embed` +### `probe-rs-tools` -In order to install cargo-embed, first install its [prerequisites](https://probe.rs/docs/getting-started/installation/) (note: these instructions are part of the more general [`probe-rs`](https://probe.rs/) embedded debugging toolkit). Then install it with cargo: +In order to install `probe-rs-tools`, first install its +[prerequisites](https://probe.rs/docs/getting-started/installation/) (note: these instructions are +part of the more general [`probe-rs`](https://probe.rs/) embedded debugging toolkit). Then install +it with Cargo. ```console $ cargo install probe-rs-tools --vers 0.24.0 +``` + +This will install several useful tools, including `probe-rs` and `cargo-embed` (which is normally +run as a Cargo command). +``` $ cargo embed --version cargo-embed 0.24.0 (git commit: crates.io) ``` ### This repository -Since this book also contains some small Rust code bases used in various chapters -you will also have to download its source code. You can do this in one of the following ways: +This book also contains some small Rust codebases used in various chapters: the easiest way to use +these is to download the book's source code. You can do this in one of the following ways: + +- Visit the [repository](https://github.com/rust-embedded/discovery-mb2/), click the green "Code" + button and then the "Download Zip" one. -* Visit the [repository](https://github.com/rust-embedded/discovery/), click the green "Code" button and then the - "Download Zip" one -* Clone it using git (if you know git you presumably already have it installed) from the same repository as linked in - the zip approach +- Clone it using `git` (if you know `git` you presumably already have it installed) from the same + repository as linked in the Zip approach. ### OS specific instructions diff --git a/mdbook/src/03-setup/linux.md b/mdbook/src/03-setup/linux.md index 6e0ccc4..b43e45d 100644 --- a/mdbook/src/03-setup/linux.md +++ b/mdbook/src/03-setup/linux.md @@ -4,53 +4,46 @@ Here are the installation commands for a few Linux distributions. ## Ubuntu 20.04 or newer / Debian 10 or newer -> **NOTE** `gdb-multiarch` is the GDB command you'll use to debug your ARM -> Cortex-M programs +> **NOTE** `gdb-multiarch` is the GDB command you'll use to debug your ARM Cortex-M programs. ``` console -$ sudo apt-get install \ - gdb-multiarch \ - minicom +$ sudo apt install gdb-multiarch minicom libunwind-dev ``` ## Fedora 32 or newer + > **NOTE** `gdb` is the GDB command you'll use to debug your ARM -> Cortex-M programs +> Cortex-M programs. ``` console -$ sudo dnf install \ - gdb \ - minicom +$ sudo dnf install gdb minicom libunwind-devel ``` ## Arch Linux > **NOTE** `arm-none-eabi-gdb` is the GDB command you'll use to debug your ARM -> Cortex-M programs +> Cortex-M programs. ``` console -$ sudo pacman -S \ - arm-none-eabi-gdb \ - minicom +$ sudo pacman -S arm-none-eabi-gdb minicom libunwind-dev ``` ## Other distros -> **NOTE** `arm-none-eabi-gdb` is the GDB command you'll use to debug your ARM -> Cortex-M programs +> **NOTE** `arm-none-eabi-gdb` is the GDB command you'll use to debug your ARM Cortex-M programs. For distros that don't have packages for [ARM's pre-built -toolchain](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads), -download the "Linux 64-bit" file and put its `bin` directory on your path. -Here's one way to do it: +toolchain](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads), download the "Linux +64-bit" file and put its `bin` directory on your path. Here's one way to do it: ``` console -$ mkdir -p ~/local && cd ~/local -$ tar xjf /path/to/downloaded/file/gcc-arm-none-eabi-9-2020-q2-update-x86_64-linux.tar.bz2 +$ mkdir -p ~/local +$ cd ~/local +$ tar xjf /path/to/downloaded/XXX.tar.bz2 ``` -Then, use your editor of choice to append to your `PATH` in the appropriate -shell init file (e.g. `~/.zshrc` or `~/.bashrc`): +Then, use your editor of choice to append to your `PATH` in the appropriate shell init file +(e.g. `~/.zshrc` or `~/.bashrc`): ``` -PATH=$PATH:$HOME/local/gcc-arm-none-eabi-9-2020-q2-update/bin +PATH=$PATH:$HOME/local/XXX/bin ``` ## udev rules @@ -76,9 +69,57 @@ Then reload the udev rules with: $ sudo udevadm control --reload ``` -If you had any board plugged to your computer, unplug them and then plug them in again, or run the following command. +If you had any board plugged to your computer, unplug them and then plug them in again, or run the +following command. + +``` console +$ sudo udevadm trigger +``` + +## Verify permissions + +Connect the micro:bit to your computer using a USB cable. + +The micro:bit should now appear as a USB device (file) in `/dev/bus/usb`. Let's find out how it got +enumerated: ``` console +$ lsusb | grep -i "NXP ARM mbed" +Bus 001 Device 065: ID 0d28:0204 NXP ARM mbed +$ # ^^^ ^^^ +``` + +In my case, the micro:bit got connected to the bus #1 and got enumerated as the device #65. This means the +file `/dev/bus/usb/001/065` *is* the micro:bit. Let's check the file permissions: + +``` console +$ ls -l /dev/bus/usb/001/065 +crw-rw-r--+ 1 nobody nobody 189, 64 Sep 5 14:27 /dev/bus/usb/001/065 +``` + +The permissions should be `crw-rw-r--+`, note the `+` at the end, then see your access rights by running the following command. + +``` console +$ getfacl /dev/bus/usb/001/065 +getfacl: Removing leadin '/' from absolute path names +# file: dev/bus/usb/001/065 +# owner: nobody +# group: nobody +user::rw- +user::rw- +group::rw- +mask::rw- +other::r- +``` + +You should see your username in the list above with the +`rw-` permissions, if not ... then check your [udev rules] +and try re-loading them with: + +[udev rules]: linux.md#udev-rules + +``` console +$ sudo udevadm control --reload $ sudo udevadm trigger ``` diff --git a/mdbook/src/03-setup/verify.md b/mdbook/src/03-setup/verify.md index a8aead6..128bacb 100644 --- a/mdbook/src/03-setup/verify.md +++ b/mdbook/src/03-setup/verify.md @@ -2,65 +2,17 @@ Let's verify that all the tools were installed correctly. -## Linux only - -### Verify permissions - -Connect the micro:bit to your computer using a USB cable. - -The micro:bit should now appear as a USB device (file) in `/dev/bus/usb`. Let's find out how it got -enumerated: - -``` console -$ lsusb | grep -i "NXP ARM mbed" -Bus 001 Device 065: ID 0d28:0204 NXP ARM mbed -$ # ^^^ ^^^ -``` - -In my case, the micro:bit got connected to the bus #1 and got enumerated as the device #65. This means the -file `/dev/bus/usb/001/065` *is* the micro:bit. Let's check the file permissions: - -``` console -$ ls -l /dev/bus/usb/001/065 -crw-rw-r--+ 1 nobody nobody 189, 64 Sep 5 14:27 /dev/bus/usb/001/065 -``` - -The permissions should be `crw-rw-r--+`, note the `+` at the end, then see your access rights by running the following command. - -``` console -$ getfacl /dev/bus/usb/001/065 -getfacl: Removing leadin '/' from absolute path names -# file: dev/bus/usb/001/065 -# owner: nobody -# group: nobody -user::rw- -user::rw- -group::rw- -mask::rw- -other::r- -``` - -You should see your username in the list above with the `rw-` permissions, if not ... then check your [udev -rules] and try re-loading them with: - -[udev rules]: linux.md#udev-rules - -``` console -$ sudo udevadm control --reload -$ sudo udevadm trigger -``` - -# All - ## Verifying cargo-embed + First, connect the micro:bit to your Computer using a USB cable. -At least an orange LED right next to the USB port of the micro:bit should light up. -Furthermore, if you have never flashed another program on to your micro:bit, the default -program the micro:bit ships with should start blinking the red LEDs on its back, you -can ignore them. +At least an orange LED right next to the USB port of the micro:bit should light up. Furthermore, if +you have never flashed another program on to your micro:bit, the default program the micro:bit ships +with should start blinking the red LEDs on its back: you can ignore them, or you can play with the +demo app. -Now let's see if probe-rs, and by extensions cargo-embed can see your micro:bit, you can do this by running the following command. +Now let's see if probe-rs, and by extensions cargo-embed can see your micro:bit. You can do this by +running the following command: ``` console $ probe-rs list @@ -98,13 +50,11 @@ Debug Port: DPv1, DP Designer: ARM Ltd Debugging RISC-V targets over SWD is not supported. For these targets, JTAG is the only supported protocol. RISC-V specific information cannot be printed. Debugging Xtensa targets over SWD is not supported. For these targets, JTAG is the only supported protocol. Xtensa specific information cannot be printed. - ``` -Next run one of these commands: +Next, make sure you are in `src/03-setup` of this book's source code. Then run these commands: ``` -$ # make sure you are in src/03-setup of the books source code $ rustup target add thumbv7em-none-eabihf $ cargo embed --target thumbv7em-none-eabihf ``` diff --git a/mdbook/src/03-setup/windows.md b/mdbook/src/03-setup/windows.md index d9358ce..ce2561f 100644 --- a/mdbook/src/03-setup/windows.md +++ b/mdbook/src/03-setup/windows.md @@ -12,7 +12,7 @@ $ arm-none-eabi-gcc -v gcc version 5.4.1 20160919 (release) (..) ``` -[gcc]: https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads +[gcc]: https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads ## PuTTY diff --git a/mdbook/src/04-meet-your-hardware/microbit-v1.md b/mdbook/src/04-meet-your-hardware/microbit-v1.md deleted file mode 100644 index 3436336..0000000 --- a/mdbook/src/04-meet-your-hardware/microbit-v1.md +++ /dev/null @@ -1,66 +0,0 @@ -# Nordic nRF51822 (the "nRF51", micro:bit v1) - -Our MCU has 48 tiny metal **pins** sitting right underneath it (it's a so called [QFN48] chip). -These pins are connected to **traces**, the little "roads" that act as the wires connecting components -together on the board. The MCU can dynamically alter the electrical properties -of the pins. This works similar to a light switch altering how electrical -current flows through a circuit. By enabling or disabling electrical current to -flow through a specific pin, an LED attached to that pin (via the traces) can -be turned on and off. - -Each manufacturer uses a different part numbering scheme, but many will allow -you to determine information about a component simply by looking at the part -number. Looking at our MCU's part number (`N51822 QFAAH3 1951LN`, you probably cannot -see it with your bare eye, but it is on the chip), the `n` at the -front hints to us that this is a part manufactured by [Nordic Semiconductor]. -Looking up the part number on their website we quickly find the [product page]. -There we learn that our chip's main marketing point is that it is a -"Bluetooth Low Energy and 2.4 GHz SoC" (SoC being short for "System on a Chip"), -which explains the RF in the product name since RF is short for radio frequency. -If we search through the documentation of the chip linked on the [product page] -for a bit we find the [product specification] which contains chapter 10 "Ordering Information" -dedicated to explaining the weird chip naming. Here we learn that: - -[QFN48]: https://en.wikipedia.org/wiki/Flat_no-leads_package -[Nordic Semiconductor]: https://www.nordicsemi.com/ -[product page]: https://www.nordicsemi.com/products/nrf51822 -[product specification]: https://infocenter.nordicsemi.com/pdf/nRF51822_PS_v3.3.pdf - -- The `N51` is the MCU's series, indicating that there are other `nRF51` MCUs -- The `822` is the part code -- The `QF` is the package code, in this case short for `QFN48` -- The `AA` is the variant code, indicating how much RAM and flash memory the MCU has, - in our case 256 kilobyte flash and 16 kilobyte RAM -- The `H3` is the build code, indicating the hardware version (`H`) as well as the product configuration (`3`) -- The `1951LN` is a tracking code, hence it might differ on your chip - -The product specification does of course contain a lot more useful information about -the chip, for example that it is based on an ARM® Cortex™-M0 32-bit processor. - -### Arm? Cortex-M0? - -If our chip is manufactured by Nordic, then who is Arm? And if our chip is the -nRF51822, what is the Cortex-M0? - -You might be surprised to hear that while "Arm-based" chips are quite -popular, the company behind the "Arm" trademark ([Arm Holdings]) doesn't -actually manufacture chips for purchase. Instead, their primary business -model is to just *design* parts of chips. They will then license those designs to -manufacturers, who will in turn implement the designs (perhaps with some of -their own tweaks) in the form of physical hardware that can then be sold. -Arm's strategy here is different from companies like Intel, which both -designs *and* manufactures their chips. - -Arm licenses a bunch of different designs. Their "Cortex-M" family of designs -are mainly used as the core in microcontrollers. For example, the Cortex-M0 -(the core our chip is based on) is designed for low cost and low power usage. -The Cortex-M7 is higher cost, but with more features and performance. - -Luckily, you don't need to know too much about different types of processors -or Cortex designs for the sake of this book. However, you are hopefully now a -bit more knowledgeable about the terminology of your device. While you are -working specifically with an nRF51822, you might find yourself reading -documentation and using tools for Cortex-M-based chips, as the nRF51822 is -based on a Cortex-M design. - -[Arm Holdings]: https://www.arm.com/