Skip to content

Commit a91d761

Browse files
MrAlders0nMrAlders0n
committed
Update development guidelines and add flow diagrams for RX and TX processes
1 parent 55ad151 commit a91d761

3 files changed

Lines changed: 200 additions & 31 deletions

File tree

‎docs/DEVELOPMENT_REQUIREMENTS.md‎

Lines changed: 6 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -56,39 +56,14 @@ When **modifying connect or disconnect logic**, you must:
5656
When **modifying ping or auto-ping logic**, you must:
5757
- Read `docs/PING_AUTO_PING_WORKFLOW.md` before making the change (to understand current intended behavior).
5858
- Update `docs/PING_AUTO_PING_WORKFLOW.md` so it remains accurate after the change:
59-
- Manual ping flow (`sendPing()` with `manual=true`)
60-
- Auto ping flow (`startAutoPing()`, `stopAutoPing()`, `scheduleNextAutoPing()`)
61-
- Ping validation logic (geofence, distance, cooldown checks)
62-
- GPS coordinate acquisition for pings (`getGpsCoordinatesForPing()`)
63-
- Payload construction (`buildPayload()`, power settings)
64-
- Repeater tracking logic (`startRepeaterTracking()`, `stopRepeaterTracking()`, `handleRxLogEvent()`)
65-
- MeshMapper API posting (`postToMeshMapperAPI()`)
66-
- Control locking behavior (`state.pingInProgress`, `updateControlsForCooldown()`)
67-
- Cooldown management (`startCooldown()`, `isInCooldown()`)
68-
- Auto countdown timer logic (pause, resume, skip reasons)
69-
- Ping interval configuration (15s/30s/60s)
70-
- Wake lock management during auto mode
71-
- Page visibility handling during auto mode
59+
- Ping flows (manual `sendPing()`, auto-ping lifecycle)
60+
- Validation logic (geofence, distance, cooldown)
61+
- GPS acquisition and payload construction
62+
- Repeater tracking and MeshMapper API posting
63+
- Control locking and cooldown management
64+
- Auto mode behavior (intervals, wake lock, page visibility)
7265
- Any UI impacts (buttons, status messages, countdown displays)
7366

74-
---
75-
## Requested Change: Update App Connection Flow (Reorder Steps)
76-
77-
### Background
78-
Below is the **current** app connection flow used when a user connects to a device for wardriving.
79-
80-
#### Current Connection Flow
81-
1. **User Initiates** → User clicks **Connect**
82-
2. **Device Selection** → Browser displays BLE device picker
83-
3. **BLE GATT Connection** → App establishes a GATT connection to the selected device
84-
4. **Protocol Handshake** → App and device exchange/confirm protocol version compatibility
85-
5. **Device Info** → App retrieves device metadata (e.g., device name, public key, settings)
86-
6. **Time Sync** → App synchronizes the device clock
87-
7. **Channel Setup** → App creates or finds the `#wardriving` channel
88-
8. **GPS Init** → App starts GPS tracking
89-
9. **Capacity Check** → App acquires an API slot from **MeshMapper**
90-
10. **Connected** → App enables all controls; system is ready for wardriving
91-
9267
---
9368

9469
### Requested Change

