tesla-fleet-api 0.4.0 → 0.6.0

package/dist/bluetooth/constants.mjs

@@ -0,0 +1,70 @@
+// src/bluetooth/constants.ts
+/** The vehicle's GATT service. It is never advertised, so never scan for it. */
+const SERVICE_UUID = "00000211-b2d1-43f0-9b88-960cebf8b91e";
+/** Client to car. Tesla's Go SDK names the two by the opposite view, hence these names. */
+const VEHICLE_WRITE_UUID = "00000212-b2d1-43f0-9b88-960cebf8b91e";
+/** Car to client. */
+const VEHICLE_NOTIFY_UUID = "00000213-b2d1-43f0-9b88-960cebf8b91e";
+/** Python's name for `VEHICLE_WRITE_UUID`. */
+const WRITE_UUID = VEHICLE_WRITE_UUID;
+/** Python's name for `VEHICLE_NOTIFY_UUID`. */
+const READ_UUID = VEHICLE_NOTIFY_UUID;
+/** The keepalive read target. */
+const VERSION_UUID = "00000214-b2d1-43f0-9b88-960cebf8b91e";
+/** GATT Device Name. */
+const NAME_UUID = "00002a00-0000-1000-8000-00805f9b34fb";
+/** GATT Appearance. */
+const APPEARANCE_UUID = "00002a01-0000-1000-8000-00805f9b34fb";
+/** Generic Access, for a backend that needs a service UUID to reach the two above. */
+const GENERIC_ACCESS_UUID = "00001800-0000-1000-8000-00805f9b34fb";
+/** Largest frame accepted, length prefix included. Tesla's Go SDK allows 2 more bytes. */
+const MAX_FRAME_SIZE = 1024;
+/**
+* Bytes per write when a connection does not say: the ATT default MTU of 23,
+* less 3 of header. Safe on any link, and all Homey offers, as it hides the MTU.
+*/
+const DEFAULT_MAX_WRITE_SIZE = 20;
+/** A chunk after this much silence means the partial frame before it was abandoned. */
+const STALE_CHUNK_TIMEOUT_MS = 1e3;
+/** An idle held link drops at about 42 s on average; a read this often keeps it about 10 times longer. */
+const DEFAULT_KEEPALIVE_INTERVAL_MS = 2e4;
+/** Infotainment answers a handshake 4 to 16 s after an RKE wake. */
+const DEFAULT_WAKE_TIMEOUT_MS = 3e4;
+/**
+* One infotainment readiness probe. A ready infotainment answers in 0.26 to 0.39 s.
+* The window opens once the request is fully written, so a slow 20-byte link
+* spends none of it writing. Raise it with `wake_probe_timeout_ms` if a link's
+* replies are slower than this, as a probe that keeps timing out never proves
+* the car is ready.
+*/
+const DEFAULT_WAKE_PROBE_TIMEOUT_MS = 1e3;
+/** How often a wake is resent while infotainment stays silent: a first wake can be missed after a long sleep. */
+const WAKE_RESEND_INTERVAL_MS = 3e3;
+/** How long an awake car's infotainment may take to finish booting. */
+const INFOTAINMENT_BOOT_TIMEOUT_MS = 2e4;
+/** How long a charge-port opening has to show in charge state. It took about 1.4 s in live trials. */
+const CHARGE_PORT_VERIFY_TIMEOUT_MS = 5e3;
+/** Between charge-state polls, while waiting for readiness or for the latch. */
+const CHARGE_PORT_VERIFY_INTERVAL_MS = 250;
+/** How long `pair` waits for someone to tap a key card. */
+const DEFAULT_PAIR_TIMEOUT_MS = 3e5;
+/** Between `pair`'s checks of whether the key was accepted. */
+const DEFAULT_PAIR_POLL_INTERVAL_MS = 5e3;
+/** Connect attempts. Each is bounded by `DEFAULT_CONNECT_TIMEOUT_MS`. */
+const DEFAULT_CONNECT_ATTEMPTS = 3;
+/** One connect attempt. Python takes the same figure from `bleak-retry-connector`. */
+const DEFAULT_CONNECT_TIMEOUT_MS = 2e4;
+/** One scan. It must outlast the backend's window, which Homey fixes at about 10 s: its adapter sets its own bound. */
+const DEFAULT_SCAN_TIMEOUT_MS = 1e4;
+/** Bound on tearing down a link: the failure behind it is what gets reported. */
+const LINK_TEARDOWN_TIMEOUT_MS = 5e3;
+/**
+* One write call. Not in Python, whose backends bound their own writes. Homey's
+* have no timeout and its link state can be stale, so a hung write must end
+* here. A design choice. BLE-00 step 10 measures how long a failing write takes
+* on Homey, which sets it.
+*/
+const GATT_WRITE_TIMEOUT_MS = 5e3;
+/** One read call, other than a keepalive's. */
+const GATT_READ_TIMEOUT_MS = 5e3;
+export { APPEARANCE_UUID, CHARGE_PORT_VERIFY_INTERVAL_MS, CHARGE_PORT_VERIFY_TIMEOUT_MS, DEFAULT_CONNECT_ATTEMPTS, DEFAULT_CONNECT_TIMEOUT_MS, DEFAULT_KEEPALIVE_INTERVAL_MS, DEFAULT_MAX_WRITE_SIZE, DEFAULT_PAIR_POLL_INTERVAL_MS, DEFAULT_PAIR_TIMEOUT_MS, DEFAULT_SCAN_TIMEOUT_MS, DEFAULT_WAKE_PROBE_TIMEOUT_MS, DEFAULT_WAKE_TIMEOUT_MS, GATT_READ_TIMEOUT_MS, GATT_WRITE_TIMEOUT_MS, GENERIC_ACCESS_UUID, INFOTAINMENT_BOOT_TIMEOUT_MS, LINK_TEARDOWN_TIMEOUT_MS, MAX_FRAME_SIZE, NAME_UUID, READ_UUID, SERVICE_UUID, STALE_CHUNK_TIMEOUT_MS, VEHICLE_NOTIFY_UUID, VEHICLE_WRITE_UUID, VERSION_UUID, WAKE_RESEND_INTERVAL_MS, WRITE_UUID };

package/dist/bluetooth/framing.cjs

@@ -0,0 +1,125 @@
+require("./constants.cjs");
+let _teslemetry_tesla_protocol_command_universal_message = require("@teslemetry/tesla-protocol/command/universal_message");
+let _teslemetry_tesla_protocol_command_vcsec = require("@teslemetry/tesla-protocol/command/vcsec");
+// src/bluetooth/framing.ts
+/** Prefix a payload with its big-endian 2-byte length, which counts the payload only. */
+function prependLength(message) {
+	const header = Buffer.alloc(2);
+	header.writeUInt16BE(message.length);
+	return Buffer.concat([header, message]);
+}
+/**
+* Cut a frame into the writes that carry it.
+* @param maxWriteSize Largest bytes per write. `null` means the backend accepts a full frame, as Python's do.
+*/
+function splitFrame(frame, maxWriteSize) {
+	if (maxWriteSize === null) return [frame];
+	if (!Number.isInteger(maxWriteSize) || maxWriteSize <= 0) throw new RangeError(`maxWriteSize must be a positive integer, got ${maxWriteSize}.`);
+	const chunks = [];
+	for (let start = 0; start < frame.length; start += maxWriteSize) chunks.push(frame.subarray(start, start + maxWriteSize));
+	return chunks;
+}
+/** Whether a decoded `RoutableMessage` holds nothing: ts-proto's shape for "no known field". */
+function hasNoKnownField(message) {
+	return message.toDestination === void 0 && message.fromDestination === void 0 && message.protobufMessageAsBytes === void 0 && message.sessionInfoRequest === void 0 && message.sessionInfo === void 0 && message.signatureData === void 0 && message.signedMessageStatus === void 0 && message.messageFrame === void 0 && message.requestUuid.length === 0 && message.uuid.length === 0 && message.flags === 0;
+}
+/**
+* Parse one reassembled frame, wrapping a bare VCSEC message.
+*
+* On a fresh link the car sends `FromVCSECMessage` frames, such as a repeating
+* `authenticationRequest`, with no `RoutableMessage` around them. None of its
+* field numbers exist on `RoutableMessage`, so one parses as a message with no
+* known field. It is wrapped as an unaddressed VCSEC message, so it reaches the
+* broadcast listeners as a wrapped one would.
+* @throws When the frame is not a `RoutableMessage`.
+*/
+function parseFrame(payload) {
+	const message = _teslemetry_tesla_protocol_command_universal_message.RoutableMessage.decode(payload);
+	if (payload.length === 0 || !hasNoKnownField(message)) return message;
+	let vcsec;
+	try {
+		vcsec = _teslemetry_tesla_protocol_command_vcsec.FromVCSECMessage.decode(payload);
+	} catch {
+		return message;
+	}
+	if (!Object.values(vcsec).some((field) => field !== void 0)) return message;
+	return _teslemetry_tesla_protocol_command_universal_message.RoutableMessage.create({
+		fromDestination: { domain: _teslemetry_tesla_protocol_command_universal_message.Domain.DOMAIN_VEHICLE_SECURITY },
+		protobufMessageAsBytes: payload
+	});
+}
+/**
+* Reassembles BLE notifications into length-prefixed messages.
+*
+* One notification can hold part of a message, one message, or several. A
+* message that cannot be decoded drops the current notification and resyncs at
+* the next one. A partial message is also dropped if its next chunk does not
+* arrive within `STALE_CHUNK_TIMEOUT_MS`.
+*/
+var ReassemblingBuffer = class {
+	callback;
+	buffer = Buffer.alloc(0);
+	expectedLength = null;
+	/** Where each notification still in `buffer` starts: the only places a resync can land. */
+	packetStarts = [];
+	lastChunkAt = null;
+	now;
+	/**
+	* @param callback Called with each parsed message. Its errors are not caught.
+	* @param now The monotonic clock, in milliseconds. Injectable for tests.
+	*/
+	constructor(callback, now = () => performance.now()) {
+		this.callback = callback;
+		this.now = now;
+	}
+	/** Take one notification and emit every message it completes. Malformed bytes never throw. */
+	receive(chunk) {
+		const now = this.now();
+		if (this.buffer.length > 0 && this.lastChunkAt !== null && now - this.lastChunkAt > 1e3) {
+			this.buffer = Buffer.alloc(0);
+			this.expectedLength = null;
+			this.packetStarts = [];
+		}
+		this.lastChunkAt = now;
+		this.packetStarts.push(this.buffer.length);
+		this.buffer = Buffer.concat([this.buffer, chunk]);
+		for (;;) {
+			if (this.expectedLength === null && this.buffer.length >= 2) this.expectedLength = this.buffer.readUInt16BE(0) + 2;
+			if (this.expectedLength === null) return;
+			if (this.expectedLength > 1024) {
+				this.discardPacket();
+				continue;
+			}
+			if (this.buffer.length < this.expectedLength) return;
+			let message;
+			try {
+				message = parseFrame(this.buffer.subarray(2, this.expectedLength));
+			} catch {
+				this.discardPacket();
+				continue;
+			}
+			const consumed = this.expectedLength;
+			this.buffer = this.buffer.subarray(consumed);
+			this.packetStarts = this.packetStarts.filter((start) => start >= consumed).map((start) => start - consumed);
+			this.expectedLength = null;
+			this.callback(message);
+		}
+	}
+	/** Drop the current notification and resync at the next, if there is one. */
+	discardPacket() {
+		this.packetStarts.shift();
+		const next = this.packetStarts[0];
+		if (next === void 0) {
+			this.buffer = Buffer.alloc(0);
+			this.packetStarts = [];
+		} else {
+			this.buffer = this.buffer.subarray(next);
+			this.packetStarts = this.packetStarts.map((start) => start - next);
+		}
+		this.expectedLength = null;
+	}
+};
+exports.ReassemblingBuffer = ReassemblingBuffer;
+exports.parseFrame = parseFrame;
+exports.prependLength = prependLength;
+exports.splitFrame = splitFrame;

