Support user-defined ESPHome API services by Copilot · Pull Request #406 · DrozmotiX/ioBroker.esphome

Copilot · 2026-02-21T09:24:43Z

Original prompt

This section details on the original issue you should resolve

<issue_title>Support user-defined services</issue_title>
<issue_description>As for now, it‘s only possible to send data back to esphome devices via mqtt listener?
My use case is reset and set specific counter values.

This could be done without mqtt with a user-defined api.service:
https://esphome.io/components/api.html#user-defined-services

IoBroker can show a esphome.services as a service object tree where data can be transmitted by json or yaml
</issue_description>

<agent_instructions>Explore 2colors/esphome-native-api lib if this kind of functionality is possible.

I don’t see functions in the lib talking to services?</agent_instructions>

Comments on the Issue (you are @copilot in this section)

Fixes Support user-defined services #117

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

Co-authored-by: DutchmanNL <7318445+DutchmanNL@users.noreply.github.com>

Copilot

Pull request overview

This PR adds support for ESPHome user-defined API services, addressing issue #117 where devices with custom api: services: YAML configurations were previously inaccessible without MQTT. The implementation leverages existing protobuf message types (ListEntitiesServicesResponse, ExecuteServiceRequest, ExecuteServiceArgument) from the @2colors/esphome-native-api library that weren't exposed as high-level methods, wiring them directly through low-level connection methods.

Changes:

Adds service discovery by listening for ListEntitiesServicesResponse messages during device initialization
Creates a UserDefinedServices channel hierarchy in ioBroker with writable argument states and a run button for each announced service
Implements service execution by constructing protobuf requests with typed arguments and sending via sendCommandMessage()

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 12 comments.

File	Description
main.js	Adds pb import, service discovery listener, handleUserDefinedService() for state tree creation, executeUserDefinedService() for execution, parseServiceArrayArg() helper, and onStateChange routing for service states
README.md	Documents the new feature in the changelog under WORK IN PROGRESS section

Copilot · 2026-02-21T10:06:38Z

+            clientDetails[host].client.connection.on('message.ListEntitiesServicesResponse', async serviceConfig => {
+                try {
+                    this.log.info(
+                        `${clientDetails[host].deviceFriendlyName} announced user-defined service "${serviceConfig.name}"`,
+                    );
+                    await this.handleUserDefinedService(host, serviceConfig);
+                } catch (e) {
+                    this.errorHandler(`[handleUserDefinedService]`, e);
+                }
+            });


The message listener for 'message.ListEntitiesServicesResponse' is registered inside the device connection setup, but there's no corresponding cleanup when the connection is closed or during adapter unload. This could lead to memory leaks if devices reconnect multiple times, as listeners will accumulate. Consider removing the listener in the 'disconnected' event handler or storing a reference to remove it during cleanup.

@copilot apply changes based on this feedback

Fixed in commit 0bcd378. The listener callback is now stored as onServiceAnnouncement and removed with .off() at the start of the disconnected handler, preventing listener accumulation across reconnects.

Copilot · 2026-02-21T10:06:38Z

