/*
 * Solar Night Light Controller
 * Target: Arduino UNO R3 (ATmega328P)
 * Purpose: Controls a 12V LED via MOSFET based on LDR light levels,
 *          incorporating Low Voltage Disconnect (LVD) for battery protection.
 */

// --- Hardware Pins ---
const int PIN_BATTERY_SENSE = A0;
const int PIN_LIGHT_SENSE   = A1;
const int PIN_LED_DRIVE     = 9;

// --- Calibration & Thresholds ---
// Voltage Divider: R1 = 30k, R2 = 10k. Ratio = (30+10)/10 = 4.0
const float VOLTAGE_DIVIDER_RATIO = 4.0;
const float ADC_REFERENCE_VOLTAGE = 5.0;
const float ADC_MAX_VALUE = 1023.0;

// Battery Thresholds (12V Lead-Acid / 3S Li-ion example)
const float BATT_LVD_DISCONNECT = 10.5; // Turn off below 10.5V
const float BATT_LVD_RECONNECT  = 11.5; // Require 11.5V to turn back on

// Light Thresholds (0-1023). Higher value = brighter ambient light.
const int LIGHT_THRESHOLD_DARK  = 300;  // Below this is considered night
const int LIGHT_THRESHOLD_LIGHT = 450;  // Above this is considered day

// --- System State ---
enum SystemState {
  STATE_DAYTIME,
  STATE_NIGHT_ON,
  STATE_LOW_BATTERY
};

SystemState currentState = STATE_DAYTIME;

// --- Timing ---
unsigned long lastLogTime = 0;
const unsigned long LOG_INTERVAL_MS = 1000;

void setup() {
  Serial.begin(115200);

  pinMode(PIN_BATTERY_SENSE, INPUT);
  pinMode(PIN_LIGHT_SENSE, INPUT);

  // Initialize MOSFET drive pin
  pinMode(PIN_LED_DRIVE, OUTPUT);
  analogWrite(PIN_LED_DRIVE, 0); // Ensure LED is OFF at boot

  Serial.println("Solar Night Light Controller Initialized.");
  Serial.println("Timestamp_ms,Battery_V,Light_ADC,State,PWM_Out");
}

void loop() {
  // 1. Read Sensors
  int rawBatteryADC = analogRead(PIN_BATTERY_SENSE);
  int rawLightADC = analogRead(PIN_LIGHT_SENSE);

  // 2. Calculate Real Voltage
  float pinVoltage = (rawBatteryADC / ADC_MAX_VALUE) * ADC_REFERENCE_VOLTAGE;
  float batteryVoltage = pinVoltage * VOLTAGE_DIVIDER_RATIO;

  // 3. State Machine Logic
  switch (currentState) {

    case STATE_DAYTIME:
      // Transition to NIGHT if it gets dark AND battery is healthy
      if (rawLightADC < LIGHT_THRESHOLD_DARK) {
        if (batteryVoltage > BATT_LVD_RECONNECT) {
          currentState = STATE_NIGHT_ON;
        } else {
          currentState = STATE_LOW_BATTERY; // Too dark, but battery is dead
        }
      }
      // Transition to LOW_BATTERY if voltage drops even during day
      if (batteryVoltage < BATT_LVD_DISCONNECT) {
        currentState = STATE_LOW_BATTERY;
      }
      break;

    case STATE_NIGHT_ON:
      // Transition back to DAYTIME if light returns
      if (rawLightADC > LIGHT_THRESHOLD_LIGHT) {
        currentState = STATE_DAYTIME;
      }
      // Transition to LOW_BATTERY if voltage drops below safe limit
      if (batteryVoltage < BATT_LVD_DISCONNECT) {
        currentState = STATE_LOW_BATTERY;
      }
      break;

    case STATE_LOW_BATTERY:
      // Only recover from Low Battery if voltage rises above reconnect threshold
      if (batteryVoltage > BATT_LVD_RECONNECT) {
        if (rawLightADC > LIGHT_THRESHOLD_LIGHT) {
          currentState = STATE_DAYTIME;
        } else {
          currentState = STATE_NIGHT_ON;
        }
      }
      break;
  }

  // 4. Actuate Outputs
  int pwmValue = 0;
  if (currentState == STATE_NIGHT_ON) {
    pwmValue = 255; // 100% duty cycle (Full brightness)
  }
  analogWrite(PIN_LED_DRIVE, pwmValue);

  // 5. Telemetry Logging (Non-blocking)
  unsigned long currentMillis = millis();
  if (currentMillis - lastLogTime >= LOG_INTERVAL_MS) {
    lastLogTime = currentMillis;

    Serial.print(currentMillis);
    Serial.print(",");
    Serial.print(batteryVoltage, 2);
    Serial.print(",");
    Serial.print(rawLightADC);
    Serial.print(",");

    if (currentState == STATE_DAYTIME) Serial.print("DAYTIME");
    else if (currentState == STATE_NIGHT_ON) Serial.print("NIGHT_ON");
    else if (currentState == STATE_LOW_BATTERY) Serial.print("LOW_BATT");

    Serial.print(",");
    Serial.println(pwmValue);
  }
}