‎docs/FLOW_WARDRIVE_RX_DIAGRAM.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
flowchart TD
2+
subgraph INIT["🔌 ON CONNECT"]
3+
A[BLE Connection Established] --> B[Start Unified RX Listening<br/>Register LogRxData handler]
4+
B --> B2[Initialize rxBatchBuffer Map<br/>Empty - ready for tracking]
5+
end
6+
7+
subgraph RECEIVE["📻 RECEIVE FROM MESH"]
8+
C[/"Radio receives packet<br/>from repeater"/] --> D[/"BLE pushes LogRxData event<br/>{lastSnr, lastRssi, raw}"/]
9+
end
10+
11+
subgraph UNIFIED["🔀 UNIFIED RX HANDLER"]
12+
D --> E{Header = 0x15? <br/>GroupText}
13+
E -->|NO| E_IGNORE[/"🚫 IGNORE"/]
14+
E -->|YES| F{Payload ≥ 3 bytes?}
15+
F -->|NO| F_IGNORE[/"🚫 IGNORE"/]
16+
F -->|YES| G{Session Log<br/>Tracking Active? <br/>10s window after TX}
17+
end
18+
19+
subgraph SESSION_LOG["📋 SESSION LOG TRACKING (Echo Detection)"]
20+
G -->|YES| H[Delegate to Session Log Handler]
21+
H --> I{Channel hash<br/>matches? }
22+
I -->|NO| I_PASS[Pass to Passive RX]
23+
I -->|YES| J[Decrypt message content]
24+
J --> K{Message matches<br/>our sent ping?}
25+
K -->|NO| K_PASS[Pass to Passive RX]
26+
K -->|YES| L{Path length > 0?}
27+
L -->|NO| L_IGNORE[/"🚫 Direct TX, not echo"/]
28+
L -->|YES| M["✅ ECHO DETECTED! <br/>Extract FIRST hop repeater ID"]
29+
M --> N[Track in repeaters Map<br/>Update SNR if better<br/>Update UI chips live]
30+
N --> O[/"Done - wait for next event"/]
31+
end
32+
33+
subgraph PASSIVE["👁️ PASSIVE RX PROCESSING"]
34+
G -->|NO| P[Passive RX Processing]
35+
I_PASS --> P
36+
K_PASS --> P
37+
P --> Q{Path length > 0? }
38+
Q -->|NO| Q_IGNORE[/"🚫 Direct TX, skip"/]
39+
Q -->|YES| R["Extract LAST hop<br/>(direct repeater) e.g., '92'"]
40+
R --> S{GPS fix<br/>available?}
41+
S -->|NO| S_SKIP[/"⚠️ Skip entry"/]
42+
S -->|YES| T["📝 ADD TO RX LOG UI<br/>{repeaterId, snr, lat, lon, timestamp}"]
43+
T --> U[Update RX Log UI<br/>Summary bar + entry chips]
44+
end
45+
46+
subgraph BATCH_TRACK["📦 BATCH TRACKING FOR API"]
47+
U --> V{Batch exists for<br/>this repeater?}
48+
49+
V -->|NO| W["🆕 CREATE NEW BATCH<br/>{<br/> firstLocation: {lat, lng}<br/> firstTimestamp: now()<br/> samples: []<br/> timeoutId: null<br/>}"]
50+
W --> X["⏰ Set 30s timeout<br/>for this repeater"]
51+
X --> Y[Store in rxBatchBuffer]
52+
53+
V -->|YES| Z[Get existing batch]
54+
55+
Y --> AA["➕ ADD SAMPLE<br/>{snr, location, timestamp}"]
56+
Z --> AA
57+
58+
AA --> BB["📏 Calculate distance from<br/>firstLocation to current"]
59+
BB --> CC{Distance ≥ 25m?}
60+
CC -->|NO| DD[/"Continue collecting<br/>Wait for next event"/]
61+
end
62+
63+
subgraph FLUSH_DIST["🔔 FLUSH: DISTANCE TRIGGER"]
64+
CC -->|YES| EE["Distance threshold met! "]
65+
EE --> FLUSH_START
66+
end
67+
68+
subgraph FLUSH_TIME["🔔 FLUSH: TIMEOUT TRIGGER"]
69+
TIMEOUT[/"⏰ 30s Timer Expires"/] --> FF["Timeout for repeater"]
70+
FF --> FLUSH_START
71+
end
72+
73+
subgraph FLUSH_END["🔔 FLUSH: SESSION END"]
74+
DISCONNECT[/"🔌 Disconnect Signal"/] --> GG["Flush ALL batches"]
75+
GG --> HH["Iterate all repeaters<br/>in rxBatchBuffer"]
76+
HH --> FLUSH_START
77+
end
78+
79+
subgraph FLUSH_PROCESS["📤 FLUSH BATCH PROCESS"]
80+
FLUSH_START[Get batch from buffer] --> II[Clear timeout if exists]
81+
II --> JJ["📊 AGGREGATE SAMPLES<br/>━━━━━━━━━━━━━━━━━━━━<br/>snr_avg = mean(samples.snr)<br/>snr_max = max(samples.snr)<br/>snr_min = min(samples.snr)<br/>sample_count = length<br/>duration = end - start"]
82+
83+
JJ --> KK["📦 BUILD API ENTRY<br/>━━━━━━━━━━━━━━━━━━━━<br/>{<br/> repeater_id: '92'<br/> location: firstLocation<br/> snr_avg: 10.25<br/> snr_max: 12.5<br/> snr_min: 8.0<br/> sample_count: 5<br/> timestamp_start<br/> timestamp_end<br/> trigger: 'distance'<br/>}"]
84+
85+
KK --> LL{session_id<br/>available?}
86+
LL -->|NO| LL_WARN[/"⚠️ Cannot post: <br/>no session_id"/]
87+
LL -->|YES| MM["Build payload: <br/>{session_id, entries: [entry]}"]
88+
89+
MM --> NN["📡 QUEUE API POST<br/>━━━━━━━━━━━━━━━━━━━━<br/>🚧 DEBUG: console.log()<br/>🚀 PROD: POST to API"]
90+
91+
NN --> OO[Remove batch from<br/>rxBatchBuffer]
92+
LL_WARN --> OO
93+
OO --> PP[/"Batch cleared for repeater"/]
94+
end
95+
96+
subgraph LOOP["🔄 CONTINUOUS LISTENING"]
97+
O --> WAIT[/"⏳ Wait for next rx_log event"/]
98+
DD --> WAIT
99+
PP --> WAIT
100+
E_IGNORE --> WAIT
101+
F_IGNORE --> WAIT
102+
L_IGNORE --> WAIT
103+
Q_IGNORE --> WAIT
104+
S_SKIP --> WAIT
105+
WAIT --> C
106+
end
107+
108+
subgraph CLEANUP["🧹 ON DISCONNECT - FULL CLEANUP"]
109+
DISCONNECT --> DC1[Flush all pending batches]
110+
DC1 --> DC2[Stop unified RX listening]
111+
DC2 --> DC3[Clear RX log entries]
112+
DC3 --> DC4[Clear rxBatchBuffer]
113+
DC4 --> DC5[Cancel all pending timeouts]
114+
end
115+
116+
B2 --> C
117+
X -.->|"30s later"| TIMEOUT
118+
119+
style INIT fill:#e3f2fd
120+
style RECEIVE fill:#fff8e1
121+
style UNIFIED fill:#f3e5f5
122+
style SESSION_LOG fill:#e8f5e9
123+
style PASSIVE fill:#fce4ec
124+
style BATCH_TRACK fill:#e0f2f1
125+
style FLUSH_DIST fill:#ffecb3
126+
style FLUSH_TIME fill:#ffecb3
127+
style FLUSH_END fill:#ffcdd2
128+
style FLUSH_PROCESS fill:#e8eaf6
129+
style LOOP fill:#eceff1
130+
style CLEANUP fill:#ffebee

