@nordicsemiconductor/pc-nrfconnect-shared 89.0.0 → 91.0.0

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

package/nrfutil/device/program.ts

@@ -0,0 +1,186 @@
+/*
+ * Copyright (c) 2023 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { v4 as uuid } from 'uuid';
+
+import { Progress } from '../sandboxTypes';
+import {
+    DeviceCore,
+    deviceSingleTaskEndOperationVoid,
+    DeviceTraits,
+    NrfutilDeviceWithSerialnumber,
+    ResetKind,
+} from './common';
+
+export type FileExtensions = 'zip' | 'hex';
+export type FirmwareType = { buffer: Buffer; type: FileExtensions } | string;
+
+export type ProgrammingOptions =
+    | JLinkProgrammingOptions
+    | McuBootProgrammingOptions
+    | NordicDfuProgrammingOptions;
+
+export interface JLinkProgrammingOptions {
+    chipEraseMode?: 'ERASE_ALL' | 'ERASE_NONE';
+    reset?: ResetKind;
+    verify?: 'VERIFY_HASH' | 'VERIFY_NONE' | 'VERIFY_READ';
+}
+
+export interface McuBootProgrammingOptions {
+    mcuEndState?: 'NRFDL_MCU_STATE_APPLICATION' | 'NRFDL_MCU_STATE_PROGRAMMING';
+    netCoreUploadDelay?: number;
+}
+
+export interface NordicDfuProgrammingOptions {
+    mcuEndState?: 'NRFDL_MCU_STATE_APPLICATION' | 'NRFDL_MCU_STATE_PROGRAMMING';
+}
+
+export const isJLinkProgrammingOptions = (
+    options: ProgrammingOptions
+): options is JLinkProgrammingOptions =>
+    (options as JLinkProgrammingOptions).chipEraseMode !== undefined;
+
+export const isMcuBootProgrammingOptions = (
+    options: ProgrammingOptions
+): options is McuBootProgrammingOptions =>
+    (options as McuBootProgrammingOptions).netCoreUploadDelay !== undefined;
+
+export const isNordicDfuProgrammingOptions = (
+    options: ProgrammingOptions
+): options is NordicDfuProgrammingOptions =>
+    !isMcuBootProgrammingOptions(options) &&
+    (options as NordicDfuProgrammingOptions).mcuEndState !== undefined;
+
+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;
+};
+
+const programmingOptionsToArgs = (options?: ProgrammingOptions) => {
+    if (!options) return [];
+
+    const args: string[] = [];
+
+    if (isJLinkProgrammingOptions(options)) {
+        if (options.chipEraseMode)
+            args.push(`chip_erase_mode=${options.chipEraseMode}`);
+        if (options.reset) args.push(`reset=${options.reset}`);
+        if (options.verify) args.push(`verify=${options.verify}`);
+    } else if (isMcuBootProgrammingOptions(options)) {
+        if (options.mcuEndState)
+            args.push(`mcu_end_state=${options.mcuEndState}`);
+        if (options.netCoreUploadDelay)
+            args.push(
+                `net_core_upload_delay=${Math.round(
+                    options.netCoreUploadDelay
+                )}`
+            );
+    } else if (isNordicDfuProgrammingOptions(options)) {
+        if (options.mcuEndState)
+            args.push(`mcu_end_state=${options.mcuEndState}`);
+    }
+
+    return args.length > 0 ? ['--options', `${args.join(',')}`] : [];
+};
+const program = (
+    device: NrfutilDeviceWithSerialnumber,
+    firmwarePath: string,
+    onProgress?: (progress: Progress) => void,
+    core?: DeviceCore,
+    programmingOptions?: ProgrammingOptions,
+    controller?: AbortController
+) =>
+    deviceSingleTaskEndOperationVoid(
+        device,
+        'program',
+        onProgress,
+        controller,
+        [
+            '--firmware',
+            firmwarePath,
+            ...deviceTraitsToArgs(device.traits),
+            ...(core ? ['--core', core] : []),
+            ...programmingOptionsToArgs(programmingOptions),
+        ]
+    );
+
+const programBuffer = async (
+    device: NrfutilDeviceWithSerialnumber,
+    firmware: Buffer,
+    type: FileExtensions,
+    onProgress?: (progress: Progress) => void,
+    core?: DeviceCore,
+    programmingOptions?: ProgrammingOptions,
+    controller?: AbortController
+) => {
+    const saveTemp = (): string => {
+        let tempFilePath;
+        do {
+            tempFilePath = path.join(os.tmpdir(), `${uuid()}.${type}`);
+        } while (fs.existsSync(tempFilePath));
+
+        fs.writeFileSync(tempFilePath, firmware);
+
+        return tempFilePath;
+    };
+
+    const tempFilePath = saveTemp();
+    try {
+        await program(
+            device,
+            tempFilePath,
+            onProgress,
+            core,
+            programmingOptions,
+            controller
+        );
+    } catch (error) {
+        fs.unlinkSync(tempFilePath);
+    }
+};
+
+export default async (
+    device: NrfutilDeviceWithSerialnumber,
+    firmware: FirmwareType,
+    onProgress?: (progress: Progress) => void,
+    core?: DeviceCore,
+    programmingOptions?: ProgrammingOptions,
+    controller?: AbortController
+) => {
+    if (typeof firmware === 'string') {
+        await program(
+            device,
+            firmware,
+            onProgress,
+            core,
+            programmingOptions,
+            controller
+        );
+    } else {
+        await programBuffer(
+            device,
+            firmware.buffer,
+            firmware.type,
+            onProgress,
+            core,
+            programmingOptions,
+            controller
+        );
+    }
+};

package/nrfutil/device/programBatch.ts

@@ -0,0 +1,69 @@
+/*
+ * Copyright (c) 2023 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { v4 as uuid } from 'uuid';
+
+import {
+    BatchOperationWrapper,
+    Callbacks,
+    convertDeviceCoreType,
+    convertProgrammingOptionsType,
+    ProgrammingOperation,
+} from './batchTypes';
+import { DeviceCore } from './common';
+import { FirmwareType, ProgrammingOptions } from './program';
+
+const program = (
+    firmware: string,
+    core: DeviceCore,
+    optionals?: {
+        programmingOptions?: ProgrammingOptions;
+        callbacks?: Callbacks;
+    }
+): BatchOperationWrapper<ProgrammingOperation> => ({
+    operation: {
+        core: convertDeviceCoreType(core),
+        operation: {
+            type: 'program',
+            firmware: {
+                file: firmware,
+            },
+            ...convertProgrammingOptionsType(optionals?.programmingOptions),
+        },
+    },
+    ...optionals?.callbacks,
+});
+
+export default (
+    firmware: FirmwareType,
+    core: DeviceCore,
+    optionals?: {
+        programmingOptions?: ProgrammingOptions;
+        callbacks?: Callbacks;
+    }
+) => {
+    if (typeof firmware === 'string') {
+        return program(firmware, core, optionals);
+    }
+
+    const saveTemp = (): string => {
+        let tempFilePath;
+        do {
+            tempFilePath = path.join(os.tmpdir(), `${uuid()}.${firmware.type}`);
+        } while (fs.existsSync(tempFilePath));
+
+        fs.writeFileSync(tempFilePath, firmware.buffer);
+
+        return tempFilePath;
+    };
+
+    const tempFilePath = saveTemp();
+
+    return program(tempFilePath, core, optionals);
+};

package/nrfutil/device/recover.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,
+        'recover',
+        onProgress,
+        controller,
+        core ? ['--core', core] : []
+    );

package/nrfutil/device/recoverBatch.ts

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

package/nrfutil/device/reset.ts

@@ -0,0 +1,41 @@
+/*
+ * Copyright (c) 2023 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import { Progress } from '../sandboxTypes';
+import {
+    DeviceCore,
+    deviceSingleTaskEndOperationVoid,
+    NrfutilDeviceWithSerialnumber,
+    ResetKind,
+} from './common';
+
+export default async (
+    device: NrfutilDeviceWithSerialnumber,
+    core?: DeviceCore,
+    resetKind?: ResetKind,
+    onProgress?: (progress: Progress) => void,
+    controller?: AbortController
+) => {
+    const args: string[] = [];
+
+    if (resetKind) {
+        args.push('--reset-kind');
+        args.push(resetKind);
+    }
+
+    if (core) {
+        args.push('--core');
+        args.push(core);
+    }
+
+    await deviceSingleTaskEndOperationVoid(
+        device,
+        'reset',
+        onProgress,
+        controller,
+        args
+    );
+};

package/nrfutil/device/resetBatch.ts

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

package/nrfutil/device/setMcuState.ts

@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) 2023 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import { Progress } from '../sandboxTypes';
+import {
+    deviceSingleTaskEndOperationVoid,
+    NrfutilDeviceWithSerialnumber,
+} from './common';
+
+export type McuState = 'Application' | 'Programming';
+
+export default (
+    device: NrfutilDeviceWithSerialnumber,
+    state: McuState,
+    onProgress?: (progress: Progress) => void,
+    controller?: AbortController
+) =>
+    deviceSingleTaskEndOperationVoid(
+        device,
+        'mcu-state-set',
+        onProgress,
+        controller,
+        [state]
+    );

package/nrfutil/device/setProtectionStatus.ts

@@ -0,0 +1,27 @@
+/*
+ * 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,
+    region: 'All' | 'SecureRegions' | 'Region0' | 'Region0Region1',
+    core?: DeviceCore,
+    onProgress?: (progress: Progress) => void,
+    controller?: AbortController
+) =>
+    deviceSingleTaskEndOperationVoid(
+        device,
+        'protection-set',
+        onProgress,
+        controller,
+        [region, ...(core ? ['--core', core] : [])]
+    );

package/nrfutil/index.ts

@@ -0,0 +1,25 @@
+/*
+ * Copyright (c) 2015 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+export { default as NrfutilDeviceLib } from './device/device';
+
+export type {
+    DeviceCore,
+    DeviceTraits,
+    ProtectionStatus,
+    SerialPort as DeviceSerialPort,
+    NrfutilDevice,
+} from './device/common';
+
+export type { DeviceCoreInfo } from './device/getCoreInfo';
+export type { ImageType } from './device/getFwInfo';
+
+export { default as prepareSandbox } from './sandbox';
+export { NrfutilSandbox } from './sandbox';
+export type { Progress, SemanticVersion } from './sandboxTypes';
+export type { Batch as DeviceBatch } from './device/batch';
+export type { Callbacks as BatchCallbacks } from './device/batchTypes';
+export type { GetProtectionStatusResult } from './device/getProtectionStatus';

package/nrfutil/moduleVersion.ts

@@ -0,0 +1,57 @@
+/*
+ * Copyright (c) 2023 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import {
+    Dependency,
+    isIncrementalVersion,
+    isSemanticVersion,
+    isStringVersion,
+    SubDependency,
+} from './sandboxTypes';
+
+export const describeVersion = (version?: SubDependency | string) => {
+    if (typeof version === 'string') {
+        return version;
+    }
+
+    if (isSemanticVersion(version)) {
+        return `${version.version.major}.${version.version.minor}.${version.version.patch}`;
+    }
+
+    if (isIncrementalVersion(version) || isStringVersion(version)) {
+        return String(version.version);
+    }
+
+    return 'Unknown';
+};
+
+type KnownModule = 'nrfdl' | 'jprog' | 'JlinkARM';
+
+const findTopLevel = (module: KnownModule, dependencies: Dependency[]) =>
+    dependencies.find(dependency => dependency.name === module);
+
+const findInDependencies = (
+    module: KnownModule,
+    dependencies: Dependency[]
+) => {
+    if (dependencies.length > 0) {
+        return resolveModuleVersion(
+            module,
+            dependencies.flatMap(dependency => [
+                ...(dependency.dependencies ?? []),
+                ...(dependency.plugins?.flatMap(
+                    plugin => plugin.dependencies
+                ) ?? []),
+            ])
+        );
+    }
+};
+
+export const resolveModuleVersion = (
+    module: KnownModule,
+    versions: Dependency[] = []
+): Dependency | SubDependency | undefined =>
+    findTopLevel(module, versions) ?? findInDependencies(module, versions);

package/nrfutil/nrfutilLogger.ts

@@ -0,0 +1,15 @@
+/*
+ * Copyright (c) 2023 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import winston from 'winston';
+
+let nrfutilLogger: winston.Logger | undefined;
+
+export const setNrfutilLogger = (logger: winston.Logger) => {
+    nrfutilLogger = logger;
+};
+
+export const getNrfutilLogger = () => nrfutilLogger;