waterfurnace 1.5.1

Python interface for waterfurnace geothermal systems

waterfurnace

Python interface for waterfurnace and geostar geothermal systems.

This provides basic sensor readings for waterfurnace geothermal systems by using the websocket interface that exists for the symphony website. This is not a documented or stable interface, so don't use this for critical systems. However, it is useful to record historical usage of your waterfurnace system.

Usage

   from waterfurnace.waterfurnace import WaterFurnace
   wf = WaterFurnace(user, pass)
   wf.login()
   data = wf.read()

The waterfurnace symphony service websocket monitors it's usage, so you need to do a data reading at least every 30 seconds otherwise the websocket is closed on the server side for resource constraints. The symphony website does a poll on the websocket every 5 seconds.

The software now supports a CLI. For details, use waterfurnace --help

Known Issues / limitations

• The python websocket code goes into a blocked state after long periods of usage (always takes at least days if not weeks or months to get to this state). I've yet to discover why. Help welcome.

License

• Free software: Apache Software License 2.0
• Documentation: https://waterfurnace.readthedocs.io.

Changelog

1.5.1 (2026-01-31)

• pypi build fixes

1.5.0 (2026-01-31)

• expose detailed location data for waterfurnace (thanks @masterkoppa)
• project main branch transition from master to main
• convert .rst to .md docs
• cleanup of obsolete files

1.4.0 (2026-01-09)

• Add get_energy_data, useful for homeassistant (thanks @masterkoppa)

1.3.1 (2026-01-07)

• Automate pypi build process

1.3.0 (2026-01-07)

• CLI enhanced to allow prompt for password (thanks @masterkoppa)
• Allow selecting device if multiple exist in your account (thanks @sam-kleiner)

1.2.0 (2025-09-13)

• Add SSL legacy compatibility to connect with modern SSL. Addresses UNSAFE_LEGACY_RENEGOTIATION_DISABLED error.
• Add LeavingWaterTemp and WaterFlowRate sensors (Series 7 WF)
• Added features to CLI (for details see --help)
  • Added debug flag
  • Added option sensor list specification
  • Added continous reporting
  • Added ability to specify furnace in a multi unit system

1.1.0 (2019-01-07)

• Fix retry logic

1.0.0 (2018-12-05)

• Detect unit automatically
• Add series 7 sensors

0.7.0 (2018-07-13)

• Add workaround timer to handle socket failures

0.6.0 (2018-02-21)

• Add timeout on socket

0.5.0 (2018-02-16)

• Update exception handling to be more Home Assistant friendly

0.4.0 (2018-02-05)

• More exceptions to distinguish errors we are expecting

0.3.0 (2018-01-23)

• Handle tid rollover

0.2.0 (2018-01-19)

• Library specific exceptions for login failures.

0.1.0 (2018-01-17)

• First release on PyPI.