Beginner docs (cheat sheet perhaps?) for templating

Configuration
,
1

I’m trying to write a simple function, and it seems that I fail to understand the data/class model of hass. My specific use case is not very relevant (for those who really wanna know I’m trying to enumerate all zigbee and zwave devices with battery and get their battery levels).

The issue I’m running into: I haven’t programmed much in whatever contraption hassio is operating in. I understand there’s jinja2 + some hass-relates objects. I have no idea:

a) what base objects I could use to enumerate devices. I know there’s “states”, is that all?, and:

b) what are the operations available on them. I understand there’s pipe-notation where you get the collections through filters, but is there any doc or better yet cheat-sheet on what those filters are.

I keep trying to monkey-copy the snippets I’m seeing on various internet sources, or whatever heresy chatgpt writes for me, which isn’t reliable in the slightest. it would really help if there was a single guide for writing templates, which has everything in it

Please share what was your source of truth when you started writing the templates

2 Likes
2

Beyond the official Jinja docs, there’s the Jinja for Ninjas tutorial. However, it is a bit old… so more recently added functions are not included. We also have a number of Template related articles in the Cookbook.

The most up-to-date source for HA-specific template info are the HA Templating docs.

HA’s implementation of Jinja also allows a number of basic Python functions, but those are considered outside the scope of the Home Assistant documentation.

3 Likes
3

@Didgeridrew beat me to it, but there are some “cheat sheets” on specific areas of templating - handling time, for example. Have a look in the Home Assistant Cook Book.

As far as batteries go, you might be interested in Battery Notes:

…and the Battery State Card:

1 Like
4

@Didgeridrew: Great, thank you!

Maybe a bit OT but is there a similar cookbook for HA integrations?

I’m asking because there’s an issue with the Mitsubishi HVAC integration and the maintainer seems to have left. I’d like to fix it myself, but it feels like it’s a well-kept secret how things work behind the scenes in the HA Core, like how the data and class models are structured and so on.

5

Developer Docs

If you need help with development, the Home Assistant Discord server tends to be a better place than these forums.

6

Thanks for the link! :pray:

Just a personal reflection after reading the “Home Assistant Developer Docs” several times. The document structure with the overview is super simplified, followed by just a couple of links under “Popular Topics” and “Source Code.” The same goes for the “Architecture Overview,” which only has a few simple diagrams.

Neither says anything about the data or class model or how everything fits together. How on earth are you supposed to learn to work with HA integrations if that’s all there is?

Anyone have any good ideas? :smiley:

7

Templating docs have one flaw: instead of telling you how to discover the data structures they just give some examples and… what next? Take integrations for example:

integration_entities(integration) returns a list of entities that are associated with a given integration, such as hue or zwave_js.

okay, great, I actually wanted to get devices with integration to zwave, so I presume zwave_js is it. Went to template editor, plugged in {{ integration_entities('zwave_js') }}, works!

okay, what next, how do I do zigbee? Lets try {{ integration_entities('zigbee') }}. Nope, empty array, ‘Zigbee’? Neither. How am I supposed to know what to use? Okay lets try {{ integrations() }}. Nope. How am I supposed to figure that out, HOW

so I went back to integrations in UI and looked at URL. It is zha. What the… This is impossible to guess. And if it’s impossible to guess, there should be some way for me to find out. Does anybody actually know? Is there a way to dump the whole structure into JSON or something like that?

8

“Impossible” is a bit much… and why are you guessing? There are multiple integrations that can be used to get devices using the Zigbee protocol into HA, so “zigbee” would be as likely as not to be the wrong integration ID.

ZHA is the identifier used in a number of places:

I am not a dev and I am unaware of any way to dump the information you are interested in. I do know that the integration IDs in use in your HA instance can be seen in the Repairs settings by selecting “Integration Startup Times” from the expansion menu. As far as I can tell, those IDs are the same as their corresponding directory name in the core components directory.

I haven’t checked if it’s 100% accurate, but you can get the integration IDs from your entities using the following in the Template tool:

{% set ns = namespace(y=[]) %}
{% for x in states|map(attribute='entity_id') if config_entry_id(x) is not none %}
{% set ns.y = (ns.y + [config_entry_attr(config_entry_id(x), 'domain')]) | unique | list %}
{% endfor %}
{{ ns.y | sort }}
9

If not already done, have a look at Smart Home Junkie on YouTube. Ed has 6 or 7 Jinja templating video’s which start from the basics. I found those very useful.

1 Like