Skip to content

Commit aa6bf2c

Browse files
dorkmodorkmo
authored
Implement fleet-based communication for Tank Alarm system, replacing manual route configuration. Added documentation for setup, migration, and device-to-device API. Updated client and server firmware to support new fleet structure, enhancing deployment efficiency and scalability.
1 parent 985c304 commit aa6bf2c

File tree

8 files changed

+1313
-18
lines changed

8 files changed

+1313
-18
lines changed

‎QUICK_REFERENCE_FLEET_SETUP.md‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# Quick Reference: Fleet-Based vs Route-Based Setup
2+
3+
## At a Glance
4+
5+
| Aspect | Route-Based (OLD) | Fleet-Based (NEW) ✅ |
6+
|--------|------------------|---------------------|
7+
| **Notehub Setup** | Create 4-5 manual routes | Create 2 fleets, assign devices |
8+
| **Setup Time** | ~20 minutes | ~5 minutes |
9+
| **Client Config Field** | `serverRoute` | `serverFleet` |
10+
| **Client Sends To** | Local `.qo` file | `fleet.<name>:<file>.qi` |
11+
| **Server Sends To** | Local `.qo` file + device param | `device:<uid>:<file>.qi` |
12+
| **Scaling** | Create route for each flow | Just assign new devices to fleet |
13+
| **Maintenance** | Update routes when changing flows | No maintenance needed |
14+
15+
## Communication Cheat Sheet
16+
17+
### Client Notefiles
18+
```cpp
19+
// Telemetry
20+
"fleet.tankalarm-server:telemetry.qi"
21+
22+
// Alarms
23+
"fleet.tankalarm-server:alarm.qi"
24+
25+
// Daily Reports
26+
"fleet.tankalarm-server:daily.qi"
27+
```
28+
29+
### Server Notefiles
30+
```cpp
31+
// Config to specific client
32+
"device:<client-uid>:config.qi"
33+
34+
// Config to all clients (broadcast)
35+
"fleet.tankalarm-clients:config.qi"
36+
```
37+
38+
## Setup Commands
39+
40+
### Notehub Fleet Creation
41+
1. **Create Server Fleet:**
42+
- Name: `tankalarm-server`
43+
- Assign: 1 server Notecard
44+
45+
2. **Create Client Fleet:**
46+
- Name: `tankalarm-clients`
47+
- Assign: All client Notecards
48+
49+
### Configuration Fields
50+
51+
**Client (`serverFleet`):**
52+
```json
53+
{
54+
"serverFleet": "tankalarm-server"
55+
}
56+
```
57+
58+
**Server (`clientFleet`):**
59+
```json
60+
{
61+
"clientFleet": "tankalarm-clients"
62+
}
63+
```
64+
65+
## Common Issues & Fixes
66+
67+
| Problem | Cause | Solution |
68+
|---------|-------|----------|
69+
| No telemetry on server | Wrong `serverFleet` value | Update client config via server UI |
70+
| Config not reaching client | Wrong device UID | Copy UID from Notehub device page |
71+
| Client not in dropdown | Not in fleet | Assign client to `tankalarm-clients` fleet |
72+
| Notes not syncing | Notecard offline | Check `card.wireless` status |
73+
74+
## Migration Checklist
75+
76+
- [ ] Create fleets in Notehub
77+
- [ ] Assign devices to fleets
78+
- [ ] Upload new client firmware
79+
- [ ] Upload new server firmware
80+
- [ ] Update client configs (change `serverFleet`)
81+
- [ ] Test telemetry flow
82+
- [ ] Test config updates
83+
- [ ] Test alarm flow
84+
- [ ] Disable old routes (optional)
85+
86+
## Key Code Changes
87+
88+
### Client: publishNote()
89+
```cpp
90+
// OLD
91+
JAddStringToObject(req, "file", fileName); // e.g., "telemetry.qo"
92+
93+
// NEW
94+
char targetFile[80];
95+
snprintf(targetFile, sizeof(targetFile), "fleet.%s:%s",
96+
gConfig.serverFleet, fileName);
97+
JAddStringToObject(req, "file", targetFile);
98+
// Result: "fleet.tankalarm-server:telemetry.qi"
99+
```
100+
101+
### Server: dispatchClientConfig()
102+
```cpp
103+
// OLD
104+
JAddStringToObject(req, "file", CONFIG_OUTBOX_FILE); // "config.qo"
105+
JAddStringToObject(req, "device", clientUid);
106+
107+
// NEW
108+
char targetFile[80];
109+
snprintf(targetFile, sizeof(targetFile), "device:%s:config.qi", clientUid);
110+
JAddStringToObject(req, "file", targetFile);
111+
// Result: "device:dev:1234...abcd:config.qi"
112+
```
113+
114+
## Documentation Map
115+
116+
```
117+
📁 Documentation Structure
118+
├── FLEET_SETUP.md ← Start here for new deployments
119+
├── DEVICE_TO_DEVICE_API.md ← Technical details & API docs
120+
├── MIGRATION_GUIDE.md ← Existing system migration
121+
├── FLEET_IMPLEMENTATION_SUMMARY.md ← Complete change summary
122+
└── SETUP.md (deprecated) ← Old route-based method
123+
```
124+
125+
## Quick Troubleshooting
126+
127+
**Enable Debug Output:**
128+
```cpp
129+
notecard.setDebugOutputStream(Serial);
130+
```
131+
132+
**Check Notecard Status:**
133+
```json
134+
{"req":"card.wireless"}
135+
{"req":"hub.status"}
136+
{"req":"hub.sync"}
137+
```
138+
139+
**View Notehub Events:**
140+
1. Log in to https://notehub.io
141+
2. Select project
142+
3. Click **Events**
143+
4. Filter by device UID
144+
5. Look for note traffic
145+
146+
**Verify Fleet Assignment:**
147+
1. Notehub → **Devices**
148+
2. Click on device
149+
3. Check **Fleets** section
150+
4. Should show assigned fleet name
151+
152+
## Additional Resources
153+
154+
- **Blues Dev Portal:** https://dev.blues.io
155+
- **Fleet API Docs:** https://dev.blues.io/reference/notehub-api/fleet-api/
156+
- **Arduino Opta Docs:** https://docs.arduino.cc/hardware/opta
157+
- **Notecard API Reference:** https://dev.blues.io/api-reference/notecard-api/
158+
159+
## Support
160+
161+
**Serial Console Checks:**
162+
```
163+
✓ "Notecard UID: dev:..." - Device identified
164+
✓ "Server setup complete" - Server ready
165+
✓ "Received config update" - Client got config
166+
✓ "Publishing telemetry" - Client sending data
167+
```
168+
169+
**Notehub Event Checks:**
170+
```
171+
✓ Client events show "fleet.tankalarm-server:*.qi"
172+
✓ Server events show incoming "*.qi" notes
173+
✓ Server events show "device:<uid>:config.qi" outbound
174+
✓ Recent timestamps on all events
175+
```
176+
177+
---
178+
179+
**Last Updated:** November 2025
180+
**Version:** 112025 Opta Release

‎TankAlarm-112025-Client-BluesOpta/DEVICE_TO_DEVICE_API.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# Device-to-Device Communication Without Manual Routes
2+
3+
## Overview
4+
5+
This implementation eliminates the need for manually configured routes in Blues Notehub by using **fleet-based note targeting** and the Notecard's built-in device-to-device communication capabilities.
6+
7+
## How It Works
8+
9+
### Traditional Route-Based Approach (OLD)
10+
1. Client sends note to `telemetry.qo`
11+
2. Notehub route manually configured to forward `telemetry.qo` → server device `telemetry.qi`
12+
3. Server polls `telemetry.qi` for incoming data
13+
4. **Problem**: Requires manual route setup in Notehub web interface for each note file type
14+
15+
### Fleet-Based API Approach (NEW)
16+
1. Client and server Notecards are organized into **Fleets** in Notehub
17+
2. Client sends notes to **fleet-scoped notefile** using special syntax
18+
3. Notes automatically delivered to all devices in target fleet
19+
4. **Benefit**: No manual route configuration needed - just fleet membership
20+
21+
## Implementation Strategy
22+
23+
### Method 1: Fleet-to-Fleet Communication (Recommended)
24+
25+
Blues Notecard supports sending notes to a fleet using the format: `<fleet>:<notefile>`.
26+
27+
**Client sends to server fleet:**
28+
```cpp
29+
// Instead of:
30+
// note.add to "telemetry.qo" with route configuration
31+
32+
// Use fleet targeting:
33+
J *req = notecard.newRequest("note.add");
34+
JAddStringToObject(req, "file", "fleet.server:telemetry.qi");
35+
JAddItemToObject(req, "body", body);
36+
notecard.sendRequest(req);
37+
```
38+
39+
**Server receives from any fleet member:**
40+
```cpp
41+
// Server just polls local notefile - Notehub delivers automatically
42+
J *req = notecard.newRequest("note.get");
43+
JAddStringToObject(req, "file", "telemetry.qi");
44+
JAddBoolToObject(req, "delete", true);
45+
J *rsp = notecard.requestAndResponse(req);
46+
```
47+
48+
### Method 2: Device-Specific Targeting
49+
50+
For server-to-client config updates, target specific device UID:
51+
52+
```cpp
53+
// Server sends config to specific client device
54+
J *req = notecard.newRequest("note.add");
55+
char targetFile[80];
56+
snprintf(targetFile, sizeof(targetFile), "device:%s:config.qi", clientDeviceUID);
57+
JAddStringToObject(req, "file", targetFile);
58+
JAddItemToObject(req, "body", configBody);
59+
notecard.sendRequest(req);
60+
```
61+
62+
### Method 3: Project-Wide Notefiles
63+
64+
Use project-level notefiles that all devices can access:
65+
66+
```cpp
67+
// Client publishes to project-level notefile
68+
J *req = notecard.newRequest("note.add");
69+
JAddStringToObject(req, "file", "project:telemetry");
70+
// Add device UID in body so server knows source
71+
J *body = JCreateObject();
72+
JAddStringToObject(body, "device", gDeviceUID);
73+
// ... add other data ...
74+
JAddItemToObject(req, "body", body);
75+
notecard.sendRequest(req);
76+
```
77+
78+
## Setup Requirements
79+
80+
### In Blues Notehub:
81+
82+
1. **Create Fleets:**
83+
- Fleet: `tankalarm-clients` (for all field devices)
84+
- Fleet: `tankalarm-server` (for base station)
85+
86+
2. **Assign Devices to Fleets:**
87+
- Navigate to Devices
88+
- Select each client Notecard → assign to `tankalarm-clients` fleet
89+
- Select server Notecard → assign to `tankalarm-server` fleet
90+
91+
3. **Done!** No route configuration needed.
92+
93+
### In Device Configuration:
94+
95+
**Client devices:**
96+
- Store the server fleet name (e.g., "tankalarm-server") in configuration
97+
- Use `fleet.tankalarm-server:<filename>` syntax when publishing
98+
99+
**Server device:**
100+
- Poll local notefiles (`.qi` files) - Notehub automatically delivers
101+
- Store client fleet name for broadcasting config updates
102+
103+
## Notefile Naming Convention
104+
105+
| Communication | Old Route-Based | New Fleet-Based |
106+
|---------------|-----------------|-----------------|
107+
| Client → Server telemetry | `telemetry.qo` → route → server `telemetry.qi` | `fleet.tankalarm-server:telemetry.qi` |
108+
| Client → Server alarm | `alarm.qo` → route → server `alarm.qi` | `fleet.tankalarm-server:alarm.qi` |
109+
| Client → Server daily | `daily.qo` → route → server `daily.qi` | `fleet.tankalarm-server:daily.qi` |
110+
| Server → Client config | `config.qo` → route → client `config.qi` | `device:<uid>:config.qi` or `fleet.tankalarm-clients:config.qi` |
111+
112+
## Benefits
113+
114+
1. **Zero Route Configuration**: No manual route setup in Notehub web interface
115+
2. **Easier Deployment**: Just assign devices to fleets
116+
3. **Scalable**: Add new clients by assigning them to client fleet
117+
4. **Flexible**: Can target specific devices or broadcast to entire fleet
118+
5. **Resilient**: Fleet membership managed in Notehub, survives device replacement
119+
120+
## Configuration Changes Needed
121+
122+
### Client Configuration (config.json)
123+
```json
124+
{
125+
"deviceLabel": "Tank01",
126+
"serverFleet": "tankalarm-server",
127+
// Remove: "serverRoute": "default-route"
128+
...
129+
}
130+
```
131+
132+
### Server Configuration (server_config.json)
133+
```json
134+
{
135+
"serverLabel": "TankAlarmServer",
136+
"clientFleet": "tankalarm-clients",
137+
...
138+
}
139+
```
140+
141+
## Migration Path
142+
143+
1. Create fleets in Notehub
144+
2. Assign devices to appropriate fleets
145+
3. Update client and server firmware with new fleet-based code
146+
4. Deploy updated firmware
147+
5. Verify communication works
148+
6. Delete old routes from Notehub (optional, for cleanup)
149+
150+
## Troubleshooting
151+
152+
**Notes not arriving at server:**
153+
- Verify server Notecard is in `tankalarm-server` fleet
154+
- Check client configuration has correct `serverFleet` name
155+
- Use Notehub Events view to see if notes are being sent
156+
- Confirm continuous mode enabled on both devices
157+
158+
**Config updates not reaching clients:**
159+
- Verify clients are in correct fleet
160+
- Check server is using correct fleet name or device UID
161+
- For device-specific targeting, ensure UID is correct (use `card.uuid` response)
162+
163+
**General debugging:**
164+
- Enable Notecard debug output: `notecard.setDebugOutputStream(Serial);`
165+
- Check Notehub Events for each device to see note traffic
166+
- Verify both devices have recent sync timestamps
167+
168+
## Hardware Requirements
169+
170+
- **Client**: Arduino Opta Lite + Blues Wireless for Opta adapter + analog extension (unchanged)
171+
- **Server**: Arduino Opta Lite + Blues Wireless for Opta adapter (unchanged)
172+
173+
No additional hardware needed - this is purely a software/configuration change.
174+
175+
## References
176+
177+
- [Blues Wireless Fleet Documentation](https://dev.blues.io/reference/notehub-api/fleet-api/)
178+
- [Notecard note.add API](https://dev.blues.io/api-reference/notecard-api/note-requests/#note-add)
179+
- [Device-to-Device Communication](https://dev.blues.io/guides-and-tutorials/routing-data-to-cloud/device-to-device/)

0 commit comments

Comments
 (0)