/*
 * sump_controller.ino
 * Dual-float sump pump controller with hysteresis and high-water alarm.
 * Target: Arduino UNO R3 (ATmega328P)
 */

// --- Pin Definitions ---
const int LOW_FLOAT_PIN = 2;
const int HIGH_FLOAT_PIN = 3;
const int RELAY_PIN = 4;
const int BUZZER_PIN = 5;

// --- Logic Definitions ---
// Using INPUT_PULLUP: Switch closed (floating up) connects to GND (LOW)
const int FLOAT_TRIGGERED = LOW;
const int FLOAT_RESTING = HIGH;

// Standard 5V relay modules are typically Active LOW
const int RELAY_ON = LOW;
const int RELAY_OFF = HIGH;

// --- Alarm Configuration ---
// Time in milliseconds before triggering alarm if High Float stays triggered
const unsigned long ALARM_DELAY_MS = 5000; 

// --- State Variables ---
bool pumpIsActive = false;
bool alarmIsActive = false;
unsigned long highFloatStartTime = 0;

void setup() {
  Serial.begin(9600);
  while (!Serial) { ; } // Wait for serial port to connect

  Serial.println("Initializing Sump Pump Controller...");

  // Configure float switch pins with internal pull-ups
  pinMode(LOW_FLOAT_PIN, INPUT_PULLUP);
  pinMode(HIGH_FLOAT_PIN, INPUT_PULLUP);

  // Configure output pins
  pinMode(RELAY_PIN, OUTPUT);
  pinMode(BUZZER_PIN, OUTPUT);

  // Set initial safe states
  digitalWrite(RELAY_PIN, RELAY_OFF);
  noTone(BUZZER_PIN);

  Serial.println("System Ready.");
  Serial.println("-----------------------------------");
}

void loop() {
  // 1. Read the current state of both float switches
  int lowFloatState = digitalRead(LOW_FLOAT_PIN);
  int highFloatState = digitalRead(HIGH_FLOAT_PIN);

  // 2. Evaluate Hysteresis Logic for the Pump
  if (highFloatState == FLOAT_TRIGGERED) {
    // Water has reached the top float. Turn pump ON.
    if (!pumpIsActive) {
      pumpIsActive = true;
      digitalWrite(RELAY_PIN, RELAY_ON);
      Serial.println("ACTION: High level reached. Pump turned ON.");
    }
  } 
  else if (lowFloatState == FLOAT_RESTING) {
    // Water has dropped below the bottom float. Turn pump OFF.
    if (pumpIsActive) {
      pumpIsActive = false;
      digitalWrite(RELAY_PIN, RELAY_OFF);
      Serial.println("ACTION: Low level cleared. Pump turned OFF.");
    }
  }
  // Note: If water is between the two floats, pumpIsActive retains its previous state.
  // This is the core of hysteresis.

  // 3. Evaluate Alarm Logic (Non-blocking timer)
  if (highFloatState == FLOAT_TRIGGERED) {
    // If this is the first moment we see the high float triggered, record the time
    if (highFloatStartTime == 0) {
      highFloatStartTime = millis();
    }

    // Check if the high float has been triggered longer than the allowed delay
    if ((millis() - highFloatStartTime >= ALARM_DELAY_MS) && !alarmIsActive) {
      alarmIsActive = true;
      tone(BUZZER_PIN, 2000); // 2kHz warning tone
      Serial.println("ALARM: Water level critically high! Pump may be failing.");
    }
  } else {
    // Water is no longer at the high float. Reset alarm states.
    if (highFloatStartTime != 0 || alarmIsActive) {
      highFloatStartTime = 0;
      alarmIsActive = false;
      noTone(BUZZER_PIN);
      Serial.println("STATUS: High water condition cleared. Alarm reset.");
    }
  }

  // Small delay to debounce switch chattering from simulated water ripples
  delay(100); 
}