package/dist/bluetooth/framing.d.cts

@@ -0,0 +1,45 @@
+import { RoutableMessage } from "@teslemetry/tesla-protocol/command/universal_message";
+/** Prefix a payload with its big-endian 2-byte length, which counts the payload only. */
+export declare function prependLength(message: Uint8Array): Buffer;
+/**
+ * Cut a frame into the writes that carry it.
+ * @param maxWriteSize Largest bytes per write. `null` means the backend accepts a full frame, as Python's do.
+ */
+export declare function splitFrame(frame: Uint8Array, maxWriteSize: number | null): Uint8Array[];
+/**
+ * Parse one reassembled frame, wrapping a bare VCSEC message.
+ *
+ * On a fresh link the car sends `FromVCSECMessage` frames, such as a repeating
+ * `authenticationRequest`, with no `RoutableMessage` around them. None of its
+ * field numbers exist on `RoutableMessage`, so one parses as a message with no
+ * known field. It is wrapped as an unaddressed VCSEC message, so it reaches the
+ * broadcast listeners as a wrapped one would.
+ * @throws When the frame is not a `RoutableMessage`.
+ */
+export declare function parseFrame(payload: Uint8Array): RoutableMessage;
+/**
+ * Reassembles BLE notifications into length-prefixed messages.
+ *
+ * One notification can hold part of a message, one message, or several. A
+ * message that cannot be decoded drops the current notification and resyncs at
+ * the next one. A partial message is also dropped if its next chunk does not
+ * arrive within `STALE_CHUNK_TIMEOUT_MS`.
+ */
+export declare class ReassemblingBuffer {
+  private readonly callback;
+  private buffer;
+  private expectedLength;
+  /** Where each notification still in `buffer` starts: the only places a resync can land. */
+  private packetStarts;
+  private lastChunkAt;
+  private readonly now;
+  /**
+   * @param callback Called with each parsed message. Its errors are not caught.
+   * @param now The monotonic clock, in milliseconds. Injectable for tests.
+   */
+  constructor(callback: (message: RoutableMessage) => void, now?: () => number);
+  /** Take one notification and emit every message it completes. Malformed bytes never throw. */
+  receive(chunk: Uint8Array): void;
+  /** Drop the current notification and resync at the next, if there is one. */
+  private discardPacket;
+}

