Skip to content

Commit d8fdee6

Browse files
author
Ravi Singh
committed
docs: add troubleshooting + self-hosting guide, remove old v1 images
- Troubleshooting guide: receiver, transmitter, cloud, hardware issues - Self-hosting guide: SQLite quick setup + PostgreSQL production deploy - Removed legacy v1 images (BaudRate, circuit diagram, receiver gif)
1 parent 784acde commit d8fdee6

5 files changed

Lines changed: 204 additions & 0 deletions

File tree

‎docs/BaudRate 115200 Select.jpg‎

-65.7 KB
Binary file not shown.

‎docs/Receiver Module.gif‎

-10.3 MB
Binary file not shown.

‎docs/circuitDiagram.png‎

-771 KB
Binary file not shown.

‎docs/self-hosting.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# Self-Hosting TankSync Cloud
2+
3+
This guide covers deploying TankSync Cloud on your own server.
4+
5+
## Requirements
6+
7+
- Ubuntu 22.04+ or Debian 12+ server
8+
- Node.js 20+
9+
- PostgreSQL 14+ (or SQLite for simple setups)
10+
- Mosquitto MQTT broker
11+
- Domain name (optional, for HTTPS)
12+
13+
## Quick Setup (SQLite, local use)
14+
15+
```bash
16+
cd pwa
17+
npm install
18+
cp .env.example .env
19+
# Edit .env: set JWT_SECRET, MQTT_URL
20+
npm run build
21+
npm start
22+
```
23+
24+
Access at `http://localhost:4800`.
25+
26+
## Production Setup (PostgreSQL + Nginx)
27+
28+
### 1. Install dependencies
29+
30+
```bash
31+
sudo apt install postgresql mosquitto mosquitto-clients nginx certbot
32+
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -
33+
sudo apt install nodejs
34+
```
35+
36+
### 2. Create database
37+
38+
```bash
39+
sudo -u postgres createuser tanksync
40+
sudo -u postgres createdb tanksync -O tanksync
41+
sudo -u postgres psql -c "ALTER USER tanksync PASSWORD 'your-password';"
42+
```
43+
44+
### 3. Configure Mosquitto
45+
46+
```bash
47+
sudo mosquitto_passwd -c /etc/mosquitto/tanksync_passwd tanksync_server
48+
# Enter a strong password
49+
50+
cat << EOF | sudo tee /etc/mosquitto/conf.d/tanksync.conf
51+
listener 1883 127.0.0.1
52+
allow_anonymous false
53+
password_file /etc/mosquitto/tanksync_passwd
54+
EOF
55+
56+
sudo systemctl restart mosquitto
57+
```
58+
59+
### 4. Deploy the app
60+
61+
Use `pwa/server-cloud/` for PostgreSQL, or `pwa/server/` for SQLite.
62+
63+
```bash
64+
# Clone and setup
65+
git clone https://github.com/Techposts/LoRa-Water-Tank-Monitor.git
66+
cd LoRa-Water-Tank-Monitor/pwa
67+
68+
# For PostgreSQL cloud version
69+
cp server-cloud/* server/
70+
cp package-cloud.json package.json
71+
npm install --omit=dev
72+
73+
# Configure
74+
cp .env.example .env
75+
# Edit .env with your database URL, MQTT credentials, etc.
76+
77+
# Build frontend
78+
npm run build
79+
```
80+
81+
### 5. Environment variables
82+
83+
```bash
84+
# Required
85+
JWT_SECRET=<random-64-char-string>
86+
DATABASE_URL=postgresql://tanksync:password@localhost:5432/tanksync
87+
MQTT_URL=mqtt://tanksync_server:password@localhost:1883
88+
89+
# Optional
90+
RESEND_API_KEY=<your-resend-api-key>
91+
TURNSTILE_SECRET=<your-cloudflare-turnstile-secret>
92+
VAPID_PUBLIC_KEY=<generate-with-npx-web-push-generate-vapid-keys>
93+
VAPID_PRIVATE_KEY=<matching-private-key>
94+
```
95+
96+
### 6. Systemd service
97+
98+
Copy `pwa/deploy/tanksync.service` to `/etc/systemd/system/` and adjust paths and user.
99+
100+
```bash
101+
sudo systemctl enable tanksync
102+
sudo systemctl start tanksync
103+
```
104+
105+
### 7. Nginx reverse proxy
106+
107+
Copy `pwa/deploy/nginx-tanksync.conf` to `/etc/nginx/sites-available/` and adjust server_name.
108+
109+
```bash
110+
sudo ln -s /etc/nginx/sites-available/tanksync /etc/nginx/sites-enabled/
111+
sudo certbot --nginx -d your-domain.com
112+
sudo systemctl reload nginx
113+
```
114+
115+
## MQTT for External Receivers
116+
117+
To allow receivers outside your network to connect:
118+
119+
1. Add a TLS listener to Mosquitto (port 8883)
120+
2. Get a Let's Encrypt certificate for your MQTT domain
121+
3. Configure per-user MQTT credentials
122+
4. Set `MQTT_PUBLIC_HOST` and `MQTT_PUBLIC_PORT` in `.env`
123+
124+
See the main README for the full architecture diagram.

