IEEE 802.15.4 Examples and API Fixes

apis/net/ieee802154/src/lib.rs

@@ -169,7 +169,8 @@ impl<S: Syscalls, C: Config> Ieee802154<S, C> {
 
 // Transmission
 impl<S: Syscalls, C: Config> Ieee802154<S, C> {
-    pub fn transmit_frame(frame: &[u8]) -> Result<(), ErrorCode> {
+    /// Transmit a frame using the IEEE 802.15.4 Phy Driver.
+    pub fn transmit_frame_raw(frame: &[u8]) -> Result<(), ErrorCode> {
         let called: Cell<Option<(u32,)>> = Cell::new(None);
         share::scope::<
             (
@@ -187,7 +188,7 @@ impl<S: Syscalls, C: Config> Ieee802154<S, C> {
                 subscribe, &called,
             )?;
 
-            S::command(DRIVER_NUM, command::TRANSMIT, 0, 0).to_result::<(), ErrorCode>()?;
+            S::command(DRIVER_NUM, command::TRANSMIT_RAW, 0, 0).to_result::<(), ErrorCode>()?;
 
             loop {
                 S::yield_wait();
@@ -253,7 +254,7 @@ mod command {
     pub const GET_PAN: u32 = 10;
     pub const GET_CHAN: u32 = 11;
     pub const GET_TX_PWR: u32 = 12;
-    pub const TRANSMIT: u32 = 27;
+    pub const TRANSMIT_RAW: u32 = 27;
     pub const SET_LONG_ADDR: u32 = 28;
     pub const GET_LONG_ADDR: u32 = 29;
     pub const TURN_ON: u32 = 30;

apis/net/ieee802154/src/tests.rs

@@ -111,8 +111,8 @@ fn transmit_frame() {
     let driver = fake::Ieee802154Phy::new();
     kernel.add_driver(&driver);
 
-    Ieee802154::transmit_frame(b"foo").unwrap();
-    Ieee802154::transmit_frame(b"bar").unwrap();
+    Ieee802154::transmit_frame_raw(b"foo").unwrap();
+    Ieee802154::transmit_frame_raw(b"bar").unwrap();
     assert_eq!(
         driver.take_transmitted_frames(),
         &[&b"foo"[..], &b"bar"[..]],

examples/ieee802154.rs → examples/ieee802154_raw.rs

@@ -1,7 +1,17 @@
 //! An example showing use of IEEE 802.15.4 networking.
+//!
+//! The kernel contains a standard and phy 15.4 driver. This example
+//! expects the kernel to be configured with the phy 15.4 driver to
+//! allow direct access to the radio and the ability to send "raw"
+//! frames. An example board file using this driver is provided at
+//! `boards/tutorials/nrf52840dk-thread-tutorial`.
+//!
+//! "No Support" Errors for setting the channel/tx power are a telltale
+//! sign that the kernel is not configured with the phy 15.4 driver.
 
 #![no_main]
 #![no_std]
+use core::fmt::Write;
 use libtock::console::Console;
 use libtock::ieee802154::{Ieee802154, RxOperator as _, RxRingBuffer, RxSingleBufferOperator};
 use libtock::runtime::{set_main, stack_size};
@@ -17,21 +27,43 @@ fn main() {
     let tx_power: i8 = -3;
     let channel: u8 = 11;
 
+    writeln!(Console::writer(), "Configuring IEEE 802.15.4 radio...\n").unwrap();
+
     Ieee802154::set_pan(pan);
+    writeln!(Console::writer(), "Set PAN to {:#06x}\n", pan).unwrap();
+
     Ieee802154::set_address_short(addr_short);
+    writeln!(
+        Console::writer(),
+        "Set short address to {:#06x}\n",
+        addr_short
+    )
+    .unwrap();
+
     Ieee802154::set_address_long(addr_long);
+    writeln!(
+        Console::writer(),
+        "Set long address to {:#018x}\n",
+        addr_long
+    )
+    .unwrap();
+
     Ieee802154::set_tx_power(tx_power).unwrap();
+    writeln!(Console::writer(), "Set TX power to {}\n", tx_power).unwrap();
+
     Ieee802154::set_channel(channel).unwrap();
+    writeln!(Console::writer(), "Set channel to {}\n", channel).unwrap();
 
     // Don't forget to commit the config!
     Ieee802154::commit_config();
+    writeln!(Console::writer(), "Committed radio configuration!\n").unwrap();
 
     // Turn the radio on
     Ieee802154::radio_on().unwrap();
     assert!(Ieee802154::is_on());
 
     // Transmit a frame
-    Ieee802154::transmit_frame(b"foobar").unwrap();
+    Ieee802154::transmit_frame_raw(b"foobar").unwrap();
 
     Console::write(b"Transmitted frame!\n").unwrap();
 

examples/ieee802154_rx_raw.rs

@@ -0,0 +1,89 @@
+//! An example showing use of IEEE 802.15.4 networking.
+//! It infinitely received a frame and prints its content to Console.
+//!
+//! The kernel contains a standard and phy 15.4 driver. This example
+//! expects the kernel to be configured with the phy 15.4 driver to
+//! allow direct access to the radio and the ability to send "raw"
+//! frames. An example board file using this driver is provided at
+//! `boards/tutorials/nrf52840dk-thread-tutorial`.
+//!
+//! "No Support" Errors for setting the channel/tx power are a telltale
+//! sign that the kernel is not configured with the phy 15.4 driver.
+
+#![no_main]
+#![no_std]
+use core::fmt::Write;
+use libtock::console::Console;
+use libtock::ieee802154::{Ieee802154, RxOperator as _, RxRingBuffer, RxSingleBufferOperator};
+use libtock::runtime::{set_main, stack_size};
+
+set_main! {main}
+stack_size! {0x600}
+
+fn main() {
+    // Configure the radio
+    let pan: u16 = 0xcafe;
+    let addr_short: u16 = 0xdead;
+    let addr_long: u64 = 0xdead_dad;
+    let tx_power: i8 = 4;
+    let channel: u8 = 11;
+
+    writeln!(Console::writer(), "Configuring IEEE 802.15.4 radio...\n").unwrap();
+
+    Ieee802154::set_pan(pan);
+    writeln!(Console::writer(), "Set PAN to {:#06x}\n", pan).unwrap();
+
+    Ieee802154::set_address_short(addr_short);
+    writeln!(
+        Console::writer(),
+        "Set short address to {:#06x}\n",
+        addr_short
+    )
+    .unwrap();
+
+    Ieee802154::set_address_long(addr_long);
+    writeln!(
+        Console::writer(),
+        "Set long address to {:#018x}\n",
+        addr_long
+    )
+    .unwrap();
+
+    Ieee802154::set_tx_power(tx_power).unwrap();
+    writeln!(Console::writer(), "Set TX power to {}\n", tx_power).unwrap();
+
+    Ieee802154::set_channel(channel).unwrap();
+    writeln!(Console::writer(), "Set channel to {}\n", channel).unwrap();
+
+    // Don't forget to commit the config!
+    Ieee802154::commit_config();
+    writeln!(Console::writer(), "Committed radio configuration!\n").unwrap();
+
+    // Turn the radio on
+    Ieee802154::radio_on().unwrap();
+    assert!(Ieee802154::is_on());
+    writeln!(Console::writer(), "Radio is on!\n").unwrap();
+
+    let mut buf = RxRingBuffer::<2>::new();
+    let mut operator = RxSingleBufferOperator::new(&mut buf);
+    loop {
+        let frame = operator.receive_frame().unwrap();
+
+        let body_len = frame.payload_len;
+
+        // Parse the counter.
+        let text = &frame.body[..body_len as usize - core::mem::size_of::<usize>()];
+        let counter_bytes =
+            &frame.body[body_len as usize - core::mem::size_of::<usize>()..body_len as usize];
+        let counter = usize::from_be_bytes(counter_bytes.try_into().unwrap());
+
+        writeln!(
+            Console::writer(),
+            "Received frame with body of len {}: \"{} {}\"\n",
+            body_len,
+            core::str::from_utf8(text).unwrap_or("-- error decoding utf8 string --"),
+            counter,
+        )
+        .unwrap();
+    }
+}

examples/ieee802154_rx_tx.rs → examples/ieee802154_rx_tx_raw.rs

@@ -1,10 +1,19 @@
 //! An example showing use of IEEE 802.15.4 networking.
 //! It infinitely sends a frame with a constantly incremented counter,
 //! and after each send receives a frame and prints it to Console.
+//!
+//! The kernel contains a standard and phy 15.4 driver. This example
+//! expects the kernel to be configured with the phy 15.4 driver to
+//! allow direct access to the radio and the ability to send "raw"
+//! frames. An example board file using this driver is provided at
+//!
+//! "No Support" Errors for setting the channel/tx power are a telltale
+//! sign that the kernel is not configured with the phy 15.4 driver.
+//! `boards/tutorials/nrf52840dk-thread-tutorial`.
 
 #![no_main]
 #![no_std]
-use core::fmt::Write as _;
+use core::fmt::Write;
 use libtock::alarm::{Alarm, Milliseconds};
 use libtock::console::Console;
 use libtock::ieee802154::{Ieee802154, RxOperator as _, RxRingBuffer, RxSingleBufferOperator};
@@ -18,21 +27,44 @@ fn main() {
     let pan: u16 = 0xcafe;
     let addr_short: u16 = 0xdead;
     let addr_long: u64 = 0xdead_dad;
-    let tx_power: i8 = 5;
+    let tx_power: i8 = 4;
     let channel: u8 = 11;
 
+    writeln!(Console::writer(), "Configuring IEEE 802.15.4 radio...\n").unwrap();
+
     Ieee802154::set_pan(pan);
+    writeln!(Console::writer(), "Set PAN to {:#06x}\n", pan).unwrap();
+
     Ieee802154::set_address_short(addr_short);
+    writeln!(
+        Console::writer(),
+        "Set short address to {:#06x}\n",
+        addr_short
+    )
+    .unwrap();
+
     Ieee802154::set_address_long(addr_long);
+    writeln!(
+        Console::writer(),
+        "Set long address to {:#018x}\n",
+        addr_long
+    )
+    .unwrap();
+
     Ieee802154::set_tx_power(tx_power).unwrap();
+    writeln!(Console::writer(), "Set TX power to {}\n", tx_power).unwrap();
+
     Ieee802154::set_channel(channel).unwrap();
+    writeln!(Console::writer(), "Set channel to {}\n", channel).unwrap();
 
     // Don't forget to commit the config!
     Ieee802154::commit_config();
+    writeln!(Console::writer(), "Committed radio configuration!\n").unwrap();
 
     // Turn the radio on
     Ieee802154::radio_on().unwrap();
     assert!(Ieee802154::is_on());
+    writeln!(Console::writer(), "Radio is on!\n").unwrap();
 
     let mut buf = RxRingBuffer::<2>::new();
     let mut operator = RxSingleBufferOperator::new(&mut buf);
@@ -54,25 +86,26 @@ fn main() {
         set_buf_cnt(&mut buf, &mut counter);
 
         // Transmit a frame
-        Ieee802154::transmit_frame(&buf).unwrap();
+        Ieee802154::transmit_frame_raw(&buf).unwrap();
 
         writeln!(Console::writer(), "Transmitted frame {counter}!\n").unwrap();
 
         let frame = operator.receive_frame().unwrap();
 
         let body_len = frame.payload_len;
+
+        // Parse the counter.
+        let text = &frame.body[..body_len as usize - core::mem::size_of::<usize>()];
+        let counter_bytes =
+            &frame.body[body_len as usize - core::mem::size_of::<usize>()..body_len as usize];
+        let received_counter = usize::from_be_bytes(counter_bytes.try_into().unwrap());
+
         writeln!(
             Console::writer(),
-            "Received frame with body of len {}: {}-{} {:?}!\n",
+            "Received frame with body of len {}: \"{} {}\"\n",
             body_len,
-            core::str::from_utf8(&frame.body[..frame.body.len() - core::mem::size_of::<usize>()])
-                .unwrap_or("<error decoding>"),
-            usize::from_le_bytes(
-                frame.body[frame.body.len() - core::mem::size_of::<usize>()..]
-                    .try_into()
-                    .unwrap()
-            ),
-            frame.body
+            core::str::from_utf8(text).unwrap_or("-- error decoding utf8 string --"),
+            received_counter,
         )
         .unwrap();