dfu/no.nordicsemi.android.dfu/DfuServiceInitiator

DfuServiceInitiator

class DfuServiceInitiator

A helper class for starting a DFU process on a remote device supporting Legacy or Secure DFU services from nRF5 SDK.

Starting a DFU Service service requires a knowledge of some EXTRA_* constants used to pass parameters to the service. The DfuServiceInitiator class may be used to make this process easier. It provides simple API that covers all low lever operations.

How to use it

    final DfuServiceController controller = new DfuServiceInitiator(mSelectedDevice.getAddress())
     .setDeviceName(mSelectedDevice.getName())
     .setKeepBond(true)
     .setZip(mFileStreamUri)
     .start(this, DfuService.class);
Content copied to clipboard

To upgrade devices with an old versions of DFU Bootloader it may be necessary to enable package receipt notifications (PRNs) using setPacketsReceiptNotificationsEnabled and set the value to 6 or lower using setPacketsReceiptNotificationsValue. This will slow down the upload, but will make it more reliable.

Constructors

Link copied to clipboard
constructor(@NonNull deviceAddress: String)
Creates the initiator instance for a device with the given MAC address.

Properties

Link copied to clipboard
val DEFAULT_MBR_SIZE: Int = 4096
The default maximum size of the data block.
Link copied to clipboard
val DEFAULT_PRN_VALUE: Int = 12
The default packet receipt notification value.
Link copied to clipboard
val DEFAULT_SCAN_TIMEOUT: Long = 5000
The default scan timeout in milliseconds.
Link copied to clipboard
val SCOPE_APPLICATION: Int = 2
Constant used to narrow the scope of the update to application only.
Link copied to clipboard
val SCOPE_SYSTEM_COMPONENTS: Int = 1
Constant used to narrow the scope of the update to system components (SD+BL) only.

Functions

