Pwnagotchi

https://pwnagotchi.ai/
Admin
Pwnagotchi is an AI-powered tool running on Raspberry Pi that learns to maximize WiFi WPA handshake...
Tokens:36,306
Snippets:281
Trust Score:8.9
Update:4 months ago
Show doc for...
Tokens:
Raw
### Installing bettercap on GNU/Linux

Source: https://pwnagotchi.ai/installation

Download, unzip, and install the bettercap binary on a GNU/Linux system. It is recommended to verify the SHA-256 digest of the downloaded file before proceeding with the installation. Change the URL to match the precompiled binary of the latest release for your specific architecture.

```bash
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/

```

--------------------------------

### Example Pwnagotchi First Boot Configuration

Source: https://pwnagotchi.ai/configuration

This is an example of a complete config.toml file for a Pwnagotchi's first boot, including PwnGrid settings and display configuration.

```toml
main.name = "pwnagotchi"
main.whitelist = [
  "YourHomeNetworkMaybe"
]

main.plugins.grid.enabled = true
main.plugins.grid.report = true
main.plugins.grid.exclude = [
  "YourHomeNetworkMaybe"
]

ui.display.type = "inky"
ui.display.color = "black"


```

--------------------------------

### Download and Install pwngrid

Source: https://pwnagotchi.ai/installation

Downloads, unzips, and installs the pwngrid binary. It's recommended to check the SHA256 digest before moving the file.

```bash
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

```

--------------------------------

### Example Response for GET /api/v1/mesh/data

Source: https://pwnagotchi.ai/api/local

This is an example response from the /api/v1/mesh/data endpoint, showing the current advertisement data.

```json
{
    "epoch": 9,
    "face": "(◕‿‿◕)",
    "identity": "ca1225b86dc35fef90922d83421d2fc9c824e95b864cfa62da7bea64ffb05aea",
    "name": "alpha",
    "policy": {
        "advertise": true,
        "ap_ttl": 120,
        "associate": true,
        "bored_num_epochs": 15,
        "channels": [],
        "deauth": true,
        "excited_num_epochs": 10,
        "hop_recon_time": 10,
        "max_inactive_scale": 2,
        "max_interactions": 3,
        "max_misses_for_recon": 5,
        "min_recon_time": 5,
        "min_rssi": -200,
        "recon_inactive_multiplier": 2,
        "recon_time": 30,
        "sad_num_epochs": 25,
        "sta_ttl": 300
    },
    "pwnd_run": 0,
    "pwnd_tot": 424,
    "uptime": 19031,
    "version": "1.0.0RC4"
}
```

--------------------------------

### Downloading and Installing bettercap

Source: https://pwnagotchi.ai/installation/#pwngrid

Download the latest release of bettercap for Linux AMD64, unzip it, and move the binary to `/usr/bin/`. It is crucial to verify the SHA-256 digest of the downloaded file before proceeding with the installation.

```bash
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 Bluetooth networking packages

Source: https://pwnagotchi.ai/hacks

Installs necessary packages for Bluetooth networking, including BlueZ, bridge utilities, and dnsmasq.

```bash
sudo apt-get install bluez bluez-tools bridge-utils dnsmasq
```

--------------------------------

### Install bettercap and update UI

Source: https://pwnagotchi.ai/installation

Installs bettercap and updates its UI components. This command also quits bettercap after execution.

```bash
sudo bettercap -eval "caplets.update; ui.update; quit"
```

--------------------------------

### Example Response for GET /api/v1/mesh/peers

Source: https://pwnagotchi.ai/api/local

This is an example response from the /api/v1/mesh/peers endpoint, showing detected nearby units and their associated data.

```json
[{
	"detected_at": "2019-10-06T22:56:06Z",
	"seen_at": "2019-10-06T22:56:06Z",
	"channel": 10,
	"RSSI": -70,
	"session_id": "de:ad:be:ef:de:ad",
	"advertisement": {
		"epoch": 9,
		"face": "(◕‿‿◕)",
		"identity": "ca1225b86dc35fef90922d83421d2fc9c824e95b864cfa62da7bea64ffb05aea",
		"name": "alpha",
		"policy": {
			"advertise": true,
			"ap_ttl": 120,
			"associate": true,
			"bored_num_epochs": 15,
			"channels": [],
			"deauth": true,
			"excited_num_epochs": 10,
			"hop_recon_time": 10,
			"max_inactive_scale": 2,
			"max_interactions": 3,
			"max_misses_for_recon": 5,
			"min_recon_time": 5,
			"min_rssi": -200,
			"recon_inactive_multiplier": 2,
			"recon_time": 30,
			"sad_num_epochs": 25,
			"sta_ttl": 300
		},
		"pwnd_run": 0,
		"pwnd_tot": 424,
		"uptime": 19031,
		"version": "1.0.0RC4"
	}
},
...]
```

--------------------------------

### Install Pwnagotchi Python Package

Source: https://pwnagotchi.ai/installation

Downloads, unzips, and installs the Pwnagotchi Python codebase and its requirements using pip.

```bash
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 .

```

--------------------------------

### GET /api/v1/data Example Response

Source: https://pwnagotchi.ai/api/local

Retrieves the current data being sent to the enrollment API. This includes brain, session, and system information.

```json
{
	"brain": {
		"born_at": 1569086045.8648627,
		"epochs_lived": 6435,
		"epochs_trained": 6295,
		"rewards": {
			"best": 1.052142857142857,
			"worst": -120000000000000000000
		}
	},
	"session": {
		"associated": 5,
		"avg_reward": 0.00945353791507638,
		"deauthed": 1,
		"duration": "00:31:06",
		"epochs": 13,
		"handshakes": 0,
		"max_reward": 0.16214285714285717,
		"min_reward": -0.2,
		"peers": 0,
		"train_epochs": 0
	},
	"uname": "Linux alpha 4.19.66-Re4son+ #1 Sun Aug 18 13:42:02 AEST 2019 armv6l GNU/Linux",
	"version": "1.0.0RC4"
}
```

--------------------------------

### Install fbi for display

Source: https://pwnagotchi.ai/hacks

Installs the Framebuffer Imageviewer utility, which is used to display images on the Pwnagotchi screen.

```bash
apt install fbi
```

--------------------------------

### Example Response for GET /api/v1/units

Source: https://pwnagotchi.ai/api/grid

This is an example JSON response for the GET /api/v1/units endpoint, which returns a paged list of enrolled units. The response includes details such as enrollment date, country, name, public key, and associated data like advertisement, brain, and session information.

```json
{
	"pages": 17,
	"records": 409,
	"units": [{
		"enrolled_at": "2019-10-06T22:56:06Z",
		"updated_at": "2019-10-15T09:57:37Z",
		"country": "IT",
		"name": "alpha",
		"fingerprint": "ca1225b86dc35fef90922d83421d2fc9c824e95b864cfa62da7bea64ffb05aea",
		"public_key": "-----BEGIN RSA PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAzJQRTn1KDdIxduFq/pB+\nQ/+pNtvegmGAmzwb3YlP+SzhihbBUIOx85TodOEQZ1efUZy6Jn3ig6gPib3a2JsM\nT85P/Fxwfz6HrC8UlaOMaDyMksDgO7ZBM4zxthL8kgwtF9N7BYXn9nBZ2ReS1Gua\ncwayBkcMUlX83fpFe15fosXF3WeBO6jSa56YLuYDaxugUODhHR9C30n6okR2wssx\n2mUK6r6/smhSqoXwLttej4YvLi0NEvhdgp1Qy5zNHdcMhqJcxvbhFrJFx4JFZLdR\nLshs2nwTQq3rwyqC8nZvHCxXOdmFXBlSY6nQzILPLVlbeUYACeyfrOGFwdsXxq8u\nk/+Q6h9MFvdDGErv16eDYd0t/s0c0h8rHcGZpPYSE/zWviM+vQgpBPUEE4JBFNro\nxCOUjVtTWHlsjnp5dIQexagXm1/5jP1ko/q9Mf/ex3WUyadIqyoJoM8M7SlkUMYW\n39Yf/Zf52dTz4gUTUtSuMwvKvO94sa33RXxQIKXhecyjh1pJ6X1QYEcxWqCFs+qf\ns3AqNeHl7h2O6ouEuZNtkRg6+cy8zYD0ZrmwMphE5tqNm1L8lpdgaNzKnOSTcTfW\nU6wDIwC/8DkANfRds5ngA+SXCkI2LI8ujthLAi25e7qY57lAKCMdK15njcQftfiS\nEgdfHZVIDLO+lLw/ZqrAqRMCAwEAAQ==\n-----END RSA PUBLIC KEY-----
",
		"data": {
			"advertisement": {
				"epoch": 9,
				"face": "(◕‿‿◕)",
				"identity": "ca1225b86dc35fef90922d83421d2fc9c824e95b864cfa62da7bea64ffb05aea",
				"name": "alpha",
				"policy": {
					"advertise": true,
					"ap_ttl": 120,
					"associate": true,
					"bored_num_epochs": 15,
					"channels": [],
					"deauth": true,
					"excited_num_epochs": 10,
					"hop_recon_time": 10,
					"max_inactive_scale": 2,
					"max_interactions": 3,
					"max_misses_for_recon": 5,
					"min_recon_time": 5,
					"min_rssi": -200,
					"recon_inactive_multiplier": 2,
					"recon_time": 30,
					"sad_num_epochs": 25,
					"sta_ttl": 300
				},
				"pwnd_run": 0,
				"pwnd_tot": 424,
				"uptime": 19031,
				"version": "1.0.0RC4"
			},
			"brain": {
				"born_at": 1569086045.8648627,
				"epochs_lived": 6435,
				"epochs_trained": 6295,
				"rewards": {
					"best": 1.052142857142857,
					"worst": -120000000000000000000
				}
			},
			"session": {
				"associated": 5,
				"avg_reward": 0.00945353791507638,
				"deauthed": 1,
				"duration": "00:31:06",
				"epochs": 13,
				"handshakes": 0,
				"max_reward": 0.16214285714285717,
				"min_reward": -0.2,
				"peers": 0,
				"train_epochs": 0
			},
			"uname": "Linux alpha 4.19.66-Re4son+ #1 Sun Aug 18 13:42:02 AEST 2019 armv6l GNU/Linux",
			"version": "1.0.0RC4"
		},
		"networks": 419
	},
    ...
    ...]
}
```

--------------------------------

### OledHat Display Implementation

Source: https://pwnagotchi.ai/contributing

An example implementation of the DisplayImpl for the OledHat display. It defines specific layout dimensions and initialization for the hardware.

```python
import logging