‎docs/FLOW_WARDRIVE_TX_DIAGRAM.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
flowchart TD
2+
subgraph TRIGGER["🎯 TRIGGER"]
3+
A[/"User Clicks 'Send Ping'<br/>OR Auto Timer Fires"/]
4+
end
5+
6+
subgraph VALIDATION["✅ VALIDATION PHASE"]
7+
B{Cooldown Active? <br/>7s after last ping}
8+
B -->|YES| B_BLOCK[/"⛔ Block & Show Warning<br/>'Wait Xs before sending'"/]
9+
B -->|NO| C[📍 Get GPS Position<br/>lat, lon, accuracy]
10+
C --> D{Within 150km<br/>of Ottawa?}
11+
D -->|NO| D_SKIP[/"⚠️ Skip Ping<br/>reason: 'outside geofence'"/]
12+
D -->|YES| E{≥25m from<br/>last ping?}
13+
E -->|NO| E_SKIP[/"⚠️ Skip Ping<br/>reason: 'too close'"/]
14+
E -->|YES| F[✅ Validations Passed]
15+
end
16+
17+
subgraph BUILD["📦 BUILD PAYLOAD"]
18+
F --> G["Build Message: <br/>@[MapperBot] LAT, LON [PWR]"]
19+
end
20+
21+
subgraph TRANSMIT["📡 TRANSMIT TO MESH"]
22+
G --> H[Start Repeater Echo Tracking<br/>Initialize rx_log listener]
23+
H --> I[/"📤 SEND TO MESH<br/>sendChannelTextMessage()<br/>#wardriving channel"/]
24+
I --> J[Update UI: 'Ping sent' ✓<br/>Start 7s cooldown<br/>Log to Session]
25+
end
26+
27+
subgraph RX_WINDOW["👂 RX LISTENING WINDOW (10 seconds)"]
28+
J --> K[/"UI: 'Listening for heard repeats (Xs)'"/]
29+
K --> L{rx_log event<br/>received?}
30+
L -->|YES| M[Validate header 0x15]
31+
M --> N[Check channel hash match]
32+
N --> O[Decrypt & verify content]
33+
O --> P[Extract first hop repeater ID]
34+
P --> Q[Track SNR, dedupe by repeater<br/>Update UI chips in real-time]
35+
Q --> L
36+
L -->|10s elapsed| R[Stop Tracking<br/>Finalize Results]
37+
end
38+
39+
subgraph FINALIZE["📊 FINALIZE & POST"]
40+
R --> S["Format: '4e(11. 5),b7(-0.75)'"]
41+
S --> T[Update Session Log Entry<br/>with Heard Repeaters]
42+
T --> U[/"🕐 Hidden 3s delay"/]
43+
U --> V[/"📤 POST to MeshMapper API<br/>{key, lat, lon, who, power,<br/>heard_repeats, ver, session_id}"/]
44+
V --> W[Refresh Coverage Map<br/>if accuracy OK]
45+
end
46+
47+
subgraph NEXT["🔄 SCHEDULE NEXT"]
48+
W --> X{Auto Mode<br/>Active?}
49+
X -->|YES| Y[Schedule next ping<br/>15/30/60s]
50+
X -->|NO| Z[Idle]
51+
end
52+
53+
A --> B
54+
B_BLOCK -.-> A
55+
D_SKIP --> X
56+
E_SKIP --> X
57+
58+
style TRIGGER fill:#e1f5fe
59+
style VALIDATION fill:#fff3e0
60+
style BUILD fill:#f3e5f5
61+
style TRANSMIT fill:#e8f5e9
62+
style RX_WINDOW fill:#fce4ec
63+
style FINALIZE fill:#e0f2f1
64+
style NEXT fill:#f5f5f5

0 commit comments

Comments
 (0)