Link copied to clipboard
@RequiresApi(api = Build.VERSION_CODES.O)
open fun createDfuNotificationChannel(@NonNull context: Context)
Creates a notification channel for the DFU service with default name and description.
@RequiresApi(api = Build.VERSION_CODES.O)
open fun createDfuNotificationChannel(@NonNull context: Context, @NonNull dfu_channel_name: String, @NonNull dfu_channel_description: String, showBadge: Boolean)
Creates a notification channel for the DFU service.
Link copied to clipboard
open fun disableMtuRequest(): DfuServiceInitiator
Disables MTU request.
Link copied to clipboard
open fun disableResume(): DfuServiceInitiator
This options allows to disable the resume feature in Secure DFU.
Link copied to clipboard
open fun setBinOrHex(fileType: Int, @NonNull uri: Uri): DfuServiceInitiator
open fun setBinOrHex(fileType: Int, @NonNull path: String): DfuServiceInitiator
Sets the URI of the BIN or HEX file containing the new firmware.
open fun setBinOrHex(fileType: Int, @RawRes rawResId: Int): DfuServiceInitiator
Sets the resource ID pointing the BIN or HEX file containing the new firmware.
open fun setBinOrHex(fileType: Int, @Nullable uri: Uri, @Nullable path: String): DfuServiceInitiator
Sets the URI or path to the BIN or HEX file containing the new firmware.
Link copied to clipboard
open fun setCurrentMtu(@IntRange(from = 23, to = 517) mtu: Int): DfuServiceInitiator
Sets the current MTU value.
open fun setCustomUuidsForButtonlessDfuWithBondSharing(@Nullable buttonlessDfuServiceUuid: UUID, @Nullable buttonlessDfuControlPointUuid: UUID): DfuServiceInitiator
Sets custom UUIDs for the Buttonless DFU Service from SDK 14 (or later).
open fun setCustomUuidsForButtonlessDfuWithoutBondSharing(@Nullable buttonlessDfuServiceUuid: UUID, @Nullable buttonlessDfuControlPointUuid: UUID): DfuServiceInitiator
Sets custom UUIDs for the Buttonless DFU Service from SDK 13.
open fun setCustomUuidsForExperimentalButtonlessDfu(@Nullable buttonlessDfuServiceUuid: UUID, @Nullable buttonlessDfuControlPointUuid: UUID): DfuServiceInitiator
Sets custom UUIDs for the experimental Buttonless DFU Service from SDK 12.x.
Link copied to clipboard
open fun setCustomUuidsForLegacyDfu(@Nullable dfuServiceUuid: UUID, @Nullable dfuControlPointUuid: UUID, @Nullable dfuPacketUuid: UUID, @Nullable dfuVersionUuid: UUID): DfuServiceInitiator
Sets custom UUIDs for Legacy DFU and Legacy Buttonless DFU.
Link copied to clipboard
open fun setCustomUuidsForSecureDfu(@Nullable dfuServiceUuid: UUID, @Nullable dfuControlPointUuid: UUID, @Nullable dfuPacketUuid: UUID): DfuServiceInitiator
Sets custom UUIDs for Secure DFU.
Link copied to clipboard
open fun setDeviceName(@Nullable name: String): DfuServiceInitiator
Sets the device name.
Link copied to clipboard
open fun setDisableNotification(disableNotification: Boolean): DfuServiceInitiator
Sets whether the progress notification in the status bar should be disabled.
Link copied to clipboard
open fun setForceDfu(force: Boolean): DfuServiceInitiator
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!).
Link copied to clipboard
open fun setForceScanningForNewAddressInLegacyDfu(force: Boolean): DfuServiceInitiator
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.
Link copied to clipboard
open fun setForeground(foreground: Boolean): DfuServiceInitiator
Sets whether the DFU service should be started as a foreground service.
Link copied to clipboard
open fun setInitFile(@NonNull initFileUri: Uri): DfuServiceInitiator
Sets the URI of the Init file.
open fun setInitFile(@RawRes initFileResId: Int): DfuServiceInitiator
Sets the resource ID of the Init file.
open fun setInitFile(@Nullable initFilePath: String): DfuServiceInitiator
Sets the path to the Init file.
open fun setInitFile(@Nullable initFileUri: Uri, @Nullable initFilePath: String): DfuServiceInitiator
Sets the URI or path to the Init file.
Link copied to clipboard
open fun setKeepBond(keepBond: Boolean): DfuServiceInitiator
Sets whether the bond information should be preserver after flashing new application.
Link copied to clipboard
open fun setMbrSize(@IntRange(from = 0) mbrSize: Int): DfuServiceInitiator
This method sets the size of an MBR (Master Boot Record).
Link copied to clipboard
open fun setMtu(@IntRange(from = 23, to = 517) mtu: Int): DfuServiceInitiator
Sets the Maximum Transfer Unit (MTU) value that the Secure DFU service will try to request before performing DFU.
Link copied to clipboard
open fun setNumberOfRetries(@IntRange(from = 0) max: Int): DfuServiceInitiator
Sets the number of retries that the DFU service will use to complete DFU.
Link copied to clipboard
open fun setPacketsReceiptNotificationsEnabled(enabled: Boolean): DfuServiceInitiator
Enables or disables the Packet Receipt Notification (PRN) procedure.
Link copied to clipboard
open fun setPacketsReceiptNotificationsValue(@IntRange(from = 0) number: Int): DfuServiceInitiator
If Packet Receipt Notification procedure is enabled, this method sets number of packets to be sent before receiving a PRN.
Link copied to clipboard
open fun setPrepareDataObjectDelay(delay: Long): DfuServiceInitiator
This method sets the duration of a delay, that the service will wait before sending each data object in Secure DFU.
Link copied to clipboard
open fun setRebootTime(rebootTime: Long): DfuServiceInitiator
Sets the time required by the device to reboot.
Link copied to clipboard
open fun setRestoreBond(restoreBond: Boolean): DfuServiceInitiator
Sets whether a new bond should be created after the DFU is complete.
Link copied to clipboard
open fun setScanTimeout(scanTimeout: Long): DfuServiceInitiator
Sets the scan duration (in milliseconds) when scanning for DFU Bootloader.
Link copied to clipboard
open fun setScope(scope: Int): DfuServiceInitiator
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.
open fun setUnsafeExperimentalButtonlessServiceInSecureDfuEnabled(enable: Boolean): DfuServiceInitiator
Set this flag to true to enable experimental buttonless feature in Secure DFU.
Link copied to clipboard
open fun setZip(@NonNull uri: Uri): DfuServiceInitiator
Sets the URI to the Distribution packet (ZIP) or to a ZIP file matching the deprecated naming convention.
open fun setZip(@RawRes rawResId: Int): DfuServiceInitiator
Sets the resource ID of the Distribution packet (ZIP) or the a ZIP file matching the deprecated naming convention.
open fun setZip(@NonNull path: String): DfuServiceInitiator
Sets the path to the Distribution packet (ZIP) or the a ZIP file matching the deprecated naming convention.
open fun setZip(@Nullable uri: Uri, @Nullable path: String): DfuServiceInitiator
Sets the URI or path of the ZIP file.
Link copied to clipboard
open fun start(@NonNull context: Context, @NonNull service: Class<out DfuBaseService>): DfuServiceController
Starts the DFU service.