import pwnagotchi.ui.fonts as fonts
from pwnagotchi.ui.hw.base import DisplayImpl


class OledHat(DisplayImpl):
    def __init__(self, config):
        super(OledHat, self).__init__(config, 'oledhat')
        self._display = None

    def layout(self):
        fonts.setup(8, 8, 8, 8)
        self._layout['width'] = 128
        self._layout['height'] = 64
        self._layout['face'] = (0, 32)
        self._layout['name'] = (0, 10)
        self._layout['channel'] = (0, 0)
        self._layout['aps'] = (25, 0)
        self._layout['uptime'] = (65, 0)
        self._layout['line1'] = [0, 9, 128, 9]
        self._layout['line2'] = [0, 53, 128, 53]
        self._layout['friend_face'] = (0, 41)
        self._layout['friend_name'] = (40, 43)
        self._layout['shakes'] = (0, 53)
        self._layout['mode'] = (103, 10)
        self._layout['status'] = {
            'pos': (30, 18),
            'font': fonts.Small,
            'max': 18
        }
        return self._layout

    def initialize(self):
        logging.info("initializing oledhat display")
        from pwnagotchi.ui.hw.libs.waveshare.oledhat.epd import EPD
        self._display = EPD()
        self._display.init()
        self._display.Clear()

    def render(self, canvas):
        self._display.display(canvas)

    def clear(self):
        self._display.clear()

