Add Particle readme
This commit is contained in:
477
Particle/README.md
Normal file
477
Particle/README.md
Normal file
@ -0,0 +1,477 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user