flairaio 0.2.0

Asynchronous Python library for Flair's API

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')

 

Bridges (click to expand)

# See model.py for details regarding "Bridges" and "Bridge" Data Classes


# Retrieve all bridges.
bridges = await client.get_bridges()

# Retrieve a specific bridge. Note: bridge_id is the specific bridge's ID as a string.
bridge = await client.get_bridge(bridge_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 Bridge LED Brightness (click to expand)

# Content of attributes and relationships dictionaries will depend on what is being updated.
# The example below is setting the LED brightness for a specific Flair Bridge.
# Note: Flair Bridge LED brightness accepts an int between, and including, 20-100


# create attributes dictionary
attributes = {
    "led-brightness": 50
}

# Set LED brightness
await client.update(resource_type='bridges', 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
Bridge	structure current-state hardware-version current-reading room sensor-readings bridge-states
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