477 lines
14 KiB
Markdown
477 lines
14 KiB
Markdown
# 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 |