Flasher tool: install Windows drivers to correctly flash the board (#671)

Co-authored-by: Cristian Maglie <c.maglie@arduino.cc>

Author: MatteoPologruto

.github/workflows/release-flasher.yml

@@ -16,14 +16,17 @@ jobs:
   build:
     strategy:
       matrix:
-        os: [linux, darwin, windows]
+        os: [ubuntu-22.04, macos-13, windows-2022]
         arch: [amd64, arm64]
         exclude:
-          - os: windows
+          - os: windows-2022
             arch: arm64
-    runs-on: ubuntu-22.04
+    runs-on: ${{ matrix.os }}
     outputs:
       release: ${{ steps.set-version.outputs.RELEASE_NAME }}
+    defaults:
+      run:
+        shell: bash
     steps:
       - name: Extract version
         run: |
@@ -37,7 +40,7 @@ jobs:
         id: set-version
         run: |
           echo "RELEASE_NAME=${{ env.RELEASE_NAME }}" >> $GITHUB_OUTPUT
-        if: matrix.os == 'windows'
+        if: matrix.os == 'windows-2022'
 
       - name: Checkout
         uses: actions/checkout@v4
@@ -60,18 +63,9 @@ jobs:
           git config --global url."https://${{ env.GITHUB_USERNAME }}:${{ env.GITHUB_TOKEN }}@github.com".insteadOf "https://github.com"
 
       - name: Build Binary
-        env:
-          GOARCH: ${{ matrix.arch }}
-          GOOS: ${{ matrix.os }}
         run: |
           task arduino-flasher-cli:build
 
-      - name: Rename Windows exe
-        working-directory: ./${{ env.DIST_DIR }}
-        run: |
-          mv arduino-flasher-cli arduino-flasher-cli.exe
-        if: matrix.os == 'windows'
-
       - name: Prepare Build Artifacts
         working-directory: ./${{ env.DIST_DIR }}
         run: |
@@ -104,7 +98,7 @@ jobs:
       - name: Download artifacts
         uses: actions/download-artifact@v5
         with:
-          name: ${{ env.PROJECT_NAME }}-windows-amd64
+          name: ${{ env.PROJECT_NAME }}-windows-2022-amd64
 
       - name: Save Win signing certificate to file
         run: echo "${{ secrets.INSTALLER_CERT_WINDOWS_CER }}" | base64 --decode > ${{ env.INSTALLER_CERT_WINDOWS_CER}}
@@ -130,7 +124,7 @@ jobs:
       - name: Upload artifacts
         uses: actions/upload-artifact@v4
         with:
-          name: ${{ env.PROJECT_NAME }}-windows-amd64
+          name: ${{ env.PROJECT_NAME }}-windows-2022-amd64
           path: |
             ${{ env.RELEASE_NAME }}.tar.gz
           if-no-files-found: error

arduino-flasher-cli/drivers.go

@@ -0,0 +1,20 @@
+package main
+
+import (
+	"github.com/bcmi-labs/orchestrator/cmd/feedback"
+	"github.com/bcmi-labs/orchestrator/cmd/i18n"
+	"github.com/spf13/cobra"
+)
+
+func newInstallDriversCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:    "install-drivers",
+		Hidden: true,
+		Run: func(cmd *cobra.Command, args []string) {
+			if err := installDrivers(); err != nil {
+				feedback.Fatal(i18n.Tr("error installing drivers: %v", err), feedback.ErrGeneric)
+			}
+		},
+	}
+	return cmd
+}

arduino-flasher-cli/drivers/dpinst-amd64.exe

@@ -0,0 +1,58 @@
+;
+; Installs WinUsb
+;
+
+[Version]
+Signature   = "$Windows NT$"
+Class       = USBDevice
+ClassGUID   = {88BAE032-5A81-49f0-BC3D-A4FF138216D6}
+Provider    = %ManufacturerName%
+CatalogFile = unoq.cat
+DriverVer   = 09/17/2025,10.48.00.000
+
+; ========== Manufacturer/Models sections ===========
+
+[Manufacturer]
+%ManufacturerName% = Standard,NTamd64
+
+[Standard.NTamd64]
+%DeviceName% =USB_Install, USB\VID_05C6&PID_9008
+
+; ========== Class definition ===========
+
+[ClassInstall32]
+AddReg = ClassInstall_AddReg
+
+[ClassInstall_AddReg]
+HKR,,,,%ClassName%
+HKR,,NoInstallClass,,1
+HKR,,IconPath,%REG_MULTI_SZ%,"%systemroot%\system32\setupapi.dll,-20"
+HKR,,LowerLogoVersion,,5.2
+
+; =================== Installation ===================
+
+[USB_Install]
+Include = winusb.inf
+Needs   = WINUSB.NT
+
+[USB_Install.Services]
+Include = winusb.inf
+Needs   = WINUSB.NT.Services
+
+[USB_Install.HW]
+AddReg=Dev_AddReg
+
+[Dev_AddReg]
+HKR,,DeviceInterfaceGUIDs,0x10000,"{51de5bfa-d59d-4f3e-9b36-0b4b210dd53f}"
+
+; [DestinationDirs]
+; If your INF needs to copy files, you must not use the DefaultDestDir directive here.  
+; You must explicitly reference all file-list-section names in this section.
+
+; =================== Strings ===================
+
+[Strings]
+ManufacturerName="Arduino"
+ClassName="Universal Serial Bus devices"
+DeviceName="Arduino UNO Q Download mode"
+REG_MULTI_SZ = 0x00010000

