Skip to content

Commit 7dc674f

Browse files
sgbairdsgbaird
authored
Merge pull request #3 from AccelerationConsortium/movements
feat: add scripts for desk lifter control and calibration
2 parents e70b877 + 30f0163 commit 7dc674f

17 files changed

Lines changed: 2222 additions & 33 deletions

‎CHANGELOG.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,13 @@
66
- FIX: nasty bug #1729 fixed
77
- add your changes here!
88

9+
- Hardware: Changed GPIO pin assignments - UP: GPIO 18, DOWN: GPIO 17 — 2025-11-18
10+
- Refactor: Centralized GPIO pin constants in `scripts/constants.py` for maintainability — 2025-11-14
911
- Docs: Added `docs/bill_of_materials.md` (Bill of Materials) — 2025-11-14
1012
- Docs: Added official product links to `docs/bill_of_materials.md` — 2025-11-14
1113
- Docs: Added prices to `docs/bill_of_materials.md` (prices as of 11/6/2025) — 2025-11-14
1214
- Build: Moved publishing to GitHub Actions trusted publisher workflow and
1315
aligned tooling docs — 2025-11-14
16+
- Fix: Added Raspberry Pi 5 GPIO compatibility using rpi-lgpio library — 2025-11-14
17+
- Docs: Added `docs/raspberry-pi-setup.md` with Pi 5 setup instructions — 2025-11-14
18+
- Fix: Updated requirements.txt to use rpi-lgpio instead of RPi.GPIO for Pi 5 compatibility — 2025-11-14

‎README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,12 @@
1818
1919
A longer description of your project goes here...
2020

21+
## Setup
22+
23+
For Raspberry Pi 5 setup instructions, see [docs/raspberry-pi-setup.md](docs/raspberry-pi-setup.md).
24+
25+
For bill of materials, see [docs/bill_of_materials.md](docs/bill_of_materials.md).
26+
2127

2228
<!-- pyscaffold-notes -->
2329

‎docs/raspberry-pi-setup.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# Raspberry Pi 5 GPIO Setup for Desk Lifter Control
2+
3+
This document describes the setup required to run the desk lifter control scripts on a Raspberry Pi 5 running Debian Trixie.
4+
5+
## Hardware Requirements
6+
7+
- Raspberry Pi 5 (with BCM2712 SoC)
8+
- GPIO pins connected to the desk lifter motor controller:
9+
- UP_PIN: GPIO 18 (physical pin 12)
10+
- DOWN_PIN: GPIO 17 (physical pin 11)
11+
- Power supply: 5V USB-C (at least 3A, preferably 5A for high-power peripherals)
12+
13+
## Software Requirements
14+
15+
- Debian Trixie (13.x)
16+
- Python 3.11 or later
17+
- Virtual environment (`venv`)
18+
19+
## GPIO Library Compatibility
20+
21+
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.
22+
23+
## Installation Steps
24+
25+
1. **Clone the repository** (if not already done):
26+
```bash
27+
git clone https://github.com/AccelerationConsortium/progressive-automations-python.git
28+
cd progressive-automations-python
29+
```
30+
31+
2. **Create and activate a virtual environment**:
32+
```bash
33+
python3 -m venv venv
34+
source venv/bin/activate
35+
```
36+
37+
3. **Install dependencies**:
38+
```bash
39+
pip install -r requirements.txt
40+
```
41+
42+
4. **Remove incompatible RPi.GPIO package** (if installed):
43+
```bash
44+
sudo apt remove -y python3-rpi.gpio
45+
```
46+
47+
5. **Ensure user is in the gpio group** (for GPIO access without sudo):
48+
```bash
49+
sudo usermod -a -G gpio $USER
50+
```
51+
Reboot after adding the user to the group.
52+
53+
## Running the Scripts
54+
55+
Activate the virtual environment and run the scripts from the `scripts/` directory:
56+
57+
```bash
58+
source venv/bin/activate
59+
cd scripts
60+
python move_to_height_no_reset.py
61+
```
62+
63+
Available scripts:
64+
- `move_to_height_no_reset.py`: Move the desk to a target height
65+
- `move_to_height.py`: Alternative height control script
66+
- `desk_control_prefect.py`: Prefect-based workflow orchestration
67+
- `test_up.py`: Test upward movement
68+
- `test_down.py`: Test downward movement
69+
- `reset_to_lowest.py`: Reset to lowest position
70+
71+
## Calibration
72+
73+
The scripts use calibration data:
74+
- Lowest height: 23.7 inches
75+
- Highest height: 54.5 inches
76+
- Up rate: 0.54 inches/second
77+
- Down rate: 0.55 inches/second
78+
79+
Adjust these values in the script if your setup differs.
80+
81+
State is saved in `lifter_state.json` in the scripts directory.
82+
83+
## Troubleshooting
84+
85+
### RuntimeError: Cannot determine SOC peripheral base address
86+
87+
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`.
88+
89+
### Permission denied on GPIO access
90+
91+
- Ensure your user is in the `gpio` group: `groups $USER` should include `gpio`.
92+
- If not, run `sudo usermod -a -G gpio $USER` and reboot.
93+
94+
### Script runs but motor doesn't move
95+
96+
- Check GPIO pin connections.
97+
- Verify the motor controller is powered and connected correctly.
98+
- Test with `test_up.py` and `test_down.py` to isolate issues.
99+
100+
### Virtual environment issues
101+
102+
- Always activate the venv before running scripts: `source venv/bin/activate`
103+
- If pip installs fail with "externally-managed-environment", you're trying to install system-wide. Use the venv.
104+
105+
## Notes
106+
107+
- The scripts use BCM pin numbering.
108+
- GPIO access requires root permissions or membership in the `gpio` group.
109+
- 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.
110+
- This setup is tested on Debian Trixie with Raspberry Pi 5.

‎requirements.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Core dependencies for desk lifter control
2+
prefect>=2.0.0
3+
rpi-lgpio

‎scripts/README.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Desk Control Scripts
2+
3+
This directory contains scripts for controlling a Progressive Automations desk lifter.
4+
5+
## 🚀 Quick Start
6+
7+
**For the modern modular system:**
8+
```bash
9+
# Navigate to the modular package
10+
cd desk_control/
11+
12+
# Run interactive CLI
13+
python main.py
14+
15+
# Run test sequence
16+
python main.py test
17+
18+
# Check duty cycle status
19+
python main.py status
20+
21+
# Deploy Prefect automation
22+
python main.py deploy
23+
```
24+
25+
## 📁 Directory Structure
26+
27+
```
28+
scripts/
29+
├── desk_control/ # 🆕 Modern modular system
30+
│ ├── main.py # Main CLI interface
31+
│ ├── desk_controller.py # High-level control logic
32+
│ ├── movement_control.py # GPIO operations
33+
│ ├── duty_cycle.py # Motor protection
34+
│ ├── prefect_flows.py # Automation & scheduling
35+
│ └── README.md # Detailed documentation
36+
├── constants.py # Shared constants (pins, calibration)
37+
├── lifter_state.json # Persistent state file
38+
├── lifter_calibration.txt # Calibration data
39+
└── desk_control_prefect_LEGACY.py # 📦 Original monolithic file (backup)
40+
```
41+
42+
## ✨ What's New
43+
44+
### **Modular Architecture**
45+
The code has been refactored into focused, maintainable modules:
46+
47+
- **`movement_control.py`** - GPIO pin control and movement execution
48+
- **`duty_cycle.py`** - 10% duty cycle protection with sliding window
49+
- **`desk_controller.py`** - Height management and safety checks
50+
- **`prefect_flows.py`** - Workflow automation and scheduling
51+
- **`main.py`** - Unified command-line interface
52+
53+
### **Improved Duty Cycle**
54+
- ✅ True sliding window (not hard resets every 20 minutes)
55+
- ✅ Precise timestamp tracking of usage periods
56+
- ✅ Automatic cleanup of old periods
57+
- ✅ Real-time duty cycle status monitoring
58+
59+
### **Better Safety**
60+
- ✅ Comprehensive error handling
61+
- ✅ GPIO cleanup in all scenarios
62+
- ✅ Continuous runtime limits (30s max per movement)
63+
- ✅ Height range validation
64+
65+
## 📖 Usage Examples
66+
67+
```bash
68+
# Basic movement
69+
python desk_control/main.py move 25.0 30.0 # Move from 25" to 30"
70+
71+
# Test sequence with custom parameters
72+
python desk_control/main.py test 1.0 5.0 # 1" movement, 5s rest
73+
74+
# Duty cycle monitoring
75+
python desk_control/main.py status
76+
77+
# Prefect automation
78+
python desk_control/main.py deploy "0 12 * * *" # Deploy for noon daily
79+
```
80+
81+
## 🔧 Configuration
82+
83+
Edit `constants.py` to adjust:
84+
- GPIO pin assignments
85+
- Calibration values (height range, movement rates)
86+
87+
## 📚 Documentation
88+
89+
See `desk_control/README.md` for detailed documentation of the modular system.
90+
91+
## 🏛️ Legacy Code
92+
93+
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‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# GPIO pin constants for desk lifter control
2+
# BCM numbering
3+
UP_PIN = 18 # BCM numbering, physical pin 12
4+
DOWN_PIN = 17 # BCM numbering, physical pin 11
5+
6+
# Calibration data
7+
LOWEST_HEIGHT = 23.7 # inches
8+
HIGHEST_HEIGHT = 54.5 # inches
9+
UP_RATE = 0.54 # inches per second
10+
DOWN_RATE = 0.55 # inches per second

0 commit comments

Comments
 (0)