@nordicsemiconductor/pc-nrfconnect-shared 89.0.0 → 90.0.0

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

package/nrfutil/device/getProtectionStatusBatch.ts

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

package/nrfutil/device/list.ts

@@ -0,0 +1,81 @@
+/*
+ * Copyright (c) 2023 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import {
+    DeviceTraits,
+    deviceTraitsToArgs,
+    getDeviceSandbox,
+    NrfutilDevice,
+    NrfutilDeviceWithSerialnumber,
+} from './common';
+
+export interface HotplugEvent {
+    id: number;
+    event: 'Arrived' | 'Left';
+    device?: NrfutilDevice;
+}
+
+export interface ListEvent {
+    devices: NrfutilDevice[];
+}
+
+const isListEvent = (event: HotplugEvent | ListEvent): event is ListEvent =>
+    (event as ListEvent).devices !== undefined;
+
+const isHotplugEvent = (
+    event: HotplugEvent | ListEvent
+): event is HotplugEvent => (event as HotplugEvent).event !== undefined;
+
+export default async (
+    traits: DeviceTraits,
+    onEnumerated: (devices: NrfutilDeviceWithSerialnumber[]) => void,
+    onError: (error: Error) => void,
+    onHotplugEvent?: {
+        onDeviceArrived: (device: NrfutilDeviceWithSerialnumber) => void;
+        onDeviceLeft: (id: number) => void;
+    }
+) => {
+    const args: string[] = [];
+    args.concat(deviceTraitsToArgs(traits));
+
+    if (onHotplugEvent) {
+        args.push('--hotplug');
+    }
+
+    const onData = (data: HotplugEvent | ListEvent) => {
+        if (isListEvent(data)) {
+            onEnumerated(
+                data.devices.filter(
+                    d => d.serialNumber
+                ) as NrfutilDeviceWithSerialnumber[]
+            );
+
+            return;
+        }
+
+        if (!onHotplugEvent || !isHotplugEvent(data)) {
+            return;
+        }
+
+        if (
+            data.event === 'Arrived' &&
+            data.device &&
+            data.device.serialNumber
+        ) {
+            onHotplugEvent.onDeviceArrived(
+                data.device as NrfutilDeviceWithSerialnumber
+            );
+        } else if (data.event === 'Left') {
+            onHotplugEvent.onDeviceLeft(data.id);
+        }
+    };
+
+    const sandbox = await getDeviceSandbox();
+    return sandbox.execBackgroundSubcommand<HotplugEvent>('list', args, {
+        onData,
+        onError,
+    });
+};