Skip to main content

Automation Rules (Miner Controller DSL)

The absolute core of the PV-Miner Application is the Miner Controller DSL (Domain Specific Language). In its latest evolution, the DSL has moved away from simple "If-This-Then-That" triggers to a highly robust, Stateful Operating Mode engine.

This engine allows you to build granular automation rules utilizing dynamic power tracking, time-based smoothing, and hardware safety locks (hysteresis) to prevent your ASIC miners from rapidly turning on and off during volatile weather.

Every configuration consists of comprehensive Operating Modes. An Operating Mode is defined by:

  1. Start Condition: When should this mode activate?
  2. Stop Condition: When should this mode deactivate?
  3. Actions: What should the miners do dynamically while this mode is active?
  4. Hardware Locks: Minimum run and idle times to protect your ASICs.

1. Variables (What You Measure)​

Variables represent the data fetched from your PV inverter, smart meter, or Home Assistant setup.

The Magic of "Potential" Surplus

The system includes POTENTIAL_PV_SURPLUS. Unlike standard surplus, this variable calculates what your solar surplus would be if all miners were turned off. This prevents the common problem where turning on a miner consumes the surplus, immediately triggering a rule to turn the miner back off!

  • BATTERY_SOC: The State of Charge of your home battery in percentage (0% to 100%).
  • PV_PRODUCTION: The current solar power generated by your panels (in kW).
  • LOADS_KW: Your current house consumption / base load excluding miners (in kW).
  • MINER_POWER_KW: The total power currently consumed by all active miners (in kW).
  • PV_SURPLUS: The raw excess solar power (in kW). Calculated as: PV_PRODUCTION - LOADS_KW.
  • POTENTIAL_PV_SURPLUS: The true available surplus (in kW). Calculated as: PV_PRODUCTION - (LOADS_KW - MINER_POWER_KW).
  • PV_SURPLUS_RATIO & POTENTIAL_PV_SURPLUS_RATIO: Scales seamlessly regardless of your PV site's max capacity (e.g., 0.15 = 15% of your max installed kWp).

2. Time Aggregations (Smoothing Data)​

Clouds pass by. Spikes in house consumption happen (e.g., turning on a kettle). To prevent your ASICs from rapidly responding to micro-fluctuations, the DSL evaluates variables over a specific timeframe (e.g., MINUTES).

  • LAST (Live): Takes the most recent, real-time value. Perfect for critical metrics like BATTERY_SOC.
  • MEDIAN: Finds the middle value over the timeframe (e.g., Median over 30 minutes). Highly resistant to extreme data outliers like a single 3-minute cloud passing by.
  • MEAN / MIN / MAX / SUM / COUNT: Standard aggregations available via the internal InfluxDB query engine.

3. Conditions & Logical Operators​

Conditions evaluate your variables to determine if an Operating Mode should Start or Stop.

Comparators:

  • EQUAL (=)
  • LESS (<) / LESS_OR_EQUAL (<=)
  • GREATER (>) / GREATER_OR_EQUAL (>=)

Logical Grouping: You can nest multiple conditions into groups to handle complex scenarios.

  • AND: All conditions inside this group must be true.
  • OR: At least one condition inside this group must be true.
  • NOT: Inverts the result of the condition.

4. Dynamic Value Expressions (New Feature)​

Instead of setting static wattage limits (like "Run at 1500W"), the DSL allows you to calculate power targets dynamically in real-time.

  • Constant: A fixed, fallback value (e.g., 1000 Watts).
  • ClusterCapacityPercentage: Targets a percentage of your total possible hardware limit (e.g., 0.5 = 50% cluster capacity).
  • DynamicVariable: Calculates a wattage target directly from a PV metric.
    • Formula: (Variable * Multiplier) + Offset
    • Example: Track POTENTIAL_PV_SURPLUS (which is in kW). Set the multiplier to 950.0 and offset to 0. This automatically converts the kW surplus into Watts, leaving a safe 50W (5%) buffer margin so you don't accidentally draw from the grid!

5. Controller Actions & Cluster Strategies​

When an Operating Mode is active, it continuously executes its Controller Actions.

Available Actions:

  • SET_POWER_TARGET: Dynamically scales the miner(s) power based on your chosen ValueExpression.
  • PAUSE: Completely stops the hashing process, dropping power consumption to an idle state.
  • RESUME: Wakes the miner up and prepares it to receive power targets.

Action Target Type:

  • SINGLE_MINER: Legacy compatibility mode.
  • ALL_MINERS: Broadcasts the action (like PAUSE) to the whole fleet at once.
  • CLUSTER_DYNAMIC: Intelligently routes power targets across your cluster based on a strategy.

Miner Distribution Strategy:

  • SEQUENTIAL: Miners are filled one by one. Miner A will be scaled up to 100% capacity before Miner B receives any surplus power.
  • EQUAL_DISTRIBUTION: Available surplus is divided equally among all available miners.

Step Size (Watts): ASICs often require specific wattage increments to run stably. You can specify a stepSizeWatts (e.g., 250). If your target is 1100W, but the step size is 250W, the system will safely round down and assign 1000W.

6. Hardware Locks (Hysteresis)​

ASIC boards take time to boot up, hash, and shut down safely. Rapidly toggling them damages the hardware. The new OperatingMode system introduces hardware locks:

  • minRunTime: Once a miner starts, it must run for this duration (e.g., 30 Minutes), ignoring temporary weather drops.
  • minIdleTime: Once a miner pauses, it must remain off for this duration (e.g., 5 Minutes) to cool down safely.

Note: The system monitors actual power draw. If a miner gets physically unplugged, the controller detects the "State Drift" and gracefully releases the lock after a 3-minute grace period.

💡 Practical Example: The Default Cluster Setup​

Here is how the default, highly-optimized PV-Miner cluster rules are structured. It uses two modes: a standard Surplus Tracker and an Emergency Battery Protector.

Mode 1: "Mining with PV-Surplus"​

  • Start Condition: POTENTIAL_PV_SURPLUS (30m Median) > 0.15 kW AND BATTERY_SOC (Live) >= 95%
  • Stop Condition: POTENTIAL_PV_SURPLUS (30m Median) < 0.02 kW
  • Hardware Locks: 30 min Run Time, 5 min Idle Time.
  • Actions:
    1. Resume All: Wakes up all available miners.
    2. Set Power Target (Sequential): Tracks POTENTIAL_PV_SURPLUS dynamically. Uses a 950.0 multiplier to convert kW to Watts while leaving a 5% safety margin. Applies the power in safe 250W steps, filling up Miner A before starting Miner B.

Mode 2: "Mining Cluster Full Stop" (Highest Priority)​

  • Start Condition: BATTERY_SOC (Live) < 90%
  • Stop Condition: BATTERY_SOC (Live) >= 92%
  • Hardware Locks: 0 min Run/Idle Time (Immediate execution).
  • Actions:
    1. Pause All: Instantly drops all miners to idle to prevent home battery drain.

⚠️ Legal Disclaimer & Liability​

Disclaimer

The PV-Miner Application and its automation engine are provided "as is". While this tool is designed to automatically scale your mining hardware based on your local PV data safely, you are solely responsible for monitoring your setup. Factors outside of the application's control—such as local network outages, inverter API delays, firmware bugs on the ASICs, or misconfigured automation rules—can lead to unintended behavior (e.g., completely draining your home battery, or importing expensive grid power).

The developers assume no liability for any financial losses, hardware damage, increased electricity bills, or missed mining rewards. By using the automation rules, you agree that you must test your rules thoroughly and actively supervise your hardware to ensure safe operation.