@nordicsemiconductor/pc-nrfconnect-shared 60.0.0-pre1

package/src/Device/deviceSetup.ts

@@ -0,0 +1,264 @@
+/*
+ * Copyright (c) 2015 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+import logger from '../logging';
+import describeError from '../logging/describeError';
+import { AppDispatch, RootState } from '../store';
+import {
+    closeDeviceSetupDialog,
+    openDeviceSetupDialog,
+    setDeviceSetupProgress,
+    setDeviceSetupProgressMessage,
+} from './deviceSetupSlice';
+import { Device } from './deviceSlice';
+import { InitPacket } from './initPacket';
+
+export interface DfuEntry {
+    key: string;
+    description?: string;
+    application: string;
+    semver: string;
+    softdevice?: string | Buffer;
+    params: Partial<InitPacket>;
+}
+
+export interface JprogEntry {
+    key: string;
+    description?: string;
+    fw: string;
+    fwIdAddress: number;
+    fwVersion: string;
+}
+
+export interface DeviceSetup {
+    supportsProgrammingMode: (device: Device) => boolean; // Return true if this device can be programed using this interface e.g. MCU Boot or DFU
+    getFirmwareOptions: (device: Device) => {
+        key: string;
+        description?: string;
+        programDevice: (
+            onProgress: (progress: number, message?: string) => void
+        ) => (
+            dispatch: AppDispatch,
+            getState: () => RootState
+        ) => Promise<Device>;
+    }[]; // The list of all firmware that can be applied for this device with the program function for that fw item
+    isExpectedFirmware: (device: Device) => (
+        dispatch: AppDispatch,
+        getState: () => RootState
+    ) => Promise<{
+        device: Device;
+        validFirmware: boolean;
+    }>; // returns true if device has one of the expected firmware returned by getFirmwareOptions
+    tryToSwitchToApplicationMode: (
+        device: Device
+    ) => (
+        dispatch: AppDispatch,
+        getState: () => RootState
+    ) => Promise<Device | null>; // returns the device after switched to app mode. If this is not possible or not relevant return null
+}
+
+export interface DeviceSetupConfig {
+    deviceSetups: DeviceSetup[];
+    allowCustomDevice?: boolean;
+    confirmMessage?: string;
+    choiceMessage?: string;
+}
+
+export const prepareDevice =
+    (
+        device: Device,
+        deviceSetupConfig: DeviceSetupConfig,
+        onSuccess: (device: Device) => void,
+        onFail: (reason?: unknown) => void,
+        checkCurrentFirmwareVersion = true,
+        requireUserConfirmation = true
+    ) =>
+    async (dispatch: AppDispatch) => {
+        const onSuccessWrapper = (d: Device) => {
+            onSuccess(d);
+            dispatch(closeDeviceSetupDialog());
+        };
+        const validDeviceSetups = deviceSetupConfig.deviceSetups.filter(
+            deviceSetup => deviceSetup.supportsProgrammingMode(device)
+        );
+
+        const possibleFirmware = validDeviceSetups
+            .map(deviceSetup => deviceSetup.getFirmwareOptions(device))
+            .flat();
+
+        if (possibleFirmware.length === 0) {
+            logger.info(
+                `Connected to device with serial number: ${device.serialNumber} ` +
+                    `and family: ${device.jlink?.deviceFamily || 'Unknown'} `
+            );
+            if (deviceSetupConfig.allowCustomDevice) {
+                logger.info(
+                    'Note: no pre-compiled firmware is available for the selected device. ' +
+                        'You may still use the app if you have programmed the device ' +
+                        'with a compatible firmware.'
+                );
+                onSuccessWrapper(device);
+            } else {
+                logger.info(
+                    'Note: no pre-compiled firmware is available for the selected device. '
+                );
+                onFail('No device setup found');
+            }
+
+            return;
+        }
+
+        if (checkCurrentFirmwareVersion) {
+            // eslint-disable-next-line no-restricted-syntax
+            for (const deviceSetup of validDeviceSetups) {
+                try {
+                    // eslint-disable-next-line no-await-in-loop
+                    const result = await dispatch(
+                        deviceSetup.isExpectedFirmware(device)
+                    );
+                    device = result.device;
+                    if (result.validFirmware) {
+                        onSuccessWrapper(device);
+                        return;
+                    }
+                } catch (error) {
+                    onFail(error);
+                    return;
+                }
+            }
+        }
+
+        const choices = possibleFirmware
+            .map(
+                fw => `${fw.key}${fw.description ? ` - ${fw.description}` : ''}`
+            )
+            .flat();
+
+        const proceedAction = (choice: number) => {
+            const selectedDeviceSetup = possibleFirmware[choice];
+
+            if (!selectedDeviceSetup) {
+                onFail('No firmware was selected'); // Should never happen
+            } else {
+                dispatch(
+                    selectedDeviceSetup.programDevice(
+                        (progress: number, message?: string) => {
+                            dispatch(setDeviceSetupProgress(progress));
+                            if (message)
+                                dispatch(
+                                    setDeviceSetupProgressMessage(message)
+                                );
+                        }
+                    )
+                )
+                    .then(onSuccessWrapper)
+                    .catch(onFail);
+            }
+        };
+
+        const cancelAction = async () => {
+            let i = 0;
+            do {
+                const deviceSetup = validDeviceSetups[i];
+                try {
+                    // eslint-disable-next-line no-await-in-loop
+                    const result = await dispatch(
+                        deviceSetup.tryToSwitchToApplicationMode(device)
+                    );
+                    if (result) {
+                        onSuccessWrapper(result);
+                        return;
+                    }
+                } catch (error) {
+                    onFail(error);
+                    return;
+                }
+
+                i += 1;
+            } while (i < validDeviceSetups.length);
+
+            onSuccessWrapper(device);
+        };
+
+        if (choices.length === 1) {
+            if (requireUserConfirmation) {
+                dispatch(
+                    openDeviceSetupDialog({
+                        onUserInput: isCanceled => {
+                            if (isCanceled) {
+                                cancelAction();
+                            } else {
+                                proceedAction(0);
+                            }
+                        },
+                        message:
+                            deviceSetupConfig.confirmMessage ??
+                            'Device must be programmed, do you want to proceed?',
+                    })
+                );
+            } else {
+                dispatch(
+                    openDeviceSetupDialog({
+                        message:
+                            deviceSetupConfig.confirmMessage ??
+                            'Device must be programmed, do you want to proceed?',
+                    })
+                );
+                proceedAction(0);
+            }
+        } else {
+            dispatch(
+                openDeviceSetupDialog({
+                    onUserInput: (isCanceled, index) => {
+                        if (isCanceled) {
+                            cancelAction();
+                        } else {
+                            proceedAction(index ?? 0);
+                        }
+                    },
+                    message:
+                        deviceSetupConfig.choiceMessage ??
+                        'Which firmware do you want to program?',
+                })
+            );
+        }
+    };
+
+export const setupDevice =
+    (
+        device: Device,
+        deviceSetupConfig: DeviceSetupConfig,
+        onDeviceIsReady: (device: Device) => void,
+        doDeselectDevice: () => void
+    ) =>
+    (dispatch: AppDispatch, getState: () => RootState) =>
+        dispatch(
+            prepareDevice(
+                device,
+                {
+                    allowCustomDevice: false,
+                    ...deviceSetupConfig,
+                },
+                d => {
+                    // Given that this task has async elements to it one might call setupDevice and
+                    // while that is still in progress select some other device
+                    // if both were to call onDeviceIsReady the app might have unexpected side effects
+                    if (
+                        getState().device.selectedSerialNumber ===
+                        d.serialNumber
+                    ) {
+                        onDeviceIsReady(d);
+                    }
+                },
+                error => {
+                    dispatch(closeDeviceSetupDialog());
+                    logger.error(
+                        `Error while setting up device ${device.serialNumber}`
+                    );
+                    logger.error(describeError(error));
+                    doDeselectDevice();
+                }
+            )
+        );

package/src/Device/deviceSetupSlice.ts

@@ -0,0 +1,94 @@
+/*
+ * Copyright (c) 2021 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import { createSlice, PayloadAction } from '@reduxjs/toolkit';
+
+import type { RootState } from '../store';
+
+export interface DeviceSetupState {
+    visible: boolean;
+    onUserInput?: (canceled: boolean, choice?: number) => void;
+    message: string;
+    progressMessage?: string;
+    choices?: string[];
+    progress?: number;
+}
+
+const initialState: DeviceSetupState = {
+    visible: false,
+    message: '',
+    choices: [],
+    onUserInput: () => {},
+};
+
+// onUserInput: (canceled: boolean, choice: boolean | string) => void, choices: string[]
+
+const slice = createSlice({
+    name: 'deviceSetup',
+    initialState,
+    reducers: {
+        openDeviceSetupDialog: (
+            state,
+            action: PayloadAction<{
+                onUserInput?: (canceled: boolean, choice?: number) => void;
+                message: string;
+                choices?: string[];
+            }>
+        ) => {
+            state.visible = true;
+            state.onUserInput = action.payload.onUserInput;
+            state.choices = action.payload.choices;
+            state.message = action.payload.message;
+        },
+        closeDeviceSetupDialog: () => ({ ...initialState }),
+
+        setDeviceSetupProgress: (state, action: PayloadAction<number>) => {
+            state.progress = action.payload;
+        },
+        setDeviceSetupMessage: (state, action: PayloadAction<string>) => {
+            state.message = action.payload;
+        },
+        setDeviceSetupProgressMessage: (
+            state,
+            action: PayloadAction<string>
+        ) => {
+            state.progressMessage = action.payload;
+        },
+        deviceSetupUserInputReceived: state => {
+            state.onUserInput = undefined;
+        },
+    },
+});
+
+export const {
+    reducer,
+    actions: {
+        openDeviceSetupDialog,
+        closeDeviceSetupDialog,
+        setDeviceSetupProgress,
+        setDeviceSetupMessage,
+        setDeviceSetupProgressMessage,
+        deviceSetupUserInputReceived,
+    },
+} = slice;
+
+export const isDeviceSetupDialogVisible = (state: RootState) =>
+    state.deviceSetup.visible;
+
+export const getDeviceSetupProgress = (state: RootState) =>
+    state.deviceSetup.progress;
+
+export const getDeviceSetupMessage = (state: RootState) =>
+    state.deviceSetup.message;
+
+export const getDeviceSetupProgressMessage = (state: RootState) =>
+    state.deviceSetup.progressMessage;
+
+export const getDeviceSetupChoices = (state: RootState) =>
+    state.deviceSetup.choices;
+
+export const getDeviceSetupUserInputCallback = (state: RootState) =>
+    state.deviceSetup.onUserInput;

package/src/Device/deviceSlice.ts

@@ -0,0 +1,248 @@
+/*
+ * Copyright (c) 2021 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
+ */
+
+import type {
+    Device as NrfdlDevice,
+    SerialPort,
+} from '@nordicsemiconductor/nrf-device-lib-js';
+import { createSlice, PayloadAction } from '@reduxjs/toolkit';
+import type { AutoDetectTypes } from '@serialport/bindings-cpp';
+import { SerialPortOpenOptions } from 'serialport';
+
+import type { RootState } from '../store';
+import {
+    getPersistedIsFavorite,
+    getPersistedNickname,
+    getPersistedSerialPortSettings,
+    persistIsFavorite,
+    persistNickname,
+    persistSerialPortSettings as persistSerialPortSettingsToStore,
+} from '../utils/persistentStore';
+
+export interface Device extends NrfdlDevice {
+    serialNumber: string;
+    boardVersion?: string;
+    nickname?: string;
+    serialport?: SerialPort;
+    favorite?: boolean;
+    id: number;
+    persistedSerialPortOptions?: SerialPortOpenOptions<AutoDetectTypes>;
+}
+
+const updateDevice = (
+    state: DeviceState,
+    serialNumber: string,
+    updateToMergeIn: Partial<Device>
+) => {
+    const device = state.devices.get(serialNumber);
+    if (device) {
+        Object.assign(device, updateToMergeIn);
+    }
+};
+
+export interface DeviceState {
+    devices: Map<string, Device>;
+    deviceInfo: Device | null;
+    selectedSerialNumber: string | null;
+    readbackProtection: 'unknown' | 'protected' | 'unprotected';
+}
+
+const initialState: DeviceState = {
+    devices: new Map(),
+    selectedSerialNumber: null,
+    deviceInfo: null,
+    readbackProtection: 'unknown',
+};
+
+const setPersistedData = (device: Device) => {
+    const newDevice = {
+        ...device,
+        favorite: getPersistedIsFavorite(device.serialNumber),
+        nickname: getPersistedNickname(device.serialNumber),
+    };
+
+    const persistedSerialPortSettings = getPersistedSerialPortSettings(
+        newDevice.serialNumber
+    );
+
+    if (persistedSerialPortSettings) {
+        const path =
+            newDevice.serialPorts?.[persistedSerialPortSettings.vComIndex]
+                ?.comName;
+
+        if (path) {
+            newDevice.persistedSerialPortOptions = {
+                ...persistedSerialPortSettings.serialPortOptions,
+                path,
+            };
+        }
+    }
+
+    return newDevice;
+};
+
+const slice = createSlice({
+    name: 'device',
+    initialState,
+    reducers: {
+        /*
+         * Indicates that a device has been selected.
+         */
+        selectDevice: (state, action: PayloadAction<Device>) => {
+            state.selectedSerialNumber = action.payload.serialNumber;
+        },
+
+        /*
+         * Indicates that the currently selected device has been deselected.
+         */
+        deselectDevice: state => {
+            state.selectedSerialNumber = null;
+            state.deviceInfo = null;
+            state.readbackProtection = 'unknown';
+        },
+
+        setDevices: (state, action: PayloadAction<Device[]>) => {
+            state.devices.clear();
+            action.payload.forEach(device => {
+                state.devices.set(
+                    device.serialNumber,
+                    setPersistedData(device)
+                );
+            });
+        },
+
+        addDevice: (state, action: PayloadAction<Device>) => {
+            state.devices.set(
+                action.payload.serialNumber,
+                setPersistedData(action.payload)
+            );
+        },
+
+        persistSerialPortOptions: (
+            state,
+            action: PayloadAction<SerialPortOpenOptions<AutoDetectTypes>>
+        ) => {
+            if (state.selectedSerialNumber === null) return;
+
+            const selectedDevice = state.devices.get(
+                state.selectedSerialNumber
+            );
+
+            if (selectedDevice) {
+                const vComIndex = selectedDevice.serialPorts?.findIndex(
+                    e => e.comName === action.payload.path
+                );
+
+                if (vComIndex !== undefined && vComIndex !== -1) {
+                    // eslint-disable-next-line @typescript-eslint/no-unused-vars -- used to filter out the path property
+                    const { path: _, ...serialPortOptions } = action.payload;
+
+                    persistSerialPortSettingsToStore(
+                        state.selectedSerialNumber,
+                        {
+                            serialPortOptions,
+                            vComIndex,
+                        }
+                    );
+
+                    state.devices.set(state.selectedSerialNumber, {
+                        ...selectedDevice,
+                        persistedSerialPortOptions: action.payload,
+                    });
+                }
+            }
+        },
+
+        removeDevice: (state, action: PayloadAction<Device>) => {
+            state.devices.delete(action.payload.serialNumber);
+
+            if (state.selectedSerialNumber === action.payload.serialNumber) {
+                state.selectedSerialNumber = null;
+                state.deviceInfo = null;
+            }
+        },
+
+        toggleDeviceFavorited: (state, action: PayloadAction<string>) => {
+            const newFavoriteState = !state.devices.get(action.payload)
+                ?.favorite;
+            persistIsFavorite(action.payload, newFavoriteState);
+            updateDevice(state, action.payload, {
+                favorite: newFavoriteState,
+            });
+        },
+
+        setDeviceNickname: {
+            prepare: (serialNumber: string, nickname: string) => ({
+                payload: { serialNumber, nickname },
+            }),
+            reducer: (
+                state,
+                action: PayloadAction<{
+                    serialNumber: string;
+                    nickname: string;
+                }>
+            ) => {
+                persistNickname(
+                    action.payload.serialNumber,
+                    action.payload.nickname
+                );
+                updateDevice(state, action.payload.serialNumber, {
+                    nickname: action.payload.nickname,
+                });
+            },
+        },
+
+        resetDeviceNickname: (state, action: PayloadAction<string>) => {
+            persistNickname(action.payload, '');
+            updateDevice(state, action.payload, {
+                nickname: '',
+            });
+        },
+
+        setReadbackProtected: (
+            state,
+            action: PayloadAction<DeviceState['readbackProtection']>
+        ) => {
+            state.readbackProtection = action.payload;
+        },
+    },
+});
+
+export const {
+    reducer,
+    actions: {
+        deselectDevice,
+        resetDeviceNickname,
+        selectDevice,
+        addDevice,
+        removeDevice,
+        setDevices,
+        setDeviceNickname,
+        toggleDeviceFavorited,
+        setReadbackProtected,
+        persistSerialPortOptions,
+    },
+} = slice;
+
+export const getDevice = (serialNumber: string) => (state: RootState) =>
+    state.device.devices.get(serialNumber);
+
+export const getDevices = (state: RootState) => state.device.devices;
+
+export const deviceIsSelected = (state: RootState) =>
+    state.device.selectedSerialNumber != null;
+
+export const selectedDevice = (state: RootState) =>
+    state.device.selectedSerialNumber !== null
+        ? state.device.devices.get(state.device.selectedSerialNumber)
+        : undefined;
+
+export const deviceInfo = (state: RootState) => state.device.deviceInfo;
+export const selectedSerialNumber = (state: RootState) =>
+    state.device.selectedSerialNumber;
+
+export const getReadbackProtection = (state: RootState) =>
+    state.device.readbackProtection;