Skip to content
/ ArgusLink Public

An asset locator project using the XIAO ESP32S3-Sense camera with front-end dashboard.

License

MIT license
1 star 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

GavinnnTann/ArgusLink

BranchesTags

Repository files navigation

This is the readme file about the entire project

ArgusLink - Intelligent Asset Management System

License: MIT Platform Status

Full-stack IoT-based Asset Management Project

A comprehensive IoT-based asset management solution for facilities, combining ESP32-CAM QR code scanning, WiFi-based zone detection, and real-time web dashboard monitoring.

Project Overview

ArgusLink automates asset location tracking in facilities using:

  • ESP32-CAM devices for autonomous QR code scanning with camera vision
  • WiFi fingerprinting fallback for location detection when QR scanning fails
  • Real-time dashboard for facility managers to monitor asset locations
  • Departure intent detection using ignition signal monitoring
  • Automatic state management with PostgreSQL triggers and scheduled jobs

Problem Statement

Traditional asset management relies on manual tracking, leading to:

  • Time wasted searching for assets
  • Inefficient space utilization
  • Difficulty tracking asset movements during shift changes
  • No historical data for optimization

"How might we enable fast, reliable, and low-cost indoor observability of assets in facilities, such that staff can identify the exact asset location within seconds without relying on manual searching or expensive sensing systems?"

Solution

ArgusLink provides automated, real-time tracking with:

  • Deterministic positioning using QR code as primary detection
  • Automatic WiFi fallback when QR scan fails (30-second timeout)
  • Real-time updates every 5 seconds
  • Mobile-responsive dashboard accessible from any device
  • Departure detection with automatic state transitions

ArgusLink Workflow

System Architecture

ArgusLink System Architecture

Key Features

ESP32-CAM Firmware

  • Dual-Mode Operation
    • 🔴 Departure Mode (Ignition ON): Sends departure intent, enters deep sleep
    • 🟢 Parking Mode (Ignition OFF): QR scanning with 30s timeout → WiFi fallback
  • QR Code Scanner
    • Format: XXX-LY-ZZZ (Location-Level-Lot)
    • Example: ABC-L3-045 = Amplitude Best Company, Level 3, Lot 45
    • HIGH error correction (30% damage tolerance)
  • WiFi Zone Fallback
    • Automatic BSSID detection when QR scan times out
    • RSSI signal strength logging
    • Zone mapping to facility/floor/area
  • Diagnostic Mode
    • Web interface via WiFi AP mode
    • Live camera stream preview
    • Real-time statistics dashboard
  • Power Management
    • Deep sleep mode after successful scan
    • Wake on reset for next cycle

Supabase Backend

  • Real-Time Database
    • Event-driven architecture with triggers
    • Automatic state machine transitions
    • Historical event log with full audit trail
  • Smart State Management
    • PARKED → DEPARTURE_INTENT → DEPARTED flow
    • 120-second confirmation timeout
    • Automatic cleanup via pg_cron jobs
  • Dual Location Detection
    • Primary: High-confidence QR scans
    • Fallback: WiFi zone mapping (BSSID→Location)
  • Views & Functions
    • asset_current_state_view - Real-time asset locations with asset numbers
    • lot_current_state_view - Current lot occupancy
    • lot_summary_view - facility-wide occupancy statistics

Web Dashboard

  • Interactive Map View
    • Grid-based facility layout visualization
    • Color-coded status indicators
      • 🟢 Green: High confidence (QR scanned)
      • 🟠 Orange: Low confidence (WiFi fallback)
      • 🟡 Yellow: Departing
      • ⚪ Gray: Departed
    • Hover tooltips with detailed information
  • List View
    • Sortable table with all asset data
    • Real-time timestamp updates
    • Export-ready format
  • Advanced Filtering
    • Search by asset number
    • Filter by facility, floor, status
    • Collapsible panel on mobile
  • Responsive Design
    • Optimized for desktop and mobile
    • Touch-friendly controls
    • Auto-refresh every 5 seconds
    • Progressive Web App ready

Tech Stack

Hardware

Component Specification
MCU Seeed XIAO ESP32S3 Sense
Camera OV2640 5MP
WiFi 802.11 b/g/n
Power 3.3V via USB-C
Storage 8MB PSRAM

Firmware

  • Framework: Arduino Core for ESP32
  • Libraries:
    • ESP32QRCodeReader - QR code decoding
    • HTTPClient - API communication
    • WiFiClientSecure - HTTPS support
    • esp_camera - Camera control

