Integration device hierarchy and device attribute information

[thomluther]

Device hierarchy

The Anker Solix integration will structure all entities under a device hierarchy in Home Assistant. Currently there are following device levels:

1. Account device

This is only a virtual 'device' type that is used as container to hold all entities that do not belong to a dedicated system or device but to your account. It also holds entities that belong to the Api session, which is used for communication to the configured Anker account. It also links to stand alone devices, which are not assigned to any power system (System device).

2. System device

This device reflects a Power System as it was created in the Anker mobile app. The Api calls it a site and each site comes with a unique ID (site_id) to identify it in the cloud. The integration will show the site_id as serial number of the system devices. System devices hold all entities that belong to the system and link to end devices that are managed by that system. An end device can be configured only into a single system. No sharing across multiple sites in the cloud is allowed for any end device. For example, the smart meter or smart plugs can be assigned only to a single power system for exclusive use in that system. With the assignment to a system, the system owner becomes also the exclusive device owner.
While the Anker app allows to share systems with different accounts, this sharing is only permitted on a system level, but not on a device level. Furthermore permission restrictions apply to the shared sites in the cloud and as such, system members cannot access or modify any device details, neither in the Anker app nor via the cloud Api.

3. End device

This reflects the end devices in a system, or stand alone devices, such as a Solarbank, Smart Meter, Smart Plug, Power Panel, X1 main module etc. If there are accessories attached to the device, like the 0 W Switch for Solarbank 1, their entities are presented within the device because accessories typically have little to no information available. End devices may be linked to sub devices, which are typically used only in larger home energy systems like the X1.

4. Sub device

This reflects a sub device that is managed by a main device in a system, for example a battery module in an X1 home energy system. Sub devices may report some entities, but typically do not report own controllable entities. Any general settings are typically managed via their main device to which they will be linked.

5. Vehicle device

This reflects a virtual device that is bound to the Account device. It is used to collect all entities that belong to an electronic vehicle definition for the user account. Each account can create/define multiple vehicles, which will be required to manage EV charging with the Solix V1 EV Charger. The EV charger end device can either be bound to its dedicated EV Charger system, a HES system like the X1 or a Solarbank Multisystem.

Device attributes

All device types used by the integration will have defined device attributes. Those device attributes are shared by all device entities, However, device attributes cannot be seen in the entity attributes on the HA developer tabs panel. They are typically only reflected in the UI when using the device panels.
The HA Jinja templates however offer functions to get device attributes in templates. The easiest way to query the device attributes is using any entity ID of the device type that you are interested in. For example you can get system device attributes by using any of the system entity IDs.

Following are examples how you can get the attributes for your system and end devices. Likewise you can use it for account or sub devices. But be aware, that not every device attribute is set for each device type.

End device attributes:
  {{'Name: ' + device_attr('sensor.sb_e1600_solar_power','name')}}
  {{'Model: ' + device_attr('sensor.sb_e1600_solar_power','model')}}
  {{'Model ID: ' + device_attr('sensor.sb_e1600_solar_power','model_id')}}
  {{'Manufacturer: ' + device_attr('sensor.sb_e1600_solar_power','manufacturer')}}
  {{'Serial: ' + device_attr('sensor.sb_e1600_solar_power','serial_number')}}
  {{'SW Version: ' + device_attr('sensor.sb_e1600_solar_power','sw_version')}}
 
System device attributes:
  {{'Name: ' + device_attr('sensor.system_bkw_yield_total','name')}}
  {{'Model: ' + device_attr('sensor.system_bkw_yield_total','model')}}
  {{'Model ID: ' + device_attr('sensor.system_bkw_yield_total','model_id')}}
  {{'Manufacturer: ' + device_attr('sensor.system_bkw_yield_total','manufacturer')}}
  {{'Serial: ' + device_attr('sensor.system_bkw_yield_total','serial_number')}}

The example can be used with your entities in the developer tabs for templates and may present your device attributes accordingly.

End device attributes:
  Name: SB E1600
  Model: Solarbank E1600
  Model ID: A17C0
  Manufacturer: Anker
  Serial: A### masked ###6
  SW Version: v2.0.9
 
System device attributes:
  Name: System BKW
  Model: Solarbank Site
  Model ID: Type 2
  Manufacturer: Anker
  Serial: 7#### masked ####f-#### masked ####7