‎docs/troubleshooting.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Troubleshooting
2+
3+
## Receiver
4+
5+
### WiFi scan button does nothing
6+
The receiver uses APSTA mode for scanning. If scan still fails, try rebooting the receiver.
7+
8+
### Captive portal doesn't appear
9+
After connecting to the "TankSync" WiFi, try opening `http://192.168.4.1` manually. iOS/Android auto-redirect is supported but may not work on all devices.
10+
11+
### OLED shows "NO DATA"
12+
No transmitter is paired yet. Go to the receiver's web UI and press "Start Pairing", then power on the transmitter.
13+
14+
### MQTT shows "disconnected"
15+
- Check WiFi is connected (receiver web UI -> System tab)
16+
- Verify MQTT broker host and port are correct
17+
- If using TLS (port 8883), ensure `use_tls` is enabled
18+
- Check MQTT username and password
19+
20+
### OTA update fails
21+
- Ensure the `.bin` file matches your board (ESP32 DevKit vs ESP32-C3)
22+
- File must be under 1.5MB (OTA partition limit)
23+
- Try uploading via the web UI at `http://<receiver-ip>/api/ota/upload`
24+
25+
## Transmitter
26+
27+
### Transmitter won't pair
28+
- Ensure transmitter and receiver are using the same LoRa frequency and network ID
29+
- Transmitter must be powered on within 60 seconds of pressing "Start Pairing" on the receiver
30+
- Try power cycling the transmitter
31+
32+
### Battery shows 0%
33+
- Check the battery voltage divider wiring
34+
- The ADC calibration assumes a 100K/100K divider on GPIO 0
35+
- If using a different divider ratio, adjust in `config.h`
36+
37+
### Distance reading is stuck or wrong
38+
- SR04T sensor needs a clear line of sight to the water surface
39+
- Minimum distance: 25cm, maximum: 400cm
40+
- Check sensor wiring (TRIG and ECHO pins)
41+
42+
## TankSync Cloud
43+
44+
### Can't sign up (captcha fails)
45+
- Disable VPN or ad blockers temporarily
46+
- Try a different browser
47+
- Clear cookies and try again
48+
49+
### Email verification code not received
50+
- Check spam/junk folder
51+
- Emails come from `onboarding@resend.dev` (or `noreply@smartghar.org` if domain verified)
52+
- Click "Resend code" (rate limited to 3 per 5 minutes)
53+
54+
### QR code scan doesn't work
55+
- Ensure your phone and the TankSync Cloud server are on the same network as the receiver
56+
- The QR code contains the receiver's local IP — it must be reachable from the server
57+
- If on a different network, manually enter MQTT details in the receiver's web UI
58+
59+
### Dashboard shows stale data
60+
- Check receiver's MQTT connection status in its web UI
61+
- If using TankSync Cloud, verify the receiver is connected to `mqtt.smartghar.org:8883`
62+
- The transmitter sends data every sleep interval (default 5 minutes)
63+
64+
### Push notifications not working
65+
- Install the app as a PWA (Add to Home Screen)
66+
- Enable notifications when prompted
67+
- VAPID keys must be configured in the server's `.env` file
68+
69+
## Hardware
70+
71+
### LoRa range is poor
72+
- Ensure antennas are attached to both RYLR998 modules
73+
- Higher mounting = better range
74+
- Avoid metal obstructions between transmitter and receiver
75+
- Try increasing spreading factor in LoRa settings (higher SF = longer range, slower speed)
76+
77+
### Solar charging not working
78+
- TP4056 module needs direct sunlight on the panel
79+
- Check that the solar panel output is 5-6V
80+
- The charge LED on TP4056 should be red when charging

0 commit comments

Comments
 (0)