Merge pull request #163 from hexwaxwing/master
minor copyediting + tamagotchi explainer + add'l screen info in docs
This commit is contained in:
evilsocket
GitHub
commit
b98ea59366
@ -16,12 +16,11 @@ full and half WPA handshakes.
|
||||
|
||||
|
||||
|
||||
Specifically, Pwnagotchi is using an [LSTM with MLP feature extractor](https://stable-baselines.readthedocs.io/en/master/modules/policies.html#stable_baselines.common.policies.MlpLstmPolicy) as its policy network for the [A2C agent](https://stable-baselines.readthedocs.io/en/master/modules/a2c.html). If you're unfamiliar with A2C, here is [a very good introductory explanation](https://hackernoon.com/intuitive-rl-intro-to-advantage-actor-critic-a2c-4ff545978752) (in comic form!) of the basic principles behind how Pwnagotchi learns. (You can read more about how Pwnagotchi learns in the [Usage](https://github.com/evilsocket/pwnagotchi/blob/master/docs/usage.md#training-the-ai) doc.)
|
||||
|
||||
|
||||
Instead of merely playing [Super Mario or Atari games](https://becominghuman.ai/getting-mario-back-into-the-gym-setting-up-super-mario-bros-in-openais-gym-8e39a96c1e41?gi=c4b66c3d5ced) like most reinforcement learning based "AI" *(yawn)*, Pwnagotchi tunes [its own parameters](https://github.com/evilsocket/pwnagotchi/blob/master/sdcard/rootfs/root/pwnagotchi/config.yml#L54) over time to **get better at pwning WiFi things** in the environments you expose it to.
|
||||
|
||||
**Keep in mind:** Unlike the usual RL simulations, Pwnagotchi actually learns over time. Time for a Pwnagotchi is measured in epochs; a single epoch can last from a few seconds to minutes, depending on how many access points and client stations are visible. Do not expect your Pwnagotchi to perform amazingly well at the very beginning, as it will be [exploring](https://hackernoon.com/intuitive-rl-intro-to-advantage-actor-critic-a2c-4ff545978752) several combinations of [key parameters](https://github.com/evilsocket/pwnagotchi/blob/master/docs/usage.md#training-the-ai) to determine ideal adjustments for pwning the particular environment you are exposing it to during its beginning epochs ... but **definitely listen to your pwnagotchi when it tells you it's bored!** Bring it into novel WiFi environments with you and have it observe new networks and capture new handshakes—and you'll see. :)
|
||||
More specifically, Pwnagotchi is using an [LSTM with MLP feature extractor](https://stable-baselines.readthedocs.io/en/master/modules/policies.html#stable_baselines.common.policies.MlpLstmPolicy) as its policy network for the [A2C agent](https://stable-baselines.readthedocs.io/en/master/modules/a2c.html). If you're unfamiliar with A2C, here is [a very good introductory explanation](https://hackernoon.com/intuitive-rl-intro-to-advantage-actor-critic-a2c-4ff545978752) (in comic form!) of the basic principles behind how Pwnagotchi learns. (You can read more about how Pwnagotchi learns in the [Usage](https://github.com/evilsocket/pwnagotchi/blob/master/docs/usage.md#training-the-ai) doc.)
|
||||
|
||||
**Keep in mind:** Unlike the usual RL simulations, Pwnagotchi actually learns over time. Time for a Pwnagotchi is measured in epochs; a single epoch can last from a few seconds to minutes, depending on how many access points and client stations are visible. Do not expect your Pwnagotchi to perform amazingly well at the very beginning, as it will be [exploring](https://hackernoon.com/intuitive-rl-intro-to-advantage-actor-critic-a2c-4ff545978752) several combinations of [key parameters](https://github.com/evilsocket/pwnagotchi/blob/master/docs/usage.md#training-the-ai) to determine ideal adjustments for pwning the particular environment you are exposing it to during its beginning epochs ... but **definitely listen to your Pwnagotchi when it tells you it's bored!** Bring it into novel WiFi environments with you and have it observe new networks and capture new handshakes—and you'll see. :)
|
||||
|
||||
Multiple units within close physical proximity can "talk" to each other, advertising their own presence to each other by broadcasting custom information elements using a parasite protocol I've built on top of the existing dot11 standard. Over time, two or more units trained together will learn to cooperate upon detecting each other's presence by dividing the available channels among them for optimal pwnage.
|
||||
|
||||
@ -29,6 +28,8 @@ Multiple units within close physical proximity can "talk" to each other, adverti
|
||||
|
||||
For hackers to learn reinforcement learning, WiFi networking, and have an excuse to get out for more walks. Also? **It's cute as f---**.
|
||||
|
||||
**In case you're curious about the name:** *Pwnagotchi* is a portmanteau of *pwn* (which we shouldn't have to explain if you are interested in this project :kissing_heart:) and *-gotchi*. It is a nostalgic reference made in homage to a very popular children's toy from the 1990s called the [Tamagotchi](https://en.wikipedia.org/wiki/Tamagotchi). The Tamagotchi (たまごっち, derived from *tamago* (たまご) "egg" + *uotchi* (ウオッチ) "watch") is a cultural touchstone for many Millennial hackers as a formative electronic toy from our collective childhoods. Were you lucky enough to possess a Tamagotchi as a kid? Well, with your Pwnagotchi, you too can enjoy the nostalgic delight of being strangely emotionally attached to a handheld automata *yet again!* Except, this time around...you get to #HackThePlanet. >:D
|
||||
|
||||
## Documentation
|
||||
---
|
||||
:warning: **THE FOLLOWING DOCUMENTATION IS BEING PREPARED FOR THE v1.0 RELEASE OF PWNAGOTCHI. Since this effort is an active (and unstable) work-in-progress, the docs displayed here are in various stages of [in]completion. There will be dead links and placeholders throughout as we are still building things out in preparation for the v1.0 release.** :warning:
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Connecting to your Pwnagotchi
|
||||
|
||||
Once you wrote the image file on the SD card, there're a few steps you'll have to follow in order to configure your unit properly, first, start with connecting the USB cable to the data port of the Raspberry Pi and the RPi to your computer. After a few seconds the board will boot and you will see a new Ethernet interface on your host computer.
|
||||
Once you wrote the image file on the SD card, there're a few steps you'll have to follow in order to configure your unit properly. First, start with connecting the USB cable to the data port of the Raspberry Pi and the RPi to your computer. After a few seconds, the board will boot and you will see a new Ethernet interface on your host computer.
|
||||
|
||||
You'll need to configure it with a static IP address:
|
||||
|
||||
@ -17,9 +17,9 @@ You can now connect to your unit using SSH:
|
||||
ssh pi@10.0.0.2
|
||||
```
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Moreover, it is recommended that you copy your SSH public key among the unit's authorized ones, so you can directly log in without entering a password:
|
||||
If you want to login directly without entering a password (recommended!), copy your SSH public key to the unit's authorized keys:
|
||||
|
||||
```bash
|
||||
ssh-copy-id -i ~/.ssh/id_rsa.pub pi@10.0.0.2
|
||||
@ -27,27 +27,27 @@ ssh-copy-id -i ~/.ssh/id_rsa.pub pi@10.0.0.2
|
||||
|
||||
## Configuration
|
||||
|
||||
You can now set a new name for your unit by [changing the hostname](https://geek-university.com/raspberry-pi/change-raspberry-pis-hostname/). Create the `/root/custom.yml` file (either via SSH or by direclty editing the SD card contents from a computer) that will override the [default configuration](https://github.com/evilsocket/pwnagotchi/blob/master/sdcard/rootfs/root/pwnagotchi/config.yml) with your custom values.
|
||||
You can now set a new name for your unit by [changing the hostname](https://geek-university.com/raspberry-pi/change-raspberry-pis-hostname/). Create the `/root/custom.yml` file (either via SSH or by directly editing the SD card contents from a computer) that will override the [default configuration](https://github.com/evilsocket/pwnagotchi/blob/master/sdcard/rootfs/root/pwnagotchi/config.yml) with your custom values.
|
||||
|
||||
## Language Selection
|
||||
|
||||
For instance, you can change `main.lang` to one of the supported languages:
|
||||
Pwnagotchi displays its UI in English by default, but it can speak several other languages! You can change `main.lang` to one of the supported languages:
|
||||
|
||||
- **english** (default)
|
||||
- german
|
||||
- dutch
|
||||
- greek
|
||||
- macedonian
|
||||
- italian
|
||||
- french
|
||||
- russian
|
||||
- swedish
|
||||
- **English** *(default)*
|
||||
- German
|
||||
- Dutch
|
||||
- Greek
|
||||
- Macedonian
|
||||
- Italian
|
||||
- French
|
||||
- Russian
|
||||
- Swedish
|
||||
|
||||
## Display Selection
|
||||
|
||||
Set the type of display you want to use via `ui.display.type` (if your display does not work after changing this setting, you might need to completely remove power from the Raspberry and make a clean boot).
|
||||
|
||||
You can configure the refresh interval of the display via `ui.fps`, we advise to use a slow refresh to not shorten the lifetime of your display. The default value is 0, which will only refresh when changes are made to the screen.
|
||||
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.
|
||||
|
||||
## Host Connection Share
|
||||
|
||||
@ -55,4 +55,4 @@ If you connect to the unit via `usb0` (thus using the data port), you might want
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
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 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`.
|
||||
|
||||
@ -2,35 +2,47 @@
|
||||
|
||||
The project has been developed to run on a Raspberry Pi 0 W configured as an [USB Ethernet gadget](https://learn.adafruit.com/turning-your-raspberry-pi-zero-into-a-usb-gadget/ethernet-gadget) device in order to connect to it via USB. However, given the proper configuration tweaks, any GNU/Linux computer with a WiFi interface that supports monitor mode could be used.
|
||||
|
||||
**An important note about the AI:** a network trained with a specific WiFi interface will only work with another interface if it supports
|
||||
the same exact WiFi channels of the first one. For instance, you can not use a neural network trained on a Raspberry Pi Zero W (that only supports 2.4Ghz channels) with a 5Ghz antenna, but you'll need to train one from scratch for those channels.
|
||||
**An important note about the AI:** a network trained with a specific WiFi interface will ONLY work with another interface if it supports the *exact same* WiFi channels of the first one. For instance, you CANNOT use a neural network trained on a Raspberry Pi Zero W (that only supports 2.4Ghz channels) with a 5Ghz antenna; you will need to train one from scratch for those channels.
|
||||
|
||||
## Required Hardware
|
||||
|
||||
- [Raspberry Pi Zero W](https://www.raspberrypi.org/products/raspberry-pi-zero-w/).
|
||||
- A micro SD card, 8GB recomended, **preferably of good quality and speed**.
|
||||
- [Raspberry Pi Zero W](https://www.raspberrypi.org/products/raspberry-pi-zero-w/).†
|
||||
- A micro SD card, 8GB recommended, **preferably of good quality and speed**.
|
||||
- A decent power bank (with 1500 mAh you get ~2 hours with AI on).
|
||||
- One of the supported displays (optional).
|
||||
|
||||
† Many users have gotten Pwnagotchi running on other types of Raspberry Pi, but the RPi0W is the "vanilla" hardware config for Pwnagotchi.
|
||||
|
||||
### Display
|
||||
|
||||
The display is an optional component as the UI is also rendered via a web interface available via the USB cable. If you connect to `usb0` (by using the data port on the unit) and point your browser to the web ui (see config.yml), your unit can work in "headless mode".
|
||||
The display is an optional component as the UI is also rendered via a web interface available via the USB cable. If you connect to `usb0` (by using the data port on the unit) and point your browser to the web ui (see `config.yml`), your unit can work in "headless mode".
|
||||
|
||||
If instead you want to fully enjoy walking around and literally looking at your unit's face, the supported display models are:
|
||||
If, instead, you want to fully enjoy walking around and literally looking at your unit's face, the supported display models are:
|
||||
|
||||
- [Waveshare eInk Display (both V1 and V2)](https://www.waveshare.com/2.13inch-e-paper-hat.htm)
|
||||
- [Product comparison](https://www.waveshare.com/4.3inch-e-paper.htm) (scroll down to `Selection Guide`)
|
||||
- [GitHub](https://github.com/waveshare/e-Paper/tree/master/RaspberryPi%26JetsonNano/python)
|
||||
- [Pimoroni Inky pHAT](https://shop.pimoroni.com/products/inky-phat)
|
||||
- [Product page](https://shop.pimoroni.com/products/inky-phat)
|
||||
- [GitHub](https://github.com/pimoroni/inky)
|
||||
- [PaPiRus eInk Screen](https://uk.pi-supply.com/products/papirus-zero-epaper-screen-phat-pi-zero)
|
||||
|
||||
Needless to say, we are always happy to receive pull requests adding support for new models.
|
||||
|
||||
One thing to note, not all displays are created equaly, TFT displays for example work similar to an HDMI display, and they are not supported, currently all the displays supported are I2C displays.
|
||||
**One thing to note:** Not all displays are created equally! TFT displays, for example, work similar to an HDMI display, and they are NOT supported. Currently, all the officially-supported displays are I2C displays. If you are still interested in using unsupported displays, you may be able to find a community-submitted hack in the [Screens](https://github.com/evilsocket/pwnagotchi/blob/master/docs/hacks.md#screens) section of the [Hacks](https://github.com/evilsocket/pwnagotchi/blob/master/docs/hacks.md) page. We are not responsible for anything you break by trying to use any display that is not officially supported by the development team!
|
||||
|
||||
#### Color and Black & White displays
|
||||
#### Color vs. Black & White displays
|
||||
|
||||
Some of the supported displays support Black & White and Coloured versions, one common question is regarding refresh speed of said displays.
|
||||
Some of the supported displays support both **Black & White** and **Colored** versions. One common question whether there are meaningful differences between the two. There are:
|
||||
- Color displays have a much slower refresh rate. In some cases, it can take up to 15 seconds; if slow refresh rates are something that you want to avoid, we recommend you use B&W displays.
|
||||
- The 3-color 2.13" Waveshare displays have a slightly smaller pixel layout (104x212) compared to their B&W counterparts (122x250).
|
||||
|
||||
Color displays have a much slower refresh rate, in some cases it can take up to 15 seconds, if slow refresh rates is something that you want to avoid we advise you to use Black & White displays
|
||||
#### Recommendations
|
||||
- Avoid the Waveshare eInk **3-color** display. The refresh time is 15 seconds.
|
||||
- Avoid the Pimoroni Inky pHAT **v1.** They're discontinued due to a faulty hardware part source used in manufacturing that resulted in high failure rates.
|
||||
- Many users seem to prefer the Inky pHATs. There are two primary reasons:
|
||||
- The Inkys feature better documentation and SDK support.
|
||||
- Many Waveshare resellers do not disclose the version of the Waveshare boards they are selling (v1 vs v2), and the type they are selling can be fairly unclear (i.e., Waveshare 2.13 vs 2.13 B vs. 2.13C, and so on.)
|
||||
|
||||
## Flashing an Image
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user