# `haco` Home Assistant Control Objects
`haco` is a Home Assistant Add-On, and associated Tasmota daemon written in Berry, to greatly simplify the process of
exposing Home
Assistant controls (e.g. Pull-down Lists, Number Sliders, Sensors, etc.) from a Tasmota device - and handling the
communication between both sides.
Using `haco` to expose, for example, a "Restart Tasmota" button to Home Assistant is as simple as writing the following
Python code:
```py
from haco import Button, Tasmota
restart = Button('Restart Tasmota', icon='restart')
@restart.callback()
def ha(value) -> Tasmota[str, 'tasmota.cmd("restart 1")']:
return value
```
A fully functional restart button will now appear associated with the device in Home Assistant:
<img alt="Restart Button" height=50% src="https://raw.githubusercontent.com/fmtr/haco/release/assets/restart_button.png" width=50%/>
Or, more practically, a cookbook pull-down menu, for a Tuya air fryer, might look like this:
```py
OPTIONS = ['Default', 'Fries', 'Shrimp', 'Pizza', 'Chicken', 'Fish', 'Steak', 'Cake', 'Bacon', 'Preheat', 'Custom']
cookbook = Select('Cookbook', options=OPTIONS, icon='chef-hat')
@cookbook.callback()
def ha(value: str) -> Tasmota[int, tuya.send(4, 3)]:
return OPTIONS.index(value)
@cookbook.callback(trigger=tuya.received(4, 3))
def tasmota(value: int):
return OPTIONS[value]
```
<img alt="Air Fryer Cookbook" height=50% src="https://raw.githubusercontent.com/fmtr/haco/release/assets/air_fryer_cookbook.png" width=50%/>
## Do I Need This? Can't I Do this with Native Tasmota?
You certainly can.
But in my experience, the process is so fiddly, error-prone and hard to maintain that it's enough to
deter the casual user (as I am) entirely. Plus, sharing your configuration, once you've finally got it working, can mean
complex step-by-step guides, setting up triggers, finding MAC addresses and topics (in Tasmota) - and numerous
Blueprints, Helpers and Templates (on the Home Assistant side).
You can see how much work creating such guides involves by seeing how it
was [heroically undertaken by Blakadder](https://blakadder.com/proscenic-in-home-assistant/), as
compared with
the [full `haco`-based equivalent](https://github.com/fmtr/haco/blob/release/haco/configs/proscenic_t21.py).
With `haco`, on the other hand, the thorny parts of the initial setup are abstracted away and your final configuration
can often be shared via a single script. Below is a list of some of the tasks that `haco`
handles for you:
* Announcing the entity via MQTT to Home Assistant
* Generating MQTT/HA-friendly unique IDs
* Associating the entity with its parent device
* Subscribing and publishing to the relevant MQTT topics
* Managing the relevant Tasmota rules
* Appropriate serialization of data
* Translating Home Assistant messages to their to appropriate Berry data types, and vice versa
## Pre-Release
:warning: This library is currently in a pre-release state. The configuration format is likely to change, and
only `Sensor`, `Select`, `Button`, `Number`, `BinarySensor`, `Switch`, `Text`, `Update`, `Fan`
and `Climate` entities are currently implemented.
## Installation
Installation involves installing two parts: the Tasmota daemon and the Home Assistant Add-On. Both are fairly simple.
### Tasmota
I'd advise first using a guinea pig Tasmota device to get `haco` up and running. The device needs to have MQTT
connected and be available to Home Assistant (i.e. showing up
in [the Devices section](https://my.home-assistant.io/redirect/devices/)).
Once your test device is ready, with a recent (12.5+) version of Tasmota, simply paste the following into your Tasmota
Berry Script Console:
```be
{"download":tasmota.urlfetch('https://fmtr.link/haco/tapp','haco.tapp'), "restart":tasmota.cmd("restart 1")}
```
You should see output like `{'restart': {'Restart': 'Restarting'}, 'download': 200}` and the device will restart.
Once the device restarts, you should see the following among your Tasmota startup logs (in the regular console, not the
Berry one):
```
HACO: The haco daemon has started. Hostname: tasmota-test, MAC: 04:74:77:9B:CB:CC. Listening for configuration...
```
#### Older Tasmota Versions
With older Tasmota versions, download the [`haco.tapp` file](https://fmtr.link/haco/tapp) on a desktop
computer,
upload it to your device and restart manually.
### Home Assistant
You can now install the Home Assistant Add-On:
[](https://fmtr.link/haco/add-on)
Once the Add-On is installed, click into its Configuration tab and you'll see a setting called `assignments`:
```yaml
- config: null
identifier: null
```
#### Assigning a configuration module to a device
Now we're ready to assign a configuration module to our Tasmota device. For now, we can use a built-in test
module `test`. The `identifer` value should be the hostname (or MAC) of your Tasmota device. So for our example it
should look like this:
```yaml
- config: test
identifier: tasmota-test # Hostname of Tasmota device
```
Saving the Configuration will restart the Add-On. After the restart, you should see the following in the Add-On logs:
```
Device "Tasmota Test Device" successfully configured. Hostname: tasmota-test MAC: 04:74:77:9B:CB:CC.
```
In Home Assistant, find the device in [the Devices section](https://my.home-assistant.io/redirect/devices/). You should
now see a test Select (pulldown) control called "Greeter".
<img alt="WebLog Select" height=50% src="https://raw.githubusercontent.com/fmtr/haco/release/assets/greeter_select.png" width=50%/>
Selecting the greetings from the pulldown, you should see them appear in your Tasmota Berry console, e.g.
```console
haco says: Hello World!
```
This means `haco` is set up and working properly. Good! You can now use `haco` to assign configuration modules to your
Tasmota devices.
## Configuration Modules
Configuration modules are a little like drivers, that tell `haco` how to communicate with a Tasmota device, what
controls to expose to Home Assistant, etc.
So far we've only used the `test` configuration module, that exposed the Greeter pulldown, but to control
real-world devices, you'll need to assign them to a module written specifically for that device. There are currently two
types of modules,
Built-In and User-Defined.
Whichever type you use, assigning them to a device is done as we saw above.
### Built-In Modules
`haco` ships with a small number of built-in configurations. These can be found in
the [configs directory](https://github.com/fmtr/haco/blob/release/haco/configs) in this repo. But in the likely event
that your device hasn't already
been added, you'll need to define your own.
:information_source: The aim is to expand the number of built-in configurations over time. So if you define your own (
see below), please submit it to this repo as a Pull Request, or raise an Issue linking to your code!
### Creating Your Own Configuration Module
#### General module structure
A configuration module is, ultimately, just a typical Python module. In this case, they contain definitions from one or
more `Control` objects. Each control definition involves two things:
* The control object assigned to a variable, e.g. `temperature_sensor=Sensor(...)`
* Any required callback functions for the control, e.g. `@temperature_sensor.callback(...)<function>`
#### Location
User-Defined modules should be added to the `/config/haco` directory in Home Assistant, with a `.py` extension,
e.g. `/config/haco/my_config.py`.
#### Defining controls
Here are a couple of simple examples to help get you started defining your own configuration module.
##### Tasmota-Only Controls
First, let's define a Tasmota-only sensor to report how much free memory there is on the Tasmota device. This sensor
is "Tasmota-Only" as it only handles values sent _from_ Tasmota (and sends nothing back from Home Assistant).
```python
from haco import Sensor
memory = Sensor('Memory Free', icon='memory', uom=Sensor.UOM.DATA_KILOBYTES, uom_type=Sensor.UOM_TYPE.DATA_SIZE)
@memory.callback(trigger='Tele#Heap')
def tasmota(value: int):
return value
```
<img alt="Memory Sensor" height=50% src="https://raw.githubusercontent.com/fmtr/haco/release/assets/memory_sensor.png" width=50%/>
Let's break this control definition down into the control object, the callback decorator, and the callback itself.
###### The control object
First we initialise a `Sensor` control object, assign it to a variable called `memory`, give it a relevant icon, unit of
measure and type.
###### The callback decorator
The callback decorator `@memory.callback(trigger='Tele#Heap')` specifies a Tasmota trigger, the values from which will
be sent to the callback function.
This specific trigger, `Tele#Heap`, fires whenever telemetry data is returned from Tasmota and, specifically, returns
the `Heap` field, which contains the free
memory in kilobytes.
:warning: Tasmota callbacks _must_ have such a `trigger` specified in this decorator.
###### The callback
Note that the callback function is named `tasmota`. This name is important as it tells `haco` that this callback
handles values _from_ Tasmota.
The response from the trigger we specified in our callback decorator above gets fed into our callback as the `value`
argument. The (optional) type annotation for the `value` argument (the `int`) tells `haco` what data type to expect from
Tasmota, and type conversion gets done automatically.
The return value from the function is what will be returned to Home Assistant as the value for the sensor.
:information_source: Note that our callback function does not actually _do_ anything with our `value` other than return
it. But if we wanted to (for example) convert the value from kilobytes to bytes, this is where we'd do it,
with `return value*1000`.
:information_source: You can find the list of available units of measure [here](../../blob/release/haco/data/uom.py) and
types [here](../../blob/main/haco/data/type_sensor.py).
#### Home Assistant-Only Controls
Moving on to the opposite type of control, that is one that only handles values _from_ Home Assistant. The Button
control does
exactly this, as it is triggered by being pressing in Home Assistant, but Tasmota returns nothing to acknowledge that
press.
Here is how to define a `Button` control that, when pressed, restarts the Tasmota device.
```py
from haco import Button, Tasmota
restart = Button('Restart Tasmota', icon='restart')
@restart.callback()
def ha(value) -> Tasmota[str, 'tasmota.cmd("restart 1")']:
return value
```
In the case we define a `Button` control, and again use our decorator to add a callback to handle values _from_ Home
Assistant, which must therefore be named `ha`.
###### The `Tasmota` Type Annotation
The most notable difference with a Home Assistant (`ha`) callback is the `Tasmota` return type annotation. This takes
two arguments, `Tasmota[<type>,<berry_expression>]`. The
first argument is the type returned by the callback function, as per usual, and which again lets `haco` convert the
return value accordingly.
The second argument is an expression that defines _what to do_ on the Tasmota side when the button is pressed. In this
case, this
is just a Berry expression to restart Tasmota.
:warning: Note that Home Assistant callbacks _must_ have such a `Tasmota` type annotation for their return type.
:information_source: In the example above, the `value` argument received and returned by our callback is not actually
used by the Berry expression side. Home Assistant just sends a constant string (`PRESS`) when the button is pressed, so
the actual content of
the `value` argument is not important.
#### Two-Way Controls
Two-way controls need to handle values from _both_ Home Assistant and from Tasmota, and hence need both the callbacks
types - `ha` and `tasmota` we've seen above.
Here is an example two-way `Select` (pulldown menu) object. It allows setting the Tasmota `WebLog` console debugging
level from Home Assistant, and also reflects any changes to that setting made on the Tasmota side.
```python
from haco import Select, Tasmota
LOG_LEVELS = ["None", "Error", "Info", "Debug", "Debug More"]
weblog = Select('WebLog Level', icon='console', options=LOG_LEVELS)
@weblog.callback()
def ha(value) -> Tasmota[str, 'tasmota.cmd("WebLog "+value)']:
return LOG_LEVELS.index(value)
@weblog.callback(trigger='WebLog')
def tasmota(value: int):
return LOG_LEVELS[value]
```
The above is very similar to what we have already seen.
The `ha` callback takes friendly names (e.g. `Error`, `Info`) selected by the user in Home Assistant, and returns them
as their corresponding number values (`WebLog 1`, `WebLog2`) used by Tasmota.
The `tasmota` callback, naturally enough, does the exact opposite, returning the string names to Home Assistant whenever
the `WebLog` command is used on the Tasmota side.
<img alt="WebLog Select" height=50% src="https://raw.githubusercontent.com/fmtr/haco/release/assets/weblog_select.png" width=50%/>
#### Debugging Your Configuration
When you first assign a new configuration to a device, keep an eye on the Add-On logs for any errors. You'll see a
typical Python stack trace if anything goes wrong.
:warning: Each time you edit your configuration module (`.py` file), you'll need to restart the Add-On. Hot
is reloading not yet supported.
#### Additional Capabilities
More complex device controls (e.g. `Climate`, `Fan`) have additional capabilities beyond a single value requiting
Tasmota/Home Assistant
callbacks. Adding callbacks for these extended capabilities is done similarly to the above, only the callbacks need
to include the name of the capability. So if you want to add callbacks around setting the `target_humidity` of
a `Climate` control, you'd need to call your callbacks `target_humidity_tasmota` and `target_humidity_ha`, etc.
A full schema of these names will appear in subsequent documentation. But you can find example implementations for most
controls in the [built-in `development` config](https://github.com/fmtr/haco/tree/release/haco/configs/development.py).
Anway, if you get the names wrong, you'll see an error like this in your Add-On logs:
```
ValueError: Callback function name "set_mode_ha" is not valid for control "Climate". Must be one of: ['action_tasmota', 'current_humidity_tasmota', 'current_temperature_tasmota', 'mode_ha', 'mode_tasmota', 'preset_mode_ha', 'preset_mode_tasmota', 'swing_mode_ha', 'swing_mode_tasmota', 'target_humidity_ha', 'target_humidity_tasmota', 'target_temperature_ha', 'target_temperature_tasmota', 'temperature_high_ha', 'temperature_high_tasmota', 'temperature_low_ha', 'temperature_low_tasmota']
```
#### Additional Resources
Beyond these examples, when creating your own configuration, you'll probably find
the [built-in configurations](https://github.com/fmtr/haco/tree/release/haco/configs) (especially
the [`development` config](https://github.com/fmtr/haco/tree/release/haco/configs/development.py)) useful.
Raw data
{
"_id": null,
"home_page": "https://fmtr.link/haco",
"name": "haco",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "homeassistant controls python tasmota",
"author": "Frontmatter",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/10/83/6f7e59eb28b2975efda482d5d7807d0c57890124c86c8d21f2906370b5da/haco-0.0.25.tar.gz",
"platform": null,
"description": "# `haco` Home Assistant Control Objects\n\n`haco` is a Home Assistant Add-On, and associated Tasmota daemon written in Berry, to greatly simplify the process of\nexposing Home\nAssistant controls (e.g. Pull-down Lists, Number Sliders, Sensors, etc.) from a Tasmota device - and handling the\ncommunication between both sides.\n\nUsing `haco` to expose, for example, a \"Restart Tasmota\" button to Home Assistant is as simple as writing the following\nPython code:\n\n```py\nfrom haco import Button, Tasmota\n\nrestart = Button('Restart Tasmota', icon='restart')\n\n\n@restart.callback()\ndef ha(value) -> Tasmota[str, 'tasmota.cmd(\"restart 1\")']:\n return value \n```\n\nA fully functional restart button will now appear associated with the device in Home Assistant:\n\n<img alt=\"Restart Button\" height=50% src=\"https://raw.githubusercontent.com/fmtr/haco/release/assets/restart_button.png\" width=50%/>\n\nOr, more practically, a cookbook pull-down menu, for a Tuya air fryer, might look like this:\n\n```py\nOPTIONS = ['Default', 'Fries', 'Shrimp', 'Pizza', 'Chicken', 'Fish', 'Steak', 'Cake', 'Bacon', 'Preheat', 'Custom']\n\ncookbook = Select('Cookbook', options=OPTIONS, icon='chef-hat')\n\n\n@cookbook.callback()\ndef ha(value: str) -> Tasmota[int, tuya.send(4, 3)]:\n return OPTIONS.index(value)\n\n\n@cookbook.callback(trigger=tuya.received(4, 3))\ndef tasmota(value: int):\n return OPTIONS[value]\n```\n\n<img alt=\"Air Fryer Cookbook\" height=50% src=\"https://raw.githubusercontent.com/fmtr/haco/release/assets/air_fryer_cookbook.png\" width=50%/>\n\n## Do I Need This? Can't I Do this with Native Tasmota?\n\nYou certainly can.\n\nBut in my experience, the process is so fiddly, error-prone and hard to maintain that it's enough to\ndeter the casual user (as I am) entirely. Plus, sharing your configuration, once you've finally got it working, can mean\ncomplex step-by-step guides, setting up triggers, finding MAC addresses and topics (in Tasmota) - and numerous\nBlueprints, Helpers and Templates (on the Home Assistant side).\n\nYou can see how much work creating such guides involves by seeing how it\nwas [heroically undertaken by Blakadder](https://blakadder.com/proscenic-in-home-assistant/), as\ncompared with\nthe [full `haco`-based equivalent](https://github.com/fmtr/haco/blob/release/haco/configs/proscenic_t21.py).\n\nWith `haco`, on the other hand, the thorny parts of the initial setup are abstracted away and your final configuration\ncan often be shared via a single script. Below is a list of some of the tasks that `haco`\nhandles for you:\n\n* Announcing the entity via MQTT to Home Assistant\n* Generating MQTT/HA-friendly unique IDs\n* Associating the entity with its parent device\n* Subscribing and publishing to the relevant MQTT topics\n* Managing the relevant Tasmota rules\n* Appropriate serialization of data\n* Translating Home Assistant messages to their to appropriate Berry data types, and vice versa\n\n## Pre-Release\n\n:warning: This library is currently in a pre-release state. The configuration format is likely to change, and\nonly `Sensor`, `Select`, `Button`, `Number`, `BinarySensor`, `Switch`, `Text`, `Update`, `Fan`\nand `Climate` entities are currently implemented.\n\n## Installation\n\nInstallation involves installing two parts: the Tasmota daemon and the Home Assistant Add-On. Both are fairly simple.\n\n### Tasmota\n\nI'd advise first using a guinea pig Tasmota device to get `haco` up and running. The device needs to have MQTT\nconnected and be available to Home Assistant (i.e. showing up\nin [the Devices section](https://my.home-assistant.io/redirect/devices/)).\n\nOnce your test device is ready, with a recent (12.5+) version of Tasmota, simply paste the following into your Tasmota\nBerry Script Console:\n\n```be\n{\"download\":tasmota.urlfetch('https://fmtr.link/haco/tapp','haco.tapp'), \"restart\":tasmota.cmd(\"restart 1\")}\n```\n\nYou should see output like `{'restart': {'Restart': 'Restarting'}, 'download': 200}` and the device will restart.\n\nOnce the device restarts, you should see the following among your Tasmota startup logs (in the regular console, not the\nBerry one):\n\n```\nHACO: The haco daemon has started. Hostname: tasmota-test, MAC: 04:74:77:9B:CB:CC. Listening for configuration...\n```\n\n#### Older Tasmota Versions\n\nWith older Tasmota versions, download the [`haco.tapp` file](https://fmtr.link/haco/tapp) on a desktop\ncomputer,\nupload it to your device and restart manually.\n\n### Home Assistant\n\nYou can now install the Home Assistant Add-On:\n\n[](https://fmtr.link/haco/add-on)\n\nOnce the Add-On is installed, click into its Configuration tab and you'll see a setting called `assignments`:\n\n```yaml\n- config: null\n identifier: null\n```\n\n#### Assigning a configuration module to a device\n\nNow we're ready to assign a configuration module to our Tasmota device. For now, we can use a built-in test\nmodule `test`. The `identifer` value should be the hostname (or MAC) of your Tasmota device. So for our example it\nshould look like this:\n\n```yaml\n- config: test\n identifier: tasmota-test # Hostname of Tasmota device\n```\n\nSaving the Configuration will restart the Add-On. After the restart, you should see the following in the Add-On logs:\n\n```\nDevice \"Tasmota Test Device\" successfully configured. Hostname: tasmota-test MAC: 04:74:77:9B:CB:CC.\n```\n\nIn Home Assistant, find the device in [the Devices section](https://my.home-assistant.io/redirect/devices/). You should\nnow see a test Select (pulldown) control called \"Greeter\".\n\n<img alt=\"WebLog Select\" height=50% src=\"https://raw.githubusercontent.com/fmtr/haco/release/assets/greeter_select.png\" width=50%/>\n\nSelecting the greetings from the pulldown, you should see them appear in your Tasmota Berry console, e.g.\n\n```console\nhaco says: Hello World!\n```\n\nThis means `haco` is set up and working properly. Good! You can now use `haco` to assign configuration modules to your\nTasmota devices.\n\n## Configuration Modules\n\nConfiguration modules are a little like drivers, that tell `haco` how to communicate with a Tasmota device, what\ncontrols to expose to Home Assistant, etc.\n\nSo far we've only used the `test` configuration module, that exposed the Greeter pulldown, but to control\nreal-world devices, you'll need to assign them to a module written specifically for that device. There are currently two\ntypes of modules,\nBuilt-In and User-Defined.\n\nWhichever type you use, assigning them to a device is done as we saw above.\n\n### Built-In Modules\n\n`haco` ships with a small number of built-in configurations. These can be found in\nthe [configs directory](https://github.com/fmtr/haco/blob/release/haco/configs) in this repo. But in the likely event\nthat your device hasn't already\nbeen added, you'll need to define your own.\n\n:information_source: The aim is to expand the number of built-in configurations over time. So if you define your own (\nsee below), please submit it to this repo as a Pull Request, or raise an Issue linking to your code!\n\n### Creating Your Own Configuration Module\n\n#### General module structure\n\nA configuration module is, ultimately, just a typical Python module. In this case, they contain definitions from one or\nmore `Control` objects. Each control definition involves two things:\n\n* The control object assigned to a variable, e.g. `temperature_sensor=Sensor(...)`\n* Any required callback functions for the control, e.g. `@temperature_sensor.callback(...)<function>`\n\n#### Location\n\nUser-Defined modules should be added to the `/config/haco` directory in Home Assistant, with a `.py` extension,\ne.g. `/config/haco/my_config.py`.\n\n#### Defining controls\n\nHere are a couple of simple examples to help get you started defining your own configuration module.\n\n##### Tasmota-Only Controls\n\nFirst, let's define a Tasmota-only sensor to report how much free memory there is on the Tasmota device. This sensor\nis \"Tasmota-Only\" as it only handles values sent _from_ Tasmota (and sends nothing back from Home Assistant).\n\n```python\nfrom haco import Sensor\n\nmemory = Sensor('Memory Free', icon='memory', uom=Sensor.UOM.DATA_KILOBYTES, uom_type=Sensor.UOM_TYPE.DATA_SIZE)\n\n\n@memory.callback(trigger='Tele#Heap')\ndef tasmota(value: int):\n return value\n\n```\n\n<img alt=\"Memory Sensor\" height=50% src=\"https://raw.githubusercontent.com/fmtr/haco/release/assets/memory_sensor.png\" width=50%/>\n\nLet's break this control definition down into the control object, the callback decorator, and the callback itself.\n\n###### The control object\n\nFirst we initialise a `Sensor` control object, assign it to a variable called `memory`, give it a relevant icon, unit of\nmeasure and type.\n\n###### The callback decorator\n\nThe callback decorator `@memory.callback(trigger='Tele#Heap')` specifies a Tasmota trigger, the values from which will\nbe sent to the callback function.\nThis specific trigger, `Tele#Heap`, fires whenever telemetry data is returned from Tasmota and, specifically, returns\nthe `Heap` field, which contains the free\nmemory in kilobytes.\n\n:warning: Tasmota callbacks _must_ have such a `trigger` specified in this decorator.\n\n###### The callback\n\nNote that the callback function is named `tasmota`. This name is important as it tells `haco` that this callback\nhandles values _from_ Tasmota.\n\nThe response from the trigger we specified in our callback decorator above gets fed into our callback as the `value`\nargument. The (optional) type annotation for the `value` argument (the `int`) tells `haco` what data type to expect from\nTasmota, and type conversion gets done automatically.\n\nThe return value from the function is what will be returned to Home Assistant as the value for the sensor.\n\n:information_source: Note that our callback function does not actually _do_ anything with our `value` other than return\nit. But if we wanted to (for example) convert the value from kilobytes to bytes, this is where we'd do it,\nwith `return value*1000`.\n\n:information_source: You can find the list of available units of measure [here](../../blob/release/haco/data/uom.py) and\ntypes [here](../../blob/main/haco/data/type_sensor.py).\n\n#### Home Assistant-Only Controls\n\nMoving on to the opposite type of control, that is one that only handles values _from_ Home Assistant. The Button\ncontrol does\nexactly this, as it is triggered by being pressing in Home Assistant, but Tasmota returns nothing to acknowledge that\npress.\n\nHere is how to define a `Button` control that, when pressed, restarts the Tasmota device.\n\n```py\nfrom haco import Button, Tasmota\n\nrestart = Button('Restart Tasmota', icon='restart')\n\n\n@restart.callback()\ndef ha(value) -> Tasmota[str, 'tasmota.cmd(\"restart 1\")']:\n return value\n\n```\n\nIn the case we define a `Button` control, and again use our decorator to add a callback to handle values _from_ Home\nAssistant, which must therefore be named `ha`.\n\n###### The `Tasmota` Type Annotation\n\nThe most notable difference with a Home Assistant (`ha`) callback is the `Tasmota` return type annotation. This takes\ntwo arguments, `Tasmota[<type>,<berry_expression>]`. The\nfirst argument is the type returned by the callback function, as per usual, and which again lets `haco` convert the\nreturn value accordingly.\n\nThe second argument is an expression that defines _what to do_ on the Tasmota side when the button is pressed. In this\ncase, this\nis just a Berry expression to restart Tasmota.\n\n:warning: Note that Home Assistant callbacks _must_ have such a `Tasmota` type annotation for their return type.\n\n:information_source: In the example above, the `value` argument received and returned by our callback is not actually\nused by the Berry expression side. Home Assistant just sends a constant string (`PRESS`) when the button is pressed, so\nthe actual content of\nthe `value` argument is not important.\n\n#### Two-Way Controls\n\nTwo-way controls need to handle values from _both_ Home Assistant and from Tasmota, and hence need both the callbacks\ntypes - `ha` and `tasmota` we've seen above.\n\nHere is an example two-way `Select` (pulldown menu) object. It allows setting the Tasmota `WebLog` console debugging\nlevel from Home Assistant, and also reflects any changes to that setting made on the Tasmota side.\n\n```python\nfrom haco import Select, Tasmota\n\nLOG_LEVELS = [\"None\", \"Error\", \"Info\", \"Debug\", \"Debug More\"]\n\nweblog = Select('WebLog Level', icon='console', options=LOG_LEVELS)\n\n\n@weblog.callback()\ndef ha(value) -> Tasmota[str, 'tasmota.cmd(\"WebLog \"+value)']:\n return LOG_LEVELS.index(value)\n\n\n@weblog.callback(trigger='WebLog')\ndef tasmota(value: int):\n return LOG_LEVELS[value]\n```\n\nThe above is very similar to what we have already seen.\n\nThe `ha` callback takes friendly names (e.g. `Error`, `Info`) selected by the user in Home Assistant, and returns them\nas their corresponding number values (`WebLog 1`, `WebLog2`) used by Tasmota.\n\nThe `tasmota` callback, naturally enough, does the exact opposite, returning the string names to Home Assistant whenever\nthe `WebLog` command is used on the Tasmota side.\n\n<img alt=\"WebLog Select\" height=50% src=\"https://raw.githubusercontent.com/fmtr/haco/release/assets/weblog_select.png\" width=50%/>\n\n#### Debugging Your Configuration\n\nWhen you first assign a new configuration to a device, keep an eye on the Add-On logs for any errors. You'll see a\ntypical Python stack trace if anything goes wrong.\n\n:warning: Each time you edit your configuration module (`.py` file), you'll need to restart the Add-On. Hot\nis reloading not yet supported.\n\n#### Additional Capabilities\n\nMore complex device controls (e.g. `Climate`, `Fan`) have additional capabilities beyond a single value requiting\nTasmota/Home Assistant\ncallbacks. Adding callbacks for these extended capabilities is done similarly to the above, only the callbacks need\nto include the name of the capability. So if you want to add callbacks around setting the `target_humidity` of\na `Climate` control, you'd need to call your callbacks `target_humidity_tasmota` and `target_humidity_ha`, etc.\n\nA full schema of these names will appear in subsequent documentation. But you can find example implementations for most\ncontrols in the [built-in `development` config](https://github.com/fmtr/haco/tree/release/haco/configs/development.py).\n\nAnway, if you get the names wrong, you'll see an error like this in your Add-On logs:\n\n```\nValueError: Callback function name \"set_mode_ha\" is not valid for control \"Climate\". Must be one of: ['action_tasmota', 'current_humidity_tasmota', 'current_temperature_tasmota', 'mode_ha', 'mode_tasmota', 'preset_mode_ha', 'preset_mode_tasmota', 'swing_mode_ha', 'swing_mode_tasmota', 'target_humidity_ha', 'target_humidity_tasmota', 'target_temperature_ha', 'target_temperature_tasmota', 'temperature_high_ha', 'temperature_high_tasmota', 'temperature_low_ha', 'temperature_low_tasmota']\n```\n\n#### Additional Resources\n\nBeyond these examples, when creating your own configuration, you'll probably find\nthe [built-in configurations](https://github.com/fmtr/haco/tree/release/haco/configs) (especially\nthe [`development` config](https://github.com/fmtr/haco/tree/release/haco/configs/development.py)) useful.\n\n\n",
"bugtrack_url": null,
"license": "Copyright \u00a9 2023 Frontmatter. All rights reserved.",
"summary": "Home Assistant Control Objects",
"version": "0.0.25",
"project_urls": {
"Homepage": "https://fmtr.link/haco"
},
"split_keywords": [
"homeassistant",
"controls",
"python",
"tasmota"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "01ede14a29631731d8511853fe5308cdfb151337c30528a9db9cd4a74d3853a9",
"md5": "4748e3c51784f15c1f3749ce9d895668",
"sha256": "ec15c0f3370c90aa0281147c53e8a0a94b4bfecdae1bb07a139cec793695b6f7"
},
"downloads": -1,
"filename": "haco-0.0.25-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4748e3c51784f15c1f3749ce9d895668",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 33482,
"upload_time": "2024-03-27T14:25:52",
"upload_time_iso_8601": "2024-03-27T14:25:52.542393Z",
"url": "https://files.pythonhosted.org/packages/01/ed/e14a29631731d8511853fe5308cdfb151337c30528a9db9cd4a74d3853a9/haco-0.0.25-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "10836f7e59eb28b2975efda482d5d7807d0c57890124c86c8d21f2906370b5da",
"md5": "6a3ed1463f1645e30ca0c956b74a0493",
"sha256": "536788e39b6ad789d9a68dc89e1d6112206d6f699ea6d1e129ebc5008c9b9116"
},
"downloads": -1,
"filename": "haco-0.0.25.tar.gz",
"has_sig": false,
"md5_digest": "6a3ed1463f1645e30ca0c956b74a0493",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 31059,
"upload_time": "2024-03-27T14:25:53",
"upload_time_iso_8601": "2024-03-27T14:25:53.766282Z",
"url": "https://files.pythonhosted.org/packages/10/83/6f7e59eb28b2975efda482d5d7807d0c57890124c86c8d21f2906370b5da/haco-0.0.25.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-27 14:25:53",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "haco"
}
JSON