diff --git a/.vscode/settings.json b/.vscode/settings.json index c8feebb..ec700c4 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -26,7 +26,7 @@ "prettier.printWidth": 120, // Code spell checker ignored words - "cSpell.words": [], + "cSpell.words": ["Bootloader", "Buttonless", "Softdevice"], "[swift]": { "editor.defaultFormatter": "vknabel.vscode-swiftformat" } diff --git a/README.md b/README.md index b10eae3..0ef1205 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@

Nordic DFU

@capacitor-community/nordic-dfu

- Capacitor plugin to interface with Nordic DFU's [IOS-DFU-Library](https://github.com/NordicSemiconductor/IOS-DFU-Library) and [Android-DFU-Library](https://github.com/NordicSemiconductor/Android-DFU-Library). + Capacitor plugin to interface with Nordic DFU's IOS-DFU-Library and Android-DFU-Library.

@@ -21,6 +21,7 @@ - [Maintainers](#maintainers) - [Installation](#installation) +- [Permissions](#permissions) - [API](#api) ## Maintainers @@ -36,6 +37,10 @@ npm install @capacitor-community/nordic-dfu npx cap sync ``` +## Permissions + +Please check the sample permissions in [Android](./example/android/app/src/main/AndroidManifest.xml) and [iOS](./example/ios/App/App/Info.plist) folders. + ## API @@ -54,7 +59,8 @@ npx cap sync -The plugin definition for the Nordic DFU plugin +Defines the plugin for handling Nordic DFU processes. +Includes methods to start the DFU process, check permissions, and manage event listeners. ### startDFU(...) @@ -62,14 +68,16 @@ The plugin definition for the Nordic DFU plugin startDFU(dfuUpdateOptions: DfuUpdateOptions) => Promise ``` -Starts the DFU process +Initiates the DFU process with the specified options. -| Param | Type | Description | -| ---------------------- | ------------------------------------------------------------- | ------------------------------- | -| **`dfuUpdateOptions`** | DfuUpdateOptions | The options for the DFU process | +| Param | Type | Description | +| ---------------------- | ------------------------------------------------------------- | ---------------------------- | +| **`dfuUpdateOptions`** | DfuUpdateOptions | Options for the DFU process. | **Returns:** Promise<void | PluginResultError> +**Since:** 1.0.0 + --- ### checkPermissions() @@ -78,10 +86,12 @@ Starts the DFU process checkPermissions() => Promise ``` -Check plugin permissions +Check status of permissions needed by the plugin **Returns:** Promise<PermissionStatus> +**Since:** 1.0.0 + --- ### requestPermissions() @@ -90,10 +100,12 @@ Check plugin permissions requestPermissions() => Promise ``` -Request permissions needed bu the plugin +Request permissions needed by the plugin **Returns:** Promise<PermissionStatus> +**Since:** 1.0.0 + --- ### addListener('DFUStateChanged', ...) @@ -111,6 +123,8 @@ Listen for when the DFU state changes **Returns:** Promise<PluginListenerHandle> & PluginListenerHandle +**Since:** 1.0.0 + --- ### removeAllListeners() @@ -121,6 +135,8 @@ removeAllListeners() => Promise Removes all listeners for the DFUStateChanged event +**Since:** 1.0.0 + --- ### Interfaces @@ -133,44 +149,46 @@ Removes all listeners for the DFUStateChanged event #### DfuUpdateOptions -The options for the DFU process +Specifies the options required for initiating the DFU process. -| Prop | Type | Description | -| ------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -| **`deviceAddress`** | string | The target device address. On **Android** this is the BLE MAC address. On **iOS** and **web** it is a randomly generated UUID identifier. | -| **`deviceName`** | string | The name of the device | -| **`filePath`** | string | The path to the firmware file | -| **`dfuOptions`** | DfuOptions | The options for the DFU process | +| Prop | Type | Description | Since | +| ------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ----- | +| **`deviceAddress`** | string | The target device address. On **Android** this is the BLE MAC address. On **iOS** and **web** it is a randomly generated UUID identifier. | 1.0.0 | +| **`deviceName`** | string | The name of the device | 1.0.0 | +| **`filePath`** | string | The path to the firmware file | 1.0.0 | +| **`dfuOptions`** | DfuOptions | The additional options for the DFU process | 1.0.0 | #### DfuOptions -| Prop | Type | Description | -| ----------------------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **`disableNotification`** | boolean | Sets whether the progress notification in the status bar should be disabled. Defaults to false. | -| **`startAsForegroundService`** | boolean | Sets whether the progress notification in the status bar should be disabled. Defaults to false. | -| **`keepBond`** | boolean | Sets whether the bond information should be preserver after flashing new application. Defaults to false. | -| **`restoreBond`** | boolean | Sets whether a new bond should be created after the DFU is complete. The old bond information will be removed before. Defaults to false. | -| **`dataObjectDelay`** | number | Sets the initial delay (in milliseconds) that the service will wait before sending each data object. Defaults to 0. | -| **`packetReceiptNotificationsEnabled`** | boolean | Enables or disables the Packet Receipt Notification (PRN) procedure. By default the PRNs are disabled on devices with Android Marshmallow or newer and enabled on older ones. | -| **`packetsReceiptNotificationsValue`** | number | If Packet Receipt Notification procedure is enabled, this method sets the number of packets to be sent before receiving a PRN. Defaults to 12. | -| **`forceDfu`** | boolean | Setting force DFU to true will prevent from jumping to the DFU Bootloader mode in case there is no DFU Version characteristic (Legacy DFU only!). Use this if the DFU operation can be handled by your device running in the application mode. This method is ignored in Secure DFU. Defaults to false. | -| **`rebootTime`** | number | Sets the time (in milliseconds) required by the device to reboot. The library will wait for this time before scanning for the device in bootloader mode. Defaults to 0 ms. | -| **`scanTimeout`** | number | Sets the scan duration (in milliseconds) when scanning for DFU Bootloader. Defaults to 5000. | -| **`forceScanningForNewAddressInLegacyDfu`** | boolean | When this is set to true, the Legacy Buttonless Service will scan for the device advertising with an incremented MAC address, instead of trying to reconnect to the same device. Defaults to false. | -| **`numberOfRetries`** | number | Sets the number of retries that the DFU service will use to complete DFU. Defaults to 0. | -| **`mtu`** | number | Sets the Maximum Transfer Unit (MTU) value that the Secure DFU service will try to request before performing DFU. By default, value 517 will be used, which is the highest supported y Android. However, as the highest supported MTU by the Secure DFU from SDK 15 (first which supports higher MTU) is 247, the sides will agree on using MTU = 247 instead if the phone supports it (Lollipop or newer device). | -| **`currentMtu`** | number | Sets the current MTU value. This method should be used only if the device is already connected and MTU has been requested before DFU service is started. Defaults to 23. | -| **`scope`** | number | This method allows to narrow the update to selected parts from the ZIP, for example to allow only application update from a ZIP file that has SD+BL+App. System components scope include the Softdevice and/or the Bootloader (they can't be separated as they are packed in a single bin file and the library does not know whether it contains only the softdevice, the bootloader or both) Application scope includes the application only. | -| **`mbrSize`** | number | This method sets the size of an MBR (Master Boot Record). It should be used only when updating a file from a HEX file. If you use BIN or ZIP, value set here will be ignored. Defaults to 4096 (0x1000) bytes. | -| **`unsafeExperimentalButtonlessServiceInSecureDfuEnabled`** | boolean | Set this flag to true to enable experimental buttonless feature in Secure DFU. When the experimental Buttonless DFU Service is found on a device, the service will use it to switch the device to the bootloader mode, connect to it in that mode and proceed with DFU. Defaults to false. | +Outlines additional options for configuring the DFU process. + +| Prop | Type | Description | Default | Since | +| ----------------------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- | +| **`disableNotification`** | boolean | Sets whether the progress notification in the status bar should be disabled. | false | 1.0.0 | +| **`startAsForegroundService`** | boolean | Sets whether the progress notification in the status bar should be disabled. | false | 1.0.0 | +| **`keepBond`** | boolean | Sets whether the bond information should be preserver after flashing new application. | false | 1.0.0 | +| **`restoreBond`** | boolean | Sets whether a new bond should be created after the DFU is complete. The old bond information will be removed before. | false | 1.0.0 | +| **`dataObjectDelay`** | number | Sets the initial delay (in milliseconds) that the service will wait before sending each data object. | 0 | 1.0.0 | +| **`packetReceiptNotificationsEnabled`** | boolean | Enables or disables the Packet Receipt Notification (PRN) procedure. By default the PRNs are disabled on devices with Android Marshmallow or newer and enabled on older ones. | | 1.0.0 | +| **`packetsReceiptNotificationsValue`** | number | If Packet Receipt Notification procedure is enabled, this method sets the number of packets to be sent before receiving a PRN. | 12 | 1.0.0 | +| **`forceDfu`** | boolean | Setting force DFU to true will prevent from jumping to the DFU Bootloader mode in case there is no DFU Version characteristic (Legacy DFU only!). Use this if the DFU operation can be handled by your device running in the application mode. This method is ignored in Secure DFU. | false | 1.0.0 | +| **`rebootTime`** | number | Sets the time (in milliseconds) required by the device to reboot. The library will wait for this time before scanning for the device in bootloader mode. | 0 | 1.0.0 | +| **`scanTimeout`** | number | Sets the scan duration (in milliseconds) when scanning for DFU Bootloader. | 5000 | 1.0.0 | +| **`forceScanningForNewAddressInLegacyDfu`** | boolean | When this is set to true, the Legacy Buttonless Service will scan for the device advertising with an incremented MAC address, instead of trying to reconnect to the same device. | false | 1.0.0 | +| **`numberOfRetries`** | number | Sets the number of retries that the DFU service will use to complete DFU. | 0 | 1.0.0 | +| **`mtu`** | number | Sets the Maximum Transfer Unit (MTU) value that the Secure DFU service will try to request before performing DFU. By default, value 517 will be used, which is the highest supported y Android. However, as the highest supported MTU by the Secure DFU from SDK 15 (first which supports higher MTU) is 247, the sides will agree on using MTU = 247 instead if the phone supports it (Lollipop or newer device). | | 1.0.0 | +| **`currentMtu`** | number | Sets the current MTU value. This method should be used only if the device is already connected and MTU has been requested before DFU service is started. | 23 | 1.0.0 | +| **`scope`** | number | This method allows to narrow the update to selected parts from the ZIP, for example to allow only application update from a ZIP file that has SD+BL+App. System components scope include the Softdevice and/or the Bootloader (they can't be separated as they are packed in a single bin file and the library does not know whether it contains only the softdevice, the bootloader or both) Application scope includes the application only. | | 1.0.0 | +| **`mbrSize`** | number | This method sets the size of an MBR (Master Boot Record). It should be used only when updating a file from a HEX file. If you use BIN or ZIP, value set here will be ignored. | 4096 | 1.0.0 | +| **`unsafeExperimentalButtonlessServiceInSecureDfuEnabled`** | boolean | Set this flag to true to enable experimental buttonless feature in Secure DFU. When the experimental Buttonless DFU Service is found on a device, the service will use it to switch the device to the bootloader mode, connect to it in that mode and proceed with DFU. | false | 1.0.0 | #### PermissionStatus -The current status of permissions in the plugin +Represents the current status of permissions in the plugin. -| Prop | Type | Description | -| ------------------- | ----------------------------------------------------------- | ---------------------------------- | -| **`notifications`** | PermissionState | Permission state of notifications. | +| Prop | Type | Description | Since | +| ------------------- | ----------------------------------------------------------- | ------------------------------------------------ | ----- | +| **`notifications`** | PermissionState | Indicates the permission state of notifications. | 1.0.0 | #### PluginListenerHandle @@ -182,22 +200,22 @@ The current status of permissions in the plugin The DFU update object that is passed to the DFUStateChanged event -| Prop | Type | Description | -| ----------- | ------------------------------------------------------- | ---------------------------------------------------------------------------- | -| **`state`** | DfuState | The DFU state that is passed to the DfuUpdate | -| **`data`** | DfuUpdateData | The DFU data that is passed to the DfuUpdate object | +| Prop | Type | Description | Since | +| ----------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------ | ----- | +| **`state`** | DfuState | Defines the structure for the DFU update object passed to the DFUStateChanged event. | 1.0.0 | +| **`data`** | DfuUpdateData | The DFU data that is passed to the DfuUpdate object | 1.0.0 | #### DfuUpdateData -The DFU data that is passed to the DfuUpdate object +Contains data related to the DFU update process, such as progress and speed. -| Prop | Type | Description | -| ----------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **`percent`** | number | The current status of upload (0-99). | -| **`speed`** | number | The current speed in bytes per millisecond. | -| **`avgSpeed`** | number | The average speed in bytes per millisecond. | -| **`currentPart`** | number | The number pf part being sent. In case the ZIP file contains a Soft Device and/or a Bootloader together with the application the SD+BL are sent as part 1, then the service starts again and send the application as part 2. | -| **`partsTotal`** | number | The total number of parts. | +| Prop | Type | Description | Since | +| ----------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | +| **`percent`** | number | The current status of upload (0-99). | 1.0.0 | +| **`speed`** | number | The current speed in bytes per millisecond. | 1.0.0 | +| **`avgSpeed`** | number | The average speed in bytes per millisecond. | 1.0.0 | +| **`currentPart`** | number | The number of parts being sent. In case the ZIP file contains a Soft Device and/or a Bootloader together with the application the SD+BL are sent as part 1, then the service starts again and send the application as part 2. | 1.0.0 | +| **`partsTotal`** | number | The total number of parts. | 1.0.0 | ### Type Aliases @@ -209,60 +227,19 @@ The DFU data that is passed to the DfuUpdate object #### DfuState -| Members | Value | Description | -| -------------------------- | ----------------------------------- | ------------------------------------------------------------------ | -| **`DEVICE_CONNECTING`** | 'DEVICE_CONNECTING' | The device is currently connecting. | -| **`DEVICE_CONNECTED`** | 'DEVICE_CONNECTED' | The device has successfully connected. Available for Android only. | -| **`DFU_PROCESS_STARTING`** | 'DFU_PROCESS_STARTING' | The DFU process is about to start. | -| **`DFU_PROCESS_STARTED`** | 'DFU_PROCESS_STARTED' | The DFU process has started. Available for Android only. | -| **`ENABLING_DFU_MODE`** | 'ENABLING_DFU_MODE' | The device is enabling DFU mode. | -| **`DFU_PROGRESS`** | 'DFU_PROGRESS' | The DFU process is in progress. | -| **`VALIDATING_FIRMWARE`** | 'VALIDATING_FIRMWARE' | The firmware is currently being validated. | -| **`DEVICE_DISCONNECTING`** | 'DEVICE_DISCONNECTING' | The device is disconnecting. | -| **`DEVICE_DISCONNECTED`** | 'DEVICE_DISCONNECTED' | The device has disconnected. Available for Android only. | -| **`DFU_COMPLETED`** | 'DFU_COMPLETED' | The DFU process has completed successfully. | -| **`DFU_ABORTED`** | 'DFU_ABORTED' | The DFU process has been aborted. | -| **`DFU_FAILED`** | 'DFU_FAILED' | The DFU process has failed. | +| Members | Value | Description | Since | +| -------------------------- | ----------------------------------- | ------------------------------------------------------------------ | ----- | +| **`DEVICE_CONNECTING`** | 'DEVICE_CONNECTING' | The device is currently connecting. | 1.0.0 | +| **`DEVICE_CONNECTED`** | 'DEVICE_CONNECTED' | The device has successfully connected. Available for Android only. | 1.0.0 | +| **`DFU_PROCESS_STARTING`** | 'DFU_PROCESS_STARTING' | The DFU process is about to start. | 1.0.0 | +| **`DFU_PROCESS_STARTED`** | 'DFU_PROCESS_STARTED' | The DFU process has started. Available for Android only. | 1.0.0 | +| **`ENABLING_DFU_MODE`** | 'ENABLING_DFU_MODE' | The device is enabling DFU mode. | 1.0.0 | +| **`DFU_PROGRESS`** | 'DFU_PROGRESS' | The DFU process is in progress. | 1.0.0 | +| **`VALIDATING_FIRMWARE`** | 'VALIDATING_FIRMWARE' | The firmware is currently being validated. | 1.0.0 | +| **`DEVICE_DISCONNECTING`** | 'DEVICE_DISCONNECTING' | The device is disconnecting. | 1.0.0 | +| **`DEVICE_DISCONNECTED`** | 'DEVICE_DISCONNECTED' | The device has disconnected. Available for Android only. | 1.0.0 | +| **`DFU_COMPLETED`** | 'DFU_COMPLETED' | The DFU process has completed successfully. | 1.0.0 | +| **`DFU_ABORTED`** | 'DFU_ABORTED' | The DFU process has been aborted. | 1.0.0 | +| **`DFU_FAILED`** | 'DFU_FAILED' | The DFU process has failed. | 1.0.0 | - -### List of Error Codes and Meanings - - - -When an error is thrown, one of the following codes (as a string value) will be used. - -| Code | Description | -| ----: | :------------------- | -| '1' | `INTERNAL_ERROR` | -| '2' | `INVALID_ARGUMENT` | -| ' '8' | `FILE_NOT_SUPPORTED` | -| '9' | `FILE_NOT_FOUND` | -| '10' | `UNKNOWN` | - -### Android - - - -If you app needs to open files in the external directories, then within your `AndroidManifest.xml` file, change the following: - -```diff - - - -+ - - -``` - -### iOS - - - -You'll need to set ios/App/Podfile to version 13 or higher (for more details please [see](https://capacitorjs.com/docs/ios#ios-support)) - -``` -platform :ios '13.0' -``` - -then `npx cap sync ios` diff --git a/src/definitions.ts b/src/definitions.ts index 263217e..f655052 100644 --- a/src/definitions.ts +++ b/src/definitions.ts @@ -1,146 +1,203 @@ import type { PluginListenerHandle, PluginResultError, PermissionState } from '@capacitor/core'; /** - * The current status of permissions in the plugin + * Represents the current status of permissions in the plugin. + * + * @since 1.0.0 */ export interface PermissionStatus { /** - * Permission state of notifications. + * Indicates the permission state of notifications. + * + * @since 1.0.0 */ notifications: PermissionState; } /** - * The DFU state that is passed to the DfuUpdate + * Enumerates the various states in the DFU process. This helps in tracking the progress and status of the + * firmware update. + * + * @since 1.0.0 */ export enum DfuState { /** * The device is currently connecting. + * + * @since 1.0.0 */ DEVICE_CONNECTING = 'DEVICE_CONNECTING', /** * The device has successfully connected. Available for Android only. + * + * @since 1.0.0 */ DEVICE_CONNECTED = 'DEVICE_CONNECTED', /** * The DFU process is about to start. + * + * @since 1.0.0 */ DFU_PROCESS_STARTING = 'DFU_PROCESS_STARTING', /** * The DFU process has started. Available for Android only. + * + * @since 1.0.0 */ DFU_PROCESS_STARTED = 'DFU_PROCESS_STARTED', /** * The device is enabling DFU mode. + * + * @since 1.0.0 */ ENABLING_DFU_MODE = 'ENABLING_DFU_MODE', /** * The DFU process is in progress. + * + * @since 1.0.0 */ DFU_PROGRESS = 'DFU_PROGRESS', /** * The firmware is currently being validated. + * + * @since 1.0.0 */ VALIDATING_FIRMWARE = 'VALIDATING_FIRMWARE', /** * The device is disconnecting. + * + * @since 1.0.0 */ DEVICE_DISCONNECTING = 'DEVICE_DISCONNECTING', /** * The device has disconnected. Available for Android only. + * + * @since 1.0.0 */ DEVICE_DISCONNECTED = 'DEVICE_DISCONNECTED', /** * The DFU process has completed successfully. + * + * @since 1.0.0 */ DFU_COMPLETED = 'DFU_COMPLETED', /** * The DFU process has been aborted. + * + * @since 1.0.0 */ DFU_ABORTED = 'DFU_ABORTED', /** * The DFU process has failed. + * + * @since 1.0.0 */ DFU_FAILED = 'DFU_FAILED', } /** - * The DFU data that is passed to the DfuUpdate object + * Contains data related to the DFU update process, such as progress and speed. + * + * @since 1.0.0 */ export interface DfuUpdateData { /** * The current status of upload (0-99). + * + * @since 1.0.0 */ percent?: number; /** * The current speed in bytes per millisecond. + * + * @since 1.0.0 */ speed?: number; /** * The average speed in bytes per millisecond. + * + * @since 1.0.0 */ avgSpeed?: number; /** - * The number pf part being sent. In case the ZIP file contains a Soft Device and/or a Bootloader together + * The number of parts being sent. In case the ZIP file contains a Soft Device and/or a Bootloader together * with the application the SD+BL are sent as part 1, then the service starts again and send the application * as part 2. + * + * @since 1.0.0 */ currentPart?: number; /** * The total number of parts. + * + * @since 1.0.0 */ partsTotal?: number; } /** * The DFU update object that is passed to the DFUStateChanged event + * + * @since 1.0.0 */ export interface DfuUpdate { /** - * The DFU state that is passed to the DfuUpdate + * Defines the structure for the DFU update object passed to the DFUStateChanged event. + * + * @since 1.0.0 */ state: DfuState; /** * The DFU data that is passed to the DfuUpdate object + * + * @since 1.0.0 */ data: DfuUpdateData; } +/** + * Outlines additional options for configuring the DFU process. + * + * @since 1.0.0 + */ export interface DfuOptions { /** * Sets whether the progress notification in the status bar should be disabled. * - * Defaults to false. + * @default false + * @since 1.0.0 */ disableNotification?: boolean; /** * Sets whether the progress notification in the status bar should be disabled. * - * Defaults to false. + * @default false + * @since 1.0.0 */ startAsForegroundService?: boolean; /** * Sets whether the bond information should be preserver after flashing new application. * - * Defaults to false. + * @default false + * @since 1.0.0 */ keepBond?: boolean; @@ -148,14 +205,16 @@ export interface DfuOptions { * Sets whether a new bond should be created after the DFU is complete. The old bond * information will be removed before. * - * Defaults to false. + * @default false + * @since 1.0.0 */ restoreBond?: boolean; /** * Sets the initial delay (in milliseconds) that the service will wait before sending each data object. * - * Defaults to 0. + * @default 0 + * @since 1.0.0 */ dataObjectDelay?: number; @@ -164,6 +223,8 @@ export interface DfuOptions { * * By default the PRNs are disabled on devices with Android Marshmallow or newer and enabled on * older ones. + * + * @since 1.0.0 */ packetReceiptNotificationsEnabled?: boolean; @@ -171,7 +232,8 @@ export interface DfuOptions { * If Packet Receipt Notification procedure is enabled, this method sets the number of packets to be sent before * receiving a PRN. * - * Defaults to 12. + * @default 12 + * @since 1.0.0 */ packetsReceiptNotificationsValue?: number; @@ -181,7 +243,8 @@ export interface DfuOptions { * Use this if the DFU operation can be handled by your device running in the application mode. * This method is ignored in Secure DFU. * - * Defaults to false. + * @default false + * @since 1.0.0 */ forceDfu?: boolean; @@ -189,14 +252,16 @@ export interface DfuOptions { * Sets the time (in milliseconds) required by the device to reboot. The library will wait for this time before * scanning for the device in bootloader mode. * - * Defaults to 0 ms. + * @default 0 + * @since 1.0.0 */ rebootTime?: number; /** * Sets the scan duration (in milliseconds) when scanning for DFU Bootloader. * - * Defaults to 5000. + * @default 5000 + * @since 1.0.0 */ scanTimeout?: number; @@ -204,13 +269,16 @@ export interface DfuOptions { * When this is set to true, the Legacy Buttonless Service will scan for the device advertising * with an incremented MAC address, instead of trying to reconnect to the same device. * - * Defaults to false. + * @default false + * @since 1.0.0 */ forceScanningForNewAddressInLegacyDfu?: boolean; /** * Sets the number of retries that the DFU service will use to complete DFU. - * Defaults to 0. + * + * @default 0 + * @since 1.0.0 */ numberOfRetries?: number; @@ -221,6 +289,8 @@ export interface DfuOptions { * By default, value 517 will be used, which is the highest supported y Android. However, as the * highest supported MTU by the Secure DFU from SDK 15 (first which supports higher MTU) is 247, * the sides will agree on using MTU = 247 instead if the phone supports it (Lollipop or newer device). + * + * @since 1.0.0 */ mtu?: number; @@ -228,7 +298,8 @@ export interface DfuOptions { * Sets the current MTU value. This method should be used only if the device is already * connected and MTU has been requested before DFU service is started. * - * Defaults to 23. + * @default 23 + * @since 1.0.0 */ currentMtu?: number; @@ -239,16 +310,17 @@ export interface DfuOptions { * a single bin file and the library does not know whether it contains only the softdevice, * the bootloader or both) Application scope includes the application only. * - * + * @since 1.0.0 */ - scope?: number; // TODO: scope enum and more info + scope?: number; /** * This method sets the size of an MBR (Master Boot Record). It should be used only * when updating a file from a HEX file. If you use BIN or ZIP, value set here will * be ignored. * - * Defaults to 4096 (0x1000) bytes. + * @default 4096 + * @since 1.0.0 */ mbrSize?: number; @@ -257,64 +329,100 @@ export interface DfuOptions { * experimental Buttonless DFU Service is found on a device, the service will use it to * switch the device to the bootloader mode, connect to it in that mode and proceed with DFU. * - * Defaults to false. + * @default false + * @since 1.0.0 */ unsafeExperimentalButtonlessServiceInSecureDfuEnabled?: boolean; - // customUuidsForLegacyDfu // TODO: figure out how to do this - // customUuidsForSecureDfu // TODO: figure out how to do this - // customUuidsForExperimentalButtonlessDfu // TODO: figure out how to do this - // customUuidsForButtonlessDfuWithBondSharing // TODO: figure out how to do this - // customUuidsForButtonlessDfuWithoutBondSharing // TODO: figure out how to do this } /** - * The options for the DFU process + * Specifies the options required for initiating the DFU process. + * + * @since 1.0.0 */ export interface DfuUpdateOptions { /** * The target device address. * On **Android** this is the BLE MAC address. * On **iOS** and **web** it is a randomly generated UUID identifier. + * + * @since 1.0.0 */ deviceAddress: string; /** * The name of the device + * + * @since 1.0.0 */ deviceName?: string; /** * The path to the firmware file + * + * @since 1.0.0 */ filePath: string; /** - * The options for the DFU process + * The additional options for the DFU process + * + * @since 1.0.0 */ dfuOptions?: DfuOptions; } /** - * The plugin definition for the Nordic DFU plugin + * Defines the plugin for handling Nordic DFU processes. + * Includes methods to start the DFU process, check permissions, and manage event listeners. + * + * @since 1.0.0 */ export interface NordicDfuPlugin { /** - * Starts the DFU process + * Initiates the DFU process with the specified options. * - * @param dfuUpdateOptions The options for the DFU process - * @returns A promise that resolves when the DFU process is complete or rejects with PluginResultError - * @example startDFU({ deviceAddress: '00:00:00:00:00:00', filePath: 'path/to/file.zip' }) + * @param dfuUpdateOptions Options for the DFU process. + * @returns A promise that resolves on successful completion of the DFU process or rejects with a PluginResultError. + * @example + * const dfuOptions: DfuOptions = { + * mtu: 23, + * currentMtu: 23, + * packetReceiptNotificationsEnabled: false, + * }; * + * const dfuUpdateOptions: DfuUpdateOptions = { + * deviceAddress: this.device.deviceId, + * deviceName: this.device.name, + * filePath: this.file.path, + * dfuOptions: dfuOptions, + * }; + * + * NordicDfu.startDFU(dfuUpdateOptions).then( + * () => console.log, + * (error: PluginResultError) => console.error + * ); + * @since 1.0.0 */ startDFU(dfuUpdateOptions: DfuUpdateOptions): Promise; /** - * Check plugin permissions + * Check status of permissions needed by the plugin + * + * @example + * const request = await NordicDfu.checkPermissions(); + * console.log(request) + * @since 1.0.0 */ checkPermissions(): Promise; /** - * Request permissions needed bu the plugin + * Request permissions needed by the plugin + * + * @example + * const request = await NordicDfu.requestPermissions(); + * console.log(request) + * @since 1.0.0 */ requestPermissions(): Promise; @@ -324,8 +432,11 @@ export interface NordicDfuPlugin { * @param eventName The name of the event to listen for * @param handler The handler function that will be called when the event is fired * @returns A promise that resolves with a PluginListenerHandle that can be used to remove the listener - * @example addListener('DFUStateChanged', (update) => { console.log(update) }) - * + * @example + * NordicDfu.addListener('DFUStateChanged', async (update: DfuUpdate) => { + * console.log(`DFU: state: ${update.state}, data: ${JSON.stringify(update.data)}`); + * } + * @since 1.0.0 */ addListener( eventName: 'DFUStateChanged', @@ -336,7 +447,9 @@ export interface NordicDfuPlugin { * Removes all listeners for the DFUStateChanged event * * @returns A promise that resolves when all listeners are removed - * @example removeAllListeners() + * @example + * NordicDfu.removeAllListeners(); + * @since 1.0.0 */ removeAllListeners(): Promise; }