@smarthome.exchange/integrations 1.0.0 → 2.0.0

package/ts/integrations/modbus/modbus.types.ts

@@ -1,407 +1,90 @@
-export type TModbusTransport = 'tcp' | 'udp' | 'rtuovertcp' | 'serial';
+import type * as plugins from '../../plugins.js';
+import type { INativeIntegrationOwnerOptions } from '../../core/classes.nativeintegrationowner.js';
 
-export type TModbusRegisterType = 'holding' | 'input';
+export interface IModbusIntegrationOptions extends INativeIntegrationOwnerOptions {}
 
-export type TModbusCoilType = 'coil' | 'discrete_input';
-
-export type TModbusDataType =
-  | 'custom'
-  | 'string'
-  | 'int'
-  | 'integer'
-  | 'int16'
-  | 'int32'
-  | 'int64'
-  | 'uint'
-  | 'uint16'
-  | 'uint32'
-  | 'uint64'
-  | 'float'
-  | 'float16'
-  | 'float32'
-  | 'float64';
-
-export type TModbusSwap = 'byte' | 'word' | 'word_byte';
-
-export type TModbusEntityPlatform = 'sensor' | 'binary_sensor' | 'switch' | 'number';
-
-export type TModbusEventType =
-  | 'snapshot_refreshed'
-  | 'command_mapped'
-  | 'command_executed'
-  | 'command_failed'
-  | 'register_read'
-  | 'register_written'
-  | 'coil_read'
-  | 'coil_written';
-
-export interface IModbusConfig {
-  hubs?: IModbusHubConfig[];
-  modbus?: IModbusHubConfig[];
-  snapshot?: IModbusSnapshot;
-  manualEntries?: IModbusManualTcpEntry[];
-  connected?: boolean;
-  timeoutMs?: number;
-  commandExecutor?: (commandArg: IModbusCommand) => Promise<IModbusCommandResult | unknown>;
+export interface IModbusMappingBase {
+  readonly id: string;
+  readonly name: string;
+  /** Zero-based wire address; no 40001 notation or vendor interpretation. */
+  readonly address: number;
+  readonly quantity?: number;
 }
 
-export interface IHomeAssistantModbusConfig extends IModbusConfig {}
-
-export interface IModbusHubConfig {
-  id?: string;
-  name?: string;
-  type?: TModbusTransport;
-  host?: string;
-  port?: number | string;
-  timeout?: number;
-  timeoutMs?: number;
-  delay?: number;
-  messageWaitMilliseconds?: number;
-  message_wait_milliseconds?: number;
-  slave?: number;
-  unit?: number;
-  unitId?: number;
-  deviceAddress?: number;
-  device_address?: number;
-  connected?: boolean;
-  manufacturer?: string;
-  model?: string;
-  serialNumber?: string;
-  serial_number?: string;
-  metadata?: Record<string, unknown>;
-  slaves?: IModbusSlaveConfig[];
-  registers?: IModbusRegisterConfig[];
-  coils?: IModbusCoilConfig[];
-  sensors?: IModbusRegisterConfig[];
-  binarySensors?: IModbusCoilConfig[];
-  binary_sensors?: IModbusCoilConfig[];
-  switches?: IModbusSwitchConfig[];
-  numbers?: IModbusNumberConfig[];
-}
-
-export interface IModbusSlaveConfig {
-  id?: string;
-  unitId?: number;
-  unit?: number;
-  slave?: number;
-  deviceAddress?: number;
-  device_address?: number;
-  name?: string;
-  connected?: boolean;
-  manufacturer?: string;
-  model?: string;
-  serialNumber?: string;
-  serial_number?: string;
-  metadata?: Record<string, unknown>;
+export interface IModbusCoilMapping extends IModbusMappingBase {
+  readonly kind: 'coil';
+  /** Owner permission for one absolute FC5 write. Requires quantity one. */
+  readonly write?: true;
 }
 
-export interface IModbusEntityConfigBase {
-  id?: string;
-  name: string;
-  uniqueId?: string;
-  unique_id?: string;
-  platform?: TModbusEntityPlatform;
-  address: number;
-  slave?: number;
-  unit?: number;
-  unitId?: number;
-  deviceAddress?: number;
-  device_address?: number;
-  scanInterval?: number;
-  scan_interval?: number;
-  deviceClass?: string;
-  device_class?: string;
-  available?: boolean;
-  metadata?: Record<string, unknown>;
+export interface IModbusDiscreteInputMapping extends IModbusMappingBase {
+  readonly kind: 'discrete_input';
 }
 
-export interface IModbusRegisterConfig extends IModbusEntityConfigBase {
-  platform?: 'sensor' | 'number';
-  inputType?: TModbusRegisterType;
-  input_type?: TModbusRegisterType;
-  registerType?: TModbusRegisterType;
-  register_type?: TModbusRegisterType;
-  count?: number;
-  dataType?: TModbusDataType;
-  data_type?: TModbusDataType;
-  structure?: string;
-  scale?: number;
-  offset?: number;
-  precision?: number;
-  swap?: TModbusSwap;
-  unitOfMeasurement?: string;
-  unit_of_measurement?: string;
-  stateClass?: string;
-  state_class?: string;
-  minValue?: number;
-  min_value?: number;
-  maxValue?: number;
-  max_value?: number;
-  nanValue?: number;
-  nan_value?: number;
-  zeroSuppress?: number;
-  zero_suppress?: number;
-  min?: number;
-  max?: number;
-  step?: number;
-  writable?: boolean;
-  value?: number | string | null;
-  registers?: number[];
+export interface IModbusHoldingRegisterMapping extends IModbusMappingBase {
+  readonly kind: 'holding';
+  /** Inclusive unsigned raw bounds for one FC6 write. Requires quantity one. */
+  readonly write?: { readonly minimum: number; readonly maximum: number };
 }
 
-export interface IModbusNumberConfig extends IModbusRegisterConfig {
-  platform?: 'number';
-  writable?: true;
+export interface IModbusInputRegisterMapping extends IModbusMappingBase {
+  readonly kind: 'input';
 }
 
-export interface IModbusCoilConfig extends IModbusEntityConfigBase {
-  platform?: 'binary_sensor' | 'switch';
-  inputType?: TModbusCoilType | TModbusRegisterType;
-  input_type?: TModbusCoilType | TModbusRegisterType;
-  coilType?: TModbusCoilType;
-  coil_type?: TModbusCoilType;
-  count?: number;
-  slaveCount?: number;
-  slave_count?: number;
-  virtualCount?: number;
-  virtual_count?: number;
-  writable?: boolean;
-  value?: boolean | number | null;
-  bits?: boolean[];
-}
+export type TModbusMapping = IModbusCoilMapping | IModbusDiscreteInputMapping | IModbusHoldingRegisterMapping | IModbusInputRegisterMapping;
+export type TModbusNormalizedMapping = TModbusMapping & { readonly quantity: number };
 
-export interface IModbusSwitchConfig extends IModbusCoilConfig {
-  platform?: 'switch';
-  writeType?: TModbusWriteType;
-  write_type?: TModbusWriteType;
-  commandOn?: number;
-  command_on?: number;
-  commandOff?: number;
-  command_off?: number;
-  stateOn?: number[];
-  state_on?: number[];
-  stateOff?: number[];
-  state_off?: number[];
-  verify?: IModbusSwitchVerifyConfig | null;
-}
-
-export interface IModbusSwitchVerifyConfig {
-  address?: number;
-  inputType?: TModbusCoilType | TModbusRegisterType;
-  input_type?: TModbusCoilType | TModbusRegisterType;
-  delay?: number;
-  stateOn?: number[];
-  state_on?: number[];
-  stateOff?: number[];
-  state_off?: number[];
-}
-
-export type TModbusWriteType = 'holding' | 'holdings' | 'coil' | 'coils';
-
-export interface IModbusRegisterState {
-  hubId?: string;
-  unitId: number;
-  address: number;
-  count: number;
-  inputType: TModbusRegisterType;
-  dataType: TModbusDataType;
-  registers?: number[];
-  value?: number | string | number[] | null;
-  updatedAt?: string;
-  metadata?: Record<string, unknown>;
-}
-
-export interface IModbusCoilState {
-  hubId?: string;
-  unitId: number;
-  address: number;
-  count: number;
-  inputType: TModbusCoilType | TModbusRegisterType;
-  bits?: boolean[];
-  value?: boolean | number | null;
-  updatedAt?: string;
-  metadata?: Record<string, unknown>;
+export interface IModbusConfig {
+  readonly homeId: string;
+  readonly address: string;
+  readonly unitId: number;
+  readonly expectedVendorName: string;
+  readonly expectedProductCode: string;
+  readonly expectedRevision?: string;
+  readonly allowUnencryptedLan: true;
+  readonly mappings: readonly TModbusMapping[];
+  readonly port?: number;
+  readonly localAddress?: string;
+  readonly name?: string;
+  readonly timeoutMs?: number;
+  readonly maxQueuedOperations?: number;
 }
 
-export interface IModbusEntitySnapshot {
-  id: string;
-  name: string;
-  uniqueId: string;
-  platform: TModbusEntityPlatform;
-  hubId: string;
-  hubName: string;
-  unitId: number;
-  address: number;
-  available: boolean;
-  writable: boolean;
-  register?: IModbusRegisterState;
-  coil?: IModbusCoilState;
-  state?: unknown;
-  attributes?: Record<string, unknown>;
-}
+export interface IHomeAssistantModbusConfig extends IModbusConfig {}
 
-export interface IModbusSlaveSnapshot {
-  id: string;
-  hubId: string;
-  unitId: number;
-  name: string;
-  online: boolean;
-  manufacturer?: string;
-  model?: string;
-  serialNumber?: string;
-  registers: IModbusRegisterState[];
-  coils: IModbusCoilState[];
-  metadata?: Record<string, unknown>;
+export interface IModbusNormalizedConfig extends Omit<IModbusConfig, 'mappings' | 'port' | 'timeoutMs' | 'maxQueuedOperations'> {
+  readonly mappings: readonly TModbusNormalizedMapping[];
+  readonly port: number;
+  readonly timeoutMs: number;
+  readonly maxQueuedOperations: number;
 }
 
-export interface IModbusHubSnapshot {
-  id: string;
-  name: string;
-  type: TModbusTransport;
-  host?: string;
-  port?: number | string;
-  online: boolean;
-  manufacturer?: string;
-  model?: string;
-  serialNumber?: string;
-  unsupportedReason?: string;
-  slaves: IModbusSlaveSnapshot[];
-  registers: IModbusRegisterState[];
-  coils: IModbusCoilState[];
-  entities: IModbusEntitySnapshot[];
-  metadata?: Record<string, unknown>;
+export interface IModbusObservation {
+  readonly mapping: TModbusNormalizedMapping;
+  readonly identity: plugins.ecobridgeDeviceManager.IModbusIdentity;
+  readonly values: readonly boolean[] | readonly number[];
+  readonly observedAt: string;
 }
 
 export interface IModbusSnapshot {
-  hubs: IModbusHubSnapshot[];
-  events: IModbusEvent[];
-  connected: boolean;
-  updatedAt: string;
-  raw?: Record<string, unknown>;
-}
-
-export interface IModbusEvent {
-  type: TModbusEventType;
-  command?: IModbusCommand;
-  hubId?: string;
-  hubName?: string;
-  unitId?: number;
-  entityId?: string;
-  deviceId?: string;
-  uniqueId?: string;
-  data?: unknown;
-  timestamp: number;
+  readonly config: IModbusNormalizedConfig;
+  readonly identity: plugins.ecobridgeDeviceManager.IModbusIdentity;
+  readonly observations: readonly IModbusObservation[];
+  readonly observedAt: string;
 }
 
-export type IModbusCommand =
-  | IModbusRefreshCommand
-  | IModbusReadRegisterCommand
-  | IModbusWriteRegisterCommand
-  | IModbusReadCoilCommand
-  | IModbusWriteCoilCommand
-  | IModbusStopCommand
-  | IModbusRestartCommand;
-
-export interface IModbusCommandBase {
-  hub?: string;
-  hubId?: string;
-  unitId?: number;
-  slave?: number;
-  entityId?: string;
-  deviceId?: string;
-  uniqueId?: string;
-}
-
-export interface IModbusRefreshCommand extends IModbusCommandBase {
-  type: 'refresh';
-}
-
-export interface IModbusStopCommand extends IModbusCommandBase {
-  type: 'stop';
-}
-
-export interface IModbusRestartCommand extends IModbusCommandBase {
-  type: 'restart';
-}
-
-export interface IModbusReadRegisterCommand extends IModbusCommandBase {
-  type: 'read_register';
-  address: number;
-  count?: number;
-  inputType?: TModbusRegisterType;
-  dataType?: TModbusDataType;
-}
-
-export interface IModbusWriteRegisterCommand extends IModbusCommandBase {
-  type: 'write_register';
-  address: number;
-  value: number | number[];
-}
-
-export interface IModbusReadCoilCommand extends IModbusCommandBase {
-  type: 'read_coil';
-  address: number;
-  count?: number;
-  inputType?: TModbusCoilType;
-}
-
-export interface IModbusWriteCoilCommand extends IModbusCommandBase {
-  type: 'write_coil';
-  address: number;
-  value: boolean | boolean[] | number | number[];
-}
-
-export interface IModbusCommandResult {
-  success: boolean;
-  error?: string;
-  data?: unknown;
-}
-
-export interface IModbusTcpCommandShape {
-  transport: 'tcp';
-  host?: string;
-  port?: number;
-  unitId: number;
-  transactionId: number;
-  functionCode: number;
-  functionName: string;
-  address?: number;
-  quantity?: number;
-  values?: number[] | boolean[];
-  mbap: {
-    transactionId: number;
-    protocolId: 0;
-    length: number;
-    unitId: number;
-  };
-  pduHex: string;
-  requestHex: string;
-}
-
-export interface IModbusTcpResponse {
-  transactionId: number;
-  unitId: number;
-  functionCode: number;
-  registers?: number[];
-  bits?: boolean[];
-  address?: number;
-  quantity?: number;
-  rawHex: string;
-}
+export type TModbusCommand =
+  | { readonly type: 'read'; readonly mappingId: string }
+  | { readonly type: 'write_coil'; readonly mappingId: string; readonly value: boolean }
+  | { readonly type: 'write_register'; readonly mappingId: string; readonly value: number };
 
 export interface IModbusManualTcpEntry {
-  host?: string;
-  port?: number;
-  type?: TModbusTransport;
-  protocol?: string;
-  name?: string;
-  id?: string;
-  unitId?: number;
-  slave?: number;
-  manufacturer?: string;
-  model?: string;
-  serialNumber?: string;
-  metadata?: Record<string, unknown>;
+  readonly integrationDomain: 'modbus';
+  readonly address: string;
+  readonly unitId: number;
+  readonly expectedVendorName: string;
+  readonly expectedProductCode: string;
+  readonly expectedRevision?: string;
+  readonly port?: number;
+  readonly name?: string;
 }
-
-export interface IModbusDiscoveryEntry extends IModbusManualTcpEntry {}

package/ts/integrations/modbus/modbus.validation.ts

@@ -0,0 +1,119 @@
+import * as plugins from '../../plugins.js';
+import type { IModbusNormalizedConfig, TModbusCommand, TModbusNormalizedMapping } from './modbus.types.js';
+
+export function modbusRecord(valueArg: unknown, allowedArg?: readonly string[]): Record<string, unknown> {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg) || ![Object.prototype, null].includes(Object.getPrototypeOf(valueArg))) {
+    throw new TypeError('Modbus inputs must be plain data objects.');
+  }
+  const result: Record<string, unknown> = {};
+  for (const key of Reflect.ownKeys(valueArg)) {
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+    if (typeof key !== 'string' || allowedArg && !allowedArg.includes(key) || !descriptor || !('value' in descriptor) || !descriptor.enumerable) {
+      throw new TypeError('Modbus inputs may not contain accessors, symbols, hidden or unsupported fields.');
+    }
+    Object.defineProperty(result, key, { value: descriptor.value, enumerable: true });
+  }
+  return result;
+}
+
+export function modbusText(valueArg: unknown, nameArg: string, maximumArg = 256): string {
+  if (typeof valueArg !== 'string' || !valueArg.length || valueArg.length > maximumArg || valueArg !== valueArg.trim() || /[\p{Cc}\p{Cs}]/u.test(valueArg)) {
+    throw new TypeError(`Modbus ${nameArg} requires bounded nonempty text without control characters.`);
+  }
+  return valueArg;
+}
+
+export function modbusIdentityText(valueArg: unknown): string {
+  if (typeof valueArg !== 'string' || !/^[\x20-\x7e]{1,244}$/.test(valueArg)) throw new TypeError('Modbus identity requires exact bounded printable ASCII text.');
+  return valueArg;
+}
+
+export function modbusAddress(valueArg: unknown): string {
+  if (typeof valueArg !== 'string' || plugins.net.isIP(valueArg) !== 4) throw new TypeError('Modbus requires an explicitly selected local IPv4 address.');
+  const parts = valueArg.split('.').map(Number);
+  const local = parts[0] === 10 || parts[0] === 127 || parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31 ||
+    parts[0] === 192 && parts[1] === 168 || parts[0] === 169 && parts[1] === 254;
+  if (!local || parts[3] === 255) throw new TypeError('Modbus requires a private, link-local or loopback unicast IPv4 address.');
+  return valueArg;
+}
+
+export function modbusInteger(valueArg: unknown, minimumArg: number, maximumArg: number): number {
+  if (typeof valueArg !== 'number' || !Number.isSafeInteger(valueArg) || valueArg < minimumArg || valueArg > maximumArg) {
+    throw new TypeError(`Modbus value must be an integer from ${minimumArg} through ${maximumArg}.`);
+  }
+  return valueArg;
+}
+
+export function modbusUnit(valueArg: unknown): number {
+  const unit = modbusInteger(valueArg, 1, 255);
+  if (unit > 247 && unit !== 255) throw new TypeError('Modbus requires an explicit unit 1–247 or direct TCP unit 255.');
+  return unit;
+}
+
+export function normalizeModbusConfig(valueArg: unknown): IModbusNormalizedConfig {
+  const value = modbusRecord(valueArg, ['homeId', 'address', 'unitId', 'expectedVendorName', 'expectedProductCode', 'expectedRevision',
+    'allowUnencryptedLan', 'mappings', 'port', 'localAddress', 'name', 'timeoutMs', 'maxQueuedOperations']);
+  if (value.allowUnencryptedLan !== true) throw new TypeError('Modbus requires explicit acceptance of unencrypted LAN transport.');
+  const mappings = modbusMappings(value.mappings);
+  return Object.freeze({
+    homeId: modbusText(value.homeId, 'homeId'), address: modbusAddress(value.address), unitId: modbusUnit(value.unitId),
+    expectedVendorName: modbusIdentityText(value.expectedVendorName), expectedProductCode: modbusIdentityText(value.expectedProductCode),
+    ...(value.expectedRevision === undefined ? {} : { expectedRevision: modbusIdentityText(value.expectedRevision) }),
+    ...(value.localAddress === undefined ? {} : { localAddress: modbusAddress(value.localAddress) }),
+    ...(value.name === undefined ? {} : { name: modbusText(value.name, 'name', 128) }), allowUnencryptedLan: true,
+    port: modbusInteger(value.port === undefined ? 502 : value.port, 1, 65535),
+    timeoutMs: modbusInteger(value.timeoutMs === undefined ? 5000 : value.timeoutMs, 1, 60000),
+    maxQueuedOperations: modbusInteger(value.maxQueuedOperations === undefined ? 16 : value.maxQueuedOperations, 1, 128), mappings,
+  });
+}
+
+export function modbusMappings(valueArg: unknown): readonly TModbusNormalizedMapping[] {
+  if (!Array.isArray(valueArg) || valueArg.length < 1 || valueArg.length > 64) throw new TypeError('Modbus requires one through 64 explicit owner read mappings.');
+  if (Reflect.ownKeys(valueArg).some((key) => key !== 'length' && (typeof key !== 'string' || !/^(0|[1-9]\d*)$/.test(key)))) throw new TypeError('Modbus mapping lists contain only indexed data entries.');
+  const mappings: TModbusNormalizedMapping[] = [];
+  for (let index = 0; index < valueArg.length; index++) {
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, String(index));
+    if (!descriptor || !('value' in descriptor) || !descriptor.enumerable) throw new TypeError('Modbus mappings must be dense enumerable data entries.');
+    const value = modbusRecord(descriptor.value, ['id', 'name', 'address', 'quantity', 'kind', 'write']);
+    const id = modbusText(value.id, 'mapping id', 64);
+    if (!/^[a-z0-9][a-z0-9_-]*$/.test(id)) throw new TypeError('Modbus mapping IDs require lowercase letters, digits, underscore or hyphen.');
+    const name = modbusText(value.name, 'mapping name', 128);
+    const address = modbusInteger(value.address, 0, 65535);
+    const kind = value.kind;
+    if (kind !== 'coil' && kind !== 'discrete_input' && kind !== 'holding' && kind !== 'input') throw new TypeError('Modbus mapping kind is unsupported.');
+    const quantity = modbusInteger(value.quantity === undefined ? 1 : value.quantity, 1, kind === 'coil' || kind === 'discrete_input' ? 2000 : 125);
+    if (address + quantity > 65536) throw new TypeError('Modbus mapping exceeds the zero-based address space.');
+    if (mappings.some((mapping) => mapping.id === id || mapping.kind === kind && address < mapping.address + mapping.quantity && mapping.address < address + quantity)) {
+      throw new TypeError('Modbus mappings require unique IDs and nonoverlapping ranges per read kind.');
+    }
+    let mapping: TModbusNormalizedMapping;
+    if (value.write === undefined) mapping = { id, name, address, quantity, kind };
+    else {
+      if (quantity !== 1) throw new TypeError('Modbus write permission requires one absolute mapped address.');
+      if (kind === 'coil' && value.write === true) mapping = { id, name, address, quantity, kind, write: true };
+      else if (kind === 'holding') {
+        const write = modbusRecord(value.write, ['minimum', 'maximum']);
+        const minimum = modbusInteger(write.minimum, 0, 65535);
+        const maximum = modbusInteger(write.maximum, minimum, 65535);
+        mapping = { id, name, address, quantity, kind, write: Object.freeze({ minimum, maximum }) };
+      } else throw new TypeError('Modbus permits explicit single-coil or bounded single-holding-register writes only.');
+    }
+    mappings.push(Object.freeze(mapping));
+  }
+  return Object.freeze(mappings);
+}
+
+export function modbusCommand(valueArg: unknown, configArg: IModbusNormalizedConfig): TModbusCommand {
+  const value = modbusRecord(valueArg, ['type', 'mappingId', 'value']);
+  const mappingId = modbusText(value.mappingId, 'mapping id', 64);
+  const mapping = configArg.mappings.find((entry) => entry.id === mappingId);
+  if (!mapping) throw new TypeError('Modbus command must target one explicitly owned read mapping.');
+  if (value.type === 'read' && !Object.hasOwn(value, 'value')) return Object.freeze({ type: 'read', mappingId });
+  if (value.type === 'write_coil' && mapping.kind === 'coil' && mapping.write === true && typeof value.value === 'boolean') {
+    return Object.freeze({ type: 'write_coil', mappingId, value: value.value });
+  }
+  if (value.type === 'write_register' && mapping.kind === 'holding' && mapping.write !== undefined) {
+    return Object.freeze({ type: 'write_register', mappingId, value: modbusInteger(value.value, mapping.write.minimum, mapping.write.maximum) });
+  }
+  throw new TypeError('Modbus command is outside the explicit mapping write permission or absolute raw value contract.');
+}