daikin-local-control 0.3.1 → 0.5.0

package/DESIGN.md

@@ -53,6 +53,46 @@ the read. A `DaikinState` holds the current mode's values alone: it has neither
 the values a classic adapter remembers for the other modes nor the `md` of a
 DSIOT leaf, so the client would still need the reply.
 
+## Discovery
+
+`discoverDevices` sends its probes from the first free UDP port from 30000 to
+30050. An adapter answers the port a probe came from, so a reply reaches the
+call that sent the probe.
+
+Rejected: port 30000 alone, bound with `reuseAddr`.
+
+- Two calls at the same time both bound the port, and each reply reached one
+  of the two sockets alone. One call resolved with every adapter and the other
+  with none, and neither rejected.
+
+`discoverDevices` asks each adapter that replies as a classic one, over HTTP,
+whether it is an Airbase adapter: `isAirbaseAdapter` takes HTTP 404 at
+`/common/basic_info` with `ret=OK` at `/skyfi/common/basic_info` for one.
+
+Rejected: the protocol from the reply alone.
+
+- An Airbase adapter reports `type=aircon` as a classic adapter does, and no
+  field of the reply is known to differ. Discovery reported it as `classic`,
+  and it answered HTTP 404 to every request of the client built from that.
+
+Rejected: asking in `createDaikinClient`, for a device written by hand as
+well.
+
+- `createDaikinClient` returns a client at once and sends nothing. Asking
+  there would make it asynchronous for every caller, to settle what a caller
+  who writes a device by hand already knows.
+
+`discoverDevices` resolves with the adapters of air conditioners alone:
+`isAirConditioner` passes a reply whose `type` is `aircon`, or `GPF` with a
+`cdev` that is not an air cleaner's.
+
+Rejected: a device for every adapter that answers.
+
+- The adapter of an air cleaner, a water heater, a floor heater or a
+  circulator answers the probe as well. `parseDevice` read each as a classic
+  air conditioner, a `DaikinDevice` had nothing to tell them apart by, and no
+  method of the client built from one worked.
+
 ## Capabilities
 
 `DaikinCapabilities` lists what a unit accepts in the vocabulary of `DaikinState`:
@@ -130,8 +170,11 @@ Rejected: positions as the numbers 0 to 25, typed `number`, with
 ## Special modes
 
 `DaikinState.specialModes` lists the special modes that are on, and `getState`
-reads it on both protocols. `DaikinControl` leaves it out, so `setState` is
-never handed a field it cannot write: UNSUPPORTED.md says what is not known.
+reads it on both protocols. `DaikinControl` leaves it out: `setSpecialMode`
+turns one mode on or off, with a request of its own on both protocols. A
+classic adapter takes it at `/aircon/set_special_mode`, beside
+`set_control_info`, and a DSIOT adapter takes one leaf, on the outdoor edge
+for powerful where every leaf `setState` writes is on the indoor edge.
 
 Rejected: a `getSpecialModes` on `ClassicDaikinClient`, beside `setSpecialMode`.
 
@@ -148,3 +191,114 @@ Rejected: one list for the whole unit.
 
 - Econo is not known to be taken in fan mode, so the one list offered it in a
   mode where UNSUPPORTED.md lists it as unknown.
