From c596f0db80b282129b1e731dbf6888bd29f7417f Mon Sep 17 00:00:00 2001 From: Jordan Williams Date: Sat, 16 Nov 2024 16:04:14 -0600 Subject: [PATCH 1/3] Document the wiring and improve the pico probe documentation --- boards/pico/README.adoc | 174 +++++++++++++++++++++++------- boards/qt-py-ch32v203/README.adoc | 48 ++++++++- 2 files changed, 178 insertions(+), 44 deletions(-) diff --git a/boards/pico/README.adoc b/boards/pico/README.adoc index 5e968e2..c848ec6 100644 --- a/boards/pico/README.adoc +++ b/boards/pico/README.adoc @@ -15,9 +15,10 @@ endif::[] :flip-link: https://github.com/knurling-rs/flip-link[flip-link] :Git: https://git-scm.com/[Git] :Noctua-NF-P12-redux-1700-PWM-Fan: https://noctua.at/en/nf-p12-redux-1700-pwm[Noctua NF-P12 redux-1700 PWM Fan] -:Picoprobe-Wiring: https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf[Picoprobe Wiring] +:Picoprobe-Wiring: https://github.com/rgrr/yapicoprobe?tab=readme-ov-file#probe--target-wiring[Picoprobe Wiring] :PicoProbe-PCB-kit: https://shop.pimoroni.com/products/picoprobe-pcb-kit?variant=39954095472723[PicoProbe PCB kit] :probe-rs: https://probe.rs/[probe-rs] +:Raspberry-Pi-3-pin-Debug-Connector-Specification: https://datasheets.raspberrypi.com/debug/debug-connector-specification.pdf[Raspberry Pi 3-pin Debug Connector Specification] :Raspberry-Pi-Pico: https://www.raspberrypi.com/products/raspberry-pi-pico/[Raspberry Pi Pico] :Raspberry-Pi-Debug-Probe: https://www.raspberrypi.com/documentation/microcontrollers/debug-probe.html[Raspberry Pi Debug Probe] :rp-hal: https://github.com/rp-rs/rp-hal[rp-hal] @@ -89,6 +90,48 @@ I use the 74AHCT125 to perform the logic-level conversion, using pin #40, `VBUS` The Raspberry Pi Pico draws 1.99 mA of current in this particular configuration. +=== Wiring + +The 74AHCT125 is wired as shown in the <<74AHCT125 Wiring>> table. +All pins omitted from the table are connected to ground. + +.74AHCT125 Wiring +[cols="1,4"] +|=== +| 74AHCT125 | Signal + +| 1 +| 3.3 Volt power + +| 9 +| 3.3 Volt PWM input signal + +| 10 +| 5 Volt PWM output signal +|=== + +The output signal from the logic-level shifter is sent through the 1N4001 power blocking diode to the fan header. +The pins on the 4-pin fan header are classified in the <<4-pin Fan Header Pinout>> table. +The pins are numbered one through four from left to right with the pins reaching upwards and the overhang positioned between the viewer and the pins. + +.4-pin Fan Header Pinout +[cols="1,4"] +|=== +| Fan Header Pin | Signal + +| 1 +| GND + +| 2 +| +12VDC + +| 3 +| Sense + +| 4 +| Control +|=== + == Getting Started . Change to the board's directory. @@ -109,26 +152,25 @@ To mount `/dev/sda1`, as in my case, use the `udisksctl` command like so. udisksctl mount --block-device /dev/sda1 ---- +. Double check that link:.cargo/config.toml[.cargo/config.toml] has the runner set to `elf2uf2-rs -d`. + . Flash the board using the `nix run` command with the `pico.flash.elf2uf2-rs` target. + [,sh] ---- -nix run '../..#pico.flash.elf2uf2-rs' +nix run ../..#pico.flash.elf2uf2-rs ---- -// == Develop - -// . Double check that link:.cargo/config.toml[.cargo/config.toml] has the runner set to `elf2uf2-rs -d`. - == Probe +The `UF2` method is handy for programming microcontrollers without requiring any additional hardware. +However, debug probes are quite convenient for flashing and debugging code running on the microcontroller. Any CMSIS-DAP compatible debug probe should work with probe-rs. The {Raspberry-Pi-Debug-Probe} is the most straightforward probe to use for this, and quite affordable. -If you happen to have another Raspberry Pi Pico on-hand, this can be used as a debug probe by following the directions in the <> section. - -If you want to use a probe with the `cargo run` command, be sure that link:.cargo/config.toml[.cargo/config.toml] has the runner set to `probe-run --chip RP2040 --protocol swd`. - -=== Raspberry Pi Debug Probe +If you happen to have another Raspberry Pi Pico on-hand, this can be used as a debug probe. +Follow the instructions in <> to install the necessary firmware to convert the Pico into a debug probe. +The {PicoProbe-PCB-kit} is a nifty add-on that makes it a bit more convenient to use the Pico as a probe. +Whichever probe you happen to choose, configure udev to give your user access to the probe by following these instructions. . Add a udev rule to be able to access the Raspberry Pi Debug Probe as a non-root user. + @@ -140,26 +182,19 @@ SUBSYSTEM=="usb", ATTRS{idVendor}=="2e8a", ATTRS{idProduct}=="000c", TAG+="uacce . Unplug the probe, and plug it back in for the udev rule to take effect. -// todo Wiring. -. Connect the probe to the Raspberry Pi Pico. - -. Flash and run the firmware using the `nix run` command with the `pico.run.probe-rs` target. -Alternatively, use the just command `just run dev probe-rs`. -+ -[,sh] ----- -nix run '.#pico.run.probe-rs' ----- +If you want to use a probe with the `cargo run` command, be sure that link:.cargo/config.toml[.cargo/config.toml] has the runner set to `probe-run --chip RP2040 --protocol swd`. -=== Pico Probe +=== Probe Firmware -The `UF2` method is handy for programming microcontrollers without requiring any additional hardware. -However, debug probes are quite convenient for flashing and debugging code running on the microcontroller. -There are many debuggers available on the market, but there's something quaint about using a spare Pico as a debugger. -The {PicoProbe-PCB-kit} is a nifty add-on that makes it a bit more convenient to use the Pico as a probe. -The steps here describe how to use a Pico as a debug probe with the Raspberry Pi Debug Probe firmware and wire everything up. +The Pico Probe and the Raspberry Pi Debug Probe use variations of the same firmware. +The firmware is installed and upgraded in the same way. +I recommend using the latest firmware. +It's very easy to install. +Raspberry Pi releases official firmware in their https://github.com/raspberrypi/debugprobe[Debug Probe] repository. +I prefer the firmware from the https://github.com/rgrr/yapicoprobe/[Yet Another Picoprobe] project, which is used in these instructions. +It's a bit faster and provides more information about the connection through the LED. -. While holding the `BOOTSEL` button on the Raspberry Pi Pico, connect it to the computer. +. While holding the `BOOTSEL` button on the Raspberry Pi Pico or Raspberry Pi Debug Probe, connect it to the computer. . Mount the drive provided by the Pico. This can be determined by perusing the block devices available from the `lsblk` command. @@ -170,33 +205,94 @@ To mount `/dev/sda1`, as in my case, use the `udisksctl` command like so. udisksctl mount --block-device /dev/sda1 ---- -. Download and install the Raspberry Pi Debug Probe firmware to the Raspberry Pi Pico. +. Download and install the appropriate firmware for the device. ++ +Raspberry Pi Debug Probe:: + [,sh] ---- curl --location --output-dir=/run/media/$USER/RPI-RP2 --remote-name \ - https://github.com/raspberrypi/debugprobe/releases/download/debugprobe-v2.0.1/debugprobe_on_pico.uf2 + https://github.com/rgrr/yapicoprobe/releases/download/v1.21/yapicoprobe-0121-picodebugprobe-11bf6c0.uf2 ---- -. Connect the debug probe Pico to the Pico to flash according to the {Picoprobe-Wiring} documentation. +Pico Probe:: + +[,sh] +---- +curl --location --output-dir=/run/media/$USER/RPI-RP2 --remote-name \ + https://github.com/rgrr/yapicoprobe/releases/download/v1.21/yapicoprobe-0121-pico-11bf6c0.uf2 +---- + +=== Probe Wiring + +This Raspberry Pi Pico uses a 3-pin debug connector on end of the board opposite the microUSB connector, right below the Raspberry Pi logo. +This is documented in detail in the {Raspberry-Pi-3-pin-Debug-Connector-Specification}. +The pins are numbered one through three from left to right when the board is oriented such that the Raspberry Pi logo is upright. +The Raspberry Pi Debug Probe utilizes a JST-SH connector. +If your Pico uses a JST-SH connector, making the connection is straightforward. +If it doesn't, the following table describes each connection, including the color of each wire for the adapter that comes with the Raspberry Pi Debug Probe. + +.Raspberry Pi 3-pin Debug Connector Pinout +[cols="1,2,2,2"] +|=== +| Pin +| SWD +| UART +| Wire Color + +| 1 +| SWCLK +| RX +| Orange + +| 2 +| GND +| GND +| Black + +| 3 +| SWDIO +| TX +| Yellow +|=== + +When using a standalone Pico as a probe, connect the pins to the target Pico according to the following table. +Refer to the {Picoprobe-Wiring} documentation for further details. + .Picoprobe Wiring [cols="1,1"] |=== | Probe | Pico -| GND | GND -| GP2 | SWCLK -| GP3 | SWDIO -| GP4/UART1 TX | GP1/UART0 RX -| GP5/UART1 RX | GP0/UART0 TX +| GND +| GND + +| GP2 +| SWCLK + +| GP3 +| SWDIO + +| GP4/UART1 TX +| GP1/UART0 RX + +| GP5/UART1 RX +| GP0/UART0 TX |=== -. Now just follow the directions in the <> section to flash the target Pico. +=== Use the Probe -== Todo +Follow these steps to run the code on the Raspberry Pi Pico. -* Document connections with the 74AHCT125. +. Connect the probe to the Raspberry Pi Pico using the connections described in the <> section. + +. Flash and run the firmware using the `nix run` command with the `pico.run.probe-rs` target. +Alternatively, use the just command `just run dev probe-rs`. ++ +[,sh] +---- +nix run .#pico.run.probe-rs +---- == References diff --git a/boards/qt-py-ch32v203/README.adoc b/boards/qt-py-ch32v203/README.adoc index 30cebb5..baf3fb0 100644 --- a/boards/qt-py-ch32v203/README.adoc +++ b/boards/qt-py-ch32v203/README.adoc @@ -77,6 +77,48 @@ I use the 74AHCT125 to perform the logic-level conversion, using pin #40, `VBUS` The QT Py CH32V203 draws only 1.11 mA of current in this particular configuration. +=== Wiring + +The 74AHCT125 is wired as shown in the <<74AHCT125 Wiring>> table. +All pins omitted from the table are connected to ground. + +.74AHCT125 Wiring +[cols="1,4"] +|=== +| 74AHCT125 | Signal + +| 1 +| 3.3 Volt power + +| 9 +| 3.3 Volt PWM input signal + +| 10 +| 5 Volt PWM output signal +|=== + +The output signal from the logic-level shifter is sent through the 1N4001 power blocking diode to the fan header. +The pins on the 4-pin fan header are classified in the <<4-pin Fan Header Pinout>> table. +The pins are numbered one through four from left to right with the pins reaching upwards and the overhang positioned between the viewer and the pins. + +.4-pin Fan Header Pinout +[cols="1,4"] +|=== +| Fan Header Pin | Signal + +| 1 +| GND + +| 2 +| +12VDC + +| 3 +| Sense + +| 4 +| Control +|=== + == Getting Started . Change to the board's directory. @@ -100,13 +142,9 @@ SUBSYSTEM=="usb", ATTRS{idVendor}=="4348", ATTRS{idProduct}=="55e0", TAG+="uacce + [,sh] ---- -nix run '../..#qt-py-ch32v203.flash.wchisp' +nix run ../..#qt-py-ch32v203.flash.wchisp ---- -== Todo - -* Document connections with the 74AHCT125. - == References * https://www.ti.com/lit/ds/symlink/sn74ahct125.pdf[SN74AHCT125 Datasheet] From 0799d545828c2178ff3d425d26e807035a8531c5 Mon Sep 17 00:00:00 2001 From: Jordan Williams Date: Sat, 16 Nov 2024 16:04:40 -0600 Subject: [PATCH 2/3] Remove extra quotes --- .github/workflows/build-attiny85.yaml | 2 +- .github/workflows/build-pico.yaml | 4 ++-- .github/workflows/build-qt-py-ch32v203.yaml | 2 +- .github/workflows/cargo-lock-updater.yaml | 6 +++--- README.adoc | 2 +- boards/attiny85/README.adoc | 2 +- 6 files changed, 9 insertions(+), 9 deletions(-) diff --git a/.github/workflows/build-attiny85.yaml b/.github/workflows/build-attiny85.yaml index 485bf94..2a94d22 100644 --- a/.github/workflows/build-attiny85.yaml +++ b/.github/workflows/build-attiny85.yaml @@ -39,7 +39,7 @@ jobs: - uses: DeterminateSystems/nix-installer-action@v15 - uses: DeterminateSystems/magic-nix-cache-action@v8 - name: Build - run: nix build '.#attiny85' + run: nix build .#attiny85 - name: Upload firmware uses: actions/upload-artifact@v4 with: diff --git a/.github/workflows/build-pico.yaml b/.github/workflows/build-pico.yaml index a66266a..35d950e 100644 --- a/.github/workflows/build-pico.yaml +++ b/.github/workflows/build-pico.yaml @@ -41,9 +41,9 @@ jobs: - uses: DeterminateSystems/nix-installer-action@v15 - uses: DeterminateSystems/magic-nix-cache-action@v8 - name: Build - run: nix build '.#pico' + run: nix build .#pico - name: Generate UF2 - run: nix develop '.#pico' --command elf2uf2-rs result/bin/pwm-fan-controller-pico pwm-fan-controller-pico + run: nix develop .#pico --command elf2uf2-rs result/bin/pwm-fan-controller-pico pwm-fan-controller-pico - name: Upload firmware uses: actions/upload-artifact@v4 with: diff --git a/.github/workflows/build-qt-py-ch32v203.yaml b/.github/workflows/build-qt-py-ch32v203.yaml index ea0c553..1cc075b 100644 --- a/.github/workflows/build-qt-py-ch32v203.yaml +++ b/.github/workflows/build-qt-py-ch32v203.yaml @@ -41,7 +41,7 @@ jobs: - uses: DeterminateSystems/nix-installer-action@v15 - uses: DeterminateSystems/magic-nix-cache-action@v8 - name: Build - run: nix build '.#qt-py-ch32v203' + run: nix build .#qt-py-ch32v203 - name: Upload firmware uses: actions/upload-artifact@v4 with: diff --git a/.github/workflows/cargo-lock-updater.yaml b/.github/workflows/cargo-lock-updater.yaml index 40093e9..836309a 100644 --- a/.github/workflows/cargo-lock-updater.yaml +++ b/.github/workflows/cargo-lock-updater.yaml @@ -18,11 +18,11 @@ jobs: - uses: DeterminateSystems/nix-installer-action@v15 - uses: DeterminateSystems/magic-nix-cache-action@v8 - name: Update ATtiny85 Cargo lock file - run: nix develop '.#attiny85' --command 'cd boards/attiny85 && cargo update' + run: nix develop .#attiny85 --command 'cd boards/attiny85 && cargo update' - name: Update Pico Cargo lock file - run: nix develop '.#pico' --command 'cd boards/pico && cargo update' + run: nix develop .#pico --command 'cd boards/pico && cargo update' - name: Update QT Py CH32V203 Cargo lock file - run: nix develop '.#qt-py-ch32v203' --command 'cd boards/qt-py-ch32v203 && cargo update' + run: nix develop .#qt-py-ch32v203 --command 'cd boards/qt-py-ch32v203 && cargo update' - name: Create Pull Request uses: peter-evans/create-pull-request@v7 with: diff --git a/README.adoc b/README.adoc index c6a68a1..021f354 100644 --- a/README.adoc +++ b/README.adoc @@ -108,7 +108,7 @@ However, the top-level directory does not load any environment, so use `nix deve + [,sh] ---- -nix develop '.#attiny85' --command just flash attiny85 +nix develop .#attiny85 --command just flash attiny85 ---- === Serial Port Permissions diff --git a/boards/attiny85/README.adoc b/boards/attiny85/README.adoc index 1c0c08e..03f042c 100644 --- a/boards/attiny85/README.adoc +++ b/boards/attiny85/README.adoc @@ -172,7 +172,7 @@ cd pwm-fan-controller/boards/attiny85 + [,sh] ---- -nix run '../..#attiny85.flash.avrdude' +nix run ../..#attiny85.flash.avrdude ---- == Todo From 4a97c07078196217b31f9bad5e80ec397ee6c61a Mon Sep 17 00:00:00 2001 From: Jordan Williams Date: Sat, 16 Nov 2024 16:04:53 -0600 Subject: [PATCH 3/3] Exclude files from the VSCode file watcher --- .vscode/settings.json | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/.vscode/settings.json b/.vscode/settings.json index 75791c2..b4c9c45 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -60,6 +60,14 @@ "VBUS", "wchisp" ], + "files.watcherExclude": { + "**/.direnv/**": true, + ".lycheecache": true, + ".pre-commit-config.yaml": true, + "**/result": true, + "**/result/**": true, + "**/target/**": true + }, "nix.enableLanguageServer": true, "nix.serverPath": "nil" }