Skip to content
English
Contact us
  • There are no suggestions because the search field is empty.

USB & Serial Port Setup

Who this is for: Anyone connecting the SandGrain Token, especially on Windows (where the USB must be passed through to WSL).

What you'll accomplish: Confirm your machine sees the Token, and, on Windows, attach it to WSL.

The device node (Device mode) needs its SandGrain Token attached via USB. Where the OS exposes it, and how you make it available to the SDK, depends on the platform.

Confirm the OS sees the Token

Linux / WSL:

ls /dev/ttyACM* /dev/ttyUSB* 2>/dev/null    # expect e.g. /dev/ttyACM0 
sudo dmesg | tail -20          # look for: ttyACM0: USB ACM device

macOS:

ls /dev/tty.usbmodem* /dev/tty.usbserial-* 2>/dev/null

You can also check Apple menu → About This Mac → System Report → USB.

If nothing appears, try a different USB port or cable, some cables are charge-only and carry no data.

Tell the SDK which port (config or flag)

  • Windows: USB_COM_PORT is the COM number (COM4 → 4).

  • Linux: USB_TTY_PREFIX / USB_TTY_PORT describe the device (/dev/ttyACM0 → prefix ACM, port 0).

These live in config_poc.h, but you rarely edit them by hand, the launchers auto-detect the port and let you override it at runtime with --usb PORT.

Windows only: attach the Token to WSL with usbipd

The Token is a Windows USB device, but the firmware runs inside WSL. usbipd bridges them.

You usually don't need to do this manually. run_standalone.ps1 and run_all.ps1 prompt you to attach the USB automatically. Follow the steps below only if you want to attach it by hand.

Install usbipd (PowerShell as administrator), if you haven't:

winget search usbipd 
winget install dorssel.usbipd-win

Open a new PowerShell window so PATH refreshes.

List devices and note the BUSID (PowerShell as administrator):

usbipd list

Check your WSL distro name/version:

wsl -l -v

Attach the Token to WSL:

usbipd attach --busid 1-1 --wsl Ubuntu-22.04

Replace 1-1 with your BUSID and Ubuntu-22.04 with your distro. Then verify inside WSL:

lsusb dmesg | grep tty

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

Linux permissions: the dialout group

On Linux and Raspberry Pi, reading the serial port requires membership in the dialout group (or uucp on Arch):

sudo usermod -aG dialout $USER    # then log out and back in 
groups | grep dialout             # verify

If you can't or don't want to join the group, run the Device with --sudo.

Common issues

  • USB device not detected in WSL → re-run usbipd list and usbipd attach; check the cable/port; verify with lsusb and dmesg | grep tty inside WSL.

  • Device/Gateway can't read the TID / access the serial port → they need sudo (raw sockets + serial). Provide sudo when prompted, or run with --sudo.