@mega-yfue/eufy-sdk 0.2.0-beta.2 → 0.2.0-beta.21

package/dist/transport/mqtt/solix-mqtt.d.ts

@@ -0,0 +1,321 @@
+/**
+ * Live telemetry for Anker Solix devices over the AWS-IoT MQTT plane.
+ *
+ * The transport is the shared `SecureMqtt` — the exact same anker AWS-IoT broker + per-user
+ * client-cert mutual TLS the eufy device path uses; a Solix account's `get_user_mqtt_info` result maps
+ * straight onto {@link SecureMqttCredentials}. Solix devices publish telemetry continuously on
+ * `dt/{app_name}/{product_code}/{device_sn}/param_info` as an **ff09 TLV frame** (the same framing
+ * family as {@link parseFf09SettingsResponse}), so this module only adds the Solix topic + a small
+ * ff09 param decoder on top of the reused transport.
+ *
+ * Frame layout (observed on a Smart Meter Gen 2 / AE1X0):
+ *   ff09 | len(u16 LE, incl. trailing XOR checksum) | 5-byte header | TLV fields | xor
+ * each TLV field is `tag(1) | len(1) | value(len)`; measurement fields carry `type(1) | 4 bytes`,
+ * type `0x05` = float32 LE. Field `a2` is the device serial (ASCII after a leading type byte).
+ */
+import { EventEmitter } from "node:events";
+import { type SecureMqttCredentials } from "./secure-mqtt.js";
+import { type Logger } from "../../core/index.js";
+/** A decoded telemetry channel: the raw value plus float/uint interpretations of a 4-byte payload. */
+export interface SolixChannel {
+    /** The leading type byte (`0x05` = float32 LE for the meter's measurement channels). */
+    type: number;
+    raw: Buffer;
+    /** Present when the payload is 4 bytes: little-endian float32. */
+    float?: number;
+    /** Present when the payload is 4 bytes: little-endian uint32. */
+    uint?: number;
+}
+/** A parsed ff09 param frame: the device serial (from `a2`) + the raw TLV field map keyed by tag. */
+export interface SolixParamFrame {
+    deviceSn?: string;
+    /** tag byte → value bytes (still including the per-field leading type byte for measurement fields). */
+    fields: Map<number, Buffer>;
+}
+/**
+ * Telemetry field tags for the Smart Meter (AE1X0) that we emit under a stable NAME, keyed by ff09 tag
+ * byte. These twelve are the meter fields the vendor app itself names, and their tag→name bindings are
+ * confirmed:
+ *
+ * - The app's field vocabulary is exactly these twelve — voltage, current and power per line
+ *   (L1/L2/L3), a power total, and cumulative import/export energy — with no current total, no
+ *   frequency and no power-factor field.
+ * - A live single-phase frame confirms the tag→field magnitudes: `0xac` a nominal mains voltage,
+ *   `0xa8` == `0xab` an equal power pair (line power equals total on one phase, one of them going
+ *   negative on export), `0xaf` the line current, `0xb3` a slowly-cumulative import counter; the L2/L3
+ *   slots read 0 on a single-CT install.
+ *
+ * The frame carries sixteen float slots (`0xa8`..`0xb7`). The four that name no field — `0xb2`, `0xb5`,
+ * `0xb6`, `0xb7` — stay raw `channel_<hex tag>` (see {@link solixReadings}). `0xb2` in particular is NOT
+ * a current total: under a 1.371 A line current it reads 0.009, three orders of magnitude off. Both
+ * `0xb2` and `0xb7` read zero at idle and non-zero under load, so they carry *something* load-related;
+ * what, is not established.
+ *
+ * This table is **meter-family-specific**: the same tag carries a different quantity on another Solix
+ * device (a Solarbank's `0xac` reads a power value, not a voltage), so {@link solixReadings} applies
+ * these names ONLY to a frame from the meter family — see {@link SOLIX_METER_PRODUCT_PREFIXES}. Every
+ * measurement tag still surfaces as `channel_<hex tag>` regardless of device, so nothing on the wire is
+ * lost; the model layer names non-meter tags per capability.
+ */
+export declare const SOLIX_METER_FIELD_NAMES: Readonly<Record<number, string>>;
+/**
+ * Product-code prefixes of the Smart Meter family that {@link SOLIX_METER_FIELD_NAMES} decodes. The table
+ * is meter-specific, so {@link solixReadings} applies its named fields ONLY to a frame whose product code
+ * starts with one of these; a Solarbank (`AE103`) reporting the same `0xac` tag would otherwise be
+ * mislabelled `meterVoltageL1` with a nonsensical (negative-power) value. These are product-code prefixes
+ * used to select a decode table — not a model import — so the `transport ⊥ model` rule is untouched.
+ *
+ * Keep this in lockstep with `SOLIX_METER_MODELS` in `model/capabilities/solix.ts` (the same meter
+ * prefixes, model-side): a prefix added there but not here grants `energyMeter` to a device whose frames
+ * this decoder then refuses to name, and no guard can catch the split (the model layer can't import
+ * transport). Add a meter prefix to both.
+ */
+export declare const SOLIX_METER_PRODUCT_PREFIXES: readonly string[];
+/**
+ * Product-code prefix of the gen-4 Solarbank (the `ats_ax170` family, e.g. `AE103` Solarbank 4 E5000
+ * Pro) whose ff09 tag layout {@link SOLIX_SOLARBANK_FIELD_NAMES} + the SOC/temperature extraction
+ * describe. Like the meter table this is family-specific — the SAME tag carries a different quantity on
+ * the meter (`0xac` is line voltage there, battery power here), so the Solarbank names are applied ONLY
+ * to a frame from this family. A product-code prefix used to pick a decode table, not a model import.
+ * `AE10` covers the AE10x gen-4 Solarbanks and does NOT match the meter (`AE1X0`, whose 4th char is `X`).
+ */
+export declare const SOLIX_SOLARBANK_PRODUCT_PREFIX = "AE10";
+/**
+ * Confirmed ff09 tag → field bindings for the gen-4 Solarbank (`ats_ax170`), correlated live against the
+ * app UI. Power values in watts; signed fields note their sign convention:
+ * - `0xac` battery power, SIGNED (+ charging / − discharging) — the measured net pack power.
+ * - `0xbc` charge power (0 unless charging); `0xad` discharge power (0 unless discharging).
+ * - `0xae` AC plug power, SIGNED (+ feeding the home / − drawing in to charge).
+ * - `0xaf` socket power — the unit's own on-board AC outlet (an appliance plugged into the Solarbank).
+ * - `0xc4` grid input power; `0xc5` home load power.
+ * SOC and temperature are NOT float channels — see {@link solixReadings}, which reads SOC from tag `0xa3`
+ * (a uint8) and temperature from the `0xa4` BMS status blob. The 4 PV-string channels (`0xc6`–`0xc9`),
+ * the AC currents (`0xb2`/`0xb3`) and export energy (`0xb4`) are not yet confirmed, so they stay raw
+ * `channel_<hex>` until a capture pins them.
+ */
+export declare const SOLIX_SOLARBANK_FIELD_NAMES: Readonly<Record<number, string>>;
+/**
+ * Confirmed `state_info` tag → field bindings for the gen-4 Solarbank. `state_info` is a SEPARATE push
+ * topic from `param_info` and, though it shares the ff09 framing, its tags carry SETTINGS/targets, NOT
+ * live measurements — so the SAME tag byte means something different here than in
+ * {@link SOLIX_SOLARBANK_FIELD_NAMES} (e.g. `0xab` is live PV power in param_info, the mode's AC-socket
+ * export limit here). Mapped by live observation against the app's SOC-setting screen; everything else
+ * stays raw `state_<hex>` until confirmed the same way.
+ */
+export declare const SOLIX_STATE_FIELD_NAMES: Readonly<Record<number, string>>;
+/**
+ * Decode a `state_info` ff09 frame to named + raw settings values. Skips the header tags (`< 0xa5`:
+ * request marker, serial, timestamps). Each settings tag is emitted under `state_<hex>` (a plain number
+ * so it's watchable in a consumer while more tags get mapped) AND, when confirmed, under its name from
+ * {@link SOLIX_STATE_FIELD_NAMES}. Value is read type-aware: `0x05` float32, `0x02` u16, `0x01` u8, and
+ * `0x03` the whole-number settings byte (`payload[1]`).
+ *
+ * The header cutoff is `0xa5` here, deliberately one lower than {@link solixReadings}' `0xa6` for
+ * `param_info`: the two frames are different layouts under the same ff09 framing — `state_info` carries
+ * a settings value at `0xa5` (SOC), where `param_info` has a header tag. The cutoffs are not meant to
+ * match; the spec pins `0xa5`'s treatment in each so they can't silently drift together.
+ */
+export declare function solixStateReadings(frame: SolixParamFrame): Record<string, number>;
+/** Interpret one TLV value as a telemetry channel (leading type byte + payload). */
+export declare function readSolixChannel(value: Buffer | undefined): SolixChannel | undefined;
+/**
+ * Decode an ff09 Solix param frame into its serial + TLV field map. Returns `null` for a non-ff09
+ * buffer, a length field that doesn't fit, or a bad checksum. Validates the trailing XOR checksum first
+ * (so a corrupted frame is rejected rather than yielding plausible floats), then walks `tag|len|value`
+ * from the first `0xa1` tag to the declared length minus the checksum byte via the shared
+ * `walkFf09Tlv` (bounded by `end`, so a field length can't overrun into the checksum).
+ */
+export declare function decodeSolixParamFrame(buf: Buffer): SolixParamFrame | null;
+/**
+ * Reduce a param frame to named + raw telemetry values. Tags below `0xa6` are skipped — `a1`/`a2`/`a3`
+ * carry the field count, the serial and the status, not measurements. A measurement channel is one whose
+ * leading type byte is `0x05` (float32 LE over a 4-byte payload); any other type is a non-measurement
+ * param and contributes nothing. Each measurement is emitted under `channel_<hex tag>`, and additionally
+ * under its name when the tag has a confirmed one AND `productCode` is from a known family — pass the
+ * telemetry topic's product code so a device outside the meter/Solarbank families keeps raw
+ * `channel_<hex>` rather than borrowing another family's tag→name table. `productCode` is required (it
+ * comes straight from the telemetry topic); pass `""` for a frame of unknown origin and no names apply.
+ * Meter family: {@link SOLIX_METER_PRODUCT_PREFIXES}; Solarbank: {@link SOLIX_SOLARBANK_PRODUCT_PREFIX}.
+ */
+export declare function solixReadings(frame: SolixParamFrame, productCode: string): Record<string, number>;
+/** A live telemetry sample emitted by {@link SolixMqtt} as a `reading` event. */
+export interface SolixReading {
+    deviceSn: string;
+    productCode: string;
+    topic: string;
+    frame: SolixParamFrame;
+    values: Record<string, number>;
+}
+/** The minimum device shape {@link SolixMqtt.watch} needs (as returned by `SolixClient.getDevices`). */
+export interface SolixMqttDevice {
+    device_sn: string;
+    product_code: string;
+}
+/** Options for {@link SolixMqtt}. */
+export interface SolixMqttOptions {
+    /** `get_user_mqtt_info` result — carries endpoint, cert/key, app_name, thing_name, user_id. */
+    mqttInfo: SecureMqttCredentials;
+    /** Override the MQTT clientId. Defaults to the cert CN (`thing_name`), distinct from the app's id. */
+    clientId?: string;
+    /**
+     * Account/user id (40-hex) for the arming `account_id` + heartbeat topic. Defaults to
+     * `mqttInfo.user_id`; set it if the credentials omit it.
+     */
+    userId?: string;
+    /**
+     * How often (ms) to re-send the device-info arming request that keeps realtime telemetry flowing.
+     * The device stops pushing `param_info` when no client keeps requesting it (the app re-arms on every
+     * foreground resume + a periodic heartbeat), so a passive subscriber goes silent after the server's
+     * reporting window closes. Default 25s — inside the observed ~30s cadence with keepalive 60. Set `0`
+     * to disable arming (subscribe-only, the old behaviour).
+     */
+    armIntervalMs?: number;
+    /**
+     * The `head.client_id` stamped into the command/heartbeat envelopes — the app-shaped
+     * `android-{app_name}-{user_id}-{mqttUuid}-{ts}` (see {@link buildAppShapedClientId}). Defaults to
+     * that shape built from {@link mqttUuid}. Pass this to pin the whole string.
+     */
+    appClientId?: string;
+    /**
+     * Stable 16-hex install UUID for the app-shaped client id. Defaults to one derived deterministically
+     * from the user id ({@link mqttUuidFrom}) — no storage needed, so the broker sees one stable client
+     * across restarts.
+     *
+     * The trade this makes: the default seed is the **account** id, which every client on that account
+     * shares, so two clients on one account derive the same uuid → the same `client_id`, and the broker
+     * evicts one to admit the other (they take the channel from each other indefinitely). Restart
+     * stability is the common case and this is the deliberate default, but pass an explicit `mqttUuid`
+     * (per host/install) when more than one client runs on the same account, to be told apart.
+     */
+    mqttUuid?: string;
+    /** The account's `site_id` for the `power_site` heartbeat. Omitted from the frame when unknown. */
+    siteId?: string;
+    logger?: Logger;
+}
+/**
+ * Subscribe to a Solix device's live telemetry and emit decoded `reading` events. Reuses
+ * `SecureMqtt` for the connection; adds only the Solix data topic + ff09 param decoding.
+ *
+ *   const mqtt = new SolixMqtt({ mqttInfo: await solix.getUserMqttInfo() });
+ *   mqtt.on("reading", (r) => console.log(r.deviceSn, r.values.meterVoltageL1));
+ *   await mqtt.watch(device);   // device = a SolixClient.getDevices() entry
+ */
+export declare class SolixMqtt extends EventEmitter {
+    private readonly transport;
+    private readonly appName;
+    private readonly userId?;
+    private readonly appClientId;
+    private readonly armIntervalMs;
+    private readonly logger?;
+    private readonly siteId?;
+    private readonly watched;
+    private seq;
+    private armTimer?;
+    /**
+     * Bind to one account's MQTT plane. The envelope `client_id` takes the app's shape
+     * (`android-{app}-{uid}-{mqttUuid}-{ts}`); its `mqttUuid` half must be stable across restarts, or every
+     * restart presents itself to the broker as a new client, so it defaults deterministically from the user
+     * id (see {@link SolixMqttOptions.mqttUuid}) rather than a fresh random per instance.
+     */
+    constructor(opts: SolixMqttOptions);
+    /**
+     * Connect, subscribe to the device's telemetry (+ command-reply) topics, ARM realtime reporting, and
+     * start the re-arm/heartbeat timer so telemetry keeps flowing without the app. Idempotent per device.
+     *
+     * Subscribes to `param_info` (+ the device/account command-reply channels) AND the device's `…/req`
+     * channel. `…/req` is the app→device request side — the broker copies the APP's own publishes there to
+     * any co-subscriber, so watching it lets us read a control the app changed that the telemetry does NOT
+     * reflect: the Solarbank's ambient light and display timeout ride an `…/req` cmd-17 (`0x68`) command
+     * (tags `a4`/`a5`), and the `param_info` `ba` bit only tracks OUR `set_device_attrs` write, never the
+     * app's separate command path. `onMessage` filters these — our own arming/echoes carry no
+     * `a4`/`a5` — and turns an app command into a `reading` with the app-set state. A `…/req` grant denial
+     * is non-fatal (only `param_info` is required); we just won't see app-side changes.
+     *
+     * Throws when `param_info` was not granted. A scope-denied filter comes back as SUBACK_FAILURE rather
+     * than an error (see `SecureMqtt.subscribe`), so an unusable subscription otherwise looks like
+     * success: the call would resolve and arm on every interval while no reading ever arrives.
+     *
+     * The re-arm timer is unreffed, so a caller that watches and returns can still exit.
+     */
+    watch(device: SolixMqttDevice): Promise<void>;
+    /** Tear down the connection and stop the re-arm timer. */
+    close(): Promise<void>;
+    /**
+     * Set a Solarbank's display screen-off timeout — publishes the captured cmd-17 command (ff09 msgtype
+     * `0x68`, tag `a5 = [01, index]`) on the device's `…/req` channel via the same envelope the arming
+     * poll uses (`sign_code:1`, no per-message signature — which the device accepts for cmd 17). `index`
+     * is the 1-based dropdown position (10s=1, 20s=2, 30s=3, 1m=4, 5m=5, 30m=6); "Never" is a separate
+     * command not handled here. Fire-and-forget: the device does not ack on a subscribed channel.
+     */
+    setDisplayTimeout(device: SolixMqttDevice, index: number): Promise<void>;
+    /**
+     * Re-arm every watched device and send the site heartbeat. The device only pushes `param_info` while
+     * a client keeps requesting it — this replays the app's `requestDeviceInfo` (cmd 17) + `power_site`
+     * heartbeat (cmd 10); the request frames are reproduced byte-for-byte by {@link buildFf09Request}
+     * (checksum-verified against captured frames in its spec). Best-effort: a publish failure is emitted,
+     * not thrown, so one bad device doesn't stop the rest or kill the timer.
+     */
+    private armAll;
+    /** Publish the device-info arming request (both the "info" and "realtime" ff09 variants the app sends). */
+    private arm;
+    /** The common `head` fields for every cmd envelope; callers add `cmd` + the per-message variable bits. */
+    private makeHead;
+    /**
+     * Build the `{head, payload}` cmd-17 (requestDeviceInfo) envelope carrying a base64 ff09 request.
+     * `account_id` is omitted when the user id is unknown: a live broker cannot tell an empty placeholder
+     * from a real value, so sending `""` would claim an account this client does not have.
+     */
+    private commandEnvelope;
+    /**
+     * The `power_site` heartbeat (cmd 10) envelope the app sends on a timer to keep the session alive.
+     * `site_id` is omitted when unknown, for the same reason `account_id` is in {@link commandEnvelope}.
+     */
+    private heartbeatEnvelope;
+    /**
+     * Decode one inbound MQTT message envelope and emit a `reading` if it carries an ff09 param frame. The
+     * product code and the fallback serial come from the topic (`dt/{app}/{pn}/{sn}/param_info`); the frame's
+     * own `a2` field wins for the serial when it carries one.
+     *
+     * Serial resolution matters because NOT every frame carries it: the device-info frame (which alone
+     * carries SOC/temperature via tags a3/a4) has a 1-byte `a2` (a status, not a serial) and can arrive on
+     * a topic whose serial segment isn't the device serial either — leaving a `deviceSn` that matches no
+     * watched device, so a consumer keying on it would drop the reading (and its temperature). So when the
+     * resolved serial isn't a watched device, fall back to the single watched device of this product code.
+     */
+    private onMessage;
+    /**
+     * Turn an app→device cmd-17 (`0x68`) command seen on the `…/req` channel into a `reading` carrying the
+     * app-set control state, so a change made in the app reflects back. The Solarbank's ambient light and
+     * display timeout are set this way (byte-identical to what {@link setDisplayTimeout} publishes), and the
+     * broker copies the app's publish to us as a co-subscriber. Only `0x68` frames carrying `a4`/`a5` are
+     * emitted, so the arming polls (`0x40`/`0x57`) and our own echoes contribute nothing:
+     * - `a4 = [01, s]` → ambient light, INVERTED (`s` 0 = on) → `ambientLightOn` 1/0. The `ba` telemetry
+     *   bit only tracks our `set_device_attrs` write, so this is the ONLY read-back of an app light toggle.
+     * - `a5 = [01, i]` → display timeout, `i` = 1-based dropdown index → `displayTimeoutIndex`.
+     */
+    private handleCommand;
+}
+/**
+ * Pull the ff09 binary frame out of a received message. Solix telemetry arrives as a `{head, payload}`
+ * envelope whose `payload` is a JSON string carrying base64 `data` (or `trans`); `SecureMqtt`
+ * has already JSON-parsed the outer envelope. Returns the decoded frame bytes, or `null`.
+ */
+export declare function extractFf09Payload(raw: unknown): Buffer | null;
+/**
+ * Build the ff09 request frame the app base64-encodes into a `requestDeviceInfo` (cmd 17) command's
+ * `data`. Captured live from the Anker app — request-type tag `a1`=0x22; the `realtime` variant adds
+ * `a2`/`a3` params (this is the one that keeps `param_info` reporting flowing), while `info` is the bare
+ * device-info fetch. Frame:
+ *   `ff09 | len(u16 LE, TOTAL bytes incl. ff09+len+xor) | 5-byte header | a1 01 22
+ *    [| a2 02 01 01 | a3 03 02 2c 01] | fe … <ts32 LE> | xor`
+ * `fe` carries a fresh unix-timestamp nonce; the trailing byte is XOR of every preceding byte (the same
+ * checksum the meter's telemetry frames use — verified to reproduce the captured frames exactly).
+ */
+/**
+ * Build the display screen-off-timeout command frame (ff09 msgtype `0x68`, tag `a5 = [01, index]`),
+ * captured live from the app on `cmd/anker_power/<pc>/<sn>/req` (cmd 17). `index` is the 1-based
+ * position in the app dropdown `[10s,20s,30s,1m,5m,30m]` — live-confirmed 10s=1, 30s=3, 1m=4. "Never"
+ * is a separate command (not this one). Byte-identical to the captured frames modulo the index byte.
+ */
+export declare function buildDisplayTimeoutFrame(index: number): Buffer;
+export declare function buildFf09Request(variant: "info" | "realtime", atUnixSec?: number): Buffer;

