Feature/stella core

.github/workflows/build.yml

@@ -1,8 +1,13 @@
 name: Build
 
 on:
+  workflow_dispatch:
   push:
-    branches: [ main, develop, personality_disorder_innit ]
+    branches:
+      - main
+      - develop
+      - personality_disorder_innit
+      - 'feature/**'
   pull_request:
     branches: [ main ]
 
@@ -24,13 +29,17 @@ jobs:
           python -m pip install --upgrade pip
           pip install platformio
 
-      - name: Build firmware
+      - name: Build Stella firmware
         run: |
           pio run -e m5cardputer
 
+      - name: Run native tests
+        run: |
+          pio test -e native
+
       - name: Upload firmware artifact
         uses: actions/upload-artifact@v4
         with:
-          name: firmware
+          name: m5stella-firmware
           path: .pio/build/m5cardputer/firmware.bin
-          retention-days: 30
+          retention-days: 30

STELLA_ARCHITECTURE.md

@@ -0,0 +1,131 @@
+# M5STELLA architecture
+
+M5STELLA is a staged evolution of M5PORKCHOP into **Stella the Wardog**, an M5Cardputer wireless field companion designed to integrate directly with W33Z.
+
+The original MIT license and attribution remain intact. The migration is intentionally incremental so existing hardware behavior, SD cards and field data are not destroyed by a giant one-shot rename.
+
+## Design rules
+
+1. **Dog personality outside, boring protocol names inside.**
+   User-facing actions can be `Sniff`, `Stay`, `Heel`, `Fetch`, `Deliver` and `Bark`; the protocol remains `scan.start`, `scan.pause`, `scan.stop`, `sync.pull`, `sync.push` and `device.identify`.
+2. **Passive remote defaults.**
+   Remote `Sniff` starts passive WARHOG wardriving. Active radio actions are never silently triggered by W33Z.
+3. **Capability driven.**
+   W33Z only unlocks features the firmware explicitly advertises.
+4. **Transport independent.**
+   Wi-Fi, USB and BLE converge on Stella protocol v1.
+5. **Backward compatible during migration.**
+   Legacy config paths and internal Porkchop symbols remain temporarily where renaming them would break existing installations. New code must use the Stella layer.
+6. **No fake telemetry.**
+   Missing GPS, battery, display frames, captures or sync state stay missing/unknown.
+
+## Stella protocol v1
+
+Firmware identity is defined in `src/stella/identity.h`.
+
+Current capabilities:
+
+- telemetry
+- gps
+- wifi_scan
+- capture_inventory
+- file_sync
+- display_mirror
+- display_input
+- firmware_update
+- device_logs
+- ble_provisioning
+
+These are capability declarations, not a promise that every transport is implemented yet. W33Z may present a capability as unavailable until the corresponding firmware path is completed.
+
+## Wi-Fi W33Z link
+
+`src/stella/w33z_link.cpp` is the first real transport implementation.
+
+The link is **opt-in**. Copy `stella_link.example.json` to `/stella_link.json` on the Stella SD card and replace `W33Z-IP` with the LAN IP/hostname of the machine exposing W33Z on port 3033.
+
+Example:
+
+```json
+{
+  "enabled": true,
+  "baseUrl": "http://W33Z-IP:3033",
+  "wifiAutoConnect": false,
+  "heartbeatMs": 5000,
+  "commandPollMs": 1500,
+  "reconnectMs": 10000
+}
+```
+
+`wifiAutoConnect=false` is the conservative default because a STA connection can influence Wi-Fi scanning behavior. When false, Stella only talks to W33Z while Wi-Fi is already connected by another firmware flow. When enabled it reuses the existing Wi-Fi credentials from firmware configuration.
+
+The transport currently implements:
+
+- deterministic device identity from ESP32 eFuse MAC
+- W33Z handshake
+- periodic telemetry heartbeat
+- GPS telemetry when a real fix exists
+- radio channel and network-count telemetry
+- command polling
+- command result acknowledgements
+
+## Command mapping
+
+| W33Z protocol | Stella UI | Current firmware behavior |
+| --- | --- | --- |
+| `scan.start` | Sniff | Passive WARHOG wardrive |
+| `scan.pause` | Stay | Return idle, report paused |
+| `scan.stop` | Heel | Return idle |
+| `device.identify` | Bark | Temporary synthesized woof |
+| `sync.pull` | Fetch | Reserved; not wired yet |
+| `sync.push` | Deliver | Reserved; not wired yet |
+| `display.snapshot` | Look | Reserved; not wired yet |
+| `device.reboot` | Roll Over | Disabled until authenticated pairing |
+| `logs.tail` | Track | Reserved; not wired yet |
+| `firmware.prepare` | Groom | Reserved; not wired yet |
+
+## Migration phases
+
+### Phase 1 - core identity and protocol
+
+- Stella firmware identity
+- W33Z Wi-Fi link
+- heartbeat and command loop
+- safe remote wardrive control
+- version/build rebrand
+
+### Phase 2 - personality replacement
+
+- `piglet` engine becomes Stella personality engine
+- pig art replaced with fox Pomeranian art
+- pig-specific copy rewritten into dog behavior
+- oinks replaced with barks/woofs/howls
+- tree-biting/foraging gags replaced with dog equivalents such as sniffing, marking territory and chasing signals
+
+### Phase 3 - device transports
+
+- USB CDC/serial transport
+- BLE provisioning and lightweight control
+- automatic transport discovery in W33Z
+- pairing/authentication and per-device trust
+
+### Phase 4 - remote display and sync
+
+- display snapshot/frame transport
+- remote button/input events
+- bidirectional wardrive/session sync
+- capture inventory
+- logs
+- firmware update staging
+
+### Phase 5 - cleanup
+
+Only after compatibility migration is proven:
+
+- rename legacy internal `Porkchop*` types
+- migrate `/m5porkchop` SD layout to `/m5stella`
+- migrate config magic/path with fallback import
+- rename remaining PIGSYNC/OINK identifiers
+- remove compatibility aliases
+
+This avoids turning the firmware into an unbootable rename bomb while still moving every new feature onto Stella-native architecture.

STELLA_LANGUAGE.md

@@ -0,0 +1,115 @@
+# Stella language guide
+
+This document is the canonical naming source for the Porkchop -> Stella conversion. The goal is **funny on the surface, precise underneath**. Dog jokes must never hide what a wireless function actually does.
+
+## Core rule
+
+Every feature has three names:
+
+1. **Technical identifier** - stable, boring, suitable for protocols and logs.
+2. **Stella label** - short dog-themed UI name.
+3. **Plain description** - tells the operator exactly what the feature does.
+
+Example:
+
+`scan.passive` -> **SNIFF** -> Passive Wi-Fi reconnaissance.
+
+## Canonical operating language
+
+| Technical meaning | Stella label | UI description |
+| --- | --- | --- |
+| Idle | **SIT** | Stella is idle and ready. |
+| Passive Wi-Fi recon | **SNIFF** | Observe nearby Wi-Fi without active disruption. |
+| Wardriving | **PATROL** | GPS-assisted Wi-Fi survey / wardrive. |
+| Active authorized capture mode | **BITE** | Active assessment/capture tooling for an authorized target. |
+| Pause work | **STAY** | Pause current work. |
+| Stop and return idle | **HEEL** | Stop current operation and return to idle. |
+| Pull data to W33Z | **FETCH** | Fetch sessions, captures and logs into W33Z. |
+| Push config to Stella | **DELIVER** | Deliver profiles/configuration from W33Z. |
+| Identify device | **BARK** | Make this Stella identify herself. |
+| Broadcast/beacon feature | **HOWL** | Broadcast a configured wireless beacon/profile. |
+| Device-to-device sync | **PACK LINK** | Stella-to-Stella local synchronization. |
+| Trusted/excluded networks | **FRIENDLY PACK** | Networks excluded from active assessment. |
+| Device/statistics screen | **WARDOG STATS** | Lifetime/session statistics and progression. |
+| BLE tools | **BLUE PAWS** | Bluetooth Low Energy utilities. |
+| Charging / low power | **NAP** | Charging or low-power state. |
+| Warning | **GROWL** | Attention required. |
+| Error | **HOWL!** | Operation failed or device needs attention. |
+
+## Porkchop migration map
+
+The legacy code names are not all renamed immediately because they are deeply coupled to storage paths, config enums and mode switching. User-facing copy should migrate first; internal symbols follow after compatibility shims are proven.
+
+| Legacy Porkchop term | Stella target | Notes |
+| --- | --- | --- |
+| `PORKCHOP` | `STELLA` | Product/device identity. |
+| `Piglet` | `Stella` / `Wardog` | Personality/avatar identity. |
+| `OINK` | `BITE` | Legacy OINK combines capture and active behavior; UI must say what is active. |
+| `DO NO HAM` | `SNIFF` | Passive reconnaissance. |
+| `WARHOG` | `PATROL` | Wardriving / GPS survey. |
+| `PIGSYNC` | `PACK LINK` | Device-to-device synchronization. |
+| `PIGGY BLUES` | `BLUE PAWS` | BLE feature family. |
+| `BACON` | `HOWL` | Beacon/broadcast feature. |
+| `BOAR BROS` | `FRIENDLY PACK` | Exclusion/trusted network list. |
+| `SWINE STATS` | `WARDOG STATS` | Statistics/progression screen. |
+| `OINK OINK` boot copy | `WOOF WOOF` | Boot identity. |
+| pig grunt/oink SFX | bark/woof/howl family | No pig vocalizations remain in final Stella sound bank. |
+
+## Personality / animation direction
+
+Stella is a fox Pomeranian. Personality should feel lively and mischievous without turning technical status into nonsense.
+
+Recommended visual metaphors:
+
+- scanning: nose down, ears moving, sniff particles / signal lines
+- wardriving: walking/patrol animation, little GPS trail
+- network discovered: ears perk up
+- interesting target tagged: paw marker / territory flag
+- location marker: Stella marks the spot; a tree/lamppost gag can be used sparingly
+- sync/fetch: Stella returns carrying a data packet
+- upload/deliver: Stella drops a packet into a terminal/mailbox
+- idle: sitting, tail movement, occasional look-around
+- warning: small growl / raised ears
+- error: confused head tilt or short howl
+- charging: curled-up nap with charging icon
+- GPS acquisition: tracking/sniffing the ground/sky
+- no GPS: confused compass/head tilt
+
+The old pig/tree gag should become a dog-specific equivalent: **Stella marking a tree/lamppost**, not a literal one-for-one animal swap everywhere.
+
+## Audio direction
+
+No final Stella build should contain an intentional pig vocalization.
+
+Audio families:
+
+- **woof** - normal confirmation / device identify
+- **double woof** - boot/personality moment
+- **short bark** - discovery/event attention
+- **growl** - warning
+- **howl** - major error / dramatic event
+- **happy yip** - achievement/level-up
+- **sniff ticks** - subtle scan feedback; should not fire constantly enough to annoy the operator
+
+Frequent operational sounds remain restrained. Stella is a tool first, mascot second.
+
+## W33Z protocol language
+
+Do not put dog jokes into machine endpoints. Keep:
+
+- `scan.start`
+- `scan.pause`
+- `scan.stop`
+- `sync.pull`
+- `sync.push`
+- `device.identify`
+- `display.snapshot`
+- `display.input`
+- `logs.tail`
+- `firmware.prepare`
+
+W33Z can render those as **Sniff / Stay / Heel / Fetch / Deliver / Bark / Look / Paw Control / Track / Groom**.
+
+## Security wording
+
+Active functionality must always be visually distinguishable from passive survey functionality. `SNIFF` and `PATROL` are passive. `BITE` is active and should show an explicit authorized-assessment indicator before transmitting disruptive frames.

platformio.ini

@@ -1,10 +1,11 @@
-; Author: 0ct0
+; M5STELLA - Stella the Wardog
+; Original M5PORKCHOP firmware by 0ct0, evolved under the MIT license.
 
 [env:m5cardputer]
 platform = espressif32@6.12.0
 board = m5stack-stamps3
 framework = arduino
-custom_version = 0.1.8b-PSTH
+custom_version = 0.1.0-stella-alpha
 board_build.mcu = esp32s3
 board_build.f_cpu = 240000000L
 board_build.flash_mode = qio
@@ -14,12 +15,24 @@ board_build.sdkconfig = sdkconfig.defaults
 monitor_speed = 115200
 upload_speed = 460800
 
+; Keep the StampS3 board default USB Serial/JTAG controller (USB mode 1).
+; It is fixed-function hardware, supports bidirectional CDC plus reliable
+; esptool recovery, and is the safest transport for W33Z enrollment.
+; ARDUINO_USB_MODE=1 is supplied by the PlatformIO board manifest.
+
+; Compile the original Porkchop avatar/environment engine.
+; Only the mascot art inside src/piglet/avatar.cpp is Stella-specific.
+build_src_filter =
+    +<*>
+    -<stella/avatar.cpp>
+
 ; Build flags
-build_flags = 
-    -DARDUINO_USB_MODE=1
+build_flags =
     -DARDUINO_USB_CDC_ON_BOOT=1
     -DCORE_DEBUG_LEVEL=1
     -DBOARD_HAS_PSRAM=0
+    -DSTELLA_LOG_ENABLED=0
+    ; Backward-compatible flag while legacy core files are migrated.
     -DPORKCHOP_LOG_ENABLED=0
     -include src/core/logging.h
     -DARDUINO_M5Stack_StampS3
@@ -28,14 +41,13 @@ build_flags =
     -DCONFIG_BT_NIMBLE_MEM_ALLOC_MODE_INTERNAL=1
     ; NimBLE: Reduce log verbosity (0=NONE, 1=ERROR, 2=WARNING, 3=INFO, 4=DEBUG)
     -DCONFIG_BT_NIMBLE_LOG_LEVEL=1
-    ; SPI pins for M5Cardputer SD card
 
     ; Allow multiple definitions to override ieee80211_raw_frame_sanity_check
     -Wl,-zmuldefs
     -Os
 
 ; Libraries - using compatible versions from m5stack repo
-lib_deps = 
+lib_deps =
     m5stack/M5Unified@^0.2.11
     m5stack/M5Cardputer@^1.1.1
     bblanchon/ArduinoJson@^7.4.2
@@ -48,8 +60,9 @@ extra_scripts = pre:scripts/pre_build.py
 [env:m5cardputer-debug]
 extends = env:m5cardputer
 build_type = debug
-build_flags = 
+build_flags =
     ${env:m5cardputer.build_flags}
+    -DSTELLA_LOG_ENABLED=1
     -DPORKCHOP_LOG_ENABLED=1
     -DDEBUG_MODE=1
     -DCORE_DEBUG_LEVEL=4