Backend

  • Database: Supabase (PostgreSQL 14.1)
  • API: Supabase REST API
  • Functions: plpgsql stored procedures
  • Scheduling: pg_cron extension
  • Security: Row Level Security (RLS)

Frontend

  • Framework: Next.js 15.1.0 (React 18)
  • Language: TypeScript 5
  • Styling: Tailwind CSS 3.4.1
  • State: React Hooks (useState, useEffect, useMemo)
  • Client: Supabase SSR v0.5.2
  • Deployment: Vercel

Development Tools

  • ESP32: PlatformIO IDE
  • Python: qrcode, Pillow (QR generation)
  • Database: Supabase Dashboard
  • Version Control: Git

Project Structure

ArgusLink/Codes/
│
├── ArgusLink QR Scanner/          # ESP32-CAM firmware
│   ├── src/
│   │   ├── main.cpp                # Main firmware logic
│   │   └── app_httpd.cpp           # Diagnostic web server
│   ├── include/
│   │   ├── config.h                # Configuration constants
│   │   ├── camera_pins.h           # Hardware pin definitions
│   │   └── camera_index.h          # Web interface HTML
│   └── platformio.ini              # Build configuration
│
├── QR_Generator/                   # QR code generation tools
│   ├── generate_qr.py              # CLI batch generator
│   ├── qr_generator_gui.py         # Tkinter GUI interface
│   ├── requirements.txt            # Python dependencies
│   ├── supabase.ts                 # Database schema reference
│   └── qr_codes/                   # Generated QR images
│       └── *.png
│
└── ArgusLink-dashboard/                  # Next.js web dashboard
    ├── app/
    │   ├── page.tsx                # Main dashboard
    │   ├── layout.tsx              # App layout
    │   └── globals.css             # Global styles
    ├── package.json                # NPM dependencies
    ├── tsconfig.json               # TypeScript config
    ├── tailwind.config.ts          # Tailwind config
    ├── next.config.js              # Next.js config
    └── .env.local.example          # Environment template

Installation & Setup

Prerequisites

  • Hardware: Seeed XIAO ESP32S3 Sense with camera
  • Software:
    • PlatformIO IDE
    • Python 3.8+
    • Node.js 24.12.0+
    • Supabase account

1. Database Setup (Supabase)

Create Tables