+                } else if (
+                    clientDetails[deviceIP][device[4]] &&
+                    clientDetails[deviceIP][device[4]].type === 'UserDefinedService'
+                ) {
+                    if (device[5] === 'run') {
+                        // Execute the service and reset the button
+                        await this.executeUserDefinedService(deviceIP, device[2], device[4]);
+                        await this.setStateAsync(id, { val: false, ack: true });
+                    } else {
+                        // Argument value updated - just acknowledge the state
+                        await this.setStateAsync(id, { val: state.val, ack: true });
+                    }


In onStateChange, there's no defensive check whether the device array has enough elements before accessing device[4] and device[5]. If a user-defined service state has an unexpected path structure, this could throw an error. Consider adding a length check before accessing these array indices, similar to the existing checks for device[3].

@copilot apply changes based on this feedback

Fixed in commit 0bcd378. The UserDefinedService branch now checks device.length >= 6 before accessing device[4]/device[5].

Copilot · 2026-02-21T10:06:38Z

+        // Create parent channel for all user-defined services
+        const servicesChannel = `${deviceName}.UserDefinedServices`;
+        await this.extendObjectAsync(servicesChannel, {
+            type: 'channel',
+            common: { name: 'User-Defined Services' },
+            native: {},
+        });
+        if (!clientDetails[host].adapterObjects.channels.includes(`${this.namespace}.${servicesChannel}`)) {
+            clientDetails[host].adapterObjects.channels.push(`${this.namespace}.${servicesChannel}`);
+        }
+
+        // Create channel for this specific service
+        const serviceChannel = `${deviceName}.UserDefinedServices.${serviceKey}`;
+        await this.extendObjectAsync(serviceChannel, {
+            type: 'channel',
+            common: { name: serviceName },
+            native: { key: serviceKey, name: serviceName },
+        });
+        if (!clientDetails[host].adapterObjects.channels.includes(`${this.namespace}.${serviceChannel}`)) {
+            clientDetails[host].adapterObjects.channels.push(`${this.namespace}.${serviceChannel}`);
+        }


The UserDefinedServices channel and service-specific channels are created but not tracked in the objectCleanup mechanism. If a service is removed from the ESPHome device configuration, the corresponding ioBroker objects will remain indefinitely. Consider tracking these channels in clientDetails[host].adapterObjects.channels (which is already done) but also ensure they're properly cleaned up when the device reconnects and the service is no longer announced.

@copilot apply changes based on this feedback

Applied in commit 39aba4a. On the connected event, userDefinedServices is reset to {} and all UserDefinedServices channel paths are removed from adapterObjects.channels. This means objectCleanup (which runs on the initialized event) will delete any ioBroker channels for services that were removed from the device config between reconnects.

Copilot · 2026-02-21T10:06:39Z

 const { Client, Discovery } = require('@2colors/esphome-native-api');
+const { pb } = require('@2colors/esphome-native-api/lib/utils/messages');


The import path '@2colors/esphome-native-api/lib/utils/messages' directly accesses internal library structure (lib/utils/) which is typically not part of the public API. This could break if the library reorganizes its internal structure in a future version. Consider requesting the library maintainers to export these protobuf constructors from the main package entry point, or document this dependency risk.

Suggested change

const { Client, Discovery } = require('@2colors/esphome-native-api');

const { pb } = require('@2colors/esphome-native-api/lib/utils/messages');

const esphomeNativeApi = require('@2colors/esphome-native-api');

const { Client, Discovery, pb } = esphomeNativeApi;

twocolors/esphome-native-api#45

@DutchmanNL
Maybe use your fork until the PR is merged? So we avoid fragile code from the start.

Copilot · 2026-02-21T10:06:40Z

    * (DutchmanNL) 
 -->
+### __WORK IN PROGRESS__
+* (@copilot) **NEW**: Support user-defined ESPHome services - devices with `api: services:` YAML now expose a `UserDefinedServices` channel in ioBroker with writable argument states and a `run` button to trigger each service (fixes #251)


The issue number referenced in the README (#251) appears to be incorrect. The PR description states "Fixes #117" but the README changelog says "fixes #251". These should match to ensure proper issue tracking and closure. Update the README to reference #117 instead of #251.

@copilot the PR resolves #117 and #251, update readme accordingly

Updated in commit 0bcd378. The README changelog entry now reads (fixes #117, fixes #251).

Copilot · 2026-02-21T10:06:40Z

+        clientDetails[host][serviceKey] = {
+            type: 'UserDefinedService',
+            name: serviceName,
+            config: serviceConfig,
+        };


The serviceKey is stored as a numeric key directly in clientDetails[host], but this could collide with existing entity IDs which are also numeric. ESPHome entities and services may share the same key space. Consider using a dedicated sub-object like clientDetails[host].userDefinedServices[serviceKey] to avoid potential collisions with entity data structures.

@copilot apply changes based on this feedback

Fixed in commit 0bcd378. Services are now stored in clientDetails[host].userDefinedServices[serviceKey] (a dedicated sub-object declared in DeviceInfo as userDefinedServices = {}). All reads in executeUserDefinedService and onStateChange use the new path, and the reconnect cleanup resets it with clientDetails[host].userDefinedServices = {}.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Co-authored-by: DutchmanNL <7318445+DutchmanNL@users.noreply.github.com>

…p, key isolation, device path guard, README) Co-authored-by: DutchmanNL <7318445+DutchmanNL@users.noreply.github.com>

SimonFischer04

see comment to thread.

Not sure if it actually works but code doesnt look too bad.

SimonFischer04 · 2026-02-21T21:10:43Z

 const { Client, Discovery } = require('@2colors/esphome-native-api');
+const { pb } = require('@2colors/esphome-native-api/lib/utils/messages');


@DutchmanNL
Maybe use your fork until the PR is merged? So we avoid fragile code from the start.

DutchmanNL · 2026-02-21T22:12:03Z

PR raised to original lib repository to make function available for easier adoption

awaiting implementation which is preferred on top of workaround accessing lib directly

Initial plan

dad9858

Copilot AI assigned Copilot and DutchmanNL Feb 21, 2026

Copilot started work on behalf of DutchmanNL February 21, 2026 09:24 View session

DutchmanNL mentioned this pull request Feb 21, 2026

Exposes user defined services as function DutchmanNL/esphome-native-api#1

Closed

Copilot AI mentioned this pull request Feb 21, 2026

Expose user-defined ESPHome services as first-class API functions DutchmanNL/esphome-native-api#2

Merged

feat: support user-defined ESPHome services (closes #251)

9465491

Co-authored-by: DutchmanNL <7318445+DutchmanNL@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Add support for user-defined services~~ Support user-defined ESPHome API services Feb 21, 2026

Copilot AI requested a review from DutchmanNL February 21, 2026 09:47

Copilot finished work on behalf of DutchmanNL February 21, 2026 09:47

DutchmanNL marked this pull request as ready for review February 21, 2026 10:00

DutchmanNL requested review from SimonFischer04 and Copilot February 21, 2026 10:00

Copilot started reviewing on behalf of DutchmanNL February 21, 2026 10:01 View session

Copilot AI reviewed Feb 21, 2026

View reviewed changes

Copilot started work on behalf of DutchmanNL February 21, 2026 16:58 View session

DutchmanNL and others added 5 commits February 21, 2026 17:58

Update main.js

85bfbfb

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update main.js

76cd2ad

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update main.js

9a54e78

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

fix: resolve ESLint/prettier violations in user-defined services code

39aba4a

Co-authored-by: DutchmanNL <7318445+DutchmanNL@users.noreply.github.com>

fix: clear stale UserDefinedService channels and entries on reconnect

5a304d0

Co-authored-by: DutchmanNL <7318445+DutchmanNL@users.noreply.github.com>

Copilot finished work on behalf of DutchmanNL February 21, 2026 17:23

Copilot started work on behalf of DutchmanNL February 21, 2026 17:24 View session

fix: apply review feedback for user-defined services (listener cleanu…

0bcd378

…p, key isolation, device path guard, README) Co-authored-by: DutchmanNL <7318445+DutchmanNL@users.noreply.github.com>

Copilot finished work on behalf of DutchmanNL February 21, 2026 17:28

SimonFischer04 reviewed Feb 21, 2026

View reviewed changes

DutchmanNL mentioned this pull request Feb 25, 2026

Implement user defined services #414

Open

Copilot AI mentioned this pull request Feb 25, 2026

Redesign user-defined ESPHome services using executeServiceService from @2colors/esphome-native-api 1.3.6 #415

Draft

SimonFischer04 marked this pull request as draft April 8, 2026 07:12

		const { Client, Discovery } = require('@2colors/esphome-native-api');
		const { pb } = require('@2colors/esphome-native-api/lib/utils/messages');

Uh oh!

Uh oh!

Conversation

Copilot AI commented Feb 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Comments on the Issue (you are @copilot in this section)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 21, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 21, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 21, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Feb 21, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 21, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Feb 21, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Feb 21, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 21, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Feb 21, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 21, 2026

Choose a reason for hiding this comment

Uh oh!

SimonFischer04 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DutchmanNL commented Feb 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Copilot AI commented Feb 21, 2026 •

edited

Loading