feat: add scripts for desk lifter control and calibration

CHANGELOG.md

@@ -6,8 +6,13 @@
 - FIX: nasty bug #1729 fixed
 - add your changes here!
 
+- Hardware: Changed GPIO pin assignments - UP: GPIO 18, DOWN: GPIO 17 — 2025-11-18
+- Refactor: Centralized GPIO pin constants in `scripts/constants.py` for maintainability — 2025-11-14
 - Docs: Added `docs/bill_of_materials.md` (Bill of Materials) — 2025-11-14
 - Docs: Added official product links to `docs/bill_of_materials.md` — 2025-11-14
 - Docs: Added prices to `docs/bill_of_materials.md` (prices as of 11/6/2025) — 2025-11-14
 - Build: Moved publishing to GitHub Actions trusted publisher workflow and
 	aligned tooling docs — 2025-11-14
+- Fix: Added Raspberry Pi 5 GPIO compatibility using rpi-lgpio library — 2025-11-14
+- Docs: Added `docs/raspberry-pi-setup.md` with Pi 5 setup instructions — 2025-11-14
+- Fix: Updated requirements.txt to use rpi-lgpio instead of RPi.GPIO for Pi 5 compatibility — 2025-11-14

README.md

@@ -18,6 +18,12 @@
 
 A longer description of your project goes here...
 
+## Setup
+
+For Raspberry Pi 5 setup instructions, see [docs/raspberry-pi-setup.md](docs/raspberry-pi-setup.md).
+
+For bill of materials, see [docs/bill_of_materials.md](docs/bill_of_materials.md).
+
 
 <!-- pyscaffold-notes -->
 

docs/raspberry-pi-setup.md

@@ -0,0 +1,110 @@
+# Raspberry Pi 5 GPIO Setup for Desk Lifter Control
+
+This document describes the setup required to run the desk lifter control scripts on a Raspberry Pi 5 running Debian Trixie.
+
+## Hardware Requirements
+
+- Raspberry Pi 5 (with BCM2712 SoC)
+- GPIO pins connected to the desk lifter motor controller:
+  - UP_PIN: GPIO 18 (physical pin 12)
+  - DOWN_PIN: GPIO 17 (physical pin 11)
+- Power supply: 5V USB-C (at least 3A, preferably 5A for high-power peripherals)
+
+## Software Requirements
+
+- Debian Trixie (13.x)
+- Python 3.11 or later
+- Virtual environment (`venv`)
+
+## GPIO Library Compatibility
+
+The standard `RPi.GPIO` library does not support Raspberry Pi 5 due to changes in the BCM2712 SoC. Instead, use `rpi-lgpio`, a drop-in replacement that provides the same API but uses the `lgpio` library for GPIO access.
+
+## Installation Steps
+
+1. **Clone the repository** (if not already done):
+   ```bash
+   git clone https://github.com/AccelerationConsortium/progressive-automations-python.git
+   cd progressive-automations-python
+   ```
+
+2. **Create and activate a virtual environment**:
+   ```bash
+   python3 -m venv venv
+   source venv/bin/activate
+   ```
+
+3. **Install dependencies**:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+4. **Remove incompatible RPi.GPIO package** (if installed):
+   ```bash
+   sudo apt remove -y python3-rpi.gpio
+   ```
+
+5. **Ensure user is in the gpio group** (for GPIO access without sudo):
+   ```bash
+   sudo usermod -a -G gpio $USER
+   ```
+   Reboot after adding the user to the group.
+
+## Running the Scripts
+
+Activate the virtual environment and run the scripts from the `scripts/` directory:
+
+```bash
+source venv/bin/activate
+cd scripts
+python move_to_height_no_reset.py
+```
+
+Available scripts:
+- `move_to_height_no_reset.py`: Move the desk to a target height
+- `move_to_height.py`: Alternative height control script
+- `desk_control_prefect.py`: Prefect-based workflow orchestration
+- `test_up.py`: Test upward movement
+- `test_down.py`: Test downward movement
+- `reset_to_lowest.py`: Reset to lowest position
+
+## Calibration
+
+The scripts use calibration data:
+- Lowest height: 23.7 inches
+- Highest height: 54.5 inches
+- Up rate: 0.54 inches/second
+- Down rate: 0.55 inches/second
+
+Adjust these values in the script if your setup differs.
+
+State is saved in `lifter_state.json` in the scripts directory.
+
+## Troubleshooting
+
+### RuntimeError: Cannot determine SOC peripheral base address
+
+This error occurs when using the old `RPi.GPIO` library on Raspberry Pi 5. Ensure you have installed `rpi-lgpio` and removed `python3-rpi.gpio`.
+
+### Permission denied on GPIO access
+
+- Ensure your user is in the `gpio` group: `groups $USER` should include `gpio`.
+- If not, run `sudo usermod -a -G gpio $USER` and reboot.
+
+### Script runs but motor doesn't move
+
+- Check GPIO pin connections.
+- Verify the motor controller is powered and connected correctly.
+- Test with `test_up.py` and `test_down.py` to isolate issues.
+
+### Virtual environment issues
+
+- Always activate the venv before running scripts: `source venv/bin/activate`
+- If pip installs fail with "externally-managed-environment", you're trying to install system-wide. Use the venv.
+
+## Notes
+
+- The scripts use BCM pin numbering.
+- GPIO access requires root permissions or membership in the `gpio` group.
+- On Raspberry Pi 5, USB peripherals may be limited to 600mA if using a 3A power supply. Use a 5A supply for high-power devices.
+- This setup is tested on Debian Trixie with Raspberry Pi 5.

requirements.txt

@@ -0,0 +1,3 @@
+# Core dependencies for desk lifter control
+prefect>=2.0.0
+rpi-lgpio

scripts/README.md

@@ -0,0 +1,93 @@
+# Desk Control Scripts
+
+This directory contains scripts for controlling a Progressive Automations desk lifter.
+
+## 🚀 Quick Start
+
+**For the modern modular system:**
+```bash
+# Navigate to the modular package
+cd desk_control/
+
+# Run interactive CLI
+python main.py
+
+# Run test sequence  
+python main.py test
+
+# Check duty cycle status
+python main.py status
+
+# Deploy Prefect automation
+python main.py deploy
+```
+
+## 📁 Directory Structure
+
+```
+scripts/
+├── desk_control/              # 🆕 Modern modular system
+│   ├── main.py               # Main CLI interface
+│   ├── desk_controller.py    # High-level control logic
+│   ├── movement_control.py   # GPIO operations
+│   ├── duty_cycle.py         # Motor protection
+│   ├── prefect_flows.py      # Automation & scheduling
+│   └── README.md             # Detailed documentation
+├── constants.py              # Shared constants (pins, calibration)
+├── lifter_state.json         # Persistent state file
+├── lifter_calibration.txt    # Calibration data
+└── desk_control_prefect_LEGACY.py  # 📦 Original monolithic file (backup)
+```
+
+## ✨ What's New
+
+### **Modular Architecture**
+The code has been refactored into focused, maintainable modules:
+
+- **`movement_control.py`** - GPIO pin control and movement execution
+- **`duty_cycle.py`** - 10% duty cycle protection with sliding window
+- **`desk_controller.py`** - Height management and safety checks
+- **`prefect_flows.py`** - Workflow automation and scheduling
+- **`main.py`** - Unified command-line interface
+
+### **Improved Duty Cycle**
+- ✅ True sliding window (not hard resets every 20 minutes)
+- ✅ Precise timestamp tracking of usage periods
+- ✅ Automatic cleanup of old periods
+- ✅ Real-time duty cycle status monitoring
+
+### **Better Safety**
+- ✅ Comprehensive error handling
+- ✅ GPIO cleanup in all scenarios
+- ✅ Continuous runtime limits (30s max per movement)
+- ✅ Height range validation
+
+## 📖 Usage Examples
+
+```bash
+# Basic movement
+python desk_control/main.py move 25.0 30.0    # Move from 25" to 30"
+
+# Test sequence with custom parameters  
+python desk_control/main.py test 1.0 5.0      # 1" movement, 5s rest
+
+# Duty cycle monitoring
+python desk_control/main.py status
+
+# Prefect automation
+python desk_control/main.py deploy "0 12 * * *"  # Deploy for noon daily
+```
+
+## 🔧 Configuration
+
+Edit `constants.py` to adjust:
+- GPIO pin assignments
+- Calibration values (height range, movement rates)
+
+## 📚 Documentation
+
+See `desk_control/README.md` for detailed documentation of the modular system.
+
+## 🏛️ Legacy Code
+
+The original monolithic file is preserved as `desk_control_prefect_LEGACY.py` for reference, but the modular system in `desk_control/` should be used for all new development.

scripts/constants.py

@@ -0,0 +1,10 @@
+# GPIO pin constants for desk lifter control
+# BCM numbering
+UP_PIN = 18   # BCM numbering, physical pin 12  
+DOWN_PIN = 17 # BCM numbering, physical pin 11
+
+# Calibration data
+LOWEST_HEIGHT = 23.7  # inches
+HIGHEST_HEIGHT = 54.5  # inches
+UP_RATE = 0.54  # inches per second
+DOWN_RATE = 0.55  # inches per second