/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ import { PersistedFileDesignator } from "#bdx/PersistedFileDesignator.js"; import { ScopedStorage } from "#bdx/ScopedStorage.js"; import { Construction, Environment, MatterError } from "@matter/general"; import { DeviceSoftwareVersionModelDclSchema } from "@matter/types"; import { DclConfig } from "./DclConfig.js"; /** Error thrown when OTA update check or download fails */ export declare class OtaUpdateError extends MatterError { constructor(message: string, options?: ErrorOptions); } export type OtaUpdateSource = "local" | "dcl-prod" | "dcl-test"; export type OtaStorageMode = "prod" | "test" | "local"; export interface DeviceSoftwareVersionModelDclSchemaWithSource extends DeviceSoftwareVersionModelDclSchema { source: OtaUpdateSource; } /** * Update information returned by checkForUpdate. * This is an alias for the DCL schema to provide better semantic meaning. */ export type OtaUpdateInfo = DeviceSoftwareVersionModelDclSchemaWithSource; /** * Service to query and manage OTA updates from the Distributed Compliance Ledger (DCL), but also allows to inject own * OTA update info from streams or files. The service is designed as a singleton within an Environment and is shared * across multiple nodes. This service is mainly relevant for controllers. * * The service checks the DCL for available software updates for Matter devices and can download and validate OTA * images. Production and test DCL instances are supported, with separate file storage for each. */ export declare class DclOtaUpdateService { #private; get construction(): Construction; /** Whether the service runs {@link DclOtaUpdateService.Options.offline}. */ get offline(): boolean; constructor(environment: Environment, options?: DclOtaUpdateService.Options); get storage(): ScopedStorage; close(): Promise; /** * Check DCL for available software updates for a device, defined by its vendor ID, product ID, and current * software version. If a target software version is provided, only that version is checked for applicability and * ignoring other newer versions. * If isProduction flag is specified, it is exactly used to find updates. Leave that flag undefined to find both * test and production updates. * When the service is {@link DclOtaUpdateService.Options.offline} the DCL is not asked, so only stored updates * (`includeStoredUpdates`) can be found. */ checkForUpdate(options: { vendorId: number; productId: number; currentSoftwareVersion: number; includeStoredUpdates?: boolean; isProduction?: boolean; targetSoftwareVersion?: number; }): Promise; /** * Store an OTA update image from a ReadableStream into persistent storage. */ store(stream: ReadableStream, updateInfo: OtaUpdateInfo, mode?: boolean | OtaStorageMode): Promise; /** * Download and validate an OTA update image from a HTTP pr HTTPS server. * * If a file with the same vendor ID, product ID, and production mode already exists * and passes validation, it will be reused instead of downloading again, unless force is true. * * Production and test files are stored separately to avoid conflicts. * * Returns a PersistedFileDesignator for the validated OTA image * * A stored image that fails validation is removed. Online, a stored image that cannot be read is replaced by a * download as well. * * @throws {OtaUpdateError} if the image is neither stored and valid nor downloadable. When the service is * {@link DclOtaUpdateService.Options.offline} it throws instead of downloading: after a stored image that fails * validation was removed, when none is stored, when the stored image cannot be read (it is kept) and with * `force` (the stored image is kept) */ downloadUpdate(updateInfo: OtaUpdateInfo, force?: boolean, timeout?: import("@matter/general").Duration): Promise; /** * Create OtaUpdateInfo from an OTA image stream. * * This method reads and validates an OTA image from a ReadableStream and creates an OtaUpdateInfo * structure. This is useful for providing OTA updates from local files or any stream source. * * The OTA image header contains most required information. However, some DCL-specific * fields are not present in the OTA header and must be provided via options or use defaults: * - cdVersionNumber: Certificate Declaration version (defaults to 1) * - softwareVersionValid: Validity flag (defaults to true) * - schemaVersion: DCL schema version (defaults to 0) * - minApplicableSoftwareVersion: If not in header, defaults to 0 (all versions) * - maxApplicableSoftwareVersion: If not in header, defaults to current version minus 1 * - specificationVersion: Not in the OTA header; stored with the image when provided * * @param stream - ReadableStream of the OTA image * @param otaUrl - URL to use for the OTA file (should be file:// for local files or https:// for remote) * @param options - Optional parameters for DCL-specific fields not in OTA header * @returns OtaUpdateInfo with stream data and header information */ updateInfoFromStream(stream: ReadableStream, otaUrl: string, options?: { /** Certificate Declaration version number. Defaults to 1. */ cdVersionNumber?: number; /** Whether this version is valid. Defaults to true. */ softwareVersionValid?: boolean; /** DCL schema version. Defaults to 0. */ schemaVersion?: number; /** * Minimum applicable software version. If not provided and not in OTA header, * defaults to 0 (applicable to all versions). */ minApplicableSoftwareVersion?: number; /** * Maximum applicable software version. If not provided and not in OTA header, * defaults to current version (only applicable to current version and below). */ maxApplicableSoftwareVersion?: number; /** Matter specification version the image implements, stored with the image. */ specificationVersion?: number; }): Promise; /** * Create OtaUpdateInfo from a remote OTA image file URL. * * This method fetches and validates a remote OTA image file (via HTTPS) and creates an OtaUpdateInfo * structure that can be used with downloadUpdate(). For local files, use updateInfoFromStream() instead. * * The OTA image header contains most required information. However, some DCL-specific * fields are not present in the OTA header and must be provided via options or use defaults: * - cdVersionNumber: Certificate Declaration version (defaults to 1) * - softwareVersionValid: Validity flag (defaults to true) * - schemaVersion: DCL schema version (defaults to 0) * - minApplicableSoftwareVersion: If not in header, defaults to 0 (all versions) * - maxApplicableSoftwareVersion: If not in header, defaults to current version * - specificationVersion: Not in the OTA header; stored with the image when provided * * @param fileUrl - HTTPS URL to the OTA image file * @param options - Optional parameters for DCL-specific fields not in OTA header * @returns OtaUpdateInfo with file URL and header data * @throws {OtaUpdateError} if the image cannot be read, including when the service is * {@link DclOtaUpdateService.Options.offline} */ createUpdateInfoFromFile(fileUrl: string, options?: { /** Certificate Declaration version number. Defaults to 1. */ cdVersionNumber?: number; /** Whether this version is valid. Defaults to true. */ softwareVersionValid?: boolean; /** DCL schema version. Defaults to 0. */ schemaVersion?: number; /** * Minimum applicable software version. If not provided and not in OTA header, * defaults to 0 (applicable to all versions). */ minApplicableSoftwareVersion?: number; /** * Maximum applicable software version. If not provided and not in OTA header, * defaults to current version (only applicable to current version and below). */ maxApplicableSoftwareVersion?: number; /** Matter specification version the image implements, stored with the image. */ specificationVersion?: number; }): Promise; /** * Find downloaded OTA updates in storage. * * This method scans the OTA storage for downloaded update files and returns * information about them. Files can be filtered by vendor ID, product ID, * and production/test mode. * * @param options - Optional filter criteria * @param options.vendorId - Filter by vendor ID * @param options.productId - Filter by product ID (requires vendorId) * @param options.isProduction - Filter by production (true) or test (false) mode * @returns Array of downloaded update information */ find(options?: DclOtaUpdateService.FindOptions): Promise; /** Get a PersistedFileDesignator for a stored OTA update file by filename. */ fileDesignatorForUpdate(filename: string): Promise; /** * Delete stored OTA update files. * * Can delete by specific filename or by vendor ID, product ID, and mode. * If only vendor ID is provided (no product ID), all files for that vendor are deleted. * * @param options - Deletion criteria * @param options.filename - Specific filename to delete (e.g. `fff1.8000.prod.3`) * @param options.vendorId - Vendor ID to filter files for deletion * @param options.productId - Product ID to filter files for deletion (optional, requires vendorId) * @param options.isProduction - (deprecated, use `mode` instead) production (true) or test (false) mode * @param options.mode - Storage mode: "prod", "test", or "local" * @returns Number of files deleted */ delete(options: { filename?: string; vendorId?: number; productId?: number; /** @deprecated Use mode instead */ isProduction?: boolean; mode?: OtaStorageMode; }): Promise; } export declare namespace DclOtaUpdateService { interface Options { /** DCL config for production endpoint. Defaults to DclConfig.production. */ productionDclConfig?: DclConfig; /** DCL config for test endpoint. Defaults to DclConfig.test. */ testDclConfig?: DclConfig; /** * Reaches no network at all: the DCL is not asked for updates and no OTA image is downloaded. Update checks * find only images already in storage (with `includeStoredUpdates`). {@link DclOtaUpdateService.downloadUpdate} * returns a stored image that validates; a stored image that fails validation is removed as online, and the * call then fails with {@link OtaUpdateError}. When the stored image cannot be read, or with `force`, it fails * without touching the stored image, since it cannot be replaced. Reading an image from a URL fails with * {@link OtaUpdateError}. * * For a deployment with no route to the ledger, and for short-lived test processes that must not depend on * it. */ offline?: boolean; } type OtaUpdateListEntry = { filename: string; vendorId: number; productId: number; softwareVersion: number; softwareVersionString: string; minApplicableSoftwareVersion?: number; maxApplicableSoftwareVersion?: number; mode: OtaStorageMode; size: number; /** Specification version recorded when the image was stored, if known. */ specificationVersion?: number; }; interface FindOptions { vendorId?: number; productId?: number; isProduction?: boolean; mode?: OtaStorageMode; currentVersion?: number; } } //# sourceMappingURL=DclOtaUpdateService.d.ts.map