@enyo-energy/energy-app-sdk 1.8.0 → 1.9.0

package/README.md

@@ -571,6 +571,86 @@ const registers = await client.readHoldingRegisters(1001, 10);
 await client.writeSingleRegister(2001, 500);
 ```
 
+##### Exceptions are data, not just failures
+
+When a device *answers* but refuses an operation, the call rejects with a `ModbusExceptionError`
+carrying the device's raw exception code. That is different from a timeout or a dropped socket, and
+the distinction is the whole point: a permission probe is a write you expect to be refused.
+
+```typescript
+import {ModbusExceptionError} from '@enyo-energy/energy-app-sdk';
+
+// May this connection write at all? Write a register back its own value and see.
+const current = (await client.readHoldingRegisters(43006, 1)).readUInt16BE(0);
+try {
+    await client.writeSingleRegister(43006, current);
+    controlAllowed = true;                       // the write landed
+} catch (error) {
+    if (error instanceof ModbusExceptionError) {
+        controlAllowed = false;                  // refused by the device, e.g. code 0x80
+    } else {
+        throw error;                             // the link is broken — a different problem
+    }
+}
+```
+
+Vendor-specific codes are passed through unvalidated (Huawei answers `0x80` for "permission
+authentication failure or permission expiration", which is outside the standard `0x01`…`0x0B`
+range). An exception response never recycles the socket.
+
+##### Vendor function codes: `sendRawPdu()`
+
+Some devices reserve a function code of their own for things the standard eight codes cannot
+express — most commonly an installer login that must succeed before any control write is accepted.
+`sendRawPdu()` puts one PDU on the wire verbatim and hands back the raw answer, on the connection
+the SDK already owns:
+
+```typescript
+const response = await client.sendRawPdu(0x41, Buffer.from([0x24, ...challengeBytes]));
+
+if (response.exceptionCode !== undefined) {
+    // The device refused. Expected often enough that it is a result, not a throw.
+    console.warn(`Vendor command refused with 0x${response.exceptionCode.toString(16)}`);
+} else {
+    parseVendorReply(response.payload);
+}
+```
+
+- The SDK knows nothing about the vendor. Sub-commands, digests and keepalives stay in your app.
+- The call queues on the same per-connection chain as every other request, so `noParallelRequests`
+  and `waitBetweenMessagesMs` hold — a login can never interleave with a block read that is already
+  in flight.
+- Request payloads are **never logged**; only the function code and the payload length are. Vendor
+  handshakes carry credential digests.
+- Payloads are capped at `MODBUS_MAX_PDU_PAYLOAD_BYTES` (252), keeping the frame inside the 253-byte
+  Modbus PDU limit. Function codes must be 1…127.
+- It needs the same `Modbus` permission as the rest of the Modbus surface — an app that can already
+  call `writeMultipleRegisters` can write any holding register, so this grants reach, not privilege.
+
+##### Knowing when the socket was replaced
+
+Anything the device tracks per *connection* rather than per device — a vendor login above all — dies
+silently when the socket is recycled. The next write simply comes back refused. `onReconnect()` is
+the signal that lets you re-establish it beforehand:
+
+```typescript
+const stopListening = client.onReconnect(() => {
+    // Permission was granted to the old socket and is gone with it.
+    authenticated = false;
+    void loginAgain();
+});
+
+// Or check after the fact, without keeping a listener alive:
+const before = client.connectionGeneration();
+await doSomething();
+if (client.connectionGeneration() !== before) {
+    // The socket was replaced in the meantime; connection-scoped state is void.
+}
+```
+
+Listeners are dropped automatically on `disconnect()`, and `onReconnect()` returns a function that
+removes just yours.
+
 #### `useOcpp(): EnergyAppOcpp`
 
 Handle OCPP charging station communication:

package/dist/cjs/index.cjs

@@ -56,6 +56,7 @@ __exportStar(require("./implementations/data-bus/data-bus-command-handler.cjs"),
 __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.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);

package/dist/cjs/index.d.cts

@@ -40,6 +40,7 @@ export * from './implementations/data-bus/data-bus-command-handler.cjs';
 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.cjs';
 export * from './packages/energy-app-modbus-rtu.cjs';
 export * from './types/enyo-modbus-server.cjs';
 export * from './packages/energy-app-modbus-server.cjs';

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

@@ -1,2 +1,66 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModbusExceptionError = exports.MODBUS_MAX_PDU_PAYLOAD_BYTES = void 0;
+/**
+ * The largest payload {@link EnergyAppModbusInstance.sendRawPdu} accepts, in bytes.
+ *
+ * A Modbus PDU is capped at 253 bytes; one of those is the function code, leaving 252 for
+ * the payload.
+ */
+exports.MODBUS_MAX_PDU_PAYLOAD_BYTES = 252;
+/**
+ * Thrown when a Modbus device answered a request with an exception response — the device is
+ * reachable and the frame was well-formed, it simply refused the operation.
+ *
+ * This is deliberately distinct from a transport failure. An app probing whether it is
+ * allowed to write (write a register back its own value and see what happens) needs
+ * "refused with code 0x80" to be reliably distinguishable from "timed out" or "socket
+ * dropped", and a generic `Error` with the code buried in its message string is not a
+ * contract anything can be built on.
+ *
+ * The socket is left intact when this is thrown: an exception response is a protocol answer,
+ * not a broken link.
+ *
+ * Note that {@link EnergyAppModbusInstance.sendRawPdu} does *not* throw this — a raw PDU
+ * reports its exception as data on {@link ModbusRawPduResponse.exceptionCode}, because there
+ * the exception is frequently the expected outcome rather than a failure.
+ *
+ * @example
+ * ```ts
+ * try {
+ *     await instance.writeSingleRegister(43006, currentValue);
+ *     // The write landed — this connection may write.
+ * } catch (error) {
+ *     if (error instanceof ModbusExceptionError && error.exceptionCode === 0x80) {
+ *         // Refused for lack of permission — a login is required.
+ *     }
+ *     throw error;
+ * }
+ * ```
+ */
+class ModbusExceptionError extends Error {
+    exceptionCode;
+    functionCode;
+    address;
+    /**
+     * @param exceptionCode The raw exception code the device answered with. Standard codes
+     *                      are `0x01`…`0x0B`; vendor-specific codes are passed through
+     *                      unvalidated.
+     * @param functionCode  The function code of the request that was refused (the request's
+     *                      own code, without the exception high bit).
+     * @param message       Human-readable description, including the operation that failed.
+     * @param address       The register or coil address involved, when the operation had
+     *                      one.
+     */
+    constructor(exceptionCode, functionCode, message, address) {
+        super(message);
+        this.exceptionCode = exceptionCode;
+        this.functionCode = functionCode;
+        this.address = address;
+        this.name = 'ModbusExceptionError';
+        // Restores the prototype chain so `instanceof` holds when this package is consumed
+        // from code compiled down to ES5.
+        Object.setPrototypeOf(this, ModbusExceptionError.prototype);
+    }
+}
+exports.ModbusExceptionError = ModbusExceptionError;

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

@@ -98,4 +98,163 @@ export interface EnergyAppModbusInstance {
     writeMultipleRegisters: (address: number, values: number[]) => Promise<void>;
     /** Read holding register string value */
     readRegisterStringValue: (address: number, quantity: number) => Promise<string>;
+    /**
+     * Sends one Modbus PDU verbatim on this connection and returns the raw response.
+     *
+     * This is the escape hatch for vendor function codes — the sub-commands a manufacturer
+     * reserves for itself outside the eight standard codes, such as the installer login a
+     * Huawei SUN2000 requires before it accepts a single control write. The transport owns
+     * framing (MBAP header, transaction id, unit id) exactly as it does for every other
+     * request; `payload` is put on the wire untouched and the response bytes come back
+     * untouched.
+     *
+     * The call is queued on the same per-connection chain as the standard reads and writes,
+     * so it honours {@link ModbusOptions.noParallelRequests} and
+     * {@link ModbusOptions.waitBetweenMessagesMs} and can never be interleaved with a block
+     * read that is already in flight.
+     *
+     * A device that answers with an exception resolves rather than rejects: the exception
+     * code is data (see {@link ModbusRawPduResponse.exceptionCode}), because for a
+     * permission probe "not allowed" is the expected answer and has to be distinguishable
+     * from a timeout or a dropped socket. Only transport failures reject.
+     *
+     * Request payloads are never logged — a vendor handshake typically carries a credential
+     * digest. Only the function code and the payload length appear in the logs.
+     *
+     * @param functionCode Modbus function code, 1…127. The exception space (`>= 0x80`) and
+     *                     `0` are rejected; the eight standard codes are allowed but the
+     *                     dedicated methods above are the better way to reach them.
+     * @param payload      PDU bytes after the function code. At most
+     *                     {@link MODBUS_MAX_PDU_PAYLOAD_BYTES} bytes, so the frame stays
+     *                     within the 253-byte Modbus PDU limit. May be empty.
+     * @param options      Optional per-call overrides.
+     * @throws Error if the parameters are out of range, if the connection is gone, or if the
+     *         device does not answer within the deadline.
+     */
+    sendRawPdu: (functionCode: number, payload: Buffer, options?: ModbusRawPduOptions) => Promise<ModbusRawPduResponse>;
+    /**
+     * Registers a listener that fires whenever the underlying socket for this unit has been
+     * replaced — a reconnect after a dropped link, a recycled half-open socket, or a stale
+     * socket torn down by the transport.
+     *
+     * This matters for anything the device tracks per connection rather than per device.
+     * A vendor login, for instance, grants permission to the *socket* that authenticated:
+     * once that socket is gone the permission is gone with it, silently — the next write
+     * simply comes back with an exception. The listener is the point at which an app can
+     * re-authenticate before the next command instead of after a failed one.
+     *
+     * The listener fires once per socket replacement, after the old socket is gone and
+     * before the next operation is served. It is not called for the initial connect.
+     * Listeners must not throw; a throwing listener is logged and ignored.
+     *
+     * @param listener Called with no arguments once per socket replacement.
+     * @returns A function that removes the listener. Every listener is dropped automatically
+     *          on {@link EnergyAppModbusInstance.disconnect}.
+     */
+    onReconnect: (listener: () => void) => () => void;
+    /**
+     * Monotonic counter of how many sockets this unit has been bound to, starting at `1` for
+     * the first live socket.
+     *
+     * The pull-based counterpart to {@link EnergyAppModbusInstance.onReconnect}: read it
+     * before and after an operation to tell whether connection-scoped state (a vendor login,
+     * a session token) survived, without having to keep a listener alive. A value that
+     * changed means the socket was replaced and anything scoped to it is void.
+     *
+     * Returns `0` while the instance has never had a live socket.
+     */
+    connectionGeneration: () => number;
+}
+/**
+ * Per-call options for {@link EnergyAppModbusInstance.sendRawPdu}.
+ */
+export interface ModbusRawPduOptions {
+    /**
+     * Deadline for this single request in milliseconds. Defaults to the connection's
+     * {@link ModbusOptions.readTimeoutMs}. As with every other operation, exceeding it is
+     * treated as a dead link and recycles the socket.
+     */
+    timeoutMs?: number;
+}
+/**
+ * The raw answer to a {@link EnergyAppModbusInstance.sendRawPdu} call.
+ *
+ * Both a normal response and a device-level exception arrive here; only transport failures
+ * are thrown. Check {@link ModbusRawPduResponse.exceptionCode} first — it is `undefined`
+ * exactly when the device accepted the request.
+ */
+export interface ModbusRawPduResponse {
+    /**
+     * The function code the device echoed. On an exception this is the requested code with
+     * the high bit set (`functionCode | 0x80`), which is what the device actually put on the
+     * wire.
+     */
+    functionCode: number;
+    /**
+     * The response bytes that followed the function code, with vendor framing intact.
+     * Empty on an exception — the exception code is reported separately rather than left in
+     * the payload.
+     */
+    payload: Buffer;
+    /**
+     * The device's exception code when it rejected the request, otherwise `undefined`.
+     *
+     * Standard Modbus defines `0x01`…`0x0B`, but vendors add their own — Huawei answers
+     * `0x80` for "permission authentication failure or permission expiration" — so this is
+     * the raw byte, passed through without validation against the standard set.
+     */
+    exceptionCode?: number;
+}
+/**
+ * The largest payload {@link EnergyAppModbusInstance.sendRawPdu} accepts, in bytes.
+ *
+ * A Modbus PDU is capped at 253 bytes; one of those is the function code, leaving 252 for
+ * the payload.
+ */
+export declare const MODBUS_MAX_PDU_PAYLOAD_BYTES = 252;
+/**
+ * Thrown when a Modbus device answered a request with an exception response — the device is
+ * reachable and the frame was well-formed, it simply refused the operation.
+ *
+ * This is deliberately distinct from a transport failure. An app probing whether it is
+ * allowed to write (write a register back its own value and see what happens) needs
+ * "refused with code 0x80" to be reliably distinguishable from "timed out" or "socket
+ * dropped", and a generic `Error` with the code buried in its message string is not a
+ * contract anything can be built on.
+ *
+ * The socket is left intact when this is thrown: an exception response is a protocol answer,
+ * not a broken link.
+ *
+ * Note that {@link EnergyAppModbusInstance.sendRawPdu} does *not* throw this — a raw PDU
+ * reports its exception as data on {@link ModbusRawPduResponse.exceptionCode}, because there
+ * the exception is frequently the expected outcome rather than a failure.
+ *
+ * @example
+ * ```ts
+ * try {
+ *     await instance.writeSingleRegister(43006, currentValue);
+ *     // The write landed — this connection may write.
+ * } catch (error) {
+ *     if (error instanceof ModbusExceptionError && error.exceptionCode === 0x80) {
+ *         // Refused for lack of permission — a login is required.
+ *     }
+ *     throw error;
+ * }
+ * ```
+ */
+export declare class ModbusExceptionError extends Error {
+    readonly exceptionCode: number;
+    readonly functionCode: number;
+    readonly address?: number | undefined;
+    /**
+     * @param exceptionCode The raw exception code the device answered with. Standard codes
+     *                      are `0x01`…`0x0B`; vendor-specific codes are passed through
+     *                      unvalidated.
+     * @param functionCode  The function code of the request that was refused (the request's
+     *                      own code, without the exception high bit).
+     * @param message       Human-readable description, including the operation that failed.
+     * @param address       The register or coil address involved, when the operation had
+     *                      one.
+     */
+    constructor(exceptionCode: number, functionCode: number, message: string, address?: number | undefined);
 }

package/dist/cjs/types/enyo-appliance-command-forecast.cjs

@@ -90,9 +90,15 @@ var BatteryCommandForecastDirectionEnum;
     /** Power should flow from the battery into the home / grid (discharging). */
     BatteryCommandForecastDirectionEnum["Discharge"] = "discharge";
     /**
-     * No energy flow — the battery holds its current state-of-charge.
-     * Use to mark idle periods between charge / discharge entries. The
-     * entry's `powerW` must be `0`.
+     * Leave the slot to the battery's own logic — for the duration of
+     * the entry the appliance decides itself whether to charge,
+     * discharge or stand still (auto mode).
+     *
+     * This is *not* a "no energy flow" marker: to block charging or
+     * discharging, use {@link BatteryCommandForecastDirectionEnum.Charge}
+     * respectively {@link BatteryCommandForecastDirectionEnum.Discharge}
+     * with `powerW = 0`. An `Idle` entry prescribes no setpoint, so its
+     * `powerW` must be `0`.
      */
     BatteryCommandForecastDirectionEnum["Idle"] = "idle";
 })(BatteryCommandForecastDirectionEnum || (exports.BatteryCommandForecastDirectionEnum = BatteryCommandForecastDirectionEnum = {}));

package/dist/cjs/types/enyo-appliance-command-forecast.d.cts

@@ -180,9 +180,15 @@ export declare enum BatteryCommandForecastDirectionEnum {
     /** Power should flow from the battery into the home / grid (discharging). */
     Discharge = "discharge",
     /**
-     * No energy flow — the battery holds its current state-of-charge.
-     * Use to mark idle periods between charge / discharge entries. The
-     * entry's `powerW` must be `0`.
+     * Leave the slot to the battery's own logic — for the duration of
+     * the entry the appliance decides itself whether to charge,
+     * discharge or stand still (auto mode).
+     *
+     * This is *not* a "no energy flow" marker: to block charging or
+     * discharging, use {@link BatteryCommandForecastDirectionEnum.Charge}
+     * respectively {@link BatteryCommandForecastDirectionEnum.Discharge}
+     * with `powerW = 0`. An `Idle` entry prescribes no setpoint, so its
+     * `powerW` must be `0`.
      */
     Idle = "idle"
 }
@@ -205,11 +211,12 @@ export interface BatteryCommandForecastScheduleEntry {
     /**
      * Target power in Watts. Always non-negative — direction is carried
      * by {@link direction}, never by sign. A `powerW` of `0` together
-     * with a `Charge` or `Discharge` direction means "hold at zero in
-     * the named direction" (effectively idle until the next entry);
-     * prefer the explicit
-     * {@link BatteryCommandForecastDirectionEnum.Idle} direction for
-     * unambiguous idle slots, in which case `powerW` must also be `0`.
+     * with a `Charge` or `Discharge` direction blocks that direction —
+     * the battery must not charge respectively discharge until the next
+     * entry. Use that to keep the battery still, *not*
+     * {@link BatteryCommandForecastDirectionEnum.Idle}, which hands
+     * control back to the appliance's own logic and prescribes no
+     * setpoint at all (its `powerW` must be `0`).
      */
     powerW: number;
 }

package/dist/cjs/types/enyo-data-bus-value.cjs

@@ -324,9 +324,11 @@ var EnyoStorageScheduleModeEnum;
  * non-negative, and consumers never have to disambiguate `0` from
  * "direction-of-zero" or interpret sign conventions per integration.
  *
- * `Idle` is the explicit "no energy flow" marker — use it to insert
- * idle slots between charge / discharge periods. An entry with
- * `direction = Idle` must carry `powerW = 0`.
+ * `Idle` hands the slot back to the battery's own logic — it does *not*
+ * mean "no energy flow". To keep the battery still, use `Charge` or
+ * `Discharge` with `powerW = 0`, which blocks that direction for the
+ * duration of the entry. An `Idle` entry prescribes no setpoint, so it
+ * must carry `powerW = 0`.
  */
 var EnyoStorageScheduleDirectionEnum;
 (function (EnyoStorageScheduleDirectionEnum) {
@@ -335,9 +337,15 @@ var EnyoStorageScheduleDirectionEnum;
     /** Power should flow from the battery into the grid / home (discharging). */
     EnyoStorageScheduleDirectionEnum["Discharge"] = "discharge";
     /**
-     * No energy flow — the battery holds its current state-of-charge.
-     * Use to mark idle periods between charge / discharge entries. The
-     * entry's `powerW` must be `0`.
+     * Leave the slot to the battery's own logic — for the duration of
+     * the entry the appliance decides itself whether to charge,
+     * discharge or stand still (auto mode).
+     *
+     * This is *not* a "no energy flow" marker: to block charging or
+     * discharging, use {@link EnyoStorageScheduleDirectionEnum.Charge}
+     * respectively {@link EnyoStorageScheduleDirectionEnum.Discharge}
+     * with `powerW = 0`. An `Idle` entry prescribes no setpoint, so its
+     * `powerW` must be `0`.
      */
     EnyoStorageScheduleDirectionEnum["Idle"] = "idle";
 })(EnyoStorageScheduleDirectionEnum || (exports.EnyoStorageScheduleDirectionEnum = EnyoStorageScheduleDirectionEnum = {}));

package/dist/cjs/types/enyo-data-bus-value.d.cts

@@ -1637,9 +1637,11 @@ export declare enum EnyoStorageScheduleModeEnum {
  * non-negative, and consumers never have to disambiguate `0` from
  * "direction-of-zero" or interpret sign conventions per integration.
  *
- * `Idle` is the explicit "no energy flow" marker — use it to insert
- * idle slots between charge / discharge periods. An entry with
- * `direction = Idle` must carry `powerW = 0`.
+ * `Idle` hands the slot back to the battery's own logic — it does *not*
+ * mean "no energy flow". To keep the battery still, use `Charge` or
+ * `Discharge` with `powerW = 0`, which blocks that direction for the
+ * duration of the entry. An `Idle` entry prescribes no setpoint, so it
+ * must carry `powerW = 0`.
  */
 export declare enum EnyoStorageScheduleDirectionEnum {
     /** Power should flow from the grid into the battery (charging). */
@@ -1647,9 +1649,15 @@ export declare enum EnyoStorageScheduleDirectionEnum {
     /** Power should flow from the battery into the grid / home (discharging). */
     Discharge = "discharge",
     /**
-     * No energy flow — the battery holds its current state-of-charge.
-     * Use to mark idle periods between charge / discharge entries. The
-     * entry's `powerW` must be `0`.
+     * Leave the slot to the battery's own logic — for the duration of
+     * the entry the appliance decides itself whether to charge,
+     * discharge or stand still (auto mode).
+     *
+     * This is *not* a "no energy flow" marker: to block charging or
+     * discharging, use {@link EnyoStorageScheduleDirectionEnum.Charge}
+     * respectively {@link EnyoStorageScheduleDirectionEnum.Discharge}
+     * with `powerW = 0`. An `Idle` entry prescribes no setpoint, so its
+     * `powerW` must be `0`.
      */
     Idle = "idle"
 }
@@ -1679,10 +1687,11 @@ export interface EnyoStorageScheduleEntry {
      * Target power for this setpoint in Watts. Always non-negative —
      * direction is carried by {@link direction}, never by sign. A
      * `powerW` of `0` together with a `Charge` or `Discharge` direction
-     * means "hold at zero in the named direction" (effectively idle
-     * until the next entry); prefer the explicit
-     * {@link EnyoStorageScheduleDirectionEnum.Idle} direction for
-     * unambiguous idle slots, in which case `powerW` must also be `0`.
+     * blocks that direction — the battery must not charge respectively
+     * discharge until the next entry. Use that to keep the battery
+     * still, *not* {@link EnyoStorageScheduleDirectionEnum.Idle}, which
+     * hands control back to the appliance's own logic and prescribes no
+     * setpoint at all (its `powerW` must be `0`).
      */
     powerW: number;
 }

package/dist/cjs/version.cjs

@@ -9,7 +9,7 @@ exports.getSdkVersion = getSdkVersion;
 /**
  * Current version of the enyo Energy App SDK.
  */
-exports.SDK_VERSION = '1.8.0';
+exports.SDK_VERSION = '1.9.0';
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/cjs/version.d.cts

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export declare const SDK_VERSION = "1.8.0";
+export declare const SDK_VERSION = "1.9.0";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/index.d.ts

@@ -40,6 +40,7 @@ export * from './implementations/data-bus/data-bus-command-handler.js';
 export * from './types/enyo-currency.js';
 export * from './packages/energy-app-sequence-generator.js';
 export * from './packages/energy-app-energy-prices.js';
+export * from './packages/energy-app-modbus.js';
 export * from './packages/energy-app-modbus-rtu.js';
 export * from './types/enyo-modbus-server.js';
 export * from './packages/energy-app-modbus-server.js';

package/dist/index.js

@@ -40,6 +40,7 @@ export * from './implementations/data-bus/data-bus-command-handler.js';
 export * from './types/enyo-currency.js';
 export * from './packages/energy-app-sequence-generator.js';
 export * from './packages/energy-app-energy-prices.js';
+export * from './packages/energy-app-modbus.js';
 export * from './packages/energy-app-modbus-rtu.js';
 export * from './types/enyo-modbus-server.js';
 export * from './packages/energy-app-modbus-server.js';

package/dist/packages/energy-app-modbus.d.ts

@@ -98,4 +98,163 @@ export interface EnergyAppModbusInstance {
     writeMultipleRegisters: (address: number, values: number[]) => Promise<void>;
     /** Read holding register string value */
     readRegisterStringValue: (address: number, quantity: number) => Promise<string>;
+    /**
+     * Sends one Modbus PDU verbatim on this connection and returns the raw response.
+     *
+     * This is the escape hatch for vendor function codes — the sub-commands a manufacturer
+     * reserves for itself outside the eight standard codes, such as the installer login a
+     * Huawei SUN2000 requires before it accepts a single control write. The transport owns
+     * framing (MBAP header, transaction id, unit id) exactly as it does for every other
+     * request; `payload` is put on the wire untouched and the response bytes come back
+     * untouched.
+     *
+     * The call is queued on the same per-connection chain as the standard reads and writes,
+     * so it honours {@link ModbusOptions.noParallelRequests} and
+     * {@link ModbusOptions.waitBetweenMessagesMs} and can never be interleaved with a block
+     * read that is already in flight.
+     *
+     * A device that answers with an exception resolves rather than rejects: the exception
+     * code is data (see {@link ModbusRawPduResponse.exceptionCode}), because for a
+     * permission probe "not allowed" is the expected answer and has to be distinguishable
+     * from a timeout or a dropped socket. Only transport failures reject.
+     *
+     * Request payloads are never logged — a vendor handshake typically carries a credential
+     * digest. Only the function code and the payload length appear in the logs.
+     *
+     * @param functionCode Modbus function code, 1…127. The exception space (`>= 0x80`) and
+     *                     `0` are rejected; the eight standard codes are allowed but the
+     *                     dedicated methods above are the better way to reach them.
+     * @param payload      PDU bytes after the function code. At most
+     *                     {@link MODBUS_MAX_PDU_PAYLOAD_BYTES} bytes, so the frame stays
+     *                     within the 253-byte Modbus PDU limit. May be empty.
+     * @param options      Optional per-call overrides.
+     * @throws Error if the parameters are out of range, if the connection is gone, or if the
+     *         device does not answer within the deadline.
+     */
+    sendRawPdu: (functionCode: number, payload: Buffer, options?: ModbusRawPduOptions) => Promise<ModbusRawPduResponse>;
+    /**
+     * Registers a listener that fires whenever the underlying socket for this unit has been
+     * replaced — a reconnect after a dropped link, a recycled half-open socket, or a stale
+     * socket torn down by the transport.
+     *
+     * This matters for anything the device tracks per connection rather than per device.
+     * A vendor login, for instance, grants permission to the *socket* that authenticated:
+     * once that socket is gone the permission is gone with it, silently — the next write
+     * simply comes back with an exception. The listener is the point at which an app can
+     * re-authenticate before the next command instead of after a failed one.
+     *
+     * The listener fires once per socket replacement, after the old socket is gone and
+     * before the next operation is served. It is not called for the initial connect.
+     * Listeners must not throw; a throwing listener is logged and ignored.
+     *
+     * @param listener Called with no arguments once per socket replacement.
+     * @returns A function that removes the listener. Every listener is dropped automatically
+     *          on {@link EnergyAppModbusInstance.disconnect}.
+     */
+    onReconnect: (listener: () => void) => () => void;
+    /**
+     * Monotonic counter of how many sockets this unit has been bound to, starting at `1` for
+     * the first live socket.
+     *
+     * The pull-based counterpart to {@link EnergyAppModbusInstance.onReconnect}: read it
+     * before and after an operation to tell whether connection-scoped state (a vendor login,
+     * a session token) survived, without having to keep a listener alive. A value that
+     * changed means the socket was replaced and anything scoped to it is void.
+     *
+     * Returns `0` while the instance has never had a live socket.
+     */
+    connectionGeneration: () => number;
+}
+/**
+ * Per-call options for {@link EnergyAppModbusInstance.sendRawPdu}.
+ */
+export interface ModbusRawPduOptions {
+    /**
+     * Deadline for this single request in milliseconds. Defaults to the connection's
+     * {@link ModbusOptions.readTimeoutMs}. As with every other operation, exceeding it is
+     * treated as a dead link and recycles the socket.
+     */
+    timeoutMs?: number;
+}
+/**
+ * The raw answer to a {@link EnergyAppModbusInstance.sendRawPdu} call.
+ *
+ * Both a normal response and a device-level exception arrive here; only transport failures
+ * are thrown. Check {@link ModbusRawPduResponse.exceptionCode} first — it is `undefined`
+ * exactly when the device accepted the request.
+ */
+export interface ModbusRawPduResponse {
+    /**
+     * The function code the device echoed. On an exception this is the requested code with
+     * the high bit set (`functionCode | 0x80`), which is what the device actually put on the
+     * wire.
+     */
+    functionCode: number;
+    /**
+     * The response bytes that followed the function code, with vendor framing intact.
+     * Empty on an exception — the exception code is reported separately rather than left in
+     * the payload.
+     */
+    payload: Buffer;
+    /**
+     * The device's exception code when it rejected the request, otherwise `undefined`.
+     *
+     * Standard Modbus defines `0x01`…`0x0B`, but vendors add their own — Huawei answers
+     * `0x80` for "permission authentication failure or permission expiration" — so this is
+     * the raw byte, passed through without validation against the standard set.
+     */
+    exceptionCode?: number;
+}
+/**
+ * The largest payload {@link EnergyAppModbusInstance.sendRawPdu} accepts, in bytes.
+ *
+ * A Modbus PDU is capped at 253 bytes; one of those is the function code, leaving 252 for
+ * the payload.
+ */
+export declare const MODBUS_MAX_PDU_PAYLOAD_BYTES = 252;
+/**
+ * Thrown when a Modbus device answered a request with an exception response — the device is
+ * reachable and the frame was well-formed, it simply refused the operation.
+ *
+ * This is deliberately distinct from a transport failure. An app probing whether it is
+ * allowed to write (write a register back its own value and see what happens) needs
+ * "refused with code 0x80" to be reliably distinguishable from "timed out" or "socket
+ * dropped", and a generic `Error` with the code buried in its message string is not a
+ * contract anything can be built on.
+ *
+ * The socket is left intact when this is thrown: an exception response is a protocol answer,
+ * not a broken link.
+ *
+ * Note that {@link EnergyAppModbusInstance.sendRawPdu} does *not* throw this — a raw PDU
+ * reports its exception as data on {@link ModbusRawPduResponse.exceptionCode}, because there
+ * the exception is frequently the expected outcome rather than a failure.
+ *
+ * @example
+ * ```ts
+ * try {
+ *     await instance.writeSingleRegister(43006, currentValue);
+ *     // The write landed — this connection may write.
+ * } catch (error) {
+ *     if (error instanceof ModbusExceptionError && error.exceptionCode === 0x80) {
+ *         // Refused for lack of permission — a login is required.
+ *     }
+ *     throw error;
+ * }
+ * ```
+ */
+export declare class ModbusExceptionError extends Error {
+    readonly exceptionCode: number;
+    readonly functionCode: number;
+    readonly address?: number | undefined;
+    /**
+     * @param exceptionCode The raw exception code the device answered with. Standard codes
+     *                      are `0x01`…`0x0B`; vendor-specific codes are passed through
+     *                      unvalidated.
+     * @param functionCode  The function code of the request that was refused (the request's
+     *                      own code, without the exception high bit).
+     * @param message       Human-readable description, including the operation that failed.
+     * @param address       The register or coil address involved, when the operation had
+     *                      one.
+     */
+    constructor(exceptionCode: number, functionCode: number, message: string, address?: number | undefined);
 }

package/dist/packages/energy-app-modbus.js

@@ -1 +1,62 @@
-export {};
+/**
+ * The largest payload {@link EnergyAppModbusInstance.sendRawPdu} accepts, in bytes.
+ *
+ * A Modbus PDU is capped at 253 bytes; one of those is the function code, leaving 252 for
+ * the payload.
+ */
+export const MODBUS_MAX_PDU_PAYLOAD_BYTES = 252;
+/**
+ * Thrown when a Modbus device answered a request with an exception response — the device is
+ * reachable and the frame was well-formed, it simply refused the operation.
+ *
+ * This is deliberately distinct from a transport failure. An app probing whether it is
+ * allowed to write (write a register back its own value and see what happens) needs
+ * "refused with code 0x80" to be reliably distinguishable from "timed out" or "socket
+ * dropped", and a generic `Error` with the code buried in its message string is not a
+ * contract anything can be built on.
+ *
+ * The socket is left intact when this is thrown: an exception response is a protocol answer,
+ * not a broken link.
+ *
+ * Note that {@link EnergyAppModbusInstance.sendRawPdu} does *not* throw this — a raw PDU
+ * reports its exception as data on {@link ModbusRawPduResponse.exceptionCode}, because there
+ * the exception is frequently the expected outcome rather than a failure.
+ *
+ * @example
+ * ```ts
+ * try {
+ *     await instance.writeSingleRegister(43006, currentValue);
+ *     // The write landed — this connection may write.
+ * } catch (error) {
+ *     if (error instanceof ModbusExceptionError && error.exceptionCode === 0x80) {
+ *         // Refused for lack of permission — a login is required.
+ *     }
+ *     throw error;
+ * }
+ * ```
+ */
+export class ModbusExceptionError extends Error {
+    exceptionCode;
+    functionCode;
+    address;
+    /**
+     * @param exceptionCode The raw exception code the device answered with. Standard codes
+     *                      are `0x01`…`0x0B`; vendor-specific codes are passed through
+     *                      unvalidated.
+     * @param functionCode  The function code of the request that was refused (the request's
+     *                      own code, without the exception high bit).
+     * @param message       Human-readable description, including the operation that failed.
+     * @param address       The register or coil address involved, when the operation had
+     *                      one.
+     */
+    constructor(exceptionCode, functionCode, message, address) {
+        super(message);
+        this.exceptionCode = exceptionCode;
+        this.functionCode = functionCode;
+        this.address = address;
+        this.name = 'ModbusExceptionError';
+        // Restores the prototype chain so `instanceof` holds when this package is consumed
+        // from code compiled down to ES5.
+        Object.setPrototypeOf(this, ModbusExceptionError.prototype);
+    }
+}

package/dist/types/enyo-appliance-command-forecast.d.ts

@@ -180,9 +180,15 @@ export declare enum BatteryCommandForecastDirectionEnum {
     /** Power should flow from the battery into the home / grid (discharging). */
     Discharge = "discharge",
     /**
-     * No energy flow — the battery holds its current state-of-charge.
-     * Use to mark idle periods between charge / discharge entries. The
-     * entry's `powerW` must be `0`.
+     * Leave the slot to the battery's own logic — for the duration of
+     * the entry the appliance decides itself whether to charge,
+     * discharge or stand still (auto mode).
+     *
+     * This is *not* a "no energy flow" marker: to block charging or
+     * discharging, use {@link BatteryCommandForecastDirectionEnum.Charge}
+     * respectively {@link BatteryCommandForecastDirectionEnum.Discharge}
+     * with `powerW = 0`. An `Idle` entry prescribes no setpoint, so its
+     * `powerW` must be `0`.
      */
     Idle = "idle"
 }
@@ -205,11 +211,12 @@ export interface BatteryCommandForecastScheduleEntry {
     /**
      * Target power in Watts. Always non-negative — direction is carried
      * by {@link direction}, never by sign. A `powerW` of `0` together
-     * with a `Charge` or `Discharge` direction means "hold at zero in
-     * the named direction" (effectively idle until the next entry);
-     * prefer the explicit
-     * {@link BatteryCommandForecastDirectionEnum.Idle} direction for
-     * unambiguous idle slots, in which case `powerW` must also be `0`.
+     * with a `Charge` or `Discharge` direction blocks that direction —
+     * the battery must not charge respectively discharge until the next
+     * entry. Use that to keep the battery still, *not*
+     * {@link BatteryCommandForecastDirectionEnum.Idle}, which hands
+     * control back to the appliance's own logic and prescribes no
+     * setpoint at all (its `powerW` must be `0`).
      */
     powerW: number;
 }

package/dist/types/enyo-appliance-command-forecast.js

@@ -87,9 +87,15 @@ export var BatteryCommandForecastDirectionEnum;
     /** Power should flow from the battery into the home / grid (discharging). */
     BatteryCommandForecastDirectionEnum["Discharge"] = "discharge";
     /**
-     * No energy flow — the battery holds its current state-of-charge.
-     * Use to mark idle periods between charge / discharge entries. The
-     * entry's `powerW` must be `0`.
+     * Leave the slot to the battery's own logic — for the duration of
+     * the entry the appliance decides itself whether to charge,
+     * discharge or stand still (auto mode).
+     *
+     * This is *not* a "no energy flow" marker: to block charging or
+     * discharging, use {@link BatteryCommandForecastDirectionEnum.Charge}
+     * respectively {@link BatteryCommandForecastDirectionEnum.Discharge}
+     * with `powerW = 0`. An `Idle` entry prescribes no setpoint, so its
+     * `powerW` must be `0`.
      */
     BatteryCommandForecastDirectionEnum["Idle"] = "idle";
 })(BatteryCommandForecastDirectionEnum || (BatteryCommandForecastDirectionEnum = {}));

package/dist/types/enyo-data-bus-value.d.ts

@@ -1637,9 +1637,11 @@ export declare enum EnyoStorageScheduleModeEnum {
  * non-negative, and consumers never have to disambiguate `0` from
  * "direction-of-zero" or interpret sign conventions per integration.
  *
- * `Idle` is the explicit "no energy flow" marker — use it to insert
- * idle slots between charge / discharge periods. An entry with
- * `direction = Idle` must carry `powerW = 0`.
+ * `Idle` hands the slot back to the battery's own logic — it does *not*
+ * mean "no energy flow". To keep the battery still, use `Charge` or
+ * `Discharge` with `powerW = 0`, which blocks that direction for the
+ * duration of the entry. An `Idle` entry prescribes no setpoint, so it
+ * must carry `powerW = 0`.
  */
 export declare enum EnyoStorageScheduleDirectionEnum {
     /** Power should flow from the grid into the battery (charging). */
@@ -1647,9 +1649,15 @@ export declare enum EnyoStorageScheduleDirectionEnum {
     /** Power should flow from the battery into the grid / home (discharging). */
     Discharge = "discharge",
     /**
-     * No energy flow — the battery holds its current state-of-charge.
-     * Use to mark idle periods between charge / discharge entries. The
-     * entry's `powerW` must be `0`.
+     * Leave the slot to the battery's own logic — for the duration of
+     * the entry the appliance decides itself whether to charge,
+     * discharge or stand still (auto mode).
+     *
+     * This is *not* a "no energy flow" marker: to block charging or
+     * discharging, use {@link EnyoStorageScheduleDirectionEnum.Charge}
+     * respectively {@link EnyoStorageScheduleDirectionEnum.Discharge}
+     * with `powerW = 0`. An `Idle` entry prescribes no setpoint, so its
+     * `powerW` must be `0`.
      */
     Idle = "idle"
 }
@@ -1679,10 +1687,11 @@ export interface EnyoStorageScheduleEntry {
      * Target power for this setpoint in Watts. Always non-negative —
      * direction is carried by {@link direction}, never by sign. A
      * `powerW` of `0` together with a `Charge` or `Discharge` direction
-     * means "hold at zero in the named direction" (effectively idle
-     * until the next entry); prefer the explicit
-     * {@link EnyoStorageScheduleDirectionEnum.Idle} direction for
-     * unambiguous idle slots, in which case `powerW` must also be `0`.
+     * blocks that direction — the battery must not charge respectively
+     * discharge until the next entry. Use that to keep the battery
+     * still, *not* {@link EnyoStorageScheduleDirectionEnum.Idle}, which
+     * hands control back to the appliance's own logic and prescribes no
+     * setpoint at all (its `powerW` must be `0`).
      */
     powerW: number;
 }

package/dist/types/enyo-data-bus-value.js

@@ -321,9 +321,11 @@ export var EnyoStorageScheduleModeEnum;
  * non-negative, and consumers never have to disambiguate `0` from
  * "direction-of-zero" or interpret sign conventions per integration.
  *
- * `Idle` is the explicit "no energy flow" marker — use it to insert
- * idle slots between charge / discharge periods. An entry with
- * `direction = Idle` must carry `powerW = 0`.
+ * `Idle` hands the slot back to the battery's own logic — it does *not*
+ * mean "no energy flow". To keep the battery still, use `Charge` or
+ * `Discharge` with `powerW = 0`, which blocks that direction for the
+ * duration of the entry. An `Idle` entry prescribes no setpoint, so it
+ * must carry `powerW = 0`.
  */
 export var EnyoStorageScheduleDirectionEnum;
 (function (EnyoStorageScheduleDirectionEnum) {
@@ -332,9 +334,15 @@ export var EnyoStorageScheduleDirectionEnum;
     /** Power should flow from the battery into the grid / home (discharging). */
     EnyoStorageScheduleDirectionEnum["Discharge"] = "discharge";
     /**
-     * No energy flow — the battery holds its current state-of-charge.
-     * Use to mark idle periods between charge / discharge entries. The
-     * entry's `powerW` must be `0`.
+     * Leave the slot to the battery's own logic — for the duration of
+     * the entry the appliance decides itself whether to charge,
+     * discharge or stand still (auto mode).
+     *
+     * This is *not* a "no energy flow" marker: to block charging or
+     * discharging, use {@link EnyoStorageScheduleDirectionEnum.Charge}
+     * respectively {@link EnyoStorageScheduleDirectionEnum.Discharge}
+     * with `powerW = 0`. An `Idle` entry prescribes no setpoint, so its
+     * `powerW` must be `0`.
      */
     EnyoStorageScheduleDirectionEnum["Idle"] = "idle";
 })(EnyoStorageScheduleDirectionEnum || (EnyoStorageScheduleDirectionEnum = {}));

package/dist/version.d.ts

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export declare const SDK_VERSION = "1.8.0";
+export declare const SDK_VERSION = "1.9.0";
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/dist/version.js

@@ -5,7 +5,7 @@
 /**
  * Current version of the enyo Energy App SDK.
  */
-export const SDK_VERSION = '1.8.0';
+export const SDK_VERSION = '1.9.0';
 /**
  * Gets the current SDK version.
  * @returns The semantic version string of the SDK

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enyo-energy/energy-app-sdk",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "enyo Energy App SDK",
   "type": "module",
   "main": "dist/index.js",