@nordicsemiconductor/pc-nrfconnect-shared 189.0.0 → 191.0.0

package/Changelog.md

@@ -7,6 +7,30 @@ This project does _not_ adhere to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html) but contrary to it
 every new version is a new major version.
 
+## 191.0.0 - 2024-11-14
+
+### Added
+
+-   Function `getJlinkCompatibility`.
+
+### Changed
+
+-   nrfutil: The core gets upgraded before installing a command.
+-   nrfutil: The `version` properties of dependencies are now optional,
+    reflecting the behaviour since `nrfutil-device` v2.7.0.
+-   Warning for J-Link versions: Only inform (not warn) if the installed version
+    is newer than the tested version. Updated the text for all cases.
+
+### Removed
+
+-   Export of internal type `SemanticVersion`.
+
+## 190.0.0 - 2024-11-06
+
+### Added
+
+-   Added `Thingy91:X` to known devices.
+
 ## 189.0.0 - 2024-10-18
 
 ### Added

package/ipc/MetaFiles.ts

@@ -54,9 +54,6 @@ const nrfutilModuleVersion = semver;
 export type NrfutilModuleName = z.infer<typeof nrfutilModuleName>;
 export type NrfutilModuleVersion = z.infer<typeof nrfutilModuleVersion>;
 
-export const nrfModules = z.record(
-    nrfutilModuleName,
-    nrfutilModuleVersion.array().nonempty()
-);
+export const nrfModules = z.record(nrfutilModuleName, z.tuple([semver]));
 
 export type NrfutilModules = z.infer<typeof nrfModules>;

package/ipc/apps.ts

@@ -5,7 +5,7 @@
  */
 
 import { handle, invoke } from './infrastructure/rendererToMain';