#!/usr/bin/env python3
"""
Objective: rain-gauge-mqtt-logger
Device: Raspberry Pi 5 + tipping bucket rain gauge + DS3231 RTC + local SQLite log
"""

import os
import time
import json
import sqlite3
import queue
import threading
from datetime import datetime, timezone
import paho.mqtt.client as mqtt

DB_FILE = "rain_log.db"
MQTT_BROKER = "localhost"  # Change to your broker IP if external
MQTT_PORT = 1883
MQTT_TOPIC = "weather/rain_gauge"
MM_PER_TIP = 0.2794  # Calibration metric: mm of rain per bucket tip
RAIN_PIN = 17

# Hardware Abstraction / Mocking
MOCK_MODE = os.environ.get("MOCK_HARDWARE", "0") == "1"

if MOCK_MODE:
    print("[INFO] Running in MOCK mode. Hardware GPIO bypassed.")
    class MockButton:
        def __init__(self, pin, pull_up, bounce_time):
            self.pin = pin
            self.when_pressed = None
            self._running = True
            self._thread = threading.Thread(target=self._simulate_rain, daemon=True)
            self._thread.start()

        def _simulate_rain(self):
            # Simulate a rain tip every 5 seconds
            while self._running:
                time.sleep(5)
                if self.when_pressed:
                    self.when_pressed()

    Button = MockButton
else:
    from gpiozero import Button

# Global Queue for thread-safe interrupt handling
tip_queue = queue.Queue()

def setup_database():
    """Initializes the SQLite database and creates the schema if it doesn't exist."""
    conn = sqlite3.connect(DB_FILE)
    cursor = conn.cursor()
    cursor.execute('''
        CREATE TABLE IF NOT EXISTS rain_events (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            timestamp TEXT NOT NULL,
            daily_tips INTEGER NOT NULL,
            daily_mm REAL NOT NULL
        )
    ''')
    conn.commit()
    return conn

def bucket_tipped():
    """Hardware interrupt callback. Kept extremely short."""
    # Put a timestamp into the queue. The OS time is synced via the DS3231 RTC.
    tip_time = datetime.now(timezone.utc).isoformat()
    tip_queue.put(tip_time)

def publish_mqtt(client, payload):
    """Publishes the JSON payload to the MQTT broker."""
    try:
        client.publish(MQTT_TOPIC, json.dumps(payload), qos=1)
        print(f"[MQTT] Published: {payload}")
    except Exception as e:
        print(f"[MQTT ERROR] Failed to publish: {e}")

def main():
    print("[INFO] Starting Rain Gauge MQTT Logger...")

    # Initialize Database
    db_conn = setup_database()
    db_cursor = db_conn.cursor()

    # Initialize MQTT Client
    mqtt_client = mqtt.Client()
    try:
        mqtt_client.connect(MQTT_BROKER, MQTT_PORT, 60)
        mqtt_client.loop_start()
        print(f"[INFO] Connected to MQTT Broker at {MQTT_BROKER}:{MQTT_PORT}")
    except Exception as e:
        print(f"[WARN] Could not connect to MQTT broker: {e}. Running in local-only mode.")

    # Initialize Hardware Interrupt
    # bounce_time handles the mechanical bouncing of the reed switch
    rain_gauge = Button(RAIN_PIN, pull_up=True, bounce_time=0.1)
    rain_gauge.when_pressed = bucket_tipped

    daily_tips = 0
    current_date = datetime.now(timezone.utc).date()

    print("[INFO] System ready. Waiting for rain events...")

    try:
        while True:
            try:
                # Block until an event occurs (timeout allows clean exit on KeyboardInterrupt)
                tip_time_str = tip_queue.get(timeout=1.0)

                # Check for day rollover to reset daily counters
                event_date = datetime.fromisoformat(tip_time_str).date()
                if event_date > current_date:
                    daily_tips = 0
                    current_date = event_date

                daily_tips += 1
                daily_mm = round(daily_tips * MM_PER_TIP, 4)

                # 1. Save to local SQLite database
                db_cursor.execute(
                    "INSERT INTO rain_events (timestamp, daily_tips, daily_mm) VALUES (?, ?, ?)",
                    (tip_time_str, daily_tips, daily_mm)
                )
                db_conn.commit()
                print(f"[DB] Logged tip {daily_tips} at {tip_time_str} ({daily_mm} mm total)")

                # 2. Publish to MQTT
                payload = {
                    "timestamp": tip_time_str,
                    "event": "bucket_tip",
                    "daily_tips": daily_tips,
                    "daily_mm": daily_mm
                }
                publish_mqtt(mqtt_client, payload)

            except queue.Empty:
                continue

    except KeyboardInterrupt:
        print("\n[INFO] Shutting down logger...")
    finally:
        db_conn.close()
        mqtt_client.loop_stop()
        mqtt_client.disconnect()

