Install Prerequisites on Windows

Who this is for: Windows users setting up the SandGrain SDK for the first time.

What you'll accomplish: Install Git, Node.js, Docker Desktop, WSL, and USB passthrough, everything the SDK needs before you clone the code.

Before you begin: You'll run most commands in a regular (non-admin) PowerShell window. A few require Administrator: those are called out. Some installers show their own UAC prompt; click Yes when they appear.

Open PowerShell

Press Win + X, choose Terminal (or PowerShell). You'll see a prompt like PS C:\Users\YourName>.

Install Git

winget install --id Git.Git --silent --accept-source-agreements --accept-package-agreements

Close and reopen PowerShell (so PATH refreshes), then verify:

git --version

Expected: git version 2.xx.x.windows.x

Install Node.js LTS

winget install --id OpenJS.NodeJS.LTS --silent --accept-source-agreements --accept-package-agreements

In a new PowerShell window, verify:

node --version    # v20.x.x or higher 
npm --version     # 10.x.x

Install Docker Desktop

winget install --id Docker.DockerDesktop --silent --accept-source-agreements --accept-package-agreements

Watch carefully: a UAC prompt will appear (sometimes behind other windows: check the taskbar for a flashing shield icon). Click Yes. The install then takes 3–5 minutes.

If winget reports Installer failed with exit code: 4294967291 (= -5), the UAC prompt was missed or denied. Re-run and accept it.

(See Troubleshooting SDK Setup.)

In a new PowerShell window, verify:

docker --version

Install WSL

Run in PowerShell as Administrator:

wsl --install

Verify:

wsl --version    # should report WSL version 2

Verify if Ubuntu is selected as the preferred distro :

wsl -l -v   

# Ubuntu should be listed and selected (with an '*' in front) 
  as the default distro, also should report with VERSION = 2

Incase if Ubuntu is not selected, set it as the default:

wsl --set-defaut  <distro-name>  

# replace <distro_name> with the name of your Ubuntu service 
  that displays when you run wsl -l -v

WSL gives you a real Linux userland to run apt, make, and the resulting test_device / test_gw binaries, which are GCC/Linux builds and don't run on native Windows.

Allow PowerShell scripts to run (one-time, per user)

Windows blocks .ps1 files by default. Allow local scripts to run:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

When prompted, type Y and press Enter.

If a single script is still blocked with "running scripts is disabled", allow it for just that session: Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

Install usbipd (USB passthrough to WSL)

The SandGrain Token is a USB device, and your firmware runs inside WSL. usbipd bridges the two. Run PowerShell as Administrator:

winget search usbipd 
winget install dorssel.usbipd-win

Open a new PowerShell window so PATH refreshes.

Note: The USB attach is lost on unplug/reboot, run usbipd attach again. On usbipd ≥ 4.0, run usbipd bind --busid <BUSID> once (as admin) before the first attach.

You don't have to attach the USB manually, the SDK launchers prompt you to attach it automatically. See USB & Serial Port Setup if you'd rather do it by hand.

Start Docker Desktop once

Start menu → search Docker Desktop → click it.
Accept the Docker Subscription Service Agreement.
Leave Use WSL 2 based engine checked → Finish.
Wait for the whale icon in the system tray to stop animating and become solid (30–60 seconds on first launch).

Verify:

docker info    # look for the "Server:" / "Server Version:" section

If you see error during connect: open //./pipe/dockerDesktopLinuxEngine, Docker isn't started yet, wait ~30s and retry. After this first launch, Docker Desktop auto-starts at login.

Next step

Continue to Get the Code & Run the Setup Script.