Merge pull request #67 from stm32-rs/improve_examples

Improve examples

Author: datdenkikniet

.github/workflows/build.yml

@@ -97,21 +97,14 @@ jobs:
     strategy:
       matrix:
         example:
-          - name: arp
-            example: arp
-            features: defmt
-          - name: ip
-            example: ip
-            features: defmt,smoltcp-phy,smoltcp/defmt,smoltcp/socket-tcp
-          - name: pktgen
-            example: pktgen
-            features: defmt
-          - name: rtic-echo
-            example: rtic-echo
-            features: rtic-echo-example
-          - name: rtic-echo with nucleo pins
-            example: rtic-echo
-            features: rtic-echo-example,example-nucleo-pins
+          - example: arp
+            features: ""
+          - example: ip
+            features: smoltcp-phy
+          - example: pktgen
+            features: ""
+          - example: rtic-echo
+            features: smoltcp-phy
         mcu:
           - stm32f107
           - stm32f429
@@ -120,19 +113,22 @@ jobs:
           - stable
         target:
           - thumbv7m-none-eabi
+        pins:
+          - nucleo
+          - default
     steps:
       - name: Checkout
         uses: actions/checkout@v3
 
-      - name: Install Rust ${{ matrix.toolchain }} with target (${{ matrix.target }})
+      - name: Install Rust ${{ matrix.toolchain }} with target (${{ matrix.target }}) and pins ${{ matrix.pins }}
         run: |
           rustup set profile minimal
           rustup override set ${{ matrix.toolchain }}
           rustup target add ${{ matrix.target }}
 
-      - name: Build example ${{ matrix.example.name }} for ${{ matrix.mcu }}
+      - name: Build example ${{ matrix.example.example }} for ${{ matrix.mcu }}
         run: |
-          cargo build --release --target=${{ matrix.target }} --example ${{ matrix.example.example}} --features ${{ matrix.mcu }},${{ matrix.example.features }}
+          STM32_ETH_EXAMPLE_PINS=${{ matrix.pins }} cargo build --release --target=${{ matrix.target }} --example ${{ matrix.example.example}} --features ${{ matrix.mcu }},${{ matrix.example.features }}
 
   # Refs: https://github.com/rust-lang/crater/blob/9ab6f9697c901c4a44025cf0a39b73ad5b37d198/.github/workflows/bors.yml#L125-L149
   #

Cargo.toml

@@ -63,10 +63,6 @@ stm32f779 = ["stm32f7xx-hal/stm32f779", "device-selected", "fence"]
 
 smoltcp-phy = ["smoltcp"]
 
-# Example features
-example-nucleo-pins = [ ]
-rtic-echo-example = [ "defmt", "smoltcp-phy", "smoltcp/defmt", "smoltcp/medium-ethernet", "smoltcp/socket-tcp" ]
-
 [dev-dependencies]
 cortex-m = { version = "0.7", features = ["critical-section-single-core"] }
 cortex-m-rt = "0.7"
@@ -75,25 +71,23 @@ cortex-m-rtic = "1.0"
 defmt-rtt = "0.4"
 panic-probe = { version = "0.3", features = [ "print-defmt" ] }
 systick-monotonic = "1.0"
-smoltcp = { version = "0.8", features = [ "medium-ethernet", "proto-ipv4", "socket-udp" ], default-features = false }
+smoltcp = { version = "0.8", features = [ "medium-ethernet", "proto-ipv4", "socket-udp", "socket-tcp", "defmt" ], default-features = false }
 
 [[example]]
 name = "pktgen"
 required-features = [ "defmt" ]
 
 [[example]]
 name = "ip"
-required-features = [
-    "defmt", "smoltcp-phy", "smoltcp/defmt", "smoltcp/socket-tcp"
-    ]
+required-features = [ "defmt", "smoltcp-phy" ]
 
 [[example]]
 name = "arp"
 required-features = [ "defmt" ]
 
 [[example]]
 name = "rtic-echo"
-required-features = [ "rtic-echo-example" ]
+required-features = [ "defmt" , "smoltcp-phy" ]
 
 [profile.release]
 debug = 2

README.md

@@ -8,7 +8,7 @@
 * STM32F4xx
 * STM32F7xx
 
-Please send pull requests.
+Pull requests are welcome :)
 
 ## Usage
 
