@enyo-energy/energy-app-sdk 0.0.188 → 0.0.190

package/dist/cjs/energy-app-permission.type.cjs

@@ -27,6 +27,7 @@ var EnergyAppPermissionTypeEnum;
     EnergyAppPermissionTypeEnum["EnergyManager"] = "EnergyManager";
     EnergyAppPermissionTypeEnum["ElectricityTariff"] = "ElectricityTariff";
     EnergyAppPermissionTypeEnum["ModbusRtu"] = "ModbusRtu";
+    EnergyAppPermissionTypeEnum["ModbusServer"] = "ModbusServer";
     EnergyAppPermissionTypeEnum["EnergyPrices"] = "EnergyPrices";
     EnergyAppPermissionTypeEnum["WeatherForecastRegister"] = "WeatherForecastRegister";
     EnergyAppPermissionTypeEnum["WeatherForecastUse"] = "WeatherForecastUse";

package/dist/cjs/energy-app-permission.type.d.cts

@@ -24,6 +24,7 @@ export declare enum EnergyAppPermissionTypeEnum {
     EnergyManager = "EnergyManager",
     ElectricityTariff = "ElectricityTariff",
     ModbusRtu = "ModbusRtu",
+    ModbusServer = "ModbusServer",
     EnergyPrices = "EnergyPrices",
     WeatherForecastRegister = "WeatherForecastRegister",
     WeatherForecastUse = "WeatherForecastUse",

package/dist/cjs/energy-app.cjs

@@ -212,6 +212,22 @@ class EnergyApp {
     useModbusRtu() {
         return this.energyAppSdk.useModbusRtu();
     }
+    /**
+     * Gets the Modbus server API for serving your app's data to Modbus clients.
+     *
+     * The inverse of {@link EnergyApp.useModbus}: the hub itself answers Modbus
+     * requests, and this app supplies the values behind individual registers by
+     * registering them with read/write handlers. The listener is host-owned and
+     * shared with every other installed app, so address ranges are
+     * first-come-first-served across apps.
+     *
+     * Requires the `ModbusServer` permission.
+     *
+     * @returns The Modbus server API instance
+     */
+    useModbusServer() {
+        return this.energyAppSdk.useModbusServer();
+    }
     /**
      * Gets the EEbus API for SHIP/SPINE device communication.
      *

package/dist/cjs/energy-app.d.cts

@@ -26,6 +26,7 @@ import { EnergyAppDynamicPriceForecast } from "./packages/energy-app-dynamic-pri
 import { EnergyAppPvSystem } from "./packages/energy-app-pv-system.cjs";
 import { EnergyAppSequenceGenerator } from "./packages/energy-app-sequence-generator.cjs";
 import { EnergyAppModbusRtu } from "./packages/energy-app-modbus-rtu.cjs";
+import { EnergyAppModbusServer } from "./packages/energy-app-modbus-server.cjs";
 import { EnergyAppEebus } from "./packages/energy-app-eebus.cjs";
 import { EnergyAppMqtt } from "./packages/energy-app-mqtt.cjs";
 import { EnergyAppBluetooth } from "./packages/energy-app-bluetooth.cjs";
@@ -171,6 +172,20 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
      * @returns The Modbus RTU API instance
      */
     useModbusRtu(): EnergyAppModbusRtu;
+    /**
+     * Gets the Modbus server API for serving your app's data to Modbus clients.
+     *
+     * The inverse of {@link EnergyApp.useModbus}: the hub itself answers Modbus
+     * requests, and this app supplies the values behind individual registers by
+     * registering them with read/write handlers. The listener is host-owned and
+     * shared with every other installed app, so address ranges are
+     * first-come-first-served across apps.
+     *
+     * Requires the `ModbusServer` permission.
+     *
+     * @returns The Modbus server API instance
+     */
+    useModbusServer(): EnergyAppModbusServer;
     /**
      * Gets the EEbus API for SHIP/SPINE device communication.
      *

package/dist/cjs/enyo-energy-app-sdk.d.cts

@@ -25,6 +25,7 @@ import { EnergyAppDynamicPriceForecast } from "./packages/energy-app-dynamic-pri
 import { EnergyAppPvSystem } from "./packages/energy-app-pv-system.cjs";
 import { EnergyAppSequenceGenerator } from "./packages/energy-app-sequence-generator.cjs";
 import { EnergyAppModbusRtu } from "./packages/energy-app-modbus-rtu.cjs";
+import { EnergyAppModbusServer } from "./packages/energy-app-modbus-server.cjs";
 import { EnergyAppEebus } from "./packages/energy-app-eebus.cjs";
 import { EnergyAppMqtt } from "./packages/energy-app-mqtt.cjs";
 import { EnergyAppBluetooth } from "./packages/energy-app-bluetooth.cjs";
@@ -123,6 +124,8 @@ export interface EnyoEnergyAppSdk {
     useSequenceGenerator: () => EnergyAppSequenceGenerator;
     /** Get the Modbus RTU serial communication API */
     useModbusRtu: () => EnergyAppModbusRtu;
+    /** Get the Modbus server API for serving registers to Modbus clients */
+    useModbusServer: () => EnergyAppModbusServer;
     /** Get the EEbus SHIP/SPINE communication API for device pairing, data access, and power management */
     useEebus: () => EnergyAppEebus;
     /** Get the MQTT communication API for connecting to internal or external MQTT brokers */

package/dist/cjs/implementations/modbus/define-modbus-server-register.cjs

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * Ergonomic authoring helpers for {@link EnyoModbusServerRegistration}s.
+ *
+ * These exist for one concrete reason: type inference. A registration's handler
+ * signatures depend on its `dataType` — a `float32` register reads a `number`, a
+ * `string` register reads a `string` — but that link only holds when TypeScript
+ * can *infer* the data type from the literal. Annotating an object literal as
+ * {@link EnyoModbusServerRegistration} defeats that: the generic falls back to
+ * the full data-type union and every handler widens to `string | number`.
+ *
+ * Building registers through these factories keeps the link intact, so a handler
+ * returning the wrong shape is a compile error rather than a runtime decode
+ * failure. They also fill in `space`, which is the one field that is pure
+ * boilerplate.
+ *
+ * Mirrors the SDK's `onboardingV2Block` pattern.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.modbusServerRegister = void 0;
+const enyo_modbus_server_js_1 = require("../../types/enyo-modbus-server.cjs");
+/**
+ * Typed factories for each Modbus address space. Each fills in `space` and
+ * returns the corresponding registration, inferring the word data type from the
+ * supplied `dataType` so handler values stay exact.
+ *
+ * @example
+ * ```typescript
+ * const registers = [
+ *     modbusServerRegister.holding({
+ *         address: 40071,
+ *         key: 'active-power-w',
+ *         name: [{language: 'en', value: 'Active power'}],
+ *         unit: 'W',
+ *         dataType: 'float32',
+ *         onRead: () => currentPowerW,        // must be a number
+ *         onWrite: (value) => applyLimit(value),
+ *     }),
+ *     modbusServerRegister.input({
+ *         address: 40080,
+ *         key: 'serial',
+ *         name: [{language: 'en', value: 'Serial number'}],
+ *         dataType: 'string',
+ *         quantity: 8,
+ *         onRead: () => deviceSerial,          // must be a string
+ *     }),
+ * ];
+ * ```
+ */
+exports.modbusServerRegister = {
+    /**
+     * A read/write single-bit coil.
+     * @param registration - Everything but `space`; omit `onWrite` for a read-only coil.
+     */
+    coil: (registration) => ({
+        ...registration,
+        space: enyo_modbus_server_js_1.EnyoModbusServerRegisterSpace.Coil,
+    }),
+    /**
+     * A read-only single-bit discrete input.
+     * @param registration - Everything but `space`.
+     */
+    discreteInput: (registration) => ({
+        ...registration,
+        space: enyo_modbus_server_js_1.EnyoModbusServerRegisterSpace.DiscreteInput,
+    }),
+    /**
+     * A read/write 16-bit holding register.
+     * @param registration - Everything but `space`. The `dataType` fixes the
+     *   handler value types; omit `onWrite` for a read-only holding register.
+     */
+    holding: (registration) => ({
+        ...registration,
+        space: enyo_modbus_server_js_1.EnyoModbusServerRegisterSpace.Holding,
+    }),
+    /**
+     * A read-only 16-bit input register.
+     * @param registration - Everything but `space`. The `dataType` fixes the
+     *   handler value type.
+     */
+    input: (registration) => ({
+        ...registration,
+        space: enyo_modbus_server_js_1.EnyoModbusServerRegisterSpace.Input,
+    }),
+};

package/dist/cjs/implementations/modbus/define-modbus-server-register.d.cts

@@ -0,0 +1,71 @@
+/**
+ * Ergonomic authoring helpers for {@link EnyoModbusServerRegistration}s.
+ *
+ * These exist for one concrete reason: type inference. A registration's handler
+ * signatures depend on its `dataType` — a `float32` register reads a `number`, a
+ * `string` register reads a `string` — but that link only holds when TypeScript
+ * can *infer* the data type from the literal. Annotating an object literal as
+ * {@link EnyoModbusServerRegistration} defeats that: the generic falls back to
+ * the full data-type union and every handler widens to `string | number`.
+ *
+ * Building registers through these factories keeps the link intact, so a handler
+ * returning the wrong shape is a compile error rather than a runtime decode
+ * failure. They also fill in `space`, which is the one field that is pure
+ * boilerplate.
+ *
+ * Mirrors the SDK's `onboardingV2Block` pattern.
+ */
+import { type EnyoModbusServerCoilRegistration, type EnyoModbusServerDiscreteInputRegistration, type EnyoModbusServerHoldingRegistration, type EnyoModbusServerInputRegistration } from '../../types/enyo-modbus-server.cjs';
+import type { EnergyAppModbusDataType } from './interfaces.cjs';
+/**
+ * Typed factories for each Modbus address space. Each fills in `space` and
+ * returns the corresponding registration, inferring the word data type from the
+ * supplied `dataType` so handler values stay exact.
+ *
+ * @example
+ * ```typescript
+ * const registers = [
+ *     modbusServerRegister.holding({
+ *         address: 40071,
+ *         key: 'active-power-w',
+ *         name: [{language: 'en', value: 'Active power'}],
+ *         unit: 'W',
+ *         dataType: 'float32',
+ *         onRead: () => currentPowerW,        // must be a number
+ *         onWrite: (value) => applyLimit(value),
+ *     }),
+ *     modbusServerRegister.input({
+ *         address: 40080,
+ *         key: 'serial',
+ *         name: [{language: 'en', value: 'Serial number'}],
+ *         dataType: 'string',
+ *         quantity: 8,
+ *         onRead: () => deviceSerial,          // must be a string
+ *     }),
+ * ];
+ * ```
+ */
+export declare const modbusServerRegister: {
+    /**
+     * A read/write single-bit coil.
+     * @param registration - Everything but `space`; omit `onWrite` for a read-only coil.
+     */
+    coil: (registration: Omit<EnyoModbusServerCoilRegistration, "space">) => EnyoModbusServerCoilRegistration;
+    /**
+     * A read-only single-bit discrete input.
+     * @param registration - Everything but `space`.
+     */
+    discreteInput: (registration: Omit<EnyoModbusServerDiscreteInputRegistration, "space">) => EnyoModbusServerDiscreteInputRegistration;
+    /**
+     * A read/write 16-bit holding register.
+     * @param registration - Everything but `space`. The `dataType` fixes the
+     *   handler value types; omit `onWrite` for a read-only holding register.
+     */
+    holding: <D extends EnergyAppModbusDataType>(registration: Omit<EnyoModbusServerHoldingRegistration<D>, "space">) => EnyoModbusServerHoldingRegistration<D>;
+    /**
+     * A read-only 16-bit input register.
+     * @param registration - Everything but `space`. The `dataType` fixes the
+     *   handler value type.
+     */
+    input: <D extends EnergyAppModbusDataType>(registration: Omit<EnyoModbusServerInputRegistration<D>, "space">) => EnyoModbusServerInputRegistration<D>;
+};

package/dist/cjs/implementations/modbus/modbus-server-validators.cjs

@@ -0,0 +1,161 @@
+"use strict";
+/**
+ * Client-side validator for {@link EnyoModbusServerRegistration} lists.
+ *
+ * The host rejects a conflicting registration at call time by throwing
+ * {@link EnyoModbusServerRegistrationConflictError}, which is the authoritative
+ * check but a poor way to find out your own register map overlaps itself. This
+ * validator catches everything that is knowable without the host — self-overlap,
+ * duplicate keys, missing metadata — so an app can fail fast at startup with all
+ * the problems at once instead of one throw at a time.
+ *
+ * It cannot see other apps' registrations, so a clean result here does **not**
+ * guarantee registration will succeed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModbusServerValidationError = void 0;
+exports.modbusServerRegisterSpan = modbusServerRegisterSpan;
+exports.validateModbusServerRegistrations = validateModbusServerRegistrations;
+exports.assertValidModbusServerRegistrations = assertValidModbusServerRegistrations;
+const enyo_modbus_server_js_1 = require("../../types/enyo-modbus-server.cjs");
+/**
+ * Thrown by {@link assertValidModbusServerRegistrations} when a register map
+ * fails validation. The message lists every blocking error.
+ */
+class ModbusServerValidationError extends Error {
+    /** The individual blocking errors that caused the failure. */
+    errors;
+    /**
+     * @param errors - The blocking validation errors.
+     */
+    constructor(errors) {
+        super(`Invalid Modbus server register map:\n- ${errors.join('\n- ')}`);
+        this.name = 'ModbusServerValidationError';
+        this.errors = errors;
+    }
+}
+exports.ModbusServerValidationError = ModbusServerValidationError;
+/** Word counts for the data types whose span is fixed. */
+const WORDS_BY_DATA_TYPE = {
+    uint16: 1,
+    int16: 1,
+    acc16: 1,
+    uint32: 2,
+    int32: 2,
+    float32: 2,
+    acc32: 2,
+};
+/** The two spaces addressed in bits rather than 16-bit words. */
+const BIT_SPACES = new Set([
+    enyo_modbus_server_js_1.EnyoModbusServerRegisterSpace.Coil,
+    enyo_modbus_server_js_1.EnyoModbusServerRegisterSpace.DiscreteInput,
+]);
+/**
+ * How many words (or bits) a registration occupies, starting at its `address`.
+ *
+ * Bit spaces always occupy one. Word spaces derive their span from `dataType`,
+ * except `'string'`, which needs an explicit `quantity` — when that is missing
+ * the span is unknowable and this returns `undefined` so the caller can report
+ * it rather than guess.
+ *
+ * @param registration - The registration to measure.
+ * @returns The span, or `undefined` when it cannot be derived.
+ */
+function modbusServerRegisterSpan(registration) {
+    if (BIT_SPACES.has(registration.space))
+        return 1;
+    const { dataType, quantity } = registration;
+    if (dataType === 'string') {
+        return quantity && quantity > 0 ? quantity : undefined;
+    }
+    return WORDS_BY_DATA_TYPE[dataType];
+}
+/**
+ * Checks a register map for problems that are knowable without the host.
+ *
+ * Reports as errors: overlapping ranges within the same space, duplicate `key`s,
+ * a missing or empty `name`, a `'string'` register without `quantity`, an
+ * unknown `dataType`, and a negative address. Reports as warnings: `scale` on a
+ * string register (which the host ignores) and a `unit` on a coil or discrete
+ * input (a bit has no unit).
+ *
+ * Two registrations only conflict within the same space — holding 40071 and
+ * input 40071 are different addresses and both are fine.
+ *
+ * @param registrations - The register map to check.
+ * @returns The {@link ModbusServerValidationResult}.
+ */
+function validateModbusServerRegistrations(registrations) {
+    const errors = [];
+    const warnings = [];
+    if (!registrations?.length) {
+        return { ok: true, errors, warnings };
+    }
+    const keys = new Set();
+    /** Claimed ranges per space, so the overlap check never crosses spaces. */
+    const claimed = new Map();
+    for (const [i, registration] of registrations.entries()) {
+        const at = `registrations[${i}] (${registration.key || '?'})`;
+        if (!registration.key?.trim()) {
+            errors.push(`${at}: key is required.`);
+        }
+        else if (keys.has(registration.key)) {
+            errors.push(`${at}: duplicate key "${registration.key}".`);
+        }
+        else {
+            keys.add(registration.key);
+        }
+        if (!registration.name?.length) {
+            errors.push(`${at}: name is required — it is what an installer sees in the register map.`);
+        }
+        if (!Number.isInteger(registration.address) || registration.address < 0) {
+            errors.push(`${at}: address must be a non-negative integer.`);
+            continue;
+        }
+        if (BIT_SPACES.has(registration.space) && registration.unit) {
+            warnings.push(`${at}: unit "${registration.unit}" on a ${registration.space} is meaningless — a bit has no unit.`);
+        }
+        const span = modbusServerRegisterSpan(registration);
+        if (span === undefined) {
+            const { dataType } = registration;
+            if (dataType === 'string') {
+                errors.push(`${at}: dataType "string" needs a positive quantity — its length cannot be derived.`);
+            }
+            else {
+                errors.push(`${at}: unknown dataType "${dataType}".`);
+            }
+            continue;
+        }
+        if (!BIT_SPACES.has(registration.space)) {
+            const { dataType, scale } = registration;
+            if (dataType === 'string' && scale !== undefined) {
+                warnings.push(`${at}: scale is ignored on a string register.`);
+            }
+        }
+        const from = registration.address;
+        const to = from + span - 1;
+        const inSpace = claimed.get(registration.space) ?? [];
+        const clash = inSpace.find((r) => from <= r.to && to >= r.from);
+        if (clash) {
+            errors.push(`${at}: ${registration.space} range ${from}..${to} overlaps ${clash.at} (${clash.from}..${clash.to}).`);
+        }
+        inSpace.push({ from, to, at });
+        claimed.set(registration.space, inSpace);
+    }
+    return { ok: errors.length === 0, errors, warnings };
+}
+/**
+ * Like {@link validateModbusServerRegistrations}, but throws
+ * {@link ModbusServerValidationError} when there are blocking errors. Warnings
+ * never throw; the validated list is returned on success for chaining.
+ *
+ * @param registrations - The register map to check.
+ * @returns The same list when it has no blocking errors.
+ * @throws {ModbusServerValidationError} When validation produces any error.
+ */
+function assertValidModbusServerRegistrations(registrations) {
+    const { ok, errors } = validateModbusServerRegistrations(registrations);
+    if (!ok)
+        throw new ModbusServerValidationError(errors);
+    return registrations;
+}

package/dist/cjs/implementations/modbus/modbus-server-validators.d.cts

@@ -0,0 +1,73 @@
+/**
+ * Client-side validator for {@link EnyoModbusServerRegistration} lists.
+ *
+ * The host rejects a conflicting registration at call time by throwing
+ * {@link EnyoModbusServerRegistrationConflictError}, which is the authoritative
+ * check but a poor way to find out your own register map overlaps itself. This
+ * validator catches everything that is knowable without the host — self-overlap,
+ * duplicate keys, missing metadata — so an app can fail fast at startup with all
+ * the problems at once instead of one throw at a time.
+ *
+ * It cannot see other apps' registrations, so a clean result here does **not**
+ * guarantee registration will succeed.
+ */
+import { type EnyoModbusServerRegistration } from '../../types/enyo-modbus-server.cjs';
+/** The outcome of validating a list of registrations. */
+export interface ModbusServerValidationResult {
+    /** True when there are no blocking `errors` (warnings are still allowed). */
+    ok: boolean;
+    /** Blocking problems — registration will fail or serve wrong data. */
+    errors: string[];
+    /** Advisory problems — allowed, but usually worth fixing. */
+    warnings: string[];
+}
+/**
+ * Thrown by {@link assertValidModbusServerRegistrations} when a register map
+ * fails validation. The message lists every blocking error.
+ */
+export declare class ModbusServerValidationError extends Error {
+    /** The individual blocking errors that caused the failure. */
+    readonly errors: string[];
+    /**
+     * @param errors - The blocking validation errors.
+     */
+    constructor(errors: string[]);
+}
+/**
+ * How many words (or bits) a registration occupies, starting at its `address`.
+ *
+ * Bit spaces always occupy one. Word spaces derive their span from `dataType`,
+ * except `'string'`, which needs an explicit `quantity` — when that is missing
+ * the span is unknowable and this returns `undefined` so the caller can report
+ * it rather than guess.
+ *
+ * @param registration - The registration to measure.
+ * @returns The span, or `undefined` when it cannot be derived.
+ */
+export declare function modbusServerRegisterSpan(registration: EnyoModbusServerRegistration): number | undefined;
+/**
+ * Checks a register map for problems that are knowable without the host.
+ *
+ * Reports as errors: overlapping ranges within the same space, duplicate `key`s,
+ * a missing or empty `name`, a `'string'` register without `quantity`, an
+ * unknown `dataType`, and a negative address. Reports as warnings: `scale` on a
+ * string register (which the host ignores) and a `unit` on a coil or discrete
+ * input (a bit has no unit).
+ *
+ * Two registrations only conflict within the same space — holding 40071 and
+ * input 40071 are different addresses and both are fine.
+ *
+ * @param registrations - The register map to check.
+ * @returns The {@link ModbusServerValidationResult}.
+ */
+export declare function validateModbusServerRegistrations(registrations: EnyoModbusServerRegistration[]): ModbusServerValidationResult;
+/**
+ * Like {@link validateModbusServerRegistrations}, but throws
+ * {@link ModbusServerValidationError} when there are blocking errors. Warnings
+ * never throw; the validated list is returned on success for chaining.
+ *
+ * @param registrations - The register map to check.
+ * @returns The same list when it has no blocking errors.
+ * @throws {ModbusServerValidationError} When validation produces any error.
+ */
+export declare function assertValidModbusServerRegistrations(registrations: EnyoModbusServerRegistration[]): EnyoModbusServerRegistration[];

package/dist/cjs/index.cjs

@@ -54,6 +54,10 @@ __exportStar(require("./types/enyo-currency.cjs"), exports);
 __exportStar(require("./packages/energy-app-sequence-generator.cjs"), exports);
 __exportStar(require("./packages/energy-app-energy-prices.cjs"), exports);
 __exportStar(require("./packages/energy-app-modbus-rtu.cjs"), exports);
+__exportStar(require("./types/enyo-modbus-server.cjs"), exports);
+__exportStar(require("./packages/energy-app-modbus-server.cjs"), exports);
+__exportStar(require("./implementations/modbus/define-modbus-server-register.cjs"), exports);
+__exportStar(require("./implementations/modbus/modbus-server-validators.cjs"), exports);
 __exportStar(require("./types/enyo-spine.cjs"), exports);
 __exportStar(require("./types/enyo-eebus.cjs"), exports);
 __exportStar(require("./types/enyo-eebus-use-cases.cjs"), exports);

package/dist/cjs/index.d.cts

@@ -38,6 +38,10 @@ export * from './types/enyo-currency.cjs';
 export * from './packages/energy-app-sequence-generator.cjs';
 export * from './packages/energy-app-energy-prices.cjs';
 export * from './packages/energy-app-modbus-rtu.cjs';
+export * from './types/enyo-modbus-server.cjs';
+export * from './packages/energy-app-modbus-server.cjs';
+export * from './implementations/modbus/define-modbus-server-register.cjs';
+export * from './implementations/modbus/modbus-server-validators.cjs';
 export * from './types/enyo-spine.cjs';
 export * from './types/enyo-eebus.cjs';
 export * from './types/enyo-eebus-use-cases.cjs';

package/dist/cjs/packages/energy-app-modbus-server.cjs

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * The **Modbus server** package: serve your app's data to Modbus clients on the
+ * hub's own listener.
+ *
+ * This is the inverse of {@link EnergyAppModbus}. There, the app is a client
+ * polling somebody else's device. Here, the hub *is* the device: a third-party
+ * energy manager, a building-automation controller or an installer's diagnostic
+ * tool connects to the hub, and the values it reads come from handlers this app
+ * registers.
+ *
+ * Requires the `ModbusServer` permission.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/packages/energy-app-modbus-server.d.cts

@@ -0,0 +1,122 @@
+/**
+ * The **Modbus server** package: serve your app's data to Modbus clients on the
+ * hub's own listener.
+ *
+ * This is the inverse of {@link EnergyAppModbus}. There, the app is a client
+ * polling somebody else's device. Here, the hub *is* the device: a third-party
+ * energy manager, a building-automation controller or an installer's diagnostic
+ * tool connects to the hub, and the values it reads come from handlers this app
+ * registers.
+ *
+ * Requires the `ModbusServer` permission.
+ */
+import type { EnergyAppModbusDataType } from '../implementations/modbus/interfaces.cjs';
+import type { EnyoModbusServerConfig, EnyoModbusServerRegistration, EnyoModbusServerRegistrationHandle, EnyoModbusServerRegistrationOf } from '../types/enyo-modbus-server.cjs';
+/**
+ * Interface for serving Modbus registers from an enyo package.
+ *
+ * **The server is shared.** One host-owned TCP listener, one unit id, and every
+ * installed app carving up the same address space. Two consequences an app
+ * author has to design around:
+ *
+ * 1. Address ranges are first-come, first-served across *all* apps, so
+ *    registration can fail with
+ *    {@link EnyoModbusServerRegistrationConflictError} through no fault of your
+ *    own. Handle it at runtime; do not assume startup registration succeeds.
+ * 2. The unit id from {@link getModbusServerConfig} does not identify your app.
+ *    A client addressing it reaches the whole hub, not your package.
+ *
+ * Register metadata (translated name, description, unit) never travels over
+ * Modbus — the protocol carries bare words. It exists so the host can show the
+ * hub's register map and generate installer documentation.
+ *
+ * @example
+ * ```typescript
+ * const server = energyApp.useModbusServer();
+ * const {addresses, port, unitId} = await server.getModbusServerConfig();
+ * console.log(`Reachable at ${addresses.join(', ')}:${port}, unit ${unitId}`);
+ *
+ * const handle = await server.registerRegister(modbusServerRegister.holding({
+ *     address: 40071,
+ *     key: 'active-power-w',
+ *     name: [
+ *         {language: 'de', value: 'Momentanleistung'},
+ *         {language: 'en', value: 'Active power'},
+ *     ],
+ *     description: [
+ *         {language: 'de', value: 'Aktuelle Wirkleistung der Anlage.'},
+ *         {language: 'en', value: 'Current active power of the plant.'},
+ *     ],
+ *     unit: 'W',
+ *     dataType: 'float32',            // claims 40071..40072
+ *     onRead: async () => currentPowerW,
+ *     onWrite: async (value) => applyPowerLimit(value),
+ * }));
+ *
+ * // later, on shutdown
+ * await handle.unregister();
+ * ```
+ */
+export interface EnergyAppModbusServer {
+    /**
+     * Returns where the hub's Modbus server can be reached — addresses, port and
+     * the shared unit id.
+     *
+     * Everything returned is host-owned and read-only. Use it to tell an
+     * installer where to point their client; prefer showing
+     * {@link EnyoModbusServerConfig.addresses} in full over guessing which
+     * interface they are on.
+     *
+     * @returns The current server configuration.
+     */
+    getModbusServerConfig(): Promise<EnyoModbusServerConfig>;
+    /**
+     * Claims one address range and serves it from the supplied handlers.
+     *
+     * The range claimed runs from `address` for as many words as the
+     * registration's `dataType` implies (1 for `uint16`, 2 for `float32`,
+     * `quantity` for `string`, 1 bit for a coil or discrete input). Any overlap
+     * with an existing registration — yours or another app's — fails the whole
+     * call; nothing partial is claimed.
+     *
+     * @param registration - The register to serve, with its metadata and handlers.
+     * @returns A handle for releasing the range again.
+     * @throws {EnyoModbusServerRegistrationConflictError} If any word of the
+     *   range is already registered. Check `heldByCaller` to tell your own
+     *   double-registration from another app holding the address.
+     */
+    registerRegister<D extends EnergyAppModbusDataType>(registration: EnyoModbusServerRegistrationOf<D>): Promise<EnyoModbusServerRegistrationHandle>;
+    /**
+     * Claims several address ranges at once, atomically.
+     *
+     * Either every registration succeeds or none does — a conflict partway
+     * through the list leaves no ranges claimed. Prefer this over a loop of
+     * {@link registerRegister} when registering a device's whole register map,
+     * so a mid-list conflict cannot strand you with half a map published.
+     *
+     * @param registrations - The registers to serve.
+     * @returns One handle per registration, in the order supplied.
+     * @throws {EnyoModbusServerRegistrationConflictError} If any range in the
+     *   list conflicts, with the details of the first conflict found. Overlaps
+     *   *within* the supplied list are reported the same way, with
+     *   `heldByCaller` true.
+     */
+    registerRegisters(registrations: EnyoModbusServerRegistration[]): Promise<EnyoModbusServerRegistrationHandle[]>;
+    /**
+     * Lists the registrations this app currently holds.
+     *
+     * Scoped to the calling app — registrations belonging to other apps are
+     * never visible, even though they share the address space.
+     *
+     * @returns The live handles, in no guaranteed order.
+     */
+    getRegisteredRegisters(): Promise<EnyoModbusServerRegistrationHandle[]>;
+    /**
+     * Releases every range this app holds.
+     *
+     * Idempotent, and safe to call when nothing is registered. Worth calling on
+     * shutdown: ranges stay claimed while the app is installed, so a stale
+     * registration blocks a later re-registration of the same address.
+     */
+    unregisterAll(): Promise<void>;
+}

package/dist/cjs/types/enyo-inverter-appliance.d.cts

@@ -42,4 +42,17 @@ export interface EnyoInverterApplianceMetadata {
      * `undefined` means "not configured" and should be treated as `false`.
      */
     blockFeedInOnNegativePrices?: boolean;
+    /**
+     * Whether the energy manager may actively steer this inverter (e.g. curtail
+     * production). When omitted, consumers fall back to their configured
+     * default behaviour — same contract as the SDK's own `controlAllowed`.
+     */
+    controlAllowed?: boolean;
+    /**
+     * Peak power of the PV modules attached to this inverter, in Watt-peak, as
+     * stated on the Anlagenpass. Distinct from `maxPvProductionW`, which is
+     * what the inverter itself can put out on the AC side; together with
+     * `moduleGroups` it also gives the power of a single module.
+     */
+    installedPeakPowerWp?: number;
 }