Skip to content

Commit

Permalink
Merge pull request #15 from RobertD502/dev
Browse files Browse the repository at this point in the history 
merge from dev branch
  • Loading branch information
@RobertD502
RobertD502 authored Jan 17, 2022
2 parents 3b4cf5b + e51dd77 commit 4347eb5
Show file tree
Hide file tree
Showing 14 changed files with 1,383 additions and 408 deletions.
137 changes: 73 additions & 64 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,110 +2,119 @@
<a href="https://www.buymeacoffee.com/RobertD502" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174"></a>
[![hacs_badge](https://img.shields.io/badge/HACS-Custom-orange.svg)](https://github.com/custom-components/hacs) ![GitHub manifest version (path)](https://img.shields.io/github/manifest-json/v/RobertD502/home-assistant-flair?filename=custom_components%2Fflair%2Fmanifest.json)

Custom component for Home Assistant Core for controlling Flair vents/rooms and monitoring pucks/vents/rooms. This integration DOES NOT control or pull in information about mini-splits.
Custom component for Home Assistant Core for controlling and monitoring Flair structures, pucks, vents, rooms, and mini split units.

Donations aren't required, but are always appreciated. If you enjoy this integration, consider buying me a coffee by clicking on the link above.
**Donations aren't required, but are always appreciated. If you enjoy this integration, consider buying me a coffee by clicking on the logo above.**

**Prior To Installation**
## **Prior To Installation**

You will need credentials consisting of client_id and client_secret. If you don't already have these, for API access, please [contact Flair Support](https://support.flair.co/hc/en-us/requests/new) with the email address associated with your registered Flair account.
You will need credentials consisting of **OAuth1** `client_id` and `client_secret`. If you don't already have these, for API access, please [contact Flair Support](https://support.flair.co/hc/en-us/requests/new) with the email address associated with your registered Flair account.

## Installation
# Table of Contents
* [Installation](#installation)
* [With HACS](#with-hacs)
* [Manual](#manual)
* [Setup](#setup)
* [Devices](#devices)
* [Structure](#structure)
* [Puck](#puck)
* [Vent](#vent)
* [Room](#room)
* [Mini Split](#mini-split)

### With HACS
# Installation

## With HACS
1. Open HACS Settings and add this repository (https://github.com/RobertD502/home-assistant-flair)
as a Custom Repository (use **Integration** as the category).
2. The `Flair` page should automatically load (or find it in the HACS Store)
3. Click `Install`

### Manual
## Manual
Copy the `flair` directory from `custom_components` in this repository,
and place inside your Home Assistant Core installation's `custom_components` directory.


## Setup
1. Install this integration.
2. Use Config Flow to configure the integration with your Flair API client_id and client_secret.
# Setup
1. Use Config Flow to configure the integration with your Flair API client_id and client_secret.
* Initiate Config Flow by navigating to Configuration > Integrations > click the "+" button > find "Flair" (restart Home Assistant and / or clear browser cache if you can't find it)

## Features

### Puck
Pucks are exposed as `sensor` entities and have a `state` that displays `current temperature` obtained by the puck.
# Devices

Available attributes:
Each Flair mini-split, puck, room, structure, and vent is represented as a device in Home Assistant. Within each device
are several entities described below.

| Attribute | Description |
| --- | --- |
| `humidity` | This is the current humidity as measured by your puck |
| `is_active` | If puck is active or not. Can be either `true` or `false` |
| `is_gateway` | If puck is set up to be a gateway. Can be either `true` or `false` |
| `voltage` | Displays the current voltage of the puck. If it is plugged in, this value will be constant (3.41 for me). If using batteries to power your puck, this can be used to monitor battery health. |
| `rssi` | Displays puck connection strength. |
## Structure

### Puck Light Level
Puck Light Level measurements are exposed as `sensor` entities. The unit of measurement is `lux` - this may change once I hear back from Flair.
Each structure has the following entities:

| Entity | Entity Type | Additional Comments |
| --- | --- | --- |
| `Home/Away Mode` | `Select` | Please read Flair's documentation regarding [Home/Away Mode](https://support.flair.co/hc/en-us/articles/360044922952-Home-Away-Mode) |
| `Schedules` | `Select` | Schedules and this entity are only available if the Flair System Mode is set to "Auto". All schedules created within the Flair app will appear here. To turn off a schedule, select "No Schedule" |
| `Structure Mode` | `Select` | Please read Flair's documentation regarding [Structure mode](https://support.flair.co/hc/en-us/articles/360058466931-Mode) |
| `System Mode` | `Select` | Please read Flair's documentation regarding [Auto mode](https://support.flair.co/hc/en-us/articles/360042659392-System-Auto) and [Manual mode](https://support.flair.co/hc/en-us/articles/360043099291-System-Manual) |

### Vent
<p align="center">
<img width="533" height="1000" src="https://github.com/RobertD502/home-assistant-flair/blob/main/images/flair_system_setting_smaller.png?raw=true">
</p>

In order to control vents, the System setting in the Flair app needs to be set to `Manual` (see image above). If you have it set to `Auto`, you will still be able to control your vents, however, eventually Flair will override your changes.
## Puck

Vents are exposed as `fan` entities and have a `state` of either `on` or `off`. If your vent is either `50` or `100` percent open, the state will be `on`. If your vent is `0` percent open, the state will be `off`. Turning the vent fan entity `on` manually will fully open the vent (100 percent). Turning the vent fan entity `off` manually will completely close the vent (0 percent). You are also able to manually open the vent halfway (50 percent) by either changing the speed to `50` via the UI or by using the service `fan.set_percentage` and setting `percentage` to `50`- the same goes for fully open with `100` or fully closed with `0`.
Each puck has the following entities:

Available attributes:
| Entity | Entity Type | Additional Comments |
| --- | --- | --- |
| `Humidity` | `Sensor` | |
| `Light Level` | `Sensor` | |
| `Temperature` | `Sensor` | |
| `RSSI` | `Sensor` | |
| `Voltage` | `Sensor` | Displays the current voltage of the puck. If using batteries to power your puck, this can be used to monitor battery health. |

| Attribute | Description |
| --- | --- |
| `percent_open` | The amount of percent the vent is open. This can be `100`, `50`, or `0` |
| `duct_temp` | The current duct temperature reading of your vent. This value will be in Fahrenheit or Celsius depending on the units Home Assistant is set to. |
| `duct_pressure_kPa` | The current duct pressure reading in kPa. |
| `voltage` | Displays the current voltage of the vent. If using batteries to power your vent, this can be used to monitor battery health. |
| `is_active` | If puck is active or not. Can be either `true` or `false`. Helpful in determining if a vent has gone offline as this will result in `false` being displayed for the `is_active` attribute |
| `rssi` | Connection strength of vent to puck |
**Note About Pucks**

### Room
Changes made to rooms will only persist if the System is set to `Auto` (the opposite of controlling vents).
Flair statement regarding Puck Light Level sensor:

Rooms are exposed as `climate` entities and have a `state` that displays the type of mode your house is in (`heat`, `cool`, `heat_cool`, or `off`). Note, you cannot change this state as it is a limitation of the official flair python API. Changing the temperature for a room climate entity will change the set temperature of the corresponding room. This change will remain for `until next scheduled event`, `3h`, `8h`, `24h`, or `forever`- this depends on the setting in the Flair app under Home Settings > System Settings > Default Hold Duration.
> It is not calibrated. The sensor itself, if the nominal reference is 1, can range from 0.3 to 1.6. This also doesn't take into account the mechanical loss in the Puck. In short, this is not an accurate lux sensor.
Available attributes:

| Attribute | Description |
| --- | --- |
| `is_active` | If room is active or not. Can be either `true` or `false`. |
## Vent

### Structure
<p align="center">
<img width="533" height="1000" src="https://github.com/RobertD502/home-assistant-flair/blob/main/images/flair_system_setting_smaller.png?raw=true">
</p>

Structures are exposed as `sensor` entities and have a `state` that displays the current active schedule, if any.
In order to control vents that are in Flair Rooms that have a temperature sensor, the System setting in the Flair app needs to be set to `Manual` (see image above). If you have it set to `Auto`, you will still be able to control your vents, however, eventually Flair will override your changes. This mode can also be set using a Flair Structure's `System Mode select entity` within Home Assistant. Any vents in Flair Rooms that don't report temperature can be controlled regardless of current mode set.

Available attributes:
Each Vent has the following entities:

| Attribute | Description |
| --- | --- |
| `available_schedules` | List of names of schedules that are available for this structure. Schedules are created and named from within the Flair App. |
| Entity | Entity Type | Additional Comments |
| --- | --- | --- |
| `Vent` | `Fan` | Has a state of either `on` or `off`. If your vent is either `50` or `100` percent open, the state will be `on`. If your vent is `0` percent open, the state will be `off`. Turning the vent fan entity `on` manually will fully open the vent (100 percent). Turning the vent fan entity `off` manually will completely close the vent (0 percent). You are also able to manually open the vent halfway (50 percent) by either changing the speed to `50` via the UI or by using the service `fan.set_percentage` and setting `percentage` to `50`- the same goes for fully open with `100` or fully closed with `0`. |
| `Duct Pressure` | `Sensor` | |
| `Duct Temperature` | `Sensor` | |
| `RSSI` | `Sensor` | |
| `Voltage` | `Sensor` | Displays the current voltage of the vent. If using batteries to power your vent, this can be used to monitor battery health. |

## Services

### flair.set_schedule
## Room

Available through UI Mode or YAML Mode (examples of both below).
Each Room has the following entities:

Required Data Fields:
| Entity | Entity Type | Additional Comments |
| --- | --- | --- |
| `Activity Status` | `Select` | Rooms can be set to Active or Inactive. |
| `Room` | `Climate` | Temperature set points can be changed on a room by room basis. Changing HVAC mode on a room by room basis is not supported as room HVAC mode (for all rooms) is controlled by a Flair structure. Changing HVAC mode for all rooms can be done using a structure's `Structure Mode` entity. |
| `Duct Temperature` | `Sensor` | |
| `RSSI` | `Sensor` | |
| `Voltage` | `Sensor` | Displays the current voltage of the vent. If using batteries to power your vent, this can be used to monitor battery health. |

| Field | Description |
| --- | --- |
| `entity_id` | entity_id of the structure for which you want to set a schedule (REQUIRED) |
| `schedule_name` | name of the schedule you want to use. List of available named schedules can be found under the `available_schedules` attribute of `structure` sensors. |
**Additional Notes**

UI Mode Example:
Changing the temperature for a room climate entity will change the set temperature of the corresponding room. This change will remain for `until next scheduled event`, `3h`, `8h`, `24h`, or `forever`- this depends on the setting in the Flair app under Home Settings > System Settings > Default Hold Duration.

![alt text](https://github.com/RobertD502/home-assistant-flair/blob/main/images/flair_set_schedule_ui.jpg?raw=true)

## Mini Split

YAML Mode Example:
Each Mini Split has the following entities:

![alt text](https://github.com/RobertD502/home-assistant-flair/blob/main/images/flair_set_schedule_yaml.jpg?raw=true)
| Entity | Entity Type | Additional Comments |
| --- | --- | --- |
| `Mini Split` | `Climate` | To fully control your mini split unit, the associated Flair structure needs to be in `Manual Mode`. If your structure is set to `Auto Mode` you will only be able to control `Fan speed` and `Swing` (if available for your unit). In addition, mini split set points are controlled by rooms if a Flair structure is set to `Auto Mode`. Changing the temperature of this climate entity will result in changing the room set point when in `Auto Mode`. |
30 changes: 14 additions & 16 deletions custom_components/flair/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,14 +5,15 @@
from flair import FlairHelper

import homeassistant.helpers.config_validation as cv
from homeassistant import config_entries
from homeassistant.config_entries import ConfigEntry
from homeassistant.const import EVENT_HOMEASSISTANT_STOP
from homeassistant.core import HomeAssistant
from homeassistant.exceptions import ConfigEntryNotReady
from homeassistant.const import (
CONF_CLIENT_ID,
CONF_CLIENT_SECRET
)
from .const import DOMAIN
from .const import DOMAIN, PLATFORMS


_LOGGER = logging.getLogger(__name__)
Expand All @@ -23,27 +24,24 @@ def setup(hass, config):
return True


async def async_setup_entry(hass, config_entry):
async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
"""Set up Flair integration from a config entry."""
client_id = config_entry.data.get(CONF_CLIENT_ID)
client_secret = config_entry.data.get(CONF_CLIENT_SECRET)
client_id = entry.data[CONF_CLIENT_ID]
client_secret = entry.data[CONF_CLIENT_SECRET]

_LOGGER.info("Initializing the Flair API")
flair = await hass.async_add_executor_job(FlairHelper, client_id, client_secret)
_LOGGER.info("Connected to API")

hass.data[DOMAIN] = flair

hass.async_add_job(
hass.config_entries.async_forward_entry_setup(config_entry, "sensor")
)

hass.async_add_job(
hass.config_entries.async_forward_entry_setup(config_entry, "fan")
)

hass.async_add_job(
hass.config_entries.async_forward_entry_setup(config_entry, "climate")
)
hass.config_entries.async_setup_platforms(entry, PLATFORMS)

return True

async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
"""Unload a Flair config entry."""
unload_ok = await hass.config_entries.async_unload_platforms(entry, PLATFORMS)
if unload_ok:
hass.data.pop(DOMAIN)
return unload_ok
Loading

0 comments on commit 4347eb5

Please sign in to comment.