@smarthome.exchange/integrations 1.0.0 → 2.0.0

package/ts/integrations/daikin/readme.md

@@ -0,0 +1,83 @@
+# Daikin selected BRP069 integration
+
+This integration connects one explicitly selected Daikin BRP069 LAN controller to native smarthome.exchange devices, entities, service calls, feature writes and observation events. The published `@ecobridge.xyz/devicemanager` `DaikinProtocol` owns HTTP, validation, fresh write preflight, preservation, bounded FIFO operations, cancellation and terminal transport drain.
+
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
+
+## Connect and control
+
+```typescript
+import { DaikinIntegration, type IDaikinNativeConfig } from '@smarthome.exchange/integrations';
+
+const integration = new DaikinIntegration();
+const config: IDaikinNativeConfig = {
+  homeId: 'selected-home',
+  apiVariant: 'brp069',
+  host: '192.168.1.40',
+  expectedMac: '409F38D107AC',
+  allowPlaintext: true,
+  timeoutMs: 5000,
+};
+const runtime = await integration.setup(config, { homeId: 'selected-home' });
+try {
+  const device = (await runtime.devices())[0];
+  const power = device.features.find((feature) => feature.id === 'power');
+  if (power?.writable) {
+    const result = await runtime.writeFeature!({ device, feature: power, value: false });
+    console.log(result.success, result.data);
+  }
+} finally {
+  await integration.destroy();
+}
+```
+
+Live setup requires an exact home ID, explicit `brp069` selection, private literal IPv4 address, exact twelve-hex-digit unicast adapter MAC, and `allowPlaintext: true`. Loopback is accepted for local fixtures. The LAN API is unauthenticated HTTP; observing the expected MAC does not authenticate the peer. DNS, automatic family selection, redirects, credentials, cloud fallback and effect retries are unsupported. `name`, `port`, `timeoutMs`, `maxResponseBytes` and `maxPendingOperations` are optional. Protocol limits are enforced by the published protocol.
+
+The embedding host must separately pass its selected `homeId` in setup and configuration-flow context. Configuration, editable form values, discovery and store scope cannot select the owner home. An optional constructor binding, `new DaikinIntegration({ homeId: 'selected-home' })`, adds a consistency constraint and still requires explicit context home. An unbound instance binds once on its first valid host admission and keeps that home after failed verification. Flow and setup share admission. The public `DaikinClient(config, { homeId: 'selected-home' })` also requires independent host context and captures it before protocol construction. This is a trusted embedding-host contract; a home string is not an authentication credential.
+
+Configuration flow and setup independently read basic information, model information and current control. A prior successful flow does not authorize setup against a changed endpoint. Discovery matches only bounded received mDNS, UDP, HTTP and manual hints; it sends no broadcasts or probes and copies no arbitrary metadata, credentials or payloads into candidates. A discovery match requires independent selected-controller verification.
+
+## Native observations and effects
+
+Device and entity IDs contain the exact home scope and adapter identity. Power and an observed target temperature are mapped from actual protocol state. Mode, target humidity, fan and direction remain observations. This protocol does not read ambient temperature, ambient humidity, energy, zones or physical HVAC action; it does not create those sensors or infer cooling/heating activity from the configured operating mode.
+
+Only explicit boolean power and explicit integer Celsius targets are writable. Targets require the current observed cool mode (18–33 °C) or heat mode (10–31 °C), supported temperature advertisement, the recorded standard `temp_rng=0` model family and a numeric current target. Other range encodings remain read only. An incomplete required fan/direction control family also remains read only. Capabilities shown by a previous read are descriptive; each effect delegates fresh capability checks to the protocol. Target writes preserve power and never implicitly turn on the controller. Every write preserves current required mode, target, humidity, fan and direction fields except the explicitly requested power or target.
+
+Services accept an exact owned entity or device target. Supplying both requires agreement. Platform domains must match the selected climate or power entity. Supported controls are `climate.turn_on`, `climate.turn_off`, `climate.set_temperature` with only numeric `temperature`, and `switch.turn_on`/`turn_off` on the power entity. `daikin.refresh` returns a fresh snapshot for an owned target. Mode changes, fan changes, direction changes, humidity changes, presets, toggles, zones and implicit values are rejected. Feature writes require an exact owned device and supported feature shape. Accessors, symbol fields, unknown service fields and unrelated targets are rejected before effect traffic.
+
+Results forward the protocol acknowledgment, requested values, independent observation and `effectOutcome`. `success: true` requires `confirmed`; accepted mismatched readback remains `indeterminate`. Errors retain `not-sent`, `rejected` or `indeterminate`. There are no optimistic snapshot mutations or automatic effect replays. Confirmation describes state at observation; another controller can change the unit between preflight and dispatch because BRP069 has no compare-and-set operation.
+
+`runtime.subscribe` emits changed state after requested fresh reads or effect readback, availability changes and errors. It does not start polling or claim a device push stream. Unsubscribe and subscriber abort remove that listener. A failed listener is removed and reported without changing a completed effect outcome. Setup lifetime abort, runtime destruction and integration destruction cancel owned HTTP work, remove listeners, drain queued and active protocol operations, and permanently reject further work. Integration destruction also joins pending setup and configuration-flow verification continuations and prevents later submission of previously returned forms. Configuration-flow and integration destruction wait for every owned cleanup to settle even when another cleanup fails. They then reject with an `AggregateError` preserving original failures inside resource groups. Repeated destruction returns the same terminal promise. Failed resources remain owned and count toward capacity; `integration.retryCleanup()` or `configFlow.retryCleanup()` explicitly retries cleanup without replaying transport operations. The shared default capacity is 16 resources across pending setup, runtimes and flow verification; `new DaikinIntegration({ capacity: 8 })` can choose a smaller bound. Closing the child flow leaves successful integration runtimes active. Caller-owned stores and databases remain untouched.
+
+## Configuration ownership and migration
+
+`configFlow.start(candidate, { homeId: 'selected-home' })` captures the host context and returns verified, credential-free configuration for that home. The form has no editable home field and rejects a conflicting submitted home before HTTP. It performs no persistence writes. Setup, flow and public-client context accept an optional caller-owned encrypted `NoSqlConfigStore` whose home ID and `daikin` domain must exactly match the admitted host home. Structural stores cannot grant admission. `IntegrationRuntimeManager` owns runtime activation and retirement. The caller decides whether and under which key to store returned configuration; the integration never closes the caller's store, database or encryption provider. No configuration persistence is required for credential-free BRP069 control.
+
+Native setup now requires `IDaikinNativeConfig`; configurations containing injected clients, command executors, snapshots, raw data, API keys or passwords are rejected. Automatic and unsupported controller families are rejected explicitly rather than becoming a ready fixture runtime. `DaikinClient.execute`, legacy command executor/client interfaces and `DaikinMapper.commandForService` are replaced by public-protocol-backed `setControl`, exact-target runtime services and `writeFeature`.
+
+The existing `DaikinMapper.toSnapshot`, raw-response parsers and translation helpers remain explicit offline utilities for BRP069, BRP072C, AirBase, SkyFi and BRP084 data. Their devices expose no writable features and their entities advertise no service controls. They do not create a live runtime. Operating mode alone is no longer reported as physical heating/cooling activity.
+
+Real HTTP and in-memory NoSQL fixtures cover these contracts. Physical Daikin hardware and firmware interoperability have not been verified. The protocol's primary sources and detailed wire limits are documented in the published [devicemanager README](https://code.foss.global/ecobridge.xyz/devicemanager#readme).
+
+## License and Legal Information
+
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [repository license file](../../../license.md).
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
+
+### Company Information
+
+Task Venture Capital GmbH<br>
+Registered at District Court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.