@nordicsemiconductor/pc-nrfconnect-shared 78.0.0 → 79.0.0

package/.github/ISSUE_TEMPLATE/custom.md

@@ -0,0 +1,10 @@
+---
+name: Custom issue template
+about: Please report bugs and feedback in DevZone
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+Please use the [Nordic DevZone](https://devzone.nordicsemi.com) portal to report bugs, questions or feedback in general. If you would like to suggest code changes, feel free to submit a pull request.

package/.husky/pre-push

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+npm run check && npm t

package/.renovaterc.json

@@ -0,0 +1,10 @@
+{
+    "extends": ["config:base", "group:allNonMajor"],
+    "packageRules": [
+        {
+            "groupName": "Prettier",
+            "matchPackageNames": ["prettier"],
+            "matchUpdateTypes": ["minor", "patch"]
+        }
+    ]
+}

package/Changelog.md

@@ -7,7 +7,7 @@ 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.
 
-## 78 - 2023-08-02
+## 79 - Unreleased
 
 ### Changed
 
@@ -16,6 +16,31 @@ every new version is a new major version.
     and use the new name `@nordicsemiconductor/pc-nrfconnect-shared` when
     importing components from shared
 
+### Steps to upgrade when using this package
+
+-   Change all references from `pc-nrfconnect-shared` to
+    `@nordicsemiconductor/pc-nrfconnect-shared`
+
+```diff
+- import { App } from 'pc-nrfconnect-shared';
++ import { App } from '@nordicsemiconductor/pc-nrfconnect-shared';
+```
+
+-   Also check references in `tsconfig.json`, s`jest.config.js` and
+    `.scss`-files.
+
+## 78 - 2023-08-03
+
+### Changed
+
+-   Shared now only uses `device.jlink.boardversion` instead of
+    `jlink.boardVersion`.
+
+### Fixed
+
+-   `deviceInfo` can now be used in applications that don't make use of the
+    shared redux store.
+
 ## 77 - 2023-08-01
 
 ### Added

package/azure-pipelines.yml

@@ -0,0 +1,36 @@
+trigger:
+    - main
+pool:
+    vmImage: 'ubuntu-latest'
+variables:
+    - group: wayland
+steps:
+    - task: NodeTool@0
+      inputs:
+          versionSpec: 18
+    - script: |
+          set -o errexit -o pipefail
+          npm ci
+          npm run check
+          npm run generate-types
+          npm test -- --coverage --coverageReporters=cobertura
+          npx esbuild scripts/nordic-publish.ts --bundle --outfile=scripts/nordic-publish.js --platform=node --log-level=warning --minify
+          node scripts/esbuild-bootstrap.js
+          npm pack
+      displayName: 'Build, Test, Compile and Pack'
+    - bash: |
+          set -o errexit -o pipefail
+          cp *.tgz "$(Build.ArtifactStagingDirectory)"
+          #Leave for now, testing purposes.
+          #condition: ne(variables['Build.Reason'], 'PullRequest')
+      displayName: 'Copy Artifacts'
+    - task: PublishCodeCoverageResults@1
+      displayName: Publish code coverage
+      inputs:
+          codeCoverageTool: Cobertura
+          summaryFileLocation: $(System.DefaultWorkingDirectory)/coverage/cobertura-coverage.xml
+    - task: PublishPipelineArtifact@1
+      inputs:
+          targetPath: $(Build.ArtifactStagingDirectory)
+          publishLocation: 'pipeline'
+      displayName: 'Publish artifacts to artifact storage'

package/{typings/generated/ipc/MetaFiles.d.ts → ipc/MetaFiles.ts}

@@ -1,15 +1,25 @@
+/*
+ * Copyright (c) 2022 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
 export type UrlString = string;
+
 export interface SourceJson {
     name: string;
     apps: UrlString[];
 }
+
 export type WithdrawnJson = UrlString[];
+
 export type AppVersions = {
     [version: string]: {
         shasum?: string;
         tarballUrl: UrlString;
     };
 };
+
 export interface AppInfo {
     name: string;
     displayName: string;
@@ -24,12 +34,16 @@ export interface AppInfo {
         shasum?: string;
     };
 }
+
 interface ObjectContainingOptionalStrings {
     [index: string]: string | undefined;
 }
+
 export interface PackageJson {
     name: string;
     version: string;
+
+    // Several optional properties
     author?: string;
     bin?: ObjectContainingOptionalStrings | string;
     dependencies?: ObjectContainingOptionalStrings;
@@ -48,5 +62,3 @@ export interface PackageJson {
     };
     scripts?: ObjectContainingOptionalStrings;
 }
-export {};
-//# sourceMappingURL=MetaFiles.d.ts.map

package/ipc/README.md

@@ -0,0 +1,43 @@
+The folder `ipc/` is meant as a middle layer between the main and renderer
+processes.
+
+Some of the code here should be called from the main process, usually to
+register IPC handlers. Other code here should be called from the renderer
+process(es), usually the ones to send IPC messages. They are both kept together
+to keep them in sync, especially that the channel names and the shape of the
+messages are the same.
+
+All the code for the main process here is ran by the launcher. The launcher or
+apps can invoke the functions from here, e.g. to do things like opening an app.
+This means, the API must be kept stable here and in the launcher, so that the
+launcher will react in the way the apps expect it.
+
+## Code conventions
+
+There are a few conventions we follow with the code here in `ipc/`:
+
+-   In each file there are pairs of functions: One to send a message over an IPC
+    channel (e.g. `openApp`) and another to register a handler for the messages
+    on that same channel (e.g. `registerOpenApp`).
+
+    Usually these two functions utilize a shared signature which is defined in a
+    type above them. Usually the functions are defined by invoking functions
+    from `infrastructure/mainToRenderer.ts` or
+    `infrastructure/rendererToMain.ts` which also use that type.
+
+-   The functions mentioned before are then exported in objects with the names
+    `inMain`, `forRenderer`, `inRenderer`, and `forMain` to signify how the
+    functions are supposed to be used. E.g. the mentioned `openApp` is in
+    `inMain` because it is called by code in the renderer processes to invoke
+    code in the main process to open an window. `registerOpenApp` is in
+    `forRenderer` because the handler is registered so that code in the renderer
+    processes can invoke it.
+
+    So, `inMain` and `forRenderer` are used when sending messages from the
+    renderer processes to the main process. `inRenderer` and `forMain` are used,
+    when sending messages from the main process to the renderer processes.
+
+-   The code here in `ipc/` must neither reference any code in `src/` (which is
+    for code of the renderer processes) nor in `main/` (which is for code in the
+    main process). Only the other way around code in those two folders can
+    reference code in `ipc/`.

package/ipc/appDetails.ts

@@ -0,0 +1,47 @@
+/*
+ * Copyright (c) 2022 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import { ipcMain, WebContents } from 'electron';
+
+import { LaunchableApp } from './apps';
+import { handleWithSender, invoke } from './infrastructure/rendererToMain';
+
+const channel = {
+    request: 'get-app-details',
+    response: 'app-details',
+};
+
+interface AppDetails {
+    coreVersion: string;
+    corePath: string;
+    homeDir: string;
+    tmpDir: string;
+    bundledJlink: string;
+    path: string;
+}
+
+export type AppDetailsFromLauncher = AppDetails & LaunchableApp;
+
+type GetAppDetails = () => AppDetailsFromLauncher;
+
+const getAppDetails = invoke<GetAppDetails>(channel.request);
+
+const registerGetAppDetails = (
+    onGetAppDetails: (webContents: WebContents) => AppDetailsFromLauncher
+) => {
+    handleWithSender<GetAppDetails>(channel.request)(onGetAppDetails);
+
+    // This legacy implementation is still needed, because we currently still
+    // send the corresponding message in apps using shared 76 or earlier.
+    // When all apps are updated and required a launcher using shared 77 or
+    // later, we can remove this.
+    ipcMain.on(channel.request, event => {
+        event.sender.send(channel.response, onGetAppDetails(event.sender));
+    });
+};
+
+export const forRenderer = { registerGetAppDetails };
+export const inMain = { getAppDetails };

package/ipc/apps.ts

@@ -0,0 +1,119 @@
+/*
+ * Copyright (c) 2022 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import { handle, invoke } from './infrastructure/rendererToMain';
+import { AppVersions, UrlString } from './MetaFiles';
+import { LOCAL, Source, SourceName } from './sources';
+
+export interface AppSpec {
+    name: string;
+    source: SourceName;
+}
+
+interface BaseApp {
+    name: string;
+    displayName: string;
+    description: string;
+    iconPath: string;
+}
+
+interface Downloadable {
+    source: SourceName;
+    homepage?: UrlString;
+    versions?: AppVersions;
+    releaseNotes?: string;
+    latestVersion: string;
+}
+
+interface Installed {
+    currentVersion: string;
+    engineVersion?: string;
+    repositoryUrl?: UrlString;
+    html?: string;
+    installed: {
+        path: string;
+        shasum?: string;
+    };
+}
+
+export interface LocalApp extends Installed, BaseApp {
+    source: typeof LOCAL;
+}
+
+export interface InstalledDownloadableApp
+    extends BaseApp,
+        Installed,
+        Downloadable {
+    isWithdrawn: false;
+}
+
+export interface UninstalledDownloadableApp extends BaseApp, Downloadable {
+    isWithdrawn: false;
+}
+
+export interface WithdrawnApp extends BaseApp, Installed, Downloadable {
+    isWithdrawn: true;
+}
+
+export type DownloadableApp =
+    | InstalledDownloadableApp
+    | UninstalledDownloadableApp
+    | WithdrawnApp;
+
+export type LaunchableApp = LocalApp | InstalledDownloadableApp | WithdrawnApp;
+
+export type App = LocalApp | DownloadableApp;
+
+export interface AppWithError extends AppSpec {
+    reason: unknown;
+    path: string;
+}
+
+const channel = {
+    getDownloadableApps: 'apps:get-downloadable-apps',
+    installDownloadableApp: 'apps:install-downloadable-app',
+};
+
+export type SourceWithError = { source: Source; reason?: string };
+
+// getDownloadableApps
+type GetDownloadableAppsResult = {
+    apps: DownloadableApp[];
+    appsWithErrors: AppWithError[];
+    sourcesWithErrors: SourceWithError[];
+};
+
+type GetDownloadableApps = () => GetDownloadableAppsResult;
+
+const getDownloadableApps = invoke<GetDownloadableApps>(
+    channel.getDownloadableApps
+);
+const registerGetDownloadableApps = handle<GetDownloadableApps>(
+    channel.getDownloadableApps
+);
+
+// installDownloadableApp
+type InstallDownloadableApp = (
+    app: DownloadableApp,
+    version?: string
+) => DownloadableApp;
+
+const installDownloadableApp = invoke<InstallDownloadableApp>(
+    channel.installDownloadableApp
+);
+const registerInstallDownloadableApp = handle<InstallDownloadableApp>(
+    channel.installDownloadableApp
+);
+
+export const forRenderer = {
+    registerGetDownloadableApps,
+    registerInstallDownloadableApp,
+};
+
+export const inMain = {
+    getDownloadableApps,
+    installDownloadableApp,
+};

package/ipc/infrastructure/mainToRenderer.ts

@@ -0,0 +1,49 @@
+/*
+ * Copyright (c) 2022 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import { BrowserWindow, ipcRenderer, WebContents } from 'electron';
+
+let launcherWindow: BrowserWindow | undefined;
+
+export const registerLauncherWindowFromMain = (window: BrowserWindow) => {
+    launcherWindow = window;
+};
+
+export const send =
+    <T extends (...args: never[]) => void>(channel: string) =>
+    (...args: Parameters<T>) =>
+        launcherWindow?.webContents.send(channel, ...args);
+
+export const on =
+    <T extends (...args: never[]) => void>(channel: string) =>
+    (handler: T) =>
+        ipcRenderer.on(channel, (_event, ...args: unknown[]) =>
+            handler(...(args as Parameters<T>))
+        );
+
+// Broadcast with a subchannel
+
+export const broadcast =
+    <T extends (...args: never[]) => void>(channel: string) =>
+    (
+        subChannel: string,
+        targets: Pick<WebContents, 'send'>[] = [],
+        ...args: Parameters<T>
+    ) =>
+        targets.forEach(target => {
+            target.send(`${channel}_${subChannel}`, ...args);
+        });
+
+export const onBroadcasted =
+    <T extends (...args: never[]) => void>(
+        channel: string,
+        subChannel: string
+    ) =>
+    (handler: T) =>
+        ipcRenderer.on(
+            `${channel}_${subChannel}`,
+            (_event, ...args: unknown[]) => handler(...(args as Parameters<T>))
+        );

package/ipc/infrastructure/rendererToMain.ts

@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) 2022 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import { ipcMain, ipcRenderer, WebContents } from 'electron';
+
+// Send
+export const send =
+    <T extends (...args: never[]) => void>(channel: string) =>
+    (...args: Parameters<T>) =>
+        ipcRenderer.send(channel, ...args);
+
+export const on =
+    <T extends (...args: never[]) => void>(channel: string) =>
+    (handler: T) =>
+        ipcMain.on(channel, (_event, ...args: unknown[]) =>
+            handler(...(args as Parameters<T>))
+        );
+
+// Invoke
+export const invoke =
+    <T extends (...args: never[]) => unknown>(channel: string) =>
+    (...args: Parameters<T>) =>
+        ipcRenderer.invoke(channel, ...args) as Promise<ReturnType<T>>;
+
+export const handle =
+    <T extends (...args: never[]) => unknown>(channel: string) =>
+    (
+        handler:
+            | ((...args: Parameters<T>) => ReturnType<T>)
+            | ((...args: Parameters<T>) => Promise<ReturnType<T>>)
+    ) =>
+        ipcMain.handle(channel, (_event, ...args: unknown[]) =>
+            handler(...(args as Parameters<T>))
+        );
+
+export const handleWithSender =
+    <T extends (...args: never[]) => unknown>(channel: string) =>
+    (
+        handler:
+            | ((sender: WebContents, ...args: Parameters<T>) => ReturnType<T>)
+            | ((
+                  sender: WebContents,
+                  ...args: Parameters<T>
+              ) => Promise<ReturnType<T>>)
+    ) =>
+        ipcMain.handle(channel, ({ sender }, ...args: unknown[]) =>
+            handler(sender, ...(args as Parameters<T>))
+        );

package/ipc/openWindow.ts

@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) 2022 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import type { AppSpec } from './apps';
+import { on, send } from './infrastructure/rendererToMain';
+
+const channel = {
+    app: 'open:app',
+    launcher: 'open-app-launcher', // It would be nice to call this `open:launcher` but we have to stick to the current name, because that is used by supported apps.
+};
+
+export interface OpenAppOptions {
+    device?: { serialNumber: string; serialPortPath?: string };
+}
+
+type OpenApp = (app: AppSpec, openAppOptions?: OpenAppOptions) => void;
+const openApp = send<OpenApp>(channel.app);
+const registerOpenApp = on<OpenApp>(channel.app);
+
+type OpenLauncher = () => void;
+const openLauncher = send<OpenLauncher>(channel.launcher);
+const registerOpenLauncher = on<OpenLauncher>(channel.launcher);
+
+export const forRenderer = {
+    registerOpenApp,
+    registerOpenLauncher,
+};
+
+export const inMain = {
+    openApp,
+    openLauncher,
+};

package/ipc/preventSleep.ts

@@ -0,0 +1,23 @@
+/*
+ * Copyright (c) 2023 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import { handle, invoke, on, send } from './infrastructure/rendererToMain';
+
+const channel = {
+    start: 'prevent-sleep:start',
+    end: 'prevent-sleep:end',
+};
+
+type Start = () => number;
+const start = invoke<Start>(channel.start);
+const registerStart = handle<Start>(channel.start);
+
+type End = (id: number) => void;
+const end = send<End>(channel.end);
+const registerEnd = on<End>(channel.end);
+
+export const forRenderer = { registerStart, registerEnd };
+export const inMain = { start, end };

package/ipc/serialPort.ts

@@ -0,0 +1,167 @@
+/*
+ * Copyright (c) 2023 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import type {
+    AutoDetectTypes,
+    SetOptions,
+    UpdateOptions,
+} from '@serialport/bindings-cpp';
+import type { SerialPortOpenOptions } from 'serialport';
+
+import { broadcast, onBroadcasted } from './infrastructure/mainToRenderer';
+import {
+    handle,
+    handleWithSender,
+    invoke,
+} from './infrastructure/rendererToMain';
+
+const channel = {
+    // **************
+    // Commands (from the renderer processes of apps to the main process)
+    // **************
+    open: 'serialport:open',
+    close: 'serialport:close',
+    write: 'serialport:write',
+    update: 'serialport:update',
+    set: 'serialport:set',
+
+    // **************
+    // Queries (from the renderer processes of apps to the main process)
+    // **************
+    isOpen: 'serialport:is-open',
+    getOptions: 'serialport:get-options',
+
+    // **************
+    // Callbacks (from the the main process to the renderer processes of apps)
+    // **************
+    onClosed: 'serialport:on-close',
+    onUpdated: 'serialport:on-update',
+    onSet: 'serialport:on-set',
+    onChanged: 'serialport:on-changed',
+
+    // Would be nice to rename the next two channels, but we cannot change the
+    // string because it would break interoperability between apps and launchers
+    onDataReived: 'serialport:on-data',
+    onDataWritten: 'serialport:on-write',
+};
+
+export type OverwriteOptions = {
+    overwrite?: boolean;
+    settingsLocked?: boolean;
+};
+
+// **************
+// Commands (from the renderer processes of apps to the main process)
+// **************
+
+type Open = (
+    options: SerialPortOpenOptions<AutoDetectTypes>,
+    overwriteOptions: OverwriteOptions
+) => void;
+const open = invoke<Open>(channel.open);
+const registerOpen = handleWithSender<Open>(channel.open);
+
+type Close = (path: string) => void;
+const close = invoke<Close>(channel.close);
+const registerClose = handleWithSender<Close>(channel.close);
+
+type Write = (path: string, data: string | number[] | Buffer) => void;
+const write = invoke<Write>(channel.write);
+const registerWrite = handle<Write>(channel.write);
+
+type Update = (path: string, options: UpdateOptions) => void;
+const update = invoke<Update>(channel.update);
+const registerUpdate = handle<Update>(channel.update);
+
+type Set = (path: string, set: SetOptions) => void;
+const set = invoke<Set>(channel.set);
+const registerSet = handle<Set>(channel.set);
+
+// **************
+// Queries (from the renderer processes of apps to the main process)
+// **************
+
+type IsOpen = (path: string) => boolean;
+const isOpen = invoke<IsOpen>(channel.isOpen);
+const registerIsOpen = handle<IsOpen>(channel.isOpen);
+
+type GetOptions = (
+    path: string
+) => SerialPortOpenOptions<AutoDetectTypes> | undefined;
+const getOptions = invoke<GetOptions>(channel.getOptions);
+const registerGetOptions = handle<GetOptions>(channel.getOptions);
+
+// **************
+// Callbacks (from the the main process to the renderer processes of apps)
+// **************
+
+type OnDataReceived = (data: unknown) => void;
+const broadcastDataReceived = broadcast<OnDataReceived>(channel.onDataReived);
+const registerOnDataReceived = (path: string) =>
+    onBroadcasted<OnDataReceived>(channel.onDataReived, path);
+
+type OnDataWritten = (data: string | number[] | Buffer) => void;
+const broadcastDataWritten = broadcast<OnDataWritten>(channel.onDataWritten);
+const registerOnDataWritten = (path: string) =>
+    onBroadcasted<OnDataWritten>(channel.onDataWritten, path);
+
+type OnClosed = () => void;
+const broadcastClosed = broadcast<OnClosed>(channel.onClosed);
+const registerOnClosed = (path: string) =>
+    onBroadcasted<OnClosed>(channel.onClosed, path);
+
+type OnUpdate = (newOptions: UpdateOptions) => void;
+const broadcastUpdated = broadcast<OnUpdate>(channel.onUpdated);
+const registerOnUpdated = (path: string) =>
+    onBroadcasted<OnUpdate>(channel.onUpdated, path);
+
+type OnSet = (newOptions: SetOptions) => void;
+const broadcastSet = broadcast<OnSet>(channel.onSet);
+const registerOnSet = (path: string) =>
+    onBroadcasted<OnSet>(channel.onSet, path);
+
+type OnChanged = (newOptions: SerialPortOpenOptions<AutoDetectTypes>) => void;
+const broadcastChanged = broadcast<OnChanged>(channel.onChanged);
+const registerOnChanged = (path: string) =>
+    onBroadcasted<OnChanged>(channel.onChanged, path);
+
+export const inRenderer = {
+    broadcastChanged,
+    broadcastClosed,
+    broadcastDataReceived,
+    broadcastDataWritten,
+    broadcastSet,
+    broadcastUpdated,
+};
+
+export const forRenderer = {
+    registerClose,
+    registerGetOptions,
+    registerIsOpen,
+    registerOpen,
+    registerSet,
+    registerUpdate,
+    registerWrite,
+};
+
+export const inMain = {
+    open,
+    close,
+    write,
+    update,
+    set,
+    isOpen,
+    getOptions,
+};
+
+export const forMain = {
+    registerOnDataReceived,
+    registerOnDataWritten,
+    registerOnClosed,
+    registerOnUpdated,
+    registerOnSet,
+    registerOnChanged,
+};