Added support for energy usage entities.

Author: RicArch97

README.md

@@ -15,7 +15,7 @@ The supreme versatility and user friendliness of the Crownstones is reflected in
 * 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
+* Real-time power and energy 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!
 
@@ -27,9 +27,11 @@ This integration stays in one line with the Crownstone app. When data is updated
 
 ## HACS
 
-Visit the [HACS installation page](https://hacs.xyz/docs/installation/manual) to set up HACS in your Home Assistant.
+Visit the [HACS installation page](https://hacs.xyz/docs/installation/installation) to install HACS, and the [HACS setup page](https://hacs.xyz/docs/configuration/basic) to enabled HACS in Home Assistant.
 
-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.
+In HACS, Click the 3 dots button in the top right corner, and click custom repositories. Select category integration, and add the link of this repository. 
+
+After adding the repository, in the HACS store, click the "+ explore & add repositories" button in the bottom right corner, and search for Crownstone. Then just follow the installation steps. Make sure to select the newest version!
 
 ## Manually
 
@@ -86,25 +88,35 @@ The events are registered, which means that if a user enters a room, but leaves
 
 <img src="images/device_triggers.jpg" width="216" height="468" /> <img src="images/trigger_config.jpg" width="216" height="468" />
 
-# Power usage
+# Power usage & Energy usage
+
+Crownstone's live power usage streaming, and energy usage summation, are 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).
 
-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 and energy usage for each Crownstone update every minute, or instantly for a particular Crownstone when switching it.
 
-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.
+## Energy usage features
 
-## Power usage device triggers
+- Starts at 0 in Home Assistant after installing/updating the integration, independent of the value received by the Crownstone
+- Persistent states: after rebooting Home Assistant, the energy usage values remain
+- When a Crownstone is reset (updated or power loss), the values in Home Assistant will remain, and will be further updated
+- The values for energy usage are set back to 0 each month in Home Assistant. In the `History` tab, you will be able to see the maximum usage for each month
+
+## Power usage & Energy 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
+- Crownstone Power Usage power changes
+
+Energy usage entities also use the default device triggers from sensor for energy usage sensors. The following triggers are available:
+- Crownstone Energy Usage energy changes
 
-For `Crownstone Power usage changes` there are 3 options:
+For `Crownstone Power Usage power changes` or `Crownstone Energy Usage energy 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!
+Example usage is to send a notification to your phone when the power usage is too high for a certain duration, or switch the device off when this happens. When energy usage reaches a certain value, you could activate a scene which turns multiple devices off.
 
-![Crownstone power usage](/images/power_usage.png)
+![Crownstone power usage](/images/power_energy_usage.png)
 
 # Comparison
 
@@ -121,7 +133,7 @@ Presence updates and data updates are always done using the Crownstone Cloud.
 - [ ] 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
+- [ ] Can use power usage & energy usage entities
 
 ## Crownstone USB Dongle
 
@@ -132,7 +144,7 @@ Presence updates and data updates are always done using the Crownstone Cloud.
 - [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
+- [x] Can use power usage & energy usage entities
 
 Get your Crownstone USB dongle [here](https://shop.crownstone.rocks/products/crownstone-usb-dongle) and enhance your Home Assistant experience!
 
@@ -151,9 +163,8 @@ If you like to contribute test results of tests that have not been done by us ye
 - [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
+- [x] Add energy usage entities to Crownstone devices
 - [ ] Create device conditions for Presence devices
-- [ ] Optimize power usage accuracy by implementing new UART protocol
-- [ ] Add energy usage entities to Crownstone devices
 
 Any ideas for future updates? Let us [know](mailto:ask@crownstone.rocks?subject=[GitHub]%20Crownstone%20Home%20Assistant%20Integration)!
 

custom_components/crownstone/config_flow.py

@@ -28,6 +28,7 @@ def __init__(self):
         """Initialize the flow."""
         self.cloud: Optional[CrownstoneCloud] = None
         self.login_info = None
+        self.sphere_input = None
         self.spheres = []
 
     async def async_step_user(self, user_input=None):
@@ -96,8 +97,17 @@ async def async_step_sphere(self, user_input=None):
                 data_schema=vol.Schema({CONF_SPHERE: vol.In(self.spheres)}),
             )
 
+        self.sphere_input = user_input
+
+        return await self.async_step_usb()
+
+    async def async_step_usb(self, user_input=None):
+        """Ask a user to plug in a Crowsntone USB (if any)."""
+        if user_input is None:
+            return self.async_show_form(step_id="usb")
+
         # set the unique id
-        await self.async_set_unique_id(user_input[CONF_SPHERE])
+        await self.async_set_unique_id(self.sphere_input[CONF_SPHERE])
 
         # return data to main
         return self.async_create_entry(
@@ -106,6 +116,6 @@ async def async_step_sphere(self, user_input=None):
                 CONF_ID: self.unique_id,
                 CONF_EMAIL: self.login_info[CONF_EMAIL],
                 CONF_PASSWORD: self.login_info[CONF_PASSWORD],
-                CONF_SPHERE: user_input[CONF_SPHERE],
+                CONF_SPHERE: self.sphere_input[CONF_SPHERE],
             },
         )

custom_components/crownstone/const.py

@@ -8,6 +8,7 @@
 # Unique ID suffixes
 CROWNSTONE_SUFFIX = "relay_and_dimmer"
 POWER_USAGE_SUFFIX = "power_usage"
+ENERGY_USAGE_SUFFIX = "energy_usage"
 PRESENCE_SUFFIX = "presence"
 
 # Signals (within integration)
@@ -17,6 +18,8 @@
 SIG_CROWNSTONE_UPDATE = "crownstone.crownstone_update"
 SIG_POWER_STATE_UPDATE = "crownstone.power_state_update"
 SIG_POWER_UPDATE = "crownstone.power_update"
+SIG_ENERGY_STATE_UPDATE = "crownstone.energy_state_update"
+SIG_ENERGY_UPDATE = "crownstone.energy_update"
 SIG_TRIGGER_EVENT = "crownstone.trigger_event"
 SIG_ADD_CROWNSTONE_DEVICES = "crownstone.add_crownstone_device"
 SIG_ADD_PRESENCE_DEVICES = "crownstone.add_presence_device"
@@ -50,6 +53,11 @@
     "description": "Location Presence",
 }
 
+# Energy usage constants
+JOULE_TO_WH = 3600
+MEASUREMENT_START = "Measurement start"
+LAST_UPDATE = "Last update"
+
 # Device automation
 
 # Config

custom_components/crownstone/data_updater.py

@@ -45,14 +45,22 @@
     SIG_ADD_PRESENCE_DEVICES,
     SIG_CROWNSTONE_STATE_UPDATE,
     SIG_CROWNSTONE_UPDATE,
+    SIG_ENERGY_STATE_UPDATE,
+    SIG_ENERGY_UPDATE,
     SIG_POWER_STATE_UPDATE,
     SIG_POWER_UPDATE,
     SIG_PRESENCE_STATE_UPDATE,
     SIG_PRESENCE_UPDATE,
     SIG_TRIGGER_EVENT,
     SIG_UART_READY,
 )
-from .helpers import async_remove_devices, check_items
+from .helpers import (
+    EnergyData,
+    async_remove_devices,
+    check_items,
+    create_utc_timestamp,
+    process_energy_update,
+)
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -89,6 +97,7 @@ def __init__(self, hass, entry, user_data, sse):
         UartEventBus.subscribe(SystemTopics.connectionClosed, self.update_uart_state)
         UartEventBus.subscribe(UartTopics.newDataAvailable, self.update_crwn_state_uart)
         UartEventBus.subscribe(UartTopics.newDataAvailable, self.update_power_usage)
+        UartEventBus.subscribe(UartTopics.newDataAvailable, self.update_energy_usage)
 
     # SSE UPDATES
 
@@ -220,6 +229,10 @@ async def update_data(self, data_event: DataChangeEvent) -> None:
                     async_dispatcher_send(
                         self.hass, SIG_POWER_UPDATE, data_event.changed_item_id
                     )
+                    # update energy usage entity (name)
+                    async_dispatcher_send(
+                        self.hass, SIG_ENERGY_UPDATE, data_event.changed_item_id
+                    )
 
                 # additions or deletions
                 if data_event.operation in (OPERATION_CREATE, OPERATION_DELETE):
@@ -303,12 +316,28 @@ def update_power_usage(self, data) -> None:
         """Update the power usage of a Crownstone when a Crownstone USB is available."""
         update_crownstone = self.user_data.crownstones.find_by_uid(data["id"])
         if update_crownstone is not None:
-            # for now, make sure power usage can't go below zero
-            # an improved version of power usage measuring is in development
             if data["powerUsageReal"] < 0:
                 update_crownstone.power_usage = 0
             else:
                 update_crownstone.power_usage = int(data["powerUsageReal"])
 
             # update HA state
             async_dispatcher_send(self.hass, SIG_POWER_STATE_UPDATE)
+
+    def update_energy_usage(self, data) -> None:
+        """Update the energy usage of a Crownstone when a Crownstone USB is available."""
+        update_crownstone = self.user_data.crownstones.find_by_uid(data["id"])
+        if update_crownstone is not None:
+            # create object that holds energy usage variables
+            new_energy_usage = EnergyData(
+                data["accumulatedEnergy"], create_utc_timestamp(data["timestamp"])
+            )
+
+            # compare new values to existing ones
+            process_energy_update(new_energy_usage, update_crownstone.energy_usage)
+
+            # set new data point
+            update_crownstone.energy_usage = new_energy_usage
+
+            # update HA state
+            async_dispatcher_send(self.hass, SIG_ENERGY_STATE_UPDATE)

custom_components/crownstone/device_trigger.py

@@ -16,6 +16,7 @@
     CONF_PLATFORM,
     CONF_TYPE,
     DEVICE_CLASS_ENERGY,
+    DEVICE_CLASS_POWER,
 )
 from homeassistant.core import CALLBACK_TYPE, Event, HomeAssistant, callback
 from homeassistant.helpers import config_validation as cv, entity_registry
@@ -107,7 +108,11 @@ async def async_get_triggers(hass: HomeAssistant, device_id: str) -> List[dict]:
     # loop through all entities for device
     for entry in entity_registry.async_entries_for_device(registry, device_id):
         # make sure to only add custom triggers to presence sensor entities
-        if entry.domain != SENSOR_PLATFORM or entry.device_class == DEVICE_CLASS_ENERGY:
+        if (
+            entry.domain != SENSOR_PLATFORM
+            or entry.device_class == DEVICE_CLASS_ENERGY
+            or entry.device_class == DEVICE_CLASS_POWER
+        ):
             continue
 
         for trigger in TRIGGER_TYPES:

custom_components/crownstone/helpers.py

@@ -1,8 +1,11 @@
 """Helper functions/classes for Crownstone."""
 import asyncio
+from datetime import datetime, timezone
 import threading
+from typing import Any
 
 from crownstone_uart import CrownstoneUart
+from tzlocal import get_localzone
 
 from homeassistant.config_entries import ConfigEntry
 from homeassistant.core import HomeAssistant
@@ -38,6 +41,23 @@ def stop(self) -> None:
         self.uart_instance.stop()
 
 
+class EnergyData:
+    """Data class that holds energy measurements."""
+
+    def __init__(self, accumulated_energy: int, utc_timestamp: Any) -> None:
+        """Initialize the object."""
+        # new value obtained from UART
+        self.energy_usage = accumulated_energy
+        # the new energy usage value (after adding the offset or previous value)
+        self.corrected_energy_usage = 0
+        # timestamp of the measurement in UTC
+        self.timestamp = utc_timestamp
+        # flag for being a first node in the energy data chain
+        self.first_measurement = False
+        # flag for a restored state from previous session
+        self.restored_state = False
+
+
 def set_to_dict(input_set: set):
     """Convert a set to a dictionary."""
     return {key: key for key in input_set}
@@ -81,3 +101,72 @@ async def async_remove_devices(
             device_reg.async_update_device(
                 device.id, remove_config_entry_id=entry.entry_id
             )
+
+
+def create_utc_timestamp(cs_timestamp: int):
+    """Create a UTC timestamp from a localzone Crownstone timestamp."""
+    # get the timezone of this computer
+    tz = get_localzone()
+    date = datetime.fromtimestamp(cs_timestamp, tz)
+    # calculate the offset
+    utc_offset = date.utcoffset().total_seconds()
+    # utc is the positive east, calculate timestamp
+    return cs_timestamp - utc_offset
+
+
+def process_energy_update(
+    next_data_point: EnergyData, previous_data_point: EnergyData
+) -> None:
+    """
+    Process an update for the energy usage.
+
+    It's possible for devices to reboot (power loss, sw update, crash).
+    After a reboot the saved value for energy goes back to zero.
+    A check is done to prevent the value in HA from resetting as well.
+    """
+    next_value = next_data_point.energy_usage
+    next_timestamp = next_data_point.timestamp
+    previous_raw_value = previous_data_point.energy_usage
+    previous_value = previous_data_point.corrected_energy_usage
+    previous_timestamp = previous_data_point.timestamp
+
+    # create data objects from timestamps
+    # check if a month or year is past
+    # we set the energy usage back to 0 each month
+    if previous_timestamp is not None:
+        next_date = datetime.fromtimestamp(next_timestamp, timezone.utc)
+        previous_date = datetime.fromtimestamp(previous_timestamp, timezone.utc)
+
+        if next_date.year > previous_date.year or next_date.month > previous_date.month:
+            next_data_point.corrected_energy_usage = 0
+            next_data_point.first_measurement = True
+            return
+
+    # initial HA value, make sure we start at 0 in HA
+    # set first measurement flag to save the start date
+    if previous_raw_value == 0 and previous_timestamp is None:
+        next_value = 0
+        next_data_point.first_measurement = True
+
+    # restored data point, set new measurement to saved value
+    elif previous_data_point.restored_state:
+        next_value = previous_value
+
+    else:
+        # calculate offset value
+        offset_value = previous_value - previous_raw_value
+
+        # if the new value is greater than the offset value, accept measurement
+        # if it is smaller, add the new value to the offsetvalue
+        # check if the new value is below the old value, but just a little, since it can increase fast
+        if next_value < previous_raw_value * 0.9:
+            next_value += previous_value
+        else:
+            next_value += offset_value
+
+        # ignore change if next value is still smaller, energy decrease unsupported
+        if next_value < previous_value:
+            next_value = previous_value
+
+    # set new value
+    next_data_point.corrected_energy_usage = next_value

custom_components/crownstone/hub.py

@@ -75,10 +75,9 @@ async def async_setup(self) -> bool:
         self.uart_manager.start()
 
         # Create SSE instance
-        # NOTE: hass loop is currently used as parameter,
-        # to run coroutines within the CrownstoneSSE eventbus in the HA loop.
-        # this is because CrownstoneSSE runs in an other OS thread.
-        self.sse = CrownstoneSSE(customer_email, customer_password, self.hass.loop)
+        self.sse = CrownstoneSSE(
+            customer_email, customer_password, asyncio.get_running_loop()
+        )
         self.sse.set_access_token(self.cloud.access_token)
         self.sse.start()