if __name__ == "__main__":
    main()

#!/usr/bin/env python3
import time
import csv
import os
import argparse
from datetime import datetime

# Attempt to import hardware libraries
try:
    import smbus2
    import spidev
    import RPi.GPIO as GPIO
    HARDWARE_AVAILABLE = True
except ImportError:
    HARDWARE_AVAILABLE = False

class I2CAdapter:
    """Adapter for I2C communication handling the RTC and NFC modules."""
    def __init__(self, use_mock: bool):
        self.use_mock = use_mock
        self.tap_counter = 0
        self.simulated_uid = "UID-8A-9B-2C"

        if not self.use_mock and HARDWARE_AVAILABLE:
            self.bus = smbus2.SMBus(1)

    def read_rtc_time(self) -> str:
        """Reads time from DS3231 or returns system time in mock mode."""
        if self.use_mock or not HARDWARE_AVAILABLE:
            # Mock mode: Return current system time
            return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
        else:
            # Physical mode: Read registers 0x00 to 0x06 from DS3231 (0x68)
            # For brevity and robustness in this adapter, we fall back to system time 
            # if physical read fails.
            try:
                data = self.bus.read_i2c_block_data(0x68, 0x00, 7)
                # BCD to Decimal conversion omitted; returning system time for safety
                return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
            except Exception:
                return datetime.now().strftime("%Y-%m-%d %H:%M:%S")

    def poll_nfc(self) -> str:
        """Polls the PN532 for a card tap. Simulates taps in mock mode."""
        if self.use_mock or not HARDWARE_AVAILABLE:
            self.tap_counter += 1
            # Simulate a tap every 5 iterations
            if self.tap_counter % 5 == 0:
                return self.simulated_uid
            return ""
        else:
            # Physical mode: Poll PN532 (0x24)
            # In a full physical implementation, we would send the InListPassiveTarget command.
            # Here we return empty to prevent blocking if hardware is misconfigured.
            return ""

class SPIAdapter:
    """Adapter for SPI communication handling the E-Paper Display."""
    def __init__(self, use_mock: bool):
        self.use_mock = use_mock
        if not self.use_mock and HARDWARE_AVAILABLE:
            self.spi = spidev.SpiDev()
            self.spi.open(0, 0)
            self.spi.max_speed_hz = 2000000

    def update_display(self, state: str, user: str = ""):
        """Pushes a new buffer to the e-paper display or prints to console."""
        if self.use_mock or not HARDWARE_AVAILABLE:
            print("\n" + "="*30)
            print("[ E-PAPER DISPLAY ]")
            print(f"STATUS: {state}")
            if user:
                print(f"USER:   {user}")
            print("="*30 + "\n")
        else:
            # Physical mode: Send image buffer over SPI
            # (Requires specific e-paper driver logic depending on the exact screen model)
            pass