@@ -92,38 +92,34 @@ The examples should run and compile on any MCU that has an 802.3 compatible PHY
 
 The examples use `defmt` and `defmt_rtt` for logging, and `panic_probe` over `defmt_rtt` for printing panic backtraces.
 
-To run or build them, the following steps should be taken:
+##### Alternative pin configuration & HSE
 
-1. Determine the correct compilation target for the MCU that you're using. For `stm32f107`, it is `thumbv7m-none-eabi`. For all others, it is `thumbv7em-none-eabihf`.
-2. Determine the MCU feature necessary for running on your MCU, e.g. `stm32f745`.
-3. Determine the Additional required features (see section below) necessary to build the example.
-4. Follow the rest of the instructions in the ["Building examples"](#building-examples) or ["Running examples"](#running-examples) subsections.
+If the board you're developing for has a High Speed External oscillator connected to the correct pins, the HSE configuration can be activated by setting the `STM32_ETH_EXAMPLE_HSE` environment variable to one of `oscillator` or `bypass` when compiling.
 
-### Additional required features
-
-Besides the feature selecting the correct MCU to be used when building and/or running an example, the following additional features are required:
-
-| Example     | Additional required features                         |
-| ----------- | ---------------------------------------------------- |
-| `arp`       | `defmt`                                              |
-| `ip`        | `defmt,smoltcp-phy,smoltcp/defmt,smoltcp/socket-tcp` |
-| `pktgen`    | `defmt`                                              |
-| `rtic-echo` | `rtic-echo-example`                                  |
-
-#### 144-pin nucleo boards
-
-For `stm32` 144-pin nucleo boards that contain an MCU supported by this crate the `example-nucleo-pins` feature should be activated. This causes the examples to use PG11 as TX_EN and PG13 as TXD0, instead of PB11 and PB12, which is the configuration used on these boards.
+If the board you're developing for uses the nucleo pinout (PG11 and PG13 instead of PB11 and PB12), the pin configuration can be changed by setting the `STM32_ETH_EXAMPLE_PINS` environment variable to `nucleo` when compiling.
 
 ### Building examples
-Run the following command:
+To build an example, run the following command:
 ```bash
-cargo build --release --example <example> --features <MCU feature>,<additional required features> --target <MCU compilation target>
+cargo build --release --example <example> \
+    --features <MCU feature>,<additional required features> \
+    --target <MCU compilation target>
 ```
 
 For example, if we wish to build the `ip` example for an `stm32f429`, we should run the following command:
 
 ```bash
-cargo build --release --example ip --features stm32f429,defmt,smoltcp-phy,smoltcp/defmt,smoltcp/socket-tcp --target thumbv7em-none-eabihf
+cargo build --release --example ip \
+        --features stm32f429,smoltcp-phy \
+        --target thumbv7em-none-eabihf
+```
+
+If we wish to build the `arp` example for a Nucleo-F767ZI with a HSE oscillator:
+
+```bash
+STM32_ETH_EXAMPLE_HSE=bypass STM32_ETH_EXAMPLE_PINS=nucleo \
+cargo build --release --example arp \
+    --features stm32f767
 ```
 
 ### Running examples
@@ -135,15 +131,27 @@ Ensure that `probe-run` can attach to your MCU
 
 Then, run the following command:
 ```bash
-DEFMT_LOG=info PROBE_RUN_CHIP=<probe-run chip> cargo run --release --example <example> --features <MCU feature>,<additional required features> --target <MCU compilation target>
+DEFMT_LOG=info PROBE_RUN_CHIP=<probe-run chip> \
+cargo run --release --example <example> \
+    --features <MCU feature>,<additional required features> \
+    --target <MCU compilation target>
 ```
 
 For example, if we wish to run the `rtic-echo` example on an `STM32F107RCT6`, we should run the following command:
 
 ```bash
-DEFMT_LOG=info PROBE_RUN_CHIP=STM32F107RC cargo run --release --example rtic-echo --features stm32f107,rtic-echo-example --target thumbv7m-none-eabi
+DEFMT_LOG=info PROBE_RUN_CHIP=STM32F107RC \
+cargo run --release --example rtic-echo \
+    --features stm32f107,smoltcp-phy \
+    --target thumbv7m-none-eabi
 ```
 
-### Other pin configurations
+Or, if we want to run the `arp` example on a Nucleo-F767ZI with a HSE oscillator:
 
-If the usage of different pins is required, the types and `setup_pins` function in `examples/common.rs` should be edited. If the pin configuration is for a `nucleo` board or other commonly used board, a PR with the changes is most welcome.
+```bash
+DEFMT_LOG=info PROBE_RUN_CHIP=STM32F767ZGTx \
+STM32_ETH_EXAMPLE_PINS=nucleo STM32_ETH_EXAMPLE_HSE=oscillator \
+cargo run --release --example arp \
+    --features stm32f767 \
+    --target thumbv7em-none-eabihf
+```

build.rs

@@ -1,4 +1,29 @@
 fn main() {
     #[cfg(feature = "stm32f1xx-hal")]
-    println!("cargo:rustc-link-search=memory.x")
+    println!("cargo:rustc-link-search=memory.x");
+
+    let hse = std::env::var("STM32_ETH_EXAMPLE_HSE");
+
+    if let Ok(hse) = hse {
+        if hse == "bypass" {
+            println!("cargo:rustc-cfg=hse=\"bypass\"")
+        } else if hse == "oscillator" {
+            println!("cargo:rustc-cfg=hse=\"oscillator\"");
+        } else if hse != "off" {
+            panic!("Invalid STM32_ETH_EXAMPLE_HSE value. Allowed values: bypass, oscillator, off")
+        }
+    }
+
+    let example_pins = std::env::var("STM32_ETH_EXAMPLE_PINS");
+
+    if let Ok(pins) = example_pins {
+        if pins == "nucleo" {
+            println!("cargo:rustc-cfg=pins=\"nucleo\"")
+        } else if pins != "default" {
+            panic!("Invalid STM32_ETH_EXAMPLE_PINS value. Allowed values: nucleo, default");
+        }
+    }
+
+    println!("cargo:rerun-if-env-changed=STM32_ETH_EXAMPLE_HSE");
+    println!("cargo:rerun-if-env-changed=STM32_ETH_EXAMPLE_PINS");
 }

examples/common.rs

@@ -36,7 +36,37 @@ pub fn setup_peripherals(p: stm32_eth::stm32::Peripherals) -> (Clocks, Gpio, Eth
     {
         let rcc = p.RCC.constrain();
 
-        let clocks = rcc.cfgr.sysclk(100.MHz()).hclk(100.MHz()).freeze();
+        let clocks = rcc.cfgr.sysclk(100.MHz()).hclk(100.MHz());
+
+        #[cfg(feature = "stm32f4xx-hal")]
+        let clocks = {
+            if cfg!(hse = "bypass") {
+                clocks.use_hse(8.MHz()).bypass_hse_oscillator()
+            } else if cfg!(hse = "oscillator") {
+                clocks.use_hse(8.MHz())
+            } else {
+                clocks
+            }
+        };
+
+        #[cfg(feature = "stm32f7xx-hal")]
+        let clocks = {
+            if cfg!(hse = "bypass") {
+                clocks.hse(stm32_eth::hal::rcc::HSEClock::new(
+                    8.MHz(),
+                    stm32_eth::hal::rcc::HSEClockMode::Bypass,
+                ))
+            } else if cfg!(hse = "oscillator") {
+                clocks.hse(stm32_eth::hal::rcc::HSEClock::new(
+                    8.MHz(),
+                    stm32_eth::hal::rcc::HSEClockMode::Oscillator,
+                ))
+            } else {
+                clocks
+            }
+        };
+
+        let clocks = clocks.freeze();
 
         let gpio = Gpio {
             gpioa: p.GPIOA.split(),
@@ -55,11 +85,15 @@ pub fn setup_peripherals(p: stm32_eth::stm32::Peripherals) -> (Clocks, Gpio, Eth
         let rcc = p.RCC.constrain();
         let mut flash = p.FLASH.constrain();
 
-        let clocks = rcc
-            .cfgr
-            .sysclk(72.MHz())
-            .hclk(72.MHz())
-            .freeze(&mut flash.acr);
+        let clocks = rcc.cfgr.sysclk(72.MHz()).hclk(72.MHz());
+
+        let clocks = if cfg!(hse = "bypass") || cfg!(hse = "oscillator") {
+            clocks.use_hse(8.MHz())
+        } else {
+            clocks
+        };
+
+        let clocks = clocks.freeze(&mut flash.acr);
 
         let gpio = Gpio {
             gpioa: p.GPIOA.split(),
@@ -90,14 +124,14 @@ mod pins {
     pub type RxD0 = PC4<Input>;
     pub type RxD1 = PC5<Input>;
 
-    #[cfg(not(feature = "example-nucleo-pins"))]
+    #[cfg(not(pins = "nucleo"))]
     pub type TxEn = PB11<Input>;
-    #[cfg(not(feature = "example-nucleo-pins"))]
+    #[cfg(not(pins = "nucleo"))]
     pub type TxD0 = PB12<Input>;
 
-    #[cfg(all(feature = "example-nucleo-pins"))]
+    #[cfg(pins = "nucleo")]
     pub type TxEn = PG11<Input>;
-    #[cfg(feature = "example-nucleo-pins")]
+    #[cfg(pins = "nucleo")]
     pub type TxD0 = PG13<Input>;
 
     pub type Mdio = PA2<Alternate<11>>;
@@ -124,13 +158,13 @@ mod pins {
         let rx_d0 = gpioc.pc4.into_floating_input();
         let rx_d1 = gpioc.pc5.into_floating_input();
 
-        #[cfg(not(feature = "example-nucleo-pins"))]
+        #[cfg(not(pins = "nucleo"))]
         let (tx_en, tx_d0) = (
             gpiob.pb11.into_floating_input(),
             gpiob.pb12.into_floating_input(),
         );
 
-        #[cfg(feature = "example-nucleo-pins")]
+        #[cfg(pins = "nucleo")]
         let (tx_en, tx_d0) = {
             (
                 gpiog.pg11.into_floating_input(),

examples/ip.rs

@@ -3,8 +3,8 @@
 
 //! For build and run instructions, see README.md
 //!
-//! This example starts a TCP listening server that should transmit `Hello` to
-//! any connecting client, and then close the connection.
+//! This example starts a TCP listening server at the address 10.0.0.1/24, on port 80, that
+//!  should transmit `Hello` to any connecting client, and then close the connection.
 
 use defmt_rtt as _;
 use panic_probe as _;
@@ -78,33 +78,40 @@ fn main() -> ! {
     );
     let server_handle = iface.add_socket(server_socket);
 
-    defmt::info!("Ready, listening at {}", ip_addr);
     loop {
         let time: u64 = cortex_m::interrupt::free(|cs| *TIME.borrow(cs).borrow());
         cortex_m::interrupt::free(|cs| {
             let mut eth_pending = ETH_PENDING.borrow(cs).borrow_mut();
             *eth_pending = false;
         });
-        match iface.poll(Instant::from_millis(time as i64)) {
-            Ok(true) => {
-                let socket = iface.get_socket::<TcpSocket>(server_handle);
-                if !socket.is_open() {
-                    if let Err(e) = socket.listen(80) {
-                        defmt::error!("TCP listen error: {:?}", e)
-                    }
-                }
 
-                if socket.can_send() {
-                    if let Err(e) = socket.send_slice(b"hello\n").map(|_| socket.close()) {
-                        defmt::info!("TCP send error: {:?}", e);
+        iface.poll(Instant::from_millis(time as i64)).ok();
+
+        let socket = iface.get_socket::<TcpSocket>(server_handle);
+
+        if !socket.is_listening() && !socket.is_open() {
+            socket.abort();
+            if let Err(e) = socket.listen(80) {
+                defmt::error!("TCP listen error: {:?}", e)
+            } else {
+                defmt::info!("Listening at {}:80...", ip_addr);
+            }
+        } else {
+            match socket.send_slice(b"hello\n") {
+                Ok(_) => {
+                    while iface.get_socket::<TcpSocket>(server_handle).send_queue() != 0 {
+                        // Poll to get the message out of the door
+                        iface.poll(Instant::from_millis(time as i64 + 1)).ok();
                     }
+
+                    // Abort the connection
+                    let socket = iface.get_socket::<TcpSocket>(server_handle);
+                    socket.abort();
+                    defmt::info!("Transmitted hello! Closing socket...");
+
+                    iface.poll(Instant::from_millis(time as i64 + 1)).ok();
                 }
-            }
-            Ok(false) => {}
-            Err(e) =>
-            // Ignore malformed packets
-            {
-                defmt::info!("Error: {:?}", e);
+                Err(_) => {}
             }
         }
     }