# 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
1. **Security Breach**: Microswitch opened (immediate response)
2. **Daily Report**: 24-hour timer for battery status
3. **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:**
```bash
# 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:**
```cpp
// Ensure unused pins are configured
pinMode(UNUSED_PIN, INPUT_PULLDOWN);  // Prevent floating
```

### 2. Firmware Programming

**Using Particle CLI:**
```bash
# 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:**
1. Go to [build.particle.io](https://build.particle.io)
2. Create new app "SecurityDevice"
3. Copy `security_device.ino` content
4. Click Flash button (lightning icon)
5. Select your Boron device

**Using Particle Workbench:**
1. Open VS Code with Particle Workbench
2. Create new Particle project
3. Copy firmware code
4. Use `Particle: Flash application (local)`

### 3. Device Configuration

**Claim Device:**
```bash
# 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:**
```bash
# 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
```cpp
// 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
```cpp
// 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:**
```cpp
const unsigned long DAILY_BATTERY_REPORT = 43200;  // 12-hour reports
const unsigned long CELLULAR_TIMEOUT = 30000;      // Faster timeout
```

**Remote/Outdoor Installation:**
```cpp
const unsigned long DAILY_BATTERY_REPORT = 86400;  // 24-hour reports
const unsigned long CELLULAR_TIMEOUT = 120000;     // Longer timeout
```

**Solar-Powered Installation:**
```cpp
const unsigned long DAILY_BATTERY_REPORT = 21600;  // 6-hour reports
const float LOW_BATTERY_THRESHOLD = 30.0;          // Higher threshold
```

## 🧪 Testing & Validation

### Bench Testing
```cpp
// 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
```bash
# 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)**
```cpp
// 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
```cpp
// 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**
1. Hold RESET button for 10+ seconds
2. Device enters safe mode (breathing magenta)
3. Flash firmware in safe mode
4. Use `particle device doctor` if needed

**OTA Update Failed**
```bash
# 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
```cpp
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
```cpp
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
- [Particle Documentation](https://docs.particle.io/)
- [Boron Datasheet](https://docs.particle.io/reference/datasheets/cellular/boron-datasheet/)
- [Cellular Guide](https://docs.particle.io/reference/cellular/)
- [Low Power Guide](https://docs.particle.io/reference/cloud-api/webhooks/)

---

**⚠️ 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