class LogbookSystem:
    def __init__(self, use_mock: bool):
        self.i2c = I2CAdapter(use_mock)
        self.spi = SPIAdapter(use_mock)
        self.log_file = "checkout_log.csv"
        self.state = "AVAILABLE"
        self.current_user = ""

        self._initialize_log()

    def _initialize_log(self):
        if not os.path.exists(self.log_file):
            with open(self.log_file, 'w', newline='') as f:
                writer = csv.writer(f)
                writer.writerow(["Timestamp", "Action", "UID"])

    def log_event(self, action: str, uid: str):
        timestamp = self.i2c.read_rtc_time()
        with open(self.log_file, 'a', newline='') as f:
            writer = csv.writer(f)
            writer.writerow([timestamp, action, uid])
        print(f"[{timestamp}] LOGGED: {action} by {uid}")

    def run(self, iterations: int = 15):
        print("Starting NFC Tool Checkout System...")
        self.spi.update_display(self.state)

        for i in range(iterations):
            uid = self.i2c.poll_nfc()
            if uid:
                if self.state == "AVAILABLE":
                    self.state = "CHECKED OUT"
                    self.current_user = uid
                    self.log_event("CHECKOUT", uid)
                    self.spi.update_display(self.state, self.current_user)
                elif self.state == "CHECKED OUT":
                    if self.current_user == uid:
                        self.state = "AVAILABLE"
                        self.current_user = ""
                        self.log_event("RETURN", uid)
                        self.spi.update_display(self.state)
                    else:
                        print(f"WARN: User {uid} attempted to return a tool checked out by {self.current_user}")

            time.sleep(1)

        print("System execution completed.")

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="NFC Tool Checkout Logbook")
    parser.add_argument("--mock", action="store_true", help="Force mock mode without hardware")
    args = parser.parse_args()

    # Auto-enable mock if hardware libraries are missing
    force_mock = args.mock or not HARDWARE_AVAILABLE
    if force_mock:
        print("Running in MOCK mode (Hardware libraries not found or --mock passed).")

    system = LogbookSystem(use_mock=force_mock)
    system.run(iterations=12)

"""
sump_monitor.py
Main application for monitoring sump pump runtime.
Reads analog current data, applies threshold logic, and logs events to CSV.
"""

import argparse
import time
import datetime
import csv
import os
from mcp3008_driver import MCP3008

# Configuration
ADC_CHANNEL = 0
# Threshold out of 1023. Adjust based on your sensor's output when the pump is ON.
# 100 is roughly 0.32V on a 3.3V reference.
ON_THRESHOLD = 100 
LOG_FILE = "sump_pump_log.csv"

def initialize_csv(filepath):
    """Creates the CSV file and writes headers if it doesn't exist."""
    if not os.path.exists(filepath):
        with open(filepath, mode='w', newline='') as file:
            writer = csv.writer(file)
            writer.writerow(["Timestamp_Start", "Timestamp_End", "Duration_Seconds", "Peak_ADC_Value"])
        print(f"[*] Created new log file: {filepath}")

def log_event(filepath, start_time, end_time, peak_val):
    """Appends a completed pump cycle to the CSV log."""
    duration = round(end_time - start_time, 2)
    start_str = datetime.datetime.fromtimestamp(start_time).strftime('%Y-%m-%d %H:%M:%S')
    end_str = datetime.datetime.fromtimestamp(end_time).strftime('%Y-%m-%d %H:%M:%S')

    with open(filepath, mode='a', newline='') as file:
        writer = csv.writer(file)
        writer.writerow([start_str, end_str, duration, peak_val])

    print(f"[LOG] Cycle recorded: {duration} seconds (Peak ADC: {peak_val})")

def simulate_environment(mcp, script_start_time):
    """
    Simulates a pump cycling on and off for dry-run validation.
    Pump turns ON for 5 seconds every 20 seconds.
    """
    elapsed = time.time() - script_start_time
    cycle_time = elapsed % 20
    if 5 <= cycle_time <= 10:
        # Simulate pump running (high current)
        mcp.mock_val = 650 
    else:
        # Simulate pump off (noise floor)
        mcp.mock_val = 15 

