Skip to content
BraedenP232Public

About

Your Pwnagotchi, Now on iOS

Resources

Stars

52 stars

Watchers

1 watching

Forks

Latest commit

 

History

30 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 

Repository files navigation

Pwnagotchi Companion (PwnIOS)

PwnIOS is an iOS companion app for Pwnagotchi.

Connect your iPhone or iPad to your Pwnagotchi over WebSocket and get live stats, screen mirroring, GPS sharing, network information, events, and remote control from the app.


Features

  • Live dashboard — uptime, battery, temperature, mode, and connection status
  • Screen mirroring — mirror the Pwnagotchi display directly on your iOS device
  • Network monitoring — discovered access points and current-session handshakes
  • GPS sharing — send occasional or live iOS location updates to Pwnagotchi
  • Handshake location — write the latest coordinates beside captured handshakes
  • Events — a focused activity log with optional verbose detail
  • Remote control — switch modes and reboot Pwnagotchi remotely
  • PiSugar support — battery monitoring through PiSugar
  • WebSocket connection — resilient reconnect, heartbeat, and clean shutdown handling

Requirements

PwnIOS 2.0.0 is tested with Python 3.13.5 and websockets 17.0.1. Verify the package in Pwnagotchi's own Python environment:

/opt/.pwn/bin/python3 -c "import websockets; print(websockets.__version__)"

Installation

1. Install the PwnIOS plugin

Manual installation

SSH into your Pwnagotchi and copy pwnios.py into the custom plugin directory configured by your image. For example:

cp pwnios.py ~/custom-plugins/pwnios.py

The location may differ between images. Use the same directory as your other working custom plugins.

Plugin repository

Alternatively, add the PwnIOS plugin repository to your Pwnagotchi configuration:

main.custom_plugin_repos = [
    "https://github.com/BraedenP232/pwnios/archive/main.zip",
]

Then install it:

sudo pwnagotchi plugins update
sudo pwnagotchi plugins install pwnios

2. Configure PwnIOS

Edit:

sudo nano /etc/pwnagotchi/config.toml

Add or modify the PwnIOS configuration:

[main.plugins.pwnios]
enabled = true

# Display
host = "0.0.0.0"
port = 8082
display = false
display_gps = false

# PiSugar
pisugar = false

# GPS
save_gps_log = true
gps_log_path = "/tmp/pwnagotchi_gps.log"
gps_altitude = 10
# Optional: override mode-aware GPS freshness
# gps_stale_seconds = 300

Configuration options

Option Default Description
enabled true Enable the PwnIOS plugin
host 0.0.0.0 Interface on which the WebSocket server listens
port 8082 WebSocket server port
display false Display iOS connection status on Pwnagotchi
display_gps false Display GPS coordinates on Pwnagotchi
pisugar false Enable PiSugar battery monitoring
save_gps_log true Save GPS data to a log file
gps_log_path /tmp/pwnagotchi_gps.log GPS log file location
gps_altitude 10 Default altitude included with GPS data when the client does not provide one
gps_stale_seconds 300 Live / 1800 Battery Saver Override how long the most recent GPS fix remains valid

3. Restart Pwnagotchi

pwnkill && pwnlog

4. Install the iOS app

Download Pwnagotchi Companion from the App Store


Usage

Connect your iPhone or iPad to the Pwnagotchi using Bluetooth tethering.

Once the connection is established, the app will show Live.

Dashboard

Live Pwnagotchi statistics including:

  • Uptime
  • Battery
  • Temperature
  • Current mode
  • Connection status
  • Pwnagotchi face

Screen

Mirrors the Pwnagotchi display directly in the app.

Network

View discovered access points and handshake activity in real time.

Location

Share your iOS device's GPS location with Pwnagotchi.

GPS data can also be logged for later use and written to a .gps.json sidecar when a handshake is captured.

Events

View connection events and Pwnagotchi activity as they happen.

Settings

Configure the connection, appearance, location sharing, and notifications.


Troubleshooting

PwnIOS won't connect

Check the following:

  1. Bluetooth tethering is enabled on your iOS device.
  2. The PwnIOS plugin is enabled in config.toml.
  3. Pwnagotchi has been restarted after installing or changing the plugin.
  4. Your iOS device is connected to the Pwnagotchi's Bluetooth network.
  5. Port 8082 is listening: sudo ss -lntp | grep ':8082'.
  6. The plugin reports a startup line in pwnlog | grep -i pwnios.

If Bluetooth tethering itself is unreliable, see this Pwnagotchi tethering writeup.

Connection keeps dropping

Keep the iOS device close to the Pwnagotchi and check the Pwnagotchi's power stability.

Check pwnlog | grep -i pwnios to determine whether the problem is the Bluetooth route, WebSocket listener, or plugin startup.

Face or screen isn't updating

Check that:

  • The Pwnagotchi display is functioning normally.
  • The PwnIOS plugin is running.
  • WebSocket traffic is being received.
  • Debug logging doesn't show connection or parsing errors.

Restarting both the Pwnagotchi and the app can also clear a stale connection.


What's New — v2.0.0

WebSocket compatibility and resilience

  • Updated the server for Python 3.13 and the modern websockets.asyncio.server API.
  • Added deterministic server startup and shutdown across the plugin's background event-loop thread.
  • Improved heartbeat, client cleanup, broadcasting, and connection health behavior.
  • Added a server hello message so the app can identify plugin and protocol versions.

Companion data

  • Merged Pwnagotchi agent handshakes with captures from the current plugin session.
  • Normalized and deduplicated handshake history by filename, preferring current-session metadata and returning the latest 100 entries.
  • Used the same normalized history for dashboard statistics and the app's handshake view.
  • Improved AUTO/MANU mode reporting by reading the runtime mode used by Pwnagotchi.
  • Added GPS coordinate and accuracy validation plus dedicated acknowledgments for accepted fixes.
  • Added mode-aware GPS freshness: five minutes for Live GPS and 30 minutes for Battery Saver, unless configured otherwise.
  • Preserved GPS sharing, per-handshake GPS exports, face updates, PiSugar data, and remote controls.
  • Reduced noisy routine logging while retaining useful lifecycle and error messages.

Links


License

MIT License


PwnIOS is not officially affiliated with the Pwnagotchi project.

About

Your Pwnagotchi, Now on iOS

Resources

Stars

52 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages