Metadata-Version: 2.4
Name: raspiarduninoai
Version: 0.1.1
Summary: Hopper gate valve + telescope control integration
Author: jmwilson2019
License-Expression: MIT
Project-URL: Homepage, https://github.com/jmwilson2019/raspiarduninoAI
Project-URL: Bug Reports, https://github.com/jmwilson2019/raspiarduninoAI/issues
Project-URL: Source, https://github.com/jmwilson2019/raspiarduninoAI
Keywords: hopper,control,automation,raspberry-pi,arduino
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyserial>=3.5
Provides-Extra: gui
Requires-Dist: PyQt5>=5.15.0; extra == "gui"
Requires-Dist: pyqtgraph>=0.13.0; extra == "gui"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pip-audit>=2.7.0; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"
Dynamic: license-file

# raspiarduninoAI

Hopper gate valve + telescope control integration with holographic GUI.

**Auto-detects and connects to Arduino/MKS Gen 1.4 boards by default!**

## Installation

### Core install

```bash
pip install raspiarduninoai
```

### GUI install

```bash
pip install "raspiarduninoai[gui]"
```

### Local development install

```bash
pip install -e ".[dev,gui]"
```

## Quick Start

### Default Mode (Auto-detect Hardware)

Simply run the GUI - it will automatically detect and connect to Arduino boards:

```bash
raspiarduninoai-gui
```

The system will:
1. 🔍 Auto-detect connected Arduino/MKS Gen 1.4 boards
2. ⚡ Connect to detected boards automatically
3. 📊 Start monitoring sensors in real-time
4. � Open in a disconnected state if no hardware is found (no simulated data)

### List Available Ports

```bash
raspiarduninoai-gui --list-ports
```

### Manual Port Specification

Override auto-detection and specify ports manually:

```bash
# Specify gate port only
raspiarduninoai-gui --gate-port /dev/ttyUSB0

# Specify both ports
raspiarduninoai-gui --gate-port /dev/ttyUSB0 --tele-port /dev/ttyUSB1
```

**For detailed hardware setup instructions, see [HARDWARE_SETUP.md](HARDWARE_SETUP.md)**

## Usage

This library provides a policy-based control system for managing a hopper gate valve based on sensor inputs (ultrasonic distance, dust detection, PIR motion).

### Holographic GUI

Launch the holographic GUI interface for real-time monitoring and control:

```bash
raspiarduninoai-gui
```

**Features:**
- 🌟 Futuristic holographic design with neon cyan/purple theme
- 📊 Real-time sensor monitoring with animated circular gauges
- 🎮 Manual control interface for gate operations
- 🚨 Live alert notifications and system status
- 📝 Real-time system log with color-coded messages
- ⚡ Smooth animations and visual effects

The GUI provides:
- **Sensor Telemetry Panel**: Live gauges showing material level and gate status
- **System Status Panel**: Detailed sensor readings and active alerts
- **Manual Controls Panel**: Buttons to open/close gate and simulate sensor events
- **System Log**: Real-time logging of all system events

### Basic Example

```python
from core import build_default_core
from policies import PolicyConfig, PolicyEngine

# Implement the hardware interface
class MyHardware:
    def send_gate(self, command: str) -> None:
        # Send command to gate controller
        print(f"Gate: {command}")

    def send_tele(self, command: str) -> None:
        # Send command to telescope controller
        print(f"Telescope: {command}")

# Create the control system
hardware = MyHardware()
core = build_default_core(hardware=hardware, logger=print)

# Process sensor data
sensor_payload = {
    "board_id": "GATE_001",
    "timestamp": 12345,
    "sensors": {
        "ultrasonic_mm": 450,  # Material level
        "dust": False,
        "pir_motion": False,
        "gate_open": True
    }
}

decision = core.on_sensor_payload(sensor_payload)
```

### Custom Policy Configuration

```python
from policies import PolicyConfig

# Configure custom thresholds and behaviors
config = PolicyConfig(
    stale_after_s=5.0,              # Consider data stale after 5 seconds
    low_material_distance_mm=500,   # Close gate when material < 500mm
    close_on_dust=True,             # Close gate on dust detection
    close_on_motion=True            # Close gate on PIR motion
)

policy_engine = PolicyEngine(config)
core = HopperCore(hardware=hardware, policy_engine=policy_engine)
```

For more examples, see `example.py`.

## Running Tests

```bash
# Run all tests
pytest test_state.py test_policies.py test_core.py test_gui.py -v

# Run tests without GUI tests (if display not available)
pytest test_state.py test_policies.py test_core.py -v

# Run with coverage
pytest -v --cov=. --cov-report=term-missing
```

## Release Readiness

This repository runs automated checks for each push/PR:
- install/build verification (`pip install .` and `python -m build`)
- dependency vulnerability audit (`pip-audit`)
- automated test suite

Release publishing is automated via GitHub Actions:
- pre-release (`prereleased`) → TestPyPI
- full release (`published`) → PyPI

### One-time PyPI setup

1. Create projects on both indexes:
   - https://test.pypi.org/project/raspiarduninoai/
   - https://pypi.org/project/raspiarduninoai/
2. In each project, configure **Trusted Publishers** for this repository and workflow:
   - Repository: `jmwilson2019/raspiarduninoAI`
   - Workflow file:
     - `.github/workflows/release-testpypi.yml` (TestPyPI)
     - `.github/workflows/release.yml` (PyPI)
3. Create a GitHub pre-release to validate publishing to TestPyPI.
4. After validation, publish a full GitHub release to publish to PyPI.

## Architecture

- **`state.py`**: Manages sensor state and data validation
- **`policies.py`**: Policy engine that evaluates sensor state and makes decisions
- **`core.py`**: Core controller that coordinates state, policy, and hardware interfaces
- **`gui.py`**: Holographic GUI for real-time monitoring and control

## Wiring

### Gate Board (MKS Gen V1.4) Final Pin Assignments

| Component | Pin / Header | Notes |
|---|---|---|
| Gate Motor 1 | X (54 STEP, 55 DIR) | Standard |
| Gate Motor 2 | Y (60 STEP, 61 DIR) | Firmware-commanded to same target as motor 1 |
| Enable (both) | 38 | Active LOW |
| Pump Relay | Heatbed (8) | High-current relay output |
| Valve (PWM) | Hotend (9) | PWM range 0-255 (`0` closed, `255` full-open, intermediate = partial) |
| HC-SR04 Trig | 17 | Digital output |
| HC-SR04 Echo | 16 | Digital input |
| Dust Sensor OUT | 18 | Digital input |
| PIR (HC-SR501) OUT | 19 | Digital input |
| Sensor Power | 5V / GND headers | Shared 5V/GND rail |

### Telescope Board

Telescope board wiring is unchanged from the existing 4-motor telescope setup.

## Wiring Notes

- Tie all sensor grounds to the same board ground reference.
- Confirm the gate enable logic is active LOW before first motion test (`LOW` = drivers enabled, `HIGH` = disabled) to avoid unexpected movement.
- Keep high-current pump relay wiring isolated from low-voltage sensor leads.
- Verify HC-SR04 orientation and stable 5V supply before trusting distance data.

## First Power-On Verification

1. Flash the gate-board firmware.
2. Open serial monitor at `115200`.
3. Confirm startup banner: `GATE_BOARD_READY`.
4. Confirm periodic JSON sensor lines are emitted.
5. Test `STATUS`, `GET_PRESETS`, `OPEN <steps>`, and `CLOSE` commands incrementally.