```

--------------------------------

### Example Request for POST /api/v1/mesh/data

Source: https://pwnagotchi.ai/api/local

This is an example request for the POST /api/v1/mesh/data endpoint, used to set advertisement data. Fields not present will be added, and fields set to null will be deleted.

```json
{
    "twitter_name": "evilsocket",
    "face": "NOFACE"
}
```

--------------------------------

### Example Encrypted Container Definitions

Source: https://pwnagotchi.ai/configuration

Examples of how to define encrypted containers, mapping a file-based container and an external storage device.

```plaintext
config /cryptobox1 /etc/pwnagotchi # /cryptobox1 is some file
handshakes /dev/sdb /root/handshakes # /dev/sdb is some external storage
```

--------------------------------

### Configure Static IP Address

Source: https://pwnagotchi.ai/configuration

This is an example of the network interface configuration you should see after setting a static IP address on your host machine.

```text
inet 10.0.0.1  netmask 255.255.255.0  broadcast 10.0.0.255
```

--------------------------------

### Start Bluetooth services and agents

Source: https://pwnagotchi.ai/hacks

Initiates Bluetooth services, agents, and network adapters on the Pwnagotchi. This makes the device discoverable and pairable via Bluetooth, and sets up the network interface for connections.

```bash
sudo bt-agent -c NoInputNoOutput&
sudo bt-adapter -a hci0 --set Discoverable 1
sudo bt-adapter -a hci0 --set DiscoverableTimeout 0
sudo bt-adapter -a hci0 --set Pairable 1
sudo bt-adapter -a hci0 --set PairableTimeout 0
sudo bt-network -a hci0 -s nap pan0 &
```

--------------------------------

### Example Request for POST /api/v1/unit/{fingerprint}/inbox

Source: https://pwnagotchi.ai/api/local

This is an example of data that can be sent as a message payload when using the POST /api/v1/unit/{fingerprint}/inbox endpoint. The content will be encrypted and signed locally.

```text
Anything that's sent as POST data will be used as a message.
```

--------------------------------

### Run Pwnagotchi in different modes

Source: https://pwnagotchi.ai/installation

Commands to start Pwnagotchi in AUTO or MANU mode, with or without debug logs, and to display help options.

```bash
# 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

