# SensorPulse Companion – Setup guide

The SensorPulse Companion app (Android/iOS) gives your phone read-only access to your Windows PC: CPU/GPU/RAM, temperatures, warnings and critical sensors. There is no remote control (no profiles, fans or overlay).

Security: Remote access is off by default. Enable it only on your home network or over VPN. Do not expose the API port to the public internet (no router port forwarding).

## Overview

1. Run SensorPulse on the PC (Windows 10/11, 64-bit)
2. Enable Settings → Automation → Localhost sensor API
3. Enable Remote access (Companion app)
4. Windows Firewall: allow inbound TCP on the API port (default 8765) for private networks – use Add firewall rule in Settings or create manually
5. Install the Companion app and scan the QR code (recommended) or use pairing JSON from Settings

## On the PC – step by step

### 1. Enable the API

Open Settings (gear) → Automation:

- Check Localhost sensor API
- Keep port `8765` or choose another (1024–65535)
- With remote access, a long API token is generated automatically

### 2. Enable remote access

Check Remote access (Companion app). SensorPulse then listens on your LAN IPs (e.g. `192.168.1.42`), not only `127.0.0.1`.

The pairing area shows:

- QR code – scan in the Companion app (or JSON-capable scanner)
- Pairing JSON – copy/paste
- LAN endpoints – URLs for browser or `curl` tests on the network

### 3. Windows Firewall

In Settings under Remote access, SensorPulse shows firewall status and offers Add firewall rule (administrator confirmation). Or create manually:

1. Search Windows for “Windows Defender Firewall with Advanced Security”
2. Inbound Rules → New Rule… → Port → TCP → `8765`
3. Profile: Private only (not Public)
4. Name e.g. SensorPulse Companion API

### 4. Pairing JSON

    {
      "v": 1,
      "name": "GAMING-PC",
      "host": "192.168.1.42",
      "port": 8765,
      "token": "…long secret…"
    }

## Companion app (phone)

1. Open SensorPulse Companion
2. Tab PCs → Add PC
3. Scan QR code (Android/iOS, recommended) or paste pairing JSON
4. Test connection → Save
5. Tabs Dashboard / Alerts – pull to refresh or wait ~20 s

## Scenarios

### Same Wi‑Fi

Phone and PC on the same home Wi‑Fi. `host` must be the PC’s IPv4 address (not `127.0.0.1`). On PC: `ipconfig` → IPv4 address.

### On the go via VPN (recommended)

Use Tailscale or WireGuard on PC and phone. Use the PC’s VPN IP as `host` in the app.

### Fixed DHCP / reserved IP

Reserve the PC’s MAC address in your router so the LAN IP stays stable.

### Multiple PCs

Save several PCs in the app; tap one in the list to make it active (●).

### Regenerate token

If the token may be compromised: Regenerate API token in Settings and update every Companion app.

## Troubleshooting

Issue | Fix
--- | ---
Connection failed | SensorPulse running? API + remote on? Same Wi‑Fi/VPN? Firewall?
`401 unauthorized` | Wrong or old token – copy fresh pairing JSON
QR not scanned | Paste JSON manually
Worked before, not now | DHCP changed IP – re-pair or reserve IP on router

## What the Companion app cannot do

- No start/stop monitoring, profiles or fan control
- No SQL admin or SNMP configuration
- No monitoring without SensorPulse running on the PC

Localhost API reference (Rainmeter, scripts) · Press `F1` in Settings while focused on the Companion section for quick help.