home-assistant / companion.home-assistant Goto Github PK
View Code? Open in Web Editor NEW:book: Home Assistant Companion docs
Home Page: https://companion.home-assistant.io/
License: Other
:book: Home Assistant Companion docs
Home Page: https://companion.home-assistant.io/
License: Other
It seems the example under:
https://companion.home-assistant.io/en/next/notifications/basic#notification-sounds
has the word "sounds:" when it should be "sound:"
Sorry if this isn't the correct way to get this corrected.
Have been thinking of altering the site structure to make things easier to find and navigate. Proposing a new structure here which I think would be a massive improvement personally.
Current way has things more siloed off and in kind of weird, hard to discover areas imo. Theming is not really an integration, and I don't feel like Sensors are an integration either... And then in the Notifications section for example it feels like there's a sort of arbitrary differentiation between basic and advanced. And depending on which section you clicked first you can't really see the other pages easily, Location section for example has no sidebar at all.
Proposed Structure & Sidebar:
I think those are broken out into clearly distinct categories, and it solves the issues mentioned above, makes navigation easier, makes it easy to discover the various features of the app. Probably only a handful of page redirects would be needed.
Header would stay mostly the same I think, except "Misc" & "Help" links get merged to one "Troubleshooting" link.
https://companion.home-assistant.io/en/notifications/basic#replacing-notifications
This
message: "Someone might be in the backyard."
data:
apns_headers:
'apns-collapse-id': 'backyard-motion-detected'
should be this
message: "Someone might be in the backyard."
data:
apns_headers:
'apns-collapse-id': 'backyard-motion-detected'
Too difficult to find the links now :)
Hello,
I want to link my local HA install from a landing page in my internal network. Is there a single link that will try to open an installed mobile app whether ios or android, but if it doesn't exist, fall back to the web location? I think it's a fairly common use case, so it would be worth documenting if it were possible.
So as discussed on Discord a little. I think versioning is causing us a bit of pain. Main issue is that when someone uses the edit function these edits are made against the next
version docs and require moving back to the 2.0.0
which are the landing version.
I've built a demo version of the docs site here from scratch and used Docusaurus 2 to do so. I ported over the conent but this is a couple of PRs out of date now but it is pretty much just a copy and paste the files job to update. Little summary
I haven't enabled the search bar yet for the proof of concept page but this should be trivial on the deployment
Looks like the search result link locations need to be updated.
Example: searching for Location
leads to
https://companion.home-assistant.io/en/core/location#__docusaurus
while it should be: https://companion.home-assistant.io/docs/core/location
So far it seems to be impacting all results. Not entirely sure where the issue relies. We had a similar issue with the links on the feature comparison table and I had to update them to be exact locations.
This should be a pretty quick fix.
On this page, it says:
You may also use a device_tracker for the latitude and longitude coordinates like so: "{{states.device_tracker.<your_device_id_here>.attributes.latitude}}" but make sure to use data_template in that case.
As the automation has two levels of data object, these docs should be clarified to specify which data object should be specified as a data_template: the first, the second, or both.
The sensors doc looks bad on mobile devices (see below) since the table is too wide for a screen. We should re write this plain text with each sensor as a sub-section heading to allow for easy direct linking. I'm thinking something like how configuration variables are shown in the main docs, see here for example.
Add step between 8 and 9 to logout of the IOS application. Without this action it is not possible to re-enroll
When home-assistant/core#44094 is fixed revert #416
Is your feature request related to a problem? Please describe.
I have a security system integrated and sending notifications. I'd like to be able to add actionable buttons such as:
Describe the solution you'd like
Something that allows me to create buttons on a notification that opens a URL directly on the device. It doesn't really have to reach back to HA for anything. Would like to be able to set a Title and a URL, as well as the usual "destructive" and other settings.
Need to make sure the case and restart requirements are clear
Menu item 'Requesting location updates' links to page https://companion.home-assistant.io/docs/notifications/location-notification but it returns Page Not Found
It seems (i searched every doc page without finding at least) there is missing documentation about the feature Enable receiving broadcast to update location introduced in Home Assistant Companion Android 1.7.0.
Link to PR home-assistant/android#355
Just updated the app via Google Play to version 3.0.0-full, which should include the change to be able to use the alarm stream for notifications, thus bypass silent mode / do not disturb. Unfortunately when testing it's not working. I only see another channel called 'alarm-stream' that has been added into notifications under the Home Assistant app, but still silent notifications.
My automation in HA:
action:
- service: notify.mobile_app_phone
data:
message: "Some message"
title: "Some title"
data:
ttl: 0
priority: high
channel: alarm_stream
This just gives me a silent notification when the action is triggered. When I use my alarm clock on my phone it gives me a sound, so I would assume my alarm notifications are properly set-up on my Android device. Running Android v10.
What am I doing wrong here?
OS: Android 10
Companion version: 2.2.1-274-full
When setting a clock alarm to whichever time, the sensor sets to five minutes before the time the alarm in reality is set to.
For example, when setting a phone alarm to 11.00 the sensor shows:
State: 2020-08-20T08:55:01.000
Attributes:
Local Time: Thu Aug 20 10:55:01 GMT+02:00 2020
Time in Milliseconds: 1597913701000
Package: com.sec.android.app.clockpackage
friendly_name: [devicename] Next Alarm
icon: mdi:alarm
device_class: timestamp
Setting the alarm to 11.16 generates the sensors state state to be 2020-08-20T09:11:01.000Z instead.
It's the same issue for both of our phones having the Android version as above as well as Companion app version.
However - it's not the same for the calendar provider. When deactivation the phone alarm, the next upcoming alarm is a calendar event set with a notification. The event starts at 17.00 local time and is set to notify 15 minutes prior. That gives this in Home Assistance:
State: 2020-08-20T14:45:00.000Z
Attributes:
Local Time: Thu Aug 20 16:45:00 GMT+02:00 2020
Time in Milliseconds: 1597934700000
Package: com.android.providers.calendar
friendly_name: [devicename] Next Alarm
icon: mdi:alarm
device_class: timestamp
Thanks!
A suggestion from me: is it a handy addition to include a package-lock.json
file in the repo by default?
Since npm install
uses this to install all packages, this also ensures that everyone that is working on the companion docs uses the same packages with local development.
Just think about it ๐
At https://companion.home-assistant.io/en/getting_started/migration it seems to say that one can enter a URL if one is not on "home wifi". Later, in the Nabu Casa troubleshooting section, it says one cannot set up Nabu Casu directly, and one needs to be on the home LAN first. It is really not clear if a connection to the HA instance uses any methods other than via the https:://hass.example.com:8123 URL, or if this is merely about finding internal (presumably working only on one SSID) vs external (presumably working everywhere) URLs.
The notion of a trailing slash, presumably "https://hass.example.com:8123" vs "https://hass.example.com:8123/" is also confusing. Technically one has no path and the other a path with no components, but it does not make sense that any software would treat these separately, especially for URLs entered by humans, almost none of whom understand the syntax subtleties.
The migration guide says only "or you can manually enter the URL", and doesn't address trailing slashes.
(I am running into this helping someone not physically with me configure the iOS app to access a server that neither of us are physically at -- but it does have a straightforward, entirely accessible, domain name.)
Please note, I wrote this while very tired and lacking sleep. It will receive updates over the next few days.
Right now, we live in a similar yet divided world. Home Assistant Companion (hereinafter HAC) for iOS came first and had many years to mature before HAC Android was even a glint in our eyes. Due to that time and somewhat limited thought for the future, iOS made some decisions that don't work well in the Android world. Android is starting to make decisions that will also affect iOS. We should try to cut down on as many differences between the two apps as possible. This will allow us to simplify our documentation but more importantly make it easier for users in households with both Androids and iPhones, in addition to making config sharing easier.
The first place to start with is notifications. Right now, both apps support different functionalities. Some functionalities exist because of work developers have done, some will never exist due to OS specific limitations. As much as possible though, we should make it possible for a user to send a notification and 90% of the time it will appear similar across platform. The way that we do this is deriving a schema that both apps can hew to while also providing allowances for platform specific functionality that users want.
As a first step towards that goal, I have come up with this:
{
"push_token": "",
"registration_info": {
"app_id": "io.robbie.HomeAssistant.beta",
"app_version": "2.0.0 (68)",
"os_name": "iOS",
"os_version": "13.1.3"
},
"id": "uuid",
"notification": {
"message": "The front door is opened",
"title": "Front Door",
"badge": 5,
"image": "https://github.com/home-assistant/home-assistant-assets/blob/master/logo-round-192x192.png?raw=true",
"tag": "one",
"click_action": "",
"actions": [
{
"title": "Action 1",
"id": "action_one"
}
],
"android": {
"priority": "high",
"ttl": "3.5s",
"sticky": true,
"visibility": "VISIBILITY_UNSPECIFIED",
"local_only": true,
"icon": "ics_launcher",
"color": "#000000",
"channel_id": "default",
"ticker": "Hello World",
"event_time": "2020-02-14T07:30:21Z",
"notification_priority": "PRIORITY_DEFAULT",
"default_sound": true,
"default_vibrate_timings": true,
"default_light_settings": true,
"vibrate_timings": [
"1s",
"3.5s"
],
"light_settings": {
"color": {
"red": 1,
"green": 1,
"blue": 1,
"alpha": 0
},
"light_on_duration": "3.5s",
"light_off_duration": "3.5s"
}
},
"ios": {
"image": {
"content_type": "image/png",
"hide_thumbnail": true
},
"subtitle": "TwelveTwelve",
"sound": {
"name": "default",
"critical": true,
"volume": 1
}
}
}
}
As you can see, we have generic fields at the top level (under the notification
dictionary) and OS specific fields in their own dictionaries. I also made a spreadsheet that shows common features and their availability across both platforms. We should conform both apps to accept this schema. It will be a pain for users to adapt to one time but will have other benefits to be explained later. The change will be opt in for existing users, at least on iOS. We also have added a UUID to the notification payload to provide lifecycle tracking. The UUID should be generated and stored by Home Assistant Core and used in all follow up events and actions. The actions are now also defined in the notification, whereas previously iOS required defining all possible actions in advance. Actions are now registered with iOS just-in-time before displaying the notification.
The next place the apps deviate significantly to the detriment of the user is Notification Action Events. On iOS, this is the event named ios.notification_action_fired
. On Android it is mobile_app_notification_action
. To start, iOS should adapt the more generic mobile_app_notification_action
event name. However, the payloads sent in the events are also very different between platforms and deserve to be unified into one
My proposal is this:
{
"event_type": "mobile_app_notification_action",
"data": {
"action_chosen": "action_one",
"action_data": {},
"device_name": "Robbie's iPhone",
"id": "uuid"
},
"origin": "REMOTE",
"time_fired": "2020-02-02T04:45:05.550251+00:00",
"context": {
"id": "abc123",
"parent_id": null,
"user_id": "123abc"
}
}
This provides everything we need to let users determine where the event came from, as well as provides them flexibility to customize by providing the action_data
dictionary, a totally user controlled space. They can fill the action_data
dict when sending the notification. The id
is the same one from the notification example above.
Great, so notifications and events are well defined and traceable. That will allow us to implement a new type of automation block which will allow pausing an automation until such time as a user responds to a notification by tapping an action. Users will no longer have to worry about setting up two automations (one to send the notification and one to catch the response event), it will just be handled seamlessly by Home Assistant Core. @balloob came up with this idea and can expand more on it.
Now that notifications have unique IDs attached to them, we can monitor them through their entire lifecycle. I propose adding the following new events:
In addition, I propose that Home Assistant Core start storing these notifications and providing a API to mobile_app
implementors to allow viewing notification history.
As somewhat of a carrot to get iOS users to opt in to the new notification and event formats, we will begin offering end to end encryption of push notifications on both platforms. On iOS, this is made possible by UNNotificationServiceExtension which will decrypt and map the notification payload before displaying the notification to the user. On Android, we already are in a position where the app is the one processing and displaying the notification, not the OS. mobile_app
will be modified to encrypt outgoing notifications using libsodium with the same webhook secret the apps already have. A very minimal forwarder has already been developed and deployed and is available for review here. Here's everything that the forwarder receives:
{
"encrypted": true,
"encrypted_data": "j6lwIesVlc+1rYltzw1iFgZZgir3QcZzs+erYXIB6TphTl6bY6xQUYYqhXQ6tGjFAWvMetre/FC89Z85OLExlm3AwX4TzEbbmpLLAoD+zuiG+FugGk756fju58ImTA+Ci5echwgyMNwehKC/RYsbS0V0YieMU34RG/2DT6SDAh++/DmktPBpealTBLnEHRx4/PuNMeqdC7kB5nfkr1gYaBBEXON0R/yLc0sR4qk42RcIyOMd2VrG1apRBSxJizhQVyBrwUWe4z8UdhlXuwLDUhBtieB/xRJSJg1B74ywGvfEtsVJVLlFii8BSsgP/wp/RlcRMLRy8ixa/WPNHLj9YSXLCNYrIvjhTwlxhjAEZncO6fHy0jOuAWbiCrWPgju2q7zWwUxtNO13rGV5pXju++sjiuGn0gKvDBsaw9ZWnVZmR50NeBVha7e4XgUPpS5+Wx78DukpCcuRU/s3N9Q4yCQHkiPtFKszEg6A5FDYb9gGnzD5aSBfKINbNDmh6oBQvN6G2HBsO8E8AdA1cOupMWEFE6b6Y7taHxgNAaX3ik1zYKGe+zDSUSv0SWqIsx8MbbgG+qkSvdNqHswvOw==",
"push_token": "",
"registration_info": {
"app_id": "io.robbie.HomeAssistant.beta",
"app_version": "2.0.0 (68)",
"os_version": "13.1.3"
}
}
and what it sends to the device:
{
"apns": {
"payload": {
"aps": {
"alert": {
"title": "Encrypted notification",
"body": "If you're seeing this, something has gone wrong with encryption"
},
"mutable-content": 1
}
}
},
"data": {
"encrypted_data": "j6lwIesVlc+1rYltzw1iFgZZgir3QcZzs+erYXIB6TphTl6bY6xQUYYqhXQ6tGjFAWvMetre/FC89Z85OLExlm3AwX4TzEbbmpLLAoD+zuiG+FugGk756fju58ImTA+Ci5echwgyMNwehKC/RYsbS0V0YieMU34RG/2DT6SDAh++/DmktPBpealTBLnEHRx4/PuNMeqdC7kB5nfkr1gYaBBEXON0R/yLc0sR4qk42RcIyOMd2VrG1apRBSxJizhQVyBrwUWe4z8UdhlXuwLDUhBtieB/xRJSJg1B74ywGvfEtsVJVLlFii8BSsgP/wp/RlcRMLRy8ixa/WPNHLj9YSXLCNYrIvjhTwlxhjAEZncO6fHy0jOuAWbiCrWPgju2q7zWwUxtNO13rGV5pXju++sjiuGn0gKvDBsaw9ZWnVZmR50NeBVha7e4XgUPpS5+Wx78DukpCcuRU/s3N9Q4yCQHkiPtFKszEg6A5FDYb9gGnzD5aSBfKINbNDmh6oBQvN6G2HBsO8E8AdA1cOupMWEFE6b6Y7taHxgNAaX3ik1zYKGe+zDSUSv0SWqIsx8MbbgG+qkSvdNqHswvOw==",
"encrypted": "true",
"registration_info": "{\"app_id\":\"io.robbie.HomeAssistant.beta\",\"app_version\":\"2.0.0 (68)\",\"os_version\":\"13.1.3\"}"
},
"token": ""
}
Obviously our servers are unable to break the encryption and the secret is only ever exchanged directly via app and Home Assistant Core. iOS requires alert and mutable-content to be set to engage our UNNotificationServiceExtension. The user should never actually see that text except if decryption fails for some reason.
The identified downsides to e2e encryption are the following:
ttl
or priority
fields or APNS headers such as apns-collapse-id
or apns-priority
. Modifications could be made to notify.mobile_app
to allow sending certain whitelisted parameters in the clear.I'm excited to hear the communities thoughts on this proposal. Thanks for reading.
Continuing conversation from home-assistant/android#125
We have loads of great iOS on-boarding info in the migration guide. However, 2019.1 has been out for about 6 months now and I would hope most people have migrated by now. We should probably consider moving a lot of the problem solving steps to a troubleshooting set up page as the current title isn't clear that these steps apply to fresh installs too
I get to the logon page and get stuck, cannot add username/pass or traverse fields to select trusted network user.
3D touch as an interaction is all but deprecated and not included in more recent models. It is replaced by haptic touch which is essentially touch and hold/long touch. We should update accordingly
@danikuci1 commented on May 26, 2020, 8:52 PM UTC:
the docs contain a link to https://companion.home-assistant.io/docs/notifications/location-notification which is a non-existent page.
This issue was moved by TomBrien from home-assistant/iOS#594.
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.