Once you’ve written the image file onto the SD card, there’re a few steps you’ll have to follow in order to configure your new Pwnagotchi properly.
For the initial configuration, the easiest way is creating a new
config.yml file of the
boot partition of the SD card.
This partition should be easily accessible from your computer regardless of your operating system as it is a simple FAT32.
In this process you might define your unit’s name, which network to whitelist and the type of display you use. The following is the example configuration for a unit with a Waveshare V2 display, for more detailed configuration instructions refer to the sections below.
main: name: 'pwnagotchi' whitelist: - 'YourHomeNetworkMaybe' plugins: grid: enabled: true report: true exclude: - 'YourHomeNetworkMaybe' ui: display: enabled: true type: 'waveshare_2' color: 'black'
The software will install this file to
/etc/pwnagotchi/config.yml (and it will remove it from the SD card) during boot.
After the first boot, you can open the
/etc/pwnagotchi/config.yml file (either via SSH or by directly editing the SD
card’s contents from a computer with a card reader) to override the default configuration with
your custom values.
If you want to restore a backup instead, you can copy the contents of the
folder in the FAT32 boot partition as
/boot/pwnagotchi. This way the whole folder containing the configuration and the RSA keypair
will be moved to
/etc/pwnagotchi during boot. Restoring this folder this way will allow the unit to boot without the need to generate
a new RSA keypair, operation that takes time and would be completely pointless if a backup needs to be restored anyway.
Given that the FAT32 boot partition is limited in size, other folders and files that are part of the backup will need to be copied manually either to the SD card, if it’s possible to mount it on a host computer, or via SSH with cable or bluetooth connectivity as explained in the following sections.
Pwnagotchi displays its UI in English by default, but it can speak several other languages! If you’re fine with English, you don’t need to do anything special here.
But if you do want to change what language Pwnagotchi displays its status in, you can change
main.lang to one of the supported languages:
If you want to contribute a new language (or improve an existing translation!), you can check out the Adding a Language doc for more details.
By default, the
grid plugin is only partially enabled. This means that whenever the unit will detect internet connectivity while in MANUAL mode, it will signal its existence to the PwnGrid server by sending ONLY the following enrollment data:
uname -acommand on the unit used to determine the type of hardware.
If you would like your unit to participate in PwnGrid’s community rankings and scoreboards (PwnGrid is like Pokémon Go, but for WiFi!), as well as be a datapoint in regional (country-level) statistics, you can fully opt-in to PwnGrid by enabling your unit to send the PwnGrid API some basic information about the networks it has pwned. None of your unit’s captured cryptographic material is sent to the PwnGrid server; ONLY the minimum information to enroll the unit in the PwnGrid database (see above) and calculate how many networks it has “conquered” so far, namely:
In order to fully opt-in to PwnGrid, you must make the following change in your
main: plugins: grid: enabled: true report: true # full-opt in
Even if you have decided to fully opted-in to PwnGrid, you can still disable reporting for specific networks—for instance, if you don’t want your home network to be in the system:
main: plugins: grid: enabled: true report: true exclude: - MyHomeNetwork # both ESSIDs and BSSIDs are supported - de:ad:be:ef:de:ad # both ESSIDs and BSSIDs are supported
PLEASE NOTE:As we use YAML for the configuration, you should know some YAML rules. Especially when it comes to quotation, some things can go wrong! E.g. if your ESSIDs starts with 0x or @ or contains some other special characters, you should use single quotes, which allows you to use all kinds of characters in your string (you only need to escape the single quote itself).
If instead you prefer to completely opt-out by also disabling signaling:
main: plugins: grid: enabled: false # full opt-out report: false
If you want to use the web UI (instead of an e-ink display attached to your unit's RPi0W) to see your Pwnagotchi's face, check out the User Interface doc for more details on using the web UI.
Set the type of display you want to use via
If your display does not work after changing this setting, you might need to completely remove power from the Raspberry Pi and make a clean boot.
waveshare_2for the V2 version of Waveshare’s ePaper HAT, this is the recommended and officially supported display.
waveshare_1for the V1 legacy version of Waveshare’s ePaper HAT
waveshare27inchfor 2.7inch e-Paper HAT
waveshare154inchfor 1.54inch e-Paper Module (B)
inkyfor Pimoroni’s Inky pHAT.
papirusfor PaPiRus Zero.
oledhatfor Waveshare’s OLED Hat.
dfrobotfor DFRobot’s eInk Hat
You can configure the refresh interval of the display via
ui.fps. We recommend using a slow refresh rate to avoid shortening the lifetime of your e-ink display. The default value is
0, which will only refresh when changes are made to the screen.
config.yml file in the
boot partition of the SD card should now look something like the following (with the
right differences if you’re using different hardware):
main: name: 'pwnagotchi' whitelist: - 'YourHomeNetworkMaybe' plugins: grid: enabled: true report: true exclude: - 'YourHomeNetworkMaybe' ui: display: type: 'inky' color: 'black'
Congratulations! Your SD card is now ready for the first boot! 👾 🎉
You can connect to your Pwnagotchi via SSH.
PLEASE NOTE: If you cannot connect to your Pwnagotchi no matter what you try, ensure that the micro-USB you are using allows data transfer and doesn't ONLY provide charge. Cheaper quality micro-USB cords often do not support data transfer and will NOT allow you to actually connect to your Pwnagotchi. :'( Use a quality cord!
pwnagotchi.localwon’t work. Instead, try your unit’s hostname +
ssh [email protected] # default password: raspberry
DEV NOTE: These are directions for the recommended hardware, a Pi0w - and connecting to it from a Linux based host via a Micro-USB through the data port. This was written while connecting to a Pi0w with a Data Capable MicroUSB to a Macbook Pro late 2012 running Ubuntu 19.04. We can not guarantee these specific directions work on any other OS. Hopefully further write ups will be provided at a later date.
10.0.0.1/24range. If it is, you should turn Wi-Fi off initially to best troubleshoot your connectivity issues, then change the interface IP scheme on your Pi once you can
These settings are only verified to work on, 1. a Pi0w, with a 2. MicroUSB data capable cable, 3. the newest released image found on our Github which at the time of writing is RC5, and 4. a completely vanilla image(plug-in and whitelist configuration is fine, but if you have previously adjusted the UI: from
0.0.0.0, you need to revert those changes by deleting anything related to
UI: in your
ifconfig to check and take note of the names of your current interfaces, and what is now recognized as an adapter on your system. Take note of the Mac Addresses that you see in this output.
Starting with a clean slate in your Network Manager (remove all wired interface profiles that you have on your Network Manager,) plug your unpowered Pi0w into your computer through the data port seen in the picture shown above .
Wait until your Pi boots into Manu mode. Once you see the breakdown that Pwnagotchi does when in MANU mode, type
ifconfig again on your host machine and look for a new interface that was not there during Step 1.
*Take EXTRA note of the new interfaces mac address I will be referencing this mac address on multiple occasions as Step 3.
On Network Manager on your PC/Host, (if there are no interfaces automatically added, you can attempt to add a new interface by selecting the mac address noted in Step 3 for the interface profile) select Settings > IPv4 and then change from
manual, then for your address, you’ll need to configure it with a static IP address and then press apply in the top right:
Back in your terminal, type
ifconfig and look for the interface that you found in Step 3 and that you edited the settings for in Step 4. If you see the following on the second line of the interface that matches the mac address from Step 3, you should now be able to enter
ping 10.0.0.2 and receive a response from your pi.
inet 10.0.0.1 netmask 255.255.255.0 broadcast 10.0.0.255
TIP: you may need to use the `linux_connection_share.sh` script before your PC will allow you to ssh to your Pi. [Host connection sharing](/configuration/#host-connection-sharing)
DEV NOTE: if you have some issues, either you are using the wrong cord, or your Operating System is missing required drivers, or something mostly out of our control. We can't help everyone with their networking, sorry
The default password is
raspberry; you should change it as soon as you log in for the first time by issuing the
passwd command and selecting a new and more complex passphrase.
If you want to login directly without entering a password (recommended and necessary for certain packaged scripts to work, like
backup.sh for instance!), copy your SSH public key to the unit’s authorized keys:
ssh-copy-id -i ~/.ssh/id_rsa.pub [email protected]
Want to be able to update your Pwnagotchi and access things from the internet on it? Sure you do!
usb0(A.K.A., using the data port).
|Mac OS X||
If you want to upload your handshakes while walking, want to use your smartphone as a display or simply shutdown your pwnagotchi gracefully, you can use the
Make sure to explicitly enable Bluetooth Tethering on your Phone (usually in Settings -> Hotspot or similar). Otherwise your Pwnagotchi will pair with your phone but you won't be able to create a Personal Area Network (PAN).
Now in pwnagotchi’s
config.yml add the following:
main: plugins: bt-tether: enabled: true devices: my-phone1: # you can choose your phones name here enabled: true # enables the device search_order: 1 # in which order the devices should be searched. E.g. this is #1. mac: 'FF:FF:FF:FF:FF' # you need to put your phones bt-mac here (the same as above, ## or goto your phones settings > status) ip: 'xx.xx.xx.44' # this is the static ip of your pwnagotchi ## adjust this to your phones pan-network (run "ifconfig bt-pan" on your phone) ## if you feel lucky, try: 192.168.44.44 (Android) or 172.20.10.6 (iOS) ## 44 is just an example, you can choose between 2-254 (if netmask is 24) netmask: 24 # netmask of the PAN interval: 1 # in minues, how often should the device be searched scantime: 15 # in seconds, how long should be searched on each interval share_internet: true # this will change the routing and nameserver on your pi priority: 99 # if you have multiple devices which can share internet; the highest priority wins max_tries: 0 # how often should be tried to find the device until it is disabled (to save power) ## 0 means infinity macbook: enabled: false # ...
The legacy configuration (without the `devices` key) is still supported, but should be converted as soon as possible.
Your pwnagotchi will indicate the status via a little
BT symbol at the top of the screen.
The status codes are:
If you want to fix these problems, the first step should be to start pwnagotchi with
check the log file (
/var/log/pwnagotchi.log) for related debug messages.
Some users had problems with the auto pairing feature of the plugin (in old versions). If your pwnagotchi should not make an effort to connect to your bluetooth device after a few minutes, there is a chance that this can be fixed by doing the pairing manually. To do this, put your phone in discoverable mode. On your pwnagotchi, run
sudo bluetoothctl and once in the bluetooth-shell, type
scan on. That will scan the environment for nearby bluetooth devices.
Pick the mac of your phone and type
pair <mac> and
trust <mac>. In short time (maybe not immediately)
you will be prompted on the phone to allow connection from your pwnagotchi hostname.
All done configuring your new Pwnagotchi? Time to learn how to take care of your new friend over in Usage!
If your network connection keeps flapping on your device connecting to your Pwnagotchi:
* Check if
usb0 (or equivalent) device is being controlled by NetworkManager.
* You can check this via
nmcli dev status.
* If you are having trouble connecting to your Pi via USB, be sure you are using a microUSB cord that is capable of data transfer