# Build Env — Transcript & Fix

## Error 1: Hermes venv pollution — TypeError on `X | Y`

```
File .../hermes-agent/venv/lib/python3.11/site-packages/requests/__init__.py
  import urllib3
File .../urllib3/_base_connection.py
  bytes, typing.IO[typing.Any], typing.Iterable[bytes | str], str
TypeError: unsupported operand type(s) for |: 'type' and 'type'
```
IDF Python is 3.9.6 (no `X | Y` unions). Hermes venv injects `PYTHONPATH` with Python 3.11's `urllib3` that uses 3.10+ syntax. Affects `tactility.py` which imports `requests`.

### Fix
```bash
. /Users/adolforeyna/esp/esp-idf/export.sh
export TACTILITY_SDK_PATH=/Users/adolforeyna/Projects/Tactility/firmware/release/TactilitySDK
export PYTHONPATH=""  # critical
/Users/adolforeyna/.espressif/python_env/idf5.3_py3.9_env/bin/python tactility.py Apps/BibleVerse build esp32s3 --local-sdk
```

## Error 2: pydantic_core shadowing — idf.py itself crashes

```
Cannot import module "pydantic_core._pydantic_core".
Please use idf.py only in an ESP-IDF shell environment.
ModuleNotFoundError: No module named 'pydantic_core._pydantic_core'
```
Hermes venv 3.11's `pydantic_core` has `_pydantic_core.cpython-311-darwin.so` built for 3.11. IDF venv 3.9/3.10 has `.cpython-39/310.so`. Because `PYTHONPATH` includes Hermes site-packages, Python tries to load 3.11 `.so` under 3.9/3.10 → fails.

Same error manifests as:
```
'/.../idf5.3_py3.9_env/bin/python' is currently active ... project was configured with '/.../idf5.3_py3.10_env/bin/python'. Run 'idf.py fullclean'
```
Solution: clear env, set IDF_PYTHON_ENV_PATH, fullclean.

### Full Fix (this session — ES3C28P firmware build)

```bash
cd /Users/adolforeyna/Projects/Tactility/firmware
unset PYTHONPATH; unset PYTHONHOME
export IDF_PYTHON_ENV_PATH=/Users/adolforeyna/.espressif/python_env/idf5.3_py3.9_env
. /Users/adolforeyna/esp/esp-idf/export.sh

# Verify fix:
$IDF_PYTHON_ENV_PATH/bin/python -c "import pydantic_core; print('ok')"
idf.py --version  # ESP-IDF v5.3.2-dirty

python device.py es3c28p                          # regenerates sdkconfig
idf.py fullclean                                 # when switching python version
idf.py build                                     # -> build/Tactility.bin
idf.py -p /dev/cu.usbmodem101 flash              # flash family board
```

Build output for ES3C28P (16MB, 80MHz, partitions-16mb-with-sd.csv):
```
Wrote 2863136 bytes (1653045 compressed) at 0x00010000 in 19.9s (1149.4 kbit/s)
bootloader 0x0, partition-table 0x8000, Tactility.bin 0x10000, system.bin 0x410000
```

## Error 3: IDF_PATH unset in subshell
`zsh -c 'python3 tactility.py...'` loses `IDF_PATH`. Always source inside same shell or use wrapper script.

## Error 4: format-truncation as error
IDF adds `-Werror=all`. `snprintf(dst, 320, "%s/bible", assets_path)` flagged even though 320B is generous.
Fix: `target_compile_options(${COMPONENT_LIB} PRIVATE -Wno-format-truncation -Wno-unused-but-set-variable)`

## Correct build commands

Firmware core:
```
cd /Users/adolforeyna/Projects/Tactility/firmware
unset PYTHONPATH; unset PYTHONHOME
export IDF_PYTHON_ENV_PATH=/Users/adolforeyna/.espressif/python_env/idf5.3_py3.9_env
. /Users/adolforeyna/esp/esp-idf/export.sh
python device.py es3c28p
idf.py build
idf.py -p /dev/cu.usbmodem101 flash
```

ELF app (BibleVerse):
```
cd /Users/adolforeyna/Projects/Tactility/apps
. ~/esp/esp-idf/export.sh > /dev/null
env -u PYTHONPATH /Users/adolforeyna/.espressif/python_env/idf5.3_py3.9_env/bin/python tactility.py Apps/BibleVerse build esp32s3 --local-sdk
# => build/BibleVerse.app 4.2MB, ESP32S3 ELF 17K
```

## Related Files
- `/Users/adolforeyna/Projects/Tactility/board_compilation_learnings.md` — full v5.3.2 compatibility fixes (I2C backport, missing cstring, etc.)
- This session also fixed wrong board: `waveshare-esp32-s3-rlcd` flashed onto color `es3c28p`. Always `grep CONFIG_TT_DEVICE_ID sdkconfig`.