Prerequisites
- Raspberry Pi 3B+, 4, or 5
- MicroSD card (16 GB minimum, 32 GB recommended)
- Power supply appropriate for your Pi model
- Ethernet cable or Wi-Fi credentials
- A computer with an SD card reader
Step 1: Download the LoopString OS Image
The LoopString OS is a pre-configured Raspberry Pi OS image with Node-RED, the LoopString agent, and all required dependencies pre-installed.
Download the latest image from your LoopString dashboard under Settings > Device Images.
Step 2: Flash the SD Card
Use Raspberry Pi Imager to flash the image:
- Open Raspberry Pi Imager
- Click Choose OS > Use custom and select the downloaded
.imgfile - Select your SD card as the target
- Click Write and wait for the process to complete
Tip: If you need Wi-Fi, click the gear icon in Raspberry Pi Imager before writing to configure your SSID and password.
Step 3: First Boot
Insert the SD card into your Pi and power it on. The first boot takes 2-3 minutes as it:
- Expands the filesystem to fill the SD card
- Installs LoopString agent dependencies
- Starts Node-RED
- Launches the setup wizard
Step 4: Run the Setup Wizard
The setup wizard runs automatically on first boot. It prompts you to:
- Connect to Wi-Fi (if not using Ethernet)
- Enter the claim token from the Add Device modal in your dashboard
- Verify the connection — the Pi registers with Firebase and appears in your dashboard
Connecting via QR Code
Scan the QR code shown in the Add Device modal with your phone. This opens the setup page with the token pre-filled, which gets sent to the Pi over your local network.
Connecting via Terminal
If you have a monitor and keyboard connected to the Pi, you can enter the 6-character claim token directly in the terminal wizard.
Step 5: Verify Connection
Once the wizard completes, your Pi should appear in the dashboard within 30 seconds. You can verify by checking:
- Dashboard — The device appears in the device selector
- Device health — CPU, memory, and disk metrics begin reporting
- Tailscale — If enabled, the tunnel status shows as online
What Gets Installed
The LoopString OS image includes:
- Raspberry Pi OS Lite (Debian Bookworm)
- Node-RED with LoopString flow templates
- LoopString agent for cloud sync and command handling
- Mosquitto MQTT broker for protocol bridging
- Tailscale for secure remote access (optional)
- Protocol packages for Modbus, S7comm, and I2C/UART/1-Wire
Troubleshooting
- Pi does not boot — Re-flash the SD card and try a different power supply
- No network — Check Ethernet cable or Wi-Fi credentials
- Claim token rejected — Generate a new token (they expire after 15 minutes)
- Pi boots but does not appear in dashboard — See Device Offline