Make changes to support HitL testing.

.github/workflows/hil-circuitpython.yml

@@ -0,0 +1,142 @@
+#
+
+name: HIL-circuitpython
+
+on:
+  pull_request:
+    branches: [ main ]
+    paths:
+      # This is quite a big job so run only when files affecting it change.
+      - .github/workflows/hil-circuitpython.yml
+      - examples/notecard-basics/cpy_example.py
+      - test/hitl/**
+      - test/scripts/usbmount
+      - test/scripts/check_cpy*.*
+      - notecard/**
+
+  workflow_dispatch:
+    inputs:
+      flash_device:
+        required: false
+        type: boolean
+        default: true
+
+jobs:
+  test:
+    runs-on: [self-hosted, linux, circuitpython, swan-3.0, notecard-serial]
+    defaults:
+      run:
+        shell: bash
+    strategy:
+      matrix:
+        CIRCUITPYTHON_VERSION: [8.2.2]
+        flash_device: # has to be an array - use the input from workflow_dispatch if present, otherwlse true
+            - ${{ github.event.inputs.flash_device=='' && true || github.event.inputs.flash_device }}
+        lock_cpy_filesystem: [true]
+    env:
+      USB_MSD_ATTACH_TIME: 15
+      CIRCUITPYTHON_UF2: "adafruit-circuitpython-swan_r5-en_US-${{ matrix.CIRCUITPYTHON_VERSION }}.uf2"
+      CIRCUITPYTHON_VERSION: ${{ matrix.CIRCUITPYTHON_VERSION}}
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v3
+
+      - name: Set Env Vars
+        run: |
+          # environment variables set in a step cannot be used until subsequent steps
+          echo "CIRCUITPYTHON_UF2_URL=https://downloads.circuitpython.org/bin/swan_r5/en_US/${CIRCUITPYTHON_UF2}" >> $GITHUB_ENV
+
+      - name: Check Runner Config
+        run: test/scripts/check_cpy_runner_config.sh
+
+      - name: Download Latest Bootloader
+        env:
+          REPO: adafruit/tinyuf2
+          ASSET: tinyuf2-swan_r5
+        if: ${{ matrix.flash_device }}
+        run: |
+          echo "retrieving the latest release from ${REPO}"
+          wget -q -O latest.json "https://api.github.com/repos/${REPO}/releases/latest"
+
+          echo "extracting asset details for ${ASSET}"
+          asset_file="${ASSET}_asset.json"
+          jq -r --arg ASSET "$ASSET" '.assets[] | select(.name | startswith($ASSET))' latest.json > $asset_file
+
+          # extract the name and download url without double quotes
+          download_name=$(jq -r '.name' $asset_file)
+          download_url=$(jq -r '.browser_download_url' $asset_file)
+          echo "Downloading release from $download_url"
+          wget -q -N $download_url
+          unzip -o $download_name
+          binfile=$(basename $download_name .zip).bin
+          echo "TINYUF2_BIN=$binfile" >> $GITHUB_ENV
+
+      - name: Download CircuitPython v${{ env.CIRCUITPYTHON_VERSION }}
+        if: ${{ matrix.flash_device }}
+        run: |
+          echo "Downloading CircuitPython for Swan from $CIRCUITPYTHON_UF2_URL"
+          wget -q -N "$CIRCUITPYTHON_UF2_URL"
+
+      - name: Erase device and program bootloader
+        if: ${{ matrix.flash_device }}
+        run: |
+          # cannot use st-flash - every 2nd programing incorrectly puts the device in DFU mode
+          # st-flash --reset  write $binfile 0x8000000
+          # Have to use the version of openocd bundled with the STM32 platform in PlatformIO, which (presumably) has the stm32 extensions compiled in
+          ~/.platformio/packages/tool-openocd/bin/openocd \
+             -d2 -s ~/.platformio/packages/tool-openocd/openocd/scripts \
+             -f interface/stlink.cfg -c "transport select hla_swd" -f target/stm32l4x.cfg \
+             -c "init; halt; stm32l4x mass_erase 0" \
+             -c "program $TINYUF2_BIN 0x8000000 verify reset; shutdown"
+
+      - name: Program CircuitPython
+        if: ${{ matrix.flash_device }}
+        run: |
+          # wait for the bootloader drive to appear
+          timeout $USB_MSD_ATTACH_TIME bash test/scripts/wait_for_file.sh "$CPY_FS_UF2"
+
+          # The bootloader reboots quickly once the whole file has been received,
+          # causing an input/output error to be reported.
+          # Ignore that, and fail if the CIRCUITPY filesystem doesn't appear
+          echo "Uploading CircuitPython binary..."
+          cp "$CIRCUITPYTHON_UF2" "$CPY_FS_UF2" || true
+          echo Ignore the input/output error above. Waiting for device to boot.
+          timeout $USB_MSD_ATTACH_TIME bash test/scripts/wait_for_file.sh "$CPY_FS_CIRCUITPY"
+          echo "CircuitPython binary uploaded and running."
+
+      - name: Make CircuitPython filesystem writeable to pyboard
+        if: ${{ matrix.lock_cpy_filesystem }}
+        run: |
+          timeout $USB_MSD_ATTACH_TIME bash test/scripts/wait_for_file.sh "$CPY_FS_CIRCUITPY"
+
+          # only copy if it's changed or not present. After the device has reset, no further changes can be made
+          # until the filesystem is erased. This allows the workflow to be rerun flash_device=false
+          diff test/hitl/boot.py "$CPY_FS_CIRCUITPY/boot.py" || test/hitl/boot.py "$CPY_FS_CIRCUITPY"
+
+          # reset the device (todo move this blob to a utility script)
+          ~/.platformio/packages/tool-openocd/bin/openocd \
+          -d2 -s ~/.platformio/packages/tool-openocd/openocd/scripts \
+          -f interface/stlink.cfg -c "transport select hla_swd" -f target/stm32l4x.cfg \
+          -c "init; halt; reset; shutdown"
+
+          # wait for the device to come back
+          timeout $USB_MSD_ATTACH_TIME bash test/scripts/wait_for_file.sh "$CPY_FS_CIRCUITPY"
+
+      - name: Setup Python
+        run: |
+           python3 -m venv .venv-runner
+           . .venv-runner/bin/activate
+           pip install -r test/hitl/requirements.txt
+
+      - name: Setup 'note-python' on device
+        if: ${{ ! matrix.lock_cpy_filesystem }}
+        run: |
+          mkdir -p ${CPY_FS_CIRCUITPY}/lib/notecard
+          cp notecard/*.py ${CPY_FS_CIRCUITPY}/lib/notecard/
+          cp examples/notecard-basics/cpy_example.py ${CPY_FS_CIRCUITPY}/example.py
+
+      - name: Run CircuitPython Tests
+        run: |
+          . .venv-runner/bin/activate
+          ${{ ! matrix.lock_cpy_filesystem }} && skipsetup=--skipsetup
+          pytest $skipsetup "--productuid=$CPY_PRODUCT_UID" "--port=$CPY_SERIAL" --platform=circuitpython test/hitl

.github/workflows/hil-micropython.yml

@@ -0,0 +1,84 @@
+name: HIL-micropython
+
+on:
+  pull_request:
+    branches: [ main ]
+    paths:
+      - .github/workflows/hil-micropython.yml
+      - test/hitl/**
+      - notecard/**
+      - examples/notecard-basics/mpy_example.py
+      - test/scripts/check_mpy*.*
+
+  workflow_dispatch:
+    inputs:
+      flash_device:
+        required: false
+        type: boolean
+        default: true
+
+jobs:
+  huzzah32:
+    runs-on:
+      - self-hosted,
+      - linux,
+      - ${{ matrix.MPY_BOARD }},
+      - notecard-serial,
+      - micropython
+    defaults:
+      run:
+        shell: bash
+    strategy:
+      matrix:
+        MICROPYTHON_VERSION: [1.20.0]
+        MICROPYTHON_DATE: [20230426]
+        MICROPYTHON_MCU: [esp32]
+        MPY_BOARD: [huzzah32]   # the --mpyboard parameter to the tests
+        flash_device: # has to be an array - use the input from workflow_dispatch if present, otherwlse true
+            - ${{ github.event.inputs.flash_device=='' && true || github.event.inputs.flash_device }}
+    env:
+      VENV: .venv-runner-mpy
+      USB_MSD_ATTACH_TIME: 15
+      MICROPYTHON_BIN: "${{matrix.MICROPYTHON_MCU}}-${{matrix.MICROPYTHON_DATE}}-v${{matrix.MICROPYTHON_VERSION}}.bin"
+      MICROPYTHON_VERSION: ${{matrix.MICROPYTHON_VERSION}}
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v3
+
+      - name: Set Env Vars
+        run: |
+          # environment variables set in a step cannot be used until subsequent steps
+          echo "MICROPYTHON_BIN_URL=https://micropython.org/resources/firmware/${{env.MICROPYTHON_BIN}}" >> $GITHUB_ENV
+
+      - name: Check Runner Config
+        run: test/scripts/check_mpy_runner_config.sh
+
+      - name: Download MicroPython v${{ env.MICROPYTHON_VERSION }}
+        if: ${{ matrix.flash_device }}
+        run: |
+          echo "Downloading MicroPython for ESP32 from $MICROPYTHON_BIN_URL"
+          wget -q -N "$MICROPYTHON_BIN_URL"
+
+      - name: Setup Python
+        run: |
+           python3 -m venv ${{ env.VENV }}
+           . ${{ env.VENV }}/bin/activate
+           # esptool installed directly because it's only a dependency of this workflow
+           # while requirements.txt are dependencies of the tests in test/hitl
+           pip install -r test/hitl/requirements.txt esptool
+
+      - name: Erase device and Program Micropython
+        if: ${{ matrix.flash_device }}
+        run: |
+          . ${{ env.VENV }}/bin/activate
+          # esptool requires the flash to be erased first
+          esptool.py --chip esp32 -p ${MPY_SERIAL} erase_flash
+          timeout 10 bash test/scripts/wait_for_file.sh "$MPY_SERIAL"
+
+          esptool.py --chip esp32 --port ${MPY_SERIAL} --baud 460800 write_flash -z 0x1000 ${{ env.MICROPYTHON_BIN }}
+          timeout 10 bash test/scripts/wait_for_file.sh "$MPY_SERIAL"
+
+      - name: Run MicroPython Tests
+        run: |
+          . ${{ env.VENV }}/bin/activate
+          pytest "--productuid=$MPY_PRODUCT_UID" "--port=$MPY_SERIAL" --platform=micropython --mpyboard=${{ matrix.MPY_BOARD }} test/hitl

README.md

@@ -136,11 +136,11 @@ The documentation for this library can be found
 The [examples](examples/) directory contains examples for using this
 library with:
 
-- [Serial](examples/notecard-basics/serial-example.py)
-- [I2C](examples/notecard-basics/i2c-example.py)
-- [RaspberryPi](examples/notecard-basics/rpi-example.py)
-- [CircuitPython](examples/notecard-basics/cpy-example.py)
-- [MicroPython](examples/notecard-basics/mpy-example.py)
+- [Serial](examples/notecard-basics/serial_example.py)
+- [I2C](examples/notecard-basics/i2c_example.py)
+- [RaspberryPi](examples/notecard-basics/rpi_example.py)
+- [CircuitPython](examples/notecard-basics/cpy_example.py)
+- [MicroPython](examples/notecard-basics/mpy_example.py)
 
 ## Contributing
 

examples/notecard-basics/board.py

@@ -0,0 +1,18 @@
+"""
+This module is used by the mpy_example to set define the appropriate peripherals for
+different types of boards. The values here are defaults.
+"""
+
+"""
+The UART instance to use that is connected to Notecard.
+"""
+UART=2
+
+"""
+The SCL pin of the I2C bus connected to Notecard
+"""
+I2C_ID=0
+SCL=0
+SDA=0
+
+

examples/notecard-basics/cpy-example.py → examples/notecard-basics/cpy_example.py

@@ -7,12 +7,7 @@
 import time
 import notecard
 
-productUID = "com.your-company.your-project"
-
-# Choose either UART or I2C for Notecard
-use_uart = True
-
-if sys.implementation.name != 'circuitpython':
+if sys.implementation.name != "circuitpython":
     raise Exception("Please run this example in a CircuitPython environment.")
 
 import board  # noqa: E402
@@ -30,18 +25,18 @@ def NotecardExceptionInfo(exception):
     """
     name = exception.__class__.__name__
     return sys.platform + ": " + name \
-        + ": " + ' '.join(map(str, exception.args))
+        + ": " + " ".join(map(str, exception.args))
 
 
-def configure_notecard(card):
+def configure_notecard(card, product_uid):
     """Submit a simple JSON-based request to the Notecard.
 
     Args:
         card (object): An instance of the Notecard class
 
     """
     req = {"req": "hub.set"}
-    req["product"] = productUID
+    req["product"] = product_uid
     req["mode"] = "continuous"
 
     try:
@@ -76,41 +71,38 @@ def get_temp_and_voltage(card):
     return temp, voltage
 
 
-def main():
+def run_example(product_uid, use_uart=True):
     """Connect to Notcard and run a transaction test."""
     print("Opening port...")
-    try:
-        if use_uart:
-            port = busio.UART(board.TX, board.RX, baudrate=9600)
-        else:
-            port = busio.I2C(board.SCL, board.SDA)
-    except Exception as exception:
-        raise Exception("error opening port: "
-                        + NotecardExceptionInfo(exception))
+    if use_uart:
+        port = busio.UART(board.TX, board.RX, baudrate=9600)
+    else:
+        port = busio.I2C(board.SCL, board.SDA)
 
     print("Opening Notecard...")
-    try:
-        if use_uart:
-            card = notecard.OpenSerial(port, debug=True)
-        else:
-            card = notecard.OpenI2C(port, 0, 0, debug=True)
-    except Exception as exception:
-        raise Exception("error opening notecard: "
-                        + NotecardExceptionInfo(exception))
+    if use_uart:
+        card = notecard.OpenSerial(port, debug=True)
+    else:
+        card = notecard.OpenI2C(port, 0, 0, debug=True)
 
     # If success, configure the Notecard and send some data
-    configure_notecard(card)
+    configure_notecard(card, product_uid)
     temp, voltage = get_temp_and_voltage(card)
 
     req = {"req": "note.add"}
     req["sync"] = True
     req["body"] = {"temp": temp, "voltage": voltage}
 
-    try:
-        card.Transaction(req)
-    except Exception as exception:
-        print("Transaction error: " + NotecardExceptionInfo(exception))
-        time.sleep(5)
+    card.Transaction(req)
+
+    # Developer note: do not modify the line below, as we use this as to signify
+    # that the example ran successfully to completion. We then use that to
+    # determine pass/fail for certain tests that leverage these examples.
+    print("Example complete.")
 
 
-main()
+if __name__ == "__main__":
+    product_uid = "com.your-company.your-project"
+    # Choose either UART or I2C for Notecard
+    use_uart = True
+    run_example(product_uid, use_uart)