package/dist/transport/mqtt/topics.d.ts

@@ -78,3 +78,33 @@ export interface ParsedTopic {
  * so an unparsed topic leaves `deviceSn` unset instead of carrying a guess.
  */
 export declare function parseSecureTopic(topic: string): ParsedTopic | undefined;
+/** The per-device Solix topics for `{appName, productCode, deviceSn}`. */
+export interface SolixDeviceTopics {
+    /** Telemetry the device pushes (SUBSCRIBE) — ff09 `param_info` frames (live measurements). */
+    paramInfo: string;
+    /**
+     * Settings/state the device pushes (SUBSCRIBE) — ff09 `state_info` frames. Same ff09 framing as
+     * `param_info` but the TAGS carry SETTINGS/targets (mode export limit, SOC limits, max_load, toggles),
+     * NOT live measurements — so it needs its own tag→name table, not the param_info one.
+     */
+    stateInfo: string;
+    /** This device's command replies (SUBSCRIBE). */
+    cmdRes: string;
+    /**
+     * The device's requestDeviceInfo channel (cmd 17). PUBLISH to arm reporting; also SUBSCRIBE — the
+     * broker copies the APP's publishes here to any co-subscriber, which is the only way to observe a
+     * control the app changed that `param_info` does not reflect (ambient light, display timeout).
+     */
+    req: string;
+}
+/** Build the per-device Solix topics. `param_info` is the telemetry we decode; `req` is arm + read-back. */
+export declare function solixDeviceTopics(appName: string, productCode: string, deviceSn: string): SolixDeviceTopics;
+/** The per-account Solix topics keyed by `user_id`. */
+export interface SolixUserTopics {
+    /** Account-level command replies (SUBSCRIBE). */
+    cmdRes: string;
+    /** The `power_site` heartbeat channel (PUBLISH only). */
+    powerSite: string;
+}
+/** Build the per-account Solix topics. Note: the account `…/req` channel is publish-side and NOT subscribed. */
+export declare function solixUserTopics(appName: string, userId: string): SolixUserTopics;

package/dist/transport/p2p/command-router.d.ts

@@ -18,6 +18,25 @@ import type { FfmpegLevel } from "../ffmpeg.js";
 import { SharedLiveSource } from "./shared-live-source.js";
 import { type PowerTier, type SessionManagerOpts } from "./session-manager.js";
 import { FragmentRecording } from "./fragment-recording.js";
+/**
+ * What a caller's own deadline on a station call has to clear, in milliseconds.
+ *
+ * A caller that bounds one of these calls itself races these waits, and a bound below them reports the
+ * caller's own expiry in place of the reason this SDK was about to give — the two are indistinguishable to
+ * whoever reads the outcome, and they call for different next steps. Published so that bound can be derived
+ * rather than copied: a literal in a caller's source is a second source of truth that goes stale silently
+ * when these change.
+ *
+ * `connect` applies to every call on a station, because nothing can be addressed to one before its session is
+ * up, and it is the session's own connect deadline: a session that reaches it closes itself, so waiting past it
+ * waits on a connection that can no longer answer. `level2Grace` applies twice where the key is required: the
+ * negotiation is re-prompted once.
+ */
+export declare const P2P_STATION_WAITS: {
+    readonly connect: 15000;
+    readonly level2Grace: 25000;
+    readonly level2Settle: 8000;
+};
 /**
  * Options accepted when warming a {@link SharedLiveSource} for a device (all optional).
  *
@@ -71,7 +90,7 @@ export interface P2PRouterDeps {
 }
 export declare class P2PCommandRouter {
     private readonly deps;
-    /** Per-station P2P session lifecycle: on-demand open + battery-aware idle-detach + refcount. */
+    /** P2P session lifecycle: on-demand open + battery-aware idle-detach + refcount, per session key. */
     private readonly manager;
     /** Error objects already forwarded while a station startup awaits the same session signal. */
     private readonly reportedErrors;
@@ -79,6 +98,21 @@ export declare class P2PCommandRouter {
     private readonly liveSources;
     /** The options each live source was built from, so a later caller's conflicting ones can be reported. */
     private readonly liveSourceOpts;
+    /**
+     * The session each live source pulls over — the station's own serial, or the source's own media
+     * session key.
+     *
+     * Written the instant the choice is made and BEFORE the connection is opened, which is what makes it
+     * a reservation rather than a record. Two cameras started together (the four-tile case this feature
+     * exists for) would otherwise both find the station's session free: a consumer attaches only after
+     * `sharedLiveSourceFor` returns, so neither is visible to the other through consumer counts, and both
+     * would take the shared connection and contend on it.
+     *
+     * A station entry is kept as well as a media one, because "is the station's own session already
+     * claimed" is the question being asked, and an entry that is present but not yet in
+     * {@link liveSources} is a claim in flight.
+     */
+    private readonly liveSessionKeys;
     /**
      * The open talkback per `${parentSn}:${channel}`, if any. The device plays one audio stream at a
      * time and the session carries one audio sequence, so this path is exclusive where a live pull is
@@ -90,6 +124,12 @@ export declare class P2PCommandRouter {
     constructor(deps: P2PRouterDeps);
     /** Forward one P2P failure once even when both the session listener and startup waiter observe it. */
     private reportError;
+    /**
+     * Emit a live trace under a station session's handle, for work this router does ON that session before
+     * the session itself records anything — reaching the station, and resolving what a device is on it. Same
+     * handle as everything the session goes on to trace, which is what groups one attempt.
+     */
+    private traceOnStation;
     /**
      * Whether this transport stack drives `dev`'s `ff09-*` commands — true when the device has its own
      * usable P2P endpoint (a non-empty `p2p_did`). The command sink asks each stack this to route a
@@ -99,7 +139,10 @@ export declare class P2PCommandRouter {
      * `no P2P session`.
      */
     static claimsDevice(dev: EufyDevice): boolean;
-    /** Stations with a live P2P session (a snapshot; mutate via the lifecycle methods, not this map). */
+    /**
+     * The open P2P sessions by key — a station's own under its serial, a camera's media session under
+     * `<stationSn>#live:<channel>` (a snapshot; mutate via the lifecycle methods, not this map).
+     */
     getSessions(): Map<string, P2PSession>;
     /**
      * Speculatively open + briefly hold a station's session (e.g. after a doorbell ring) so a
@@ -109,7 +152,7 @@ export declare class P2PCommandRouter {
      *
      * One hold, taken before the open so a slow connect can't idle-close mid-flight. It expires on its
      * own, which arms the station's idle window rather than closing the session, per {@link PREWARM_MS}.
-     * A second hold after the open would buy nothing: {@link openStation} returns once the socket is bound
+     * A second hold after the open would buy nothing: {@link openSession} returns once the socket is bound
      * and the lookups are away, not once the peer has answered, so both would expire together.
      *
      * Best-effort — a failed open surfaces via `onError`. A {@link SessionSupersededError} does not: the
@@ -142,7 +185,41 @@ export declare class P2PCommandRouter {
      * when present, else the freshest private IP in the record ({@link freshestLanIp}) — so P2P works
      * on-LAN even when broadcast is blocked (AP isolation) or the record's `ip_addr` went stale.
      */
-    private openStation;
+    /**
+     * The key a camera's own media session is filed under, distinct from every station serial because a
+     * serial contains no `#`.
+     */
+    private static mediaSessionKey;
+    /** Whether `key` names a media session rather than a station's own. */
+    private static isMediaSessionKey;
+    /**
+     * Open (or reuse) a SECOND connection to a station, carrying one camera's media and nothing else.
+     *
+     * One session serves one camera: a station fans its cameras over a session and answers the most recent
+     * start on it, so two cameras down one tunnel take it from each other in turn. Another connection is
+     * how a station serves another camera.
+     *
+     * The hardware was shown to do this before the SDK did. A first-party display showing four tiles was
+     * captured opening one PPCS session per camera, with three cameras' video arriving in the same second
+     * at 2304x1296, 1600x1200 and 3840x2160 — three geometries at once, which no composed stream can be.
+     * Reproduced here afterwards on a base carrying two attached cameras, one at 3840x2160, both holding
+     * full frame rate at once over a session each, where the same pair down one session could only take
+     * turns.
+     *
+     * It carries media alone. The station announces its state to every client that connects, so a session
+     * wired to the same fan-out would report every event a second time; {@link makeSession} leaves this one
+     * unannounced, and the station's own session stays the single source of connection state, control
+     * notifications and frames.
+     *
+     * The level-2 key is waited for here on the same terms the station's own session gets, because a
+     * connection is not usable for this without one: an attached camera's media start has no level-1 form,
+     * so a start issued before the key arrives is dropped as `media-command-unsent`, and the stream then
+     * shows nothing until a later keepalive tick happens to find the key. A connected session that cannot
+     * carry the start is not a connected session, so this refuses rather than returning one.
+     */
+    private openMediaSession;
+    /** Open (or reuse) the session filed under `key`, dialling `parentSn`'s endpoint. */
+    private openSession;
     /**
      * Build + wire a {@link P2PSession} for a station (NOT yet connected — the caller awaits `connect()`).
      *
@@ -154,6 +231,12 @@ export declare class P2PCommandRouter {
      *
      * The `close` handler drops the session from the {@link SessionManager} and disposes any shared live
      * source riding this station (consumers get `stop`; a later attach rebuilds via the factory).
+     *
+     * A session filed under a media key is wired for errors and its own teardown ONLY. Connection state,
+     * level-2 readiness and inbound frames all reach the owner through the station's own session, and a
+     * station announces those to every client that connects — so fanning a second connection's copies out
+     * under the same station serial would report each one twice, and a close would tear down the station
+     * while its own session is still serving.
      */
     private makeSession;
     /**
@@ -262,22 +345,40 @@ export declare class P2PCommandRouter {
      * {@link releaseLingeringSiblings}. A pull with consumers is never touched. The release runs before the
      * reuse branch, so a reuse frees the station as a cold start does.
      *
+     * `mayOpenOwnSession` decides whether a camera that finds the station's own session claimed may open a
+     * connection of its own for it. Only the continuous-pull egresses pass it. A still must not: it wants one
+     * frame, and a socket plus a level-2 negotiation per thumbnail is a cost a tile refresh cannot justify —
+     * so a still asked for while a sibling is being watched contends as it always did, and the caller's
+     * retained image answers it. A live view still outranks a tile; what changed is that two live views no
+     * longer have to outrank each other.
+     *
      * The session goes into a {@link HeldSession} cell, so it can be replaced under a source that stays in
      * place.
      */
-    sharedLiveSourceFor(sn: string, opts?: SharedLiveOpts): Promise<SharedLiveSource>;
+    sharedLiveSourceFor(sn: string, opts?: SharedLiveOpts, mayOpenOwnSession?: boolean): Promise<SharedLiveSource>;
     /**
      * Tear down any pull on this station that is lingering for ANOTHER camera, before starting this one.
      *
      * A lingering pull has no consumers but is still held open, and on an attached camera holding it open means
-     * re-sending the full media start every keepalive tick. Two channels doing that at once on a station that
-     * serves one camera at a time leaves the new stream receiving nothing but the old camera's frames for as
-     * long as the linger lasts.
+     * re-sending the full media start every keepalive tick. Two channels doing that at once over ONE session,
+     * which serves one camera at a time, leaves the new stream receiving nothing but the old camera's frames
+     * for as long as the linger lasts.
      *
      * Several cameras genuinely being WATCHED together are never disturbed — the linger exists to make
      * re-opening the SAME camera cheap, and it keeps doing that. What it may not do is keep a camera nobody is
      * looking at competing with one somebody just asked for.
      *
+     * An `idle` source is skipped, because it is not a linger and holds nothing: it has never warmed, so it
+     * has sent no media start and is competing for nothing. Without that, two cameras opened at the same
+     * moment destroy each other — the second finds the first's source built but not yet attached to, reads
+     * zero consumers as a linger, and disposes the source its caller is holding. Which is the four-tile case
+     * this whole path exists for.
+     *
+     * A sibling lingering on a connection of its OWN is skipped for the same reason stated the other way: the
+     * contention this releases is contention over one session, and that sibling is not on this one. Dropping
+     * it would close a socket and throw away the cheap re-attach the linger exists to provide, to relieve a
+     * competition that is not happening.
+     *
      * A snapshot tile is nobody looking. Opening a live view in the Home app takes that cell fullscreen, so the
      * pulls refreshing the other cells are off screen, yet each goes on re-issuing its own media start every
      * retry tick — measured as four pulls warming together off one HomeBase, a live request landing 1.4 s later,
@@ -288,14 +389,27 @@ export declare class P2PCommandRouter {
      */
     private releaseLingeringSiblings;
     /**
-     * The channel a live viewer already holds on this station, if any, ignoring `key` itself.
+     * Whether another camera has already claimed this station's OWN session, ignoring `key`.
+     *
+     * The question a newcomer has to answer is not whether the station is busy — it can serve one camera
+     * per connection — but whether the connection it would otherwise share is taken. A camera on a media
+     * session of its own does not hold this one, so a station whose first camera has since stopped hands
+     * its own session to the next arrival rather than opening a socket beside an idle one.
+     *
+     * A claim counts while its source is still `idle`, source or no source. That is a start that has been
+     * handed to its caller but not yet attached to, and it is the only state in which two cameras asked for
+     * at the same moment can see each other: consumers attach after this method has already run for both.
+     *
+     * The cost is that a pull genuinely abandoned before its first attach goes on holding the station's own
+     * session, and the next camera pays for a connection of its own rather than reclaiming it. That is one
+     * socket against destroying a start someone is waiting on, which is not a close trade.
      *
      * A stopped source is skipped even when consumers are still attached to it. A failed start fails its
      * consumers without detaching them, so a caller still holding a dead handle leaves the count non-zero,
-     * and counting that as a viewer would refuse every later stream on the station until the client
-     * restarted. Only a source that can still deliver holds a place.
+     * and counting that as a viewer would put every later camera on a connection of its own until the
+     * client restarted. Only a source that can still deliver holds a place.
      */
-    private occupiedSiblingChannel;
+    private stationSessionInUse;
     /**
      * Whether the stream on `key` should re-assert its channel to hold the station.
      *
@@ -305,8 +419,8 @@ export declare class P2PCommandRouter {
      *  - Nothing attached: no. There is nobody to take the station for.
      *  - A live viewer attached: yes. That is the picture someone is looking at.
      *  - Held only for stills, while a sibling on this station has a live viewer: no. A still refreshes a
-     *    tile that is off screen while the live view is on it, and a station serving one camera at a time
-     *    cannot satisfy both. Measured: a still on a sibling halved a live view's frame rate for as long as
+     *    tile that is off screen while the live view is on it, and one session serving one camera at a time
+     *    cannot satisfy both — and a still does not open a connection of its own. Measured: a still on a sibling halved a live view's frame rate for as long as
      *    it took, and its own capture then took fifteen seconds because it was contending.
      *
      * A still with no live sibling re-asserts, so a tile refreshing on a quiet station is
@@ -321,8 +435,24 @@ export declare class P2PCommandRouter {
      * not.
      */
     private attachUnlessAborted;
-    /** Dispose one cached live source and forget it, so the next acquisition builds a fresh one. */
+    /**
+     * Dispose one cached live source and forget it, so the next acquisition builds a fresh one. Its claim
+     * on a session goes with it, and a media session opened for this source alone is closed: nothing else
+     * can reach that connection, so leaving it open would hold a socket and a station keepalive for a
+     * camera no longer being pulled. A claim on the STATION's own session is released without closing
+     * anything — that connection carries the station's control traffic and outlives any one camera.
+     */
     private dropLiveSource;
+    /** Close and forget the media session `key`'s live source owned, if it owned one. */
+    private closeMediaSession;
+    /**
+     * Drop the live source a media session was carrying, after that session closed on its own.
+     *
+     * The source holds the closed connection and never re-resolves it, so it can only answer its retained
+     * keyframe and then fail on its warm-up deadline. Its consumers get `stop`, and the next attach builds
+     * a fresh source — which, finding the station busy again, opens a fresh media session for it.
+     */
+    private tearDownMediaSession;
     /**
      * Drop everything that was riding a station's session, and report the station closed.
      *
@@ -545,6 +675,13 @@ export declare class P2PCommandRouter {
      * standalone camera never negotiates a level-2 key, so pinning this to level 2 makes the envelope
      * unreachable on exactly the devices that serve their own RTSP stream. Verified live: a standalone
      * camera accepts the level-1 form. With no `form` (default) it stays level-2 only.
+     *
+     * Both seals REPLAY the frame {@link DIRECT_CMD_SENDS}× at 200ms, as every other fire-and-forget
+     * control on this router does: these are unacknowledged datagrams, and a level-1 device is the one
+     * least able to afford a single dropped one — it has no reply, no readback here, and nothing that
+     * would tell a caller the write was lost rather than refused. The level-1 form reports delivery by
+     * throwing (`sendSetPayload` throws when the session has no address) rather than by returning a
+     * boolean, so the first pass carries the failure and the rest are repeats.
      */
     private sendSetPayloadEnvelope;
     /**

package/dist/transport/p2p/index.d.ts

@@ -10,4 +10,5 @@ export * from "./envelope.js";
 export * from "./write-commands.js";
 export * from "./lan-ip.js";
 export { LIVE_TRACE_MESSAGE, type LiveTrace } from "./live-trace.js";
+export { P2P_STATION_WAITS } from "./command-router.js";
 export * as p2pCodec from "./codec.js";