-import { AppVersions, UrlString } from './MetaFiles';
+import type { AppVersions, NrfutilModules, UrlString } from './MetaFiles';
 import { LOCAL, Source, SourceName } from './sources';
 
 export interface AppSpec {
@@ -33,6 +33,7 @@ interface Installed {
     engineVersion?: string;
     repositoryUrl?: UrlString;
     html?: string;
+    nrfutil?: NrfutilModules;
     installed: {
         publishTimestamp?: string;
         path: string;

package/nrfutil/device/logLibVersions.ts

@@ -8,21 +8,23 @@ import { spawn } from 'child_process';
 import os from 'os';
 
 import describeError from '../../src/logging/describeError';
-import {
-    describeVersion,
-    getExpectedVersion,
-    resolveModuleVersion,
-} from '../moduleVersion';
+import { getJlinkCompatibility } from '../jlinkVersion';
+import { describeVersion, findDependency } from '../moduleVersion';
 import { getNrfutilLogger } from '../nrfutilLogger';
-import type { ModuleVersion, SubDependency } from '../sandboxTypes';
+import type { Dependency, ModuleVersion } from '../sandboxTypes';
 
-const log = (description: string, moduleVersion?: SubDependency | string) => {
+const log = (
+    description: string,
+    dependencyOrVersion?: Dependency | string
+) => {
     const logger = getNrfutilLogger();
-    if (moduleVersion == null) {
+    if (dependencyOrVersion == null) {
         logger?.warn(`Unable to detect version of ${description}.`);
     } else {
         logger?.info(
-            `Using ${description} version: ${describeVersion(moduleVersion)}`
+            `Using ${description} version: ${describeVersion(
+                dependencyOrVersion
+            )}`
         );
     }
 };
@@ -75,24 +77,37 @@ export default async (moduleVersion: ModuleVersion) => {
         const dependencies = moduleVersion.dependencies;
 
         log('nrfutil-device', moduleVersion.version);
-        log('nrf-device-lib', resolveModuleVersion('nrfdl', dependencies));
-        log('nrfjprog DLL', resolveModuleVersion('jprog', dependencies));
-        log('JLink', resolveModuleVersion('JlinkARM', dependencies));
+        log('nrf-device-lib', findDependency('nrfdl', dependencies));
+        log('nrfjprog DLL', findDependency('jprog', dependencies));
+        log('JLink', findDependency('JlinkARM', dependencies));
 
-        const jlinkVersion = resolveModuleVersion('JlinkARM', dependencies);
+        const jlinkCompatibility = getJlinkCompatibility(moduleVersion);
 
-        if (jlinkVersion) {
-            const result = getExpectedVersion(jlinkVersion);
-            if (!result.isExpectedVersion) {
+        switch (jlinkCompatibility.kind) {
+            case 'No J-Link installed':
                 logger?.warn(
-                    `Installed JLink version does not match the expected version (${result.expectedVersion})`
+                    `SEGGER J-Link is not installed. ` +
+                        `Install at least version ${jlinkCompatibility.requiredJlink} ` +
+                        `from https://www.segger.com/downloads/jlink`
                 );
-            }
-        } else {
-            logger?.warn(
-                `JLink is not installed. Please install JLink from: https://www.segger.com/downloads/jlink`
-            );
+                break;
+            case 'Outdated J-Link':
+                logger?.warn(
+                    `Outdated SEGGER J-Link. Your version of SEGGER J-Link (${jlinkCompatibility.actualJlink}) ` +
+                        `is older than the one this app was tested with (${jlinkCompatibility.requiredJlink}). ` +
+                        `Install the newer version from https://www.segger.com/downloads/jlink`
+                );
+                break;
+            case 'Newer J-Link is used':
+                logger?.info(
+                    `Your version of SEGGER J-Link (${jlinkCompatibility.actualJlink}) ` +
+                        `is newer than the one this app was tested with (${jlinkCompatibility.requiredJlink}). ` +
+                        `The tested version is not required, and your J-Link version will most likely work fine.` +
+                        ` If you get issues related to J-Link with your devices, use the tested version.`
+                );
+                break;
         }
+
         if (
             process.platform === 'darwin' &&
             os.cpus()[0].model.includes('Apple')

package/nrfutil/index.ts

@@ -6,7 +6,7 @@
 
 export { default as prepareSandbox } from './sandbox';
 export { NrfutilSandbox } from './sandbox';
-export type { Progress, SemanticVersion } from './sandboxTypes';
+export type { Progress } from './sandboxTypes';
 export { getNrfutilLogger, setNrfutilLogger } from './nrfutilLogger';
 export {
     getModule,
@@ -14,3 +14,4 @@ export {
     setVerboseLogging,
     getAllModuleVersions,
 } from './modules';
+export { getJlinkCompatibility } from './jlinkVersion';

package/nrfutil/jlinkVersion.test.ts

@@ -0,0 +1,323 @@
+/*
+ * Copyright (c) 2024 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import {
+    convertToSemver,
+    existingIsOlderThanExpected,
+    getJlinkCompatibility,
+    hasExpectedVersionFormat,
+    strippedVersionName,
+} from './jlinkVersion';
+import type { Dependency, ModuleVersion } from './sandboxTypes';
+
+// Note: In this test the space at the end of 'JLink_V7.96 ' or '7.96 ' is
+// intentional because it is also reported like that by nrfutil.
+
+test('strippedVersionName', () => {
+    expect(
+        strippedVersionName({
+            version: '7.94i',
+            versionFormat: 'string',
+        })
+    ).toBe('7.94i');
+    expect(
+        strippedVersionName({
+            version: '7.96 ',
+            versionFormat: 'string',
+        })
+    ).toBe('7.96');
+});
+
+describe('expectedFormat', () => {
+    it('fails if the version format is not string', () => {
+        expect(
+            hasExpectedVersionFormat(
+                {
+                    version: 18,
+                    versionFormat: 'incremental',
+                },
+                false
+            )
+        ).toBe(false);
+
+        expect(
+            hasExpectedVersionFormat(
+                {
+                    version: { major: 1, minor: 2, patch: 3 },
+                    versionFormat: 'semantic',
+                },
+                false
+            )
+        ).toBe(false);
+    });
+
+    it('fails if the content is unexpected', () => {
+        const noJlinkPrefix = {
+            version: '7.94i',
+            versionFormat: 'string',
+        } as const;
+        expect(hasExpectedVersionFormat(noJlinkPrefix, false)).toBe(false);
+
+        const wrongCasing = {
+            version: 'jlink_v7.96',
+            versionFormat: 'string',
+        } as const;
+        expect(hasExpectedVersionFormat(wrongCasing, false)).toBe(false);
+
+        const unexpectedPostfix = {
+            version: 'JLink_V7.96-beta',
+            versionFormat: 'string',
+        } as const;
+        expect(hasExpectedVersionFormat(unexpectedPostfix, false)).toBe(false);
+    });
+
+    it('succeeds for expected content', () => {
+        expect(
+            hasExpectedVersionFormat(
+                {
+                    version: 'JLink_V7.94i',
+                    versionFormat: 'string',
+                },
+                false
+            )
+        ).toBe(true);
+        expect(
+            hasExpectedVersionFormat(
+                {
+                    version: 'JLink_V7.96 ',
+                    versionFormat: 'string',
+                },
+                false
+            )
+        ).toBe(true);
+        expect(
+            hasExpectedVersionFormat(
+                {
+                    version: 'JLink_V8.10',
+                    versionFormat: 'string',
+                },
+                false
+            )
+        ).toBe(true);
+    });
+});
+
+test('convertToSemver', () => {
+    expect(
+        convertToSemver({ version: 'JLink_V7.94', versionFormat: 'string' })
+    ).toBe('7.94.0');
+    expect(
+        convertToSemver({ version: 'JLink_V7.96 ', versionFormat: 'string' })
+    ).toBe('7.96.0');
+    expect(
+        convertToSemver({ version: 'JLink_V7.98a', versionFormat: 'string' })
+    ).toBe('7.98.1');
+    expect(
+        convertToSemver({ version: 'JLink_V8.10b', versionFormat: 'string' })
+    ).toBe('8.10.2');
+});
+
+describe('existingIsOlderThanExpected', () => {
+    const version794i = {
+        version: 'JLink_V7.94i',
+        versionFormat: 'string',
+    } as const;
+    const version794k = {
+        version: 'JLink_V7.94k',
+        versionFormat: 'string',
+    } as const;
+    const version796 = {
+        version: 'JLink_V7.96 ',
+        versionFormat: 'string',
+    } as const;
+    const version810b = {
+        version: 'JLink_V8.10b',
+        versionFormat: 'string',
+    } as const;
+
+    it('is false if no expected is specified', () => {
+        expect(
+            existingIsOlderThanExpected({ ...version794i, name: 'JlinkARM' })
+        ).toBe(false);
+    });
+    it('is false if the actual is equal the expected', () => {
+        expect(
+            existingIsOlderThanExpected({
+                ...version794i,
+                name: 'JlinkARM',
+                expectedVersion: version794i,
+            })
+        ).toBe(false);
+    });
+    it('is false if the actual is newer than the expected', () => {
+        expect(
+            existingIsOlderThanExpected({
+                ...version794k,
+                name: 'JlinkARM',
+                expectedVersion: version794i,
+            })
+        ).toBe(false);
+        expect(
+            existingIsOlderThanExpected({
+                ...version796,
+                name: 'JlinkARM',
+                expectedVersion: version794i,
+            })
+        ).toBe(false);
+        expect(
+            existingIsOlderThanExpected({
+                ...version810b,
+                name: 'JlinkARM',
+                expectedVersion: version794i,
+            })
+        ).toBe(false);
+    });
+
+    it('is true if the actual is older than the expected', () => {
+        expect(
+            existingIsOlderThanExpected({
+                ...version794i,
+                name: 'JlinkARM',
+                expectedVersion: version794k,
+            })
+        ).toBe(true);
+        expect(
+            existingIsOlderThanExpected({
+                ...version794i,
+                name: 'JlinkARM',
+                expectedVersion: version796,
+            })
+        ).toBe(true);
+        expect(
+            existingIsOlderThanExpected({
+                ...version794i,
+                name: 'JlinkARM',
+                expectedVersion: version810b,
+            })
+        ).toBe(true);
+    });
+});
+
+describe('getJlinkCompatibility', () => {
+    const createModuleVersion = (
+        ...dependencies: Dependency[]
+    ): ModuleVersion => ({
+        classification: 'nrf-external',
+        name: 'nrfutil-device',
+        version: '2.5.0',
+        build_timestamp: '',
+        commit_date: '',
+        commit_hash: '',
+        dependencies: [
+            {
+                classification: 'nrf-external',
+                name: 'nrfdl',
+                versionFormat: 'semantic',
+                version: {
+                    major: 0,
+                    minor: 17,
+                    patch: 38,
+                },
+                dependencies,
+            },
+        ],
+        host: '',
+    });
+
+    it(`Reports no installed J-Link for for module versions reported by nrfutil-device before v2.7`, () => {
+        expect(getJlinkCompatibility(createModuleVersion())).toEqual({
+            kind: 'No J-Link installed',
+            requiredJlink: '7.94e',
+            actualJlink: 'none',
+        });
+    });
+
+    it(`Reports no installed J-Link for for module versions reported by nrfutil-device since v2.7`, () => {
+        expect(
+            getJlinkCompatibility(
+                createModuleVersion({
+                    name: 'JlinkARM',
+                    expectedVersion: {
+                        versionFormat: 'string',
+                        version: 'JLink_V8.10f',
+                    },
+                })
+            )
+        ).toEqual({
+            kind: 'No J-Link installed',
+            requiredJlink: '8.10f',
+            actualJlink: 'none',
+        });
+    });
+
+    it(`Reports an outdated J-Link version`, () => {
+        expect(
+            getJlinkCompatibility(
+                createModuleVersion({
+                    name: 'JlinkARM',
+                    version: 'JLink_V7.94e',
+                    versionFormat: 'string',
+                    expectedVersion: {
+                        version: 'JLink_V7.94i',
+                        versionFormat: 'string',
+                    },
+                })
+            )
+        ).toEqual({
+            kind: 'Outdated J-Link',
+            requiredJlink: '7.94i',
+            actualJlink: '7.94e',
+        });
+    });
+
+    it(`Reports a newer J-Link version is used`, () => {
+        expect(
+            getJlinkCompatibility(
+                createModuleVersion({
+                    name: 'JlinkARM',
+                    version: 'JLink_V8.10f',
+                    versionFormat: 'string',
+                    expectedVersion: {
+                        version: 'JLink_V7.94i',
+                        versionFormat: 'string',
+                    },
+                })
+            )
+        ).toEqual({
+            kind: 'Newer J-Link is used',
+            requiredJlink: '7.94i',
+            actualJlink: '8.10f',
+        });
+    });
+
+    it(`Reports the tested J-Link version is used`, () => {
+        expect(
+            getJlinkCompatibility(
+                createModuleVersion({
+                    name: 'JlinkARM',
+                    version: 'JLink_V7.94i',
+                    versionFormat: 'string',
+                    expectedVersion: {
+                        version: 'JLink_V7.94i',
+                        versionFormat: 'string',
+                    },
+                })
+            )
+        ).toEqual({ kind: 'Tested J-Link is used' });
+    });
+
+    it(`Reports the tested J-Link version is used by specifying no expected version`, () => {
+        expect(
+            getJlinkCompatibility(
+                createModuleVersion({
+                    name: 'JlinkARM',
+                    version: 'JLink_V7.94i',
+                    versionFormat: 'string',
+                })
+            )
+        ).toEqual({ kind: 'Tested J-Link is used' });
+    });
+});

package/nrfutil/jlinkVersion.ts

@@ -0,0 +1,144 @@
+/*
+ * Copyright (c) 2024 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import semver from 'semver';
+
+import { findDependency } from './moduleVersion';
+import {
+    type Dependency,
+    hasVersion,
+    type ModuleVersion,
+} from './sandboxTypes';
+import {
+    type DiscriminatedVersion,
+    isStringVersion,
+    versionToString,
+} from './version';
+
+export const strippedVersionName = (version: DiscriminatedVersion) =>
+    versionToString(version).trim().replace('JLink_V', '');
+
+export const hasExpectedVersionFormat = (
+    dependency: Dependency | DiscriminatedVersion,
+    logFailure = true
+): dependency is DiscriminatedVersion => {
+    if (!hasVersion(dependency)) return false;
+
+    const jlinkVersionRegex = /^JLink_V\d+\.\d+[a-z]?$/;
+    const result =
+        isStringVersion(dependency) &&
+        versionToString(dependency).trim().match(jlinkVersionRegex) != null;
+
+    if (!result && logFailure) {
+        console.error(
+            `The J-Link version was not reported in the expected format. ` +
+                `Format: ${dependency.versionFormat}, ` +
+                `version: ${JSON.stringify(dependency)}, `
+        );
+    }
+
+    return result;
+};
+
+export const convertToSemver = (version: DiscriminatedVersion) => {
+    const [, majorMinor, patchLetter] =
+        strippedVersionName(version).match(/(\d\.\d+)(.)?/) ?? [];
+
+    const patch = patchLetter
+        ? patchLetter.charCodeAt(0) - 'a'.charCodeAt(0) + 1
+        : 0;
+
+    return `${majorMinor}.${patch}`;
+};
+
+export const existingIsOlderThanExpected = (
+    jlinkVersionDependency: Dependency
+) => {
+    if (
+        jlinkVersionDependency.expectedVersion == null ||
+        !hasExpectedVersionFormat(jlinkVersionDependency) ||
+        !hasExpectedVersionFormat(jlinkVersionDependency.expectedVersion)
+    )
+        return false;
+
+    return semver.lt(
+        convertToSemver(jlinkVersionDependency),
+        convertToSemver(jlinkVersionDependency.expectedVersion)
+    );
+};
+
+const nrfutilDeviceToJLink = (nrfutilDeviceVersion: string) => {
+    // According to https://docs.nordicsemi.com/bundle/nrfutil/page/guides/installing.html#prerequisites
+    if (semver.lt(nrfutilDeviceVersion, '2.0.0')) {
+        return '7.80c';
+    }
+
+    if (semver.lt(nrfutilDeviceVersion, '2.1.0')) {
+        return '7.88j';
+    }
+
+    if (semver.lt(nrfutilDeviceVersion, '2.5.4')) {
+        return '7.94e';
+    }
+
+    return '7.94i';
+};
+
+export const getJlinkCompatibility = (moduleVersion: ModuleVersion) => {
+    const jlinkVersionDependency = findDependency(
+        'JlinkARM',
+        moduleVersion.dependencies
+    );
+
+    if (!hasVersion(jlinkVersionDependency)) {
+        const requiredVersion =
+            jlinkVersionDependency?.expectedVersion != null
+                ? strippedVersionName(jlinkVersionDependency.expectedVersion)
+                : nrfutilDeviceToJLink(moduleVersion.version);
+        return {
+            kind: 'No J-Link installed',
+            requiredJlink: requiredVersion,
+            actualJlink: 'none',
+        } as const;
+    }
+
+    if (
+        jlinkVersionDependency.expectedVersion &&
+        existingIsOlderThanExpected(jlinkVersionDependency)
+    ) {
+        const requiredJlink = strippedVersionName(
+            jlinkVersionDependency.expectedVersion
+        );
+        const actualJlink = strippedVersionName(jlinkVersionDependency);
+
+        return {
+            kind: 'Outdated J-Link',
+            requiredJlink,
+            actualJlink,
+        } as const;
+    }
+
+    if (
+        jlinkVersionDependency.expectedVersion == null ||
+        jlinkVersionDependency.version ===
+            jlinkVersionDependency.expectedVersion.version
+    ) {
+        return {
+            kind: 'Tested J-Link is used',
+        } as const;
+    }
+
+    const requiredJlink = strippedVersionName(
+        jlinkVersionDependency.expectedVersion
+    );
+    const actualJlink = strippedVersionName(jlinkVersionDependency);
+
+    return {
+        kind: 'Newer J-Link is used',
+        requiredJlink,
+        actualJlink,
+    } as const;
+};