installPybricksDialog: add feature to install custom firmware

This restores the ability to drag and drop a custom firmware file to
flash the firmware on the hub.

Fixes: https://github.com/pybricks/pybricks-code/issues/1020

CHANGELOG.md

@@ -4,6 +4,9 @@
 
 ## [Unreleased]
 
+### Added
+- Added feature to install custom firmware from file ([pybricks-code#1020]).
+
 ### Fixed
 - Fixed run button enabled when no file open ([support#691]).
 - Fixed flash firmware dialog not showing when settings not open ([support#694]).
@@ -11,6 +14,7 @@
 - Fixed imports with invalid file name silently ignored ([support#717]).
 
 [pybricks-code#1011]: https://github.com/pybricks/pybricks-code/issues/1011
+[pybricks-code#1020]: https://github.com/pybricks/pybricks-code/issues/1020
 [support#691]: https://github.com/pybricks/support/issues/691
 [support#694]: https://github.com/pybricks/support/issues/694
 [support#717]: https://github.com/pybricks/support/issues/717

src/firmware/installPybricksDialog/InstallPybricksDialog.tsx

@@ -8,6 +8,7 @@ import {
     Checkbox,
     Classes,
     Code,
+    Collapse,
     ControlGroup,
     DialogStep,
     FormGroup,
@@ -23,9 +24,14 @@ import {
 } from '@blueprintjs/core';
 import { Classes as Classes2, Popover2 } from '@blueprintjs/popover2';
 import { Select2 } from '@blueprintjs/select';
+import { FirmwareMetadata, HubType } from '@pybricks/firmware';
+import { fileOpen } from 'browser-fs-access';
 import classNames from 'classnames';
-import React, { useMemo, useState } from 'react';
+import React, { useCallback, useMemo, useState } from 'react';
+import { useDropzone } from 'react-dropzone';
 import { useDispatch } from 'react-redux';
+import { useLocalStorage } from 'usehooks-ts';
+import { alertsShowAlert } from '../../alerts/actions';
 import {
     appName,
     pybricksUsbDfuWindowsDriverInstallUrl,
@@ -44,13 +50,14 @@ import { useHubPickerSelectedHub } from '../../components/hubPicker/hooks';
 import { FileMetadata } from '../../fileStorage';
 import { useFileStorageMetadata } from '../../fileStorage/hooks';
 import { useSelector } from '../../reducers';
+import { ensureError } from '../../utils';
 import ExternalLinkIcon from '../../utils/ExternalLinkIcon';
 import { isLinux, isWindows } from '../../utils/os';
 import {
     firmwareInstallPybricksDialogAccept,
     firmwareInstallPybricksDialogCancel,
 } from './actions';
-import { useFirmware } from './hooks';
+import { useCustomFirmware, useFirmware } from './hooks';
 import { useI18n } from './i18n';
 import { validateHubName } from '.';
 
@@ -59,6 +66,44 @@ const dialogBody = classNames(
     'pb-firmware-installPybricksDialog-body',
 );
 
+/** Translates hub type from firmware metadata to local hub type. */
+function getHubTypeFromMetadata(
+    metadata: FirmwareMetadata | undefined,
+    fallback: Hub,
+): Hub {
+    switch (metadata?.['device-id']) {
+        case HubType.MoveHub:
+            return Hub.Move;
+        case HubType.CityHub:
+            return Hub.City;
+        case HubType.TechnicHub:
+            return Hub.Technic;
+        case HubType.PrimeHub:
+            return Hub.Prime;
+        case HubType.EssentialHub:
+            return Hub.Essential;
+        default:
+            return fallback;
+    }
+}
+
+function getHubTypeNameFromMetadata(metadata: FirmwareMetadata | undefined): string {
+    switch (metadata?.['device-id']) {
+        case HubType.MoveHub:
+            return 'BOOST Move Hub';
+        case HubType.CityHub:
+            return 'City Hub';
+        case HubType.TechnicHub:
+            return 'Technic Hub';
+        case HubType.PrimeHub:
+            return 'SPIKE Prime/MINDSTORMS Robot Inventor hub';
+        case HubType.EssentialHub:
+            return 'SPIKE Essential hub';
+        default:
+            return '?';
+    }
+}
+
 const UnsupportedHubs: React.VoidFunctionComponent = () => {
     const i18n = useI18n();
 
@@ -117,26 +162,150 @@ const UnsupportedHubs: React.VoidFunctionComponent = () => {
     );
 };
 
-const SelectHubPanel: React.VoidFunctionComponent = () => {
+type SelectHubPanelProps = {
+    customFirmwareZip: File | undefined;
+    onCustomFirmwareZip: (firmwareZip: File | undefined) => void;
+};
+
+const SelectHubPanel: React.VoidFunctionComponent<SelectHubPanelProps> = ({
+    customFirmwareZip,
+    onCustomFirmwareZip,
+}) => {
+    const { isCustomFirmwareRequested, customFirmwareData } =
+        useCustomFirmware(customFirmwareZip);
+    const [isAdvancedOpen, setIsAdvancedOpen] = useLocalStorage(
+        'installPybricksDialog.isAdvancedOpen',
+        false,
+    );
     const i18n = useI18n();
+    const dispatch = useDispatch();
+
+    const onDrop = useCallback((acceptedFiles: File[]) => {
+        // should only be one file since multiple={false}
+        acceptedFiles.forEach((f) => {
+            onCustomFirmwareZip(f);
+        });
+    }, []);
+
+    const onClick = useCallback(async () => {
+        try {
+            const file = await fileOpen({
+                id: 'customFirmware',
+                mimeTypes: ['application/zip'],
+                extensions: ['.zip'],
+                // TODO: translate description
+                description: 'Zip Files',
+                excludeAcceptAllOption: true,
+                startIn: 'downloads',
+            });
+
+            onCustomFirmwareZip(file);
+        } catch (err) {
+            if (err instanceof DOMException && err.name === 'AbortError') {
+                // user cancelled, nothing to do
+            } else {
+                dispatch(
+                    alertsShowAlert('alerts', 'unexpectedError', {
+                        error: ensureError(err),
+                    }),
+                );
+            }
+        }
+    }, []);
+
+    const onKeyDown = useCallback(
+        (e: React.KeyboardEvent) => {
+            if (e.key !== 'Enter' && e.key !== ' ') {
+                return;
+            }
+
+            e.stopPropagation();
+            onClick();
+        },
+        [onClick],
+    );
+
+    const { getRootProps, getInputProps } = useDropzone({
+        accept: { 'application/zip': ['.zip'] },
+        multiple: false,
+        // react-dropzone doesn't allow full control of File System API, so we
+        // implement our own using browser-fs-access instead.
+        noClick: true,
+        onDrop,
+    });
 
     return (
         <div className={dialogBody}>
-            <p>{i18n.translate('selectHubPanel.message')}</p>
-            <HubPicker />
-            <Popover2
-                popoverClassName={Classes2.POPOVER2_CONTENT_SIZING}
-                placement="right-end"
-                content={<UnsupportedHubs />}
-                renderTarget={({ isOpen: _isOpen, ref, ...targetProps }) => (
+            {isCustomFirmwareRequested ? (
+                <>
+                    <p>{i18n.translate('selectHubPanel.customFirmware.message')}</p>
+                    <p>
+                        {i18n.translate('selectHubPanel.customFirmware.hubType', {
+                            hubTypeName: getHubTypeNameFromMetadata(
+                                customFirmwareData?.metadata,
+                            ),
+                        })}
+                    </p>
+                    <p>
+                        {i18n.translate(
+                            'selectHubPanel.customFirmware.firmwareVersion',
+                            {
+                                version:
+                                    customFirmwareData?.metadata['firmware-version'],
+                            },
+                        )}
+                    </p>
                     <Button
-                        elementRef={ref as React.Ref<HTMLButtonElement>}
-                        {...targetProps}
+                        onClick={() => {
+                            onCustomFirmwareZip(undefined);
+                        }}
                     >
-                        {i18n.translate('selectHubPanel.notOnListButton.label')}
+                        {i18n.translate('selectHubPanel.customFirmware.clearButton')}
                     </Button>
-                )}
-            />
+                </>
+            ) : (
+                <>
+                    <p>{i18n.translate('selectHubPanel.message')}</p>
+                    <HubPicker />
+                    <Popover2
+                        popoverClassName={Classes2.POPOVER2_CONTENT_SIZING}
+                        placement="right-end"
+                        content={<UnsupportedHubs />}
+                        renderTarget={({ isOpen: _isOpen, ref, ...targetProps }) => (
+                            <Button
+                                elementRef={ref as React.Ref<HTMLButtonElement>}
+                                {...targetProps}
+                            >
+                                {i18n.translate('selectHubPanel.notOnListButton.label')}
+                            </Button>
+                        )}
+                    />
+                </>
+            )}
+            <div className="pb-firmware-installPybricksDialog-selectHub-advanced">
+                <Button
+                    minimal={true}
+                    small={true}
+                    icon={isAdvancedOpen ? 'chevron-down' : 'chevron-right'}
+                    onClick={() => setIsAdvancedOpen((v) => !v)}
+                >
+                    {i18n.translate('selectHubPanel.advanced.label')}
+                </Button>
+                <Collapse isOpen={isAdvancedOpen}>
+                    <div
+                        {...getRootProps({
+                            className: 'pb-dropzone-root',
+                            onClick,
+                            onKeyDown,
+                        })}
+                    >
+                        <input {...getInputProps()} />
+                        {i18n.translate(
+                            'selectHubPanel.advanced.customFirmwareDropzone.label',
+                        )}
+                    </div>
+                </Collapse>
+            </div>
         </div>
     );
 };
@@ -144,27 +313,38 @@ const SelectHubPanel: React.VoidFunctionComponent = () => {
 type AcceptLicensePanelProps = {
     hubType: Hub;
     licenseAccepted: boolean;
+    customFirmwareZip: File | undefined;
     onLicenseAcceptedChanged: (accepted: boolean) => void;
 };
 
 const AcceptLicensePanel: React.VoidFunctionComponent<AcceptLicensePanelProps> = ({
     hubType,
     licenseAccepted,
+    customFirmwareZip,
     onLicenseAcceptedChanged,
 }) => {
-    const { data, error } = useFirmware(hubType);
+    const { firmwareData, firmwareError } = useFirmware(hubType);
+    const { isCustomFirmwareRequested, customFirmwareData, customFirmwareError } =
+        useCustomFirmware(customFirmwareZip);
     const i18n = useI18n();
 
+    const selectedFirmwareData = isCustomFirmwareRequested
+        ? customFirmwareData
+        : firmwareData;
+    const selectedFirmwareError = isCustomFirmwareRequested
+        ? customFirmwareError
+        : firmwareError;
+
     return (
         <div className={dialogBody}>
             <div className="pb-firmware-installPybricksDialog-license-text">
-                {data ? (
-                    <Pre>{data.licenseText}</Pre>
+                {selectedFirmwareData ? (
+                    <Pre>{selectedFirmwareData.licenseText}</Pre>
                 ) : (
                     <NonIdealState
-                        icon={error ? 'error' : <Spinner />}
+                        icon={selectedFirmwareError ? 'error' : <Spinner />}
                         description={
-                            error
+                            selectedFirmwareError
                                 ? i18n.translate('licensePanel.licenseText.error')
                                 : undefined
                         }
@@ -176,7 +356,7 @@ const AcceptLicensePanel: React.VoidFunctionComponent<AcceptLicensePanelProps> =
                 label={i18n.translate('licensePanel.acceptCheckbox.label')}
                 checked={licenseAccepted}
                 onChange={(e) => onLicenseAcceptedChanged(e.currentTarget.checked)}
-                disabled={!data}
+                disabled={!selectedFirmwareData}
             />
         </div>
     );
@@ -441,9 +621,19 @@ export const InstallPybricksDialog: React.VoidFunctionComponent = () => {
     const [selectedIncludeFile, setSelectedIncludeFile] = useState<FileMetadata>();
     const [licenseAccepted, setLicenseAccepted] = useState(false);
     const [hubType] = useHubPickerSelectedHub();
-    const { data } = useFirmware(hubType);
+    const { firmwareData } = useFirmware(hubType);
+    const [customFirmwareZip, setCustomFirmwareZip] = useState<File>();
+    const { isCustomFirmwareRequested, customFirmwareData } =
+        useCustomFirmware(customFirmwareZip);
     const i18n = useI18n();
 
+    const selectedFirmwareData = isCustomFirmwareRequested
+        ? customFirmwareData
+        : firmwareData;
+    const selectedHubType = isCustomFirmwareRequested
+        ? getHubTypeFromMetadata(customFirmwareData?.metadata, hubType)
+        : hubType;
+
     return (
         <MultistepDialog
             title={i18n.translate('title')}
@@ -454,8 +644,8 @@ export const InstallPybricksDialog: React.VoidFunctionComponent = () => {
                 onClick: () =>
                     dispatch(
                         firmwareInstallPybricksDialogAccept(
-                            hubBootloaderType(hubType),
-                            data?.firmwareZip ?? new ArrayBuffer(0),
+                            hubBootloaderType(selectedHubType),
+                            selectedFirmwareData?.firmwareZip ?? new ArrayBuffer(0),
                             selectedIncludeFile?.path,
                             hubName,
                         ),
@@ -465,7 +655,12 @@ export const InstallPybricksDialog: React.VoidFunctionComponent = () => {
             <DialogStep
                 id="hub"
                 title={i18n.translate('selectHubPanel.title')}
-                panel={<SelectHubPanel />}
+                panel={
+                    <SelectHubPanel
+                        customFirmwareZip={customFirmwareZip}
+                        onCustomFirmwareZip={setCustomFirmwareZip}
+                    />
+                }
                 nextButtonProps={{ text: i18n.translate('nextButton.label') }}
             />
             <DialogStep
@@ -473,8 +668,9 @@ export const InstallPybricksDialog: React.VoidFunctionComponent = () => {
                 title={i18n.translate('licensePanel.title')}
                 panel={
                     <AcceptLicensePanel
-                        hubType={hubType}
+                        hubType={selectedHubType}
                         licenseAccepted={licenseAccepted}
+                        customFirmwareZip={customFirmwareZip}
                         onLicenseAcceptedChanged={setLicenseAccepted}
                     />
                 }
@@ -489,7 +685,7 @@ export const InstallPybricksDialog: React.VoidFunctionComponent = () => {
                 title={i18n.translate('optionsPanel.title')}
                 panel={
                     <ConfigureOptionsPanel
-                        hubType={hubType}
+                        hubType={selectedHubType}
                         hubName={hubName}
                         includeProgram={includeProgram}
                         selectedIncludeFile={selectedIncludeFile}
@@ -504,7 +700,7 @@ export const InstallPybricksDialog: React.VoidFunctionComponent = () => {
             <DialogStep
                 id="bootloader"
                 title={i18n.translate('bootloaderPanel.title')}
-                panel={<BootloaderModePanel hubType={hubType} />}
+                panel={<BootloaderModePanel hubType={selectedHubType} />}
                 backButtonProps={{ text: i18n.translate('backButton.label') }}
             />
         </MultistepDialog>

src/firmware/installPybricksDialog/hooks.ts

@@ -2,26 +2,30 @@
 // Copyright (c) 2022 The Pybricks Authors
 // based on https://usehooks-ts.com/react-hook/use-fetch
 
-import { FirmwareReader } from '@pybricks/firmware';
+import { FirmwareMetadata, FirmwareReader } from '@pybricks/firmware';
 import cityHubZip from '@pybricks/firmware/build/cityhub.zip';
 import essentialHubZip from '@pybricks/firmware/build/essentialhub.zip';
 import moveHubZip from '@pybricks/firmware/build/movehub.zip';
 import primeHubZip from '@pybricks/firmware/build/primehub.zip';
 import technicHubZip from '@pybricks/firmware/build/technichub.zip';
-import { useEffect, useReducer, useRef } from 'react';
+import { useEffect, useMemo, useReducer, useRef } from 'react';
+import { useDispatch } from 'react-redux';
 import { useIsMounted } from 'usehooks-ts';
+import { alertsShowAlert } from '../../alerts/actions';
 import { Hub } from '../../components/hubPicker';
+import { ensureError } from '../../utils';
 
 type FirmwareData = {
     firmwareZip: ArrayBuffer;
     licenseText: string;
+    metadata: FirmwareMetadata;
 };
 
 interface State {
     /** The firmware.zip data or undefined if `fetch()` is not complete or on error. */
-    data?: FirmwareData;
+    firmwareData?: FirmwareData;
     /** Undefined `fetch()` is not complete yet or was successful, otherwise the error. */
-    error?: Error;
+    firmwareError?: Error;
 }
 
 type Cache = { [url: string]: FirmwareData };
@@ -52,8 +56,8 @@ export function useFirmware(hubType: Hub): State {
     const isMounted = useIsMounted();
 
     const initialState: State = {
-        error: undefined,
-        data: undefined,
+        firmwareError: undefined,
+        firmwareData: undefined,
     };
 
     // Keep state logic separated
@@ -62,9 +66,9 @@ export function useFirmware(hubType: Hub): State {
             case 'loading':
                 return { ...initialState };
             case 'fetched':
-                return { ...initialState, data: action.payload };
+                return { ...initialState, firmwareData: action.payload };
             case 'error':
-                return { ...initialState, error: action.payload };
+                return { ...initialState, firmwareError: action.payload };
             default:
                 return state;
         }
@@ -96,7 +100,8 @@ export function useFirmware(hubType: Hub): State {
                 const firmwareZip = await response.arrayBuffer();
                 const reader = await FirmwareReader.load(firmwareZip);
                 const licenseText = await reader.readReadMeOss();
-                const data = { firmwareZip, licenseText };
+                const metadata = await reader.readMetadata();
+                const data = { firmwareZip, licenseText, metadata };
 
                 cache.current[url] = data;
 
@@ -114,7 +119,7 @@ export function useFirmware(hubType: Hub): State {
                     return;
                 }
 
-                dispatch({ type: 'error', payload: error as Error });
+                dispatch({ type: 'error', payload: ensureError(error) });
             }
         };
 
@@ -123,3 +128,90 @@ export function useFirmware(hubType: Hub): State {
 
     return state;
 }
+
+/**
+ * Gets the data from the user-provided firmware file, if any.
+ * @param zipFile The user-provided zip file.
+ * @returns State consisting of unzipped data or error.
+ */
+export function useCustomFirmware(zipFile: File | undefined) {
+    const reduxDispatch = useDispatch();
+    const isMounted = useIsMounted();
+
+    const initialState: State = {
+        firmwareError: undefined,
+        firmwareData: undefined,
+    };
+
+    // Keep state logic separated
+    const fetchReducer = (state: State, action: Action): State => {
+        switch (action.type) {
+            case 'loading':
+                return { ...initialState };
+            case 'fetched':
+                return { ...initialState, firmwareData: action.payload };
+            case 'error':
+                return { ...initialState, firmwareError: action.payload };
+            default:
+                return state;
+        }
+    };
+
+    const [state, dispatch] = useReducer(fetchReducer, initialState);
+
+    useEffect(() => {
+        if (!zipFile) {
+            dispatch({ type: 'loading' });
+            return;
+        }
+
+        // REVISIT: with no cache, we end up unzipping the same file multiple times.
+
+        const readFile = async () => {
+            dispatch({ type: 'loading' });
+
+            try {
+                const firmwareZip = await zipFile.arrayBuffer();
+                const reader = await FirmwareReader.load(firmwareZip);
+                const licenseText = await reader.readReadMeOss();
+                const metadata = await reader.readMetadata();
+                const data = {
+                    firmwareZip,
+                    licenseText,
+                    metadata,
+                };
+
+                if (!isMounted()) {
+                    return;
+                }
+
+                dispatch({ type: 'fetched', payload: data });
+            } catch (err) {
+                if (process.env.NODE_ENV !== 'test') {
+                    console.error(err);
+                }
+
+                if (!isMounted()) {
+                    return;
+                }
+
+                const error = ensureError(err);
+                dispatch({ type: 'error', payload: error });
+                reduxDispatch(alertsShowAlert('alerts', 'unexpectedError', { error }));
+            }
+        };
+
+        readFile();
+    }, [zipFile, isMounted]);
+
+    const isCustomFirmwareRequested = useMemo(
+        () => state.firmwareData !== undefined,
+        [state.firmwareData],
+    );
+
+    return {
+        isCustomFirmwareRequested,
+        customFirmwareData: state.firmwareData,
+        customFirmwareError: state.firmwareError,
+    };
+}

src/firmware/installPybricksDialog/installPybricksDialog.scss

@@ -12,6 +12,13 @@
         gap: bp.$pt-grid-size;
     }
 
+    &-selectHub {
+        &-advanced {
+            margin-top: auto;
+            width: 100%;
+        }
+    }
+
     &-license {
         &-text {
             flex-grow: 1;

src/firmware/installPybricksDialog/translations/en.json

@@ -20,6 +20,18 @@
                     "footnote": "firmware cannot be updated"
                 }
             }
+        },
+        "advanced": {
+            "label": "Advanced",
+            "customFirmwareDropzone": {
+                "label": "Drop custom firmware .zip file here or click to browse."
+            }
+        },
+        "customFirmware": {
+            "message": "Custom firmware selected.",
+            "hubType": "Hub Type: {hubTypeName}",
+            "firmwareVersion": "Firmware Version: {version}",
+            "clearButton": "Clear"
         }
     },
     "licensePanel": {

src/index.scss

@@ -60,6 +60,29 @@ body {
     white-space: nowrap;
 }
 
+// shared styles
+
+.pb-dropzone-root {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    padding: bp.$pt-grid-size * 2;
+    border-width: 2;
+    border-radius: 2;
+    border-style: dashed;
+    border-color: bp.$pt-divider-black;
+    background-color: bp.$pt-app-background-color;
+    color: bp.$pt-text-color-muted;
+    outline: none;
+    transition: border 0.24s ease-in-out;
+
+    .#{bp.$ns}-dark & {
+        border-color: bp.$pt-dark-divider-white;
+        background-color: bp.$pt-dark-app-background-color;
+        color: bp.$pt-dark-text-color-muted;
+    }
+}
+
 // global style tweaks
 
 .#{bp.$ns}-toast {

src/index.tsx

@@ -68,6 +68,27 @@ if (appVersion.match(/beta/)) {
     document.body.classList.add('pb-beta');
 }
 
+// prevent default drag/drop which just "downloads" any file dropped anywhere
+// in the browser window
+
+const dragEventHandler = (e: DragEvent) => {
+    if (
+        e.target instanceof Element &&
+        !e.target.classList.contains('pb-dropzone-root')
+    ) {
+        e.preventDefault();
+
+        if (e.dataTransfer) {
+            e.dataTransfer.effectAllowed = 'none';
+            e.dataTransfer.dropEffect = 'none';
+        }
+    }
+};
+
+window.addEventListener('dragenter', dragEventHandler, false);
+window.addEventListener('dragover', dragEventHandler);
+window.addEventListener('drop', dragEventHandler);
+
 sagaMiddleware.run(rootSaga);
 
 ReactDOM.render(