@nordicsemiconductor/pc-nrfconnect-shared 88.0.0 → 90.0.0

package/ipc/MetaFiles.ts

@@ -14,10 +14,13 @@ export interface SourceJson {
 export type WithdrawnJson = UrlString[];
 
 export type AppVersions = {
-    [version: string]: {
-        shasum?: string;
-        tarballUrl: UrlString;
-    };
+    [version: string]: AppVersion;
+};
+
+export type AppVersion = {
+    shasum?: string;
+    tarballUrl: UrlString;
+    nrfutilModules?: nrfutilModules;
 };
 
 export interface AppInfo {
@@ -39,6 +42,15 @@ interface ObjectContainingOptionalStrings {
     [index: string]: string | undefined;
 }
 
+interface nrfConnectForDesktop {
+    nrfutil?: nrfutilModules;
+    html?: string;
+}
+
+interface nrfutilModules {
+    [index: string]: string[] | undefined;
+}
+
 export interface PackageJson {
     name: string;
     version: string;
@@ -52,6 +64,7 @@ export interface PackageJson {
     devDependencies?: ObjectContainingOptionalStrings;
     displayName?: string;
     engines?: ObjectContainingOptionalStrings;
+    nrfConnectForDesktop?: nrfConnectForDesktop;
     files?: readonly string[];
     license?: string;
     main?: string;
@@ -61,7 +74,4 @@ export interface PackageJson {
         url: UrlString;
     };
     scripts?: ObjectContainingOptionalStrings;
-    nrfConnectForDesktop?: {
-        html?: string;
-    };
 }

package/nrfutil/device/__mocks__/device.ts

@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) 2023 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+const program = jest.fn();
+const programBuffer = jest.fn();
+const erase = jest.fn();
+const recover = jest.fn();
+const reset = jest.fn();
+const getProtectionStatus = jest.fn();
+const setProtectionStatus = jest.fn();
+const getFwInfo = jest.fn();
+const setMcuState = jest.fn();
+const getCoreInfo = jest.fn();
+const list = jest.fn(() => ({
+    stop: jest.fn(),
+}));
+const firmwareRead = jest.fn();
+const onLogging = jest.fn();
+const setLogLevel = jest.fn();
+const setVerboseLogging = jest.fn();
+const getModuleVersion = jest.fn();
+
+export default {
+    program,
+    programBuffer,
+    erase,
+    recover,
+    reset,
+    getProtectionStatus,
+    setProtectionStatus,
+    getFwInfo,
+    setMcuState,
+    getCoreInfo,
+    list,
+    firmwareRead,
+    onLogging,
+    setLogLevel,
+    setVerboseLogging,
+    getModuleVersion,
+};

package/nrfutil/device/batch.ts

@@ -0,0 +1,219 @@
+/*
+ * Copyright (c) 2023 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import { TaskEnd } from '../sandboxTypes';
+import { BatchOperationWrapper, Callbacks } from './batchTypes';
+import {
+    DeviceCore,
+    getDeviceSandbox,
+    NrfutilDeviceWithSerialnumber,
+    ResetKind,
+} from './common';
+import eraseBatch from './eraseBatch';
+import firmwareReadBatch from './firmwareReadBatch';
+import { DeviceCoreInfo } from './getCoreInfo';
+import getCoreInfoBatch from './getCoreInfoBatch';
+import { FWInfo } from './getFwInfo';
+import getFwInfoBatch from './getFwInfoBatch';
+import { GetProtectionStatusResult } from './getProtectionStatus';
+import getProtectionStatusBatch from './getProtectionStatusBatch';
+import { FirmwareType, ProgrammingOptions } from './program';
+import programBatch from './programBatch';
+import recoverBatch from './recoverBatch';
+import resetBatch from './resetBatch';
+
+type BatchOperationWrapperUnknown = BatchOperationWrapper<unknown, unknown>;
+
+export class Batch {
+    private operations: BatchOperationWrapperUnknown[];
+
+    private collectOperations: {
+        callback: (completedTasks: TaskEnd<unknown>[]) => void;
+        operationId: number;
+        count: number;
+    }[] = [];
+
+    constructor(operations?: BatchOperationWrapperUnknown[]) {
+        this.operations = operations ?? [];
+    }
+
+    public erase(core: DeviceCore, callbacks?: Callbacks) {
+        this.operations.push(
+            eraseBatch(core, { callbacks }) as BatchOperationWrapperUnknown
+        );
+
+        return this;
+    }
+
+    public firmwareRead(core: DeviceCore, callbacks?: Callbacks<Buffer>) {
+        this.operations.push(
+            firmwareReadBatch(core, {
+                callbacks,
+            }) as BatchOperationWrapperUnknown
+        );
+
+        return this;
+    }
+
+    public getCoreInfo(
+        core: DeviceCore,
+        callbacks?: Callbacks<DeviceCoreInfo>
+    ) {
+        this.operations.push(
+            getCoreInfoBatch(core, {
+                callbacks,
+            }) as BatchOperationWrapperUnknown
+        );
+
+        return this;
+    }
+
+    public getFwInfo(core: DeviceCore, callbacks?: Callbacks<FWInfo>) {
+        this.operations.push(
+            getFwInfoBatch(core, {
+                callbacks,
+            }) as BatchOperationWrapperUnknown
+        );
+
+        return this;
+    }
+
+    public getProtectionStatus(
+        core: DeviceCore,
+        callbacks?: Callbacks<GetProtectionStatusResult>
+    ) {
+        this.operations.push(
+            getProtectionStatusBatch(core, {
+                callbacks,
+            }) as BatchOperationWrapperUnknown
+        );
+
+        return this;
+    }
+
+    public program(
+        firmware: FirmwareType,
+        core: DeviceCore,
+        programmingOptions?: ProgrammingOptions,
+        callbacks?: Callbacks
+    ) {
+        this.operations.push(
+            programBatch(firmware, core, {
+                programmingOptions,
+                callbacks,
+            }) as BatchOperationWrapperUnknown
+        );
+
+        return this;
+    }
+
+    public recover(core: DeviceCore, callbacks?: Callbacks) {
+        this.operations.push(
+            recoverBatch(core, { callbacks }) as BatchOperationWrapperUnknown
+        );
+
+        return this;
+    }
+
+    public reset(core: DeviceCore, reset?: ResetKind, callbacks?: Callbacks) {
+        this.operations.push(
+            resetBatch(core, {
+                reset,
+                callbacks,
+            }) as BatchOperationWrapperUnknown
+        );
+
+        return this;
+    }
+
+    public collect(
+        count: number,
+        callback: (completedTasks: TaskEnd<unknown>[]) => void
+    ) {
+        this.collectOperations.push({
+            callback,
+            operationId: this.operations.length - 1,
+            count,
+        });
+
+        return this;
+    }
+
+    public async run(
+        device: NrfutilDeviceWithSerialnumber,
+        controller?: AbortController | undefined
+    ): Promise<unknown[]> {
+        let beginId = 0;
+        let endId = 0;
+        const results: TaskEnd<unknown>[] = [];
+
+        const operations = {
+            operations: this.operations.map((operation, index) => ({
+                operationId: index.toString(),
+                ...operation.operation,
+            })),
+        };
+
+        const sandbox = await getDeviceSandbox();
+        try {
+            await sandbox.execSubcommand<unknown>(
+                'execute-batch',
+                [
+                    '--serial-number',
+                    device.serialNumber,
+                    '--batch-json',
+                    JSON.stringify(operations),
+                ],
+                (progress, task) => {
+                    if (task) {
+                        this.operations[endId].onProgress?.(progress, task);
+                    }
+                },
+                onTaskBegin => {
+                    beginId += 1;
+                    this.operations[endId].onTaskBegin?.(onTaskBegin);
+                },
+                taskEnd => {
+                    results.push(taskEnd);
+
+                    this.operations[endId].onTaskEnd?.(taskEnd);
+
+                    this.collectOperations
+                        .filter(operation => operation.operationId === endId)
+                        .forEach(operation => {
+                            operation.callback(
+                                results.slice(
+                                    results.length - operation.count,
+                                    results.length
+                                )
+                            );
+                        });
+
+                    endId += 1;
+                },
+                controller
+            );
+
+            const errors = results.filter(result => result.result === 'fail');
+            if (errors.length > 0) {
+                const error = new Error(
+                    `Batch failed: ${errors
+                        .map(e => `error: ${e.error}, message: ${e.message}`)
+                        .join('\n')}`
+                );
+                this.operations[endId].onException?.(error);
+                throw error;
+            }
+        } catch (error) {
+            if (beginId !== endId) {
+                this.operations[beginId].onException?.(error as Error);
+            }
+            throw error;
+        }
+
+        return results.map(result => result.data);
+    }
+}

package/nrfutil/device/batchTypes.ts

@@ -0,0 +1,133 @@
+/*
+ * Copyright (c) 2023 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import { Progress, Task, TaskBegin, TaskEnd } from '../sandboxTypes';
+import { DeviceCore, ResetKind } from './common';
+import {
+    isJLinkProgrammingOptions,
+    isMcuBootProgrammingOptions,
+    isNordicDfuProgrammingOptions,
+    ProgrammingOptions,
+} from './program';
+
+export interface BatchOperationWrapper<OperationType, T = void> {
+    operation: GenericOperation<OperationType>;
+    onProgress?: (progress: Progress, task?: Task) => void;
+    onTaskBegin?: TaskBeginCallback;
+    onTaskEnd?: TaskEndCallback<T>;
+    onException?: (error: Error) => void;
+}
+
+export type Callbacks<T = void> = {
+    onTaskBegin?: TaskBeginCallback;
+    onTaskEnd?: TaskEndCallback<T>;
+    onProgress?: (progress: Progress, task?: Task) => void;
+    onException?: (error: Error) => void;
+};
+
+export type DeviceCoreBatch =
+    | 'NRFDL_DEVICE_CORE_APPLICATION'
+    | 'NRFDL_DEVICE_CORE_NETWORK'
+    | 'NRFDL_DEVICE_CORE_MODEM';
+
+export const convertDeviceCoreType = (core?: DeviceCore) => {
+    switch (core) {
+        case 'Application':
+            return 'NRFDL_DEVICE_CORE_APPLICATION';
+        case 'Network':
+            return 'NRFDL_DEVICE_CORE_NETWORK';
+        case 'Modem':
+            return 'NRFDL_DEVICE_CORE_MODEM';
+    }
+};
+
+export const convertProgrammingOptionsType = (
+    programmingOptions?: ProgrammingOptions
+) => {
+    if (!programmingOptions) {
+        return undefined;
+    }
+
+    if (isJLinkProgrammingOptions(programmingOptions)) {
+        return {
+            qspi_erase_mode: programmingOptions.chipEraseMode,
+            reset: programmingOptions.reset,
+            verify: programmingOptions.verify,
+        };
+    }
+
+    if (isMcuBootProgrammingOptions(programmingOptions)) {
+        return {
+            mcu_end_state: programmingOptions.mcuEndState,
+            net_core_upload_delay: programmingOptions.netCoreUploadDelay,
+        };
+    }
+
+    if (isNordicDfuProgrammingOptions(programmingOptions)) {
+        return {
+            mcu_end_state: programmingOptions.mcuEndState,
+        };
+    }
+};
+
+export interface ProgrammingOperation {
+    type: 'program';
+    firmware: {
+        file: string;
+    };
+    reset?: ResetKind;
+}
+
+export interface ResetOperation {
+    type: 'reset';
+    option?: ResetKind;
+}
+
+export interface RecoverOperation {
+    type: 'recover';
+}
+
+export interface ProtectionGetOperation {
+    type: 'protection-get';
+}
+
+export interface FirmwareReadOperation {
+    type: 'fw-read';
+    firmware: {
+        buffer: string;
+    };
+}
+
+export interface EraseOperation {
+    type: 'erase';
+}
+
+export interface GetCoreInfoOperation {
+    type: 'core-info';
+}
+
+export interface GetFwInfoOperation {
+    type: 'fw-info';
+}
+
+export interface GenericOperation<T> {
+    core?: DeviceCoreBatch;
+    operationId?: string;
+    operation: T;
+}
+
+export type BatchOperation =
+    | ProgrammingOperation
+    | ResetOperation
+    | RecoverOperation
+    | ProtectionGetOperation
+    | FirmwareReadOperation
+    | EraseOperation
+    | GetCoreInfoOperation
+    | GetFwInfoOperation;
+
+export type TaskEndCallback<T = void> = (end: TaskEnd<T>) => void;
+export type TaskBeginCallback = (begin: TaskBegin) => void;

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]
+    );
+};