Add Wokwi support (VS Code and browser)

.devcontainer/Dockerfile

@@ -7,7 +7,7 @@ ENV LC_ALL=C.UTF-8
 ENV LANG=C.UTF-8
 ARG CONTAINER_USER=esp
 ARG CONTAINER_GROUP=esp
-ARG NIGHTLY_VERSION=nightly-2023-06-25
+ARG NIGHTLY_VERSION=nightly-2023-11-14
 ARG ESP_BOARD=esp32c3
 
 RUN apt-get update \

.devcontainer/devcontainer.json

@@ -6,7 +6,7 @@
     "build": {
         "dockerfile": "Dockerfile",
         "args": {
-            "NIGHTLY_VERSION": "nightly-2023-06-25"
+            "NIGHTLY_VERSION": "nightly-2023-11-14"
         }
     },
     "customizations": {

.github/blinky.test.yaml

@@ -0,0 +1,16 @@
+name: blinky test
+version: 1
+author: Sergio Gasquez Arcos
+
+steps:
+  - wait-serial: "Hello world!"
+  - delay: 100ms
+  - expect-pin:
+      part-id: esp
+      pin: 7
+      value: 0
+  - delay: 550ms
+  - expect-pin:
+      part-id: esp
+      pin: 7
+      value: 1

.github/button-interrupt.test.yaml

@@ -0,0 +1,17 @@
+name: button-interrupt test
+version: 1
+author: Sergio Gasquez Arcos
+
+steps:
+        - wait-serial: "Hello world!"
+        # Press once
+        - set-control:
+                  part-id: btn1
+                  control: pressed
+                  value: 0
+        - delay: 100ms
+        - set-control:
+                  part-id: btn1
+                  control: pressed
+                  value: 1
+        - wait-serial: "GPIO interrupt"

.github/button.test.yaml

@@ -0,0 +1,26 @@
+name: button test
+version: 1
+author: Sergio Gasquez Arcos
+
+steps:
+  - wait-serial: "Hello world!"
+  - delay: 100ms
+  # Press once
+  - set-control:
+      part-id: btn1
+      control: pressed
+      value: 1
+  - delay: 50ms
+  - expect-pin:
+      part-id: esp
+      pin: 7
+      value: 0
+  - set-control:
+      part-id: btn1
+      control: pressed
+      value: 0
+  - delay: 50ms
+  - expect-pin:
+      part-id: esp
+      pin: 7
+      value: 1

.github/hello-world.test.yaml

@@ -0,0 +1,6 @@
+name: hello-world test
+version: 1
+author: Sergio Gasquez Arcos
+
+steps:
+  - wait-serial: "Hello world!"

.github/http-client.test.yaml

@@ -0,0 +1,9 @@
+name: http-client test
+version: 1
+author: Sergio Gasquez Arcos
+
+steps:
+    - wait-serial: "Wait to get connected"
+    - wait-serial: "Wait to get an ip address"
+    - wait-serial: "Making HTTP request"
+    - wait-serial: "< Hello fellow Rustaceans! >"

.github/panic.test.yaml

@@ -0,0 +1,6 @@
+name: panic test
+version: 1
+author: Sergio Gasquez Arcos
+
+steps:
+    - wait-serial: "!! A panic occured in "

.github/stack-overflow-detection.test.yaml

@@ -0,0 +1,7 @@
+name: stack-overflow-detection test
+version: 1
+author: Sergio Gasquez Arcos
+
+steps:
+    - wait-serial: "Safe stack"
+    - wait-serial: "Possible Stack Overflow Detected"

.github/workflows/ci.yml

@@ -3,21 +3,27 @@ name: CI
 on:
   push:
     paths-ignore:
+      - "book/"
+      - "book/**"
       - "**/README.md"
+      - ".github/workflows/wokwi_projects.yml"
   pull_request:
     paths-ignore:
+      - "book/"
+      - "book/**"
       - "**/README.md"
+      - ".github/workflows/wokwi_projects.yml"
   schedule:
     - cron: "50 7 * * *"
 
 env:
   CARGO_TERM_COLOR: always
-  SSID: ssid
-  PASSWORD: password
+  SSID: Wokwi-GUEST
+  PASSWORD: ""
 
 jobs:
   hello-world:
-    name: intro/hello-world
+    name: hello-world
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -31,14 +37,35 @@ jobs:
       - run: cargo build --release
         working-directory: intro/hello-world
 
+      - name: Wokwi CI check
+        if: github.actor == 'esp-rs'
+        uses: wokwi/wokwi-ci-action@v1
+        with:
+          token: ${{ secrets.WOKWI_CLI_TOKEN }}
+          path: intro/hello-world
+          timeout: 30000
+          scenario: ${{ github.workspace }}/.github/hello-world.test.yaml
+          fail_text: 'Error'
+
   examples:
-    name: ${{ matrix.project }}
+    name: ${{ matrix.project.name }}
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
         project:
-          ["intro/blinky", "intro/button", "intro/button-interrupt", "intro/hello-world", "intro/panic", "intro/http-client", "advanced/stack_overflow_detection"]
+          - name: "blinky"
+            path: "intro/blinky"
+          - name: "button"
+            path: "intro/button"
+          - name: "button-interrupt"
+            path: "intro/button-interrupt"
+          - name: "panic"
+            path: "intro/panic"
+          - name: "http-client"
+            path: "intro/http-client"
+          - name: "stack-overflow-detection"
+            path: "advanced/stack-overflow-detection"
     steps:
       - uses: actions/checkout@v4
 
@@ -49,4 +76,14 @@ jobs:
           components: rust-src
 
       - run: cargo build --release --examples
-        working-directory: ${{ matrix.project }}
+        working-directory: ${{ matrix.project.path }}
+
+      - name: Wokwi CI check
+        if: matrix.project.name != 'stack-overflow-detection' && github.actor == 'esp-rs'
+        uses: wokwi/wokwi-ci-action@v1
+        with:
+          token: ${{ secrets.WOKWI_CLI_TOKEN }}
+          path: ${{ matrix.project.path }}
+          timeout: 30000
+          scenario: ${{ github.workspace }}/.github/${{ matrix.project.name }}.test.yaml
+          fail_text: 'Error'

.github/workflows/wokwi_projects.yml

@@ -0,0 +1,91 @@
+---
+name: Wokwi.com CI
+
+on:
+  push:
+    paths:
+      - '.github/workflows/wokwi_projects.yml'
+  pull_request:
+    paths:
+      - '.github/workflows/wokwi_projects.yml'
+  schedule:
+    - cron: "50 7 * * *"
+  workflow_dispatch:
+
+jobs:
+  wokwi-check:
+    name: ${{ matrix.project.name }}
+    if: github.actor == 'esp-rs'
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        project:
+          # - name: "hello-world"
+          #   id: "382725628217620481"
+          #   path: "intro/hello-world"
+          - name: blinky
+            id: "382725482391094273"
+            path: "intro/blinky"
+          - name: button
+            id: "382725583123606529"
+            path: "intro/button"
+          - name: button-interrupt
+            id: "382723722184136705"
+            path: "intro/button-interrupt"
+          - name: panic
+            id: "382726300037178369"
+            path: "intro/panic"
+
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@v4
+
+      - name: Download project code
+        run: |
+          wget -q -O ${{ matrix.project.name }}.zip  https://wokwi.com/api/projects/${{ matrix.project.id }}/zip
+          unzip ${{ matrix.project.name }}.zip -d ${{ matrix.project.name }}
+          mkdir -p ${{ matrix.project.name }}/src
+          rm -rf ${{ matrix.project.path }}/src/*.rs
+          cp ${{ matrix.project.name }}/*.rs ${{ matrix.project.path }}/src/
+          rm -rf ${{ matrix.project.path }}/Cargo.toml
+          cp ${{ matrix.project.name }}/Cargo.toml ${{ matrix.project.path }}/Cargo.toml
+
+      - name: Create wokwi.toml
+        run: echo -e "[wokwi]\nversion = 1\nfirmware = '${{ matrix.project.name }}/${{ matrix.project.name }}'\nelf = '${{ matrix.project.name }}/${{ matrix.project.name }}'" > ${{ matrix.project.path }}/wokwi.toml
+
+      - name: Update ownership
+        run: |
+          sudo chown 1000:1000 -R ${{ matrix.project.path }}
+
+      - name: Pull Docker image
+        run: docker image pull espressif/idf-rust:esp32c3_latest
+
+      - name: Test code example in Docker image
+        uses: addnab/docker-run-action@v3
+        with:
+          image: espressif/idf-rust:esp32c3_latest
+          options: -u esp -v ${{ github.workspace }}:/home/esp/workspace
+          run: |
+            cd /home/esp/workspace/${{ matrix.project.path }}
+            export SSID="Wokwi-GUEST" && export PASSWORD=""
+            /home/esp/.cargo/bin/cargo build --release --out-dir /home/esp/workspace/${{ matrix.project.path }}/${{ matrix.project.name }} -Z unstable-options
+            rm -rf /home/esp/workspace/${{ matrix.project.path }}/target
+
+      - run: cat ${{ matrix.project.path }}/wokwi.toml
+
+      - name: Wokwi CI check
+        uses: wokwi/wokwi-ci-action@v1
+        with:
+          token: ${{ secrets.WOKWI_CLI_TOKEN }}
+          path: ${{ matrix.project.path }}
+          timeout: 30000
+          scenario: ${{ github.workspace }}/.github/${{ matrix.project.name }}.test.yaml
+          fail_text: 'Error'
+
+      - name: Upload source code
+        if: success() || failure()
+        uses: actions/upload-artifact@v3
+        with:
+          name: ${{ matrix.project.name }}_${{ matrix.project.id }}
+          path: ${{ matrix.project.path }}

advanced/stack_overflow_detection/Cargo.toml → advanced/stack-overflow-detection/Cargo.toml

@@ -1,5 +1,5 @@
 [package]
-name = "stack_overflow_protection"
+name = "stack-overflow-detection"
 version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"

advanced/stack-overflow-detection/diagram.json

@@ -0,0 +1,33 @@
+{
+    "version": 1,
+    "author": "Sergio Gasquez Arcos",
+    "editor": "wokwi",
+    "parts": [
+        {
+            "type": "board-esp32-c3-rust-1",
+            "id": "esp",
+            "top": -126.57,
+            "left": 46.35,
+            "attrs": {
+                "builder": "rust-nostd-esp"
+            }
+        }
+    ],
+    "connections": [
+        [
+            "esp:21",
+            "$serialMonitor:RX",
+            "",
+            []
+        ],
+        [
+            "esp:20",
+            "$serialMonitor:TX",
+            "",
+            []
+        ]
+    ],
+    "serialMonitor": {
+        "display": "auto"
+    }
+}

advanced/stack_overflow_detection/rust-toolchain.toml → advanced/stack-overflow-detection/rust-toolchain.toml

@@ -1,4 +1,4 @@
 [toolchain]
-channel = "nightly-2023-06-25"
+channel = "nightly-2023-11-14"
 components = ["rust-src"]
 targets = ["riscv32imc-unknown-none-elf"]

advanced/stack-overflow-detection/wokwi.toml

@@ -0,0 +1,9 @@
+[wokwi]
+version = 1
+# Exercise
+# firmware = "target/riscv32imc-unknown-none-elf/release/stack_overflow_detection"
+# elf = "target/riscv32imc-unknown-none-elf/release/stack_overflow_detection"
+
+# Solution
+firmware = 'target/riscv32imc-unknown-none-elf/release/examples/stack-overflow-detection'
+elf = 'target/riscv32imc-unknown-none-elf/release/examples/stack-overflow-detection'

book/src/02_0_preparations.md

@@ -2,7 +2,7 @@
 
 This chapter contains information about the course material, the required hardware, and an installation guide.
 
-## Icons and Formatting we use
+## Icons and Formatting We Use
 
 We use Icons to mark different kinds of information in the book:
 * ✅ Call for action.
@@ -31,6 +31,20 @@ Anchor comments can be ignored, they are only used to introduce those parts of c
 
 > No additional debugger/probe hardware is required.
 
-## Companion material
+## Simulating Projects
+
+Certain projects can be simulated with [Wokwi][wokwi]. Look for indications in the book to identify projects available for simulation. Simulation can be accomplished through two methods:
+- Using wokwi.com: Conduct the build process and code editing directly through the browser.
+- Using [Wokwi VS Code extension][wokwi-vscode]: Leverage VS Code to edit projects and perform builds. Utilize the Wokwi VS Code extension to simulate the resulting binaries.
+    - This approach requires some [installation][wokwi-installation]
+    - This approach assumes that the project is built in debug mode
+    - This approach allows [debugging the project][wokwi-debug]
+
+[wokwi]: https://wokwi.com/
+[wokwi-vscode]: https://docs.wokwi.com/vscode/getting-started
+[wokwi-installation]: https://docs.wokwi.com/vscode/getting-started#installation
+[wokwi-debug]: https://docs.wokwi.com/vscode/debugging
+
+## Companion Material
 
 - [Official esp-rs book](https://esp-rs.github.io/book/introduction.html)