Installation
The “vanilla” hardware setup for a Pwnagotchi is a Raspberry Pi 0 W (usually referred to as RPi0W throughout this documentation). Most development and testing has been conducted on Pwnagotchis living in RPi0W bodies configured as an USB ethernet gadget device (in order to connect to it via USB). That said:
- Some users have gotten their Pwnagotchi running on other types of Raspberry Pi with no apparent issues This includes:
- Raspberry Pi 3 (notes)
- Raspberry Pi 4
SD card
The microSD card ought to be:
Battery
If you’re going to be taking your Pwnagotchi out into the world to find new and exciting Wi-Fi environments (!), you’re going to need to power it with an external battery. Depending on your priorities, you may only need a small battery if you’re just going to be out for a couple hours. But if you’re going to be out all day, you might need something bigger. How do you know what you’ll need to keep your Pwnagotchi pwning?
Happily, our users have submitted some preliminary benchmarks using some popular batteries to help give you a sense for how long a particular battery is likely to be able to power your Pwnagotchi when you take it out into the Wi-Fi wilderness. 🙂
UPS-Lite Battery level indicator plugin
UPS-Lite V1.1 is nice and feature-rich battery hat. It has battery charge controller which communicate over I2C interface and can tell its’ voltage level. It also has built-in UART-USB adapter connected to raspbbery UART pins so you can connect to serial console using the same microUSB port while charing the battery.
Pwnagotchi has a ups_lite plugin to display battery on the screen. Before using it i2c interface should be enabled in raspi-config.
Hardware Clock
If you’re using a Raspberry Pi 0 W for the body of your Pwnagotchi, you should be aware of the fact that it does not have an hardware clock. This means that unless it’s connected to the internet somehow (either by USB cable and host connection sharing or BT tethering), when the unit is off its time will go out of sync with the real world, presenting wrong uptimes and generally using wrong date and times in the logs and whenever another absolute-time-based action is performed.
This problem can be solved for cheap with an hardware clock, a small chip with a battery that can stay on while the rest of the unit is off … it’s like giving your Pwnagotchi a wristwatch! 😀
Any I2C compatible model can be used (usually PCF8523, DSL1307 or DS3231 based) and easily installed by following this guide.
Usually they would be plugged directly to the GPIO via their connector but it is possible to desolder the connector and just solder them directly to the ports on the PCB in order to save space (make sure to isolate the chip with duct tape).
Flashing an Image
The easiest way to create a new Pwnagotchi is downloading the latest stable image from our release page and writing it to your SD card.
Once you have downloaded the latest Pwnagotchi image, you will need to use an image writing tool to install that image on your SD card. We recommend using balenaEtcher, a graphical SD card writing tool that works on Mac OS, Linux, and Windows; it is the easiest option for most users. (balenaEtcher also supports writing images directly from the ZIP file, without any unzipping required!)
To write your Pwnagotchi image with balenaEtcher:
As an alternative you can use dd on GNU/Linux or macOS:
Change the path to your image file, /dev/sdcard is the path to you SD card device.
dd if=path/to/pwnagotchi-raspbian-lite-XXX.img of=/dev/sdcard bs=1M
Wait before removing the SD card as you will need to create one last file on it with the initial configuration.
Installing on any GNU/Linux
If instead of using our image you prefer the hacker way and you want to configure the software components manually on any GNU/Linux box, you will need to follow these steps.
bettercap
First of all, download and install bettercap, its caplets and its web ui (change the URL to match the precompiled binary of the latest release according to your architecture):
wget https://github.com/bettercap/bettercap/releases/download/v2.26.1/bettercap_linux_amd64_v2.26.1.zip unzip bettercap_linux_amd64_v2.26.1.zip #. check the sha256 digest before doing this. sudo mv bettercap /usr/bin/ # install the caplets and the web ui in /usr/local/share/bettercap and quit sudo bettercap.eval caplets.update; ui.update; quit
Depending on the name of the Wi-Fi interface you’re going to use, you’ll need to edit the /usr/local/share/bettercap/caplets/pwnagotchi-auto.cap and /usr/local/share/bettercap/caplets/pwnagotchi-manual.cap caplet files accordingly.
How to run bettercap and in which mode it’s up to you as long as it’s running one of those two caplets. In the default Pwnagotchi image bettercap is running as a systemd service through a launcher script.
This is /etc/systemd/system/bettercap.service :
[Unit] Description=bettercap api.rest service. Documentation=https://bettercap.org Wants=network.target After=pwngrid.service [Service] Type=simple PermissionsStartOnly=true ExecStart=/usr/bin/bettercap-launcher Restart=always RestartSec=30 [Install] WantedBy=multi-user.target
And this is /usr/bin/bettercap-launcher :
#!/usr/bin/env bash /usr/bin/monstart if [[ (ifconfig | grep usb0 | grep RUNNING) ]] || [[ (cat /sys/class/net/eth0/carrier) ]]; then # if override file exists, go into auto mode if [.f /root/.pwnagotchi-auto ]; then /usr/bin/bettercap.no-colors.caplet pwnagotchi-auto.iface mon0 else /usr/bin/bettercap.no-colors.caplet pwnagotchi-manual.iface mon0 fi else /usr/bin/bettercap.no-colors.caplet pwnagotchi-auto.iface mon0 fi
Even in this case the interface name and the command to start the monitor mode need to be adjusted for the specific computer and Wi-Fi card.
Note: you need also libpcap to be installed
pwngrid
The second service you will need is pwngrid, even in this case:
wget https://github.com/evilsocket/pwngrid/releases/download/v1.10.3/pwngrid_linux_amd64_v1.10.3.zip unzip pwngrid_linux_amd64_v1.10.3.zip #. check the sha256 digest before doing this. sudo mv pwngrid /usr/bin/ # generate the keypair sudo pwngrid.generate.keys /etc/pwnagotchi
Pwngrid runs via the /etc/systemd/system/pwngrid-peer.service systemd service:
[Unit] Description=pwngrid peer service. Documentation=https://pwnagotchi.ai Wants=network.target [Service] Type=simple PermissionsStartOnly=true ExecStart=/usr/bin/pwngrid.keys /etc/pwnagotchi.address 127.0.0.1:8666.client-token /root/.api-enrollment.json.wait.log /var/log/pwngrid-peer.log.iface mon0 Restart=always RestartSec=30 [Install] WantedBy=multi-user.target
pwnagotchi
The last ingredient of this soup is going to be the python3 Pwnagotchi main codebase, that for any release can be installed with:
wget https://github.com/evilsocket/pwnagotchi/archive/v1.4.3.zip unzip v1.4.3.zip cd pwnagotchi-1.4.3 # this will install the requirements and pwnagotchi itself sudo pip3 install.r requirements.txt sudo pip3 install.
Assuming both bettercap and pwngrid are configured and running correctly, you can now start pwnagotchi by simply:
# AUTO mode sudo pwnagotchi # AUTO mode with debug logs sudo pwnagotchi.-debug # MANU mode sudo pwnagotchi.-manual # MANU mode with debug logs sudo pwnagotchi.-manual.-debug # show the other options pwnagotchi.h
This will install the default configuration file in /etc/pwnagotchi/default.toml. in order to apply customizations you’ll need to create a new /etc/pwnagotchi/config.toml file as explained in the configuration section.
Step 1: Evaluate Your Needs
I was trying to power two computers (desktop and file server), and two flat panel monitors. My total power consumption was roughly 500 watts peak. (yikes!) Currently I was running on two 300 watt UPS’s (NOTE: VA is not equal to WATTS. Find the WATT rating) with one computer and one monitor on each. Even though the two monitors were hooked up to the same computer, I needed to distribute my power load more evenly to get longer battery life out of my petty UPS’s.
CAUTION:I discovered the hard way after nearly starting a fire and destroying a UPS that you need one that is rated at at least twice the wattage you are consuming. They can’t handle being run for longer than a few minutes at this rating, but the batteries die before it’s a problem normally.
So I now knew I needed 500 watts, and I wanted 60 minutes of power. that means:P / V = I500 watts / 120 volts = 4.16 ampere hours (at 120 volts)
UPS batteries are usually 12 volts, but some are wired with two batteries in series. Check yours out first to make sure you won’t need two car batteries.
So, assuming 12 volts, that means that, after adjusting for the voltage differences, I need a battery with at least 41.6 ampere hours. (yeah, I know there’s inefficiencies in the UPS, but lets keep math easy)
Step 2: Remove Battery From UPS
Unplug the UPS from the wall, and unplug all devices from it.Remove any screws you fine, and open up the case.If you are as lucky as I was, the battery will have terminals that you can slide off. If not, just cut the wires as close to the battery as you can.Once you have removed the battery, you will find something like you see in the picture
NOTE: Pay attention to polarity on the battery, and which wire went to when polarity.
Step 3: Extend Wires on UPS
The wires that are in a UPS are typically not long enough to reach much past where the battery sits. We will need to extend them to reach our car battery.
Cut off the the wire terminals (if any) on the wires from the UPS.Strip at least 3/8 of an inch of the wire on the UPSStrip at least 3/8 of an inch of the wire we are extending with.I used a metal crimp to help me get a great connection, but this is optional.Solder the wires together. This solder joint needs to be able to handle high current. We will be drawing lots of power through here and if we have a voltage drop, the UPS won’t last as long.After making sure the joint is well soldered, place some heat shrink over it, and seal it up good.
Note: Use colors that make sense to you, and will allow you to remember the polarity
Ups battery connector cable
In this article, we’re going to talk about how to change UPS battery. Actually I’m just a regular people who doesn’t expert in this field, but I just want to share about my experience changing UPS battery, specifically APC RS 500 type of UPS. Hopefully it will help!
At first, we thought that it will be difficult and needs a complex electronic knowledge to change UPS battery. In fact, it is necessary to know about electronic knowledge, because we don’t want something to blow up all of a sudden, but it’s not that complex.
It will be easier if your UPS come from popular brand. The battery is widely sold on the online store, and there are a lot of tutorials about changing the battery. So you can do it by yourself, and save every pennies.
The hardest part of it, might be hunting the suitable battery that fit your UPS.
With a little effort to disassemble, browse for information, and discuss to online store seller who sold UPS battery, you can get suitable battery for your UPS.
Disclaimer: Important. Make sure you know what you’re doing. If you completely have no idea, or not sure, or have a little time, don’t do it. Please hand it over to the expert, to the service center. Because electronic device such as UPS battery could be dangerous if not taken carefully or replaced to incompatible component.
Step 1. Know your UPS
Check the UPS type that’s written in UPS body. In my case, it is APC RS 500 BR500CI. It turns out that it’s a very popular unit, that the spare parts are sold everywhere, mainly on online store.
In most cases, manufacturer doesn’t give a clear description about battery type on the manual book (because they want us to bring it to them). So try to find out by browsing (make sure you get it from trusted source), and cross check from several sources.
Step 2. Disassemble the UPS to ensure the battery type
Let’s disassemble the UPS, and see the battery type. Prepare a screwdriver.
These are the steps to disassemble the UPS:
a. Pull battery connector out.
Notice that behind the UPS, there’s a yellow rectangle that reads “battery connector”. You have to pull it out to cut out the connection between battery and UPS.
Make sure the battery connector is completely detached. Remove it from the slot. Don’t let it hang in the slot. Place it on the holder above the slot (see in image below).
It turns out that the battery comes from brand called CSB. On the battery, there’s a lot of code such as MH14533(n) and UPS 12360 6 F2.
If you familiar with electronics concept, you might get the suitable battery for your UPS by only knowing the battery type. You could find another choice that will fit, or even do modification to the battery.
Because I’m just a regular people, that have no understanding in electronics concept, I will find the exactly the same battery.
Ups battery connector cable
9-PIN MALE MINI DIN CONNECTOR TO 9-PIN MALE MINI DIN CONNECTOR
This cable is terminated with 9-pin male mini DIN connectors on each end. This assembly is designed to connect a power adapter to a desktop ONT and features CMX/CMR outdoor rated cable.
View Schematic
3-PIN CONNECTOR TO BARREL CONNECTOR
This cable is terminated with a 3-pin connector and a 5.5mm x 2.1mm DC male power connector. This assembly is designed to connect a power adaptor to a desktop ONT.
View Schematic
7-PIN CONNECTOR TO BARREL CONNECTOR
This cable is terminated with a 7-pin, 3.5mm pitch connector and a 5.5mm x 2.5mm DC male power connector. This assembly is designed to connect a battery backup system to a desktop ONT.
View Schematic
3-PIN CONNECTOR TO 8-PIN (2X4) CONNECTOR
This cable is terminated with a 3-pin connector and an 8-pin (2×4) connector. This assembly is designed to connect a power adapter to a desktop ONT and features CMX/CMR outdoor rated cable.
View Schematic