Added power usage entities, added dynamic data updating, fixed bugs.

Author: RicArch97

README.md

@@ -1,51 +1,59 @@
 [![hacs_badge](https://img.shields.io/badge/HACS-Custom-orange.svg?style=for-the-badge)](https://github.com/custom-components/hacs)
 [![GitHub release (latest by date)](https://img.shields.io/github/v/release/crownstone/crownstone-home-assistant?label=Latest%20release&style=for-the-badge)](https://github.com/crownstone/crownstone-home-assistant/releases)
 [![Maintained](https://img.shields.io/maintenance/yes/2020?style=for-the-badge)](https://github.com/RicArch97)
-![Github All Releases](https://img.shields.io/github/downloads/crownstone/crownstone-home-assistant/total.svg?label=Total%20downloads&style=for-the-badge&color=yellow)
 
 # Crownstone Home Assistant Integration
 
-This is the HACS repository for the Crownstone Home Assistant integration!
+<img src="images/crownstone_home_assistant.png" width="1628" height="763.5" />
 
-This repo contains files that are not available yet in Home Assistant Core. The main purpose is to make the integration available for testing. If you're using this integration and encounted a bug, please post an issue with the problem so we can resolve it.
+# Features
+
+Welcome to the Crownstone integration, a very advanced integration for Home Assistant!
+
+The supreme versatility and user friendliness of the Crownstones is reflected into this integration by the following features:
 
-Also, if you have any great ideas to make the integration even better, let us know!
+* Extremely easy to set up
+* Instant updates for switch states and data
+* Dynamically adding and removing devices/entities
+* Real-time power usage measurements using the Crownstone USB
+* Keeps track of **who** is in which room!
+* Custom advanced presence triggers to make your whole home react to your presence!
 
-<img src="images/dashboard.jpg" width="216" height="468" /> <img src="images/device_triggers.jpg" width="216" height="468" /> <img src="images/trigger_config.jpg" width="216" height="468" />
+This integration stays in one line with the Crownstone app. When data is updated, Crownstones added/deleted or Locations added/deleted, the changes are **instantly** made in Home Assistant as well, thanks to our amazing Server Send Event service!
 
 # Installation
 
 ## HACS
 
 Visit the [HACS installation page](https://hacs.xyz/docs/installation/manual) to set up HACS in your Home Assistant.
 
-Click the 3 dots button in the top right corner, and click custom respositories. Select category integration, and add the link of this repository. In the HACS store, click the "+" button in the bottom right corner, and search for Crownstone.
+Click the 3 dots button in the top right corner, and click custom repositories. Select category integration, and add the link of this repository. In the HACS store, click the "+" button in the bottom right corner, and search for Crownstone.
 
 ## Manually
 
 Copy all files from custom_components/crownstone/ to custom_components/crownstone inside your HA config folder.
 
-# Features
-
-The Crownstone integration currently supports the following features:
-
-## Switching and dimming Crownstones
+# Crownstones
 
-Crownstone are respresented in the light platform. You can create a card in the overview and add your Crownstone entities to have a nice overview of your Crownstones! If a Crownstone supports dimming, there will be a brightness slider to dim your Crownstone.
+Crownstone are represented in the light platform, and can switch or dim. You can create a card in the overview and add your Crownstone entities to have a nice overview of your Crownstones! If a Crownstone supports dimming, there will be a brightness slider to dim your Crownstone.
 
-The default communication method to switch and dim Crownstones, is the cloud. Using a cloud, it can take 1-3 seconds before a crownstone switches. However, we added support for the Crownstone USB in Home Assistant. Plug the USB in and start Home Assistant, it should automatically start switching using the USB. Since the latencies are so low using the USB, switching and dimming will be instant!
+When the ability state of **dimming** is changed through the Crownstone app, your config entry will reload to process the change in supported features. This means that some states may be different, and the power usage is likely back to 0W.  
 
-### Crownstone ability updates
+Crownstone entities have some state attributes to provide more information about the Crownstone. To see this information, simply click on the entity. This information is:
+* Switch method (Crownstone Cloud or Crownstone USB Dongle)
+* Dimming (Enabled or Disabled)
+* Tap To Toggle (Enabled or Disabled)
+* Switchcraft (Enabled or Disabled)
 
-Currently, the Crownstone integration supports updating a Crownstone's ability during runtime. Once changed in the app, Home Assistant will reload your config entry, and re-initialize all your Crownstone entities.
+<img src="images/crownstone_entity.png" width="390" height="385" />
 
-## Presence sensor
+# Presence
 
 The unique selling point of Crownstone, the presence on room level, is also available in Home Assistant!
 
-The state sensor is a string of the first names of the people who are in the room. It is possbile for multiple people to be in the same room, the names of the users is separated by a comma.
+The state sensor is a string of the first names of the people who are in the room. It is possible for multiple people to be in the same room, the names of the users is separated by a comma.
 
-Apart from the room presence there is also sphere presence. this shows who is currently in the sphere (house, apartement). If a user is at home (in the sphere), the user's name will be shown in sphere presence and one of the room presence entities.
+Apart from the room presence there is also sphere presence. this shows who is currently in the sphere (house, apartment). If a user is at home (in the sphere), the user's name will be shown in sphere presence and one of the room presence entities.
 
 The Crownstone app is leading the presence functionality, for any issues with your presence detection make sure to go to your Crownstone app and retrain your rooms. 4 Crownstones are required for the localisation on room level. If you don't have 4 Crownstones, it will only show your presence in the sphere (house).
 
@@ -74,16 +82,74 @@ Note that these triggers are `event based`. Multiple users and all users trigger
 
 The events are registered, which means that if a user enters a room, but leaves shortly after, the event for entered stays registered. If the other 2 users in the trigger then enter the room, the action will STILL execute. Make sure you select the correct trigger for the occasion. Using a single user trigger to execute an action will always be the safest option.
 
-# Troubleshooting
+<img src="images/device_triggers.jpg" width="216" height="468" /> <img src="images/trigger_config.jpg" width="216" height="468" />
+
+# Power usage
+
+Crownstone's live power usage streaming is also available in Home Assistant. Because of the constant updates, this functionality is only available when using the [Crownstone USB dongle](#crownstone-usb-dongle).
+
+The power usage for each Crownstone updates every minute, or instantly for a particular Crownstone when switching it. It can take some time before the correct power usage is displayed.
+
+## Power usage device triggers
+
+Power usage entities use the default device triggers from sensor for power usage sensors. The following triggers are available:
+- Crownstone Power usage energy changes
+
+For `Crownstone Power usage changes` there are 3 options:
+- Above a certain value
+- Below a certain value
+- Duration of the change in hh/mm/ss
+
+You can have other devices react to peaks in power usage, send an event or notification, whatever you like!
+
+<img src="images/power_usage.png" width="356" height="479" /> 
+
+# Comparison
+
+The integration works with the Crownstone Cloud and the Crownstone USB dongle. The differences between the two are only relevant for the Crownstones. The integration uses the Crownstone Cloud by default, to use the Crownstone USB you'll have to purchase one from the Crownstone store.
+
+Presence updates and data updates are always done using the Crownstone Cloud.
+
+## Crownstone Cloud
+
+- [x] Switching Crownstones
+- [x] Dimming Crownstones
+- [x] State updates in Home Assistant when switching from Crownstone app
+- [x] Can switch multiple Crownstones at once
+- [ ] No delay when switching Crownstones
+- [ ] State updates in Home Assistant when using lightswitch with Switchcraft
+- [ ] Can switch Crownstones independently (no smartphone in proximity required)
+- [ ] Can use power usage entities
+
+## Crownstone USB Dongle
+
+- [x] Switching Crownstones
+- [x] Dimming Crownstones
+- [x] State updates in Home Assistant when switching from Crownstone app
+- [x] Can switch multiple Crownstones at once
+- [x] No delay when switching Crownstones
+- [x] State updates in Home Assistant when using lightswitch with Switchcraft
+- [x] Can switch Crownstones independently (no smartphone in proximity required)
+- [x] Can use power usage entities
+
+Get your Crownstone USB dongle [here](https://shop.crownstone.rocks/products/crownstone-usb-dongle) and enhance your Home Assistant experience!
 
-1. When I switch my Crownstone using the app, the change isn't visible in Home Assistant, why?
+# Testing
 
-We chose not to update the state in Home Assistant externally because the state isn't always known. When using switchcraft for example, the state of the Crownstone is not updated in the cloud. The safest option is to only let Home Assistant change the state of it's entities. The Crownstone entities use assumed state which means you will ALWAYS be able to switch your Crownstones using Home Assistant, independed of the state in the app.
+To ensure the best possibly experience with the Crownstone Home Assistant integration, thoroughly testing is required. You can find a test rapport [here](test_rapport.md). 
 
-2. I updated some data / Crownstone firmware in the Crownstone app, but it is not updated in Home Assistant
+This rapport shows exactly what tests have been done, and what the result was. 
+If you like to contribute test results of tests that have not been done by us yet, you can post an issue with the test & the result. We will adjust the rapport accordingly including credit.
 
-Dynamically updating data is not yet supported for the Crownstone integration. To register the changes in HA, you'll have to restart.
+# Roadmap
 
-3. Will there be an option to use power usage as trigger in Home Assistant?
+- [ ] Publish initial Crownstone integration to Home Assistant Core (in progress)
+- [x] Optimize configuration flow for easier setup
+- [x] Create device triggers for Presence devices
+- [x] Add power usage entities to Crownstone devices
+- [x] Fix state updates coming from the Crownstone app not being done in Home Assistant
+- [x] Dynamically update data & add/remove Crownstone and Location devices without restarting or reloading
+- [ ] Create device conditions for Presence devices
+- [ ] Optimize power usage accuracy by implementing new UART protocol
 
-The power usage feature is on the roadmap for upcoming updates. Likely this will come whenever the Crownstone hub is finished.
+Any ideas for future updates? Let us [know](mailto:ask@crownstone.rocks?subject=[GitHub]%20Crownstone%20Home%20Assistant%20Integration)!

custom_components/crownstone/config_flow.py

@@ -44,12 +44,12 @@ async def async_step_user(self, user_input=None):
         self.cloud = CrownstoneCloud(
             email=user_input[CONF_EMAIL],
             password=user_input[CONF_PASSWORD],
-            websession=aiohttp_client.async_get_clientsession(self.hass),
+            clientsession=aiohttp_client.async_get_clientsession(self.hass),
         )
 
         # handle login errors on setup form
         try:
-            await self.cloud.async_login()
+            await self.cloud.async_initialize()
             # save email and password for later use
             self.login_info = user_input
             # start next flow
@@ -75,19 +75,16 @@ async def async_step_user(self, user_input=None):
 
     async def async_step_sphere(self, user_input=None):
         """Handle the step for selecting a sphere."""
-        # get the spheres for the user
-        await self.cloud.spheres.async_update_sphere_data()
-
         # only 1 sphere configured, don't show form and set this as sphere
-        if len(self.cloud.spheres.spheres) == 1:
+        if len(self.cloud.cloud_data.spheres) == 1:
             user_input = {
-                CONF_SPHERE: next(iter(self.cloud.spheres.spheres.values())).name
+                CONF_SPHERE: next(iter(self.cloud.cloud_data.spheres.values())).name
             }
 
         # show form with drop down menu
         if user_input is None:
             # generate sphere list
-            for sphere in self.cloud.spheres:
+            for sphere in self.cloud.cloud_data:
                 self.spheres.append(sphere.name)
 
             return self.async_show_form(
@@ -100,9 +97,6 @@ async def async_step_sphere(self, user_input=None):
         # make sure this sphere is only set up once
         self._abort_if_unique_id_configured()
 
-        # cleanup RequestHandler
-        self.cloud.reset()
-
         # return data to main
         return self.async_create_entry(
             title=self.unique_id,

custom_components/crownstone/const.py

@@ -5,28 +5,44 @@
 SENSOR_PLATFORM = "sensor"
 LIGHT_PLATFORM = "light"
 
-# Signals
-SIG_STATE_UPDATE = "crownstone.state_update"
+# Signals (within integration)
+SIG_PRESENCE_STATE_UPDATE = "crownstone.presence_state_update"
+SIG_PRESENCE_UPDATE = "crownstone.presence_update"
+SIG_CROWNSTONE_STATE_UPDATE = "crownstone.crownstone_state_update"
+SIG_CROWNSTONE_UPDATE = "crownstone.crownstone_update"
+SIG_POWER_STATE_UPDATE = "crownstone.power_state_update"
+SIG_POWER_UPDATE = "crownstone.power_update"
 SIG_TRIGGER_EVENT = "crownstone.trigger_event"
+SIG_ADD_CROWNSTONE_DEVICES = "crownstone.add_crownstone_device"
+SIG_ADD_PRESENCE_DEVICES = "crownstone.add_presence_device"
+SIG_UART_READY = "crownstone.uart_ready"
+
+# Added/deleted device or entities
+ADDED_ITEMS = "added_items"
+REMOVED_ITEMS = "removed_items"
+ABILITY = {"enabled": False, "properties": {}}
+
+# Abilities state
+ABILITY_STATE = {True: "Enabled", False: "Disabled"}
 
 # Config flow
 CONF_SPHERE = "sphere"
 
 # Crownstone entity
 CROWNSTONE_TYPES = {
-    "PLUG": "Crownstone plug",
-    "CROWNSTONE_USB": "Crownstone USB",
-    "BUILTIN": "Crownstone built-in",
-    "BUILTIN_ONE": "Crownstone built-in one",
-    "GUIDESTONE": "Crownstone guidestone",
+    "PLUG": "Plug",
+    "CROWNSTONE_USB": "USB Dongle",
+    "BUILTIN": "Built-in",
+    "BUILTIN_ONE": "Built-in One",
+    "GUIDESTONE": "Guidestone",
 }
 CROWNSTONE_EXCLUDE = ["CROWNSTONE_USB", "GUIDESTONE"]
 
 # Presence entity
-PRESENCE_SPHERE = {"icon": "mdi:earth", "description": "Sphere presence"}
+PRESENCE_SPHERE = {"icon": "mdi:earth", "description": "Sphere Presence"}
 PRESENCE_LOCATION = {
     "icon": "mdi:map-marker-radius",
-    "description": "Location presence",
+    "description": "Location Presence",
 }
 
 # Device automation
@@ -43,6 +59,6 @@
 ALL_USERS_ENTERED = "all_entered"
 ALL_USERS_LEFT = "all_left"
 
-# Trigger events
+# Trigger events (these are fired in the bus, and available to the user)
 EVENT_USER_ENTERED = "crownstone.user_entered"
 EVENT_USER_LEFT = "crownstone.user_left"