@iobroker/dm-utils 1.0.16 → 2.0.1

package/README.md

@@ -73,6 +73,14 @@ the `DeviceManagement` implementation's `handleXxxAction()` is called, and the a
 The communication between the `ioBroker.device-manager` tab and the adapter happens through `sendTo`.
 
 **IMPORTANT:** make sure your adapter doesn't handle `sendTo` messages starting with `dm:`, otherwise the communication will not work.
+- Use for Example this on the top of your onMessage Methode:
+
+```js
+if (obj.command?.startsWith('dm:')) {
+    // Handled by Device Manager class itself, so ignored here
+    return;
+}
+```
 
 ### Access adapter methods
 
@@ -116,12 +124,11 @@ Every array entry is an object of type `DeviceInfo` which has the following prop
 
 - `id` (string): a unique (human-readable) identifier of the device (it must be unique for your adapter instance only)
 - `name` (string or translations): the human-readable name of this device
-- `status` (optional): the current status of the device, which can be one of:
-  - `"disconnected"`
-  - `"connected"`
-  - an object containing:
-    - `icon` (string): an icon depicting the status of the device (see below for details)
-    - `description` (string, optional): a text that will be shown as a tooltip on the status
+- `status` (optional): the current status of the device, which has to be an object containing:
+    - `connection` (string): alowed values are: `"connected"` / `"disconnected"`
+    - `rssi` (number): rssi value of the connection
+    - `battery` (boolean / number): if boolean: false: Battery empty. If number: battery level of the device (shows also a battery symbol at card)
+    - `warning` (boolean / string): if boolean: true indicates a warning. If string: shows also the warning with mouseover
 - `actions` (array, optional): an array of actions that can be performed on the device; each object contains:
   - `id` (string): unique identifier to recognize an action (never shown to the user)
   - `icon` (string): an icon shown on the button (see below for details)
@@ -129,19 +136,26 @@ Every array entry is an object of type `DeviceInfo` which has the following prop
   - `disabled` (boolean, optional): if set to `true`, the button can't be clicked but is shown to the user
 - `hasDetails` (boolean, optional): if set to `true`, the row of the device can be expanded and details are shown below
 
