firmware: Firmware must be sector size multiple.

If the EV3 firmware size is not a multiple of the sector size,
the flashing process will hang. Raise an error if this happens.

Author: jaguilar

src/firmware/actions.ts

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// Copyright (c) 2020-2025 The Pybricks Authors
+// Copyright (c) 2020-2026 The Pybricks Authors
 
 import { FirmwareReaderError, HubType } from '@pybricks/firmware';
 import { createAction } from '../actions';
@@ -47,6 +47,8 @@ export enum FailToFinishReasonType {
     FailedToCompile = 'flashFirmware.failToFinish.reason.failedToCompile',
     /** The combined firmware-base.bin and main.mpy are too big. */
     FirmwareSize = 'flashFirmware.failToFinish.reason.firmwareSize',
+    /** The firmware's start or end is not aligned to the sector boundary. */
+    FirmwareAlignment = 'flashFirmware.failToFinish.reason.firmwareAlignment',
     /** An unexpected error occurred. */
     Unknown = 'flashFirmware.failToFinish.reason.unknown',
 }
@@ -94,6 +96,9 @@ export type FailToFinishReasonBadMetadata =
 export type FailToFinishReasonFirmwareSize =
     Reason<FailToFinishReasonType.FirmwareSize>;
 
+export type FailToFinishReasonFirmwareAlignment =
+    Reason<FailToFinishReasonType.FirmwareAlignment>;
+
 export type FailToFinishReasonFailedToCompile =
     Reason<FailToFinishReasonType.FailedToCompile>;
 
@@ -113,6 +118,7 @@ export type FailToFinishReason =
     | FailToFinishReasonZipError
     | FailToFinishReasonBadMetadata
     | FailToFinishReasonFirmwareSize
+    | FailToFinishReasonFirmwareAlignment
     | FailToFinishReasonFailedToCompile
     | FailToFinishReasonUnknown;
 

src/firmware/sagas.ts

@@ -1241,6 +1241,20 @@ function* handleFlashEV3(action: ReturnType<typeof firmwareFlashEV3>): Generator
     // FIXME: should be called much earlier.
     yield* put(didStart());
 
+    console.debug(`Firmware size: ${action.firmware.byteLength} bytes`);
+
+    // Apparently, erasing a span of the flash creates some sort of record in
+    // the EV3, and we can only write within a given erase span. Writes that
+    // cross the boundary will hang. To avoid this, we erase the whole firmware
+    // range at once.
+    const sectorSize = 64 * 1024; // flash memory sector size
+    if (action.firmware.byteLength % sectorSize !== 0) {
+        yield* put(didFailToFinish(FailToFinishReasonType.FirmwareAlignment));
+        yield* put(firmwareDidFailToFlashEV3());
+        yield* cleanup();
+        return;
+    }
+
     const maxPayloadSize = 1018; // maximum payload size for EV3 commands
 
     const erasePayload = new DataView(new ArrayBuffer(8));

src/notifications/i18n.ts

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// Copyright (c) 2020-2022 The Pybricks Authors
+// Copyright (c) 2020-2025 The Pybricks Authors
 //
 // Notification translation keys.
 
@@ -35,6 +35,7 @@ export enum I18nId {
     FlashFirmwareBadMetadata = 'flashFirmware.badMetadata',
     FlashFirmwareCompileError = 'flashFirmware.compileError',
     FlashFirmwareSizeTooBig = 'flashFirmware.sizeTooBig',
+    FlashFirmwareAlignment = 'flashFirmware.alignment',
     FlashFirmwareUnexpectedError = 'flashFirmware.unexpectedError',
     ServiceWorkerUpdateMessage = 'serviceWorker.update.message',
     ServiceWorkerUpdateAction = 'serviceWorker.update.action',

src/notifications/sagas.test.ts

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// Copyright (c) 2021-2023 The Pybricks Authors
+// Copyright (c) 2021-2025 The Pybricks Authors
 
 import type { ToastOptions, Toaster } from '@blueprintjs/core';
 import { FirmwareReaderError, FirmwareReaderErrorCode } from '@pybricks/firmware';
@@ -95,6 +95,7 @@ test.each([
     ),
     didFailToFinish(FailToFinishReasonType.FailedToCompile),
     didFailToFinish(FailToFinishReasonType.FirmwareSize),
+    didFailToFinish(FailToFinishReasonType.FirmwareAlignment),
     didFailToFinish(FailToFinishReasonType.Unknown, new Error('test error')),
     appDidCheckForUpdate(false),
     fileStorageDidFailToInitialize(new Error('test error')),

src/notifications/sagas.ts

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// Copyright (c) 2020-2023 The Pybricks Authors
+// Copyright (c) 2020-2026 The Pybricks Authors
 
 // Saga for managing notifications (toasts)
 
@@ -228,6 +228,9 @@ function* showFlashFirmwareError(
         case FailToFinishReasonType.FirmwareSize:
             yield* showSingleton(Level.Error, I18nId.FlashFirmwareSizeTooBig);
             break;
+        case FailToFinishReasonType.FirmwareAlignment:
+            yield* showSingleton(Level.Error, I18nId.FlashFirmwareAlignment);
+            break;
         case FailToFinishReasonType.Unknown:
             yield* showUnexpectedError(
                 I18nId.FlashFirmwareUnexpectedError,

src/notifications/translations/en.json

@@ -33,6 +33,7 @@
         "badMetadata": "The firmware.metadata.json file contains missing or invalid entries. Fix it then try again.",
         "compileError": "The included main.py file could not be compiled. Fix it then try again.",
         "sizeTooBig": "The combined firmware and main.py are too big to fit in the flash memory.",
+        "alignment": "The firmware's start or end is not aligned to the sector boundary.",
         "unexpectedError": "Unexpected error while trying to install firmware: {errorMessage}"
     },
     "mpy": {