def main():
    parser = argparse.ArgumentParser(description="Sump Pump Runtime Monitor")
    parser.add_argument("--mock", action="store_true", help="Run in mock mode without physical hardware")
    args = parser.parse_args()

    print("======================================")
    print("      Sump Pump Runtime Monitor       ")
    print("======================================")

    if args.mock:
        print("[!] Running in MOCK mode. Hardware bypassed.")
    else:
        print("[!] Running in HARDWARE mode.")

    initialize_csv(LOG_FILE)

    # Initialize ADC
    adc = MCP3008(bus=0, device=0, mock=args.mock)

    # State machine variables
    pump_is_running = False
    cycle_start_time = 0
    peak_adc_in_cycle = 0
    script_start_time = time.time()

    print(f"[*] Monitoring started. Press Ctrl+C to exit.")
    print(f"[*] Threshold set to ADC > {ON_THRESHOLD}")

    try:
        while True:
            # Inject simulated data if in mock mode
            if args.mock:
                simulate_environment(adc, script_start_time)

            # Read current sensor
            current_val = adc.read_channel(ADC_CHANNEL)

            # State Machine Logic
            if current_val > ON_THRESHOLD:
                if not pump_is_running:
                    # Transition: OFF -> ON
                    pump_is_running = True
                    cycle_start_time = time.time()
                    peak_adc_in_cycle = current_val
                    print(f"[{datetime.datetime.now().strftime('%H:%M:%S')}] PUMP ON DETECTED (ADC: {current_val})")
                else:
                    # Update peak value during the cycle
                    if current_val > peak_adc_in_cycle:
                        peak_adc_in_cycle = current_val
            else:
                if pump_is_running:
                    # Transition: ON -> OFF
                    pump_is_running = False
                    cycle_end_time = time.time()
                    print(f"[{datetime.datetime.now().strftime('%H:%M:%S')}] PUMP OFF DETECTED")
                    log_event(LOG_FILE, cycle_start_time, cycle_end_time, peak_adc_in_cycle)

            # Sample rate: ~10Hz is sufficient for this application
            time.sleep(0.1)

    except KeyboardInterrupt:
        print("\n[*] Shutting down monitor gracefully...")
    finally:
        adc.close()
        print("[*] Cleanup complete. Exiting.")

