M5PORKCHOP

                    Volume Zero, Issue 3, Phile 1 of 1

                          M5PORKCHOP README
                          v0.1.8b-PSTH

                            ^__^
                            (oo)\_______
                            (__)\       )\/\
                                ||----w |
                                ||     ||
                (yes that's a cow. the pig ate the pig art budget.)
                (the horse was unavailable for comment.)


                67% of skids skip READMEs.
                100% of those skids report bugs we documented.
                the horse thinks this is valid.


                         TABLE OF CONTENTS

    1. WHAT THE HELL IS THIS
    2. MODES (what the pig does)
    3. THE PIGLET (mood, avatar, weather)
    4. THE FORBIDDEN CHEESE ECONOMY (XP, ranks, trophies)
    5. CLOUD HOOKUPS (WiGLE / WPA-SEC)
    6. PIGSYNC (son of a pig)
    7. THE MENUS
    8. CONTROLS
    9. SD CARD LAYOUT
    10. BUILDING
    11. LEGAL
    12. TROUBLESHOOTING (the confessional)
    13. GREETZ

    (pro tip: CTRL+F "horse" for enlightenment.
     we counted them. the horse counted more.
     one of us is wrong. both of us are the barn.)

+==============================================================+
|                                                              |
| [O] OINK MODE     - yoink handshakes. question ethics.       |
| [D] DO NO HAM     - zero TX. passive recon. zen pig.         |
| [W] WARHOG        - GPS wardriving. legs required.           |
| [H] SPECTRUM      - RF analysis. client hunting. fangs.      |
| [B] PIGGY BLUES   - BLE spam. YOU DIED. in that order.       |
| [F] FILE XFER     - web UI. civilization achieved.           |
| [*] BACON         - fake beacons. via MENU. worth the trip.  |
|                                                              |
| [1] PIG DEMANDS   - session challenges. three trials.        |
| [2] PIGSYNC       - the prodigal son answers the phone.      |
|                                                              |
| REMEMBER:                                                    |
| 1. only attack what you own or have written permission to    |
| 2. "because it can" is not a legal defense                   |
| 3. the pig watches. the law judges. know the difference.     |
|                                                              |
+==============================================================+

--[ 1 - WHAT THE HELL IS THIS

    three questions every operator asks:
    1. "what does it do?"
    2. "is it legal?"
    3. "why does the pig look disappointed in me?"


----[ 1.1 - THE ELEVATOR PITCH

    PORKCHOP runs on M5Cardputer (ESP32-S3, 240MHz, 8MB flash).
    it turns a pocket keyboard into a WiFi pentesting companion with:

    - promiscuous mode packet capture and EAPOL extraction
    - GPS wardriving with WiGLE v1.6 export
    - 2.4GHz spectrum analysis with client tracking
    - BLE notification spam (Apple/Android/Samsung/Windows)
    - beacon injection with vendor IE fingerprinting
    - device-to-device sync via ESP-NOW (PigSync)
    - a personality system with opinions about your choices

    it's a learning tool for WiFi security research.
    the difference between tool and weapon is the hand holding it. 
    wink. wink.


----[ 1.2 - THE LINEUP (what you're getting into)

    words are cheap. pixels are evidence.

    THE PIG IN THE FLESH:

    ![PIG PEN](docs/images/porkchop.jpg)
    *the pigs. awake. judging. 240x135 pixels of unsolicited opinions.*

    THE HARDWARE NAKED:

    ![Cardputer ADV with CapLoRa module](docs/images/hardware_cardputer_adv.jpg)
    *cardputer ADV + CapLoRa868. GPS + LoRa on a keyboard.*
    *smaller than your phone. more opinions than your family.*

    ![The full kit - Cardputer + CapLoRa + GPS antenna](docs/images/hardware_full_kit.jpg)
    *the full loadout. everything the pig needs to judge your neighborhood.*

    (photos missing? we're working on it. the pig doesn't pose for free.
     the horse refused the photoshoot entirely. barn lighting was wrong.)


----[ 1.3 - HARDWARE SPECS

    M5Cardputer (M5Stack StampS3):
        (EAPOL has M1, M2, M3, M4. the hardware is M5.
         the fifth message. the one the protocol never sent.
         we are the frame after the handshake.)
        - ESP32-S3FN8: 240MHz dual-core, 512KB SRAM, 8MB flash
        - NO PSRAM (~300KB usable heap. every byte matters.)
        - 240x135 IPS LCD (ST7789V2)
        - QWERTY keyboard (56 keys)
        - SD card slot (FAT32, shared SPI bus with CapLoRa)
        - NeoPixel LED (GPIO 21)
        - USB-C (power + serial)

    Optional:
        - GPS module: AT6668/ATGM336H (Grove port G1/G2 or CapLoRa)
        - CapLoRa868 module (G15/G13 GPS, SX1262 LoRa shares SD SPI)
        - Cardputer ADV: BMI270 IMU enables dial mode in Spectrum
        - your legs, for wardriving. no judgment on wheels.

    GET THE HARDWARE (the part where we sell out):

        look. we're going to be transparent here.
        these are affiliate links. we get a cut.
        you get a pig. capitalism works (sometimes).

        the pig doesn't mass-produce itself.
        the pig needs a body. the body needs a store.
        the store needs a link. the link needs a click.
        you see where this is going.

        M5Stack Cardputer ADV (the pig's body):
        https://shop.m5stack.com/products/m5stack-cardputer-adv-version-esp32-s3/?ref=xqezhcga

        CapLoRa 1262 (GPS + LoRa module, the pig's sense of direction):
        https://shop.m5stack.com/products/cap-lora-1262-for-cardputer-adv-sx1262-atgm336h?ref=xqezhcga

        buying through these links funds:
        1. coffee (which becomes code)
        2. code (which becomes bugs)
        3. bugs (which become trauma)
        4. trauma (which becomes coffee)
        5. the circle continues. you're an investor now.

        not buying? also valid. the pig judges purchases,
        not people. clone it, build it, source it however.
        open source means open source.

        but if you DO click... the pig remembers its friends.


----[ 1.4 - ARCHITECTURE (for the silicon gourmets)

    THE CORE:
    cooperative main loop. porkchop.update() (SFX ticks inside),
    Display::update(), Mood::update(). the pig's vital organs.
    single PorkchopMode enum, 24 states. one mode lives. the others wait.
    the pig is a finite state machine with infinite opinions.
    the horse is a barn with load-bearing feelings.

    THE MEMORY WAR:
    no PSRAM means ~300KB internal SRAM for everything.
    TLS needs ~35KB contiguous (kMinContigForTls in heap_policy.h).
    WiFi driver init needs ~70KB (why preInitWiFiDriverEarly() exists).
    the heap fragments like your relationship with sleep.

    HEAP CONDITIONING:
    boot runs a 5-phase ritual: frag blocks (50x1KB), struct blocks
    (20x3KB), TLS test allocs (26KB, 32KB, 40KB). exploits ESP-IDF's
    TLSF allocator for O(1) coalescing. the result: a clean brain
    for TLS handshakes. percussive maintenance for memory.
    the horse calls this "barn defragmentation."
    the barn denies having a defragmentation problem.
    the barn is the horse. denial is structural.

    HEAP MONITORING:
    heap_health.h samples every 1s. auto-triggers conditioning when
    health drops below 65%, clears when it recovers above 75%.
    adaptive cooldown: 15-60s between rounds (scales with heap state).
    the heart bar at the bottom of the screen is heap health.
    100% = clean. 0% = swiss cheese. the pig's blood pressure, basically.

    THE EVENT BUS:
    max 32 queued events, 16 processed per update tick.
    MODE_CHANGE, ML_RESULT, GPS_FIX, GPS_LOST,
    HANDSHAKE_CAPTURED, NETWORK_FOUND, DEAUTH_SENT,
    ROGUE_AP_DETECTED, OTA_AVAILABLE, LOW_BATTERY.
    the pig processes feelings through a state machine.
    the horse processes feelings through a k-hole.

    DUAL-CORE PATTERN:
    WiFi promiscuous callbacks run on core 1 (WiFi task).
    they CANNOT allocate memory or call Serial. instead:
    callback sets volatile flags + writes to static pools.
    main loop on core 0 checks flags and processes safely.
    this is the deferred event pattern. it keeps the WDT happy.
    WDT = Watchdog Timer. also What Did (The pig) Think.

    STATIC POOLS:
    OINK pre-allocates PendingHandshakeFrame pendingHsPool[4]
    (~13KB in BSS). permanent. std::atomic indices for lock-free
    producer/consumer between WiFi task and main loop.
    the pig pays rent on memory it might never use.

    NetworkRecon:
    shared background scanning service. OINK, DONOHAM, SPECTRUM,
    and WARHOG all consume the same getNetworks() vector.
    spinlock mutex with RAII CriticalSection wrapper.
    channel hop order: 1, 6, 11, then 2-5, 7-10, 12-13.
    max 200 networks tracked. the pig has limits.
    (200 is generous. the heap disagrees.)

    BOOT GUARD:
    RTC memory tracks rapid reboots. 3 in 60 seconds = force IDLE.
    crash loops get the nuclear option. the pig learns from pain.
    the horse calls this progress.

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

--[ 2 - MODES (what the pig does)

    one keypress from IDLE. zero menus. zero friction.
    each mode changes the pig's vocabulary.
    this is not a bug. this is character development.


----[ 2.1 - OINK MODE (active hunt) [O]

    the pig goes rowdy. opinions about APs become actionable.
    snout to the wire. tusks out.

    CAPABILITIES:
        - channel hop across 2.4GHz (13 channels, adaptive timing)
        - promiscuous mode 802.11 frame capture
        - EAPOL handshake extraction (M1-M4, validates sequence)
        - PMKID extraction from RSN IE in M1 frames
          (the AP just volunteers it. trust issues are real.)
        - deauth (Reason 7) + disassoc (Reason 8) with jitter
          (randomized inter-frame timing. less predictable to WIDS.
           the pig appreciates subtlety. the timing appreciates rank.)
        - PMF detectio