pyfreshr

Python library around the Fresh-r web interface for use in a Home Assistant integration.

Installation

pip install pyfreshr

Quick start

import asyncio
from pyfreshr import FreshrClient

async def main():
    async with FreshrClient() as client:
        await client.login("user@example.com", "password")

        devices = await client.fetch_devices()
        for device in devices:
            readings = await client.fetch_device_current(device)
            print(device.id, readings.t1, readings.flow, readings.co2)

asyncio.run(main())

Session persistence

The login sequence performs three HTTP round-trips. To avoid repeating this on every Home Assistant restart, save the session token after login and restore it on the next startup. The client re-authenticates automatically if the restored token has expired.

from pyfreshr import FreshrClient

async def setup(hass, stored_token):
    client = FreshrClient(on_session_update=lambda token: hass.store.save(token))

    if stored_token:
        client.restore_session(stored_token)   # skip login if token is still valid
    else:
        await client.login("user@example.com", "password")

    return client

Logging

The library uses Python's standard logging module under the logger name pyfreshr.client. To see debug output (HTTP requests, response statuses, session events) enable it in your application:

import logging
logging.getLogger("pyfreshr.client").setLevel(logging.DEBUG)

In Home Assistant, add this to your configuration.yaml:

logger:
  logs:
    pyfreshr.client: debug

Example script

Run the example script (without installing the package) from the repository root:

PYTHONPATH=src python examples/example_usage.py

You can also set credentials via environment variables FRESHR_USER and FRESHR_PASS before running the script.

Models

DeviceSummary

Returned by fetch_devices(). Contains the device identifier and metadata.

DeviceReadings

Returned by fetch_device_current(). All numeric fields are None when the API does not return a value for the device type. See Value processing for fields that are calibrated before being returned.

Supported devices

The dashboard exposes four device types. Three are supported; the fourth (Extract) uses a separate external API that is not covered by this library.

The device type is detected automatically from the type string returned by the API (substring match, mirroring the dashboard JS). fetch_device_current accepts a DeviceSummary directly and uses its type to select the correct API request name and default field list.

Value processing

Raw API values are calibrated before being returned, matching the processing performed by the dashboard JavaScript (processCurrentData). The processed values are reflected in the DeviceReadings fields.

Flow (DeviceReadings.flow)

Flow is calibrated through a piecewise curve. For Forward devices the raw sensor value is first divided by 3 before the curve is applied.

if raw_flow > 200:
    flow = (raw_flow − 700) / 30 + 20
else:
    flow = raw_flow

flow = round(flow, 1)  # m³/h

Humidity (DeviceReadings.hum)

Humidity is adjusted for the supply-air temperature using the Magnus-Tetens formula. The reference temperature used depends on device type:

T_sh = 243.04 × (a − ln(hum/100)) / (17.625 + ln(hum/100) − a)
       where a = 17.625 × dp / (243.04 + dp)

hum_adj = hum × exp(4283.78 × (T_sh − T_ref) / (243.12 + T_sh) / (243.12 + T_ref))
hum_adj = round(hum_adj, 1)  # %RH

If any input value is missing or the formula produces NaN the raw humidity (rounded to 1 dp) is returned instead.