if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Water Softener Salt Level Monitor
Target: Raspberry Pi 5 + VL53L0X ToF Sensor + 2.13 inch SPI e-paper display
"""

import argparse
import time
import logging
from datetime import datetime

logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s [%(levelname)s] %(message)s',
    datefmt='%Y-%m-%d %H:%M:%S'
)

# --- Calibration Constants ---
# Distance from the sensor to the salt when the tank is completely full
TANK_FULL_DISTANCE_MM = 150  
# Distance from the sensor to the bottom of the tank (or minimum salt level)
TANK_EMPTY_DISTANCE_MM = 850 

class VL53L0XAdapter:
    """Adapter for the VL53L0X Time-of-Flight sensor."""
    def __init__(self, dry_run=False):
        self.dry_run = dry_run
        self.sensor = None
        self.mock_distance = 200 # Starting mock distance in mm

        if not self.dry_run:
            try:
                import board
                import busio
                import adafruit_vl53l0x
                i2c = busio.I2C(board.SCL, board.SDA)
                self.sensor = adafruit_vl53l0x.VL53L0X(i2c)
                logging.info("Hardware VL53L0X initialized successfully.")
            except ImportError:
                logging.warning("adafruit_vl53l0x not found. Falling back to Mock VL53L0X.")
                self.dry_run = True
            except Exception as e:
                logging.error(f"Failed to initialize hardware VL53L0X: {e}. Falling back to Mock.")
                self.dry_run = True

    def get_distance(self):
        """Returns distance in millimeters."""
        if self.dry_run:
            # Simulate salt depletion over time for demonstration purposes
            self.mock_distance += 15 
            if self.mock_distance > TANK_EMPTY_DISTANCE_MM + 50:
                self.mock_distance = TANK_FULL_DISTANCE_MM
            return self.mock_distance
        else:
            try:
                return self.sensor.range
            except Exception as e:
                logging.error(f"Error reading from sensor: {e}")
                return -1

class EPaperAdapter:
    """Adapter for the 2.13 inch SPI e-paper display."""
    def __init__(self, dry_run=False):
        self.dry_run = dry_run
        self.epd = None

        if not self.dry_run:
            try:
                # Attempting to load standard Waveshare library structure
                from waveshare_epd import epd2in13_V4
                self.epd = epd2in13_V4.EPD()
                self.epd.init()
                self.epd.Clear(0xFF)
                logging.info("Hardware E-Paper initialized successfully.")
            except ImportError:
                logging.warning("waveshare_epd library not found. Falling back to Mock E-Paper.")
                self.dry_run = True
            except Exception as e:
                logging.error(f"Failed to init hardware E-Paper: {e}. Falling back to Mock.")
                self.dry_run = True

    def update_display(self, percentage, distance):
        """Updates the e-paper display with current salt level."""
        timestamp = datetime.now().strftime('%H:%M')

        # Create a visual bar representation
        bar_length = 20
        filled_blocks = max(0, min(bar_length, int((percentage / 100.0) * bar_length)))
        empty_blocks = bar_length - filled_blocks
        visual_bar = f"[{'#' * filled_blocks}{'-' * empty_blocks}]"

        status_text = "OK"
        if percentage < 20:
            status_text = "REFILL SOON!"
        if percentage <= 5:
            status_text = "EMPTY! REFILL NOW!"

        display_string = (
            f"=== SALT LEVEL ===\n"
            f"Level: {percentage:.1f}%\n"
            f"Dist:  {distance} mm\n"
            f"{visual_bar}\n"
            f"Status: {status_text}\n"
            f"Updated: {timestamp}\n"
            f"=================="
        )

        if self.dry_run:
            logging.info(f"Mock E-Paper Update:\n{display_string}")
        else:
            try:
                # In a real implementation, we would use PIL (Pillow) to draw text onto an image buffer
                # and send it to self.epd.display(). For this validated pure-Python representation,
                # we log the buffer action that would occur.
                from PIL import Image, ImageDraw
                # Create blank image
                image = Image.new('1', (self.epd.height, self.epd.width), 255)
                draw = ImageDraw.Draw(image)
                # Draw text (using default font for simplicity)
                draw.text((10, 10), display_string, fill=0)
                # Rotate image if necessary for screen orientation
                image = image.rotate(90, expand=True)
                self.epd.display(self.epd.getbuffer(image))
                logging.info("Hardware display updated.")
            except Exception as e:
                logging.error(f"Failed to write to hardware display: {e}")

    def sleep(self):
        """Puts the e-paper display to sleep to prevent damage."""
        if not self.dry_run and self.epd:
            try:
                self.epd.sleep()
            except Exception as e:
                logging.error(f"Failed to sleep hardware display: {e}")

def calculate_percentage(distance_mm):
    """Calculates the remaining salt percentage based on calibration distances."""
    if distance_mm <= TANK_FULL_DISTANCE_MM:
        return 100.0
    if distance_mm >= TANK_EMPTY_DISTANCE_MM:
        return 0.0

    usable_range = TANK_EMPTY_DISTANCE_MM - TANK_FULL_DISTANCE_MM
    current_depletion = distance_mm - TANK_FULL_DISTANCE_MM
    percentage = 100.0 - ((current_depletion / usable_range) * 100.0)
    return max(0.0, min(100.0, percentage))

def main():
    parser = argparse.ArgumentParser(description="Water Softener Salt Level Monitor")
    parser.add_argument("--dry-run", action="store_true", help="Run without physical hardware")
    parser.add_argument("--interval", type=int, default=10, help="Polling interval in seconds")
    args = parser.parse_args()

    logging.info("Starting Water Softener Salt Level Monitor...")
    if args.dry_run:
        logging.info("Running in DRY-RUN mode.")

    sensor = VL53L0XAdapter(dry_run=args.dry_run)
    display = EPaperAdapter(dry_run=args.dry_run)

    last_percentage = -100.0 # Force initial update

    try:
        while True:
            distance = sensor.get_distance()
            if distance < 0:
                logging.warning("Invalid sensor reading. Retrying next cycle.")
                time.sleep(args.interval)
                continue

            percentage = calculate_percentage(distance)
            logging.info(f"Reading: {distance}mm -> {percentage:.1f}%")

            # Update display only if percentage changes by more than 2% to save screen lifespan
            if abs(percentage - last_percentage) >= 2.0:
                logging.info("Significant change detected. Updating display...")
                display.update_display(percentage, distance)
                last_percentage = percentage
                # Put display back to sleep after update
                display.sleep()

            time.sleep(args.interval)

    except KeyboardInterrupt:
        logging.info("Monitor stopped by user.")
    finally:
        display.sleep()
        logging.info("Shutdown complete.")

if __name__ == "__main__":
    main()