pi-pm3/PI_GEN_PM3_BUILD_NOTES.md

# Pi-gen PM3 Client Build Integration - Session Notes

**Date**: 2025-11-26
**For Next Session**: Priority #3 - Add PM3 Client Build to pi-gen

---

## 🔍 Current State Analysis

### Last Build Attempt (Docker Container: pigen_work)

**Build Status**: ❌ **FAILED** at stage 02-Wireless-AP (NOT PM3-related)

**Timeline**:
- ✅ stage 01-proxmark3: **SUCCESS** - PM3 firmware built successfully
- ❌ stage 02-Wireless-AP: **FAILED** - iptables/hostapd configuration errors

**Error Details**:
```
cp: cannot stat '/etc/hostapd/hostapd.conf': No such file or directory
cp: cannot stat 'config/default_hostapd': No such file or directory
iptables: Failed to initialize nft: Protocol not supported
[19:06:04] Build failed
```

**Conclusion**: PM3 firmware build works, but CLIENT with Python bindings is NOT being built yet.

---

## 📁 Current PM3 Build Configuration

### File: `pi-gen/stageDTPM3/01-proxmark3/00-run-chroot.sh`

**Current Script** (9 lines - very basic):
```bash
#!/bin/bash -e

su - dt
git clone https://github.com/RfidResearchGroup/proxmark3
cd proxmark3
echo PLATFORM=PM3GENERIC > Makefile.platform
make clean && make
exit
```

**What it does**:
- ✅ Clones RRG/Iceman proxmark3 repo
- ✅ Builds firmware only (`make` in root = firmware)
- ❌ Does NOT build client
- ❌ Does NOT build Python bindings
- ❌ Does NOT apply qrcode fix
- ❌ Does NOT install client to ~/.pm3/

---

## 🎯 Required Changes for Next Session

### Task 1: Enhance `01-proxmark3/00-run-chroot.sh`

**New script needs to**:

1. **Clone Proxmark3 repo** (already done)
   ```bash
   git clone https://github.com/RfidResearchGroup/proxmark3
   cd proxmark3
   ```

2. **Apply CMakeLists.txt qrcode fix** 🔴 **CRITICAL**
   ```bash
   # Fix experimental Python library
   sed -i '/TARGET_SOURCES.*pm3rrg_rdv4_experimental/,/)/s|${PM3_ROOT}/client/src/ui.c|${PM3_ROOT}/client/src/ui.c\n    ${PM3_ROOT}/client/src/qrcode/qrcode.c|' \
       client/experimental_lib/CMakeLists.txt
   ```

3. **Build client with Python bindings**
   ```bash
   # Build client
   cd client
   mkdir -p build
   cd build
   cmake .. -DBUILD_PYTHON_LIB=ON
   make -j$(nproc)
   ```

4. **Install to ~/.pm3/ directory**
   ```bash
   # Create installation directory
   mkdir -p ~/.pm3/proxmark3/client

   # Copy client executable
   cp proxmark3 ~/.pm3/proxmark3/client/

   # Copy Python bindings
   cp -r experimental_lib/build/*.so ~/.pm3/proxmark3/client/
   cp -r experimental_lib/example_py ~/.pm3/proxmark3/client/pyscripts

   # Copy firmware files
   mkdir -p ~/.pm3/proxmark3/firmware
   cp ../../bootrom/obj/bootrom.elf ~/.pm3/proxmark3/firmware/
   cp ../../armsrc/obj/fullimage.elf ~/.pm3/proxmark3/firmware/
   ```

5. **Set Python path in environment**
   ```bash
   # Add to .bashrc or systemd environment
   echo 'export PYTHONPATH=$HOME/.pm3/proxmark3/client/pyscripts:$PYTHONPATH' >> ~/.bashrc
   ```

---

## 📋 Reference Files

### Key Documentation

1. **CMakeLists.txt Fix Details**
   - File: `UPSTREAM_CONTRIBUTIONS.md`
   - Section: "Proxmark3 Python Bindings - qrcode Symbol Fix"
   - Exact line to add: `${PM3_ROOT}/client/src/qrcode/qrcode.c`
   - Location: `client/experimental_lib/CMakeLists.txt` around line 434

2. **Working PM3 Build Example**
   - Directory: `.pm3-test/proxmark3/`
   - This is a successful build with Python bindings
   - Use as reference for directory structure

3. **Current Backend Integration**
   - File: `app/backend/workers/pm3_worker.py`
   - Uses Python bindings from `pm3` module
   - Expects to find module in:
     - `.pm3-test/proxmark3/client/experimental_lib/`
     - `~/.pm3/proxmark3/client/pyscripts/`
     - `/usr/local/share/proxmark3/client/pyscripts/`

---

## 🚨 Known Issues to Watch For

### Issue 1: Wireless-AP Stage Failure

**Current blocker**: The build fails AFTER PM3 stage at Wireless-AP setup

**Error symptoms**:
- Missing hostapd.conf files
- iptables nft protocol not supported

**Resolution**: May need to fix this stage before testing full PM3 integration, OR use quick build mode to test PM3 only.

### Issue 2: User Context

**Current script uses**: `su - dt` (switches to dt user)

**Question for next session**:
- Should PM3 be installed for `dt` user or `pi` user?
- Current backend runs as `pi` user (systemd service)
- Recommendation: Install to `/opt/proxmark3/` for system-wide access

### Issue 3: Build Dependencies

**May need to install**:
- cmake
- python3-dev
- build-essential
- libreadline-dev
- libusb-1.0-0-dev

**Add to**: `pi-gen/stageDTPM3/00-packages` or stage-specific packages file

---

## 🧪 Testing Strategy for Next Session

### Step 1: Test Script Locally First
```bash
# Don't run full docker build immediately
./build-image.sh test
```

### Step 2: Quick Build Mode
```bash
# Build only stageDTPM3 (faster iteration)
./build-image.sh quick
```

### Step 3: Verify Installation
After build completes, check inside the image:
```bash
# Mount the image and verify
ls -la /home/pi/.pm3/proxmark3/
python3 -c "import sys; sys.path.insert(0, '/home/pi/.pm3/proxmark3/client/pyscripts'); import pm3; print('Success!')"
```

---

## 📦 Expected File Structure After Build

```
/home/pi/.pm3/proxmark3/
├── client/
│   ├── proxmark3              # Client executable
│   ├── pm3rrg_rdv4_experimental.so  # Python bindings library
│   └── pyscripts/
│       ├── pm3.py             # Python module
│       └── __pycache__/
└── firmware/
    ├── bootrom.elf
    └── fullimage.elf
```

---

## ✅ Success Criteria

Next session is successful when:

1. ✅ PM3 client builds with Python bindings enabled
2. ✅ CMakeLists.txt qrcode fix is applied automatically
3. ✅ Python bindings library (`pm3rrg_rdv4_experimental.so`) is created
4. ✅ All files installed to `/home/pi/.pm3/proxmark3/`
5. ✅ Python module can be imported: `import pm3`
6. ✅ Dangerous Pi backend can find and use the bindings
7. ✅ Full image build completes without errors (or at least past PM3 stage)

---

## 🔗 Quick Links for Next Session

**Start with these commands**:
```bash
# 1. Review current PM3 build script
cat pi-gen/stageDTPM3/01-proxmark3/00-run-chroot.sh

# 2. Check CMakeLists.txt fix documentation
cat UPSTREAM_CONTRIBUTIONS.md | grep -A 20 "qrcode"

# 3. Review working example build
ls -la .pm3-test/proxmark3/client/experimental_lib/

# 4. Read this notes file
cat PI_GEN_PM3_BUILD_NOTES.md
```

**Then proceed with**:
1. Edit `pi-gen/stageDTPM3/01-proxmark3/00-run-chroot.sh`
2. Test with `./build-image.sh test`
3. Build with `./build-image.sh quick`
4. Verify installation

---

**Good luck with the build! 🚀**