+
+## Simulators
+
+`startClassicSimulator`, `startDsiotSimulator` and `startAirbaseSimulator`
+each start an adapter as a server. A simulator shares the codecs' tables, `src/codecs/*/tables.ts`, and
+none of their functions. A table holds what an adapter calls a thing: its
+field and leaf names, and the code for each value. A function does something
+with it: a codec parses a reply and builds a request, and a simulator answers
+the request, holds what it was sent, and builds the reply.
+
+Rejected: a simulator that builds its replies with the codecs' functions.
+
+- A simulator built from a codec agrees with it by construction. A codec that
+  reads a field wrongly would meet a simulator that writes it wrongly the same
+  way, and the test of one against the other would pass.
+
+Rejected: a simulator with tables of its own, sharing nothing with the codecs.
+
+- Every code was written twice, in two files that had to be kept alike, and a
+  caller setting a field of a simulator by hand had no table to read it from.
+- The second writing caught a wrong code only where the simulator encoded a
+  value itself. `tables.test.ts` writes every entry out again, and catches
+  one wherever it is used.
+
+`package.json` exports the simulators as `daikin-local-control/simulators`,
+an entry of their own beside the package root.
+
+Rejected: exporting them from the package root.
+
+- A caller's production code imports the root. With the simulators in it, that
+  import loads two servers the code never starts, and a bundler has to work
+  out that it can drop them.
+
+A simulator holds its state in the adapter's terms, `controlInfo.stemp` on a
+classic simulator and a leaf's `pv` by its address on a DSIOT one, and takes
+it in the package's models: a `DaikinState`, a `DaikinSensors` and a
+`DaikinDeviceInfo`. It turns a model into the adapter's fields with functions
+of its own, in `src/simulators/`, so a client that reads the state back
+checks the codec that parses it against a second writing of the same
+encoding.
+
+Rejected: options in the adapter's terms alone, a record of strings for each
+reply.
+
+- A caller had to know the adapter's encodings to start a unit in a state: a
+  DSIOT setpoint of 24 °C is the leaf value `3000`.
+
+A classic or a DSIOT simulator takes what the unit has as a
+`DaikinSimulatorUnit`, which says it in terms both protocols have flags for:
+`coolingOnly`, `swing`, `fan`. An Airbase simulator takes an
+`AirbaseSimulatorUnit` of its own: an Airbase unit has zones and airside, and
+neither a cooling-only kind nor a special mode.
+
+Rejected: taking a `DaikinCapabilities`.
+
+- Most values of it are ones no adapter reports. Fan speeds of `auto`,
+  `level1` and `level3` have no `frate_steps`, and a DSIOT adapter reports
+  every fan speed or none, so the simulator would throw for most of what the
+  type allows.
+
+A simulator answers HTTP 501 to a request whose answer from an adapter is not
+known, such as a path it does not serve.
+
+Rejected: answering such a request the way an adapter plausibly would, with
+HTTP 404 or `ret=PARAM NG`.
+
+- A caller's test would then pass or fail on an answer no adapter is known to
+  give. No adapter is known to answer 501, so a caller cannot take it for an
+  adapter's reply.
+
+A simulator answers one request at a time, and a request that arrives
+meanwhile waits for its turn: an adapter makes concurrent requests wait.
+`replyDelayInMs` makes the wait long enough for a test to see. Whether an
+adapter also drops a connection while it is busy is not known, so a simulator
+never does.
+
+A simulator answers the discovery probe only when started with
+`answersDiscovery`.
+
+Rejected: answering it always.
+
+- An adapter answers on UDP port 30050, a fixed port, so a simulator that
+  always bound it could not start beside another program that holds it, in a
+  test that never discovers anything.
+
+Each simulator is at one `address` of the machine, `127.0.0.1` unless it is
+given another. It answers the probe from that address, and the simulators
+share port 30050: each hears the probe on a socket bound to every address,
+and answers from a second socket bound to its own.
+
+Rejected: one socket for each simulator, bound to port 30050 of its own
+address.
+
+- The probe is a broadcast to `255.255.255.255`, and a socket bound to one
+  address receives none of it: two simulators bound that way answered no
+  probe.
+
+Rejected: one socket bound to every address, answering from it.
+
+- The machine then picks the address a reply leaves from, its address on the
+  LAN, so `discoverDevices` reports the simulator there, and the simulator
+  has to listen for HTTP on the LAN where a test needs loopback alone.
+
+`discoverDevices` keeps one device for each `host`, the address a reply came
+from with the `api_port` it announces, so it finds every simulator on a
+machine: they answer from one address and announce a port each.
+
+Rejected: one device for each address.
+
+- Simulators on one machine share its addresses, so a caller could have as
+  many discovered as the machine has addresses, two on a laptop.

package/README.md

