tactility_apps/.claude/skills/tactility-app-development/references/build-env.md

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

. /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)

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.