package/dist/bluetooth/framing.d.mts

@@ -0,0 +1,45 @@
+import { RoutableMessage } from "@teslemetry/tesla-protocol/command/universal_message";
+/** Prefix a payload with its big-endian 2-byte length, which counts the payload only. */
+export declare function prependLength(message: Uint8Array): Buffer;
+/**
+ * Cut a frame into the writes that carry it.
+ * @param maxWriteSize Largest bytes per write. `null` means the backend accepts a full frame, as Python's do.
+ */
+export declare function splitFrame(frame: Uint8Array, maxWriteSize: number | null): Uint8Array[];
+/**
+ * Parse one reassembled frame, wrapping a bare VCSEC message.
+ *
+ * On a fresh link the car sends `FromVCSECMessage` frames, such as a repeating
+ * `authenticationRequest`, with no `RoutableMessage` around them. None of its
+ * field numbers exist on `RoutableMessage`, so one parses as a message with no
+ * known field. It is wrapped as an unaddressed VCSEC message, so it reaches the
+ * broadcast listeners as a wrapped one would.
+ * @throws When the frame is not a `RoutableMessage`.
+ */
+export declare function parseFrame(payload: Uint8Array): RoutableMessage;
+/**
+ * Reassembles BLE notifications into length-prefixed messages.
+ *
+ * One notification can hold part of a message, one message, or several. A
+ * message that cannot be decoded drops the current notification and resyncs at
+ * the next one. A partial message is also dropped if its next chunk does not
+ * arrive within `STALE_CHUNK_TIMEOUT_MS`.
+ */
+export declare class ReassemblingBuffer {
+  private readonly callback;
+  private buffer;
+  private expectedLength;
+  /** Where each notification still in `buffer` starts: the only places a resync can land. */
+  private packetStarts;
+  private lastChunkAt;
+  private readonly now;
+  /**
+   * @param callback Called with each parsed message. Its errors are not caught.
+   * @param now The monotonic clock, in milliseconds. Injectable for tests.
+   */
+  constructor(callback: (message: RoutableMessage) => void, now?: () => number);
+  /** Take one notification and emit every message it completes. Malformed bytes never throw. */
+  receive(chunk: Uint8Array): void;
+  /** Drop the current notification and resync at the next, if there is one. */
+  private discardPacket;
+}

package/dist/bluetooth/framing.mjs

