home-assistant / developers.home-assistant Goto Github PK
View Code? Open in Web Editor NEWDevelopers website for Home Assistant.
Home Page: https://developers.home-assistant.io
License: Other
Developers website for Home Assistant.
Home Page: https://developers.home-assistant.io
License: Other
Firstly, everything about configuration variables description IMO should be collected in one place (here, I suggest) and be referenced, where needed.
Secondly, there are some things that writers interpret differently. I see a lot of various formattings in the "components" section.
This is how I interpret the documentation (although example Template sensor is formatted different way):
map
type is a YAML mapping, where all key names are definite:
position: latitude: 12.345 longitude: 32.123position (map) (Required) Your position.
latitude (string) (Required) Latitude.
longitude (string) (Required) Longitude.
(string is because float is not allowed)
list
type is a YAML mapping, containing indefenite amount of similar objects with indefenite key names corresponding to them:
Here Paul
and Sarah
are indefinite keys.
my_friends: Paul: second_name: "Johnson" age: 32 Sarah: second_name: "Connor" age: 59my_friends (list) (Optional) Your friends.
second_name (string) (Required) Your friend's second name.
age (int) (Required) Your friend's age.
The documentation says nothing about YAML lists
prime_numbers:
- 23
- 7
- 13
This leads to confusion. For example, repeat
variable here is described as (int | list):
repeat: - 15 - 30 - 60
Here is another example to help you understand my point:
key_name:
- name: Dave
age: 21
city: New York
- name: Nathan
age: 35
city: Washington
Also, the exampled template sensor has a variable with device_class
type, which is not listed in the standard.
I tried to add a custom card to the UI, following the instructions here.
In the section Referencing your new card, there is no mention, where to put Lovelace UI configuration to load the custom card. User, like me, may assume it's in the main configuration.yaml
file.
As I dug deeper, I found out the Lovelace YAML mode docs and I was able to load my custom card after creating the file ui-lovelace.yaml
and enabling it in the UI using:
lovelace:
mode: yaml
However, it's not clear if this is the only way to load custom cards or if there are other (better) ways which don't require to write the entire UI configuration in YAML.
I created this issue, because other people could be facing similar problems and I think the page should be updated. I can update the page, if you advise what should be put there.
move[bot] commented on Oct 5, 2018, 8:27 PM UTC:
Krastanov commented on Oct 5, 2018, 2:52 PM UTC:
Home Assistant release with the issue: 0.79.3
Component/platform: Developer documentation
Description of problem:
There seems to be at least 3 styles in use for the schemas when listing multiple components, and it is not clear whether some of them are deprecated or advised against.
There is the style used by sensor/command_line
, namely:
sensor:
- platform: command_line
command: "command A"
- platform: command_line
command: "command B"
This is referred to as "style 1" in your style guide
There is the style used by switch/command_line
, namely:
switch:
- platform: command_line
switches:
switch_A: ...
switch_B: ...
This style is not present in the style guide.
Then there is style 2 from your style guide:
media_player livingroom:
platform: mpd
server: IP_ADDRESS
media_player kitchen:
platform: plex
Are all 3 of these styles equally "official"? Should any of them be avoided? Or is it just a question of taste?
This issue was moved by fabaff from home-assistant/home-assistant#17165.
This issue was moved by fabaff from home-assistant/home-assistant.io#6544.
I've realised that CoreDNS (hassio_dns) isn't mentioned anywhere in the architecture chart or information.
I think this would be a good addition as not many people seem to be aware of it at all.
When building the development environment using https://developers.home-assistant.io/docs/development_environment/#setting-up-virtual-environment
Building wheels for collected packages: pyyaml, distlib
Running setup.py bdist_wheel for pyyaml ... error
Complete output from command /mnt/c/Users/daz/core/venv/bin/python3 -u -c "import setuptools, tokenize;__file__='/tmp/pip-install-b0wxy1w6/pyyaml/setup.py';f=getattr(tokenize, 'open', open)(__file__);code=f.read().replace('\r\n', '\n');f.close();exec(compile(code, __file__, 'exec'))" bdist_wheel -d /tmp/pip-wheel-gx4luy4z --python-tag cp37:
usage: -c [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
or: -c --help [cmd1 cmd2 ...]
or: -c --help-commands
or: -c cmd --help
error: invalid command 'bdist_wheel'
Forum post Problems with bdist_wheel when following HA Dev guide
The configuration docs page (https://developers.home-assistant.io/docs/en/documentation_create_page.html#configuration) shows the allowed types to be:
string, int, time, template or map
The example also shows a type list for the monitored_conditions key.
I'm not sure if list should be added to the allowed types (and how it's used explained), or if the example should be using map instead.
Hello.
Is it actual?
https://github.com/home-assistant/developers.home-assistant/edit/master/docs/frontend_creating_custom_ui.md
Since polymer3 shouldn't we add js files instead of html?
The "Lokalise translation workflow documents" link on the translations page is currently broken. If someone can find the new URL, this would be an easy fix and could possibly be a good Hacktoberfest task.
Current URL: https://docs.lokalise.co/category/iOzEuQPS53-for-team-leads-and-translators
This is with regards to docs/creating_integration_manifest.md
What is the correct way to reference a required library that is already used within Home Assistant without causing a conflict? The current solution is to not reference a version number but that a) goes against the documentation and b) assumes versions maintain compatibility.
See sermayoral/ha-samsungtv-encrypted#27
Scrape (a core part of HA) is using beautifulsoup4==4.9.0
ha-samsungtv-encrypted is using beautifulsoup4==4.6.0 (for whatever reason)
The Windows dev environment instructions need to be updated to only talk about the Linux subsystem and need some more handholding than just the handful of links that we have now.
The video on the front page requires you to play it on the YouTube website and will not allow you to play it in the embedded player on the website. this is not a huge issue but it does not seem right from a user experience point of view. Is it possible to ask the owner to allow for playback from external websites or get your own copy of the video?
The docs say
All API calls have to be accompanied by the header
X-HA-Access: YOUR_PASSWORD
[...]
yet the example directly following does not use that header, but instead has a Bearer
authorization header:
$ curl -X GET \
-H "Authorization: Bearer ABCDEFGH" \
-H "Content-Type: application/json" \
http://IP_ADDRESS:8123/ENDPOINT
It's not very clear which is the right way.
In addition, the YOUR_PASSWORD
bit refers to https://www.home-assistant.io/components/http/ which says
Where possible you should use a long lasting access token instead of this.
With the move of the Development content to developers.home-assistant the documentation about writing the component or platform documentation for main website was left behind for the initial roll-out.
Suggestion move to "Misc" and create a new section.
@starbuck93 commented on Jul 20, 2018, 7:55 PM UTC:
Home Assistant release with the issue:
N/A
Last working Home Assistant release (if known):
N/A
Operating environment (Hass.io/Docker/Windows/etc.):
N/A
Component/platform:
N/A
Description of problem:
http://dev-docs.home-assistant.io/ is throwing a CloudFlare Error
Problem-relevant configuration.yaml
entries and (fill out even if it seems unimportant):
Traceback (if applicable):
Additional information:
I was digging through some API documentation and ran into this a few times before I confirmed it wasn't just me by asking on Discord.
This issue was moved by awarecan from home-assistant/home-assistant#15581.
Many of our entity docs are incomplete! I'm using this issue to track the work remaining to flush out our entity documentation. Please help by picking one up and writing the docs!
Using cover as the standard:
When using the instructions to set up Ubuntu in WSL it is not possible to install all dependencies with pip3 install -r requirements_test_all.txt -c homeassistant/package_constraints.txt
when using Ubuntu18.04.
This is due to the fact that PyAV requires ffmpeg in a version greater than 4 and Ubuntu 18.04 only provides version 3.
When using Ubuntu 20.04 under WSL everything works when I use Python3.8 instead of Python3.7:
sudo apt install python3-pip python3.8-dev python3.8-venv python-wheel-common
The instructions below are extremely unclear and it is unknown what steps to take. See recent conversations on this outlining that every step of these instructions are non-sensical, out of date, and/or do not reflect any steps or methods one would use to follow them. See: https://community.home-assistant.io/t/debugging-the-home-assistant-operating-system/197829
"You need set the dev mode on supervisor and enable debug with options. You need also install the Remote debug Add-on from Developer Repository to expose the debug port to Host." ????
The re enabled search has not been recrawled yet but redirects seem to be handling everything well. However, using the search gives duplicate hits for some items as on the previous site (which had versioning) it found the current (/docs/en/*
) version and the next (docs/en/next/*
). I'll request a recrawl now
This page: https://developers.home-assistant.io/docs/en/documentation_create_page.html outputs the {% raw %} and {% endraw %} in the Configuration and Embedding Code sections.
I'm not sure if they're not necessary or not being parsed correctly.
Hi,
I would like to help updating the documentation, but I am confused as to how to.
In the current README.md
file, it is written that the documentation is done with Docusaurus + NodeJS + Yarn.
But in the current documentation section of the doc (documentation_index.md
), it is written that the documentation is done with Jekyll + Ruby.
Where is the truth?
We still have a swagger file in the main repo. We never used that file as far as I remember.
I think that we should remove it if we are not going to use it. It's probably out-dated as nobody touched it in the last year.
At this page:
Then you can work on the documentation:
- Fork home-assistant.io git repository.
- Create/edit/update a page in the directory
source/_components/
for your platform/component.
Should it only mention source/_components/
? There are other documentation sections like /source/_docs
.
The rest of the page seems to be a little outdated too.
Hi all,
Currently I am doing Native App Integration with Android in Kotlin.
I have injected the Get Access Token when WebView start to load mentioned in documentation (https://developers.home-assistant.io/docs/en/frontend_external_auth), as per below:
webview.evaluateJavascript("window.externalAuthSetToken(true, {\n" +
" \"access_token\": \"" + long_live_access_token + "\",\n" +
" \"expires_in\": 60\n" +
"});",
null)
Normally, it able to login Home Assistant successfully with this Javascript injection.
However, sometimes it would not success due to unknown reason, causing following error:
Is there any way to track the External Authentication login status, so that I could prompt user to re-login again?
Reference: #225
Thanks.
If followed the "Debugging Hass.io documentation" to setup SSH (by adding a authorized_keys file to the boot partition). But it seems that this method is no longer working.
Booting with a USB stick with named CONFIG containing the authorized_keys file did work.
Is this a bug in the documentation, or should this method also still work?
In both cases adding the USB method would be nice since its a more simple way of adding the file.
If someone can confirm what methods are working I would be happy to help out and update the docs myself!
As a developer I want documentation files that are present in the published documentation website to be part of the actual documentation project, to prevent google from leading me to outdated pages.
homeassistant.remote
API is still online and UI leads users to believe it is part of 0.91.1This file should not be hosted online since it is not part of the current product. It currently is indexed by google.
Possibly, the underlying issue is that releases of the documentation do not delete legacy files.
docs/external_api_rest_python.md
was deleted in 3e09850homeassistant.remote
was removed in home-assistant/core#16099In developers.home-assistant/docs/config_entries_config_flow_handler.md discovery
is listed as DEPRECATED. Should this be DEPRECIATED?
| discovery
| DEPRECATED Invoked if your integration has been discovered by the discovery integration.
My logs are getting spammed with the following warning:
WARNING (MainThread) [homeassistant.components.camera] The websocket command 'camera_thumbnail' has been deprecated.
I see where this is happening:
https://github.com/home-assistant/core/pull/32473/files
But the developer documentation doesn't reflect this change:
https://developers.home-assistant.io/docs/api/websocket/#fetching-camera-thumbnails
Home Assistant Core release with the issue:
0.111.2
Last working Home Assistant Core release (if known):
New integration
Operating environment (Home Assistant/Supervised/Docker/venv):
docker-ce-19.03.10-3.el7.x86_64
Integration causing this issue:
camera
Link to integration documentation on our website:
https://www.home-assistant.io/integrations/camera/
https://developers.home-assistant.io/docs/api/websocket/#fetching-camera-thumbnails
configuration.yaml
cameras:
- entity: camera.front_door
motion_entity: binary_sensor.motion_front_door
- entity: camera.driveway
motion_entity: binary_sensor.motion_driveway
- entity: camera.backyard
motion_entity: binary_sensor.motion_backyard
- entity: camera.back_corner
motion_entity: binary_sensor.motion_back_corner
thumb_interval: 10
type: 'custom:surveillance-card'
update_interval: 1
WARNING (MainThread) [homeassistant.components.camera] The websocket command 'camera_thumbnail' has been deprecated.
Hi,
I'm at odds figuring out how to implement hvac_action()
and hvac_mode
(and corresponding actions and modes lists). As I see it right now, the state
of an entity is defined solely by the hvac_mode()
.. but it is the action
that has CURRENT_
constants, which makes me think that action
should have defined the state instead.
https://developers.home-assistant.io/docs/en/entity_climate.html
The docs here simply state that the action should be the currently operating action (ie. off/idle when the temperature is reached) - but action seems to have no influence on the state, and thereby the display on the Thermostat card.
I've tried the following, f.ex., as I thought this was wanted:
mode
is set to ´HVAC_MODE_HEAT`, as the HVAC system only supports heating/not heatingaction
is set to CURRENT_HVAC_OFF
, as the temperature has been reached.actions
is set to OFF/HEAT and modes
is set to just HEATBut with those values, the thermostat card (and state) show the device as heating.
So.
CURRENT_HVAC_IDLE
vs. CURRENT_HVAC_OFF
be described?Related: dave-code-ruiz/uhomeuponor#6
Mike.
Allowed entries:
string
,int
,time
,template
ormap
(for a list of entries).
Then it gives the template
sensor as an example. There we can unlisted types are used.
entity_id: description: A list of entity IDs so the sensor only reacts to state changes of these entities. This can be used if the automatic analysis fails to find all relevant entities. required: false type: string, list
device_class: description: The type/class of the sensor to set the icon in the frontend. required: false type: device_class
This subject is also touched there and there it lists
string
,boolean
,integer
,list
There are some pages with an incorrect sidebar label. Instead they show Introduction
.
https://developers.home-assistant.io/docs/en/configuration_yaml_index.html
---
title: "Integration Configuration via YAML"
sidebar_label: Configuration via YAML
---
https://developers.home-assistant.io/docs/en/integration_quality_scale_index.html
---
title: "Integration Quality Scale"
sidebar_label: "Integration Quality Scale"
---
Just leaving this here as a note. In the migration of the site to Docusaurus V2 we changed structure. Site should be recrawled by DocSearch by morning (UTC) and I’ll switch the search back on then
Upcoming events in developer docs have ceased after 0.116- only future HA birthdays :slight_smile: Convinent to see beta/release dates in my calendar...
Hi all,
Currently I am doing Native App WebView Integration with Android in Kotlin.
Differs with another issue (#266) that used Authenticated Webview with Long Live Access Token (LLAT), to skip HA Login Page, this time I am trying to display HA Login Page instead (Without any Javascript injection).
Expected Flow:
Load URL (http://192.168.1.100:8123/) -> Open WebView -> Load HA Login Page -> Enter HA Username & Password -> Login Successfully
Actual Flow:
Load URL (http://192.168.1.100:8123/) -> Open WebView -> Unable To Connect To Home Assistant -> Press Retry -> Enter HA Username & Password -> Login Successfully
However, sometimes it would not success due to unknown reason, causing following error:
How would it possible to trigger this error, since I am no longer inject any Javascript to this WebView?
Thanks.
would be great if someone could outline how docker builds are done at release time and how to add images.
i.e. I have a dockerfile in home-assistant-cli but no info on how to get it setup to publish to dockerhub (lack of permissions etc.)
I'm trying to register a simple webhook in my custom_component as described here: https://developers.home-assistant.io/docs/en/app_integration_sending_data.html#webhooks
But when I call it I only get a 404 Not found. Is the documentation not up to date or is it a bug?
Hi,
I followed the hello world
example in the Development 101, and contrary to what it said, the state card does not appear within main panel.
I setup my dev environment following the Set up Development Environment doc just last week.
Is the doc out of date, or is this a bug?
Home Assistant release with the issue:
0.93.0.dev0
Last working Home Assistant release (if known):
Unknown
Operating environment (Hass.io/Docker/Windows/etc.):
MacOS Mojave 10.14.4
Em
Hi all,
I would like to implement External Authentication for Android apps (Written in Kotlin).
I refer to two documentation links:
Based on this two links, I should add ?external_auth=1 to my HA url. So my url will become http://IP:8123/?external_auth=1.
After run, it become like screenshot below:
So, just to confirm, I need to execute all the following commands in my Android app so that could successfully login HA using External Authentication method?
window.externalApp.getExternalAuth({
callback: 'externalAuthSetToken'
});
// To be called by external app
window.externalAuthSetToken(true, {
"access_token": "qwere",
"expires_in": 1800
});
Or do I miss out somethings else?
Thanks.
Their is several Mixin class related to the entity, and one of them is RestoreEntity. If you don’t know it, you cannot guess it.
It would be nice to document the usage of such classes. I’m sure it will help to reduce some boilerplate.
Refer to: https://github.com/home-assistant/developers.home-assistant/blob/master/docs/hassio_addon_communication.md under section Home Assistant Core.
The line regarding the Websocket API proxy is extremely unclear and does not align with standard websocket usage.
Typically, a websocket URL begins with ws://
or wss://
. Since the proxy mentioned here begins with http://
, the actual connection and authentication are (supposedly?) completely different.
Please add additional verbiage to this section explaining how someone would actually use this proxy, and how a pure websocket call may differ from the same call passed in via the proxy endpoint.
I have created a docker environment to do my development in.
When I have attached to the container (docker container exec -it MY_CONTAINER_NAME bash
), does that mean I'm in my "Home Assistant development environment" as mentioned in the docs from e2b65a6 (https://developers.home-assistant.io/docs/creating_component_index)?
Because when I run the command python3 -m script.scaffold integration
(tried in '/', '/config', '/config/custom_components' and '/config/custom_components/MY_NEW_INTEGRATION') I only get the output Run from project root
.
Where is this 'project root'?
I think the wording is a bit confusing and inconsistent. I have below tried to compile a list of places where I found these inconsistencies. Once it is clear what the correct wording is, I could create PRs to adjust.
An entity is looked up in the registry based on a combination of the platform type (e.g., light), and the integration name (domain) (e.g. hue) and the unique ID of the entity
According to that definition this would be the entity_id: [platform type].[domain]_[unique_id]
[component].[platform]_[unique_id]
This naming is also confirmed by this architecture page.
For example, the built-in switch component is responsible for interaction with different types of switches. A platform provides support for a particular kind or brand of device. For example, a switch could use a WeMo or Orvibo platform and a light component might interact with the Hue or LIFX platform.
Now when looking here instead, it states that the first part (before the dot) is the domain
which I now think is wrong.
Then there is also entity_namespace
which apparently is being phased out though (see note here).
On the integration platform page it then suddenly refers to what I think is a component
again as domain
.
Home Assistant has various built-in integrations that abstract device types. There are lights, switches, covers, climate devices, and many more. Your integration can hook into these integrations by creating a platform. You will need a platform for each integration that you are integrating with.
To create a platform, you will need to create a file with the domain name of the integration that you are building a platform for. So if you are building a light, you will add a new file light.py to your integration folder.
domain
creeps in again:If the platform adds extra services, the format should be .. So if your integration's domain is "awesome_sauce" and you are making a light platform, you would register services under the awesome_sauce domain. Make sure that your services verify permissions.
Each integration is stored inside a directory named after the integration domain.
If your integration is going to integrate one or more devices, you will need to do this by creating a platform that interacts with an entity integration. For example, if you want to represent a light device inside Home Assistant, you will create light.py, which will contain a light platform for the light integration.
Can someone shed some light here, what the correct wording and meaning is so we can clearly document that?
I am trying to understand what after_dependencies are.
The documentation describes an 'optional dependency', but I don't know what that means (sounds like a contradiction).
Is it another integration that could be used by the current one but is not always? If so what is the intended behaviour and what is the purpose of listing it in the manifest?
A bit more clarity in the wording and maybe an example would help.
It is unclear to me how to develop on the Hass.io panel.
The documentation only covers general frontend development work.
The source for API documentation is located in the main repo.
Suggestion to move it and make it available at developers.home-assistant.
It appears that the developer docs have not been updated in a while. For example, on this page:
http://dev-docs.home-assistant.io/en/stable/api/helpers.html
the link to homeassistant.helpers.condition.and_from_config(config: Dict[str, Any], config_validation: bool = True)
shows the incorrect line reference.
The impact is that I am not confident that the dev-docs are showing me all the helper methods which are available to use.
https://github.com/home-assistant/developers.home-assistant/blob/master/docs/creating_platform_example_light.md needs updates:
The return type in setup_platform is currently a boolean. Turns out, this is not correct. I'm referencing discussion home-assistant/core#14485 (comment)
The documentation, does not fully reflect ADR007.
My understanding of the result of ADR0007 is that normal integrations should not be extending PLATFORM_SCHEMA
, but should be using CONFIG_SCHEMA
instead, at least for any integrations still allowed to use YAML configuration given ADR0010.
Yet the Platform checklist still suggests using PLATFORM_SCHEMA
, as does the the Component Checklist.
Firstly, this is work I'm happy to do but thought we should discuss in an issue first.
Currently there is no PR (or issue) template on this repo. This means sometimes there are vague PRs submitted and the full context is not clear. I would suggest we should have a simple template along the lines of:
Please provide a brief summary of your change(s) here
[ ] Document existing feature in Home Assistant (please add link below)
[ ] Document new or changing feature in Home Assistant which there is an existing pull request for
[ ] Spelling or grammatical corrections or rewording for clarity
Please link to any relevant files or pull requests elsewhere on the Home Assistant GitHub.
master
of dev
branch (i.e. https://github.com/home-assistant/core/blob/7c784b69638f3e2b3c91294b31a62e1058ba9709/homeassistant/components/random/sensor.py#L48-L57)Hello!
Please, clarify the statement that the info
logging level is reserved for the HA core (Style guidelines).
This question arose because I added functionality to my custom component that requires not related to debugging output. This functionality is optional, and requires conscious enabling.
Am I really unable to use the info
logging level? Is this statement out of date?
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.