HAPSIC is an advanced, physics-based controller designed to run natively on the ESP32 (via ESPHome). It actively calculates complex thermodynamic states (e.g., Dew Point, Mixing Ratios) in real-time to precisely control a steam humidifier via a 0-10V DAC, ensuring optimal target humidity in an HVAC duct without risking condensation or mold.
Standard humidistats simply turn on when Relative Humidity drops below a setpoint. This is dangerous for steam injection into HVAC ducts; if the duct temperature isn't hot enough, or the mass flow rate isn't high enough, injecting steam blindly will exceed the saturation point, causing the duct to rain condensation inside your walls.
HAPSIC solves this with math.
- Open HACS in Home Assistant
- Go to Automation → ⋮ (three dots) → Custom repositories
- Add
astyrrian1/hapsicwith category AppDaemon - Click Install
- Restart AppDaemon
- Copy
apps/hapsic_controller/hapsic_controller.pyinto your AppDaemonapps/hapsic_controller/directory - Configure your
apps.yamlwith the appropriate entity IDs - Restart AppDaemon
HAPSIC ships with a generic Mission Control dashboard for monitoring the physics engine, duct safety, and moisture balance in real time. It uses only HAPSIC contract entities and intentionally excludes site-specific sensors, locations, rooms, vendors, and personal Home Assistant helpers.
The companion Home Assistant MQTT/package definitions live in packages/hapsic_sensors.yaml. Copy that file into your Home Assistant packages/ directory when manually installing or updating the dashboard sensors.
Prerequisites (install via HACS → Frontend):
To install:
- Copy
packages/hapsic_sensors.yamlinto your Home Assistantpackages/directory and restart Home Assistant Core - In Home Assistant, go to Settings → Dashboards → Add Dashboard
- Open the new dashboard, click ⋮ → Edit Dashboard → ⋮ → Raw configuration editor
- Paste the contents of
dashboards/mission-control.yaml - Save
Personal production dashboards should live in your own Home Assistant config repository. Keep local-only entities, room names, vendor hardware, and location-specific context out of this open-source dashboard.
Dashboard entity contract:
- State and faults:
sensor.hapsic_fsm_state,sensor.hapsic_fault_reason,sensor.hapsic_boil_status - User inputs/storage:
input_number.target_dew_point,input_number.humidifier_max_capacity,input_number.hapsic_chi_ema,input_text.hapsic_boiler_curve - Physics and control:
sensor.hapsic_steam_voltage,sensor.hapsic_steam_mass,sensor.hapsic_ventilation_loss,sensor.hapsic_net_flux,sensor.hapsic_structure_velocity,sensor.hapsic_room_deficit,sensor.hapsic_target_duct_dp,sensor.hapsic_max_achievable_dp,sensor.hapsic_is_target_infeasible - Psychrometrics and duct safety:
sensor.hapsic_room_dew_point,sensor.hapsic_room_average_temp,sensor.hapsic_room_average_rh,sensor.hapsic_pre_steam_dp,sensor.hapsic_duct_dp,sensor.hapsic_cleansed_supply_temp,sensor.hapsic_cleansed_supply_rh,sensor.hapsic_cleansed_post_steam_temp,sensor.hapsic_cleansed_post_steam_rh,sensor.hapsic_supply_flow,sensor.hapsic_cleansed_airflow,binary_sensor.hapsic_shelly_offline,binary_sensor.hapsic_duct_temp_fallback_active - Health:
sensor.hapsic_chi_instant,sensor.hapsic_health_measured_steam,sensor.hapsic_health_production_efficiency - Economy advisory:
binary_sensor.hapsic_economy_advisory_active,binary_sensor.hapsic_economy_advisory_severe,binary_sensor.hapsic_economy_steaming_active,binary_sensor.hapsic_passive_import_candidate,sensor.hapsic_economy_advisory_reason,sensor.hapsic_economy_negative_net_streak,sensor.hapsic_economy_severe_net_streak,sensor.hapsic_economy_suggested_target_delta,sensor.hapsic_passive_import_lbs_hr,sensor.hapsic_passive_export_lbs_hr,sensor.hapsic_economy_advisory_time_7d,sensor.hapsic_economy_advisory_count_7d,sensor.hapsic_economy_severe_time_7d,sensor.hapsic_economy_steaming_time_7d
HAPSIC includes three Blueprint automations for proactive system monitoring. Each can be imported with one click:
| Blueprint | Purpose |
|---|---|
| Critical Fault Alerts | Immediate notification on fault entry (zero flow, sensor failure, clogged filter, defrost, bypass, watchdog) |
| Maintenance & Awareness | Non-urgent alerts: target infeasibility, fault recovery, canister health (CHI EMA) |
| Daily Status Digest | Once-daily summary of system health, energy consumption, and weather conditions |
To install a blueprint:
- In Home Assistant, go to Settings → Automations & Scenes → Blueprints
- Click Import Blueprint and paste the raw GitHub URL of the blueprint file
- Create an automation from the blueprint and configure your notification target
HAPSIC is uniquely designed with a strict Local-First, Edge-Computed philosophy. The core intelligence lives directly on the microcontroller, ensuring physics boundaries are maintained safely, regardless of WiFi connectivity or Home Assistant crashes.
However, we maintain a mathematically identical "Digital Twin" in Python for state-of-the-art testing.
The native firmware compiled by ESPHome:
- Handles floating-point Magnus-Tetens formula calculations for vapor pressure and dew point.
- Evaluates the mass balance (translating Target Dewpoint into sensible Grams of Steam per Kg of Air).
- Utilizes a complex Finite State Machine (FSM) governing anti-short-cycling, proportional bounding, safety relay triggers, and graceful 30-minute sensor-failure fallback mechanics.
A mathematically identical, 1:1 replica of the C++ thermodynamic engine and FSM, executed entirely natively in Python.
- Instead of taking 20 minutes to flash a microcontroller to test a new proportional threshold, DevOps/engineers can run weeks of simulated time through the Python twin in milliseconds.
HAPSIC binds gracefully into Home Assistant payloads.
- It reads data off a Zehnder ComfoAir Q ERV (Supply Temp, Extract Humidity, air flows) alongside physical Duct Sensors to compute real-time safety thresholds over Modbus/CAN bus.
- Prioritizes a 3-Tier fallback logic: House HA Variables -> Zehnder CAN variables -> 30-minute Cached Lock -> Safe Hardware Shutdown.
Designed specifically for the M5Stack StamPLC (ESP32), driving:
MCP4725I2C DACs for 0-10V Steam and Fan modulation.AW9523I2C Expander for physical safety relay switching.
HAPSIC enforces a strict Enterprise-Grade CI/CD pipeline. No Pull Request can be merged unless both the C++ firmware and the Python simulator traces match their calculations flawlessly.
- See SETUP.md to configure your local toolchain spanning Python, ESPHome, Clang-format, and preparing your M5Stack StamPLC device via USB.
- See CONTRIBUTING.md for a comprehensive guide on running the test suites, generating simulations, and contributing to the engine.
- See CHANGELOG.md for release history.