Create Your Own Custom Art & Expressions
Pwnagotchi displays various facial expressions on its e-ink/LCD screen to show its current mood and status. Face packs are collections of custom images that replace the default expressions.
Popular third-party face packs include:
| Tool | Purpose | Recommended |
|---|---|---|
| Image Editor | Create/edit face images | GIMP, Photoshop, Aseprite |
| Python 3 | For plugin-based faces | Python 3.7+ |
| SSH Client | Transfer files to device | OpenSSH, PuTTY |
| Text Editor | Edit config/Python files | VSCode, Nano, Vim |
Your face pack should follow this directory structure:
Image dimensions depend on your display type:
| Display Type | Resolution | Color Depth |
|---|---|---|
| Waveshare 2.13" V2 (e-ink) | 250 x 122 pixels | 1-bit B&W |
| Waveshare 2.13" V3 (e-ink) | 250 x 122 pixels | 1-bit B&W |
| Waveshare 2.7" (e-ink) | 264 x 176 pixels | 1-bit B&W |
| Waveshare 1.44" LCD HAT | 128 x 128 pixels | RGB 65K |
| Waveshare 1.3" LCD HAT | 240 x 240 pixels | RGB 65K |
| Pimoroni Inky pHAT | 212 x 104 pixels | Black/White/Red or Yellow |
Recommended Face Image Size:
Pwnagotchi has multiple emotional states. Here's what each face represents:
| Face File | When It's Displayed |
|---|---|
| look_r.png / look_l.png | Default idle state, looking around |
| look_r_happy.png / look_l_happy.png | Happy while looking around |
| sleep.png / sleep2.png | AI is sleeping (low activity) |
| awake.png | Just woke up from sleep |
| bored.png | No interesting APs found |
| intense.png | Actively attacking/deauthing |
| cool.png | Successfully captured handshake |
| happy.png | General positive state |
| grateful.png | Received a reward/bonus |
| excited.png | Found interesting targets |
| motivated.png | High epoch/good performance |
| demotivated.png | Poor performance/low rewards |
| smart.png | AI learned something new |
| lonely.png | No peers detected nearby |
| sad.png | Lost a peer connection |
| angry.png | Error occurred or attack failed |
| friend.png | Peer pwnagotchi detected! |
| broken.png | Critical error state |
| debug.png | Debug mode active |
| upload.png / upload1.png / upload2.png | Uploading handshakes (animated) |
The easiest way - just create PNG images for each mood:
You can also use text-based faces defined in the config:
# /etc/pwnagotchi/config.toml
ui.faces.look_r = "( ^_^)"
ui.faces.look_l = "(^_^ )"
ui.faces.look_r_happy = "( ^o^)"
ui.faces.look_l_happy = "(^o^ )"
ui.faces.sleep = "(-_-) zzZ"
ui.faces.sleep2 = "(-.-) zzZ"
ui.faces.awake = "(0_0)"
ui.faces.bored = "(-_-)"
ui.faces.intense = "(>_<)"
ui.faces.cool = "(B_B)"
ui.faces.happy = "(^_^)"
ui.faces.grateful = "(^_^)"
ui.faces.excited = "(*_*)"
ui.faces.motivated = "(9_9)"
ui.faces.demotivated = "(-.-)"
ui.faces.smart = "(^_~)"
ui.faces.lonely = "(;_;)"
ui.faces.sad = "(T_T)"
ui.faces.angry = "(`_')"
ui.faces.friend = "(^_^)"
ui.faces.broken = "(X_X)"
ui.faces.debug = "(#_#)"
ui.faces.upload = "(~_~)"
ui.faces.upload1 = "(-_~)"
ui.faces.upload2 = "(~_-)"
For advanced face packs with animations or dynamic content, create a Python plugin:
import pwnagotchi.plugins as plugins
import pwnagotchi.ui.faces as faces
from pwnagotchi.ui.components import LabeledValue
from pwnagotchi.ui.view import BLACK
import pwnagotchi.ui.fonts as fonts
from PIL import Image
import os
class MyCustomFaces(plugins.Plugin):
__author__ = 'YourName'
__version__ = '1.0.0'
__license__ = 'GPL3'
__description__ = 'Custom face pack with special effects'
__name__ = 'my_custom_faces'
__help__ = 'Custom face pack plugin'
__dependencies__ = {
'pip': ['pillow']
}
__defaults__ = {
'enabled': False,
}
def __init__(self):
self.faces_path = '/custom/plugins/my_faces/faces/'
def on_loaded(self):
# Load custom face images
self.load_custom_faces()
def load_custom_faces(self):
# Override default faces with custom images
face_files = {
'LOOK_R': 'look_r.png',
'LOOK_L': 'look_l.png',
'LOOK_R_HAPPY': 'look_r_happy.png',
'LOOK_L_HAPPY': 'look_l_happy.png',
'SLEEP': 'sleep.png',
'SLEEP2': 'sleep2.png',
'AWAKE': 'awake.png',
'BORED': 'bored.png',
'INTENSE': 'intense.png',
'COOL': 'cool.png',
'HAPPY': 'happy.png',
'GRATEFUL': 'grateful.png',
'EXCITED': 'excited.png',
'MOTIVATED': 'motivated.png',
'DEMOTIVATED': 'demotivated.png',
'SMART': 'smart.png',
'LONELY': 'lonely.png',
'SAD': 'sad.png',
'ANGRY': 'angry.png',
'FRIEND': 'friend.png',
'BROKEN': 'broken.png',
'DEBUG': 'debug.png',
'UPLOAD': 'upload.png',
'UPLOAD1': 'upload1.png',
'UPLOAD2': 'upload2.png',
}
for face_name, filename in face_files.items():
path = os.path.join(self.faces_path, filename)
if os.path.exists(path):
# Load and set the custom face
img = Image.open(path)
setattr(faces, face_name, img)
def on_ui_setup(self, ui):
# Optional: Add custom UI elements
pass
def on_ui_update(self, ui):
# Optional: Update faces dynamically
pass
# SSH into your pwnagotchi
ssh [email protected]
# Edit the config file
sudo nano /etc/pwnagotchi/config.toml
# Add your custom faces (see config example above)
# Save and exit (Ctrl+X, Y, Enter)
# Restart pwnagotchi
sudo systemctl restart pwnagotchi
# SSH into your pwnagotchi
ssh [email protected]
# Create directory for custom faces
sudo mkdir -p /usr/local/share/pwnagotchi/custom-faces/
# Copy your face images (from your computer)
scp -r ./my-face-pack/faces/* [email protected]:/tmp/
# On the pwnagotchi, move to proper location
sudo mv /tmp/*.png /usr/local/share/pwnagotchi/custom-faces/
# Update config to use custom faces path
sudo nano /etc/pwnagotchi/config.toml
Add to your config.toml:
ui.faces.path = "/usr/local/share/pwnagotchi/custom-faces/"
# Copy plugin file to custom plugins directory
sudo cp my_custom_faces.py /usr/local/share/pwnagotchi/custom-plugins/
# Copy face images
sudo mkdir -p /usr/local/share/pwnagotchi/custom-plugins/my_faces/faces/
sudo cp ./faces/*.png /usr/local/share/pwnagotchi/custom-plugins/my_faces/faces/
# Enable in config.toml
sudo nano /etc/pwnagotchi/config.toml
Add to config:
main.custom_plugins = "/usr/local/share/pwnagotchi/custom-plugins/"
main.plugins.my_custom_faces.enabled = true
sudo systemctl restart pwnagotchi
sudo tail -f /var/log/pwnagotchi.log
# You can force mood changes via bettercap API
# Connect to bettercap at http://10.0.0.2/
# Use the events tab to send mood triggers
# Or via command line:
curl -X POST http://10.0.0.2:8081/api/session \
-H "Content-Type: application/json" \
-d '{"cmd": "set wifi.show faces true"}'
Share your face pack with the community:
# My Awesome Pwnagotchi Face Pack
## Preview
## Installation
1. SSH into your pwnagotchi
2. Clone this repo: `git clone https://github.com/you/face-pack`
3. Run: `./install.sh`
4. Restart pwnagotchi
## Faces Included
| Mood | Preview |
|------|---------|
| Happy |  |
| Sad |  |
...
## Credits
Created by [YourName]
## License
GPL3
| Task | Command/Path |
|---|---|
| Config file | /etc/pwnagotchi/config.toml |
| Custom plugins | /usr/local/share/pwnagotchi/custom-plugins/ |
| Default faces | /usr/local/lib/python3.*/dist-packages/pwnagotchi/ui/faces.py |
| Restart service | sudo systemctl restart pwnagotchi |
| View logs | sudo tail -f /var/log/pwnagotchi.log |
| Web UI | http://10.0.0.2:8080 |
| Bettercap API | http://10.0.0.2:8081 |