firmware: add UI for EV3 firmware flashing

dlech · dlech · commit 007640c7b6f2 · 2025-08-09T21:51:47.000-05:00
This is just the UI bits (new file template, Pybricks firmware install,
official firmware restore).

The Pybricks firmware flashing hangs because we don't have a EV3 firmware
yet in @pybricks/firmware. Official firmware restore has an alert()
placeholder so at least it does something.
diff --git a/package.json b/package.json
@@ -13,7 +13,7 @@
         "@pmmmwh/react-refresh-webpack-plugin": "^0.5.11",
         "@pybricks/firmware": "7.22.0",
         "@pybricks/ide-docs": "2.20.0",
-        "@pybricks/images": "^1.3.0",
+        "@pybricks/images": "^1.4.0",
         "@pybricks/jedi": "1.17.0",
         "@pybricks/mpy-cross-v5": "^2.0.0",
         "@pybricks/mpy-cross-v6": "^2.0.0",
diff --git a/src/components/hubPicker/HubPicker.tsx b/src/components/hubPicker/HubPicker.tsx
@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// Copyright (c) 2022-2023 The Pybricks Authors
+// Copyright (c) 2022-2025 The Pybricks Authors
 
 import './hubPicker.scss';
 import { Radio, RadioGroup } from '@blueprintjs/core';
@@ -66,6 +66,12 @@ export const HubPicker: React.FunctionComponent<HubPickerProps> = ({ disabled })
                     label="MINDSTORMS Robot Inventor Hub"
                 />
             </Radio>
+            <Radio value={Hub.EV3}>
+                <HubIcon
+                    url={new URL('@pybricks/images/hub-ev3.png', import.meta.url)}
+                    label="MINDSTORMS EV3"
+                />
+            </Radio>
         </RadioGroup>
     );
 };
