rewritten passages

embedded-workshop-book/src/radio-puzzle-help.md

@@ -2,7 +2,7 @@
 
 ## Use a dictionary.
 
-Our suggestion is to use a dictionary / map. `std::collections::HashMap` is not available in `no_std` code (without linking to a global allocator) but you can use one of the stack-allocated maps in the [`heapless`] crate. It supplies a stack-allocated, fixed-capacity version of the `std::Vec` type which will come in handy to store byte arrays. To store character mappings we recommend using a `heapless::IndexMap`.
+Our suggestion is to use a dictionary / map. `std::collections::HashMap` is not available in `no_std` code (without linking to a global allocator) but you can use one of the stack-allocated maps in the [`heapless`] crate. It supplies a stack-allocated, fixed-capacity version of the `std::Vec` type which will come in handy to store byte arrays. To store character mappings we recommend using a `heapless::LinearMap`.
 
 `heapless` is already declared as a dependency in the Cargo.toml of the project so you can directly import it into the application code using a `use` statement.
 
@@ -12,13 +12,13 @@ Our suggestion is to use a dictionary / map. `std::collections::HashMap` is not
 
 ``` rust
 use heapless::Vec;         // like `std::Vec` but stack-allocated
-use heapless::FnvIndexMap; // a dictionary / map
-use heapless::consts::*;   // defines U16, U32, U64... etc. to set the size of the IndexMap
+use heapless::LinearMap; // a dictionary / map
+use heapless::consts::*;   // defines U16, U32, U64... etc. to set the size of the LinearMap
 
 fn main() {
     // A hash map with a capacity of 16 key-value pairs allocated on the stack
     // note that U16 is a heapless constant, not Rust's u16
-    let mut my_map = FnvIndexMap::<_, _, U16>::new();
+    let mut my_map = LinearMap::<_, _, U16>::new();
     my_map.insert(b'A', b'~').unwrap();
 
     // A vector with a fixed capacity of 8 elements allocated on the stack
@@ -28,9 +28,9 @@ fn main() {
 }
 ```
 
-If you haven't used a stack-allocated collection before note that you'll need to specify the capacity of the collection as a type parameter using one of the "type-level values" in the `heapless::consts` module (e.g. `U8`, `U64` etc.). The [`heapless::IndexMap` documentation][indexMap] of the `heapless` crate has some usage examples, as does the [`heapless::Vec` documentation][vec].
+If you haven't used a stack-allocated collection before note that you'll need to specify the capacity of the collection as a type parameter using one of the "type-level values" in the `heapless::consts` module (e.g. `U8`, `U64` etc.). The [`heapless::LinearMap` documentation][indexMap] of the `heapless` crate has some usage examples, as does the [`heapless::Vec` documentation][vec].
 
-[indexMap]: https://docs.rs/heapless/0.5.5/heapless/struct.IndexMap.html
+[indexMap]: https://docs.rs/heapless/0.5.5/heapless/struct.LinearMap.html
 [vec]: https://docs.rs/heapless/0.5.5/heapless/struct.Vec.html
 
 ## Note the difference between character literals and byte literals!

embedded-workshop-book/src/radio-puzzle.md

@@ -2,10 +2,13 @@
 
 ![illustration showing that you send plaintext and the dongle responds with ciphertext](../img/puzzle_illustration.jpg)
 
-Your task in this section is to decrypt the [substitution cipher] encrypted *ASCII* string stored in the Dongle. The string has been encrypted using *simple substitution*.
+Your task in this section is to decrypt the [substitution cipher] encrypted *ASCII* string stored in the Dongle using one of the stack-allocated maps in the [`heapless`] crate. The string has been encrypted using *simple substitution*.
+
+## Preparing the Dongle
 
 
 [substitution cipher]: https://en.wikipedia.org/wiki/Substitution_cipher
+[`heapless`]: https://docs.rs/heapless
 
   ✅ Flash the `puzzle.hex` program on the Dongle. Follow the instructions from the "nRF52840 Dongle" section but flash the `puzzle.hex` program instead of the `loopback.hex` one -- don't forget to put the Dongle in bootloader mode before invoking `nrfdfu`.
 
@@ -13,13 +16,25 @@ Your task in this section is to decrypt the [substitution cipher] encrypted *ASC
 
 Like in the previous sections the Dongle will listen for radio packets -- this time over *channel 25* -- while also logging messages over a USB/serial interface.
 
+## Sending Messages and Receiving the Dongle's Responses
+
 ✅ Open the `beginner/apps` folder in VS Code; then open the `src/bin/radio-puzzle.rs` file. Run the program. 
 
-
-## Dongle Responses
+This will send a zero sized packet `let msg = b""` to the dongle. 
 
 ❗ The Dongle responds to the DK's requests wirelessly (i.e. by sending back radio packets) as well. You'll see the dongle responses printed by the DK. This means you don't have to worry if serial-term doesn't work on your machine.
 
+✅ Try sending one-byte sized packets. 
+✅ Try sending longer packets. 
+
+What happens?
+
+❗ The Dongle responds to the DK's requests wirelessly (i.e. by sending back radio packets) as well. You'll see the dongle responses printed by the DK. This means you don't have to worry if serial-term doesn't work on your machine.
+
+
+<details>
+    <summary>Answer</summary>
+
 The Dongle will respond differently depending on the length of the incoming packet:
 
 - On zero-sized packets it will respond with the encrypted string.
@@ -28,4 +43,8 @@ The Dongle will respond differently depending on the length of the incoming pack
 
 The Dongle will always respond with packets that are valid UTF-8 so you can use `str::from_utf8` on the response packets.
 
-See the next chapter for solving stragies and help.
+This step is illustrated in `src/bin/radio-puzzle-1.rs`
+
+</details>
+
+From here on, the exercise can be solved in multiple ways. If you have an idea on how to go from here and what tools to use, you can work on your own. If you don't have an idea what to do next or what tools to use, we'll provide a guide on the next page.