Files

stephenminakian baa45e9d47 Add Particle readme

2025-07-06 21:57:12 -06:00

14 KiB

Raw Blame History

Particle Boron LTE Security Device

Ultra-low-power security monitoring device using Particle Boron LTE with immediate local alarm response and 2+ year battery life.

🎯 Overview

This firmware transforms a Particle Boron LTE into a professional security monitoring device optimized for:

Ultra-low power consumption (130μA sleep current)
Immediate security response (sub-second alarm activation)
Long-term remote operation (2+ years on battery)
Reliable cellular communication (LTE-M/NB-IoT)

⚡ Power Performance

Power Consumption Breakdown

Sleep Mode (STOP):     130μA     (99% of time)
Wake & Process:        80mA      (10-15 seconds)
Cellular Connect:      300-800mA (30-60 seconds)
Alarm Active:          +50mA     (10 seconds)

Battery Life Estimates

5000mAh Li-Po: 2-3 years typical operation
10000mAh Li-Po: 4-5 years typical operation
With 6W Solar Panel: Indefinite operation

🔌 Hardware Requirements

Core Components

Particle Boron LTE (Gen 3) - Main controller
5000-10000mAh Li-Po Battery - Primary power
Microswitch (NC) - Security sensor
Alarm Device - Local deterrent (siren, buzzer, etc.)
Weatherproof Enclosure - Environmental protection

Pin Configuration

Boron Pin   Connection              Description
─────────────────────────────────────────────────────
D2          Microswitch Common      Security sensor input
GND         Microswitch NC          Normally closed contact
D3          Alarm Device +          Alarm output (with driver)
GND         Alarm Device -          Alarm ground
D7          Status LED (built-in)   Visual feedback
VIN         Battery + (3.7-12V)     Power input
GND         Battery -               Power ground

Microswitch Wiring (NC Configuration)

┌─────────────┐
│ Microswitch │
│             │
│   COM  NC   │ 
│    │   │    │
└────┼───┼────┘
     │   │
     │   └─── GND (Boron)
     │
     └─────── D2 (Boron)

State: CLOSED (normal) = D2 reads HIGH (pulled up)
State: OPEN (breach)   = D2 reads LOW (pulled to GND)

Alarm Device Options

Option A: Simple Buzzer (Low Power)

D3 ────┬─── Buzzer +
       │
      ┌▼┐
      │R│ 1kΩ resistor
      └┬┘
       │
      GND ─── Buzzer -

Option B: High Power Siren (Recommended)

D3 ────┬─── 1kΩ ─── Base (2N2222 NPN)
       │
      GND         Emitter
                     │
                    GND
                  
                  Collector ──── Siren +
                  
VIN ──────────────────────────── Siren -

📡 Network Configuration

Cellular Requirements

LTE Coverage: Device requires LTE-M or NB-IoT coverage
Data Plan: 1-5MB per month typical usage
Signal Strength: Target -70dBm or better for reliability

Particle Cloud Integration

Events: Published to Particle Cloud as private events
Webhooks: Particle Cloud forwards to your webhook server
OTA Updates: Firmware updates delivered over cellular

🔋 Power Optimization Features

Sleep Strategy

STOP Mode: Ultra-low power sleep (130μA)
24-Hour Wake Cycle: Daily battery reports
Pin Interrupt Wake: Immediate wake on security breach
Cellular Management: Radio only active when needed

Wake Scenarios

Security Breach: Microswitch opened (immediate response)
Daily Report: 24-hour timer for battery status
Cold Start: Device power-on or reset

Battery Management

Proactive Monitoring: Daily battery level reports
Low Battery Alerts: 20% and 10% thresholds
Critical Shutdown: Auto-sleep at 5% to prevent damage
Solar Ready: Supports solar charging systems

🛡️ Security Features

Immediate Response

Local Alarm: Activates before any network activity
Sub-Second Response: <1 second from trigger to alarm
Guaranteed Duration: 10-second minimum alarm time
Network Independent: Works even without cellular coverage

Tamper Detection

Boot Counting: Tracks device resets and power cycles
Startup Alerts: Notifications when device restarts
Firmware Tracking: Version monitoring for security
Signal Monitoring: Cellular quality tracking

Data Security