diff --git a/src/components/hubPicker/index.ts b/src/components/hubPicker/index.ts
@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// Copyright (c) 2022 The Pybricks Authors
+// Copyright (c) 2022-2025 The Pybricks Authors
 
 /** Supported hub types. */
 export enum Hub {
@@ -15,6 +15,8 @@ export enum Hub {
     Prime = 'primehub',
     /** SPIKE Essential hub */
     Essential = 'essentialhub',
+    /** MINDSTORMS EV3 hub */
+    EV3 = 'ev3',
 }
 
 /**
@@ -25,6 +27,7 @@ export function hubHasUSB(hub: Hub): boolean {
         case Hub.Prime:
         case Hub.Essential:
         case Hub.Inventor:
+        case Hub.EV3:
             return true;
         default:
             return false;
@@ -52,6 +55,7 @@ export function hubHasExternalFlash(hub: Hub): boolean {
         case Hub.Prime:
         case Hub.Essential:
         case Hub.Inventor:
+        case Hub.EV3:
             return true;
         default:
             return false;
@@ -69,5 +73,7 @@ export function hubBootloaderType(hub: Hub) {
         case Hub.City:
         case Hub.Technic:
             return 'ble-lwp3-bootloader';
+        case Hub.EV3:
+            return 'usb-ev3';
     }
 }
diff --git a/src/editor/pybricksMicroPython.ts b/src/editor/pybricksMicroPython.ts
@@ -309,7 +309,9 @@ export const language = <monaco.languages.IMonarchLanguage>{
  */
 function createTemplate(hubClassName: string, deviceClassNames: string[]): string {
     return `from pybricks.hubs import ${hubClassName}
-from pybricks.pupdevices import ${deviceClassNames.join(', ')}
+from pybricks.${
+        hubClassName === 'EV3Brick' ? 'ev3devices' : 'pupdevices'
+    } import ${deviceClassNames.join(', ')}
 from pybricks.parameters import Button, Color, Direction, Port, Side, Stop
 from pybricks.robotics import DriveBase
 from pybricks.tools import wait, StopWatch
@@ -325,7 +327,8 @@ type HubLabel =
     | 'technichub'
     | 'inventorhub'
     | 'primehub'
-    | 'essentialhub';
+    | 'essentialhub'
+    | 'ev3';
 
 const templateSnippets: Array<
     Required<
@@ -375,6 +378,18 @@ const templateSnippets: Array<
             'ColorLightMatrix',
         ]),
     },
+    {
+        label: 'ev3',
+        documentation: 'Template for MINDSTORMS EV3 program.',
+        insertText: createTemplate('EV3Brick', [
+            'Motor',
+            'ColorSensor',
+            'GyroSensor',
+            'InfraredSensor',
+            'TouchSensor',
+            'UltrasonicSensor',
+        ]),
+    },
 ];
 
 /**
diff --git a/src/firmware/actions.ts b/src/firmware/actions.ts
@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// Copyright (c) 2020-2022 The Pybricks Authors
+// Copyright (c) 2020-2025 The Pybricks Authors
 
 import { FirmwareReaderError, HubType } from '@pybricks/firmware';
 import { createAction } from '../actions';
@@ -429,3 +429,39 @@ export const firmwareDidRestoreOfficialDfu = createAction(() => ({
 export const firmwareDidFailToRestoreOfficialDfu = createAction(() => ({
     type: 'firmware.action.didFailToRestoreOfficialDfu',
 }));
+
+/**
+ * Versions of official LEGO EV3 firmware available for restore.
+ */
+export enum EV3OfficialFirmwareVersion {
+    /** Official LEGO EV3 firmware version 1.09H (Home edition). */
+    home = '1.09H',
+    /** Official LEGO EV3 firmware version 1.09E (Education edition). */
+    education = '1.09E',
+    /** Official LEGO EV3 firmware version 1.10E (only useful for Microsoft MakeCode). */
+    makecode = '1.10E',
+}
+
+/**
+ * Action that triggers the restore official EV3 firmware saga.
+ */
+export const firmwareRestoreOfficialEV3 = createAction(
+    (version: EV3OfficialFirmwareVersion) => ({
+        type: 'firmware.action.restoreOfficialEV3',
+        version,
+    }),
+);
+
+/**
+ * Action that indicates {@link firmwareRestoreOfficialEV3} succeeded.
+ */
+export const firmwareDidRestoreOfficialEV3 = createAction(() => ({
+    type: 'firmware.action.didRestoreOfficialEV3',
+}));
+
+/**
+ * Action that indicates {@link firmwareRestoreOfficialEV3} failed.
+ */
+export const firmwareDidFailToRestoreOfficialEV3 = createAction(() => ({
+    type: 'firmware.action.didFailToRestoreOfficialEV3',
+}));
diff --git a/src/firmware/bootloaderInstructions/BootloaderInstructions.tsx b/src/firmware/bootloaderInstructions/BootloaderInstructions.tsx
@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// Copyright (c) 2022-2023 The Pybricks Authors
+// Copyright (c) 2022-2025 The Pybricks Authors
 
 import './bootloaderInstructions.scss';
 import { Callout, Intent } from '@blueprintjs/core';
@@ -117,7 +117,11 @@ const BootloaderInstructions: React.FunctionComponent<BootloaderInstructionsProp
     const { button, light, lightPattern } = useMemo(() => {
         return {
             button: i18n.translate(
-                hubHasBluetoothButton(hubType) ? 'button.bluetooth' : 'button.power',
+                hubType === Hub.EV3
+                    ? 'button.right'
+                    : hubHasBluetoothButton(hubType)
+                      ? 'button.bluetooth'
+                      : 'button.power',
             ),
             light: i18n.translate(
                 hubHasBluetoothButton(hubType) ? 'light.bluetooth' : 'light.status',
@@ -163,13 +167,16 @@ const BootloaderInstructions: React.FunctionComponent<BootloaderInstructionsProp
     const prepareSteps = useMemo(
         () => (
             <>
-                <li>
-                    {i18n.translate(
-                        hubHasUSB(hubType)
-                            ? 'instructionGroup.prepare.usb'
-                            : 'instructionGroup.prepare.batteries',
-                    )}
-                </li>
+                {hubType !== Hub.EV3 && (
+                    <li>
+                        {i18n.translate(
+                            hubHasUSB(hubType)
+                                ? 'instructionGroup.prepare.usb'
+                                : 'instructionGroup.prepare.batteries',
+                        )}
+                    </li>
+                )}
+
                 <li>{i18n.translate('instructionGroup.prepare.turnOff')}</li>
                 {/* For non-usb recovery, show step about official app */}
                 {recovery && !hubHasUSB(hubType) && (
@@ -179,6 +186,12 @@ const BootloaderInstructions: React.FunctionComponent<BootloaderInstructionsProp
                         })}
                     </li>
                 )}
+
+                {hubType === Hub.EV3 && (
+                    <li>
+                        {i18n.translate('instructionGroup.bootloaderMode.connectUsb')}
+                    </li>
+                )}
             </>
         ),
         [i18n, recovery, hubType],
@@ -210,28 +223,36 @@ const BootloaderInstructions: React.FunctionComponent<BootloaderInstructionsProp
 
                 {/* not strictly necessary, but order is swapped in the video,
                     so we match it here. */}
-                {hubType !== Hub.Essential && hubHasUSB(hubType) && (
+                {(hubType === Hub.Prime || hubType === Hub.Inventor) &&
+                    hubHasUSB(hubType) && (
+                        <li
+                            className={classNames(
+                                activeStep === 'connect-usb' && 'pb-active-step',
+                            )}
+                        >
+                            {i18n.translate(
+                                'instructionGroup.bootloaderMode.connectUsb',
+                            )}
+                        </li>
+                    )}
+
+                {hubType !== Hub.EV3 && (
                     <li
                         className={classNames(
-                            activeStep === 'connect-usb' && 'pb-active-step',
+                            activeStep === 'wait-for-light' && 'pb-active-step',
                         )}
                     >
-                        {i18n.translate('instructionGroup.bootloaderMode.connectUsb')}
+                        {i18n.translate(
+                            'instructionGroup.bootloaderMode.waitForLight',
+                            {
+                                button,
+                                light,
+                                lightPattern,
+                            },
+                        )}
                     </li>
                 )}
 
-                <li
-                    className={classNames(
-                        activeStep === 'wait-for-light' && 'pb-active-step',
-                    )}
-                >
-                    {i18n.translate('instructionGroup.bootloaderMode.waitForLight', {
-                        button,
-                        light,
-                        lightPattern,
-                    })}
-                </li>
-
                 {hubType === Hub.Essential && hubHasUSB(hubType) && (
                     <li
                         className={classNames(
@@ -242,6 +263,18 @@ const BootloaderInstructions: React.FunctionComponent<BootloaderInstructionsProp
                     </li>
                 )}
 
+                {hubType === Hub.EV3 && (
+                    <li
+                        className={classNames(
+                            activeStep === 'press-power-button' && 'pb-active-step',
+                        )}
+                    >
+                        {i18n.translate(
+                            'instructionGroup.bootloaderMode.pressPowerButtonEV3',
+                        )}
+                    </li>
+                )}
+
                 {recovery && !hubHasUSB(hubType) && (
                     <li
                         className={classNames(
@@ -262,7 +295,9 @@ const BootloaderInstructions: React.FunctionComponent<BootloaderInstructionsProp
                         )}
                     >
                         {i18n.translate(
-                            'instructionGroup.bootloaderMode.releaseButton',
+                            hubType === Hub.EV3
+                                ? 'instructionGroup.bootloaderMode.releaseButtonsEV3'
+                                : 'instructionGroup.bootloaderMode.releaseButton',
                             {
                                 button,
                             },
@@ -342,6 +377,13 @@ const BootloaderInstructions: React.FunctionComponent<BootloaderInstructionsProp
                             1
                         }
                     >
+                        {hubType === Hub.EV3 && (
+                            <li>
+                                {i18n.translate(
+                                    'instructionGroup.connect.selectEV3FirmwareType',
+                                )}
+                            </li>
+                        )}
                         <li>
                             {i18n.translate(
                                 'instructionGroup.connect.clickConnectAndFlash',
@@ -389,7 +431,7 @@ const BootloaderInstructions: React.FunctionComponent<BootloaderInstructionsProp
                 </Callout>
             )}
 
-            {hubHasUSB(hubType) && isWindows() && (
+            {hubHasUSB(hubType) && hubType !== Hub.EV3 && isWindows() && (
                 <Callout intent={Intent.WARNING} icon={<WarningSign />}>
                     {i18n.translate('warning.windows.message', {
                         instructions: (
diff --git a/src/firmware/bootloaderInstructions/translations/en.json b/src/firmware/bootloaderInstructions/translations/en.json
@@ -11,7 +11,8 @@
     },
     "button": {
         "bluetooth": "Bluetooth button",
-        "power": "button"
+        "power": "button",
+        "right": "right button"
     },
     "light": {
         "bluetooth": "Bluetooth light",
@@ -37,10 +38,13 @@
             "waitForLight": "Wait for the {light} to start blinking {lightPattern}.",
             "waitAppConnect": "The app will automatically connect and start restoring the firmware.",
             "releaseButton": "Release the {button}.",
-            "keepHolding": "Keep holding the {button} in the next steps. We'll tell you when to let go."
+            "keepHolding": "Keep holding the {button} in the next steps. We'll tell you when to let go.",
+            "pressPowerButtonEV3": "Press the center button to turn on the EV3.",
+            "releaseButtonsEV3": "When the screen says \"Updating...\", release both buttons."
         },
         "connect": {
             "title": "Install:",
+            "selectEV3FirmwareType": "Select the version of firmware to restore below.",
             "clickConnectAndFlash": "Click the {flashButton} button below.",
             "selectDevice": "In the pop-up dialog, select {deviceName} and click {connectButton}.",
             "connectButton": "Connect"
diff --git a/src/firmware/installPybricksDialog/InstallPybricksDialog.tsx b/src/firmware/installPybricksDialog/InstallPybricksDialog.tsx
@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// Copyright (c) 2022-2023 The Pybricks Authors
+// Copyright (c) 2022-2025 The Pybricks Authors
 
 import './installPybricksDialog.scss';
 import {
@@ -142,11 +142,6 @@ const UnsupportedHubs: React.FunctionComponent = () => {
                         'selectHubPanel.notOnListButton.info.mindstorms.nxt',
                     )}
                 </li>
-                <li>
-                    {i18n.translate(
-                        'selectHubPanel.notOnListButton.info.mindstorms.ev3',
-                    )}
-                </li>
             </ul>
             <h4>
                 {i18n.translate('selectHubPanel.notOnListButton.info.poweredUp.title')}
diff --git a/src/firmware/installPybricksDialog/actions.ts b/src/firmware/installPybricksDialog/actions.ts
@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// Copyright (c) 2022 The Pybricks Authors
+// Copyright (c) 2022-2025 The Pybricks Authors
 
 import { createAction } from '../../actions';
 
@@ -8,7 +8,7 @@ export const firmwareInstallPybricksDialogShow = createAction(() => ({
     type: 'firmware.installPybricksDialog.action.show',
 }));
 
-type FlashMethod = 'ble-lwp3-bootloader' | 'usb-lego-dfu';
+type FlashMethod = 'ble-lwp3-bootloader' | 'usb-lego-dfu' | 'usb-ev3';
 
 /**
  * Action that indicates the user accepted the install Pybricks firmware dialog.
diff --git a/src/firmware/installPybricksDialog/translations/en.json b/src/firmware/installPybricksDialog/translations/en.json
@@ -14,8 +14,7 @@
                         "sponsor": "sponsor"
                     },
                     "rcx": "RCX: Might work in streaming mode.",
-                    "nxt": "NXT: We have tested this. It could work!",
-                    "ev3": "EV3: Supported using Visual Studio Code."
+                    "nxt": "NXT: We have tested this. It could work!"
                 },
                 "poweredUp": {
                     "title": "Other hubs",
diff --git a/src/firmware/restoreOfficialDialog/RestoreOfficialDialog.tsx b/src/firmware/restoreOfficialDialog/RestoreOfficialDialog.tsx
diff --git a/src/firmware/restoreOfficialDialog/translations/en.json b/src/firmware/restoreOfficialDialog/translations/en.json
diff --git a/src/firmware/sagas.ts b/src/firmware/sagas.ts
diff --git a/yarn.lock b/yarn.lock
