MikeFaith/pi-pm3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add Dangerous Pi MVP implementation - complete backend and system integration

Browse Source 
This commit adds the complete Dangerous Pi web management interface with all MVP features implemented and tested locally.

## New Features

### Backend (Python + FastAPI)
- Complete FastAPI backend with async support
- 40+ API endpoints (Health, PM3, WiFi, Updates, UPS, BLE, Plugins)
- 6 managers: Session, WiFi, Update, UPS, BLE, Plugin
- SQLite database with sessions, config, history, crash reports
- Server-Sent Events (SSE) for real-time notifications
- Mock PM3 worker for development without hardware

### WiFi Manager
- Interface detection (USB vs built-in)
- Network scanning with signal strength
- Mode switching (AP/Client/Dual/Auto/Off)
- Network connection with password support
- Hidden SSID and saved networks support
- Static IP and DHCP configuration
- 10 WiFi API endpoints

### Update Manager
- GitHub releases API integration
- Automatic periodic update checks
- Semantic version comparison
- Update download with progress tracking
- SHA256 checksum verification
- Automatic installation with backup and rollback
- PM3 client rebuild after updates
- 6 Update API endpoints

### UPS Manager
- I2C battery monitoring (MAX17040-compatible)
- Battery percentage, voltage, current tracking
- Power source detection (AC/Battery)
- Safe shutdown triggers at configurable thresholds
- Event callbacks for battery warnings
- SSE and BLE notification integration
- 3 UPS API endpoints

### BLE Manager
- Bluetooth Low Energy notification support
- Auto-detects BLE capability
- Multiple notification types (updates, battery, shutdown, etc.)
- BLE advertising management
- Device connection tracking
- 4 BLE API endpoints

### Plugin Framework
- Dynamic plugin loading/unloading
- Plugin lifecycle management (load, enable, disable, unload)
- Hook system for extensibility
- JSON-based metadata
- Example "Hello World" plugin included
- 7 Plugin API endpoints

### Frontend (Remix.js + React)
- Cyberpunk-themed responsive UI
- Dashboard with system status
- PM3 command interface with history
- Settings page with WiFi and Update management
- Command logs viewer
- Theme toggle (Dark/Light/Auto)
- Server-side rendering (SSR)
- Mobile-first responsive design

### System Integration
- Systemd service with security hardening
- Automated install/uninstall scripts
- Environment configuration template
- Hardware access groups (i2c, bluetooth, gpio, dialout)
- Pi-gen stage 04 integration for OS image building
- Port conflict resolution with ttyd-bash
- I2C interface auto-enable for UPS HAT

### Testing
- test_backend.py - Backend API tests
- test_ups.py - UPS manager tests
- test_ble.py - BLE manager tests
- test_plugins.py - Plugin manager tests
- All tests passing locally

### Documentation
- 12 comprehensive documentation files
- claude.md - AI development guide
- WIFI_MANAGER.md - WiFi management guide
- UPDATE_MANAGER.md - Update system guide
- PORT_CONFLICT.md - Port conflict resolution guide
- MVP_COMPLETE.md - MVP implementation summary
- PROJECT_STATUS.md - Project status and roadmap
- systemd/README.md - Service management docs
- pi-gen integration documentation

## Technical Details
- ~5,000+ lines of backend code
- 11 Python dependencies (smbus2 added for UPS)
- FastAPI with async/await throughout
- Type hints and docstrings on all functions
- RESTful API design with SSE for notifications
- Security hardening (non-root, protected dirs, resource limits)

## Next Steps
- Deploy to Raspberry Pi Zero 2 W hardware
- Test with real Proxmark3 device
- Test UPS HAT integration
- Test BLE on Pi hardware
- Build custom OS image with pi-gen
- Performance optimization for Pi Zero 2 W

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
michael
2025-11-26 08:11:36 -08:00
parent 0a586c5360
commit 1da6730735
68 changed files with 12673 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

450
UI_GUIDELINES.md Normal file
View File

@@ -0,0 +1,450 @@
# Dangerous Pi - UI/UX Guidelines
## Design Philosophy
**Resource-Constrained Excellence**: Build a beautiful, functional interface that respects the Pi Zero 2 W's limited resources while providing an excellent user experience.
### Core Principles
1. **Performance First** - Every byte counts
2. **Progressive Enhancement** - Works without JavaScript, better with it
3. **Mobile-First** - Optimize for small screens (most users access via phone)
4. **Single-Purpose Focus** - One task at a time, clear hierarchy
5. **Instant Feedback** - Users should never wonder what's happening
---
## Technical Constraints
### Hardware Limitations
- **CPU**: Quad-core ARM Cortex-A53 @ 1GHz (limited)
- **RAM**: 512MB (shared with OS and backend)
- **Network**: WiFi only, potentially slow AP mode
- **Storage**: MicroSD (minimize writes)
### Performance Targets
- **First Contentful Paint**: < 1.5s
- **Time to Interactive**: < 3s
- **Total Bundle Size**: < 150KB (gzipped)
- **CSS**: < 20KB (gzipped)
- **Fonts**: System fonts only (no web fonts)
---
## Visual Design System
### Color Palette
```
Primary (Actions):
- Blue: #2563eb (buttons, links, active states)
- Blue Dark: #1e40af (hover states)
Status Colors:
- Success: #059669 (connected, completed)
- Warning: #d97706 (low battery, needs attention)
- Error: #dc2626 (disconnected, failed)
- Info: #0891b2 (notifications, tips)
Neutral (UI):
- Background: #ffffff (light) / #1f2937 (dark)
- Surface: #f9fafb (light) / #111827 (dark)
- Border: #e5e7eb (light) / #374151 (dark)
- Text Primary: #111827 (light) / #f9fafb (dark)
- Text Secondary: #6b7280 (light) / #9ca3af (dark)
```
### Typography
```css
/* Use system font stack - zero download time */
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI",
Roboto, "Helvetica Neue", Arial, sans-serif;
/* Type Scale */
text-xs: 0.75rem (12px) - Labels, captions
text-sm: 0.875rem (14px) - Body small, secondary text
text-base: 1rem (16px) - Body text, inputs
text-lg: 1.125rem (18px) - Emphasized text
text-xl: 1.25rem (20px) - Page titles
text-2xl: 1.5rem (24px) - Section headers
/* Line Height */
leading-tight: 1.25 - Headings
leading-normal: 1.5 - Body text
leading-relaxed: 1.75 - Long-form content
```
### Spacing System
```css
/* 4px base unit */
0: 0
1: 0.25rem (4px)
2: 0.5rem (8px)
3: 0.75rem (12px)
4: 1rem (16px)
6: 1.5rem (24px)
8: 2rem (32px)
12: 3rem (48px)
```
### Components
#### Buttons
```
Primary: Bold background, white text, clear call-to-action
Secondary: Border only, transparent background
Danger: Red background for destructive actions
Icon-only: 44x44px minimum touch target
```
#### Cards
```
Light elevation, subtle border
Padding: 1rem (mobile) / 1.5rem (desktop)
Border radius: 0.5rem (8px)
```
#### Forms
```
Inputs: 44px min height (touch-friendly)
Labels: Always visible (no floating labels)
Validation: Inline, immediate feedback
```
---
## Layout Structure
### Grid System
- **Mobile**: Single column, full-width
- **Tablet**: 2 columns where appropriate
- **Desktop**: 3-column max (sidebar + main + auxiliary)
### Navigation
- **Mobile**: Bottom navigation bar (thumb-friendly)
- **Desktop**: Left sidebar (collapsible)
- **Max 5 items**: Dashboard, Commands, Settings, Logs, Help
### Page Structure
```
┌─────────────────────────────────┐
│ Header (always visible) │
│ - Logo / Title │
│ - Status indicators │
│ - Session info │
├─────────────────────────────────┤
│ │
│ Main Content Area │
│ (scrollable) │
│ │
│ - Clear hierarchy │
│ - Generous whitespace │
│ - Focused tasks │
│ │
├─────────────────────────────────┤
│ Bottom Nav (mobile) │
│ or Footer (desktop) │
└─────────────────────────────────┘
```
---
## Interaction Patterns
### Loading States
1. **Skeleton screens** for initial load (CSS only, no spinners)
2. **Inline progress** for actions (e.g., "Executing...")
3. **Toast notifications** for completion/errors (auto-dismiss)
### Error Handling
1. **Inline validation** - Show errors near the field
2. **Error boundaries** - Graceful degradation
3. **Retry options** - Always offer a way forward
4. **Clear messages** - Explain what happened and why
### Real-Time Updates (SSE)
1. **Status badges** - Live connection indicator
2. **Notification dot** - New events available
3. **Auto-update** - Background refresh without disruption
4. **Rate limiting** - Debounce rapid updates
### Command Execution Flow
```
1. User enters command
2. Instant visual feedback (disable button, show "Executing...")
3. Command sent to backend
4. Progress indication (if long-running)
5. Result display (success/error with output)
6. Re-enable interface
```
---
## Page Specifications
### 1. Dashboard (`/`)
**Purpose**: Quick status overview, jump to common actions
**Content**:
- System status card (CPU temp, memory, disk)
- PM3 connection status
- UPS battery level (if present)
- Quick actions (Scan, Clone, Settings)
- Recent activity log (last 5 commands)
- Update notification (if available)
**Layout**: 2-3 cards on mobile (stacked), 3-4 cards on desktop (grid)
### 2. Commands (`/commands`)
**Purpose**: Execute PM3 commands with guided workflows
**Tabs**:
- **Quick Actions**: Buttons for common commands (hw status, hf search, lf search)
- **Custom**: Text input for advanced users
- **Wizards**: Step-by-step guides (Clone Card, Format T5577, etc.)
**Output**: Monospace terminal-style display with syntax highlighting
### 3. Settings (`/settings`)
**Purpose**: Configure system behavior
**Sections**:
- Wi-Fi (mode selection, credentials)
- Updates (auto-update toggle, check now)
- Session (timeout setting, current session info)
- Backup (schedule, restore)
- Security (auth enable, HTTPS)
- Advanced (PM3 device path, timeouts)
**Layout**: Accordion on mobile, tabs on desktop
### 4. Logs (`/logs`)
**Purpose**: View command history and system logs
**Features**:
- Filterable table (date, command, status)
- Export option (CSV)
- Clear history button (with confirmation)
### 5. Help (`/help`)
**Purpose**: Embedded documentation
**Content**:
- Quick start guide
- Common PM3 commands
- Troubleshooting
- Link to full documentation
---
## Accessibility (a11y)
### WCAG 2.1 AA Compliance
- **Color contrast**: 4.5:1 minimum for text
- **Keyboard navigation**: All interactive elements reachable
- **Focus indicators**: Clear, visible focus styles
- **ARIA labels**: Meaningful labels for screen readers
- **Alt text**: All images/icons have descriptions
### Touch Targets
- **Minimum size**: 44x44px
- **Spacing**: 8px minimum between targets
- **Feedback**: Visual response to all interactions
---
## Performance Optimization
### CSS Strategy
```
✅ DO:
- Use vanilla CSS (no framework overhead)
- CSS Grid & Flexbox for layouts
- CSS variables for theming
- Minimal animations (transform/opacity only)
- Mobile-first media queries
❌ DON'T:
- Heavy CSS frameworks (Bootstrap, Material UI)
- Web fonts (use system fonts)
- Complex animations (drains CPU)
- Excessive shadows/gradients
- Unused CSS
```
### JavaScript Strategy
```
✅ DO:
- Remix SSR (minimal client JS)
- Progressive enhancement
- Code splitting by route
- Debounce user input
- Use native APIs where possible
❌ DON'T:
- Heavy libraries (moment.js, lodash)
- Polyfills for modern browsers only
- Unnecessary dependencies
- Client-side rendering (use SSR)
- Global state (use URL/forms)
```
### Image Strategy
```
✅ DO:
- Inline SVG icons (<2KB each)
- System emoji for decorative elements
- Lazy loading for below-fold images
- Serve WebP with fallbacks
❌ DON'T:
- Icon fonts (Flash of Unstyled Text)
- Large images (compress heavily)
- Unoptimized assets
- Background images (use CSS colors)
```
---
## Dark Mode
### Implementation
- **System preference detection**: `prefers-color-scheme`
- **Manual toggle**: Persisted in localStorage
- **CSS variables**: Single source of truth for colors
- **No flash**: SSR with cookie-based preference
### Colors
```css
:root {
/* Light mode (default) */
--color-bg: #ffffff;
--color-surface: #f9fafb;
--color-text: #111827;
}
@media (prefers-color-scheme: dark) {
:root {
--color-bg: #1f2937;
--color-surface: #111827;
--color-text: #f9fafb;
}
}
```
---
## Mobile Considerations
### Touch-First Design
- Large buttons (44x44px minimum)
- Bottom navigation (thumb zone)
- Swipe gestures (optional, enhance)
- Avoid hover-only interactions
### Viewport
```html
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=5">
```
### PWA Support
- Add to home screen
- Offline fallback page
- Service worker for caching
- App manifest
---
## Development Checklist
### Before Committing
- [ ] Lighthouse score > 90 (Performance, A11y, Best Practices)
- [ ] Works without JavaScript
- [ ] Mobile responsive (320px - 1920px)
- [ ] Dark mode tested
- [ ] Keyboard navigation works
- [ ] Screen reader tested
- [ ] Bundle size < 150KB gzipped
### Testing Devices
- iPhone SE (375px width)
- iPad Mini (768px width)
- Desktop (1280px+ width)
---
## Quick Reference
### Breakpoints
```css
sm: 640px /* Tablets */
md: 768px /* Small laptops */
lg: 1024px /* Desktop */
```
### Animation Durations
```css
fast: 150ms /* Hovers, simple transitions */
normal: 250ms /* Most UI animations */
slow: 350ms /* Page transitions */
```
### Z-Index Scale
```css
base: 0 /* Normal content */
dropdown: 10 /* Dropdowns, tooltips */
modal: 100 /* Modals, dialogs */
toast: 200 /* Notifications */
```
---
## Resources
- **Remix Docs**: https://remix.run/docs
- **CSS Grid**: https://css-tricks.com/snippets/css/complete-guide-grid/
- **A11y Checklist**: https://www.a11yproject.com/checklist/
- **Performance Budget**: https://web.dev/performance-budgets-101/
---
## Example Component: Status Badge
```css
/* Lightweight, semantic, accessible */
.status-badge {
display: inline-flex;
align-items: center;
gap: 0.5rem;
padding: 0.25rem 0.75rem;
border-radius: 9999px;
font-size: 0.875rem;
font-weight: 500;
}
.status-badge--success {
background: #d1fae5;
color: #065f46;
}
.status-badge--error {
background: #fee2e2;
color: #991b1b;
}
```
```jsx
<span className="status-badge status-badge--success" role="status">
<span aria-hidden="true">●</span>
Connected
</span>
```
**Why it's good**:
- Semantic HTML
- CSS-only styling (no JS)
- Accessible (role="status")
- Visual and text indicator
- Small footprint (~100 bytes)