Merge pull request #114 from ferrous-systems/suggest-cyme

Suggest cyme

Author: skade

build.sh

@@ -41,12 +41,17 @@ pushd radio-app
 cargo build --target=thumbv7em-none-eabihf --release
 cargo fmt --check
 popd
-for i in usb-lib usb-lib-solutions/*; do
+for i in usb-lib-solutions/*; do
     pushd $i
     cargo build --target=thumbv7em-none-eabihf --release
     cargo fmt --check
+    cargo test
     popd
 done
+pushd usb-lib 
+    cargo build --target=thumbv7em-none-eabihf --release
+    cargo fmt --check
+popd
 pushd usb-app
 cargo build --target=thumbv7em-none-eabihf --release
 cargo fmt --check

exercise-book/src/nrf52-hardware.md

@@ -66,7 +66,7 @@ After connecting the DK to your PC/laptop it will show up as:
 ```console
 $ lsusb
 (..)
-Bus 001 Device 014: ID 1366:1015 SEGGER 4-Port USB 2.0 Hub
+Bus 001 Device 014: ID 1366:1051 SEGGER 4-Port USB 2.0 Hub
 ```
 
 The device will also show up in the `/dev` directory as a `ttyACM` device:

exercise-book/src/nrf52-radio-dongle.md

@@ -15,20 +15,20 @@ When put in bootloader mode the Dongle will run a bootloader program instead of
 
 When the Dongle is in bootloader mode its red LED will pulsate. The Dongle will also appear as a USB CDC ACM device with vendor ID `0x1915` and product ID `0x521f`.
 
-You can also use our `cargo xtask usb-list` tool, a minimal cross-platform version of the `lsusb` tool, to check out the status of the Dongle.
+You can also use `cyme`, a cross-platform version of the `lsusb` tool, to check out the status of the Dongle.
 
-✅ Run `cargo xtask usb-list` **in the root** of the rust-exercises checkout to list all USB devices; the Dongle will be highlighted in the output, along with a note if in bootloader mode.
+✅ Run `cyme` to list all USB devices.
 
 Output should look like this:
 
 ```console
-radio-app/ $ cd ../..
-rust-exercises/ $ cargo xtask usb-list
+$ cyme
+(..)
+  2  16  0x1915 0x521f Open DFU Bootloader      E1550CA275E7      12.0 Mb/s
 (..)
-Bus 001 Device 016: ID 1915:521f <- nRF52840 Dongle (in bootloader mode)
 ```
 
-🔎 [`cargo xtask`](https://github.com/matklad/cargo-xtask) lets us extend `cargo` with custom commands which are installed as you run them for the first time. We've used it to add some helper tools to our workshop materials while keeping the preparation installations as minimal as possible.
+The first two values depend on your host computer and which USB port you used, so they will be different for you. The hex-string is the device's unique ID and that will also be different.
 
 Now that the device is in bootloader mode browse to the [`nrf52-code/boards/dongle-fw`](../../nrf52-code/boards/dongle-fw) directory. You'll find some `ELF` files (without a file ending) there. These are pre-compiled Rust programs to be flashed onto your dongle.
 
@@ -56,19 +56,19 @@ After the device has been programmed it will automatically reset and start runni
 
 🔎 The `loopback` application will make the Dongle enumerate itself as a CDC ACM device.
 
-✅ Run `cargo xtask usb-list` tool to see the newly enumerated Dongle in the output:
+✅ Run `cyme` to see the newly enumerated Dongle in the output:
 
 ```console
-$ cargo xtask usb-list
+$ cyme
 (..)
-Bus 001 Device 020: ID 1209:0309 <- nRF52840 Dongle (loopback-fw)
+  2  16  0x1209 0x0309 Dongle Loopback          -                 12.0 Mb/s
 ```
 
 The `loopback` app will log messages over the USB interface. To display these messages on the host we have provided a cross-platform tool: `cargo xtask serial-term`.
 
 ❗ Do not use serial terminal emulators like `minicom` or `screen`. They use the USB TTY ACM interface in a slightly different manner and may result in data loss.
 
-✅ Run `cargo xtask serial-term`. It shows you the logging output the Dongle is sending on its serial interface to your computer. This helps you monitor what's going on at the Dongle and debug connection issues. Start with the Dongle unplugged and you should see the following output:
+✅ Run `cargo xtask serial-term` from the root of the extracted tarball / git checkout. It shows you the logging output the Dongle is sending on its serial interface to your computer. This helps you monitor what's going on at the Dongle and debug connection issues. Start with the Dongle unplugged and you should see the following output:
 
 ```console
 $ cargo xtask serial-term

exercise-book/src/nrf52-tools.md

@@ -82,7 +82,7 @@ In Zadig's graphical user interface,
 
 2. From the device (top) drop down menu select "BULK interface (Interface nnn)"
 
-3. Once that device is selected, `1366 1015` should be displayed in the USB ID field. That's the Vendor ID - Product ID pair.
+3. Once that device is selected, `1366 1051` should be displayed in the USB ID field. That's the Vendor ID - Product ID pair.
 
 4. Select 'WinUSB' as the target driver (right side)
 
@@ -104,10 +104,6 @@ Go to [https://rustup.rs](https://rustup.rs/) and follow the instructions.
 
 **Windows**: It's OK to ignore the message about `git` not being installed, if you get one!
 
-### Better TOML
-
-**All**: For better handling of `Cargo.toml` files, we recommend you install [Better TOML](https://marketplace.visualstudio.com/items?itemName=bungcip.better-toml) if you're using VS Code.
-
 ### Rust Cross compilation support
 
 **All**: Run this command in a terminal:
@@ -125,9 +121,9 @@ cargo install cargo-binutils
 rustup +stable component add llvm-tools
 ```
 
-### General purpose tools
+### Third-party tools written in Rust
 
-Install the [`flip-link`](https://crates.io/crates/flip-link) and [`nrf-dfu`](https://crates.io/crates/nrfdfu) tools from source using the following Cargo commands:
+Install the [`flip-link`](https://crates.io/crates/flip-link), [`nrf-dfu`](https://crates.io/crates/nrfdfu) and [`cyme`](https://crates.io/crates/cyme) tools from source using the following Cargo commands:
 
 ```console
 $ cargo install flip-link
@@ -137,6 +133,10 @@ Installed package `flip-link v0.1.7` (..)
 $ cargo install nrfdfu
 (..)
 Installed package `nrfdfu v0.1.3` (..)
+
+$ cargo install cyme
+(..)
+Installed package `cyme v1.7.0` (..)
 ```
 
 Install `probe-rs` 0.24 pre-compiled binaries on Linux or macOS with:
@@ -162,6 +162,27 @@ cargo-size 0.3.6
 
 ✅ Connect the nRF52840-DK with your computer by plugging the usb-cable into the J2 connector on the DK (the usb connector on the short side of the board).
 
+✅ Use `cyme` to list the USB devices on your computer.
+
+```console
+$ cyme
+(..)
+  2  15  0x1366 0x1051 J-Link                   001050255503      12.0 Mb/s
+(..)
+```
+
+Your nRF52840-DK should appear as "J-Link" with USB Vendor ID (VID) of 0x1366 and a USB Product ID (PID) 0x1051.
+
+🔎 If `cyme` doesn't work for any reason, you can use `cargo xtask usb-list`, which does the same thing but is much more basic. Run it from the root of the extracted tarball / git checkout:
+
+```console
+$ cargo xtask usb-list
+    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.04s
+     Running `xtask/target/debug/xtask usb-list`
+Bus 002 Device 015: ID 1366:1051 <- J-Link on the nRF52840 Development Kit
+(...) random other USB devices will be listed
+```
+
 ✅ In the terminal run the following command from the [`nrf52-code/radio-app`](../../nrf52-code/radio-app) folder. This will build and run a simple program on the DK to test the set-up.
 
 ```console

exercise-book/src/nrf52-usb-data-stage.md

@@ -28,8 +28,8 @@ The raw values you need to pack into the descriptor are as follows. Note, we won
 - `bDescriptorType = 1`, device descriptor type (must always be this value)
 - `bDeviceClass = bDeviceSubClass = bDeviceProtocol = 0`, these are unimportant for enumeration
 - `bMaxPacketSize0 = 64`, this is the most performant option (minimizes exchanges between the device and the host) and it's assumed by the `Ep0In` abstraction
-- `idVendor = consts::VID`, value expected by `cargo xtask usb-list` (\*)
-- `idProduct = consts::PID`, value expected by `cargo xtask usb-list` (\*)
+- `idVendor = consts::VID`, our example's USB Vendor ID (\*)
+- `idProduct = consts::PID`, our example's USB Product ID (\*)
 - `bcdDevice = 0x0100`, this means version 1.0 but any value should do
 - `iManufacturer = iProduct = iSerialNumber = None`, string descriptors not supported
 - `bNumConfigurations = 1`, must be at least `1` so this is the minimum value

exercise-book/src/nrf52-usb-idle-state.md

@@ -55,12 +55,13 @@ You can find traces for other OSes in these files (they are in the [`nrf52-code/
 - `macos-enumeration.txt`
 - `win-enumeration.txt`
 
-✅ Double check that the enumeration works by running [`cargo xtask usb-list`](./nrf52-usb-listing-usb-devices.md) while `usb-4.rs` is running.
+✅ Double check that the enumeration works by running [`cyme`](./nrf52-usb-listing-usb-devices.md) while `usb-4.rs` is running.
 
 ```console
-Bus 001 Device 013: ID 1366:1015 <- J-Link on the nRF52840 Development Kit
-(..)
-Bus 001 Device 016: ID 1209:0717 <- nRF52840 on the nRF52840 Development Kit
+$ cyme
+(...) random other USB devices will be listed
+  2  15  0x1366 0x1051 J-Link                   001050255503      12.0 Mb/s
+  2  16  0x1209 0x0717 composite_device         -                 12.0 Mb/s
 ```
 
 Both the J-Link and the device implemented by your firmware should appear in the list.

exercise-book/src/nrf52-usb-listing-usb-devices.md

@@ -1,18 +1,20 @@
 # Listing USB Devices
 
-✅ To list all USB devices, run `cargo xtask usb-list` from the top-level checkout.
+As we showed in [Preparation/Software Tools](./nrf52-tools.md), we can use `cyme` to list USB devices on our system.
+
+✅ To list all USB devices, run `cyme` from the top-level checkout.
 
 ```console
-$ cargo xtask usb-list
+$ cyme
 (...) random other USB devices will be listed
-Bus 001 Device 010: ID 1366:1015 <- J-Link on the nRF52840 Development Kit
+  2  15  0x1366 0x1051 J-Link                   001050255503      12.0 Mb/s
 ```
 
-The goal of this workshop is to get the nRF52840 SoC to show in this list. The embedded application will use the USB Vendor ID (VID) and USB Product ID (PID) defined in [`nrf52-code/consts`](../../nrf52-code/consts); `cargo xtask usb-list` will highlight the USB device that matches that VID/PID pair, like this:
+The goal of this workshop is to get the nRF52840 SoC to show in this list. The embedded application will use the USB Vendor ID (VID) 0x1209 and USB Product ID (PID) 0x0717, as defined in [`nrf52-code/consts`](../../nrf52-code/consts):
 
 ```console
-$ cargo xtask usb-list
+$ cyme
 (...) random other USB devices will be listed
-Bus 001 Device 010: ID 1366:1015 <- J-Link on the nRF52840 Development Kit
-Bus 001 Device 059: ID 1209:0717 <- nRF52840 on the nRF52840 Development Kit
-```
+  2  15  0x1366 0x1051 J-Link                   001050255503      12.0 Mb/s
+  2  16  0x1209 0x0717 composite_device         -                 12.0 Mb/s
+````

nrf52-code/usb-app-solutions/Cargo.lock

@@ -19,7 +19,7 @@ defmt = "0.3.5"
 defmt-rtt = "0.4"
 dk = { path = "../boards/dk", features = ["advanced"] }
 panic-probe = { version = "0.3.0", features = ["print-defmt"] }
-usb = { path = "../usb-lib" }
+usb = { path = "../usb-lib-solutions/complete" }
 usb2 = "0.0.1"
 
 [dependencies.heapless]

nrf52-code/usb-app-solutions/Cargo.toml

@@ -0,0 +1,2 @@
+target
+Cargo.lock