```

--------------------------------

### POST /api/v1/data Example Request

Source: https://pwnagotchi.ai/api/local

Sets data to be sent to the enrollment API. New fields are added, and fields set to null are deleted.

```json
{
	"something": "new"
}
```

--------------------------------

### Encrypt Configuration Directory

Source: https://pwnagotchi.ai/configuration

Step-by-step guide to encrypting the Pwnagotchi configuration directory using LUKS, including creating a container, formatting, mounting, and updating the configuration file.

```bash
# create a container file
dd if=/dev/zero of=/cryptobox bs=1M count=100
# make it luks-ready! You'll be asked for a password. Remember it,
because you will have to type it everytime you start your pwnagotchi.
cryptsetup luksFormat /cryptobox
# Now we can open it (you'll have to type your password in)
cryptsetup luksOpen /cryptobox cryptobox
# create a ext4 filesystem
mkfs.ext4 /dev/mapper/cryptobox
# mount it to /mnt
mount /dev/mapper/cryptobox /mnt
# now we copy all the configs to /mnt/
cp /etc/pwnagotchi/* /mnt/
# remove the old files
rm /etc/pwnagotchi/*
# tell pwnagotchi about the encrypted container
echo "cryptobox /cryptobox /etc/pwnagotchi" > /root/.pwnagotchi-crypted
```

--------------------------------

### Manage Pwnagotchi Plugins via CLI

Source: https://pwnagotchi.ai/plugins

Use the 'pwnagotchi plugins' subcommand to manage plugins. This includes actions like searching, listing, updating, enabling, disabling, installing, and uninstalling plugins.

```bash
usage: pwnagotchi plugins [-h]
                          {search,list,update,upgrade,enable,disable,install,uninstall,edit}
                          ...
```

```bash
positional arguments:
  {search,list,update,upgrade,enable,disable,install,uninstall,edit}
    search              Search for pwnagotchi plugins
    list                List available pwnagotchi plugins
    update              Updates the database
    upgrade             Upgrades plugins
    enable              Enables a plugin
    disable             Disables a plugin
    install             Installs a plugin
    uninstall           Uninstalls a plugin
    edit                Edit the options

optional arguments:
  -h, --help            show this help message and exit


```

--------------------------------

### API Request with JWT Authentication

Source: https://pwnagotchi.ai/api/grid

This example shows how to make a POST request to an API endpoint that requires JWT authentication. Ensure the 'Authorization' header includes the valid JWT token.

```http
POST https://api.pwnagotchi.ai/api/v1/some-api-path
...
...
Authorization: token ... JWT token here ...
...
```

--------------------------------

### GPS Plugin Example for Pwnagotchi

Source: https://pwnagotchi.ai/plugins

This Python code implements a GPS plugin that saves GPS coordinates to a JSON file whenever a handshake is captured. It requires the 'gps.device' and 'gps.speed' options to be configured.

```python
import logging
import json
import os
import pwnagotchi.plugins as plugins


class GPS(plugins.Plugin):
    __author__ = 'evilsocket@gmail.com'
    __version__ = '1.0.0'
    __license__ = 'GPL3'
    __description__ = 'Save GPS coordinates whenever an handshake is captured.'

    def __init__(self):
        self.running = False

    def on_loaded(self):
        logging.info("gps plugin loaded for %s" % self.options['device'])

    def on_ready(self, agent):
        if os.path.exists(self.options['device']):
            logging.info("enabling gps bettercap's module for %s" % self.options['device'])
            try:
                agent.run('gps off')
            except:
                pass

            agent.run('set gps.device %s' % self.options['device'])
            agent.run('set gps.speed %d' % self.options['speed'])
            agent.run('gps on')
            self.running = True
        else:
            logging.warning("no GPS detected")

    def on_handshake(self, agent, filename, access_point, client_station):
        if self.running:
            info = agent.session()
            gps = info['gps']
            gps_filename = filename.replace('.pcap', '.gps.json')

            logging.info("saving GPS to %s (%s)" % (gps_filename, gps))
            with open(gps_filename, 'w+t') as fp:
                json.dump(gps, fp)

```

--------------------------------

### Example Response for GET /api/v1/inbox/{id}

Source: https://pwnagotchi.ai/api/local

This JSON object represents a typical response when retrieving a message from the inbox. It includes metadata about the message and its content.

```json
{
    "id": 123,
    "created_at": "2019-10-06T22:56:06Z",
    "updated_at": "2019-10-06T22:56:06Z",
    "deleted_at": null,
    "seen_at": null,
    "sender_name": "alpha",
    "sender": "ca1225b86dc35fef90922d83421d2fc9c824e95b864cfa62da7bea64ffb05aea",
    "data": "base64 encoded cleartext message data",
    "signature": "base64 encoded RSA-PSS signature of the encrypted data"
}
```

--------------------------------

### Enable Full PwnGrid Participation

Source: https://pwnagotchi.ai/configuration

To fully opt-in to PwnGrid and participate in community rankings and statistics, enable the grid plugin and set report to true in your config.toml file.

```toml
main.plugins.grid.enabled = true
main.plugins.grid.report = true # full-opt in

```

--------------------------------

### Configure Pwnagotchi for Waveshare 3.5" SPI TFT screen

Source: https://pwnagotchi.ai/hacks

Sets up symlinks for displaying Pwnagotchi images and configures the system to use the Waveshare 3.5" SPI TFT screen. Ensure 'dwc2' and 'g_ether' are loaded and 'dwc2' overlay is present.

```bash
cd ~
ln -s pwnagotchi.png pwnagotchi_1.png
ln -s pwnagotchi.png pwnagotchi_2.png
ln -s pwnagotchi.png pwnagotchi_3.png
```

```bash
fbi -T 1 -a -noverbose -t 15 -cachemem 0 /root/pwnagotchi_1.png /root/pwnagotchi_2.png /root/pwnagotchi_3.png &
```

--------------------------------

### Configure Memory Mount Settings

Source: https://pwnagotchi.ai/configuration

Detailed configuration for memory mounts, including mount point, size, sync interval, and compression options. Recommended to use zram and rsync for efficiency.

```ini
fs.memory.mounts.log.enabled = true     # switch
fs.memory.mounts.log.mount = "/var/log" # which directory to map into memory
fs.memory.mounts.log.size = "50M"       # max size to put into memory
fs.memory.mounts.log.sync = 60          # interval in seconds to sync back onto disk
fs.memory.mounts.log.zram = true        # use zram for compression (recommended)
fs.memory.mounts.log.rsync = true       # use rsync to copy only the difference (recommended)
```

--------------------------------

### GET /api/v1/mesh/memory

Source: https://pwnagotchi.ai/api/local

Retrieves a list of all unique units that have been encountered by the Pwnagotchi device.

```APIDOC
## GET /api/v1/mesh/memory

### Description
Returns a list of all the units that have ever been met.

### Method
GET

### Endpoint
/api/v1/mesh/memory

### Response
#### Success Response (200)
- **fingerprint** (string) - Unique identifier for the unit.
- **met_at** (string) - Timestamp when the unit was first met.
- **detected_at** (string) - Timestamp when the unit was detected.
- **seen_at** (string) - Timestamp when the unit was last seen.
- **prev_seen_at** (string) - Timestamp when the unit was previously seen.
- **encounters** (integer) - Number of encounters with the unit.
- **channel** (integer) - The WiFi channel the unit was detected on.
- **rssi** (integer) - Received Signal Strength Indicator.
- **session_id** (string) - The session ID of the unit.
- **advertisement** (object) - Advertisement data from the unit.
  - **epoch** (integer)
  - **face** (string)
  - **grid_version** (string)
  - **identity** (string)
  - **name** (string)
  - **policy** (object)
  - **pwnd_run** (integer)
  - **pwnd_tot** (integer)
  - **session_id** (string)
  - **timestamp** (integer)
  - **uptime** (integer)
  - **version** (string)

### Response Example
```json
[
  {
    "fingerprint": "b3ee4a482bdc6fb41d17961948dc8d19fb4d3e8cd10c475f2785c384fdb32c0f",
    "met_at": "0001-01-01T00:00:00Z",
    "detected_at": "2019-10-24T18:22:50.916146256+01:00",
    "seen_at": "2019-10-24T18:38:26.352928748+01:00",
    "prev_seen_at": "2019-10-24T18:38:26.026575031+01:00",
    "encounters": 52339,
    "channel": 4,
    "rssi": -4,
    "session_id": "fe:8c:cc:b7:28:3b",
    "advertisement": {
      "epoch": 94,
      "face": "( ⚆_⚆)",
      "grid_version": "1.7.6",
      "identity": "b3ee4a482bdc6fb41d17961948dc8d19fb4d3e8cd10c475f2785c384fdb32c0f",
      "name": "ribbon",
      "policy": {
        "advertise": true,
        "ap_ttl": 30,
        "associate": true,
        "bored_num_epochs": 5,
        "channels": [],
        "deauth": true,
        "excited_num_epochs": 5,
        "hop_recon_time": 5,
        "max_inactive_scale": 3,
        "max_interactions": 1,
        "max_misses_for_recon": 3,
        "min_recon_time": 1,
        "min_rssi": -200,
        "recon_inactive_multiplier": 1,
        "recon_time": 5,
        "sad_num_epochs": 5,
        "sta_ttl": 60
      },
      "pwnd_run": 4,
      "pwnd_tot": 17,
      "session_id": "fe:8c:cc:b7:28:3b",
      "timestamp": 1571636023,
      "uptime": 15382,
      "version": "1.0.0RC5"
    }
  }
]
```
```

--------------------------------

### GET /api/v1/mesh/data

Source: https://pwnagotchi.ai/api/local

Retrieves the current advertisement data used by the Pwnagotchi unit.

```APIDOC
## GET /api/v1/mesh/data

### Description
Gets the data that is currently used for advertisement by this Pwnagotchi unit.

### Method
GET

### Endpoint
/api/v1/mesh/data

### Response
#### Success Response (200)
- **data** (object) - The advertisement data.
  - **epoch** (integer) - Current epoch number.
  - **face** (string) - Emoticon representing the unit's state.
  - **identity** (string) - Unique identity hash of the unit.
  - **name** (string) - Name of the unit.
  - **policy** (object) - Unit's policy configuration.
  - **pwnd_run** (integer) - Number of successful runs in the current session.
  - **pwnd_tot** (integer) - Total number of successful runs.
  - **uptime** (integer) - Uptime of the unit in seconds.
  - **version** (string) - Software version of the unit.

### Response Example
```json
{
    "epoch": 9,
    "face": "(◕‿‿◕)",
    "identity": "ca1225b86dc35fef90922d83421d2fc9c824e95b864cfa62da7bea64ffb05aea",
    "name": "alpha",
    "policy": {
        "advertise": true,
        "ap_ttl": 120,
        "associate": true,
        "bored_num_epochs": 15,
        "channels": [],
        "deauth": true,
        "excited_num_epochs": 10,
        "hop_recon_time": 10,
        "max_inactive_scale": 2,
        "max_interactions": 3,
        "max_misses_for_recon": 5,
        "min_recon_time": 5,
        "min_rssi": -200,
        "recon_inactive_multiplier": 2,
        "recon_time": 30,
        "sad_num_epochs": 25,
        "sta_ttl": 300
    },
    "pwnd_run": 0,
    "pwnd_tot": 424,
    "uptime": 19031,
    "version": "1.0.0RC4"
}
```
```

--------------------------------

### GET /api/v1/units/by_country

Source: https://pwnagotchi.ai/api/grid

Retrieves a list of countries and the number of Pwnagotchi units registered in each.

```APIDOC
## GET /api/v1/units/by_country

### Description
Get a list of countries and number of units registered for each.

### Method
GET

### Endpoint
/api/v1/units/by_country

### Response
#### Success Response (200)
- **country** (string) - The country code.
- **units** (integer) - The number of units registered in that country.

### Response Example
```json
[
  {
    "country": "US",
    "units": 117
  },
  {
    "country": "DE",
    "units": 58
  }
]
```
```

--------------------------------

### GET /api/v1/unit/inbox

Source: https://pwnagotchi.ai/api/grid

Retrieve a paged list of all PwnMAIL inbox messages associated with the unit.

```APIDOC
## GET /api/v1/unit/inbox

### Description
Get a paged list of all PwnMAIL inbox messages.

### Method
GET

### Endpoint
/api/v1/unit/inbox

### Response
#### Success Response (200)
- **pages** (integer) - The total number of pages available.
- **records** (integer) - The total number of messages.
- **messages** (array) - A list of message objects.
  - **id** (integer) - The unique identifier of the message.
  - **created_at** (string) - The timestamp when the message was created.
  - **updated_at** (string) - The timestamp when the message was last updated.
  - **deleted_at** (string) - The timestamp when the message was deleted (null if not deleted).
  - **seen_at** (string) - The timestamp when the message was last seen (null if not seen).
  - **sender_name** (string) - The name of the message sender.
  - **sender** (string) - The identifier of the message sender.

### Response Example
```json
{
	"pages": 1,
	"records": 1,
	"messages": [{
        "id": 123,
        "created_at": "2019-10-06T22:56:06Z",
        "updated_at": "2019-10-06T22:56:06Z",
        "deleted_at": null,
        "seen_at": null,
        "sender_name": "alpha",
        "sender": "ca1225b86dc35fef90922d83421d2fc9c824e95b864cfa62da7bea64ffb05aea"
    }]
}
```
```

--------------------------------

### GET /api/v1/mesh/memory/{fingerprint}

Source: https://pwnagotchi.ai/api/local

Retrieves detailed historical information for a specific unit identified by its fingerprint.

```APIDOC
## GET /api/v1/mesh/memory/{fingerprint}

### Description
Return the historical information of a unit given its fingerprint.

### Method
GET

### Endpoint
/api/v1/mesh/memory/{fingerprint}

### Parameters
#### Path Parameters
- **fingerprint** (string) - Required - The unique fingerprint of the unit to retrieve historical data for.

### Response
#### Success Response (200)
- **fingerprint** (string) - Unique identifier for the unit.
- **met_at** (string) - Timestamp when the unit was first met.
- **detected_at** (string) - Timestamp when the unit was detected.
- **seen_at** (string) - Timestamp when the unit was last seen.
- **prev_seen_at** (string) - Timestamp when the unit was previously seen.
- **encounters** (integer) - Number of encounters with the unit.
- **channel** (integer) - The WiFi channel the unit was detected on.
- **rssi** (integer) - Received Signal Strength Indicator.
- **session_id** (string) - The session ID of the unit.
- **advertisement** (object) - Advertisement data from the unit.
  - **epoch** (integer)
  - **face** (string)
  - **grid_version** (string)
  - **identity** (string)
  - **name** (string)
  - **policy** (object)
  - **pwnd_run** (integer)
  - **pwnd_tot** (integer)
  - **session_id** (string)
  - **timestamp** (integer)
  - **uptime** (integer)
  - **version** (string)

### Response Example
```json
{
  "fingerprint": "e322e903cade856a6ae687795640f6a0f6b78132c15963825e73f6502795487f",
  "met_at": "0001-01-01T00:00:00Z",
  "detected_at": "2019-10-24T18:22:55.533569911+01:00",
  "seen_at": "2019-10-24T18:39:38.083348784+01:00",
  "prev_seen_at": "2019-10-24T18:39:37.527044326+01:00",
  "encounters": 41544,
  "channel": 5,
  "rssi": -12,
  "session_id": "57:61:8e:d0:b7:99",
  "advertisement": {
    "epoch": 69,
    "face": "(◕‿‿◕)",
    "grid_version": "1.7.6",
    "identity": "e322e903cade856a6ae687795640f6a0f6b78132c15963825e73f6502795487f",
    "name": "squid",
    "policy": {
      "advertise": true,
      "ap_ttl": 30,
      "associate": true,
      "bored_num_epochs": 5,
      "channels": [],
      "deauth": true,
      "excited_num_epochs": 5,
      "hop_recon_time": 5,
      "max_inactive_scale": 3,
      "max_interactions": 1,
      "max_misses_for_recon": 3,
      "min_recon_time": 1,
      "min_rssi": -200,
      "recon_inactive_multiplier": 1,
      "recon_time": 5,
      "sad_num_epochs": 5,
      "sta_ttl": 60
    },
    "pwnd_run": 2,
    "pwnd_tot": 10,
    "session_id": "57:61:8e:d0:b7:99",
    "timestamp": 1571628894,
    "uptime": 15389,
    "version": "1.0.0RC5"
  }
}
```
```

--------------------------------

### Initial Pwnagotchi Configuration

Source: https://pwnagotchi.ai/configuration

This TOML snippet defines basic Pwnagotchi settings including unit name, language, whitelisted networks, and enables the grid plugin. It also configures the display type and color.

```toml
main.name = "pwnagotchi"
main.lang = "en"
main.whitelist = [
  "EXAMPLE_NETWORK",
  "ANOTHER_EXAMPLE_NETWORK",
  "fo:od:ba:be:fo:od",
  "fo:od:ba"
]

main.plugins.grid.enabled = true
main.plugins.grid.report = true
main.plugins.grid.exclude = [
  "YourHomeNetworkHere"
]

ui.display.enabled = true
ui.display.type = "waveshare_2"
ui.display.color = "black"


```

--------------------------------

### GET /api/v1/unit/inbox/{id}/{mark}

Source: https://pwnagotchi.ai/api/grid

Mark a message in the inbox as seen, unseen, or deleted using its identifier.

```APIDOC
## GET /api/v1/unit/inbox/{id}/{mark}

### Description
Mark a message given its identifier, mark can be `seen`, `unseen` or `deleted`.

### Method
GET

### Endpoint
/api/v1/unit/inbox/{id}/{mark}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the message.
- **mark** (string) - Required - The action to perform on the message. Can be `seen`, `unseen`, or `deleted`.
```

--------------------------------

### Build Custom Pwnagotchi Image

Source: https://pwnagotchi.ai/contributing

Command to create a zip file with the Pwnagotchi image and its sha256 checksum. Requires specific build tools.

```bash
make image

```
Tokens:
Raw