@@ -0,0 +1,122 @@
+import "./constants.mjs";
+import { Domain, RoutableMessage } from "@teslemetry/tesla-protocol/command/universal_message";
+import { FromVCSECMessage } from "@teslemetry/tesla-protocol/command/vcsec";
+// src/bluetooth/framing.ts
+/** Prefix a payload with its big-endian 2-byte length, which counts the payload only. */
+function prependLength(message) {
+	const header = Buffer.alloc(2);
+	header.writeUInt16BE(message.length);
+	return Buffer.concat([header, message]);
+}
+/**
+* Cut a frame into the writes that carry it.
+* @param maxWriteSize Largest bytes per write. `null` means the backend accepts a full frame, as Python's do.
+*/
+function splitFrame(frame, maxWriteSize) {
+	if (maxWriteSize === null) return [frame];
+	if (!Number.isInteger(maxWriteSize) || maxWriteSize <= 0) throw new RangeError(`maxWriteSize must be a positive integer, got ${maxWriteSize}.`);
+	const chunks = [];
+	for (let start = 0; start < frame.length; start += maxWriteSize) chunks.push(frame.subarray(start, start + maxWriteSize));
+	return chunks;
+}
+/** Whether a decoded `RoutableMessage` holds nothing: ts-proto's shape for "no known field". */
+function hasNoKnownField(message) {
+	return message.toDestination === void 0 && message.fromDestination === void 0 && message.protobufMessageAsBytes === void 0 && message.sessionInfoRequest === void 0 && message.sessionInfo === void 0 && message.signatureData === void 0 && message.signedMessageStatus === void 0 && message.messageFrame === void 0 && message.requestUuid.length === 0 && message.uuid.length === 0 && message.flags === 0;
+}
+/**
+* Parse one reassembled frame, wrapping a bare VCSEC message.
+*
+* On a fresh link the car sends `FromVCSECMessage` frames, such as a repeating
+* `authenticationRequest`, with no `RoutableMessage` around them. None of its
+* field numbers exist on `RoutableMessage`, so one parses as a message with no
+* known field. It is wrapped as an unaddressed VCSEC message, so it reaches the
+* broadcast listeners as a wrapped one would.
+* @throws When the frame is not a `RoutableMessage`.
+*/
+function parseFrame(payload) {
+	const message = RoutableMessage.decode(payload);
+	if (payload.length === 0 || !hasNoKnownField(message)) return message;
+	let vcsec;
+	try {
+		vcsec = FromVCSECMessage.decode(payload);
+	} catch {
+		return message;
+	}
+	if (!Object.values(vcsec).some((field) => field !== void 0)) return message;
+	return RoutableMessage.create({
+		fromDestination: { domain: Domain.DOMAIN_VEHICLE_SECURITY },
+		protobufMessageAsBytes: payload
+	});
+}
+/**
+* Reassembles BLE notifications into length-prefixed messages.
+*
+* One notification can hold part of a message, one message, or several. A
+* message that cannot be decoded drops the current notification and resyncs at
+* the next one. A partial message is also dropped if its next chunk does not
+* arrive within `STALE_CHUNK_TIMEOUT_MS`.
+*/
+var ReassemblingBuffer = class {
+	callback;
+	buffer = Buffer.alloc(0);
+	expectedLength = null;
+	/** Where each notification still in `buffer` starts: the only places a resync can land. */
+	packetStarts = [];
+	lastChunkAt = null;
+	now;
+	/**
+	* @param callback Called with each parsed message. Its errors are not caught.
+	* @param now The monotonic clock, in milliseconds. Injectable for tests.
+	*/
+	constructor(callback, now = () => performance.now()) {
+		this.callback = callback;
+		this.now = now;
+	}
+	/** Take one notification and emit every message it completes. Malformed bytes never throw. */
+	receive(chunk) {
+		const now = this.now();
+		if (this.buffer.length > 0 && this.lastChunkAt !== null && now - this.lastChunkAt > 1e3) {
+			this.buffer = Buffer.alloc(0);
+			this.expectedLength = null;
+			this.packetStarts = [];
+		}
+		this.lastChunkAt = now;
+		this.packetStarts.push(this.buffer.length);
+		this.buffer = Buffer.concat([this.buffer, chunk]);
+		for (;;) {
+			if (this.expectedLength === null && this.buffer.length >= 2) this.expectedLength = this.buffer.readUInt16BE(0) + 2;
+			if (this.expectedLength === null) return;
+			if (this.expectedLength > 1024) {
+				this.discardPacket();
+				continue;
+			}
+			if (this.buffer.length < this.expectedLength) return;
+			let message;
+			try {
+				message = parseFrame(this.buffer.subarray(2, this.expectedLength));
+			} catch {
+				this.discardPacket();
+				continue;
+			}
+			const consumed = this.expectedLength;
+			this.buffer = this.buffer.subarray(consumed);
+			this.packetStarts = this.packetStarts.filter((start) => start >= consumed).map((start) => start - consumed);
+			this.expectedLength = null;
+			this.callback(message);
+		}
+	}
+	/** Drop the current notification and resync at the next, if there is one. */
+	discardPacket() {
+		this.packetStarts.shift();
+		const next = this.packetStarts[0];
+		if (next === void 0) {
+			this.buffer = Buffer.alloc(0);
+			this.packetStarts = [];
+		} else {
+			this.buffer = this.buffer.subarray(next);
+			this.packetStarts = this.packetStarts.map((start) => start - next);
+		}
+		this.expectedLength = null;
+	}
+};
+export { ReassemblingBuffer, parseFrame, prependLength, splitFrame };

package/dist/bluetooth/homey.cjs

