Better developer documentation required for noobs

Hi guys,
can we better the developers documentation. It needs to be a little more spread out documenting the possible options for each value default false is not very clear what happens when set to false and what happens when set to true. Options like icon what part of the tile is affected by this? Entity_Picture what does it affect and what are the specs eg (jpg X by Y). The documentation appears to be missing quite a few classes.

Also more examples would assist greatly. how can i change the switch type from toggle to up down is there a multi select switch type for things like a fan speed selector where its not simply On/Off but Off/Low/Med/Hi.

Can we spend a little more time updating the docs for newbies rather than creating them for the already master reference manual i’m happy to assist if i can ask some one the questions.

Sorry if i sound like a winger but i like this product and can see it has great potential but am frustrated at the lack of resources.


1 Like

Name a page that needs improvement and let’s work on it.

1 Like

lets start by looking at the layout after watching the video from PYCON by Paulus Schoutsen things make more sense.

But in his example he shows a sensor first add the abstract base class

from homeassistant.helpers.entity import entity

simple i can look this up in the Home Assistant Documentation release 0.83.3 and i can see it has a lot of properties and methods but they are all mixed together.

next he sets the name of this entity

def name(self);
return ‘Temperature’

That’s simple to understand but next he sets a unit of measurement
def unit_of_measurement(self);

but this looks to have been imported from homeassistant.const but there is no list of the constants i can chose from not even a reference in the documentation to a table listing them.

the same in his second example

he implements a switch using the ToggleEntity class but this is difficult to find in the documentation as it appears to be a follow on from the previous class.

i would expect when looking at the documentation to see a heading (like there is) showing we are looking at homeassistant.helpers.entity but this should be followed with sub headings entity, toggleentity, then each of these in a subsection with clear headdings and then sections listing properties and methods as demonstrated below this way i can see clearly that the homeassistant,helpers.entity has 2 classes and a breif description of what they are then i can see the section for more details



  1. Entity
    An abstract class for home assistant entities

  2. ToggleEntity
    An abstract class for entities that can be turned on and off

  1. Entity
    An abstract class for home assistant entities

Returns True if entity is available

sets the icon to be used in the front end (refer to diagram XX)
returns the currently set icon to be used in the front end

Note: the icon should be the icon url from
example: or a local file reference /icons/lamp.ico referenced from the homeassistant install folder

Return the name of the entity

Set the unit of measurement for this entity
values should be selected from the homeassistant.const list in table 1 of apendix A

async_device_update(warning = True)
Process ‘update’ or ‘async_update’ from entity.
Calling this method with warning set to True will cause the update or async_update method of this entity to be executed.

  1. Toggle Entity
    This Class implements all properties and methods of the entities class and the following
    is_on return True if entity is on

Toggle the entity

Turn the entity on

Turn the entity off

1 Like