@nordicsemiconductor/pc-nrfconnect-shared 89.0.0 → 91.0.0

package/nrfutil/device/common.ts

@@ -0,0 +1,274 @@
+/*
+ * Copyright (c) 2023 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import { getUserDataDir } from '../../src/utils/appDirs';
+import {
+    getIsLoggingVerbose,
+    persistIsLoggingVerbose,
+} from '../../src/utils/persistentStore';
+import { getNrfutilLogger } from '../nrfutilLogger';
+import sandbox, { type NrfutilSandbox } from '../sandbox';
+import { Progress } from '../sandboxTypes';
+
+export const deviceTraitsToArgs = (traits: DeviceTraits) => {
+    const args: string[] = [];
+    const traitsString = Object.keys(traits)
+        .map(trait => (traits[trait as keyof DeviceTraits] ? trait : null))
+        .filter(t => t !== null)
+        .join(',');
+
+    if (traitsString.length > 0) {
+        args.push('--traits');
+        args.push(traitsString);
+    }
+
+    return args;
+};
+
+export type ResetKind =
+    | 'RESET_SYSTEM'
+    | 'RESET_HARD'
+    | 'RESET_DEBUG'
+    | 'RESET_PIN';
+
+export interface DeviceArrivedEvent {
+    device: NrfutilDevice;
+}
+
+export interface DeviceLeftEvent {
+    id: number;
+}
+
+export interface HwInfo {
+    romSize: number;
+    ramSize: number;
+    romPageSize: number;
+    deviceFamily: string;
+    deviceVersion: string;
+}
+
+export interface DfuTriggerInfo {
+    wAddress: number;
+    wVersionMajor: number;
+    wVersionMinor: number;
+    wFirmwareId: number;
+    wFlashSize: number;
+    wFlashPageSize: number;
+}
+
+export interface DfuTriggerVersion {
+    semVer: string;
+}
+
+export interface NrfutilDevice {
+    id: number;
+    serialNumber?: string; // undefined in case udev is not installed
+    traits: DeviceTraits;
+    usb?: USB;
+    jlink?: JLink;
+    // non-Nordic devices may not have serialPorts property at all
+    serialPorts?: Array<SerialPort>;
+    hwInfo?: HwInfo;
+    dfuTriggerInfo?: DfuTriggerInfo;
+    dfuTriggerVersion?: DfuTriggerVersion;
+    broken?: null | {
+        description: string;
+        url: string;
+    };
+}
+
+export interface NrfutilDeviceWithSerialnumber extends NrfutilDevice {
+    serialNumber: string;
+}
+
+export type DeviceFamily =
+    | 'NRF51_FAMILY'
+    | 'NRF52_FAMILY'
+    | 'NRF53_FAMILY'
+    | 'NRF91_FAMILY';
+
+export type ProtectionStatus =
+    | 'NRFDL_PROTECTION_STATUS_NONE'
+    | 'NRFDL_PROTECTION_STATUS_REGION0'
+    | 'NRFDL_PROTECTION_STATUS_REGION0_REGION1'
+    | 'NRFDL_PROTECTION_STATUS_SECURE_REGIONS'
+    | 'NRFDL_PROTECTION_STATUS_ALL';
+
+export type VersionType =
+    | 'NRFDL_VERSION_TYPE_SEMANTIC'
+    | 'NRFDL_VERSION_TYPE_INCREMENTAL'
+    | 'NRFDL_VERSION_TYPE_STRING';
+
+export type DeviceCore = 'Application' | 'Modem' | 'Network';
+
+export interface DeviceTraits {
+    usb?: boolean;
+    nordicUsb?: boolean;
+    nordicDfu?: boolean;
+    seggerUsb?: boolean;
+    jlink?: boolean;
+    serialPorts?: boolean;
+    broken?: boolean;
+    mcuBoot?: boolean;
+    modem?: boolean;
+}
+
+export interface USB {
+    serialNumber: string;
+    manufacturer: string | null;
+    osDevicePath: string;
+    product: string | null;
+    device: USBDevice;
+}
+
+export interface USBDeviceDescriptor {
+    bDescriptorType: number;
+    idVendor: number;
+    idProduct: number;
+    bcdDevice: number;
+}
+
+export interface USBConfigurationDescriptor {
+    bDescriptorType: number;
+}
+
+export interface USBInterfaceDescriptor {
+    bDescriptorType: number;
+    bInterfaceClass: number;
+    bInterfaceSubClass: number;
+    bInterfaceProtocol: number;
+}
+
+export interface USBInterface {
+    descriptors: USBInterfaceDescriptor[];
+    endpointLists: USBEndpoint[];
+}
+
+export interface USBEndpointDescriptor {
+    bDescriptorType: number;
+}
+
+export interface USBEndpoint {
+    descriptors?: USBEndpointDescriptor[];
+    length: number;
+}
+
+export interface USBConfiguration {
+    descriptors: USBConfigurationDescriptor[];
+    interfaceLists: USBInterface[];
+    length: number;
+}
+
+export interface USBDevice {
+    busNumber: number;
+    address: number;
+    descriptor: USBDeviceDescriptor;
+    configList: USBConfiguration; // todo: check this prop
+}
+
+export interface JLink {
+    serialNumber: string;
+    boardVersion: string | null; // can be null for external jLink
+    jlinkObFirmwareVersion: string | null;
+    deviceFamily: string | null;
+    deviceVersion: string | null; // will be null if device is protected
+}
+
+export interface SerialPort {
+    serialNumber: string | null;
+    comName: string | null;
+    manufacturer: string | null;
+    productId: string | null;
+    vendorId: string | null;
+    vcom: number;
+    path: string | null;
+}
+
+let deviceSandbox: NrfutilSandbox | undefined;
+let promiseDeviceSandbox: Promise<NrfutilSandbox> | undefined;
+
+export const getDeviceSandbox = async () => {
+    if (deviceSandbox) {
+        return deviceSandbox;
+    }
+
+    if (!promiseDeviceSandbox) {
+        promiseDeviceSandbox = sandbox(
+            getUserDataDir(),
+            'device',
+            undefined,
+            undefined
+        );
+        deviceSandbox = await promiseDeviceSandbox;
+
+        deviceSandbox.onLogging(evt => {
+            const deviceLogger = getNrfutilLogger();
+            switch (evt.level) {
+                case 'TRACE':
+                    deviceLogger?.verbose(evt.message);
+                    break;
+                case 'DEBUG':
+                    deviceLogger?.debug(evt.message);
+                    break;
+                case 'INFO':
+                    deviceLogger?.info(evt.message);
+                    break;
+                case 'WARN':
+                    deviceLogger?.warn(evt.message);
+                    break;
+                case 'ERROR':
+                    deviceLogger?.error(evt.message);
+                    break;
+                case 'CRITICAL':
+                    deviceLogger?.error(evt.message);
+                    break;
+                case 'OFF':
+                default:
+                    // Unreachable
+                    break;
+            }
+        });
+
+        deviceSandbox.setLogLevel(getIsLoggingVerbose() ? 'trace' : 'error');
+        // Only the first reset after selecting "reset with verbose logging" is relevant
+        persistIsLoggingVerbose(false);
+    }
+
+    const box = await promiseDeviceSandbox;
+    return box;
+};
+
+export const deviceSingleTaskEndOperation = async <T = void>(
+    device: NrfutilDeviceWithSerialnumber,
+    command: string,
+    onProgress?: (progress: Progress) => void,
+    controller?: AbortController,
+    args: string[] = []
+) => {
+    const box = await getDeviceSandbox();
+    return box.singleTaskEndOperationWithData<T>(
+        command,
+        onProgress,
+        controller,
+        [...args, '--serial-number', device.serialNumber]
+    );
+};
+
+export const deviceSingleTaskEndOperationVoid = async (
+    device: NrfutilDeviceWithSerialnumber,
+    command: string,
+    onProgress?: (progress: Progress) => void,
+    controller?: AbortController,
+    args: string[] = []
+) => {
+    const box = await getDeviceSandbox();
+    await box.singleTaskEndOperationOptionalData(
+        command,
+        onProgress,
+        controller,
+        [...args, '--serial-number', device.serialNumber]
+    );
+};

package/nrfutil/device/device.ts

@@ -0,0 +1,62 @@
+/*
+ * Copyright (c) 2023 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import { LogLevel, LogMessage } from '../sandboxTypes';
+import { Batch } from './batch';
+import { getDeviceSandbox } from './common';
+import erase from './erase';
+import firmwareRead from './firmwareRead';
+import getCoreInfo from './getCoreInfo';
+import getFwInfo from './getFwInfo';
+import getProtectionStatus from './getProtectionStatus';
+import list from './list';
+import program from './program';
+import recover from './recover';
+import reset from './reset';
+import setMcuState from './setMcuState';
+import setProtectionStatus from './setProtectionStatus';
+
+const onLogging = async (handler: (logging: LogMessage) => void) => {
+    const sandbox = await getDeviceSandbox();
+    return sandbox.onLogging(handler);
+};
+
+const setLogLevel = async (level: LogLevel) => {
+    const sandbox = await getDeviceSandbox();
+    sandbox.setLogLevel(level);
+};
+
+const setVerboseLogging = async (verbose: boolean) => {
+    const sandbox = await getDeviceSandbox();
+    if (process.env.NODE_ENV === 'production' && !verbose) {
+        sandbox.setLogLevel('off');
+    } else {
+        sandbox.setLogLevel(verbose ? 'trace' : 'error');
+    }
+};
+const getModuleVersion = async () => {
+    const sandbox = await getDeviceSandbox();
+    return sandbox.getModuleVersion();
+};
+
+export default {
+    program,
+    erase,
+    recover,
+    reset,
+    getProtectionStatus,
+    setProtectionStatus,
+    getFwInfo,
+    setMcuState,
+    getCoreInfo,
+    list,
+    firmwareRead,
+    onLogging,
+    setLogLevel,
+    setVerboseLogging,
+    getModuleVersion,
+    batch: () => new Batch(),
+};

package/nrfutil/device/erase.ts

@@ -0,0 +1,26 @@
+/*
+ * Copyright (c) 2023 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import { Progress } from '../sandboxTypes';
+import {
+    DeviceCore,
+    deviceSingleTaskEndOperationVoid,
+    NrfutilDeviceWithSerialnumber,
+} from './common';
+
+export default (
+    device: NrfutilDeviceWithSerialnumber,
+    core?: DeviceCore,
+    onProgress?: (progress: Progress) => void,
+    controller?: AbortController
+) =>
+    deviceSingleTaskEndOperationVoid(
+        device,
+        'erase',
+        onProgress,
+        controller,
+        core ? ['--core', core] : []
+    );

package/nrfutil/device/eraseBatch.ts

@@ -0,0 +1,28 @@
+/*
+ * Copyright (c) 2023 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import {
+    BatchOperationWrapper,
+    Callbacks,
+    convertDeviceCoreType,
+    EraseOperation,
+} from './batchTypes';
+import { DeviceCore } from './common';
+
+export default (
+    core: DeviceCore,
+    optionals?: {
+        callbacks?: Callbacks;
+    }
+): BatchOperationWrapper<EraseOperation> => ({
+    operation: {
+        core: convertDeviceCoreType(core),
+        operation: {
+            type: 'erase',
+        },
+    },
+    ...optionals?.callbacks,
+});

package/nrfutil/device/firmwareRead.ts

@@ -0,0 +1,34 @@
+/*
+ * Copyright (c) 2023 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import { Progress } from '../sandboxTypes';
+import {
+    DeviceCore,
+    deviceSingleTaskEndOperation,
+    NrfutilDeviceWithSerialnumber,
+} from './common';
+
+export interface DeviceBuffer {
+    serialNumber: string;
+    buffer: string;
+}
+
+export default async (
+    device: NrfutilDeviceWithSerialnumber,
+    core?: DeviceCore,
+    onProgress?: (progress: Progress) => void,
+    controller?: AbortController
+) => {
+    const deviceBuffer = await deviceSingleTaskEndOperation<DeviceBuffer>(
+        device,
+        'fw-read',
+        onProgress,
+        controller,
+        core ? ['--core', core] : []
+    );
+
+    return Buffer.from(deviceBuffer.buffer, 'base64');
+};

package/nrfutil/device/firmwareReadBatch.ts

@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) 2023 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import {
+    BatchOperationWrapper,
+    Callbacks,
+    convertDeviceCoreType,
+    FirmwareReadOperation,
+} from './batchTypes';
+import { DeviceCore } from './common';
+import { DeviceBuffer } from './firmwareRead';
+
+export default (
+    core: DeviceCore,
+    optionals?: {
+        callbacks?: Callbacks<Buffer>;
+    }
+): BatchOperationWrapper<FirmwareReadOperation, DeviceBuffer> => ({
+    operation: {
+        core: convertDeviceCoreType(core),
+        operation: {
+            type: 'fw-read',
+            firmware: {
+                buffer: '',
+            },
+        },
+    },
+    ...optionals?.callbacks,
+    onTaskEnd: taskEnd => {
+        if (taskEnd.result === 'success' && taskEnd.data)
+            optionals?.callbacks?.onTaskEnd?.({
+                ...taskEnd,
+                data: Buffer.from(taskEnd.data.buffer, 'base64'),
+            });
+        else {
+            optionals?.callbacks?.onException?.(new Error('Read failed'));
+        }
+    },
+});

package/nrfutil/device/getCoreInfo.ts

@@ -0,0 +1,44 @@
+/*
+ * Copyright (c) 2023 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import { Progress } from '../sandboxTypes';
+import {
+    DeviceCore,
+    deviceSingleTaskEndOperation,
+    NrfutilDeviceWithSerialnumber,
+} from './common';
+
+export type DeviceCoreInfo = {
+    name: 'core-info';
+    codeAddress: number;
+    codePageSize: number;
+    codeSize: number;
+    uicrAddress: number;
+    infoPageSize: number;
+    codeRamPresent: boolean;
+    codeRamAddress: number;
+    dataRamAddress: number;
+    ramSize: number;
+    qspiPresent: boolean;
+    xipAddress: number;
+    xipSize: number;
+    pinResetPin: number;
+    serialNumber: string;
+};
+
+export default (
+    device: NrfutilDeviceWithSerialnumber,
+    core?: DeviceCore,
+    onProgress?: (progress: Progress) => void,
+    controller?: AbortController
+) =>
+    deviceSingleTaskEndOperation<DeviceCoreInfo>(
+        device,
+        'core-info',
+        onProgress,
+        controller,
+        core ? ['--core', core] : []
+    );

package/nrfutil/device/getCoreInfoBatch.ts

@@ -0,0 +1,29 @@
+/*
+ * Copyright (c) 2023 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import {
+    BatchOperationWrapper,
+    Callbacks,
+    convertDeviceCoreType,
+    GetCoreInfoOperation,
+} from './batchTypes';
+import { DeviceCore } from './common';
+import { DeviceCoreInfo } from './getCoreInfo';
+
+export default (
+    core: DeviceCore,
+    optionals?: {
+        callbacks?: Callbacks<DeviceCoreInfo>;
+    }
+): BatchOperationWrapper<GetCoreInfoOperation, DeviceCoreInfo> => ({
+    operation: {
+        core: convertDeviceCoreType(core),
+        operation: {
+            type: 'core-info',
+        },
+    },
+    ...optionals?.callbacks,
+});

package/nrfutil/device/getFwInfo.ts

@@ -0,0 +1,69 @@
+/*
+ * Copyright (c) 2023 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import { Progress } from '../sandboxTypes';
+import {
+    DeviceCore,
+    deviceSingleTaskEndOperation,
+    NrfutilDeviceWithSerialnumber,
+} from './common';
+
+type BootloaderType =
+    | 'NRFDL_BOOTLOADER_TYPE_NONE'
+    | 'NRFDL_BOOTLOADER_TYPE_MCUBOOT'
+    | 'NRFDL_BOOTLOADER_TYPE_SDFU'
+    | 'NRFDL_BOOTLOADER_TYPE_B0'
+    | 'NRFDL_BOOTLOADER_TYPE_UNKNOWN';
+
+export type ImageType =
+    | 'NRFDL_IMAGE_TYPE_APPLICATION'
+    | 'NRFDL_IMAGE_TYPE_BOOTLOADER'
+    | 'NRFDL_IMAGE_TYPE_SOFTDEVICE'
+    | 'NRFDL_IMAGE_TYPE_OPERATIVE_SYSTEM'
+    | 'NRFDL_IMAGE_TYPE_GENERIC'
+    | 'NRFDL_IMAGE_TYPE_UNKNOWN';
+
+interface ImageLocation {
+    address: number;
+    size: number;
+}
+
+interface SemanticVersion {
+    major: number;
+    minor: number;
+    patch: number;
+    pre: string;
+    metadata?: string;
+}
+
+interface Image {
+    imageLocation?: ImageLocation;
+    imageType: ImageType;
+    version: SemanticVersion | string | number;
+    versionFormat: string;
+}
+
+export interface FWInfo {
+    name: 'fw-read-info';
+    bootloaderType: BootloaderType;
+    imageInfoList: Image[];
+    serialNumber: string;
+    operationId?: string;
+}
+
+export default (
+    device: NrfutilDeviceWithSerialnumber,
+    core?: DeviceCore,
+    onProgress?: (progress: Progress) => void,
+    controller?: AbortController
+) =>
+    deviceSingleTaskEndOperation<FWInfo>(
+        device,
+        'fw-info',
+        onProgress,
+        controller,
+        core ? ['--core', core] : []
+    );

package/nrfutil/device/getFwInfoBatch.ts

@@ -0,0 +1,29 @@
+/*
+ * Copyright (c) 2023 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import {
+    BatchOperationWrapper,
+    Callbacks,
+    convertDeviceCoreType,
+    GetFwInfoOperation,
+} from './batchTypes';
+import { DeviceCore } from './common';
+import { FWInfo } from './getFwInfo';
+
+export default (
+    core: DeviceCore,
+    optionals?: {
+        callbacks?: Callbacks<FWInfo>;
+    }
+): BatchOperationWrapper<GetFwInfoOperation, FWInfo> => ({
+    operation: {
+        core: convertDeviceCoreType(core),
+        operation: {
+            type: 'fw-info',
+        },
+    },
+    ...optionals?.callbacks,
+});

package/nrfutil/device/getProtectionStatus.ts

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2023 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import { Progress } from '../sandboxTypes';
+import {
+    DeviceCore,
+    deviceSingleTaskEndOperation,
+    NrfutilDeviceWithSerialnumber,
+} from './common';
+
+type DeviceFamily =
+    | 'NRF51_FAMILY'
+    | 'NRF52_FAMILY'
+    | 'NRF53_FAMILY'
+    | 'NRF91_FAMILY';
+
+type ProtectionStatus =
+    | 'NRFDL_PROTECTION_STATUS_NONE'
+    | 'NRFDL_PROTECTION_STATUS_REGION0'
+    | 'NRFDL_PROTECTION_STATUS_REGION0_REGION1'
+    | 'NRFDL_PROTECTION_STATUS_SECURE_REGIONS'
+    | 'NRFDL_PROTECTION_STATUS_ALL';
+
+export interface GetProtectionStatusResult {
+    core: DeviceCore;
+    deviceFamily?: DeviceFamily;
+    protectionStatus: ProtectionStatus;
+    serialNumber: string;
+}
+
+export default (
+    device: NrfutilDeviceWithSerialnumber,
+    core?: DeviceCore,
+    onProgress?: (progress: Progress) => void,
+    controller?: AbortController
+) =>
+    deviceSingleTaskEndOperation<GetProtectionStatusResult>(
+        device,
+        'protection-get',
+        onProgress,
+        controller,
+        core ? ['--core', core] : []
+    );