Entity Names and IDs

Entity names and IDs

How the integration names things, and how to find the entity id an automation needs. The recipes in this wiki use short placeholder ids such as sensor.inverter_ac_power; this page tells you what to put in their place.

One device per data block

The integration creates one Home Assistant device per SunSpec block it polls, per config entry. An inverter that exposes the common block, the three-phase inverter block and the MPPT block shows up as three devices on the Devices & Services page.

A device is named <base> <block label>:

Part	Where it comes from	Example
base	The Device name prefix option if you set one, otherwise the model string the inverter reports in its common block	Symo GEN24 4.0 or Garage
block label	The SunSpec label of the block, shortened for the long ones	Inverter (Three Phase), MPPT, Meter (Three Phase Wye), Immediate Controls

So a Fronius without a prefix gets Symo GEN24 4.0 Inverter (Three Phase), and the same inverter with the prefix Garage gets Garage Inverter (Three Phase). The prefix is what tells two inverters of the same type apart.

Renaming a device in Home Assistant is safe. The integration never overwrites a name you set yourself.

Entity names

An entity carries only the name of its data point. Home Assistant puts the device name in front for display, so the entity AC power on the device above is shown as Symo GEN24 4.0 Inverter (Three Phase) AC power.

The common points have curated names (AC power, Lifetime energy produced, DC voltage, Operating state, Cabinet temperature and so on). Every other point uses the label from the SunSpec model definition, which is already readable English.

Points inside a repeating group carry the group and its index in front: the second MPPT input's DC power is Module 1 DC Power. Indices start at 0.

Entity IDs

Home Assistant builds the entity id from device name plus entity name the first time the entity is created, lower-cased, with everything that is not a letter or digit turned into underscores:

sensor.symo_gen24_4_0_inverter_three_phase_ac_power
sensor.garage_inverter_three_phase_ac_power
sensor.garage_mppt_module_1_dc_power
number.garage_immediate_controls_export_limit
select.garage_storage_battery_control_mode

Two consequences:

• The id is fixed at creation. Setting or changing the prefix later renames the device, not the existing entity ids. Change the id by hand in the entity settings if you want it to match.
• Migrated entities keep their old ids. If you came from cjne/ha-sunspec, your entities still have ids like sensor.inverter_three_phase_watts, and every automation that used them keeps working.

Finding the id you need

Settings -> Devices & Services -> SunSpec Modbus -> the device -> click the entity -> cog icon. The id is at the top of the settings dialog.

Faster when you know the SunSpec point name: Developer tools -> States, type the point name into the attributes filter. Every sensor from this integration carries a sunspec_key attribute holding the point name, so sunspec_key: W lists exactly the AC power sensors of every inverter and meter you have.

Attributes

Attribute	On	Contents
integration	every sensor	sunspec2
sunspec_key	every sensor	The SunSpec point name, W, WH, module:0:DCW
label	every sensor	The label from the model definition
raw	enum and bitfield sensors	The numeric value behind the decoded state
active_flags	bitfield sensors	The set flags as a list, so a template does not have to split the state string on commas

Diagnostic and disabled entities

Temperatures, operating states and event bitfields are tagged Diagnostic, so the device page lists them below the measurements.

A few entities exist but start disabled, because they never change or are only noise:

• the vendor event bitfields and the vendor operating state
• the nameplate ratings from block 120 (rated power, apparent power, current, lifetime energy) and the configured maximum and voltage reference from block 121
• among the write controls: the export limit revert value, the stays on after revert switch, the active power setpoint mode and the battery minimum reserve

To switch one on: open the entity, cog icon, Enabled. It gets its first value on the next poll.

Units

Lifetime energy comes in watt-hours, as SunSpec reports it. The README shows how to have Home Assistant convert the entity and its history to kWh.

Percentages of a reference quantity (% WMax, % WChaMax, % VRef) are plain percent in Home Assistant. Which quantity they refer to is in the entity name.

Units Home Assistant has no equivalent for, such as apparent energy in VAh or rates like % WMax/min, are dropped rather than passed through as text. The value is still there, it just does not pretend to be a measurable quantity, so it never starts a statistics series the recorder cannot convert.

Looking a point up

The sunspec_key matches the point name in the model definition. The definitions ship with the integration under pysunspec2/models/json/, one file per block; the desc field of a point is the SunSpec description. SunSpec models explained says which file to open.