Hi all,

I would like to implement External Authentication for Android apps (Written in Kotlin).

I refer to two documentation links:

1. https://github.com/home-assistant/developers.home-assistant/blob/master/docs/frontend_external_auth.md
2. https://developers.home-assistant.io/docs/en/frontend_external_auth.html

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.

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

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.

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?

https://docusaurus.io/docs/en/versioning

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.

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.

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.

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

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." ????

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.

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?

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.

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.)

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.

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...

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.

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.

dev-docs.home-assistant.io is out of date

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.

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

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

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.

It says

Allowed entries: string, int, time, template or map (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

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.

• Documentation for the homeassistant.remote API is still online and UI leads users to believe it is part of 0.91.1

This 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 3e09850
• homeassistant.remote was removed in home-assistant/core#16099

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.

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.

In 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.

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!

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:

Summary

Please provide a brief summary of your change(s) here

Type of change

[ ] 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

Relevant link(s)

Please link to any relevant files or pull requests elsewhere on the Home Assistant GitHub.

• For documentation for existing features this should be the relevant lines in the source file or directory on the relevant master of dev branch (i.e. https://github.com/home-assistant/core/blob/7c784b69638f3e2b3c91294b31a62e1058ba9709/homeassistant/components/random/sensor.py#L48-L57)
• For documentation relating to new or changed features, this link should be to the relevant pull request (i.e. home-assistant/core#2)

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?

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 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.

• https://github.com/home-assistant/developers.home-assistant/blob/master/docs/entity_registry_index.md

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]

• However, looking at the entity doc it would be: [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.

• On the creating custom platform page the 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.

• And lastly (for now), this Integration File Structure page completely throws me off.

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?

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)

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 heating
• action is set to CURRENT_HVAC_OFF, as the temperature has been reached.
• actions is set to OFF/HEAT and modes is set to just HEAT

But with those values, the thermostat card (and state) show the device as heating.

So.

• Could more words be put on the difference between mode and action, possibly examples?
• Could CURRENT_HVAC_IDLE vs. CURRENT_HVAC_OFF be described?

Related: dave-code-ruiz/uhomeuponor#6

Mike.

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.

@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.

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?

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"
---

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:

• Specify the base entity class to inherit
• Describe properties and methods (which should be implemented/overridden)
• Describe consts (states, features, etc...)

Docs Needed (prioritized)

• Light - completely empty - @luismonge1192
• Media Player - incomplete
• Climate - @willgreenberg #227
• Remote - completely empty
• Alarm Control Panel - incomplete
• Lock - completely empty
• Fan - completely empty - @Angie1313 #229
• Camera - no existing page
• Calendar - no existing page

The problem

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

Environment

• 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

Problem-relevant 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

Traceback/Error logs

WARNING (MainThread) [homeassistant.components.camera] The websocket command 'camera_thumbnail' has been deprecated.

Additional information

custom-cards/surveillance-card#22

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.

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

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.123

  position (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: 59

  my_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.

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

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 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.

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'?

The source for API documentation is located in the main repo.

Suggestion to move it and make it available at developers.home-assistant.

It is unclear to me how to develop on the Hass.io panel.
The documentation only covers general frontend development work.

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?