# Homepage ![](https://2437601896-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MP4pDCJ-xRbneIBqxoC%2F-MP4pFi9pAL4XljP57wz%2F-MP59RsAdVcLct0fxuZS%2FHuskoll-Python-banner.png?alt=media\&token=4f66da47-8567-4d8b-b9c2-39442328f7d2) **Welcome to the Huskoll Python Library!** This library provides a wrapper to the open API for controlling Huskoll devices. All functions supported by the API are supported in this library as well. #### What is Huskoll? Huskoll is a Swedish device for controlling heat pumps of various brands. #### Disclaimer This library is not endorsed, affiliated, or made by anyone related with the Huskoll product team. It is created and maintained by a third-party. Hi, by the way! I'm Albin! If you want to check out more of my work, visit my personal website at ! # Quickstart ## Quickstart The library is easy and straightforward to use - it has one main class that represents a Huskoll Device. ### Obtain an access token To use the API (and this library), you need to have an access token. According to the[ Huskoll API docs](https://documenter.getpostman.com/view/6416017/S1TYTvqb#54b6d0af-5fa6-4f58-a204-1b8651aefa35), you can obtain that by sending an email to[ info@huskoll.se](mailto:info@huskoll.se). ### Obtain your hardware ID To use the API (and this library), you also need to obtain the Hardware ID for the device(s) you want to interract with. The Hardware ID is visible in the Huskoll App, and also on a sticker on the bottom of the Huskoll device. (at least in the devices I checked with, hardware version 1.3) ### Installation The Huskoll Python Library will soon be available via PyPi under the package name *huskoll*. ### And now, to the code! Below are some code examples which shows what you can do with the library. There are more parameters and functions available which might help a lot - make sure to check out the docs for [the Device class](/functions-and-classes/the-huskoll-class) and [the Status class](/functions-and-classes/the-status-class)! #### Initialization of devices This code shows the standard three-liner initialization code for devices. ```python from huskoll import Huskoll TOKEN = "YOUR_TOKEN_HERE" #Replace this with your token HARDWARE_ID = "YOUR_HARDWARE_ID_HERE" #Replace this with the hardware ID of the device you wish to control device = Huskoll.Device(token=TOKEN, hardware_id=HARDWARE_ID) #Create an object to work with the device. You can create as many of these as you want for multiple devices. ``` #### Basic functions, executed one-by-one This example shows the execution of some basic functions, one-by-one. Overwhelmed? Scroll a bit further down :) ```python from huskoll import Huskoll #Import the library TOKEN = "YOUR_TOKEN_HERE" #Replace this with your token HARDWARE_ID = "YOUR_HARDWARE_ID_HERE" #Replace this with the hardware ID of the device you wish to control device = Huskoll.Device(token=TOKEN, hardware_id=HARDWARE_ID) #Create an object to work with the device input("Press enter to turn off your heat pump.") device.power_off() #Quick function to power off the device input("Press enter to turn on your heat pump.") device.power_on() #Quick function to power on the device input("Press enter to change the heating mode to cooling.") device.set_cooling() #Quick function to set the device heating mode to cooling input("Press enter to change the heating mode to heating.") device.set_heating() #Quick function to set the device heating mode to heating input("Press enter to change the device temperature to 20.") device.set_temp(20) #Quick function to set the device temperature to a set point input("Press enter to decrease the device temperature by 2 steps.") device.decrease_temperature(by=2) #Quick function to decrease the device temperature. The by-parameter indicates by how many steps the temperature should be decreased. input("Press enter to increase the device temperature by 1 step.") device.increase_temperature() #The by parameter does not have to be set here, since its default is 1. ``` #### Update multiple parameters at once This example shows how to update multiple parameters to Huskoll at once, limiting the number of API requests and making the code prettier. ```python from huskoll import Huskoll #Import the library TOKEN = "YOUR_TOKEN_HERE" #Replace this with your token HARDWARE_ID = "YOUR_HARDWARE_ID_HERE" #Replace this with the hardware ID of the device you wish to control device = Huskoll.Device(token=TOKEN, hardware_id=HARDWARE_ID) #A number of utility variables are provided by the library, and some of them are used below! device.update_status( new_power_status=device.POWER_ON, new_temperature=23, new_fan_speed=device.FAN_HIGH ) #Set the device power to on, the temperature to 23 degrees, and the fan speed to high. The rest (the heating mode) will be unchanged. ``` #### Get device status ```python from huskoll import Huskoll #Import the library TOKEN = "YOUR_TOKEN_HERE" #Replace this with your token HARDWARE_ID = "YOUR_HARDWARE_ID_HERE" #Replace this with the hardware ID of the device you wish to control device = Huskoll.Device(token=TOKEN, hardware_id=HARDWARE_ID) #Create an object to work with the device device_status = device.get_status() #Get the device status #Print out device status print("Device status: ") print(f"Power: {device_status.power}") #Print out the power status print(f"Current mode: {device_status.mode}") #Print out the mode print(f"Current set temperature: {device_status.current_set_point}") #Print out the current set temperature print(f"Current environment temperature: {device_status.current_env_temperature}") #Print out the current environment temperature ``` # The Device class The Device class is the only class that will be interacted with by the programmer and includes various functions for working with the Huskoll device. ### Initialization Initialization of the class is done by passing the device hardware ID and a token. The token can be obtained by emailing Huskoll according to their [API docs](https://documenter.getpostman.com/view/6416017/S1TYTvqb#4d0f5740-0f2a-430b-8217-4b320adae485). The hardware ID can be found in the app or on the bottom of the sensor. ### Functions #### get\_status() Calls the Huskoll API to get the current status of the device. Updates the ".status" parameter of the class and returns a [Status](/functions-and-classes/the-status-class) object representing the current device status. #### update\_status(new\_power\_status=None, new\_mode=None, new\_fan\_speed=None, new\_temperature=None) Calls the Huskoll API to update one or multiple parameters for the device. Only one of these variables needs to be set - the rest will be taken from the current device status. *Tip:* Check out the quick helper functions below if you only want to update one parameter. #### power\_off() Powers off the heat pump. Does not change any other already set parameters. Shortcut function to update\_status. #### power\_on() Powers on the heat pump. Does not change any other already set parameters. Shortcut function to update\_status #### set\_cooling() Sets the device heating mode to cooling. Does not change any other already set parameters. Shortcut function to update\_status. #### set\_heating() Sets the device heating mode to heating. Does not change any other already set parameters. Shortcut function to update\_status. #### fan\_speed\_low() Sets the device fan speed to low. Does not change any other already set parameters. Shortcut function to update\_status. #### fan\_speed\_medium() Sets the device fan speed to medium. Does not change any other already set parameters. Shortcut function to update\_status. #### fan\_speed\_high() Sets the device fan speed to high. Does not change any other already set parameters. Shortcut function to update\_status. #### fan\_speed\_auto() Sets the device fan speed to auto. Does not change any other already set parameters. Shortcut function to update\_status. Shortcut function to update\_status. #### set\_temp(new\_temp, supress\_warning=False) Sets the heat pump to a new temperature as specified by new\_temp. If you get a warning by executing this function and want to ignore it, set the supress warning variable to True. #### change\_temperature(by=1, force\_status\_update=False): Function for changing the set temperature goal(set point) of the device by a certain steps. Takes two optional keywords: **by** - how many steps to change the temperature with. Defaults to 1. **force\_status\_update** - if not True, the device will use its stored status data if it has read the status before this function was called. Defaults to False. #### def decrease\_temperature(by=1, force\_status\_update=False): Function for decreasing the set temperature goal(set point) of the device by a certain steps. Takes two optional keywords: **by** - how many steps to change the temperature with. Defaults to 1. **force\_status\_update** - if not True, the device will use its stored status data if it has read the status before this function was called. Defaults to False. This function calls change\_temperature under-the-hood. #### increase\_temperature(by=1, force\_status\_update=False): Function for decreasing the set temperature goal(set point) of the device by a certain steps. Takes two optional keywords: **by** - how many steps to change the temperature with. Defaults to 1. **force\_status\_update** - if not True, the device will use its stored status data if it has read the status before this function was called. Defaults to False. This function calls change\_temperature under-the-hood. ### Internal helper functions #### generate\_request\_auth() Returns a dictionary with the required parameters to send to the Huskoll server for authentication. Takes no arguments. ### Helper variables The class also provides the following helper variables, which are the strings that Huskoll's API accepts. #### Power-related helpers **POWER\_ON** and **POWER\_OFF** #### Fan-related helpers **FAN\_AUTO**, **FAN\_LOW**, **FAN\_MEDIUM**, and **FAN\_HIGH** #### Heating mode related helpers **COOL** and **HEAT**. # The Status class The Status class represents the status of a Huskoll device, and can be retrieved by calling `Huskoll.get_status()`. The class has the following values:
**status**: The current status of the device as returned by the server (usually "online" if your device is alive and well) **power:** What power the heat pump was last set to by the device. Possible known values: "on", "off". **mode:** What mode the heat pump was last set to by the device. Possible known values: "cool", "heat". **current\_set**\_**point:** What temperature the heat pump was last set to by the device. Possible known values: Integers within the span 8 - 32 degrees. **fan\_speed:** What fan speed the heat pump was last set to by the device. Possible known values: "low", "medium", "high", and "auto". {% hint style="warning" %} Due to lack of documentation, the definitions of the current *env* temperature value and the last alarm variable has been made based on assumptions. {% endhint %} **current\_env\_temperature:** The last reported environment temperature (by the device sensors) **last\_alarm:** When the device last reported a temperature alarm. **hardware\_generation:** The hardware generation of the device.