Private Events: All Particle.publish() calls use PRIVATE flag
Encrypted Transport: All cellular communication encrypted
Webhook Authentication: Server validates device authenticity
No Local Storage: No sensitive data stored on device

🚀 Installation Guide

1. Hardware Assembly

Basic Wiring:

# Connect microswitch (NC configuration)
# Common terminal → D2
# NC terminal → GND

# Connect alarm device (with driver circuit)
# Control signal → D3
# Power and ground as appropriate

# Connect battery
# Li-Po + → VIN (3.7V nominal)
# Li-Po - → GND

Power Optimization:

// Ensure unused pins are configured
pinMode(UNUSED_PIN, INPUT_PULLDOWN);  // Prevent floating

2. Firmware Programming

Using Particle CLI:

# Install Particle CLI
npm install -g particle-cli

# Login to your account
particle login

# Flash the firmware
particle flash your-device-name security_device.ino

# Monitor device events
particle subscribe mine

Using Particle Web IDE:

Go to build.particle.io
Create new app "SecurityDevice"
Copy security_device.ino content
Click Flash button (lightning icon)
Select your Boron device

Using Particle Workbench:

Open VS Code with Particle Workbench
Create new Particle project
Copy firmware code
Use Particle: Flash application (local)

3. Device Configuration

Claim Device:

# Claim device to your account
particle device add YOUR_DEVICE_ID

# Set device name
particle device rename YOUR_DEVICE_ID "Security-Device-01"

# Check device status
particle list

Verify Connectivity:

# Check device online status
particle get YOUR_DEVICE_ID connected

# Monitor device events
particle subscribe YOUR_DEVICE_ID

📊 Monitoring & Diagnostics

Event Types

The device publishes these event types to monitor health and security:

Security Events:

SECURITY_BREACH: Microswitch opened (intruder detected)
MOTION_CLEARED: Security sensor returned to normal (optional)

System Events:

DEVICE_STARTUP: Device powered on or reset
DAILY_BATTERY_REPORT: 24-hour battery status
LOW_BATTERY: Battery below 20%
CRITICAL_BATTERY: Battery below 10%

Data Format

// Example event data format:
"Type:SECURITY_BREACH|Desc:Microswitch opened|Batt:85.2%|Signal:-45|Quality:3|Boot:15|Alarm:ON"

Status LED Patterns

Startup:           3 slow blinks (500ms each)
Security Breach:   5 rapid blinks (100ms each)
Daily Report:      2 medium blinks (200ms each)
Cellular Connect:  Alternating blink during connection
Success:           2 quick blinks (100ms each)
Error:             10 rapid blinks (50ms each)

🔧 Configuration Options

Adjustable Parameters

// Sleep and wake timing
const unsigned long DAILY_BATTERY_REPORT = 86400; // 24 hours
// Options: 43200 (12h), 172800 (48h)

// Alarm behavior
const unsigned long ALARM_DURATION = 10000; // 10 seconds
// Options: 5000 (5s), 15000 (15s), 30000 (30s)

// Connection timeouts
const unsigned long CELLULAR_TIMEOUT = 60000; // 60 seconds
// Options: 30000 (30s), 120000 (2min)

// Battery thresholds
const float LOW_BATTERY_THRESHOLD = 20.0;      // 20%
const float CRITICAL_BATTERY_THRESHOLD = 10.0; // 10%

Environment-Specific Tuning

Indoor Installation:

const unsigned long DAILY_BATTERY_REPORT = 43200;  // 12-hour reports
const unsigned long CELLULAR_TIMEOUT = 30000;      // Faster timeout

Remote/Outdoor Installation:

const unsigned long DAILY_BATTERY_REPORT = 86400;  // 24-hour reports
const unsigned long CELLULAR_TIMEOUT = 120000;     // Longer timeout

Solar-Powered Installation:

const unsigned long DAILY_BATTERY_REPORT = 21600;  // 6-hour reports
const float LOW_BATTERY_THRESHOLD = 30.0;          // Higher threshold

🧪 Testing & Validation

Bench Testing

// Add to setup() for testing mode
#define TESTING_MODE
#ifdef TESTING_MODE
void testMode() {
    Serial.begin(9600);
    Serial.println("Security Device Test Mode");
    
    // Test all functions
    testMicroswitch();
    testAlarm();
    testCellularConnection();
    testBatteryReporting();
}
#endif

