From 0023e56eb8b504ee9267005993dad255be18cf3a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20NEDJAR?= Date: Mon, 13 Apr 2026 05:10:49 +0200 Subject: [PATCH 1/2] tooling: Rename firmware targets to micropython-* with deprecation errors. --- .github/workflows/release.yml | 2 +- CONTRIBUTING.md | 24 ++++---- Makefile | 57 ++++++++++++++----- .../examples/calibrate_temperature.py | 4 +- scripts/deploy_usb.py | 2 +- 5 files changed, 59 insertions(+), 30 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index d6fc307e..28d22ebc 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -71,7 +71,7 @@ jobs: sudo apt-get install -y --no-install-recommends gcc-arm-none-eabi libnewlib-arm-none-eabi - name: Build firmware - run: make firmware + run: make micropython-firmware - name: Attach firmware to release env: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3ef6589d..68636a4b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -119,9 +119,9 @@ For local development (without dev container): * Python 3.10+ * Node.js 22+ (for husky, commitlint, lint-staged, semantic-release) -* `arm-none-eabi-gcc` toolchain (for `make firmware`) -* `pyocd` (for `make deploy`, installed via `pip install -e ".[flash]"`) -* OpenOCD (optional, for `make deploy-openocd`) +* `arm-none-eabi-gcc` toolchain (for `make micropython-firmware`) +* `pyocd` (for `make micropython-deploy`, installed via `pip install -e ".[flash]"`) +* OpenOCD (optional, for `make micropython-deploy-openocd`) * `mpremote` (installed via `pip install -e ".[test]"`) * GitHub CLI (`gh`) @@ -191,20 +191,22 @@ make bump PART=major # major: v1.1.0 → v2.0.0 The drivers are "frozen" into the MicroPython firmware for the STeaMi board. The Makefile automates cloning, building, and flashing: ```bash -make firmware # Clone micropython-steami (if needed), link local drivers, build -make firmware-update # Refresh the MicroPython clone and board-specific submodules -make deploy # Flash firmware via pyOCD (default) -make deploy-openocd # Flash firmware via OpenOCD (alternative) -make deploy-usb # Flash firmware via DAPLink USB mass-storage (alternative) +make micropython-firmware # Clone micropython-steami (if needed), link local drivers, build +make micropython-update # Refresh the MicroPython clone and board-specific submodules +make micropython-deploy # Flash firmware via pyOCD (default) +make micropython-deploy-openocd # Flash firmware via OpenOCD (alternative) +make micropython-deploy-usb # Flash firmware via DAPLink USB mass-storage (alternative) +make micropython-clean # Clean MicroPython firmware build artifacts make run SCRIPT=lib/steami_config/examples/show_config.py # Run with live output make deploy-script SCRIPT=lib/.../calibrate_magnetometer.py # Deploy as main.py for autonomous use -make run-main # Re-execute the deployed main.py -make firmware-clean # Clean firmware build artifacts +make run-main # Re-execute main.py on the board ``` +The legacy short names (`make firmware`, `make deploy`, etc.) are deprecated and now print an error message asking which firmware (MicroPython or DAPLink) you intended to target. + The firmware source is cloned into `.build/micropython-steami/` (gitignored). A symbolic link replaces the submodule `lib/micropython-steami-lib` with your local working directory, so the firmware always includes your latest changes — even uncommitted ones. -Use `make firmware` for normal rebuilds from the existing local clone. Use `make firmware-update` only when you want to refresh the `micropython-steami` checkout itself or resync the board-specific submodules before rebuilding. +Use `make micropython-firmware` for normal rebuilds from the existing local clone. Use `make micropython-update` only when you want to refresh the `micropython-steami` checkout itself or resync the board-specific submodules before rebuilding. All these tools are included in the dev container. For local development, see the [Prerequisites](#prerequisites) section. diff --git a/Makefile b/Makefile index d98dc8f5..f374819c 100644 --- a/Makefile +++ b/Makefile @@ -88,7 +88,7 @@ ci: lint test test-examples ## Run all CI checks (lint + tests + examples) .PHONY: build build: lint test ## Build (lint + test) -# --- Firmware --- +# --- MicroPython firmware --- $(MPY_DIR): @echo "Cloning micropython-steami into $(CURDIR)/$(MPY_DIR)..." @@ -96,8 +96,8 @@ $(MPY_DIR): git clone --branch $(MICROPYTHON_BRANCH) $(MICROPYTHON_REPO) $(CURDIR)/$(MPY_DIR) $(MAKE) -C $(STM32_DIR) BOARD=$(BOARD) submodules -.PHONY: firmware -firmware: $(MPY_DIR) ## Build MicroPython firmware with current drivers +.PHONY: micropython-firmware +micropython-firmware: $(MPY_DIR) ## Build MicroPython firmware with current drivers @set -e @if [ ! -f "$(MPY_DIR)/lib/micropython-lib/README.md" ]; then \ echo "Initializing submodules for $(BOARD)..."; \ @@ -111,8 +111,8 @@ firmware: $(MPY_DIR) ## Build MicroPython firmware with current drivers $(MAKE) -C $(STM32_DIR) BOARD=$(BOARD) @echo "Firmware ready: $(STM32_DIR)/build-$(BOARD)/firmware.hex" -.PHONY: firmware-update -firmware-update: $(MPY_DIR) ## Update the MicroPython clone and board-specific submodules +.PHONY: micropython-update +micropython-update: $(MPY_DIR) ## Update the MicroPython clone and board-specific submodules @set -e @echo "Updating micropython-steami..." rm -rf $(CURDIR)/$(MPY_DIR)/lib/micropython-steami-lib @@ -123,21 +123,48 @@ firmware-update: $(MPY_DIR) ## Update the MicroPython clone and board-specific s @echo "Updating required submodules for $(BOARD)..." $(MAKE) -C $(STM32_DIR) BOARD=$(BOARD) submodules -.PHONY: deploy -deploy: deploy-pyocd ## Flash firmware (default: pyocd) +.PHONY: micropython-deploy +micropython-deploy: micropython-deploy-pyocd ## Flash MicroPython firmware (default: pyocd) -.PHONY: deploy-pyocd -deploy-pyocd: $(MPY_DIR) ## Flash firmware via pyOCD (CMSIS-DAP) +.PHONY: micropython-deploy-pyocd +micropython-deploy-pyocd: $(MPY_DIR) ## Flash MicroPython firmware via pyOCD (CMSIS-DAP) $(PYTHON) -m pyocd flash $(STM32_DIR)/build-$(BOARD)/firmware.elf --format elf -.PHONY: deploy-openocd -deploy-openocd: $(MPY_DIR) ## Flash firmware via OpenOCD +.PHONY: micropython-deploy-openocd +micropython-deploy-openocd: $(MPY_DIR) ## Flash MicroPython firmware via OpenOCD $(MAKE) -C $(STM32_DIR) BOARD=$(BOARD) deploy-openocd -.PHONY: deploy-usb -deploy-usb: $(MPY_DIR) ## Flash firmware via DAPLink USB mass-storage +.PHONY: micropython-deploy-usb +micropython-deploy-usb: $(MPY_DIR) ## Flash MicroPython firmware via DAPLink USB mass-storage @$(PYTHON) scripts/deploy_usb.py $(STM32_DIR)/build-$(BOARD)/firmware.bin +# --- Deprecated targets (ambiguous since DAPLink build is also planned) --- +# Replaced by explicit micropython-* / daplink-* targets to avoid confusion +# about which firmware is being built or flashed. + +define DEPRECATED_FIRMWARE +@echo "Error: 'make $(1)' is ambiguous. Use one of:"; \ +echo " make micropython-$(2) (MicroPython firmware)"; \ +echo " make daplink-$(2) (DAPLink firmware, see #377)"; \ +exit 1 +endef + +.PHONY: firmware firmware-update firmware-clean deploy deploy-pyocd deploy-openocd deploy-usb +firmware: + $(call DEPRECATED_FIRMWARE,firmware,firmware) +firmware-update: + $(call DEPRECATED_FIRMWARE,firmware-update,update) +firmware-clean: + $(call DEPRECATED_FIRMWARE,firmware-clean,clean) +deploy: + $(call DEPRECATED_FIRMWARE,deploy,deploy) +deploy-pyocd: + $(call DEPRECATED_FIRMWARE,deploy-pyocd,deploy-pyocd) +deploy-openocd: + $(call DEPRECATED_FIRMWARE,deploy-openocd,deploy-openocd) +deploy-usb: + $(call DEPRECATED_FIRMWARE,deploy-usb,deploy-usb) + .PHONY: run run: ## Run a script on the board with live output (SCRIPT=path/to/file.py) @if [ -z "$(SCRIPT)" ]; then \ @@ -158,8 +185,8 @@ deploy-script: ## Deploy a script as main.py for autonomous execution (SCRIPT=pa run-main: ## Re-execute main.py on the board and capture output $(PYTHON) -m mpremote connect $(PORT) exec "exec(open('/flash/main.py').read())" -.PHONY: firmware-clean -firmware-clean: ## Clean firmware build artifacts +.PHONY: micropython-clean +micropython-clean: ## Clean MicroPython firmware build artifacts @if [ -d "$(STM32_DIR)" ]; then \ $(MAKE) -C $(STM32_DIR) BOARD=$(BOARD) clean; \ fi diff --git a/lib/steami_config/examples/calibrate_temperature.py b/lib/steami_config/examples/calibrate_temperature.py index 19bfe91c..4f835b50 100644 --- a/lib/steami_config/examples/calibrate_temperature.py +++ b/lib/steami_config/examples/calibrate_temperature.py @@ -5,8 +5,8 @@ config zone and survive power cycles. Note: this example assumes the drivers are frozen into the firmware. -Use ``make firmware && make deploy`` to build a firmware with the -latest drivers before running this script. +Use ``make micropython-firmware && make micropython-deploy`` to build a +firmware with the latest drivers before running this script. """ from time import sleep_ms diff --git a/scripts/deploy_usb.py b/scripts/deploy_usb.py index efb94b2b..93a2afda 100644 --- a/scripts/deploy_usb.py +++ b/scripts/deploy_usb.py @@ -139,7 +139,7 @@ def main(): firmware = sys.argv[1] if not os.path.isfile(firmware): print("Error: firmware binary not found: " + firmware, file=sys.stderr) - print("Run 'make firmware' first.", file=sys.stderr) + print("Run 'make micropython-firmware' first.", file=sys.stderr) sys.exit(1) mount = find_steami() From b725ab9c577c3592526652617e173a0d33b1b9f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20NEDJAR?= Date: Mon, 13 Apr 2026 05:16:01 +0200 Subject: [PATCH 2/2] docs: Disambiguate firmware references (MicroPython vs DAPLink). --- .devcontainer/Dockerfile | 2 +- .devcontainer/devcontainer.json | 2 +- CONTRIBUTING.md | 19 ++++++++++++------- lib/steami_config/README.md | 4 ++-- lib/wsen-hids/README.md | 2 +- 5 files changed, 17 insertions(+), 12 deletions(-) diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index cfc412a3..ca3a52eb 100644 --- a/.devcontainer/Dockerfile +++ b/.devcontainer/Dockerfile @@ -1,6 +1,6 @@ FROM mcr.microsoft.com/devcontainers/python:3.10 -# System packages for firmware build and board communication +# System packages for MicroPython firmware build and board communication RUN apt-get update && apt-get install -y --no-install-recommends \ gcc-arm-none-eabi \ libnewlib-arm-none-eabi \ diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 6698cad7..34f6fe07 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -5,7 +5,7 @@ }, // USB access for STeaMi board (DAPLink / mpremote / pyOCD / OpenOCD). - // Privileged mode is required for firmware flashing and board communication. + // Privileged mode is required for MicroPython firmware flashing and board communication. // This is incompatible with GitHub Codespaces but essential for local use. "privileged": true, "mounts": ["type=bind,source=/dev/bus/usb,target=/dev/bus/usb"], diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 68636a4b..1b4593d9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -140,7 +140,7 @@ The container also provides: * **zsh + oh-my-zsh** as default shell with persistent shell history * **Pylance** configured with MicroPython STM32 stubs (no false `import machine` errors) * **Serial Monitor** extension for board communication -* **USB passthrough** for mpremote, pyOCD, OpenOCD, and firmware flashing (the container runs in privileged mode with `/dev/bus/usb` mounted) +* **USB passthrough** for mpremote, pyOCD, OpenOCD, and MicroPython firmware flashing (the container runs in privileged mode with `/dev/bus/usb` mounted) * **udev rules** for the DAPLink interface (auto-started on container creation) Note: GitHub Codespaces is not supported because the container requires privileged mode and USB device access for board communication. @@ -186,16 +186,21 @@ make bump PART=minor # minor: v1.0.1 → v1.1.0 make bump PART=major # major: v1.1.0 → v2.0.0 ``` -## Firmware build and deploy +## MicroPython firmware build and deploy -The drivers are "frozen" into the MicroPython firmware for the STeaMi board. The Makefile automates cloning, building, and flashing: +The STeaMi board has two distinct firmwares: + +- **MicroPython firmware** — runs on the STM32WB55 main MCU and exposes the drivers from this repository +- **DAPLink firmware** — runs on the STM32F103 interface chip and provides the I2C bridge, mass-storage, and CMSIS-DAP debug interface (build targets planned in #377) + +This section covers the **MicroPython firmware** only. The drivers in this repository are "frozen" into it. The Makefile automates cloning, building, and flashing: ```bash make micropython-firmware # Clone micropython-steami (if needed), link local drivers, build make micropython-update # Refresh the MicroPython clone and board-specific submodules -make micropython-deploy # Flash firmware via pyOCD (default) -make micropython-deploy-openocd # Flash firmware via OpenOCD (alternative) -make micropython-deploy-usb # Flash firmware via DAPLink USB mass-storage (alternative) +make micropython-deploy # Flash MicroPython firmware via pyOCD (default) +make micropython-deploy-openocd # Flash MicroPython firmware via OpenOCD (alternative) +make micropython-deploy-usb # Flash MicroPython firmware via DAPLink USB mass-storage (alternative) make micropython-clean # Clean MicroPython firmware build artifacts make run SCRIPT=lib/steami_config/examples/show_config.py # Run with live output make deploy-script SCRIPT=lib/.../calibrate_magnetometer.py # Deploy as main.py for autonomous use @@ -204,7 +209,7 @@ make run-main # Re-execute main.py on the board The legacy short names (`make firmware`, `make deploy`, etc.) are deprecated and now print an error message asking which firmware (MicroPython or DAPLink) you intended to target. -The firmware source is cloned into `.build/micropython-steami/` (gitignored). A symbolic link replaces the submodule `lib/micropython-steami-lib` with your local working directory, so the firmware always includes your latest changes — even uncommitted ones. +The MicroPython firmware source is cloned into `.build/micropython-steami/` (gitignored). A symbolic link replaces the submodule `lib/micropython-steami-lib` with your local working directory, so the firmware always includes your latest changes — even uncommitted ones. Use `make micropython-firmware` for normal rebuilds from the existing local clone. Use `make micropython-update` only when you want to refresh the `micropython-steami` checkout itself or resync the board-specific submodules before rebuilding. diff --git a/lib/steami_config/README.md b/lib/steami_config/README.md index 42f0cafd..bc0fb737 100644 --- a/lib/steami_config/README.md +++ b/lib/steami_config/README.md @@ -3,8 +3,8 @@ Persistent configuration module for the STeaMi board. Configuration data (board info, sensor calibration) is stored as compact JSON -in the STM32F103 internal flash config zone (1 KB) and survives firmware -updates and `clear_flash` operations. +in the STM32F103 internal flash config zone (1 KB) and survives MicroPython +firmware updates and `clear_flash` operations. --- diff --git a/lib/wsen-hids/README.md b/lib/wsen-hids/README.md index 94f68765..92017f75 100644 --- a/lib/wsen-hids/README.md +++ b/lib/wsen-hids/README.md @@ -308,4 +308,4 @@ The `examples/` directory provides practical scripts demonstrating how to use th | `data_logger.py` | Log data every 5 seconds in CSV format (`timestamp, humidity, temperature`) for serial capture | | `dew_point.py` | Compute and display dew point using temperature and humidity (Magnus formula) | | `heater_demo.py` | Demonstrate the built-in heater: compare readings before and after enabling it | -| `low_power_sampling.py` | Low-power sampling: one-shot every 10 s with `power_off()` between reads. Requires firmware >= v0.1.0 (#238) | +| `low_power_sampling.py` | Low-power sampling: one-shot every 10 s with `power_off()` between reads. Requires MicroPython firmware >= v0.1.0 (#238) |