Walkthrough: Split Deployment on Raspberry Pi

Who this is for: Developers who want a realistic production-style topology, with the Gateway and Device running on separate machines and the TrustBridge stack on a laptop.

What you'll accomplish: Run the TrustBridge stack on a laptop, the Gateway on one Pi, and the Device (with the Token) on a second Pi, and watch an authentication flow end to end.

Prerequisites: A working TrustBridge stack on the laptop (see SDK + TrustBridge on Windows or on Linux & macOS).

The topology

     
     ┌──────────────── Laptop (LAPTOP_IP) ─────────────────┐
     │                                                     │
     │   Docker stack (trustbridge-net):                   │
     │   BE :3000 · FE :5173 · Cloud SDK                   │
     │   Mosquitto :1883 · MySQL :3306 · Redis :6379       │
     └─────────────────────────────────────────────────────┘
          ▲
          │  Gateway ONLY:
          │    • MQTT :1883  (auth requests + gw_log telemetry)
          │    • HTTP  BE:3000/api/devices/whitelist  (whitelist sync)
          │
┌── Pi #2: GATEWAY ───┐                     ┌── Pi #1: DEVICE ───────┐
│ test_gw :8080       │   ◀───────────      │                        │
│ No USB hardware     │                     │ test_device            │
│ (MQTT + HTTP uplink)│ TCP:8080            │ SandGrain USB attached │
└─────────────────────┘ auth + HELLO        │                        │
                        /RUN_AUTH relay     └────────────────────────┘

Box	Role	Binaries	USB?
Laptop	Docker host	`tb-be`, `tb-fe`, `tb-mysql`, `tb-mosquitto`, `sandgrain-cloud-app`	No
Pi #2	Gateway	`test_gw`	No
Pi #1	Device	`test_device` (foreground)	Yes (SandGrain Token)

Alternative: a single Pi can run both roles, run bash run_gateway.sh in one terminal and bash run_device.sh in another (use the Pi's own IP as the Gateway host). Two Pis give the more realistic split.

Hardware and network

2× Raspberry Pi (any 64-bit model, running 64-bit Raspberry Pi OS or Ubuntu Server).
1× SandGrain USB Token (plugs into Pi #1).
1× laptop with the Docker stack already up.

Network: critically important. All three boxes must be on the same IP subnet. Most routers use a /24 mask, so the first three octets must match (e.g. all 192.168.1.x). If the laptop is on 10.10.10.x but the Pis are on 10.10.8.x, they can't reach each other, the easiest fix is to connect all three to the same Wi-Fi SSID.

Label your IPs and keep them handy:

Label	Meaning	Find it with
`LAPTOP_IP`	Laptop's LAN IP	`ipconfig` (Windows) / `ip -4 addr show` (Linux/macOS)
`PI_GW_IP`	Pi #2's IP	`hostname -I` on Pi #2
`PI_DEV_IP`	Pi #1's IP	`hostname -I` on Pi #1

Laptop: find its LAN IP and open the firewall

Find the IP on the adapter shared with the Pis (skip 169.254., 172., and vEthernet (WSL) / Tailscale addresses).

Windows, open the required ports (PowerShell as administrator):

New-NetFirewallRule -DisplayName "TrustBridge BE 3000"  -Direction Inbound -Protocol TCP -LocalPort 3000 -Action Allow 
New-NetFirewallRule -DisplayName "TrustBridge MQTT 1883" -Direction Inbound -Protocol TCP -LocalPort 1883 -Action Allow 
New-NetFirewallRule -DisplayName "TrustBridge FE 5173"  -Direction Inbound -Protocol TCP -LocalPort 5173 -Action Allow

On Linux/macOS the default firewall usually allows outbound LAN traffic without changes. Verify by opening http://LAPTOP_IP:5173 on the laptop (use the IP, not localhost), the login page should load.

Both Pi's: Common Setup

Do this on both Pis.

# USB serial access 
sudo usermod -aG dialout $USER      # log out/in (or reboot) afterward; verify: groups | grep dialout  

# Get the SDK code 
mkdir -p ~/Desktop && cd ~/Desktop 
git clone -b release/v3.6.0 <SandGrain-TrustBridgeSDK-repo-url> 
cd SandGrain-TrustBridgeSDK/SandGrain-SDK 
chmod +x setup.sh run_device.sh run_gateway.sh  

# Install build tools, the MQTT client library, python, tmux, and create the venv 
bash setup.sh

Clock skew (optional). If make later complains about "file has modification time in the future" / "clock skew detected", sync the Pi's clock: sudo apt install -y systemd-timesyncd && sudo systemctl enable --now systemd-timesyncd && sudo timedatectl set-ntp true

3. Pi #2: the Gateway (start this first)

bash run_gateway.sh

At the prompts (Enter keeps the saved value from .env.gateway):

Cloud / BE host → the TrustBridge Docker stack LAN IP (LAPTOP_IP)
MQTT broker host → defaults to the IP above; keep it unless the broker is elsewhere
MQTT port → 1883
MQTT username / password → blank unless the broker requires auth
Gateway listen port → 8080 (the port the Device Pi dials)

It builds test_gw and runs it in the foreground (Ctrl-C to stop). It derives BE_URL=http://<LAPTOP_IP>:3000/api automatically to sync the device whitelist. Leave this terminal running.

Pi #1: The Device

Make sure Pi #2 is already running (the Device tries to reach the Gateway at startup).

Plug in the Token and confirm the OS sees it:

ls /dev/ttyACM* /dev/ttyUSB* 2>/dev/null    # expect e.g. /dev/ttyACM0

If nothing appears, try a different USB port or cable (some are charge-only).

Then:

bash run_device.sh

At the prompts:

MQTT broker host → the laptop's LAN IP (LAPTOP_IP), for run_auth triggers and telemetry
Gateway Pi host → the Gateway Pi's LAN IP (PI_GW_IP)
MQTT port → 1883; Gateway port → 8080
USB serial port → auto-detected (/dev/ttyACM0); override with --usb 0

It builds test_device and runs in the foreground. By default it runs in --listen mode (auth triggered from the backend), while the interactive menu (options 1/2/3) is also available. Add --menu for the menu only, or --sudo if you didn't join the dialout group.

Verify end to end

Browser (any device on the same Wi-Fi): http://LAPTOP_IP:5173 → login page loads.
Pi #2 gateway log: Whitelist loaded: N device(s) (N > 0 once your device is registered in the BE admin panel).
Pi #1 device log: Device SDK initialized OK and MQTT connected.
In the frontend: trigger authentication for the registered device. You should see the flow: FE/BE → MQTT publish → Pi #2 Gateway → TCP to Pi #1 → the Device runs the handshake against the SandGrain hardware → result flows back to BE → FE updates.

Start / stop order

Always start Laptop → Pi #2 → Pi #1, so the Device finds the Gateway listening and the Gateway finds the backend up.

To stop:

Ctrl+C on Pi #1, then
Ctrl+C on Pi #2, then
start-all.sh down on the laptop.