docs: update README with prerequisites and ESP-IDF setup instructions

README.md

@@ -2,53 +2,117 @@
 
 Kern is an experimental project that explores the capabilities of the ESP32-P4 as a platform to perform air-gapped Bitcoin signatures and cryptography. 
 
-## Build
+DIY Hardware & Programming Notes: For information about suitable DIY hardware, suggested configuration profiles, and notes on secure boot, see the DIY Guide.
 
-### Cloning the Repository
+## Prerequisites (Linux)
 
-This project uses git submodules. You have two options:
+### Build dependencies
 
-#### Option 1: Clone with submodules (Recommended)
+CMake and Ninja are required to build the firmware.
 
-When cloning the project for the first time, make sure to clone it recursively to include all submodules:
+#### Debian / Ubuntu / Mint / Kubuntu
 
 ```bash
-git clone --recursive https://github.com/yourusername/yourrepository.git
+sudo apt update
+sudo apt install -y cmake ninja-build git python3 python3-venv
 ```
 
-#### Option 2: Initialize submodules after cloning
+### Python requirement
 
-If you've already cloned the repository without the `--recursive` flag, you can initialize and update the submodules with:
+A recent Python version is required (recommended: Python >= 3.11). Older system versions may cause dependency installation failures.
+
+Check your version:
 
 ```bash
-git submodule update --init --recursive
+python3 --version
 ```
 
-### Building the Project
+## ESP32-P4 — ESP-IDF 5.5 Setup (Linux)
+
+Crux requires the ESP-IDF SDK v5.5, which provides official support for ESP32-P4. For detailed SDK documentation, see the Espressif official guide: https://docs.espressif.com/projects/esp-idf/en/v5.5/esp32p4/
 
-Follow these instructions to install esp-idf https://docs.espressif.com/projects/esp-idf/en/v5.5/esp32p4/get-started/index.html
+### Install ESP-IDF v5.5 (isolated setup)
 
-After that you can build the project from the root directory with:
+To avoid conflicts with other ESP-IDF versions (e.g. v5.4), the tools and Python environment must be isolated.
+
+#### Get the ESP-IDF SDK
 
 ```bash
-idf.py build
+mkdir -p ~/esp
+cd ~/esp
+git clone -b v5.5 --recursive https://github.com/espressif/esp-idf.git esp-idf-5.5
 ```
 
-or flash the project to the device with:
+#### Isolate ESP-IDF tools (IMPORTANT)
+
+Before installing, define a dedicated tools directory for ESP-IDF 5.5:
 
 ```bash
-idf.py flash
+export IDF_TOOLS_PATH="$HOME/.espressif-idf55"
+```
+
+This prevents reuse of Python environments created for other ESP-IDF versions.
+
+#### Install required tools for ESP32-P4
+
+```bash
+cd ~/esp/esp-idf-5.5
+./install.sh esp32p4
+```
+
+This step installs:
+
+- ESP32-P4 toolchain
+- Python virtual environment
+- ESP-IDF v5.5 dependency constraints
+
+#### Activate the ESP-IDF environment
+
+```bash
+. ~/esp/esp-idf-5.5/export.sh
+```
+
+Verify installation:
+
+```bash
+idf.py --version
+```
+
+## Repository setup
+
+This project uses git submodules. The example below uses the `~/esp` workspace created during the ESP-IDF setup.
+
+### Clone with submodules (recommended)
+
+```bash
+cd ~/esp
+git clone --recursive https://github.com/odudex/Crux.git
+cd Crux
 ```
 
-and if you are debuggning things you may want to run monitor too:
+### Initialize submodules after cloning
+
+If you've already cloned the repository without the `--recursive` flag, initialize and update the submodules with:
 
 ```bash
+git submodule update --init --recursive
+```
+
+## Build, flash, monitor
+
+With the ESP-IDF 5.5 environment activated and from the project root:
+
+```bash
+idf.py build
+idf.py flash
 idf.py monitor
 ```
 
-### Build Options
+Exit monitor with `Ctrl + ]`.
+
+## Build options
 
-#### Enable/disable Auto-focus
+### Enable/disable Auto-focus
 
 To enable camera auto-focus, enable camera focus motor on menuconfig: