feat: Allow integrations to provide entity icon and description

lib/entities/button.ts

@@ -6,7 +6,7 @@
  * @license Apache License 2.0, see LICENSE for more details.
  */
 
-import { CommandHandler, Entity, EntityType, EntityName } from "./entity.js";
+import { CommandHandler, Entity, EntityType, EntityName, EntityDescription } from "./entity.js";
 import log from "../loggers.js";
 
 export enum ButtonStates {
@@ -35,6 +35,8 @@ export enum ButtonCommands {
 }
 
 export interface ButtonParams {
+  icon?: string;
+  description?: EntityDescription;
   state?: ButtonStates;
   area?: string;
   cmdHandler?: CommandHandler;
@@ -59,11 +61,17 @@ export class Button extends Entity {
    * @param id The entity identifier. Must be unique inside the integration driver.
    * @param name The human-readable name of the entity.
    *        Either a string, which will be mapped to English, or a Map / Object containing multiple language strings.
-   * @param {ButtonParams} [params] Entity parameters.
+   * @param {ButtonParams} [params] Button-entity parameters.
    * @throws AssertionError if invalid parameters are specified.
    */
-  constructor(id: string, name: EntityName, { state = ButtonStates.Available, area, cmdHandler }: ButtonParams = {}) {
+  constructor(
+    id: string,
+    name: EntityName,
+    { icon, description, state = ButtonStates.Available, area, cmdHandler }: ButtonParams = {}
+  ) {
     super(id, name, EntityType.Button, {
+      icon,
+      description,
       features: ["press"],
       attributes: {
         state: state

lib/entities/climate.ts

@@ -6,7 +6,7 @@
  * @license Apache License 2.0, see LICENSE for more details.
  */
 
-import { CommandHandler, Entity, EntityType, EntityName } from "./entity.js";
+import { CommandHandler, Entity, EntityType, EntityName, EntityDescription } from "./entity.js";
 import log from "../loggers.js";
 
 // Climate entity states
@@ -167,6 +167,8 @@ export enum TemperatureUnit {
 
 // Define types for the parameters in the constructor
 export interface ClimateParams {
+  icon?: string;
+  description?: EntityDescription;
   features?: ClimateFeatures[];
   attributes?: Partial<Record<ClimateAttributes, ClimateStates | number>>;
   deviceClass?: string;
@@ -190,15 +192,24 @@ export class Climate extends Entity {
    * @param {string} id The entity identifier. Must be unique inside the integration driver.
    * @param {EntityName} name The human-readable name of the entity.
    *        Either a string, which will be mapped to English, or a Map / Object containing multiple language strings.
-   * @param {ClimateParams} [params] Entity parameters.
+   * @param {ClimateParams} [params] Climate-entity parameters.
    * @throws AssertionError if invalid parameters are specified.
    */
   constructor(
     id: string,
     name: EntityName,
-    { features, attributes, deviceClass, options, area, cmdHandler }: ClimateParams = {}
+    { icon, description, features, attributes, deviceClass, options, area, cmdHandler }: ClimateParams = {}
   ) {
-    super(id, name, EntityType.Climate, { features, attributes, deviceClass, options, area, cmdHandler });
+    super(id, name, EntityType.Climate, {
+      icon,
+      description,
+      features,
+      attributes,
+      deviceClass,
+      options,
+      area,
+      cmdHandler
+    });
 
     log.debug(`Climate entity created with id: ${this.id}`);
   }

lib/entities/cover.ts

@@ -6,7 +6,7 @@
  * @license Apache License 2.0, see LICENSE for more details.
  */
 
-import { CommandHandler, Entity, EntityType, EntityName } from "./entity.js";
+import { CommandHandler, Entity, EntityType, EntityName, EntityDescription } from "./entity.js";
 import log from "../loggers.js";
 
 // Cover entity states
@@ -158,6 +158,8 @@ export enum CoverOptions {}
 
 // Define types for the parameters in the constructor
 export interface CoverParams {
+  icon?: string;
+  description?: EntityDescription;
   features?: CoverFeatures[];
   attributes?: Partial<Record<CoverAttributes, CoverStates | number>>;
   deviceClass?: CoverDeviceClasses;
@@ -182,15 +184,24 @@ export class Cover extends Entity {
    * @param {string} id The entity identifier. Must be unique inside the integration driver.
    * @param {EntityName} name The human-readable name of the entity.
    *        Either a string, which will be mapped to English, or a Map / Object containing multiple language strings.
-   * @param {CoverParams} [params] Entity parameters.
+   * @param {CoverParams} [params] Cover-entity parameters.
    * @throws AssertionError if invalid parameters are specified.
    */
   constructor(
     id: string,
     name: EntityName,
-    { features, attributes, deviceClass, options, area, cmdHandler }: CoverParams = {}
+    { icon, description, features, attributes, deviceClass, options, area, cmdHandler }: CoverParams = {}
   ) {
-    super(id, name, EntityType.Cover, { features, attributes, deviceClass, options, area, cmdHandler });
+    super(id, name, EntityType.Cover, {
+      icon,
+      description,
+      features,
+      attributes,
+      deviceClass,
+      options,
+      area,
+      cmdHandler
+    });
 
     log.debug(`Cover entity created with id: ${this.id}`);
   }

lib/entities/entities.ts

@@ -120,6 +120,8 @@ export class Entities extends EventEmitter {
    * Returned properties are:
    * - entity_id
    * - entity_type
+   * - icon
+   * - description
    * - device_id
    * - features
    * - name
@@ -138,6 +140,8 @@ export class Entities extends EventEmitter {
       const entity = {
         entity_id: value.id,
         entity_type: value.entity_type,
+        icon: value.icon,
+        description: value.description,
         device_id: value.device_id,
         features: value.features,
         name: value.name,

lib/entities/entity.ts

@@ -34,13 +34,16 @@ export enum EntityType {
 }
 
 export type EntityName = string | { [key: string]: string };
+export type EntityDescription = string | { [key: string]: string };
 export type EntityAttributes = { [key: string]: string | number | boolean | string[] };
 export type EntityOptions = { [key: string]: string | number | boolean | object };
 export type EntityCommandParams = { [key: string]: string | number | boolean };
 
 export type CommandHandler = (entity: Entity, command: string, params?: EntityCommandParams) => Promise<StatusCodes>;
 
 export interface EntityParams {
+  icon?: string;
+  description?: EntityDescription;
   features?: string[];
   attributes?: EntityAttributes;
   deviceClass?: string;
@@ -56,6 +59,10 @@ export class Entity {
   public name: EntityName;
   /** Entity device type name: one of the supported entities. */
   public entity_type: EntityType;
+  /** Optional icon of the entity. If not specified, a default icon is used based on the entity type. */
+  public icon?: string;
+  /** Optional description of the entity. */
+  public description?: EntityDescription;
 
   /** Optional associated device, if the integration driver supports multiple devices. */
   public device_id?: string;
@@ -84,13 +91,24 @@ export class Entity {
     id: string,
     name: string | { [key: string]: string },
     entityType: EntityType,
-    { features = [], attributes = { state: "UNKNOWN" }, deviceClass, options, area, cmdHandler }: EntityParams = {}
+    {
+      icon,
+      description,
+      features = [],
+      attributes = { state: "UNKNOWN" },
+      deviceClass,
+      options,
+      area,
+      cmdHandler
+    }: EntityParams = {}
   ) {
     this.id = id;
 
     const languageName = toLanguageObject(name);
     assert(languageName);
     this.name = languageName || "?";
+    this.icon = icon;
+    this.description = toLanguageObject(description) || undefined;
 
     this.entity_type = entityType;
     this.features = features;

lib/entities/light.ts

@@ -6,7 +6,7 @@
  * @license Apache License 2.0, see LICENSE for more details.
  */
 
-import { CommandHandler, Entity, EntityType, EntityName } from "./entity.js";
+import { CommandHandler, Entity, EntityType, EntityName, EntityDescription } from "./entity.js";
 import log from "../loggers.js";
 
 /**
@@ -117,6 +117,8 @@ export enum LightOptions {
 }
 
 export interface LightParams {
+  icon?: string;
+  description?: EntityDescription;
   features?: LightFeatures[];
   attributes?: Partial<Record<LightAttributes, LightStates | number>>;
   deviceClass?: string;
@@ -139,15 +141,24 @@ export class Light extends Entity {
    * @param {string} id The entity identifier. Must be unique inside the integration driver.
    * @param {EntityName} name The human-readable name of the entity.
    *        Either a string, which will be mapped to English, or a Map / Object containing multiple language strings.
-   * @param {LightParams} [params] Entity parameters.
+   * @param {LightParams} [params] Light-entity parameters.
    * @throws AssertionError if invalid parameters are specified.
    */
   constructor(
     id: string,
     name: EntityName,
-    { features, attributes, deviceClass, options, area, cmdHandler }: LightParams = {}
+    { icon, description, features, attributes, deviceClass, options, area, cmdHandler }: LightParams = {}
   ) {
-    super(id, name, EntityType.Light, { features, attributes, deviceClass, options, area, cmdHandler });
+    super(id, name, EntityType.Light, {
+      icon,
+      description,
+      features,
+      attributes,
+      deviceClass,
+      options,
+      area,
+      cmdHandler
+    });
 
     log.debug(`Light entity created with id: ${this.id}`);
   }

lib/entities/media_player.ts

@@ -6,7 +6,7 @@
  * @license Apache License 2.0, see LICENSE for more details.
  */
 
-import { Entity, EntityType, CommandHandler, EntityName } from "./entity.js";
+import { Entity, EntityType, CommandHandler, EntityName, EntityDescription } from "./entity.js";
 import log from "../loggers.js";
 import { Pagination, Paging, StatusCodes } from "../api_definitions.js";
 
@@ -733,6 +733,8 @@ export enum RepeatMode {
 }
 
 export interface MediaPlayerParams {
+  icon?: string;
+  description?: EntityDescription;
   features?: MediaPlayerFeatures[];
   attributes?: Partial<
     Record<MediaPlayerAttributes, MediaPlayerStates | RepeatMode | string | string[] | number | boolean>
@@ -758,15 +760,24 @@ export class MediaPlayer extends Entity {
    * @param {string} id The entity identifier. Must be unique inside the integration driver.
    * @param {EntityName} name The human-readable name of the entity.
    *        Either a string, which will be mapped to English, or a Map / Object containing multiple language strings.
-   * @param {MediaPlayerParams} [params] Entity parameters.
+   * @param {MediaPlayerParams} [params] Media-player-entity parameters.
    * @throws AssertionError if invalid parameters are specified.
    */
   constructor(
     id: string,
     name: EntityName,
-    { features, attributes, deviceClass, options, area, cmdHandler }: MediaPlayerParams = {}
+    { icon, description, features, attributes, deviceClass, options, area, cmdHandler }: MediaPlayerParams = {}
   ) {
-    super(id, name, EntityType.MediaPlayer, { features, attributes, deviceClass, options, area, cmdHandler });
+    super(id, name, EntityType.MediaPlayer, {
+      icon,
+      description,
+      features,
+      attributes,
+      deviceClass,
+      options,
+      area,
+      cmdHandler
+    });
 
     log.debug(`MediaPlayer entity created with id: ${this.id}`);
   }

lib/entities/remote.ts

@@ -6,7 +6,7 @@
  * @license Apache License 2.0, see LICENSE for more details.
  */
 
-import { CommandHandler, Entity, EntityType, EntityName, EntityOptions } from "./entity.js";
+import { CommandHandler, Entity, EntityType, EntityName, EntityOptions, EntityDescription } from "./entity.js";
 import { DeviceButtonMapping, EntityCommand, UiPage } from "./ui.js";
 import log from "../loggers.js";
 import assert from "node:assert";
@@ -165,6 +165,8 @@ export function createRemoteSequenceCmd(
 }
 
 export interface RemoteParams {
+  icon?: string;
+  description?: EntityDescription;
   features?: RemoteFeatures[];
   attributes?: Partial<Record<RemoteAttributes, RemoteStates>>;
   simpleCommands?: string[];
@@ -186,13 +188,23 @@ export class Remote extends Entity {
    *
    * @param id The entity identifier. Must be unique inside the integration driver.
    * @param name The human-readable name of the entity.
-   * @param params Entity parameters.
+   * @param params Remote-entity parameters.
    * @throws AssertionError if invalid parameters are specified.
    */
   constructor(
     id: string,
     name: EntityName,
-    { features, attributes, simpleCommands, buttonMapping, uiPages, area, cmdHandler }: RemoteParams = {}
+    {
+      icon,
+      description,
+      features,
+      attributes,
+      simpleCommands,
+      buttonMapping,
+      uiPages,
+      area,
+      cmdHandler
+    }: RemoteParams = {}
   ) {
     const options: EntityOptions = {};
     if (simpleCommands) {
@@ -205,7 +217,7 @@ export class Remote extends Entity {
       options[RemoteOptions.UserInterface] = { pages: uiPages };
     }
 
-    super(id, name, EntityType.Remote, { features, attributes, options, area, cmdHandler });
+    super(id, name, EntityType.Remote, { icon, description, features, attributes, options, area, cmdHandler });
 
     log.debug(`Remote entity created with id: ${this.id}`);
   }

lib/entities/sensor.ts

@@ -6,7 +6,7 @@
  * @license Apache License 2.0, see LICENSE for more details.
  */
 
-import { Entity, EntityType, EntityName } from "./entity.js";
+import { Entity, EntityType, EntityName, EntityDescription } from "./entity.js";
 import log from "../loggers.js";
 
 /**
@@ -120,6 +120,8 @@ export enum SensorOptions {
 }
 
 export interface SensorParams {
+  icon?: string;
+  description?: EntityDescription;
   attributes?: Partial<Record<SensorAttributes, SensorStates | number | string>>;
   deviceClass?: SensorDeviceClasses;
   options?: Partial<Record<SensorOptions, string | number>>;
@@ -138,11 +140,15 @@ export class Sensor extends Entity {
    *
    * @param id The entity identifier. Must be unique inside the integration driver.
    * @param name The human-readable name of the entity.
-   * @param params Entity parameters.
+   * @param params Sensor-entity parameters.
    * @throws AssertionError if invalid parameters are specified.
    */
-  constructor(id: string, name: EntityName, { attributes, deviceClass, options, area }: SensorParams = {}) {
-    super(id, name, EntityType.Sensor, { attributes, deviceClass, options, area });
+  constructor(
+    id: string,
+    name: EntityName,
+    { icon, description, attributes, deviceClass, options, area }: SensorParams = {}
+  ) {
+    super(id, name, EntityType.Sensor, { icon, description, attributes, deviceClass, options, area });
 
     log.debug(`Sensor entity created with id: ${this.id}`);
   }