flairaio

Asynchronous Python library for Flair's API


Keywords
flair, systems, api, oauth2, client, vent, puck, flair-client, flair-puck, flair-pucks, flair-python, flair-vent, flair-vents
License
MIT
Install
pip install flairaio==0.1.3

Documentation

Flairaio

Asynchronous Python library for Flair's API using OAuth 2.0 Authentication.

This package provides an API client for the Flair API to be used with OAuth 2.0 credentials generated by Flair. For API access, please contact Flair Support with the email address associated with your registered Flair account.

Installation

PyPI

pip3 install flairaio

This package depends on aiohttp and requires Python 3.7 or greater.

Usage

Creating Client

import asyncio
from flairaio import FlairClient
from aiohttp import ClientSession

async def main():
    async with ClientSession() as session:
    
        # Create a client using OAuth 2.0 client_id and client_secret
        client = FlairClient('client_id', 'client_secret', session)
        

        ###################################################################################
        Examples within the examples section utilize the FlairClient instance created above
        ###################################################################################

        
        
loop = asyncio.get_event_loop()
loop.run_until_complete(main())

Examples

 

Retrieving objects of interest


Users (click to expand)
# See model.py for details regarding "Users" and "User" Data Classes


# Retrieve all users.
users = await client.get_users()

# Retrieve a specific user. Note: user_id is the specific user's ID as a string.
user = await client.get_user(user_id='1')

 

Structures (click to expand)
# See model.py for details regarding "Structures" and "Structure" Data Classes


# Retrieve all structures.
structures = await client.get_structures()

# Retrieve a specific structure. Note: structure_id is the specific structure's ID as a string.
structure = await client.get_structure(structure_id='1')

 

Rooms (click to expand)
# See model.py for details regarding "Rooms" and "Room" Data Classes


# Retrieve all rooms.
rooms = await client.get_rooms()

# Retrieve a specific room. Note: room_id is the specific room's ID as a string.
room = await client.get_room(room_id='1')

 

Pucks (click to expand)
# See model.py for details regarding "Pucks" and "Puck" Data Classes


# Retrieve all pucks.
pucks = await client.get_pucks()

# Retrieve a specific puck. Note: puck_id is the specific puck's ID as a string.
puck = await client.get_puck(puck_id='1')

 

Vents (click to expand)
# See model.py for details regarding "Vents" and "Vent" Data Classes


# Retrieve all vents.
vents = await client.get_vents()

# Retrieve a specific vent. Note: vent_id is the specific vent's ID as a string.
vent = await client.get_vent(vent_id='1')

 

Thermostats (click to expand)
# See model.py for details regarding "Thermostats" and "Thermostat" Data Classes


# Retrieve all thermostats.
thermostats = await client.get_thermostats()

# Retrieve a specific thermostat. Note: thermostat_id is the specific thermostat's ID as a string.
thermostat = await client.get_thermostat(thermostat_id='1')

 

HVAC Units (click to expand)
# See model.py for details regarding "HVACUnits" and "HVACUnit" Data Classes


# Retrieve all HVAC units.
hvac_units = await client.get_hvac_units()

# Retrieve a specific HVAC unit. Note: hvac_id is the specific HVAC unit's ID as a string.
hvac_unit = await client.get_hvac_unit(hvac_id='1')

 

Zones (click to expand)
# See model.py for details regarding "Zones" and "Zone" Data Classes


# Retrieve all zones.
zones = await client.get_zones()

# Retrieve a specific zone. Note: zone_id is the specific zone's ID as a string.
zone = await client.get_zone(zone_id='1')

 

Getting all Flair Data (click to expand)
# See model.py for details regarding "FlairData" Data Class

# The resulting FlairData instance will contain an instance of "Users" and an instance of "Structures" which 
# contains instances of "Structure" created for every structure associated with your account. Within each Structure,
# you will find its id, attributes, relationships, as well as all rooms, pucks, vents, thermostats, HVAC units, and zones
# associated with said structure - each of these also contains their id, attributes, and relationships. As a bonus, the
# get_flair_data method also fetches the current reading endpoints for pucks and vents.


# Retrieve all flair data.
flair_data = await client.get_flair_data()

 

Retrieving Related Items


