Setup guide

Step 1

Gather hardware

WellSenseOS is bring-your-own-hardware. You need a Raspberry Pi that can run 64-bit Raspberry Pi OS, an ultrasonic distance sensor, power, and a mount that aims the sensor at the water surface.

• Raspberry Pi 3B+ / 4 / 5 €45–90
• Ultrasonic sensor (HC-SR04 class) €5–15
• 5V PSU + weatherproof mount €20–40

Indicative DIY total: €70–150 one-time (indicative). We don’t sell kits. Prefer 2.4 GHz Wi‑Fi for SoftAP and home join (many Pi models are 2.4 GHz only on the SoftAP path).

Step 2

Create your account and a well

1. Open the portal and create an account (email + password). Start the 30-day trial when prompted.
2. Create a well (or tank): name, shape, total depth, and sensor offset. Volume and percent full are calculated in the cloud from those values.
3. Optionally open Devices → Add device so the waiting checklist is ready before you flash the Pi.

Step 3

Flash the WellSenseOS Pi image

1. Download the latest wellsenseos-pi-*.img.xz from the Download page (sign in to the portal to get the file).
2. Install Raspberry Pi Imager, choose Use custom, select the image, and write it to a microSD card.
3. Default SSH login on the image is wellsense / wellsense — change that password after first successful setup.

Step 4

Wire the sensor and power on

1. Wire the HC‑SR04-class sensor using BCM pins (default agent config: trigger 23, echo 24). Keep distance_unit: cm unless you convert elsewhere.
2. Mount the sensor facing the water; note the offset for the well geometry.
3. Insert the SD card, connect power, and wait about one minute for SoftAP to start.

No sensor yet? SoftAP still works; the agent can fall back to mock readings until GPIO hardware is ready.

Step 5

Complete SoftAP setup on your phone

1. On your phone, open Wi‑Fi and join WellSenseOS-XXXX (XXXX is derived from the Pi’s MAC).
2. Open the captive portal, or browse to http://192.168.4.1/ if it does not appear automatically.
3. Enter:
   • Home Wi‑Fi name and password
   • Your WellSense email and password (same as the portal)
   • A device name (for example “Borehole Pi”)
4. Tap save. The portal reports success when setup is queued — the Pi then leaves SoftAP, joins your home Wi‑Fi, and registers with the cloud (often under two minutes).
5. Reconnect your phone to home Wi‑Fi when SoftAP disappears.

If SoftAP comes back, setup failed (Wi‑Fi password, API reachability, or account). Rejoin SoftAP and try again, or check the Pi over SSH when it is on the LAN.

SoftAP can register the device before you confirm your email. You must verify your email (check your inbox for the confirmation link) before signing in to the portal.

Step 6

Confirm the device in the portal

1. On a laptop or phone on home Wi‑Fi, log in and open Devices (use Add device for the waiting checklist).
2. When the Pi registers you should see a success toast and a New chip. Finish setup: assign a well if it is unassigned, then wait for the first heartbeat / reading (about 30 seconds).
3. Open the well detail page to confirm live level and volume.