@@ -0,0 +1,165 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_async = require("./async.cjs");
+const require_constants = require("./constants.cjs");
+const require_transport = require("./transport.cjs");
+const require_shared = require("./adapters/shared.cjs");
+// src/bluetooth/adapters/homey.ts
+/**
+* Bytes per write: `null`, a whole frame in one write. Homey hides the MTU.
+* BLE-00 (HW-0, 2026-11-03) measured a 114-byte frame in one write at 232 ms to
+* a reply, against 562 ms for 6 writes of 20 bytes. Only 114 bytes were tried:
+* a signed frame (about 200 bytes) is confirmed by HW-5. Pass `maxWriteSize: 20`
+* to `HomeyBleTransport` to chunk at the ATT minimum if that run shows a failure.
+*/
+const HOMEY_MAX_WRITE_SIZE = null;
+/**
+* Bound on one scan. `discover()` takes a fixed 10.04 s when it is not cached
+* (HW-0), so the library's 10 s default would time out about 40 ms early.
+* `VehicleBluetooth` uses this when `scan_timeout_ms` is not set.
+*/
+const HOMEY_SCAN_TIMEOUT_MS = 15e3;
+/**
+* For `connect_timeout_ms` and `max_connect_attempts`, not applied by this
+* adapter: `discover()` caches for 30 s, so a fast retry sees old data, and
+* these fit Homey's 9 s action window. BLE-00 step 11 sets both, against its
+* target of a connect under 4 s in 9 of 10. A flow with no such window should
+* keep the library's defaults until then, as a link slower than this never lands.
+*/
+const HOMEY_VEHICLE_OPTIONS = {
+	connect_timeout_ms: 4e3,
+	max_connect_attempts: 1
+};
+/**
+* Bound on discovery and subscribing once a link is up. Homey has no timeout of
+* its own, and if these hang, nothing else could release the vehicle's slot.
+* BLE-00 steps 3 and 4 show what a slow link takes.
+*/
+const HOMEY_SETUP_TIMEOUT_MS = require_constants.DEFAULT_CONNECT_TIMEOUT_MS;
+/** Bound on unsubscribing, which must not keep `disconnect` from running on a dead link. BLE-00 step 10. */
+const HOMEY_UNSUBSCRIBE_TIMEOUT_MS = 1e3;
+function find(characteristics, uuid) {
+	return characteristics.find((characteristic) => require_shared.compactUuid(characteristic.uuid) === require_shared.compactUuid(uuid));
+}
+var HomeyConnection = class {
+	id;
+	handlers;
+	maxWriteSize;
+	claims;
+	lost = false;
+	closed = false;
+	closing;
+	peripheral;
+	characteristics = [];
+	genericAccess;
+	subscribed = false;
+	onDisconnect = () => {
+		this.lost = true;
+		if (!this.closed) this.handlers.onDisconnect();
+	};
+	constructor(id, handlers, maxWriteSize, claims) {
+		this.id = id;
+		this.handlers = handlers;
+		this.maxWriteSize = maxWriteSize;
+		this.claims = claims;
+	}
+	/** Stale after a silent drop. The library's timeouts are what find a dead link. */
+	get isConnected() {
+		return !this.lost && !this.closed && this.peripheral?.isConnected === true;
+	}
+	/** Discover, then subscribe: the link is live only once this resolves. */
+	async attach(peripheral) {
+		this.peripheral = peripheral;
+		this.assertCurrent();
+		peripheral.once("disconnect", this.onDisconnect);
+		const characteristics = await (await peripheral.getService(require_shared.compactUuid(require_constants.SERVICE_UUID))).discoverCharacteristics();
+		const notify = find(characteristics, require_constants.VEHICLE_NOTIFY_UUID);
+		if (!notify || !find(characteristics, "00000212-b2d1-43f0-9b88-960cebf8b91e")) throw new Error("The vehicle's write or notify characteristic was not found.");
+		this.assertCurrent();
+		this.characteristics = characteristics;
+		await notify.subscribeToNotifications((data) => this.handlers.onNotify(data));
+		this.subscribed = true;
+	}
+	/**
+	* Homey hands every attempt the same link, and one subscription per
+	* characteristic. A superseded attempt stops here, before it changes either.
+	*/
+	assertCurrent() {
+		if (this.claims.superseded(this.id, this)) throw new Error("A newer connect attempt took over this link.");
+	}
+	async write(data) {
+		const characteristic = find(this.characteristics, require_constants.VEHICLE_WRITE_UUID);
+		if (!characteristic) throw new require_transport.BleNotSubmittedError("The vehicle write characteristic was not found.");
+		if (!this.isConnected) throw new require_transport.BleNotSubmittedError("The link is down.");
+		await characteristic.write(Buffer.from(data));
+	}
+	async read(characteristic) {
+		const target = characteristic === "version" ? find(this.characteristics, require_constants.VERSION_UUID) : find(await this.discoverGenericAccess(), characteristic === "deviceName" ? require_constants.NAME_UUID : require_constants.APPEARANCE_UUID);
+		if (!target) throw new require_transport.BleNotSubmittedError(`The ${characteristic} characteristic was not found.`);
+		return target.read();
+	}
+	/**
+	* Homey's stack may hide this service, which BLE-00 step 8 settles. A failed
+	* lookup leaves a characteristic unresolved on a healthy link, so it must not
+	* read as a lost one.
+	*/
+	discoverGenericAccess() {
+		const { peripheral } = this;
+		if (!peripheral) return Promise.reject(new require_transport.BleNotSubmittedError("The link is down."));
+		this.genericAccess ??= peripheral.getService(require_shared.compactUuid(require_constants.GENERIC_ACCESS_UUID)).then((service) => service.discoverCharacteristics()).catch((cause) => {
+			this.genericAccess = void 0;
+			throw new require_transport.BleNotSubmittedError("Generic Access could not be resolved.", { cause });
+		});
+		return this.genericAccess;
+	}
+	disconnect() {
+		this.closing ??= (async () => {
+			this.closed = true;
+			const { peripheral, claims, id } = this;
+			peripheral?.removeListener("disconnect", this.onDisconnect);
+			const superseded = claims.superseded(id, this);
+			claims.release(id, this);
+			if (superseded || !peripheral) return;
+			if (this.subscribed) await require_shared.quietly(() => require_async.withTimeout(() => find(this.characteristics, require_constants.VEHICLE_NOTIFY_UUID).unsubscribeFromNotifications(), HOMEY_UNSUBSCRIBE_TIMEOUT_MS));
+			await require_shared.quietly(() => peripheral.disconnect());
+		})();
+		return this.closing;
+	}
+};
+var HomeyBleTransport = class {
+	ble;
+	maxWriteSize;
+	claims = new require_shared.LinkClaims();
+	scanTimeoutMs = HOMEY_SCAN_TIMEOUT_MS;
+	/** @param ble `this.homey.ble`. The app needs the `homey:wireless:ble` permission. */
+	constructor(ble, options = {}) {
+		this.ble = ble;
+		this.maxWriteSize = options.maxWriteSize === void 0 ? null : options.maxWriteSize;
+	}
+	/** Takes Homey's fixed window, whatever `timeoutMs` says. Never pass `discover` a filter. */
+	async scan({ matches }) {
+		return (await this.ble.discover()).filter((advertisement) => !matches || advertisement.localName !== void 0 && matches(advertisement.localName)).map((advertisement) => ({
+			id: advertisement.uuid,
+			name: advertisement.localName,
+			rssi: advertisement.rssi,
+			connectable: advertisement.connectable
+		}));
+	}
+	async connect(device, handlers) {
+		const connection = new HomeyConnection(device.id, handlers, this.maxWriteSize, this.claims);
+		this.claims.claim(device.id, connection);
+		try {
+			const peripheral = await (await this.ble.find(device.id)).connect();
+			await require_async.withTimeout(() => connection.attach(peripheral), HOMEY_SETUP_TIMEOUT_MS);
+		} catch (error) {
+			await connection.disconnect();
+			throw error;
+		}
+		return connection;
+	}
+};
+exports.HOMEY_MAX_WRITE_SIZE = HOMEY_MAX_WRITE_SIZE;
+exports.HOMEY_SCAN_TIMEOUT_MS = HOMEY_SCAN_TIMEOUT_MS;
+exports.HOMEY_SETUP_TIMEOUT_MS = HOMEY_SETUP_TIMEOUT_MS;
+exports.HOMEY_UNSUBSCRIBE_TIMEOUT_MS = HOMEY_UNSUBSCRIBE_TIMEOUT_MS;
+exports.HOMEY_VEHICLE_OPTIONS = HOMEY_VEHICLE_OPTIONS;
+exports.HomeyBleTransport = HomeyBleTransport;

