address Lotte's feedback

- removed 'in their value' from text
- elaborate a bit more on the type level diff between `[b'H', b'i']` and `b"Hi"`
- note that not being fully 802.15.4 compliant is not an issue for the workshop
  exercises
- use `b'A'` syntax in hints now that it has been covered early on
- use large enough capacity in hints
- for consistency, set channel first thing in all hints

beginner/README.md

@@ -339,7 +339,7 @@ let slice: &[u8] = &array;
 
 `slice` and `ref_to_array` are constructed in the same way but have different types. `ref_to_array` is represented in memory as a single pointer (1 word / 4 bytes); `slice` is represented as a pointer + length (2 words / 8 bytes).
 
-Because slices track length at runtime -- in their value -- rather than in their type they can point to chunks of memory of any length.
+Because slices track length at runtime rather than in their type they can point to chunks of memory of any length.
 
 ``` rust
 let array1: [u8; 3] = [0, 1, 2];
@@ -363,7 +363,27 @@ Rust provides a more convenient way to write ASCII characters: byte literals. `b
 
 ### Byte string literals
 
-`[b'H', b'e', b'l', b'l', b'o']` can be further rewritten as `b"Hello"`. This is called a byte string literal; note that there's a `b` before the opening double quote. A byte string literal is a series of byte literals; these literals have type `&[u8; N]` where `N` is the number of byte (literals) in the string.
+`[b'H', b'e', b'l', b'l', b'o']` can be further rewritten as `b"Hello"`. This is called a *byte* string literal (note that unlike a string literal like `"Hello"` this one has a `b` before the opening double quote). A byte string literal is a series of byte literals (`u8` values); these literals have type `&[u8; N]` where `N` is the number of byte literals in the string.
+
+Because byte string literals are references you need to *dereference* them to get an array type.
+
+``` rust
+let reftoarray: &[u8; 2] = b"Hi";
+
+// these two are equivalent
+let array1:  [u8; 2] = [b'H', 'i'];
+let array2:  [u8; 2] = *b"Hi";
+//          ^          ^ dereference
+```
+
+Or if you want to go the other way around: you need to take a reference to an array to get the same type as a byte string literal.
+
+``` rust
+// these two are equivalent
+let reftoarray1: &[u8; 2] = b"Hi";
+let reftoarray2: &[u8; 2] = &[b'H', 'i'];
+//               ^          ^
+```
 
 ### Character constrains in byte string vs. string literals
 
@@ -401,7 +421,9 @@ Take note of how LQI changes with these changes. Do packet loss occur in any of
 
 ### 802.15.4 compatibility
 
-The radio interface we are using follows the IEEE 802.15.4 specification but it's missing MAC level features like addressing (each device gets its own address), opt-in acknowledgment (a transmitted packet must be acknowledged with a response acknowledgment packet; the packet is re-transmitted if the packet is not acknowledged in time). These MAC level features are not implemented *in hardware* (in the nRF52840 Radio peripheral) so they would need to be implemented in software to be fully IEEE 802.15.4 compliant.
+The radio API we are using follows the PHY layer of the IEEE 802.15.4 specification but it's missing MAC level features like addressing (each device gets its own address), opt-in acknowledgment (a transmitted packet must be acknowledged with a response acknowledgment packet; the packet is re-transmitted if the packet is not acknowledged in time). These MAC level features are not implemented *in hardware* (in the nRF52840 Radio peripheral) so they would need to be implemented in software to be fully IEEE 802.15.4 compliant.
+
+This is not an issue for the workshop exercises but it's something to consider if you would like to continue from here and build a 802.15.4 compliant network API.
 
 ## Radio in
 

beginner/apps/src/bin/radio-puzzle-1.rs

@@ -19,9 +19,11 @@ fn main() -> ! {
 
     let mut packet = Packet::new();
 
+    // first exchange a single packet with the Dongle
     // letter 'A' (uppercase)
     let source = 65;
     // let source = b'A'; // this is the same as above
+
     // TODO try other letters
 
     // single letter (byte) packet
@@ -48,8 +50,9 @@ fn main() -> ! {
 
     // TODO next do the whole ASCII range [0, 127]
     // start small: just 'A' and 'B' at first
-    // OR for source in b'A'..=b'B' (NOTE: inclusive range)
-    for _source in 65..67 {
+    // NOTE: `a..=b` means inclusive range; `a` and `b` are included in the range
+    // `a..b` means open-ended range; `a` is included in the range but `b` isn't
+    for _source in b'A'..=b'B' {
         // TODO similar procedure as above
     }
 

beginner/apps/src/bin/radio-puzzle-3.rs

@@ -18,8 +18,8 @@ fn main() -> ! {
     // puzzle.hex uses channel 25
     radio.set_channel(Channel::_25);
 
-    // TODO increase capacity
-    let dict = LinearMap::<u8, u8, consts::U2>::new();
+    // capacity (128) should be large enough for the ASCII range
+    let dict = LinearMap::<u8, u8, consts::U128>::new();
 
     let mut packet = Packet::new();
     // TODO do the whole ASCII range [0, 127]

beginner/apps/src/bin/radio-puzzle-4.rs

@@ -14,7 +14,7 @@ fn main() -> ! {
 
     // a buffer with capacity for 2 bytes
     let mut buffer = Vec::<u8, consts::U2>::new();
-    //                               ^^ capacity; this is a type not a value
+    //                                 ^^ capacity; this is a type not a value
 
     // do some insertions
     buffer.push(b'H').expect("buffer full");
@@ -29,8 +29,5 @@ fn main() -> ! {
         str::from_utf8(&buffer).expect("content was not UTF-8")
     );
 
-    // TODO try another insertion
-    // TODO try changing the capacity
-
     dk::exit()
 }

beginner/apps/src/bin/radio-puzzle-6.rs

@@ -17,16 +17,14 @@ fn main() -> ! {
     let mut radio = board.radio;
     let mut timer = board.timer;
 
-    /* # Build a dictionary */
-    // TODO increase capacity
-    let dict = LinearMap::<u8, u8, consts::U2>::new();
-
     // puzzle.hex uses channel 25
     radio.set_channel(Channel::_25);
 
+    /* # Build a dictionary */
+    let dict = LinearMap::<u8, u8, consts::U128>::new();
+
     let mut packet = Packet::new();
-    // TODO do the whole ASCII range [0, 127]
-    for source in b'A'..=b'B' {
+    for source in 0..=127 {
         packet.copy_from_slice(&[source]);
 
         radio.send(&packet);

beginner/apps/src/bin/radio-puzzle-7.rs

@@ -17,16 +17,14 @@ fn main() -> ! {
     let mut radio = board.radio;
     let mut timer = board.timer;
 
-    /* # Build a dictionary */
-    // TODO increase capacity
-    let dict = LinearMap::<u8, u8, consts::U2>::new();
-
     // puzzle.hex uses channel 25
     radio.set_channel(Channel::_25);
 
+    /* # Build a dictionary */
+    let dict = LinearMap::<u8, u8, consts::U128>::new();
+
     let mut packet = Packet::new();
-    // TODO do the whole ASCII range [0, 127]
-    for source in b'A'..=b'B' {
+    for source in 0..=127 {
         packet.copy_from_slice(&[source]);
 
         radio.send(&packet);
@@ -78,7 +76,7 @@ fn main() -> ! {
         str::from_utf8(&buffer).expect("buffer contains non-UTF-8 data")
     );
 
-    /* # Verify decrypted text */
+    /* # (NEW) Verify decrypted text */
     packet.copy_from_slice(&buffer);
 
     radio.send(&packet);