arduino-flasher-cli/drivers/dpinst-x86.exe

@@ -0,0 +1,8 @@
+//go:build !windows
+
+package main
+
+// installDrivers is a no-op on non-Windows platforms
+func installDrivers() error {
+	return nil
+}

arduino-flasher-cli/drivers/unoq.cat

@@ -0,0 +1,62 @@
+package main
+
+import (
+	"embed"
+	"log/slog"
+	"runtime"
+
+	"github.com/arduino/go-paths-helper"
+)
+
+//go:embed drivers
+var drivers embed.FS
+
+// installDrivers installs the Windows driver using dpinst.exe. This requires
+// administrative privileges.
+func installDrivers() error {
+	tmpDir, err := paths.MkTempDir("", "arduino-flasher-windriver-")
+	if err != nil {
+		return err
+	}
+	defer tmpDir.RemoveAll()
+
+	dpinstArch := "drivers/dpinst-x86.exe"
+	if runtime.GOARCH == "amd64" {
+		dpinstArch = "drivers/dpinst-amd64.exe"
+	}
+	dpinst, err := drivers.ReadFile(dpinstArch)
+	if err != nil {
+		return err
+	}
+	driverCat, err := drivers.ReadFile("drivers/unoq.cat")
+	if err != nil {
+		return err
+	}
+	driverInf, err := drivers.ReadFile("drivers/unoq.inf")
+	if err != nil {
+		return err
+	}
+	dpinstPath := tmpDir.Join("dpinst.exe")
+	err = dpinstPath.WriteFile(dpinst)
+	if err != nil {
+		return err
+	}
+	catPath := tmpDir.Join("unoq.cat")
+	err = catPath.WriteFile(driverCat)
+	if err != nil {
+		return err
+	}
+	infPath := tmpDir.Join("unoq.inf")
+	err = infPath.WriteFile(driverInf)
+	if err != nil {
+		return err
+	}
+
+	slog.Info("Installing Windows driver")
+	dpinstProc, err := paths.NewProcessFromPath(nil, dpinstPath, "/SE", "/SW", "/SA")
+	if err != nil {
+		return err
+	}
+	dpinstProc.SetDir(tmpDir.String())
+	return dpinstProc.Run()
+}

arduino-flasher-cli/drivers/unoq.inf

@@ -6,9 +6,11 @@ import (
 	"fmt"
 	"net/url"
 	"os"
+	"runtime"
 	"strings"
 
 	"github.com/arduino/go-paths-helper"
+	runas "github.com/arduino/go-windows-runas"
 	"github.com/bcmi-labs/orchestrator/cmd/feedback"
 	"github.com/bcmi-labs/orchestrator/cmd/i18n"
 	"github.com/spf13/cobra"
@@ -24,6 +26,7 @@ func newFlashCmd() *cobra.Command {
 			" " + os.Args[0] + " flash 20250915-173\n",
 		Args: cobra.ExactArgs(1),
 		Run: func(cmd *cobra.Command, args []string) {
+			checkDriversInstalled()
 			runFlashCommand(cmd.Context(), args, forceYes)
 		},
 	}
@@ -33,6 +36,17 @@ func newFlashCmd() *cobra.Command {
 	return appCmd
 }
 
+func checkDriversInstalled() {
+	if runtime.GOOS != "windows" {
+		return
+	}
+	cmd, _ := os.Executable()
+	pwd, _ := os.Getwd()
+	if _, err := runas.RunElevated(cmd, pwd, []string{"install-drivers"}, true); err != nil {
+		feedback.Fatal(i18n.Tr("error installing drivers: %v", err), feedback.ErrGeneric)
+	}
+}
+
 func runFlashCommand(ctx context.Context, args []string, forceYes bool) {
 	version := args[0]
 

arduino-flasher-cli/drivers_others.go

@@ -1,9 +1,10 @@
 module arduino-flasher
 
-go 1.25
+go 1.25.1
 
 require (
 	github.com/arduino/go-paths-helper v1.14.0
+	github.com/arduino/go-windows-runas v1.0.1
 	github.com/bcmi-labs/orchestrator v0.3.0
 	github.com/codeclysm/extract/v4 v4.0.0
 	github.com/spf13/cobra v1.9.1
@@ -18,5 +19,5 @@ require (
 	github.com/sirupsen/logrus v1.9.3 // indirect
 	github.com/spf13/pflag v1.0.7 // indirect
 	github.com/ulikunitz/xz v0.5.12 // indirect
-	golang.org/x/sys v0.35.0 // indirect
+	golang.org/x/sys v0.36.0 // indirect
 )