package/dist/bluetooth/homey.d.cts

@@ -0,0 +1,84 @@
+import { BleConnection, BleDeviceRef, BleLinkHandlers, BleScanOptions, BleTransport } from "./transport.cjs";
+/**
+ * Bytes per write: `null`, a whole frame in one write. Homey hides the MTU.
+ * BLE-00 (HW-0, 2026-11-03) measured a 114-byte frame in one write at 232 ms to
+ * a reply, against 562 ms for 6 writes of 20 bytes. Only 114 bytes were tried:
+ * a signed frame (about 200 bytes) is confirmed by HW-5. Pass `maxWriteSize: 20`
+ * to `HomeyBleTransport` to chunk at the ATT minimum if that run shows a failure.
+ */
+export declare const HOMEY_MAX_WRITE_SIZE: null;
+/**
+ * Bound on one scan. `discover()` takes a fixed 10.04 s when it is not cached
+ * (HW-0), so the library's 10 s default would time out about 40 ms early.
+ * `VehicleBluetooth` uses this when `scan_timeout_ms` is not set.
+ */
+export declare const HOMEY_SCAN_TIMEOUT_MS = 15000;
+/**
+ * For `connect_timeout_ms` and `max_connect_attempts`, not applied by this
+ * adapter: `discover()` caches for 30 s, so a fast retry sees old data, and
+ * these fit Homey's 9 s action window. BLE-00 step 11 sets both, against its
+ * target of a connect under 4 s in 9 of 10. A flow with no such window should
+ * keep the library's defaults until then, as a link slower than this never lands.
+ */
+export declare const HOMEY_VEHICLE_OPTIONS: {
+  readonly connect_timeout_ms: 4000;
+  readonly max_connect_attempts: 1;
+};
+/**
+ * Bound on discovery and subscribing once a link is up. Homey has no timeout of
+ * its own, and if these hang, nothing else could release the vehicle's slot.
+ * BLE-00 steps 3 and 4 show what a slow link takes.
+ */
+export declare const HOMEY_SETUP_TIMEOUT_MS = 20000;
+/** Bound on unsubscribing, which must not keep `disconnect` from running on a dead link. BLE-00 step 10. */
+export declare const HOMEY_UNSUBSCRIBE_TIMEOUT_MS = 1000;
+export interface HomeyCharacteristicLike {
+  uuid: string;
+  read(): Promise<Buffer>;
+  /** Always a write with response: the only kind Homey offers. */
+  write(data: Buffer): Promise<unknown>;
+  subscribeToNotifications(callback: (data: Buffer) => void): Promise<void>;
+  unsubscribeFromNotifications(): Promise<void>;
+}
+export interface HomeyServiceLike {
+  discoverCharacteristics(): Promise<HomeyCharacteristicLike[]>;
+}
+export interface HomeyPeripheralLike {
+  /** Can stay true after a silent drop, so it is only ever a faster signal. BLE-00 step 9 measures it. */
+  readonly isConnected: boolean;
+  getService(uuid: string): Promise<HomeyServiceLike>;
+  disconnect(): Promise<void>;
+  /** Not guaranteed on every drop, but if it fires, the link is gone. BLE-00 step 9 measures it. */
+  once(event: "disconnect", listener: () => void): unknown;
+  removeListener(event: "disconnect", listener: () => void): unknown;
+}
+export interface HomeyAdvertisementLike {
+  uuid: string;
+  /** Typed as a string, but Homey's guide says it is optional. BLE-00 step 2 measures how often it is there. */
+  localName?: string;
+  rssi?: number;
+  connectable?: boolean;
+  /** If already connected, returns the existing connection. It has no timeout: the library bounds it. */
+  connect(): Promise<HomeyPeripheralLike>;
+}
+/** What this adapter needs of `this.homey.ble`. */
+export interface HomeyBleManagerLike {
+  /** About 10 s, fixed, when not cached (BLE-00 HW-0). Called with no filter, because the vehicle advertises no service. */
+  discover(): Promise<HomeyAdvertisementLike[]>;
+  find(uuid: string): Promise<HomeyAdvertisementLike>;
+}
+export interface HomeyBleTransportOptions {
+  /** Bytes per write, or `null` for a whole frame in one write. Defaults to `HOMEY_MAX_WRITE_SIZE`. */
+  maxWriteSize?: number | null;
+}
+export declare class HomeyBleTransport implements BleTransport {
+  private readonly ble;
+  private readonly maxWriteSize;
+  private readonly claims;
+  readonly scanTimeoutMs = 15000;
+  /** @param ble `this.homey.ble`. The app needs the `homey:wireless:ble` permission. */
+  constructor(ble: HomeyBleManagerLike, options?: HomeyBleTransportOptions);
+  /** Takes Homey's fixed window, whatever `timeoutMs` says. Never pass `discover` a filter. */
+  scan({ matches }: BleScanOptions): Promise<BleDeviceRef[]>;
+  connect(device: BleDeviceRef, handlers: BleLinkHandlers): Promise<BleConnection>;
+}