BESS-Guard: Asynchronous Battery Safety and HVAC Control Emulator

BESS-Guard is a Python-based asynchronous simulation project that models selected monitoring, safety-response, and thermal-management workflows used in Battery Energy Storage Systems (BESS).

The project demonstrates how incoming battery-rack telemetry can be processed concurrently with a safety-control loop, staged HVAC logic, structured event logging, and simulated rack isolation through contactor tripping when predefined operating limits are exceeded.

Note: This repository is an educational and portfolio-oriented software emulator. It is not intended for deployment in safety-critical BESS hardware or as a replacement for certified battery-management, protection, or industrial control systems.

---

🛠️ Key Architectural Features

• Asynchronous Telemetry Processing: Uses Python's asyncio framework to run telemetry ingestion and safety/HVAC evaluation loops concurrently without blocking the main execution flow.
• Single-Event Processing Logic: Uses timestamp tracking (last_timestamp_processed) to ensure that each incoming telemetry sample is evaluated and logged once, preventing duplicated event records.
• Multi-Stage HVAC Control: Implements threshold-based thermal management with three cooling stages:
  • Stage 1: Fan cooling
  • Stage 2: Liquid chiller activation
  • Emergency mode: Maximum fan speed and chiller flow
• Safety Boundary Evaluation: Continuously evaluates temperature and voltage limits and classifies operating conditions as NORMAL, WARNING, CRITICAL_THERMAL_RUNAWAY, or CRITICAL_ELECTRICAL_FAULT.
• Protective Rack Isolation: Simulates opening the main DC contactors when a critical safety threshold is exceeded, representing electrical isolation of the affected battery rack.
• Structured JSON Logging: Generates machine-readable telemetry and incident records suitable for post-processing, visualization, and basic fault-analysis workflows.

---

📈 System Response and Thermal Analysis

The simulation includes a predefined thermal-ramp scenario in which cell temperature and voltage increase progressively until a critical safety limit is reached.

What the visualization demonstrates:

• Discrete telemetry processing: Each telemetry update is processed once, avoiding repeated records caused by the faster safety-loop polling interval.
• Progressive thermal response: The HVAC controller transitions from inactive operation to fan cooling, liquid-chiller cooling, and finally emergency cooling as temperature rises.
• Safety override and rack isolation: Once the critical temperature boundary is exceeded, the controller commands emergency cooling, records an incident snapshot, and simulates opening the rack contactors.

---

📂 Generated JSON Outputs

The simulation produces two structured JSON files:

1. Active Telemetry Stream (telemetry_log.json)

This file stores one JSON object per processed telemetry sample. It records the operating state, electrical and thermal measurements, HVAC condition, and contactor status.

{
    "timestamp": "2026-06-23T23:41:25Z",
    "bess_rack_id": "RACK_A1",
    "system_state": "WARNING",
    "metrics": {
        "cell_temp_C": 46.2,
        "cell_voltage_V": 4.1,
        "current_A": 120
    },
    "hvac_status": {
        "mode": "STAGE_2_LIQUID_CHILLER",
        "fan_speed_pct": 80,
        "chiller_flow_Lmin": 15.0,
        "cooling_fans": "ON",
        "liquid_chiller": "ON"
    },
    "contactor_status": "CLOSED"
}

2. Incident Black-Box Record (safety_events.json)

This file is generated only after a critical safety trip. It captures the fault classification, telemetry snapshot, HVAC state, and simulated protection actions at the time of rack isolation.

{
    "event_id": "EVT_20260623_234128",
    "timestamp": "2026-06-23T23:41:28Z",
    "severity": "CRITICAL",
    "fault_description": "Safety envelope boundary breached. Source: CRITICAL_THERMAL_RUNAWAY",
    "automated_actions_executed": [
        "Initiated HVAC emergency cooling command (EMERGENCY_MAX)",
        "Opened Main DC Contactors (Isolated Rack_A1)"
    ],
    "snapshot_at_trip": {
        "temperature_C": 62.1,
        "voltage_V": 4.26,
        "current_A": 160
    },
    "hvac_snapshot_at_trip": {
        "mode": "EMERGENCY_MAX",
        "fan_speed_pct": 100,
        "chiller_flow_Lmin": 25.0,
        "cooling_fans": "ON",
        "liquid_chiller": "ON"
    },
    "contactor_status_at_trip": "OPEN"
}

---

🚀 Getting Started

Prerequisites

The core simulation uses only Python standard-library modules.

• Python 3.8 or later

For optional telemetry analysis and plot generation, install the required libraries:

pip install pandas matplotlib

Run the Simulation

Execute the Python script or Jupyter Notebook cell containing:

await main()

The simulation will dynamically generate telemetry sequences, evaluate safety boundaries, command the closed-loop HVAC layers, and produce the structured logging files (telemetry_log.json and safety_events.json).

Optional Analysis

Use the analysis script or notebook cell to parse the time-series logs and generate the diagnostic performance plot: bess_hvac_response.png.

---

🔧 Potential Future Extensions

• Integration with real BMS telemetry sources such as CAN, Modbus, or MQTT.
• Configurable safety thresholds through YAML or JSON configuration files.
• State-of-charge (SoC) and state-of-health (SoH) estimation modules.
• Battery-pack rather than single-rack simulation scaling.
• Fault-injection scenarios for sensor failures, communication loss, and abnormal current events.
• Interactive dashboard visualization using Streamlit or Plotly.
• Unit tests and automated CI/CD validation.

---

⚠️ Disclaimer

BESS-Guard is a software simulation created for learning, portfolio development, and demonstration of asynchronous control-flow concepts in battery-energy-storage applications. It must not be used as a safety-certified control system for real battery installations.