*** See Related Endpoints for available related links.

Getting related data (click to expand)
# You need to create an instance of the object of interest prior to retrieving its related item(s).


# Create a Puck instance for a specific puck. Note: puck_id is the specific puck's ID as a string.
puck = await client.get_puck(puck_id='1')

# Retrieve "current-reading" for puck
current_reading = await client.get_related(flair_object=puck, related_type='current_reading')

 

Creating


Creating New Room (click to expand)
# Content of attributes and relationships dictionaries will depend on what is being created.


# Create attributes dictionary for new room.
attributes = {
    "name": "My New Flair Room"
}

# Creat new room "My New Flair Room"
await client.create(resource_type='rooms', attributes=attributes, relationships={})

 

Deleting


Deleting Room (click to expand)
# Deleting a room with an id of '1234'
await client.delete(resource_type='rooms', item_id='1234')

 

Updating


Opening Vent (click to expand)
# Content of attributes and relationships dictionaries will depend on what is being updated.
# The example below is fully opening a specific Flair vent


# create attributes dictionary
attributes = {
    "percent-open": 100
}

# Fully open the vent
await client.update(resource_type='vents', item_id='1', attributes=attributes, relationships={})

 

Setting HVAC Unit Mode (click to expand)

Note:

* If structure is set to Manual mode: HVAC mode, temp, swing, and fan speed can only be set when the unit is powered on.

* If structure is set to Auto mode: Only swing and fan speed can be set.

* Fan speed: if structure is set to Manual mode, changing fan speed requires updating the attribute "fan-speed". Changing fan speed with structure in Auto mode requires updating the attribute "default-fan-speed".

* Swing: If structure is set to Manual mode, changing swing requires updating the attribute "swing". Changing swing with structure in Auto mode requires updating the attribute "swing-auto".

# Content of attributes and relationships dictionaries will depend on what is being updated.
# The example below is setting the HVAC Unit mode to Cool.


# create attributes dictionary
attributes = {
    "mode": 'Cool'
}

# Update HVAC unit's mode to Cool
await client.update(resource_type='hvac-units', item_id='1', attributes=attributes, relationships={})

 

Available Related Endpoints

Resource Type Related
HVAC Unit
  • puck
  • current-state
  • hvac-unit-states
  • structure
  • zone
  • plug
  • integration-structure
  • make
  • room
Puck
  • room
  • hardware-version
  • hvac-units
  • puck-states
  • closest-vents
  • beacon-sightings
  • current-reading
  • structure
  • sensor-readings
  • current-state
Room
  • remote-sensors
  • thermostat
  • structure
  • occupants
  • pucks
  • vents
  • hvac-units
  • room-states
  • bridges
  • current-conclusions
  • puck-apps
  • zones
  • plugs
  • occupancy-conclusions
  • room-auto-conclusions
Structure
  • admin-users
  • release-approvals
  • default-zone
  • remote-sensors
  • schedules
  • hvac-units
  • demand-response-program-enrollments
  • weather-readings
  • hvac-unit-groups
  • beacon-sightings
  • plugs
  • alerts
  • structure-states
  • current-conclusions
  • rooms
  • geofence-events
  • pucks
  • releases
  • bridges
  • licenses
  • occupancy-conclusions
  • thermostats
  • integration-structures
  • viewer-users
  • supported-device-brands
  • geofences
  • current-weather
  • active-schedule
  • current-state
  • ui-notifications
  • zones
  • invitations
  • vents
  • plug-invites
  • editor-users
  • devices
  • puck-oauth-apps
Thermostat
  • current-state
  • integration-structure
  • zone
  • remote-sensor
  • thermostat-states
  • structure
  • room
User
  • networks
  • unfinished-setup-structure
  • integrations
  • ui-notifications
  • accessible-structures
  • editable-structures
  • received-invitations
  • default-structure
  • primary-device
  • structures
  • adminable-structures
  • viewable-structures
  • devices
  • puck-oauth-apps
Vent
  • current-reading
  • current-state
  • sensor-readings
  • closest-puck
  • room
  • vent-states
  • structure
Zone
  • rooms
  • zone-auto-conclusions
  • structure
  • thermostat
  • hvac-unit