OpenBuilds BlackBox Python Shared-Core Framework

A decoupled, pure-Python software framework designed to drive an OpenBuilds BlackBox (Grbl 1.1) CNC controller. Raw G-code strings are completely encapsulated behind safe Python object methods. This architecture utilizes a master launcher thread to bypass Windows serial port conflicts, keeping an integrated graphical Emergency Stop fully active while background worker threads run custom recipes.

---

📂 Project Directory Structure

Ensure all files live in the exact same directory on your computer:

• cnc_launcher.py: The only file you execute. It boots the controller, dynamically visualizes all available scripts, runs selected macros on a background thread, and hosts the visual E-Stop.
• blackbox_driver.py: The hardware abstraction layer. Handles standard communication frames, coordinates multi-axis vectors, and translates inputs into hardware steps.
• base_template.py: A clean blueprint file containing the necessary run_recipe(cnc) hook to copy-paste for creating new automation programs.
• example_program.py: A fully working multi-axis deployment template configured to use high-level Python commands.

---

🛠️ Hardware & Environment Setup

1. Connect the BlackBox to your PC with a high-grade USB data cable.
2. Connect the 24V power supply to the BlackBox (USB logic power alone cannot actuate the stepper motor communication rails).
3. Ensure all external CNC software programs (e.g., OpenBuilds CONTROL, CNCjs) are completely closed so the Windows serial port unlocks.
4. Open your terminal environment and install the required packages:

   pip install pyserial pygame

---

🎛️ High-Level Python API Reference

When writing a new script inside the run_recipe(cnc) block, use this primary method blueprint to control your hardware:

cnc.move_simultaneous(x=0, y=0, z=0, speed=None, delay=1.0)

Generates fluid, coordinated motion across any combination of motors simultaneously on a single shared connection pipeline.

• x, y, z: Floating-point numerical millimeter values relative to the tool's immediate position. Positive or negative inputs dictate direction. (Note: A single y input automatically drives both Y1 and Y2 stepper motors perfectly in unison).
• speed: Optional integer parameter representing Feed Rate velocity in mm/min. If left blank, it defaults to the baseline parameter (2000).
• delay: Floating-point number representing time in seconds to wait before advancing to the next step. This allows the mechanical components enough time to reach their calculated destination without blocking the graphical visual interface loop.

---

🏃 Launching Your Operations

To open the master terminal hub and begin executing profiles, run the launcher script from your command prompt:

python cnc_launcher.py

🛑 Emergency Stop Functionality

Because custom scripts are pushed into a standalone background thread, the main loop remains highly responsive. At any point during active motor operations, you can:

1. Click the large red HARDWARE EMERGENCY STOP button inside the window.
2. Press the ESCAPE key on your keyboard.

Both options immediately inject a real-time serial freeze command directly to the BlackBox chip, terminate any active file execution processes, and close down communication ports cleanly.