Field Testing Checklist

Microswitch Operation: NC switch triggers properly
Alarm Activation: Immediate response (<1 second)
Cellular Connection: Reliable within 60 seconds
Event Publishing: Particle Console shows events
Power Consumption: Measure sleep current (target: 130μA)
Battery Life: Validate projected consumption
Signal Strength: Check installation location (-70dBm target)
Weather Resistance: Verify enclosure sealing

Production Validation

# Monitor power consumption
particle get YOUR_DEVICE_ID vitals

# Check cellular signal
particle get YOUR_DEVICE_ID signal

# Verify event publishing
particle subscribe YOUR_DEVICE_ID

# Test security trigger
# (Manually open microswitch and verify alarm + event)

🚨 Troubleshooting

Common Issues

Device Won't Sleep (High Power Consumption)

// Check for blocking code
Serial.println("Checking sleep conditions...");
Serial.println("Cellular ready: " + String(Cellular.ready()));
Serial.println("Particle connected: " + String(Particle.connected()));

// Remove Serial calls in production!

Microswitch Not Triggering

Verify NC (normally closed) wiring
Check switch mechanical operation
Test continuity: closed = 0Ω, open = ∞Ω
Confirm pullup resistor configuration

Cellular Connection Issues

Check signal strength at installation site
Verify SIM card activation and data plan
Test with external antenna if signal weak
Monitor connection timeout settings

Alarm Not Activating

Verify D3 output voltage (3.3V when HIGH)
Check alarm device power requirements
Test driver circuit with multimeter
Confirm alarm device functionality

High Data Usage

Reduce event publishing frequency
Check for unnecessary Particle.publish() calls
Monitor cellular data usage in console
Optimize alert message size

Debug Mode

// Enable for development only (remove in production)
#define DEBUG_MODE
#ifdef DEBUG_MODE
void debugLog(String message) {
    Serial.println(String(millis()) + ": " + message);
}
#endif

Recovery Procedures

Device Stuck/Unresponsive

Hold RESET button for 10+ seconds
Device enters safe mode (breathing magenta)
Flash firmware in safe mode
Use particle device doctor if needed

OTA Update Failed

# Force update via USB
particle flash --usb security_device.ino

# Or use DFU mode
# Hold SETUP + RESET, release RESET, wait for yellow, release SETUP
particle flash --usb tinker  # Reset to Tinker
particle flash YOUR_DEVICE_ID security_device.ino  # Reflash

📈 Performance Optimization

Power Optimization

Minimize wake time: Keep cellular connection brief
Efficient data format: Compact message structure
Smart reconnection: Avoid unnecessary connection attempts
Sleep verification: Ensure proper STOP mode entry

Network Optimization

Message compression: Use abbreviated field names
Batch operations: Multiple sensor readings per message
Connection reuse: Minimize connect/disconnect cycles
Retry logic: Smart exponential backoff

Battery Life Extension

Solar integration: 6W+ panel for indefinite operation
Temperature management: Avoid extreme temperature exposure
Maintenance schedule: Proactive battery replacement
Load management: Optimize alarm duty cycle

🔄 Over-The-Air Updates

Safe OTA Practices

void checkForUpdates() {
    if (Particle.connected()) {
        // Allow time for OTA during startup
        unsigned long otaWindow = millis();
        while (millis() - otaWindow < 30000) {  // 30 second window
            Particle.process();
            delay(100);
        }
    }
}

Version Management

const String FIRMWARE_VERSION = "1.0.0";

void publishStartupAlert() {
    String data = String::format(
        "Type:DEVICE_STARTUP|FW:%s|Batt:%.1f%%",
        FIRMWARE_VERSION.c_str(),
        System.batteryCharge()
    );
    Particle.publish("Security Alert", data, PRIVATE);
}

📚 Additional Resources

Documentation

Power Analysis: docs/power-analysis.md
Hardware Guide: docs/hardware-guide.md
Troubleshooting: docs/troubleshooting.md
Performance Tuning: docs/performance-tuning.md

External Resources

⚠️ Important Notes:

Remove all Serial debugging code in production builds
Test thoroughly before deploying to remote locations
Always include physical access for emergency maintenance
Follow local regulations for security devices and alarms

14 KiB Raw Blame History