BPV4 CollarEVAL

Bluepaws V4

Unified firmware repository for the Bluepaws animal tracker system. Both the transmitting collar and receiving home hub share a single codebase with a common TLV binary protocol and configuration library.

System Overview

Data paths:

• Collar -> LoRa -> Home Hub -> log + display -> WiFi -> Cloud
• Collar -> LTE-M/NB-IoT -> Cloud via REST POST

Battery target: 30+ days at 10-minute wake intervals.

Hardware

The Sequans GM02SP replaces the previous BG77 + L76K combination. A single module handles both cellular IoT and GPS positioning, simplifying the collar BOM and reducing power draw.

Independent Walter LTE testbed

The separate walter PlatformIO target exercises real GM02SP LTE/GNSS on an ESP32-S3 Walter board, with a simulated LoRa transmit step and its own independent collar ID 1010. It does not replace or alter the WisMesh collar firmware. See Walter setup and commissioning before provisioning credentials or flashing. It boots idle and is not a default build/upload target.

Repository Structure

The top level is organised by responsibility. Firmware stays under the physical product it runs on; the two Home Hub implementations are grouped together so that hub and home-hub no longer appear to be separate products.

BluepawsV4/
├── README.md                         # Repository overview
├── docs/
│   ├── protocol/                     # Wire formats and commands
│   ├── firmware/collar/              # Collar design and test notes
│   ├── firmware/home-hub/            # Home Hub design and test notes
│   ├── operations/                   # Runbooks and release readiness
│   └── development/                  # Environment strategy and backlog
├── pcb/collar/                       # Collar PCB projects and vendor libraries
├── platformio.ini                    # Multi-environment build config
├── shared/lib/BluepawsProtocol/      # Shared protocol & config
│   ├── README.md                     # Protocol implementation notes
│   ├── library.json                  # PlatformIO library manifest
│   ├── bp_protocol.h                 # Shared protocol implementation header
│   └── bp_config.h                   # LoRa params, profiles, timing
├── collar/                           # nRF52840 collar firmware
│   ├── src/main.cpp
│   └── include/collar_pins.h
├── hub/                              # All Home Hub implementations
│   ├── platformio/                   # Heltec ESP32-S3 prototype + LittleFS UI
│   ├── esp-idf-p4/                   # ESP32-P4 production testbed
│   ├── maps/                         # Offline map-pack inputs and guidance
│   └── tests/esp-idf-p4/             # Host tests for the P4 core
├── diagnostics/

Web GUI

The hub serves a real-time tracking dashboard over WiFi, built with Leaflet.js and Server-Sent Events (SSE).

Device Cards - each tracked animal gets a card in the left sidebar showing:

• Unique emoji avatar with colour-coded ring (auto-assigned per device)
• Last GPS coordinates in monospace
• Status badge (Home / Out / Lost / Error)
• Telemetry grid: profile, battery %, signal strength, GPS accuracy, distance from home, last seen
• Jump - centres map on the animal at zoom 17
• Follow - auto-pans the map as new positions arrive
• Trail - toggles breadcrumb polyline on/off per device
• Cmd - opens command modal

Map Features:

• Three base layers: Street (OSM), Satellite (Esri), Topographic
• Per-device coloured trail lines with dashed polylines
• Lost-mode markers pulse red
• Measurement tool
• Dark / light theme toggle

Connection Monitoring:

• Server sends SSE heartbeat every 5 seconds
• Client watchdog flips to "No heartbeat" if 10 seconds pass without any event
• Status banner shows Connected or Disconnected

Mock Server

Simulates animals with live SSE telemetry for local GUI development:

node tools/mock-server.js
# http://localhost:3000
# Streams position updates every 2s + heartbeat every 5s

Customer Web App

web/ contains the Vercel-ready Next.js and TypeScript refactor of the hub dashboard. It preserves the embedded GUI in hub/platformio/data/, reads the latest live positions from Supabase by default, and confines mock telemetry to tutorial mode.

cd web
npm install
npm run dev

For Vercel, import this repository and select web as the project Root Directory. Leave the Install, Build, and Output settings at their detected Next.js defaults. See web/README.md for the exact deployment settings and the planned HTTPS Edge Function -> Supabase -> Realtime data path.

The cloud ingestion schema, device registry, and authenticated Edge Function are under supabase/. See tools/VPS_SIMULATOR.md for the Ubuntu VPS client and tools/TLV_SIMULATOR_GUI.md for the desktop packet-builder and manual HTTPS test console.

Development and Production Environments

The existing Supabase BluepawsV4 project is the permanent DEV/Test environment. Production will use a separate clean Supabase project reconstructed from the version-controlled migrations in this repository. Development and simulator data must not be migrated into production.

The same GitHub repository and Vercel project are used for both environments, with Vercel environment configuration selecting the appropriate Supabase project.

See:

• docs/development/DEV_TO_PROD_STRATEGY.md for the authoritative promotion strategy and decision record.
• docs/development/ENVIRONMENT_MATRIX.md for DEV vs PROD separation rules.
• docs/operations/PRODUCTION_READINESS_CHECKLIST.md for the pre-launch security and operational checklist.

TLV Protocol v1.2

The canonical protocol document is:

docs/protocol/TLV_PROTOCOL_V1_2.md

The system is moving away from production JSON telemetry. JSON remains useful for debugging, logs, exports and admin APIs, but LoRa and cellular telemetry should use the compact binary TLV packet.

Locked packet shape:

[32-byte fixed header][0-24 bytes TLV][8-byte HMAC-SHA256 tag]

Packet size:

minimum = 40 bytes
maximum = 64 bytes

Fixed header summary

The 8-byte tag is the first eight bytes of HMAC-SHA256 over the complete header and TLV section. The same authenticated binary packet is preserved across LoRa and LTE paths; path-specific RF and gateway details live only in the HTTPS JSON wrapper. See the canonical document for enums, selected TLVs, validation rules and examples.

Message Flow

Collar --LoRa--> Hub --REST POST--> Cloud
Collar --LTE-M/Cat-M1 REST POST--> Cloud

Both paths preserve the original authenticated packet, including (device_guid16, msg_seq_id, time_unix). The hub relays the collar bytes without changing them. Redundancy is intentional for reliability.

Canonical retry deduplication is handled in the cloud using:

SHA-256(complete authenticated packet)

Reuse of (device_guid16, msg_seq_id, time_unix) with different packet content is treated as an identity conflict rather than an overwrite.

Hub CSV or debug log format should be derived from decoded TLV fields, not treated as the production on-air format.

Building

Requires PlatformIO.

# Build both targets
pio run

# Build collar only
pio run -e collar

# Build hub only
pio run -e hub

# Upload to connected device
pio run -e collar -t upload
pio run -e hub -t upload

Operating Profiles