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

pip install raspiarduninoai

GUI install

pip install "raspiarduninoai[gui]"

Local development install

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:

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. 🔄 Fall back to simulation mode if no hardware found

List Available Ports

raspiarduninoai-gui --list-ports

Simulation Mode (No Hardware)

Force simulation mode for testing without hardware:

raspiarduninoai-gui --mock

Manual Port Specification

Override auto-detection and specify ports manually:

# 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

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:

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

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

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

# 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.

Cockpit GUI

A holographic HUD-style control surface for the rig lives in run_seraphina_gui.py. It reuses the existing state.py / policies.py / core.py modules to parse the gate board's JSON sensor stream and exposes:

• Always-on cockpit gauge cluster (hopper level, valve % open, annunciator lamps for gate, pump, dust and flow, and the current policy decision).
• Manual controls for the gate presets (sent as OPEN <steps> per the firmware contract), the pump relay (PUMP ON / PUMP OFF), and the telescope.
• A Seraphina AGI chat panel that prefers the seraphina Python API and falls back to the installed seraphina CLI when no Python entry point is exposed.

Run

pip install -r requirements.txt
python run_seraphina_gui.py

The script assumes the gate board is on /dev/ttyACM0 and the telescope board on /dev/ttyACM1 at 115200 baud (the values defined at the top of the file - adjust there if your wiring differs). Hardware and Seraphina integrations all degrade gracefully when their backends are missing so the HUD can be launched on a bare workstation for layout work.

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.