@@ -1,26 +1,32 @@
 # daikin-local-control
 
 [![npm version](https://img.shields.io/npm/v/daikin-local-control)](https://www.npmjs.com/package/daikin-local-control)
+[![npm downloads](https://img.shields.io/npm/dm/daikin-local-control)](https://www.npmjs.com/package/daikin-local-control)
 [![CI](https://github.com/cheziyi/daikin-local-control/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/cheziyi/daikin-local-control/actions/workflows/ci.yml?query=branch%3Amain)
 [![Node version](https://img.shields.io/node/v/daikin-local-control)](package.json)
+[![Types](https://img.shields.io/npm/types/daikin-local-control)](package.json)
 [![License](https://img.shields.io/npm/l/daikin-local-control)](LICENSE)
+[![Checked with Biome](https://img.shields.io/badge/Checked_with-Biome-60a5fa?style=flat&logo=biome)](https://biomejs.dev)
 
 A TypeScript and Node.js client for controlling Daikin air conditioners **over
 the local network** (LAN), through their Wi-Fi adapters and with no cloud
-dependency. It implements the same local-control protocol as the **DAIKIN Mobile
-Controller** app, so it works with the units and Wi-Fi adapters that app
-supports — split / multi-split and SkyAir units fitted with adapters such as the
-BRP072A42, BRP072C42 and BRP084 — in the
-[markets where that app is used](#coverage--limitations).
+dependency. It implements the local-control protocols of the **DAIKIN Mobile
+Controller**, **Daikin Airbase** and **ONECTA** apps, so it works with the units
+and Wi-Fi adapters those apps support — split / multi-split, SkyAir and ducted
+units fitted with adapters such as the BRP072A42, BRP072C42, BRP084, BRP069 and
+BRP15B61 — in the [markets where those apps are used](#coverage--limitations).
 
-Daikin Wi-Fi adapters come in two generations, and the package has a client for
-each:
+Daikin Wi-Fi adapters speak one of three protocols, and the package has a
+client for each:
 
 - **`ClassicDaikinClient`** — classic adapters (BRP072A42, BRP072C42, BRP069).
   Full core control plus typed [extended controls](#extended-controls).
 - **`DsiotDaikinClient`** — newer DSIOT adapters (BRP084). Power, mode,
-  setpoint, humidity, fan, swing and louver positions;
+  setpoint, humidity, fan, swing, louver positions and special modes;
   [UNSUPPORTED.md](UNSUPPORTED.md) lists what is not mapped yet.
+- **`AirbaseDaikinClient`** — Airbase adapters (BRP15B61) on ducted units.
+  Power, mode, setpoint, fan and direction, plus [zones](#airbase), fan auto
+  and airside.
 
 You normally don't pick one yourself: `createDaikinClient` chooses the right
 client for each discovered device.
@@ -47,9 +53,9 @@ if (device === undefined) {
   throw new Error("No adapter answered");
 }
 
-// 2. Build the right client: createDaikinClient picks the classic or the DSIOT
-//    client from the device. Pass localPassword only when the adapter has a
-//    child lock code (see Credentials below).
+// 2. Build the right client: createDaikinClient picks the classic, the DSIOT
+//    or the Airbase client from the device. Pass localPassword only when the
+//    adapter has a child lock code (see Credentials below).
 const client = createDaikinClient(device, {
   terminalUuid: savedUuid, // generated once and stored (see Credentials below)
   localPassword: device.requiresLocalPassword ? "<child lock code>" : undefined,
@@ -73,17 +79,19 @@ await client.close();
 
 ### Discovery
 
-`discoverDevices()` resolves with one `DaikinDevice` for each adapter that
-answered, and with an empty array when none did. Each carries the adapter's
-`macAddress`, such as `A4:08:EA:CC:91:D4`, and `firmwareVersion`, such as
-`1.2.51`, when the adapter reports them: key a stored device on `macAddress`,
-because `host` changes when the adapter is given a new address.
+`discoverDevices()` resolves with one `DaikinDevice` for each air conditioner's
+adapter that answered, and with an empty array when none did. Each carries the
+adapter's `macAddress`, such as `A4:08:EA:CC:91:D4`, and `firmwareVersion`,
+such as `1.2.51`, when the adapter reports them: key a stored device on
+`macAddress`, because `host` changes when the adapter is given a new address.
 
 | It | So |
 | --- | --- |
 | Resolves after `timeoutInMs`, never earlier | Pass `discoverDevices({ timeoutInMs: 1000 })` to wait less than the default 3000 |
 | Broadcasts to `255.255.255.255` | It does not find an adapter on another subnet or VLAN |
-| Binds UDP port 30000 | It rejects with the socket's error when the socket fails |
+| Keeps the adapters of air conditioners alone | It leaves out the adapter of an air cleaner, a water heater or another appliance, which answers the same broadcast |
+| Asks each classic adapter over HTTP whether it is an Airbase adapter, which replies to the broadcast as a classic one does | It resolves later than `timeoutInMs` while an adapter is slow to answer, by 3000 ms at most for each request after up to 750 ms of retrying a dropped connection, and reports as `classic` one that does not answer. An Airbase device requires no registration and no child lock code, whatever the adapter's reply says |
+| Binds the first free UDP port from 30000 to 30050 | Calls made at the same time each get every reply. It rejects with the socket's error when none of the ports is free, or when the socket fails |
 
 Write the device by hand when you already know its address, or when discovery
 cannot reach it:
@@ -98,8 +106,13 @@ const client = createDaikinClient(device, { terminalUuid: savedUuid });
 A device written by hand has no `name`, `macAddress` or `firmwareVersion`: read
 them from the adapter with `await client.getDeviceInfo()`.
 
-Set `protocol` to `dsiot` for a BRP084 and to `classic` for every other
-adapter. A device without flags is an adapter that requires neither
+To tell an Airbase adapter from a classic one by its address, request
+`/common/basic_info`: an Airbase adapter answers HTTP 404 there, and `ret=OK`
+at `/skyfi/common/basic_info`.
+
+Set `protocol` to `dsiot` for a BRP084, to `airbase` for a BRP15B61 and to
+`classic` for every other adapter: `createDaikinClient()` goes by it and asks
+the adapter nothing. A device without flags is an adapter that requires neither
 registration nor a child lock code. If yours requires either, set
 `requiresRegistration: true` / `requiresLocalPassword: true` and set up
 [credentials](#credentials) to match; add `usesHttps: true` if it also speaks
@@ -109,25 +122,29 @@ for you.
 ### Credentials
 
 An adapter can need up to three things. Discovery tells you which ones apply
-(`device.requiresRegistration`, `device.requiresLocalPassword`).
+(`device.requiresRegistration`, `device.requiresLocalPassword`). An Airbase
+adapter takes none of them: `createDaikinClient()` still takes a
+`terminalUuid`, and sends it nothing of the three.
 
-**Terminal uuid (always).** It identifies your app to the adapter. Any random
-UUID works. Generate it **once**, store it, and reuse it on every run: an
-adapter that requires registration remembers it, so a new uuid means registering
-again.
+**Terminal uuid (always).** It identifies your app to the adapter. Pass 32
+lowercase hexadecimal digits, a UUID without its dashes: `createDaikinClient()`
+throws an `Error` for any other form, and sends the uuid as given. Generate it
+**once**, store it, and reuse it on every run: an adapter that requires
+registration remembers it, so a new uuid means registering again.
 
 ```ts
 import { randomUUID } from "node:crypto";
 
-const savedUuid = loadFromConfig() ?? saveToConfig(randomUUID());
+const savedUuid =
+  loadFromConfig() ?? saveToConfig(randomUUID().replaceAll("-", ""));
 ```
 
 **KEY (when `device.requiresRegistration` is `true`).** These
 adapters only answer terminals they have registered. Each adapter's KEY is
 printed on its label, next to the SSID (also in the operation manual). Register
 your uuid with it once. Until you do, every call fails with HTTP 401/403.
-Each uuid is registered separately, so an adapter already set up in the DAIKIN
-Mobile Controller app still needs registering here.
+Each uuid is registered separately, so an adapter already set up in a Daikin
+app still needs registering here.
 
 ```ts
 import { ClassicDaikinClient } from "daikin-local-control";
@@ -147,8 +164,8 @@ Some of these adapters also switch to HTTPS (`device.usesHttps`); see
 
 **Child lock code (when `device.requiresLocalPassword` is `true`).** The protocol
 calls it the local password (`lpw`). It is the 4-digit code set under Child lock
-in the DAIKIN Mobile Controller app. It is **not** printed on the label, and it
-is not your Wi-Fi or Out-of-Home password. Pass it as `localPassword` to
+in the Daikin app the adapter was set up with. It is **not** printed on the
+label, and it is not your Wi-Fi or Out-of-Home password. Pass it as `localPassword` to
 `createDaikinClient`. If it's forgotten, the adapter has to be reset.
 
 ### State and capabilities
@@ -201,10 +218,20 @@ given, whether or not the unit lists it.
 | `targetTemperatureInC` | In `fan` and `dehumidify` |
 | `targetHumidity` | In `fan` |
 | `fanSpeed` | In `dehumidify`, and on a DSIOT adapter in `cool` while a humidity setting is on: the fan runs on `auto` |
-| `verticalPosition`, `horizontalPosition` | On a classic adapter, when the unit has no 3D airflow. On a DSIOT adapter, a fixed vertical position the unit lacks, and every fixed horizontal position |
+| `verticalPosition`, `horizontalPosition` | On a classic adapter, when the unit has no 3D airflow. On a DSIOT adapter, a fixed vertical position the unit lacks, and every fixed horizontal position. On an Airbase adapter, always |
+
+An Airbase adapter also drops every `targetHumidity`, and a
+`targetTemperatureInC` in `fan` as well as in `dehumidify`.
 
 `setState()` takes no `specialModes`: turn one on or off with
-[`setSpecialMode()`](#extended-controls), which only a classic adapter has.
+`setSpecialMode()`, which sends a request of its own. Check the mode against
+`getCapabilities().specialModes` first: the client sends any mode as given.
+An Airbase adapter has no request for one, so `AirbaseDaikinClient` rejects
+with a `DaikinError` whose `httpStatusCode` is 501.
+
+```ts
+await client.setSpecialMode("powerful", true);
+```
 
 Pass `maxStateAgeForSetStateInMs` to `createDaikinClient` when you poll the
 state anyway: `setState()` reads the unit before each write, and with it builds
@@ -238,7 +265,6 @@ if (client instanceof ClassicDaikinClient) {
     maxPowerInPercent: 70,
     mode: "manual",
   });
-  await client.setSpecialMode("powerful", true);
   await client.setOutOfHomeAccess(false); // home network only
   await client.setEnergyPrice(0.3); // per kWh
   await client.setMetadata({
@@ -265,6 +291,43 @@ what is not known about each.
 `DsiotDaikinClient` has `reboot()` and the raw `multireqGet` / `multireqUpdate`
 hatches for any `dgc_status` leaf.
 
+### Airbase
+
+`AirbaseDaikinClient` adds the controls a ducted unit has. Narrow to the
+concrete class to reach them:
+
+```ts
+import { AirbaseDaikinClient } from "daikin-local-control";
+
+if (client instanceof AirbaseDaikinClient) {
+  const zones = await client.getZones(); // [{ name: "Living", enabled: true }, ...]
+  await client.setZone(1, true); // open the second zone
+
+  if ((await client.getFanAuto()) !== null) {
+    await client.setFanAuto(true);
+  }
+  if ((await client.getAirside()) !== null) {
+    await client.setAirside(true);
+  }
+
+  // Any other endpoint, by its path below /skyfi.
+  const holiday = await client.command("/common/get_holiday");
+}
+```
+
+| Method | Does |
+| --- | --- |
+| `getZones()` | Resolves with `{ name, enabled }` for each zone, in the unit's order, and with an empty array on a unit without zones |
+| `setZone(index, enabled)` | Opens or closes the zone at that place in `getZones()`, counted from 0 |
+| `getFanAuto()`, `getAirside()` | Resolve with `true` or `false`, or `null` on a unit that does not take the setting |
+| `setFanAuto(enabled)` | Lets the unit pick the fan speed itself, up to the `fanSpeed` that is set. It switches airside off |
+| `setAirside(enabled)` | Switches airside on or off. Switching it on switches fan auto off and sets `fanSpeed` to `level1` |
+
+A `fanSpeed` in `setState()` switches airside off and keeps fan auto.
+
+Only a unit with zones takes fan auto and airside, and it takes no `auto` fan
+speed and no `swingMode`: `getCapabilities()` lists what a unit takes.
+
 ### Errors and retries
 
 A client method that fails rejects with a `DaikinError`; branch on
@@ -276,11 +339,15 @@ A client method that fails rejects with a `DaikinError`; branch on
 | 502 | The adapter answered with an error: a `ret` or `rsc` other than OK, or a reply that does not parse |
 | 503 | The adapter refused or dropped the connection (a `DaikinConnectionError`), or DSIOT answered `rsc` 503 |
 | 504 | The request timed out, or the TLS handshake failed |
+| 501 | `AirbaseDaikinClient.setSpecialMode()`: an Airbase adapter has no request for a special mode |
 | Any other | The adapter's own HTTP status, such as 403 |
 
-Two failures are not a `DaikinError`: `discoverDevices()` rejects with the
-socket's error, and `multireqUpdate()` throws an `Error` for a path that names
-a resource without a leaf, such as `dgc_status`.
+Four failures are not a `DaikinError`: `discoverDevices()` rejects with the
+socket's error, `createDaikinClient()` throws an `Error` for a
+[terminal uuid](#credentials) in the wrong form, `multireqUpdate()` throws
+an `Error` for a path that names a resource without a leaf, such as
+`dgc_status`, and `setZone()` rejects with an `Error` for an index the unit
+has no zone at.
 
 Only a `DaikinConnectionError` is retried, up to five times by default.
 [DESIGN.md](DESIGN.md#retries) says why.
@@ -291,22 +358,181 @@ Only a `DaikinConnectionError` is retried, up to five times by default.
 | Stop a client retrying | `retry: { delaysInMs: [] }` to `createDaikinClient` |
 | Send one request that is not safe to repeat | `{ retry: false }` as the last argument of `command()`, `multireqGet()` or `multireqUpdate()` |
 
-## Coverage & limitations
+### Simulators
+
+Test your code against a simulated adapter instead of a real one: start a
+simulator, and point a client at its `host`. Import the simulators from
+`daikin-local-control/simulators`: the package root does not export them.
+
+```ts
+import { createDaikinClient } from "daikin-local-control";
+import { startClassicSimulator } from "daikin-local-control/simulators";
+
+const simulator = await startClassicSimulator({
+  deviceInfo: { name: "Bedroom", macAddress: "A4:08:EA:CC:91:D4" },
+  unit: { coolingOnly: true, swing: "vertical" },
+  state: { power: true, targetTemperatureInC: 22 },
+  sensors: { indoorTemperatureInC: 27 },
+});
+const client = createDaikinClient(
+  { host: simulator.host, protocol: "classic" },
+  { terminalUuid: savedUuid },
+);
+
+await client.getState(); // power: true, mode: "cool", targetTemperatureInC: 22
+
+simulator.setState({ power: false }); // someone uses the remote control
+simulator.setSensors({ indoorTemperatureInC: 24 }); // the room cools down
+
+await client.close();
+await simulator.stop();
+```
+
+`startDsiotSimulator()` starts a DSIOT adapter and takes the same options:
+pass `protocol: "dsiot"` to `createDaikinClient`.
+`startAirbaseSimulator()` starts an [Airbase adapter](#airbase-simulator):
+pass `protocol: "airbase"`. A simulator speaks plain HTTP on a free port of
+`127.0.0.1`, which nothing outside the machine reaches.
+
+Describe the adapter and its unit in the types the clients resolve with:
+
+| Option | Holds | Defaults to |
+| --- | --- | --- |
+| `deviceInfo` | `name`, `macAddress` and `firmwareVersion`, as `getDeviceInfo()` reads them | A name of `Simulator` |
+| `unit` | What the unit has: see below | A heat pump with every fan speed, swing on both axes and all three special modes |
+| `state` | Any fields of a `DaikinState`, `specialModes` included | Off, in cool at 24 °C, on the auto fan speed |
+| `sensors` | Any fields of a `DaikinSensors`; `null` is a reading the unit lacks | 26 °C and 55 % indoors, 30 °C outdoors |
+
+| `unit` field | Holds | Defaults to |
+| --- | --- | --- |
+| `coolingOnly` | `true` for a unit that offers dehumidify, cool and fan alone | `false` |
+| `fan` | `false` for a unit whose fan speed cannot be set | `true` |
+| `fanLevels` | 2, 3 or 5 fan levels. Classic simulator only | 5 |
+| `swing` | `none`, `vertical` or `both` | `both` |
+| `specialModes` | Those of `powerful`, `econo` and `streamer` the unit takes | All three |
+| `coolTemperaturesInC`, `heatTemperaturesInC` | `{ min, max }` | 18 to 32 and 10 to 30 |
+
+`setState()` and `setSensors()` change a running simulator the same way.
+`setState()` throws an `Error` for a field the unit has nothing to hold, such
+as a `verticalPosition` on a unit without fixed louver positions.
+
+#### Airbase simulator
+
+`startAirbaseSimulator()` takes `deviceInfo`, `state` and `sensors` as the
+other two do, and a `unit` of its own. It reports no humidity unless
+`sensors` gives one, and its `setState()` throws an `Error` for a
+`targetHumidity`, a louver position or a special mode.
+
+```ts
+import { startAirbaseSimulator } from "daikin-local-control/simulators";
+
+const simulator = await startAirbaseSimulator({
+  unit: { zones: ["Living", "Bedrooms"], airside: true },
+  state: { power: true, fanSpeed: "level3" },
+});
 
-It supports the same markets and Wi-Fi adapters as the DAIKIN Mobile Controller
-app, so it is **not valid for every Daikin region or app**.
+simulator.setZone(1, false); // someone closes a zone on the wall controller
+simulator.controlInfo.f_auto = "1"; // and switches fan auto on
+```
+
+| `unit` field | Holds | Defaults to |
+| --- | --- | --- |
+| `zones` | The names of the unit's zones, each open at the start | None: a unit without zones |
+| `auto`, `dehumidify` | `false` for a unit that does not offer the mode | `true` |
+| `fan` | `false` for a unit whose fan speed cannot be set | `true` |
+| `fanLevels` | 2 or 3 fan levels | 3 |
+| `airside` | `true` for a unit with zones that takes airside | `false` |
+| `swing` | `false` for a unit without zones that takes no direction | `true` |
+| `coolTemperaturesInC`, `heatTemperaturesInC` | `{ min, max }`, in whole degrees | None reported, so 18 to 32 and 10 to 30 |
+
+A unit with zones takes fan auto, and no `auto` fan speed and no direction.
+It answers HTTP 404 to a path outside `/skyfi`, as an Airbase adapter does,
+so `discoverDevices()` reports it as `airbase` when it is started with
+`answersDiscovery`.
+
+| To | Do |
+| --- | --- |
+| Check what the unit holds | Call `getState()` on a client |
+| Check what your code sent | Read `simulator.requests`: each has `method`, `path`, `query`, `headers` and `body` |
+| Require registration (classic) | Pass `key`: the simulator answers HTTP 403 until `registerTerminal()` is given it |
+| Require the child lock code | Pass `localPassword` |
+| Make the adapter slow | Pass `replyDelayInMs`: it answers one request at a time, so a second request waits for the first |
+| Make the adapter unreachable | `await simulator.stop()` |
+| Reach it from another machine | Pass `address`, an address of this machine other than the default `127.0.0.1` |
+| Have `discoverDevices()` find it | Pass `answersDiscovery: true` |
+
+Start as many discoverable simulators as you like, in one process or several:
+`discoverDevices()` resolves with one device for each, at `127.0.0.1` and the
+simulator's own port.
+
+`discoverDevices()` broadcasts the probe, so it also finds the real adapters
+on the LAN, and it needs a network to broadcast on. Only a program that is
+not a simulator gets in the way: while one holds UDP port 30050, starting a
+simulator with `answersDiscovery` rejects with the socket's error.
+
+For anything the options above do not cover, such as humidity settings or
+fixed louver positions, set the adapter's own fields. A classic simulator
+takes `basicInfo`, `modelInfo`, `controlInfo` and `sensorInfo`, the fields of
+each reply, and holds them under the same names. An Airbase simulator takes
+those four and `zoneSetting`. A DSIOT simulator takes `leaves`, and holds each
+leaf by its address. A field given this way replaces
+what `unit` sets, and `state` and `sensors` replace it in turn. The package
+root exports the adapter's codes as tables, such as `CLASSIC_FAN_SPEED_CODES`
+and `DSIOT_PATHS`.
+
+```ts
+// A classic unit with 3D airflow: both louvers, and five fixed positions.
+const classic = await startClassicSimulator({
+  modelInfo: { en_fdir2: "1", s_fdir_ud: "81", s_fdir_ud_step: "5", s_fdir_lr: "1" },
+  controlInfo: { f_dir_ud: "0", f_dir_lr: "0" },
+});
+classic.setState({ verticalPosition: "position3" });
 
-| Region         | Markets using the DAIKIN Mobile Controller app                 |
-| -------------- | -------------------------------------------------------------- |
-| Southeast Asia | Thailand, Singapore, the Philippines                           |
-| East Asia      | Hong Kong, Taiwan                                              |
-| Oceania        | Australia, New Zealand                                         |
+// A DSIOT unit that takes a humidity setting in cool.
+const dsiot = await startDsiotSimulator({
+  leaves: {
+    "/dsiot/edge/adr_0100.dgc_status.e_1002.e_3001.p_0C": { pv: "00", pt: 2 },
+  },
+});
+dsiot.setState({ targetHumidity: "auto" });
+```
+
+A simulator answers HTTP 501 to a request it has no answer for, so a client
+rejects with a `DaikinError` whose `httpStatusCode` is 501.
+[UNSUPPORTED.md](UNSUPPORTED.md#simulators) lists what a simulator leaves out,
+and each answer that is not known to be a real adapter's.
+[DESIGN.md](DESIGN.md#simulators) says what a simulator shares with the
+clients' codecs, and why no more.
+
+## Coverage & limitations
 
-The app is published by Daikin Thailand and may be available in other countries
-too; if your local Daikin site points you to it, this package should apply. Units
-sold for other apps likely use a different protocol, e.g. Onecta / Daikin Online
-Controller (Europe), GO DAIKIN (Malaysia) or Daikin Comfort Control / Daikin One
-(North America).
+It supports the Wi-Fi adapters of three apps, in the markets where each is
+used, so it is **not valid for every Daikin region or app**.
+
+| App | Markets | Adapters | Client |
+| --- | --- | --- | --- |
+| DAIKIN Mobile Controller | Thailand, Singapore, the Philippines, Hong Kong, Taiwan, Australia, New Zealand | BRP072A42, BRP072C42, BRP069 | `ClassicDaikinClient` |
+| DAIKIN Mobile Controller | The same | BRP084 | `DsiotDaikinClient` |
+| Daikin Airbase | Australia | BRP15B61, on a ducted unit | `AirbaseDaikinClient` |
+| ONECTA, once Daikin Online Controller | Europe | BRP069A and BRP069B series | `ClassicDaikinClient` |
+
+Each app may be available in more countries than the table lists: if your
+local Daikin site points you to one of the three, this package should apply.
+
+Three limits apply, and [UNSUPPORTED.md](UNSUPPORTED.md) says what is not known
+about each:
+
+- **Europe**: power, mode, setpoint, fan, swing and special modes go to a
+  classic adapter there as they do elsewhere. `getCapabilities()` follows the
+  rules of the other markets, and which adapters there speak HTTPS is not
+  known.
+- **A DSIOT adapter in Europe** (BRP069C series) is not covered: it may not
+  answer on the LAN until it is switched on.
+- **An Airbase adapter** is told from a classic one by how it answers over
+  HTTP: no field of its discovery reply is known to differ.
+
+Units sold for other apps likely use a different protocol, e.g. GO DAIKIN
+(Malaysia) or Daikin Comfort Control / Daikin One (North America).
 
 This package is still young, so expect some rough edges. If something doesn't
 work with your unit, please