-- Event log table
CREATE TABLE parking_scans (
    event_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    device_id VARCHAR(50) NOT NULL,
    event_type VARCHAR(20) NOT NULL,
    ts_utc TIMESTAMPTZ NOT NULL,
    bssid MACADDR NOT NULL,
    rssi INTEGER,
    qr_success BOOLEAN,
    raw VARCHAR(100),
    depot VARCHAR(10),
    floor INTEGER,
    lot INTEGER,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Current state table
CREATE TABLE asset_current_state (
    device_id VARCHAR(50) PRIMARY KEY,
    current_event_type VARCHAR(20),
    current_lot_id VARCHAR(20),
    current_depot VARCHAR(10),
    current_floor INTEGER,
    current_lot INTEGER,
    wifi_zone VARCHAR(20),
    wifi_zone_letter VARCHAR(1),
    wifi_level INTEGER,
    last_event_time TIMESTAMPTZ,
    qr_success BOOLEAN,
    last_rssi INTEGER
);

-- Device to asset mapping
CREATE TABLE device_asset_mapping (
    device_id VARCHAR(50) PRIMARY KEY,
    asset_number VARCHAR(20) UNIQUE NOT NULL
);

-- WiFi BSSID to location mapping
CREATE TABLE bssid_zone_mapping (
    bssid MACADDR PRIMARY KEY,
    zone VARCHAR(20),
    level INTEGER,
    zone_letter VARCHAR(1),
    depot VARCHAR(10)
);

-- layout master data
CREATE TABLE lots_master (
    id SERIAL PRIMARY KEY,
    depot VARCHAR(10) NOT NULL,
    floor INTEGER NOT NULL,
    lot_number INTEGER NOT NULL,
    UNIQUE(depot, floor, lot_number)
);

Create Triggers and Functions

See Supabase documentation for complete SQL scripts:

  • update_asset_current_state() trigger
  • update_lot_current_state() trigger
  • confirm_departures() cron job

2. ESP32 Firmware Setup

Configure WiFi and API

Edit include/config.h:

// WiFi credentials
#define WIFI_STA_SSID       "YourWiFiSSID"
#define WIFI_STA_PASSWORD   "YourPassword"

// Supabase configuration
#define SUPABASE_URL        "https://your-project.supabase.co"
#define SUPABASE_API_KEY    "your-anon-key"
#define API_ENDPOINT        SUPABASE_URL "/rest/v1/parking_scans"

// Device ID (unique per device)
#define DEVICE_ID           "ESP32S3-001"

Flash Firmware

cd ESP32_Cam_PlatformIO
pio run --target upload
pio device monitor

3. QR Code Generation

Install Python Dependencies

cd QR_Generator
pip install -r requirements.txt

Generate QR Codes

# CLI batch generation
python generate_qr.py --depot ABC --floors 3 --lots 50

# GUI interface
python qr_generator_gui.py

4. Web Dashboard Setup

Install Dependencies

cd asset-dashboard
npm install

Configure Environment

Create .env.local:

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

Run Development Server

npm run dev
# Access at http://localhost:3000

Deploy to Vercel

npm run build
# Deploy via Vercel CLI or GitHub integration

Security Considerations

ESP32 Firmware

  • HTTPS/TLS for API communication
  • API key authentication
  • NTP time synchronization for accurate timestamps
  • Deep sleep mode for power efficiency

Supabase Backend

  • Row Level Security (RLS) policies
  • Anon key with restricted permissions
  • Service role key for admin operations only
  • SECURITY INVOKER views for proper permission handling

Web Dashboard

  • Environment variables for sensitive keys
  • Client-side rate limiting
  • HTTPS only in production
  • CORS configuration

Database Schema

Key Tables

parking_scans (Event Log)

Stores all parking/departure events with full audit trail.

asset_current_state (Live State)

Current location and status of each asset, updated in real-time via triggers.

bssid_zone_mapping (WiFi Zones)

Maps WiFi access points to physical facility locations for fallback detection.

Key Views

asset_current_state_view

Joins asset state with asset numbers for dashboard display.

lot_current_state_view

Shows current occupancy status of each parking lot.

lot_summary_view

Aggregated statistics per facility for capacity monitoring.

QR Code Format

Structure: XXX-LY-ZZZ

Component Description Example Range
XXX Facility Code ABC 1-5 chars
L Literal "L" L Fixed
Y Floor Number 3 1-9
ZZZ Lot Number 045 001-999

Example

ABC-L3-045 = Amplitude Best Company, Level 3, Lot 045

Error Correction

  • Level: HIGH (30% recoverable)
  • Enables scanning at various angles and lighting conditions
  • Robust to partial damage or dirt

Dashboard Usage

Desktop View

  1. Map View: Visual grid showing facility layout with color-coded asset markers
  2. List View: Table with sortable columns and search functionality
  3. Filters: Sidebar with facility, floor, and status filters

Mobile View

  1. Tap "Filters" button to show/hide filter panel
  2. Use tabs to switch between Map and List views
  3. Touch asset markers for details

Status Indicators

  • 🟢 Green: High confidence (QR scanned)
  • 🟠 Orange: Low confidence (WiFi fallback)
  • 🟡 Yellow: Departing (engine ON, departure intent sent)
  • ⚪ Gray: Departed (confirmed after 120s)

Troubleshooting

ESP32 Issues

QR Scan Timeout

  • Check camera focus and lighting
  • Verify QR code format matches XXX-LY-ZZZ
  • System will automatically fall back to WiFi zone detection

WiFi Connection Failed

  • Verify SSID and password in config.h
  • Check WiFi signal strength
  • Device will retry connection automatically

API Error 400

  • Check Supabase URL and API key
  • Verify table structure matches schema
  • Check Supabase logs for detailed error

Dashboard Issues

No Data Showing

  • Verify .env.local configuration
  • Check Supabase API permissions (RLS policies)
  • Open browser console for error messages

Future Enhancements

  • Historical analytics dashboard
  • Predictive parking availability
  • Multi-facility management
  • Mobile app (React Native)
  • Driver mobile check-in app
  • SMS/Push notifications for dispatchers
  • Integration with fleet management systems
  • Advanced reporting and KPIs

License

MIT License - See LICENSE file for details

Contributors

  • Gavin Tan

Support

For issues, questions, or contributions:

  • Create an issue on GitHub

Acknowledgments

  • Seeed Studio for XIAO ESP32S3 platform
  • Supabase for backend infrastructure

About

An asset locator project using the XIAO ESP32S3-Sense camera with front-end dashboard.

Topics

nextjs esp32 platformio qrcode-scanner qrcode-generator

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages