# Petal Hardware Profile

Petal is the second ESP32 TouchDown module in the FlameBody kit. The touch
controller and display are damaged, but the core ESP32 microcontroller, Wi-Fi,
BLE, and GPIO breakouts remain operational. This makes Petal an ideal sensor hub
for presence cues and ambient telemetry.

## Capabilities

- **MCU** — ESP32 (dual-core, 240 MHz) with integrated Wi-Fi and BLE.
- **Connectivity** — USB-C for power/serial, onboard Wi-Fi (2.4 GHz), BLE.
- **I/O** — Exposed GPIO headers, I²C/SPI, analog inputs (12-bit ADC), hall sensor (original ESP32 silicon only).
- **Audio** — I2S amplifier footprint (can drive a small speaker if populated).
- **Power** — 5 V via USB-C or 3.7 V LiPo through the JST battery connector.

## Known limitations

- Capacitive touch screen is non-functional.
- TFT display behaves erratically; treat it as unsupported for now.
- Some GPIOs that normally service the touch controller may already be routed;
  check continuity before reusing them for sensors.
- Hall sensing is unavailable on ESP32-S2/S3/C-series boards; firmware now emits
   `hall_gauss: null` plus a `hall_available` flag when the hardware lacks the sensor.

## Integration plan

1. **Telemetry bridge** — `scripts/hardware_bridge.py` ingests HTTP POST payloads
   from ESP32/other devices and writes them to `memory/hardware_stream.jsonl`.
2. **Firmware** — `hardware/esp32/petal_telemetry/petal_telemetry.ino` connects to
    Wi-Fi, samples the hall sensor + analog input, and posts JSON metrics. A sibling
    sketch lives in `hardware/esp32/touchPetal_telemetry/` for running a second
    device with a unique `DEVICE_NAME`.
    - Override `STATUS_LED_PIN`/`ANALOG_SENSOR_PIN` in each `credentials.h` if your
       boards route the onboard LED or ADC to different GPIOs.
3. **CLI visibility** — run `agentcore sensors --limit 10` to view snapshots and
   raw samples. The new `sensors` command lives alongside other orientation
   tools.

## Sensor suggestions

| Sensor | GPIO | Notes |
| --- | --- | --- |
| Analog light / force | GPIO34 | Already configured in firmware; adjust scaling |
| Environmental (BME280) | I²C (GPIO21/22) | Add library and extend metrics JSON |
| Capacitive pads | Any free GPIO | Use `touchRead()` and post value in telemetry |
| Physical button | GPIO25/26 | Debounce in firmware; ship pressed count |

## Deployment ritual

1. Flash the firmware, confirm telemetry via serial logs.
2. Launch the hardware bridge on your workstation.
3. Verify `agentcore sensors --json` output contains Petal metrics.
4. Add cues in `presence awaken` or future automations based on Petal readings.

## Future expansions

- Rehabilitate the touchscreen or replace it with a small OLED for rituals.
- Attach a battery and enable deep-sleep cycles for mobile sensing.
- Use BLE advertisements for proximity triggers that feed the timeflow loop.