Skip to content

Capacitor plugin to interface with Nordic's IOS-DFU-Library and Android-DFU-Library.

License

Notifications You must be signed in to change notification settings

robsonos/nordic-dfu

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

50 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation


Nordic DFU

capacitor-community-nordic-dfu

Capacitor plugin to interface with Nordic DFU's IOS-DFU-Library and Android-DFU-Library.

GitHub Workflow Status (with event)
Downloads from npmjs Version from npmjs GitHub contributors from allcontributors.org

Table of Contents

Maintainers

Maintainer GitHub Active
robsonos robsonos yes

Installation

npm install capacitor-community-nordic-dfu
npx cap sync

Permissions

Please check the sample permissions in Android and iOS folders.

API

Defines the plugin for handling Nordic DFU processes. Includes methods to start the DFU process, check permissions, and manage event listeners.

startDFU(...)

startDFU(dfuUpdateOptions: DfuUpdateOptions) => Promise<void | PluginResultError>

Initiates the DFU process with the specified options.

Param Type Description
dfuUpdateOptions DfuUpdateOptions Options for the DFU process.

Returns: Promise<void | PluginResultError>

Since: 1.0.0


checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Check status of permissions needed by the plugin

Returns: Promise<PermissionStatus>

Since: 1.0.0


requestPermissions()

requestPermissions() => Promise<PermissionStatus>

Request permissions needed by the plugin

Returns: Promise<PermissionStatus>

Since: 1.0.0


addListener('DFUStateChanged', ...)

addListener(eventName: 'DFUStateChanged', handler: (update: DfuUpdate) => void) => Promise<PluginListenerHandle> & PluginListenerHandle

Listen for when the DFU state changes

Param Type Description
eventName 'DFUStateChanged' The name of the event to listen for
handler (update: DfuUpdate) => void The handler function that will be called when the event is fired

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

Since: 1.0.0


removeAllListeners()

removeAllListeners() => Promise<void>

Removes all listeners for the DFUStateChanged event

Since: 1.0.0


Interfaces

PluginResultError

Prop Type
message string

DfuUpdateOptions

Specifies the options required for initiating 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

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
disableResume boolean This options allows to disable the resume feature in Secure DFU. When the extra value is set to true, the DFU will send Init Packet and Data again, despite the firmware might have been send partially before. By default, without setting this extra, or by setting it to false, the DFU will resume the previously cancelled upload if CRC values match. false 1.4.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. Available for Android only. 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. Available for Android only. 23 1.0.0
disableMtuRequest boolean Disables MTU request. Available for Android only. false 1.4.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

Represents the current status of permissions in the plugin.

Prop Type Description Since
notifications PermissionState Indicates the permission state of notifications. 1.0.0

PluginListenerHandle

Prop Type
remove () => Promise<void>

DfuUpdate

The DFU update object that is passed to the DFUStateChanged event

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

Contains data related to the DFU update process, such as progress and speed.

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
duration number The total time elapsed since the start of the DFU process in milliseconds 1.1.0
remainingTime number The estimated remaining time to the end of the DFU process in milliseconds 1.1.0

Type Aliases

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

Enums

DfuState

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

Contributors