+Possible strings for device icons are here: [TYPE ICONS](https://github.com/ioBroker/adapter-react-v5/blob/main/src/Components/DeviceType/DeviceTypeIcon.tsx#L68)
+<br/>
+Possible strings for action icons are here: [ACTION NAMES](https://github.com/ioBroker/dm-gui-components/blob/main/src/Utils.tsx#L128)
+<br/>
+Possible strings for configuration icons are here: [CONFIGURATION TYPES](https://github.com/ioBroker/dm-utils/blob/b3e54ecfaedd6a239beec59c5deb8117d1d59d7f/src/types/common.ts#L110)
+<br/>
 ### `getInstanceInfo()`
 
 This method allows the device manager tab to gather some general information about the instance. It is called when the user opens the tab.
 
 If you override this method, the returned object must contain:
 
-- `apiVersion` (string): the supported API version; must currently always be `"v1"`
+- `apiVersion` (string): the supported API version; must be `"v1"` or `"v2"` (if "backend to GUI communication" is used or IDs instead of values)
 - `actions` (array, optional): an array of actions that can be performed on the instance; each object contains:
   - `id` (string): unique identifier to recognize an action (never shown to the user)
   - `icon` (string): an icon shown on the button (see below for details)
   - `title` (string): the title shown next to the icon on the button
   - `description` (string, optional): a text that will be shown as a tooltip on the button
   - `disabled` (boolean, optional): if set to `true`, the button can't be clicked but is shown to the user
+- `communicationStateId` (string) (optional): the ID of the state that is used by backend for communication with front-end (only API v2)
 
 ### `getDeviceDetails(id: string)`
 
@@ -295,12 +309,45 @@ This method returns a promise that resolves to a `ProgressDialog` object.
       - `label` (string, optional): change the label to the right of the progress bar
 - `close()`
   - Closes the progress dialog (and allows you to open other dialogs)
+
+### `sendCommandToGui(command: BackendToGuiCommand)`
+
+Sends command to GUI to add/update/delete devices or to update the status of device.
+
+**It is suggested** to use the state's ID directly in DeviceInfo structure instead of sending the command every time to GUI on status update.  
+
+See example below:
+```ts
+class MyAdapterDeviceManagement extends DeviceManagement<MyAdapter> {
+    protected listDevices(): RetVal<DeviceInfo[]>{
+        const deviceInfo: DeviceInfo = {
+          id: 'uniqieID',
+          name: 'My device',
+          icon: 'node', // find possible icons here: https://github.com/ioBroker/adapter-react-v5/blob/main/src/Components/DeviceType/DeviceTypeIcon.tsx#L68
+          manufacturer: { objectId: 'uniqieID', property: 'native.manufacturer' },
+          model: { objectId: 'uniqieID', property: 'native.model' },
+          status: {
+            battery: { stateId: 'uniqieID.DevicePower0.BatteryPercent' },
+            connection: { stateId: 'uniqieID.online', mapping: {'true': 'connected', 'false': 'disconnected'} },
+            rssi: { stateId: 'uniqieID.rssi' },
+          },
+          hasDetails: true,
+        };
+        return [deviceInfo];
+    }
+}
+```
   
 <!--
 	Placeholder for the next version (at the beginning of the line):
 	### **WORK IN PROGRESS**
 -->
 ## Changelog
+### 2.0.1 (2026-01-28)
+* (@GermanBluefox) BREAKING: Admin/GUI must have version 9 (or higher) of `dm-gui-components`
+* (@GermanBluefox) Added types to update status of device directly from state
+* (@GermanBluefox) Added backend to GUI communication possibility
+
 ### 1.0.16 (2026-01-02)
 * (@GermanBluefox) Added `ignoreApplyDisabled` flag
 * (@GermanBluefox) Added `update` icon

package/build/DeviceManagement.d.ts

@@ -2,13 +2,16 @@ import type { AdapterInstance } from '@iobroker/adapter-core';
 import type { ActionContext } from './ActionContext';
 import type { ProgressDialog } from './ProgressDialog';
 import { type DeviceDetails, type DeviceInfo, type ErrorResponse, type InstanceDetails, type JsonFormData, type JsonFormSchema, type RefreshResponse, type RetVal, type ActionButton } from './types';
-import type { ControlState } from './types/base';
+import type { BackendToGuiCommand, ControlState } from './types/base';
 export declare abstract class DeviceManagement<T extends AdapterInstance = AdapterInstance> {
     protected readonly adapter: T;
     private instanceInfo?;
     private devices?;
+    private readonly communicationStateId;
     private readonly contexts;
-    constructor(adapter: T);
+    constructor(adapter: T, communicationStateId?: string | boolean);
+    private ensureCommunicationState;
+    protected sendCommandToGui(command: BackendToGuiCommand): Promise<void>;
     protected get log(): ioBroker.Log;
     protected getInstanceInfo(): RetVal<InstanceDetails>;
     protected abstract listDevices(): RetVal<DeviceInfo[]>;

package/build/DeviceManagement.js

@@ -3,16 +3,55 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MessageContext = exports.DeviceManagement = void 0;
 const types_1 = require("./types");
 class DeviceManagement {
-    constructor(adapter) {
+    constructor(adapter, communicationStateId) {
         this.adapter = adapter;
         this.contexts = new Map();
         adapter.on('message', this.onMessage.bind(this));
+        if (communicationStateId === true) {
+            // use standard ID `info.deviceManager`
+            this.communicationStateId = 'info.deviceManager';
+        }
+        else if (communicationStateId) {
+            this.communicationStateId = communicationStateId;
+        }
+        if (this.communicationStateId) {
+            this.ensureCommunicationState().catch(e => this.log().error(`Cannot initialize communication state: ${e}`));
+        }
+    }
+    async ensureCommunicationState() {
+        let stateObj = await this.adapter.getObjectAsync(this.communicationStateId);
+        if (!stateObj) {
+            stateObj = {
+                _id: this.communicationStateId,
+                type: 'state',
+                common: {
+                    expert: true,
+                    name: 'Communication with GUI for device manager',
+                    type: 'string',
+                    role: 'state',
+                    def: '',
+                    read: true,
+                    write: false,
+                },
+                native: {},
+            };
+            await this.adapter.setObjectAsync(this.communicationStateId, stateObj);
+        }
+    }
+    async sendCommandToGui(command) {
+        if (this.communicationStateId) {
+            await this.adapter.setStateAsync(this.communicationStateId, JSON.stringify(command), true);
+        }
+        else {
+            throw new Error('Communication state not found');
+        }
     }
     get log() {
         return this.adapter.log;
     }
     getInstanceInfo() {
-        return { apiVersion: 'v1' };
+        // Overload this method if your adapter does not use BackendToGui communication and States/Objects in DeviceInfo
+        return { apiVersion: 'v2', communicationStateId: this.communicationStateId || undefined };
     }
     getDeviceDetails(id) {
         return { id, schema: {} };

package/build/types/base.d.ts

@@ -1,4 +1,4 @@
-import type { ActionContext, ConfigConnectionType, ErrorResponse, MessageContext } from '..';
+import type { ActionContext, ConfigConnectionType, ErrorResponse, MessageContext, ValueOrObject, ValueOrState, ValueOrStateOrObject } from '..';
 import type { ApiVersion, DeviceRefresh, DeviceStatus, RetVal } from './common';
 type ActionType = 'api' | 'adapter';
 export type Color = 'primary' | 'secondary' | (string & {});
@@ -97,33 +97,36 @@ export interface DeviceAction<T extends ActionType = 'api'> extends ActionBase<T
     }>;
 }
 export interface InstanceDetails<T extends ActionType = 'api'> {
+    /** API Version: 1 - till 2025 (including), 2 - from 2026 */
     apiVersion: ApiVersion;
     actions?: InstanceAction<T>[];
+    /** ID of state used for communication with GUI */
+    communicationStateId?: string;
 }
 export interface DeviceInfo<T extends ActionType = 'api'> {
     /** ID of the action. Should be unique only in one adapter. Other adapters could have same names */
     id: string;
     /** Name of the device. It will be shown in the card header */
-    name: ioBroker.StringOrTranslated;
+    name: ValueOrObject<ioBroker.StringOrTranslated>;
     /** base64 or url icon for device card */
-    icon?: string;
-    manufacturer?: ioBroker.StringOrTranslated;
-    model?: ioBroker.StringOrTranslated;
+    icon?: ValueOrState<string>;
+    manufacturer?: ValueOrStateOrObject<ioBroker.StringOrTranslated>;
+    model?: ValueOrStateOrObject<ioBroker.StringOrTranslated>;
     /** Color or 'primary', 'secondary' for the text in the card header */
-    color?: Color;
+    color?: ValueOrState<Color>;
     /** Background color of card header (you can use primary, secondary or color rgb value or hex) */
-    backgroundColor?: Color;
+    backgroundColor?: ValueOrState<Color>;
     status?: DeviceStatus | DeviceStatus[];
     /** Connection type, how the device is connected */
-    connectionType?: ConfigConnectionType;
+    connectionType?: ValueOrStateOrObject<ConfigConnectionType>;
     /** If this flag is true or false, the according indication will be shown. Additionally, if ACTIONS.ENABLE_DISABLE is implemented, this action will be sent to backend by clicking on this indication */
-    enabled?: boolean;
+    enabled?: ValueOrState<boolean>;
     /** List of actions on the card */
     actions?: DeviceAction<T>[];
     /** List of controls on the card. The difference of controls and actions is that the controls can show status (e.g. on/off) and can work directly with states */
     controls?: DeviceControl<T>[];
     /** If true, the button `more` will be shown on the card and called `dm:deviceDetails` action to get the details  */
-    hasDetails?: boolean;
+    hasDetails?: ValueOrStateOrObject<boolean>;
     /** Device type for grouping */
     group?: {
         key: string;
@@ -131,4 +134,30 @@ export interface DeviceInfo<T extends ActionType = 'api'> {
         icon?: string;
     };
 }
+export interface BackendToGuiCommandDeviceInfoUpdate {
+    /** Used for updating and for adding new device */
+    command: 'infoUpdate';
+    /** Device ID */
+    deviceId: string;
+    /** Backend can send directly new information about device to avoid extra request from GUI */
+    info?: DeviceInfo;
+}
+export interface BackendToGuiCommandDeviceStatusUpdate {
+    /** Status of device was updated */
+    command: 'statusUpdate';
+    /** Device ID */
+    deviceId: string;
+    /** Backend can send directly new status to avoid extra request from GUI */
+    status?: DeviceStatus;
+}
+export interface BackendToGuiCommandDeviceDelete {
+    /** Device was deleted */
+    command: 'delete';
+    deviceId: string;
+}
+export interface BackendToGuiCommandAllUpdate {
+    /** Read ALL information about all devices anew */
+    command: 'all';
+}
+export type BackendToGuiCommand = BackendToGuiCommandDeviceInfoUpdate | BackendToGuiCommandDeviceStatusUpdate | BackendToGuiCommandDeviceDelete | BackendToGuiCommandAllUpdate;
 export {};

package/build/types/common.d.ts

@@ -1,10 +1,23 @@
-export type ApiVersion = 'v1';
+export type ApiVersion = 'v1' | 'v2';
 export type ConfigConnectionType = 'lan' | 'wifi' | 'bluetooth' | 'thread' | 'z-wave' | 'zigbee' | 'other';
+export type ValueOrObject<T> = T | {
+    objectId: string;
+    property: string;
+};
+export type ValueOrState<T, M = {
+    [value: string | number]: string;
+}> = T | {
+    stateId: string;
+    mapping?: M;
+};
+export type ValueOrStateOrObject<T> = T | ValueOrObject<T> | ValueOrState<T>;
 export type DeviceStatus = 'connected' | 'disconnected' | {
-    battery?: number | boolean | 'charging' | string;
-    connection?: 'connected' | 'disconnected';
-    rssi?: number;
-    warning?: ioBroker.StringOrTranslated | boolean;
+    battery?: ValueOrState<number | boolean | 'charging' | string>;
+    connection?: ValueOrState<'connected' | 'disconnected', {
+        [value: string]: 'connected' | 'disconnected';
+    }>;
+    rssi?: ValueOrState<number>;
+    warning?: ValueOrState<ioBroker.StringOrTranslated | boolean>;
 };
 export type DeviceRefresh = 'device' | 'instance' | false | true;
 export type RefreshResponse = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iobroker/dm-utils",
-  "version": "1.0.16",
+  "version": "2.0.1",
   "description": "ioBroker Device Manager utilities for backend",
   "main": "build/index.js",
   "publishConfig": {