Pwnagotchi Companion is a sophisticated iOS companion app that provides real-time monitoring and control of your Pwnagotchi device. Using advanced WebSocket technology with intelligent reconnection, message queuing, and health monitoring, Pwnagotchi Companion delivers a seamless experience for managing your Pwnagotchi from your iPhone or iPad.
- Live Statistics: Monitor uptime, battery level, temperature, and current operating mode
- Connection Health: Advanced network quality detection with automatic degradation handling
- Performance Metrics: Track message throughput, ping latency, and connection stability
- Activity Timeline: Comprehensive event logging with categorized status updates
- Live Face Display: Real-time Pwnagotchi face updates with support for custom faces
- Screen Mirroring: Direct display view of your Pwnagotchi's actual screen
- Dual View Modes: Switch between face view and full screen display
- Automatic Refresh: Configurable refresh intervals for optimal performance
- Custom Face Capabilities: Compatible with custom faces via custom-faces-switcher
- Intelligent WebSocket Management: Auto-reconnection with exponential backoff
- Message Queue System: Reliable message delivery with retry logic and priority handling
- Background Resilience: Maintains connection state across app lifecycle changes
- GPS Tracking: Real-time location sharing
- Accuracy Metrics: Display GPS precision and last update timestamps
- Mode Switching: Change between AUTO, MANUAL
- System Commands: Remote reboot and state management
- Access Point Discovery: Real-time WiFi network detection and analysis
- Handshake Monitoring: Live capture status and peer detection
- Channel Information: Current operating channel and hop detection
- Network Statistics: Comprehensive WiFi environment analysis
- Handshake GPS On_Handshake() now saves a .gps.json version alongside .pcap with gps coords if available.
- Improved Instructions Combed through the current Bluetooth Setup Guide and FAQ within Pwnagotchi Companion app to explain things more diligently and it's easier to read.
- No Haptic Disabled Haptic Feedback Toggle for now as haptic engine was not running consistantly throughout multiple views.
- Layout Fixing Fixed some places where text was getting cut off so I allowed it to wrap.
// Advanced connection states with automatic recovery
enum ConnectionState {
case disconnected, connecting, connected, reconnecting, failed(Error)
}- Priority Queue System: High, normal, and low priority message routing
- Automatic Retry Logic: Failed messages are intelligently retried
- Message Acknowledgment: Reliable delivery confirmation system
- Queue Persistence: Messages survive connection interruptions
- Background Processing: JSON parsing and image decoding off main thread
- Memory Management: Efficient image handling and data cleanup
- Timer Coordination: Sophisticated timer management for different update intervals
- Resource Conservation: Automatic pause/resume based on app state
- Manual Configuration: Custom IP and port configuration with validation
- Connection History: Remember and quickly reconnect to known devices
- Real-Time Dashboard: Live stats with beautiful visualizations
- Event Timeline: Scrollable history of all Pwnagotchi activities
- Settings Panel: Comprehensive configuration options
- Debug Console: Advanced logging for troubleshooting
Navigate to your custom plugins directory:
cd ~/custom-plugins/ # Or wherever you have set yours in config.toml
Create pwnios.py:
sudo nano pwnios.py
Paste contents of pwnios.py plugin
Add the custom plugin repository to your /etc/pwnagotchi/config.toml:
main.custom_plugin_repos = [
"https://github.com/BraedenP232/pwnios/archive/main.zip",
]# Update plugin repositories
sudo pwnagotchi plugins update
# Install Pwnagotchi Companion plugin
sudo pwnagotchi plugins install pwniosEdit /etc/pwnagotchi/config.toml:
main.plugins.pwnios.enabled = true
main.plugins.pwnios.display = true # Show connection count on display
main.plugins.pwnios.display_gps = true # Show GPS status on display
main.plugins.pwnios.port = 8082 # WebSocket server port
# Coming soon
# main.plugins.pwnios.save_gps_log = true # Optional: Enable GPS logging
# main.plugins.pwnios.gps_log_path = "/tmp/pwnagotchi_gps.log" # GPS log locationpwnkill && pwnlogπ± The Pwnagotchi Companion app will be available on the App Store soon!
- Network Connection: Connect your iOS device to the Pwnagotchi via Bluetooth Tethering
- Verify Connection: Verify the Bluetooth connection and possibly restart Pwnagotchi
- Connection: Pwnagotchi Companion will present Live when the connection is established
- Dashboard: Main view with live statistics and face display
- Screen View: Swipe to view actual Pwnagotchi display
- Network: View discovered APs and some information about them
- Location: GPS sharing from iOS device to Pwnagotchi, saved for optional wardriving
- Events: Detailed activity log with filtering options
- Settings: App configuration and connection management
- Debug Mode: Enable detailed logging for troubleshooting
- β Verify Bluetooth tethering is connected properly
- π Check if Pwnagotchi is powered on and responsive
- π Confirm plugin is enabled and Pwnagotchi has restarted
- π§ Troubleshoot using wpa_2's great writeup
- πΆ Ensure Pwnagotchi is close to iOS device
- β‘ Verify Pwnagotchi power supply is stable
- π Enable debug logging to identify patterns
- πΌοΈ Verify Pwnagotchi display is active and changing
- π‘ Check WebSocket message flow in debug logs
- π Toggle between face and screen view modes
- βοΈ Restart both app and Pwnagotchi if needed
The app includes comprehensive diagnostic tools:
- Connection Metrics: Real-time latency and throughput monitoring
- Message Inspector: View raw WebSocket traffic
- Health Monitor: Connection quality assessment
- Network Analyzer: WiFi environment analysis
- iOS: 16.0 or later
- Devices: iPhone, iPad, iPod touch
- Network: WiFi or Cellular with local network access
- Pwnagotchi: Jayofelony's fork
- WebSocket: Primary communication protocol (RFC 6455)
- HTTP: Screen capture and control commands
- TCP: Reliable connection with automatic retry
- JSON: Structured data exchange format
- Latency: Sub-second response times on good networks
- Throughput: Handles high-frequency updates without blocking
- Memory: Optimized for minimal memory footprint
- Battery: Efficient background processing to preserve battery life
- π§ jayofelony's Pwnagotchi Fork: github.com/jayofelony/pwnagotchi
- π€ PwnDroid (Android): PwnDroid Repository
- π§ Pwnagotchi Plugins: Official Plugin Collection
- π¬ Discord Server: Unofficial Pwnagotchi Community
- π Documentation: Official Pwnagotchi Docs
- π Bug Reports: GitHub Issues
- π‘ Feature Requests: GitHub Discussions
- Check Documentation: Most common issues are covered here
- Search Issues: Someone may have already solved your problem
- Enable Debug Logging: Helps identify specific issues
- Community Support: Ask questions in Discord or GitHub Discussions
- Bug Reports: Use provided templates for best results
- watchOS Companion: Basic stats and notifications on Apple Watch
- Widget Support: iOS home screen widgets for quick status
- Multi-Device: Manage multiple Pwnagotchi devices
- Push Notifications: Alerts for important events
- Advanced Analytics: Historical data analysis and trends
- macOS Version: Full-featured macOS companion app
- Multi-Platform Version: Potentially a release of the app on most platforms built with Expo
- Automation: Integration with iOS Shortcuts and HomeKit
- Cloud Services: Optional cloud backup and sync
- Advanced Mapping: GPS tracking with map visualization
We welcome contributions from the community! Here's how you can help:
- π Bug Fixes: Help identify and fix issues
- β¨ New Features: Implement requested functionality
- π Documentation: Improve guides and API documentation
- π§ͺ Testing: Beta testing on different devices and networks
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes with proper documentation
- Test thoroughly on real devices
- Submit a pull request with detailed description
- Follow Swift best practices and iOS Human Interface Guidelines
- Use SwiftUI for new UI components
- Include unit tests for new functionality
- Document public APIs with DocC comments
This project is licensed under the MIT License - see the LICENSE file for details.
- SwiftUI framework (Apple)
- UIKit framework (Apple)
- Network framework (Apple)
- Combine framework (Apple)
- evilsocket: Original Pwnagotchi creator
- jayofelony: Maintaining the active Pwnagotchi fork
- Pwnagotchi Community: Continuous inspiration and feedback
Note: This project is not officially affiliated with the Pwnagotchi project but is developed with love for the community. No Pwnagotchi feelings were harmed in the making of this app. π€β€οΈ