firmware/bootloaderInstructions: extract component

This extracts the instructions for placing a hub in bootloader mode to a separate component so that it can be shared.
2026-09-15 11:04:49 +00:00 · 2022-11-18 19:28:00 -06:00
parent f167f168ee
commit 44169bd178
5 changed files with 161 additions and 141 deletions
@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2022 The Pybricks Authors
+
+import { Callout, Intent } from '@blueprintjs/core';
+import React, { useMemo } from 'react';
+import {
+    pybricksUsbDfuWindowsDriverInstallUrl,
+    pybricksUsbLinuxUdevRulesUrl,
+} from '../../app/constants';
+import { Hub, hubHasBluetoothButton, hubHasUSB } from '../../components/hubPicker';
+import ExternalLinkIcon from '../../utils/ExternalLinkIcon';
+import { isLinux, isWindows } from '../../utils/os';
+import { useI18n } from './i18n';
+
+type BootloaderInstructionsProps = {
+    hubType: Hub;
+};
+
+/**
+ * Provides customized instructions on how to enter bootloader mode based
+ * on the hub type.
+ */
+const BootloaderInstructions: React.VoidFunctionComponent<
+    BootloaderInstructionsProps
+> = ({ hubType }) => {
+    const i18n = useI18n();
+
+    const { button, light, lightPattern } = useMemo(() => {
+        return {
+            button: i18n.translate(
+                hubHasBluetoothButton(hubType) ? 'button.bluetooth' : 'button.power',
+            ),
+            light: i18n.translate(
+                hubHasBluetoothButton(hubType) ? 'light.bluetooth' : 'light.status',
+            ),
+            lightPattern: i18n.translate(
+                hubHasBluetoothButton(hubType)
+                    ? 'lightPattern.bluetooth'
+                    : 'lightPattern.status',
+            ),
+        };
+    }, [i18n, hubType]);
+
+    return (
+        <>
+            {hubHasUSB(hubType) && isLinux() && (
+                <Callout intent={Intent.WARNING} icon="warning-sign">
+                    {i18n.translate('warning.linux')}{' '}
+                    <a
+                        href={pybricksUsbLinuxUdevRulesUrl}
+                        target="_blank"
+                        rel="noreferrer"
+                    >
+                        {i18n.translate('warning.learnMore')}
+                    </a>
+                    <ExternalLinkIcon />
+                </Callout>
+            )}
+            {hubHasUSB(hubType) && isWindows() && (
+                <Callout intent={Intent.WARNING} icon="warning-sign">
+                    {i18n.translate('warning.windows')}{' '}
+                    <a
+                        href={pybricksUsbDfuWindowsDriverInstallUrl}
+                        target="_blank"
+                        rel="noreferrer"
+                    >
+                        {i18n.translate('warning.learnMore')}
+                    </a>
+                    <ExternalLinkIcon />
+                </Callout>
+            )}
+            <p>{i18n.translate('instruction')}</p>
+            <ol>
+                {hubHasUSB(hubType) && <li>{i18n.translate('step.disconnectUsb')}</li>}
+
+                <li>{i18n.translate('step.powerOff')}</li>
+
+                {/* City hub has power issues and requires disconnecting motors/sensors */}
+                {hubType === Hub.City && <li>{i18n.translate('step.disconnectIo')}</li>}
+
+                <li>{i18n.translate('step.holdButton', { button })}</li>
+
+                {hubHasUSB(hubType) && <li>{i18n.translate('step.connectUsb')}</li>}
+
+                <li>
+                    {i18n.translate('step.waitForLight', {
+                        button,
+                        light,
+                        lightPattern,
+                    })}
+                </li>
+
+                <li>
+                    {i18n.translate(
+                        /* hubs with USB will keep the power on, but other hubs won't */
+                        hubHasUSB(hubType) ? 'step.releaseButton' : 'step.keepHolding',
+                        {
+                            button,
+                        },
+                    )}
+                </li>
+            </ol>
+        </>
+    );
+};
+
+export default BootloaderInstructions;
@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2022 The Pybricks Authors
+
+import { useI18n as useShopifyI18n } from '@shopify/react-i18n';
+import type { TypedI18n } from '../../i18n';
+import type translations from './translations/en.json';
+
+export function useI18n(): TypedI18n<typeof translations> {
+    // istanbul ignore next: babel-loader rewrites this line
+    const [i18n] = useShopifyI18n();
+    return i18n;
+}
@@ -0,0 +1,30 @@
+{
+    "warning": {
+        "linux": "If you have never used Pybricks with USB on Linux, you will need to configure udev rules to allow permission before you can flash the hub firmware.",
+        "windows": " If you have never used Pybricks with USB on Windows, you may need to manually install a USB driver before you can flash the hub firmware.",
+        "learnMore": "Learn more."
+    },
+    "instruction": "To flash the firmware, the hub must be placed in bootloader mode. Follow the steps below to do this:",
+    "button": {
+        "bluetooth": "Bluetooth button",
+        "power": "power button"
+    },
+    "light": {
+        "bluetooth": "Bluetooth light",
+        "status": "hub status light"
+    },
+    "lightPattern": {
+        "bluetooth": "pink-green-blue-off",
+        "status": "light purple"
+    },
+    "step": {
+        "disconnectUsb": "Disconnect the USB cable from the hub.",
+        "powerOff": "Turn off the hub.",
+        "disconnectIo": "Disconnect all motors and sensors from the I/O ports on the hub.",
+        "holdButton": "Press and hold the {button} on the hub.",
+        "connectUsb": "Connect the USB cable.",
+        "waitForLight": "Keep holding the {button} and wait for the {light} to start flashing {lightPattern}. This takes about 5 seconds.",
+        "releaseButton": "Release the {button}",
+        "keepHolding": "Keep holding the {button}."
+    }
+}