no.nordicsemi.android.dfu

Class DfuServiceInitiator

java.lang.Object

no.nordicsemi.android.dfu.DfuServiceInitiator

public class DfuServiceInitiator
extends java.lang.Object

Starting the DfuService 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.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_PRN_VALUE
static int	SCOPE_APPLICATION Constant used to narrow the scope of the update to application only.
static int	SCOPE_SYSTEM_COMPONENTS Constant used to narrow the scope of the update to system components (SD+BL) only.

Constructor Summary

Constructors

Constructor and Description
DfuServiceInitiator(java.lang.String deviceAddress) Creates the builder.

Method Summary

Modifier and Type	Method and Description
static void	createDfuNotificationChannel(android.content.Context context)
DfuServiceInitiator	setBinOrHex(int fileType, int rawResId) Deprecated.
DfuServiceInitiator	setBinOrHex(int fileType, java.lang.String path) Deprecated.
DfuServiceInitiator	setBinOrHex(int fileType, android.net.Uri uri) Deprecated.
DfuServiceInitiator	setBinOrHex(int fileType, android.net.Uri uri, java.lang.String path) Deprecated. The Distribution packet (ZIP) should be used for DFU Bootloader version 0.5 or newer
DfuServiceInitiator	setCustomUuidsForButtonlessDfuWithBondSharing(java.util.UUID buttonlessDfuServiceUuid, java.util.UUID buttonlessDfuControlPointUuid) Sets custom UUIDs for the Buttonless DFU Service from SDK 14 (or later).
DfuServiceInitiator	setCustomUuidsForButtonlessDfuWithoutBondSharing(java.util.UUID buttonlessDfuServiceUuid, java.util.UUID buttonlessDfuControlPointUuid) Sets custom UUIDs for the Buttonless DFU Service from SDK 13.
DfuServiceInitiator	setCustomUuidsForExperimentalButtonlessDfu(java.util.UUID buttonlessDfuServiceUuid, java.util.UUID buttonlessDfuControlPointUuid) Sets custom UUIDs for the experimental Buttonless DFU Service from SDK 12.x.
DfuServiceInitiator	setCustomUuidsForLegacyDfu(java.util.UUID dfuServiceUuid, java.util.UUID dfuControlPointUuid, java.util.UUID dfuPacketUuid, java.util.UUID dfuVersionUuid) Sets custom UUIDs for Legacy DFU and Legacy Buttonless DFU.
DfuServiceInitiator	setCustomUuidsForSecureDfu(java.util.UUID dfuServiceUuid, java.util.UUID dfuControlPointUuid, java.util.UUID dfuPacketUuid) Sets custom UUIDs for Secure DFU.
DfuServiceInitiator	setDeviceName(java.lang.String name) Sets the device name.
DfuServiceInitiator	setDisableNotification(boolean disableNotification) Sets whether the progress notification in the status bar should be disabled.
DfuServiceInitiator	setForceDfu(boolean force) 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!).
DfuServiceInitiator	setInitFile(int initFileResId) Deprecated.
DfuServiceInitiator	setInitFile(java.lang.String initFilePath) Deprecated.
DfuServiceInitiator	setInitFile(android.net.Uri initFileUri) Deprecated.
DfuServiceInitiator	setInitFile(android.net.Uri initFileUri, java.lang.String initFilePath) Deprecated.
DfuServiceInitiator	setKeepBond(boolean keepBond) Sets whether the bond information should be preserver after flashing new application.
DfuServiceInitiator	setPacketsReceiptNotificationsEnabled(boolean enabled) Enables or disables the Packet Receipt Notification (PRN) procedure.
DfuServiceInitiator	setPacketsReceiptNotificationsValue(int number) If Packet Receipt Notification procedure is enabled, this method sets number of packets to be sent before receiving a PRN.
DfuServiceInitiator	setRestoreBond(boolean restoreBond) Sets whether the bond should be created after the DFU is complete.
DfuServiceInitiator	setScope(int scope) 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.
DfuServiceInitiator	setUnsafeExperimentalButtonlessServiceInSecureDfuEnabled(boolean enable) Set this flag to true to enable experimental buttonless feature in Secure DFU.
DfuServiceInitiator	setZip(int rawResId) Sets the resource ID of the Distribution packet (ZIP) or the a ZIP file matching the deprecated naming convention.
DfuServiceInitiator	setZip(java.lang.String path) Sets the path to the Distribution packet (ZIP) or the a ZIP file matching the deprecated naming convention.
DfuServiceInitiator	setZip(android.net.Uri uri) Sets the URI to the Distribution packet (ZIP) or to a ZIP file matching the deprecated naming convention.
DfuServiceInitiator	setZip(android.net.Uri uri, java.lang.String path) Sets the URI or path of the ZIP file.
DfuServiceController	start(android.content.Context context, java.lang.Class<? extends DfuBaseService> service) Starts the DFU service.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_PRN_VALUE

public static final int DEFAULT_PRN_VALUE

See Also:

Constant Field Values

SCOPE_SYSTEM_COMPONENTS

public static final int SCOPE_SYSTEM_COMPONENTS

Constant used to narrow the scope of the update to system components (SD+BL) only.

See Also:

Constant Field Values

SCOPE_APPLICATION

public static final int SCOPE_APPLICATION

Constant used to narrow the scope of the update to application only.

See Also:

Constant Field Values

Constructor Detail

DfuServiceInitiator

public DfuServiceInitiator(java.lang.String deviceAddress)

Creates the builder. Use setZip(...), or setBinOrHex(...) methods to specify the file you want to upload. In the latter case an init file may also be set using the setInitFile(...) method. Init files are required by DFU Bootloader version 0.5 or newer (SDK 7.0.0+).

Parameters:

deviceAddress - the target device device address

Method Detail

setDeviceName

public DfuServiceInitiator setDeviceName(java.lang.String name)

Sets the device name. The device name is not required. It's written in the notification during the DFU process. If not set the R.string.dfu_unknown_name value will be used.

Parameters:

name - the device name (optional)

Returns:

the builder

setDisableNotification

public DfuServiceInitiator setDisableNotification(boolean disableNotification)

Sets whether the progress notification in the status bar should be disabled. Defaults to false.

Parameters:

disableNotification - whether to disable the notification

Returns:

the builder

setKeepBond

public DfuServiceInitiator setKeepBond(boolean keepBond)

Sets whether the bond information should be preserver after flashing new application. This feature requires DFU Bootloader version 0.6 or newer (SDK 8.0.0+). Please see the DfuBaseService.EXTRA_KEEP_BOND for more information regarding requirements. Remember that currently updating the Soft Device will remove the bond information.

Parameters:

keepBond - whether the bond information should be preserved in the new application.

Returns:

the builder

setRestoreBond

public DfuServiceInitiator setRestoreBond(boolean restoreBond)

Sets whether the bond should be created after the DFU is complete. Please see the DfuBaseService.EXTRA_RESTORE_BOND for more information regarding requirements.

Parameters:

restoreBond - whether the bond should be created after the DFU is complete.

Returns:

the builder

setPacketsReceiptNotificationsEnabled

public DfuServiceInitiator setPacketsReceiptNotificationsEnabled(boolean enabled)

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.

Parameters:

enabled - true to enabled PRNs, false to disable

Returns:

the builder

See Also:

DfuSettingsConstants.SETTINGS_PACKET_RECEIPT_NOTIFICATION_ENABLED

setPacketsReceiptNotificationsValue

public DfuServiceInitiator setPacketsReceiptNotificationsValue(int number)

If Packet Receipt Notification procedure is enabled, this method sets number of packets to be sent before receiving a PRN. A PRN is used to synchronize the transmitter and receiver.

Parameters:

number - number of packets to be sent before receiving a PRN. Defaulted when set to 0.

Returns:

the builder

See Also:

setPacketsReceiptNotificationsEnabled(boolean), DfuSettingsConstants.SETTINGS_NUMBER_OF_PACKETS

setForceDfu

public DfuServiceInitiator setForceDfu(boolean force)

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 it if the DFU operation can be handled by your device running in the application mode.

If the DFU Version characteristic exists, the information whether to begin DFU operation, or jump to bootloader, is taken from that characteristic's value. The value returned equal to 0x0100 (read as: minor=1, major=0, or version 0.1) means that the device is in the application mode and buttonless jump to DFU Bootloader is supported.

However, if there is no DFU Version characteristic, a device may support only Application update (version from SDK 4.3.0), may support Soft Device, Bootloader and Application update but without buttonless jump to bootloader (SDK 6.0.0) or with buttonless jump (SDK 6.1.0).

In the last case, the DFU Library determines whether the device is in application mode or in DFU Bootloader mode by counting number of services: if no DFU Service found - device is in app mode and does not support buttonless jump, if the DFU Service is the only service found (except General Access and General Attribute services) - it assumes it is in DFU Bootloader mode and may start DFU immediately, if there is at least one service except DFU Service - the device is in application mode and supports buttonless jump. In the last case, if you want to perform DFU operation without jumping - call the setForceDfu(boolean) method with parameter equal to true.

This method is ignored in Secure DFU.

Parameters:

force - true to ensure the DFU will start if there is no DFU Version characteristic (Legacy DFU only)

Returns:

the builder

See Also:

DfuSettingsConstants.SETTINGS_ASSUME_DFU_NODE

setScope

public DfuServiceInitiator setScope(int scope)

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.

Parameters:

scope - the update scope, one of SCOPE_SYSTEM_COMPONENTS or SCOPE_APPLICATION.

Returns:

the builder

setUnsafeExperimentalButtonlessServiceInSecureDfuEnabled

public DfuServiceInitiator setUnsafeExperimentalButtonlessServiceInSecureDfuEnabled(boolean enable)

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.

Please, read the information below before setting it to true.

In the SDK 12.x the Buttonless DFU feature for Secure DFU was experimental. It is NOT recommended to use it: it was not properly tested, had implementation bugs (e.g. link) and does not required encryption and therefore may lead to DOS attack (anyone can use it to switch the device to bootloader mode). However, as there is no other way to trigger bootloader mode on devices without a button, this DFU Library supports this service, but the feature must be explicitly enabled here. Be aware, that setting this flag to false will no protect your devices from this kind of attacks, as an attacker may use another app for that purpose. To be sure your device is secure remove this experimental service from your device.

Spec:
Buttonless DFU Service UUID: 8E400001-F315-4F60-9FB8-838830DAEA50
Buttonless DFU characteristic UUID: 8E400001-F315-4F60-9FB8-838830DAEA50 (the same)
Enter Bootloader Op Code: 0x01
Correct return value: 0x20-01-01 , where:
0x20 - Response Op Code
0x01 - Request Code
0x01 - Success
The device should disconnect and restart in DFU mode after sending the notification.

In SDK 13 this issue will be fixed by a proper implementation (bonding required, passing bond information to the bootloader, encryption, well tested). It is recommended to use this new service when SDK 13 (or later) is out. TODO fix the docs when SDK 13 is out.

setCustomUuidsForLegacyDfu

public DfuServiceInitiator setCustomUuidsForLegacyDfu(java.util.UUID dfuServiceUuid,
                                                      java.util.UUID dfuControlPointUuid,
                                                      java.util.UUID dfuPacketUuid,
                                                      java.util.UUID dfuVersionUuid)

Sets custom UUIDs for Legacy DFU and Legacy Buttonless DFU. Use this method if your DFU implementation uses different UUID for at least one of the given UUIDs. Parameter set to null will reset the UUID to the default value.

Parameters:

dfuServiceUuid - custom Legacy DFU service UUID or null, if default is to be used

dfuControlPointUuid - custom Legacy DFU Control Point characteristic UUID or null, if default is to be used

dfuPacketUuid - custom Legacy DFU Packet characteristic UUID or null, if default is to be used

dfuVersionUuid - custom Legacy DFU Version characteristic UUID or null, if default is to be used (SDK 7.0 - 11.0 only, set null for earlier SDKs)

Returns:

the builder

setCustomUuidsForSecureDfu

public DfuServiceInitiator setCustomUuidsForSecureDfu(java.util.UUID dfuServiceUuid,
                                                      java.util.UUID dfuControlPointUuid,
                                                      java.util.UUID dfuPacketUuid)

Sets custom UUIDs for Secure DFU. Use this method if your DFU implementation uses different UUID for at least one of the given UUIDs. Parameter set to null will reset the UUID to the default value.

Parameters:

dfuServiceUuid - custom Secure DFU service UUID or null, if default is to be used

dfuControlPointUuid - custom Secure DFU Control Point characteristic UUID or null, if default is to be used

dfuPacketUuid - custom Secure DFU Packet characteristic UUID or null, if default is to be used

Returns:

the builder

setCustomUuidsForExperimentalButtonlessDfu

public DfuServiceInitiator setCustomUuidsForExperimentalButtonlessDfu(java.util.UUID buttonlessDfuServiceUuid,
                                                                      java.util.UUID buttonlessDfuControlPointUuid)

Sets custom UUIDs for the experimental Buttonless DFU Service from SDK 12.x. Use this method if your DFU implementation uses different UUID for at least one of the given UUIDs. Parameter set to null will reset the UUID to the default value.

Remember to call setUnsafeExperimentalButtonlessServiceInSecureDfuEnabled(boolean) with parameter true if you intent to use this service.

Parameters:

buttonlessDfuServiceUuid - custom Buttonless DFU service UUID or null, if default is to be used

buttonlessDfuControlPointUuid - custom Buttonless DFU characteristic UUID or null, if default is to be used

Returns:

the builder

setCustomUuidsForButtonlessDfuWithBondSharing

public DfuServiceInitiator setCustomUuidsForButtonlessDfuWithBondSharing(java.util.UUID buttonlessDfuServiceUuid,
                                                                         java.util.UUID buttonlessDfuControlPointUuid)

Sets custom UUIDs for the Buttonless DFU Service from SDK 14 (or later). Use this method if your DFU implementation uses different UUID for at least one of the given UUIDs. Parameter set to null will reset the UUID to the default value.

Parameters:

buttonlessDfuServiceUuid - custom Buttonless DFU service UUID or null, if default is to be used

buttonlessDfuControlPointUuid - custom Buttonless DFU characteristic UUID or null, if default is to be used

Returns:

the builder

setCustomUuidsForButtonlessDfuWithoutBondSharing

public DfuServiceInitiator setCustomUuidsForButtonlessDfuWithoutBondSharing(java.util.UUID buttonlessDfuServiceUuid,
                                                                            java.util.UUID buttonlessDfuControlPointUuid)

Sets custom UUIDs for the Buttonless DFU Service from SDK 13. Use this method if your DFU implementation uses different UUID for at least one of the given UUIDs. Parameter set to null will reset the UUID to the default value.

Parameters:

buttonlessDfuServiceUuid - custom Buttonless DFU service UUID or null, if default is to be used

buttonlessDfuControlPointUuid - custom Buttonless DFU characteristic UUID or null, if default is to be used

Returns:

the builder

setZip

public DfuServiceInitiator setZip(android.net.Uri uri)

Sets the URI to the Distribution packet (ZIP) or to a ZIP file matching the deprecated naming convention.

Parameters:

uri - the URI of the file

Returns:

the builder

See Also:

setZip(String), setZip(int)

setZip

public DfuServiceInitiator setZip(java.lang.String path)

Sets the path to the Distribution packet (ZIP) or the a ZIP file matching the deprecated naming convention.

Parameters:

path - path to the file

Returns:

the builder

See Also:

setZip(Uri), setZip(int)

setZip

public DfuServiceInitiator setZip(int rawResId)

Sets the resource ID of the Distribution packet (ZIP) or the a ZIP file matching the deprecated naming convention. The file should be in the /res/raw folder.

Parameters:

rawResId - file's resource ID

Returns:

the builder

See Also:

setZip(Uri), setZip(String)

setZip

public DfuServiceInitiator setZip(android.net.Uri uri,
                                  java.lang.String path)

Sets the URI or path of the ZIP file. If the URI and path are not null the URI will be used.

Parameters:

uri - the URI of the file

path - the path of the file

Returns:

the builder

setBinOrHex

@Deprecated
public DfuServiceInitiator setBinOrHex(int fileType,
                                                    android.net.Uri uri)

Deprecated.

Sets the URI of the BIN or HEX file containing the new firmware. For DFU Bootloader version 0.5 or newer the init file must be specified using one of setInitFile(Uri) methods.

Parameters:

fileType - the file type, a bit field created from:

• DfuBaseService.TYPE_APPLICATION - the Application will be sent
• DfuBaseService.TYPE_SOFT_DEVICE - he Soft Device will be sent
• DfuBaseService.TYPE_BOOTLOADER - the Bootloader will be sent

uri - the URI of the file

Returns:

the builder

setBinOrHex

@Deprecated
public DfuServiceInitiator setBinOrHex(int fileType,
                                                    java.lang.String path)

Deprecated.

Sets the URI of the BIN or HEX file containing the new firmware. For DFU Bootloader version 0.5 or newer the init file must be specified using one of setInitFile(String) methods.

Parameters:

fileType - see setBinOrHex(int, Uri) for details

path - path to the file

Returns:

the builder

setBinOrHex

@Deprecated
public DfuServiceInitiator setBinOrHex(int fileType,
                                                    android.net.Uri uri,
                                                    java.lang.String path)

Deprecated. The Distribution packet (ZIP) should be used for DFU Bootloader version 0.5 or newer

Sets the URI or path to the BIN or HEX file containing the new firmware. For DFU Bootloader version 0.5 or newer the init file must be specified using one of setInitFile(String) methods.

Parameters:

fileType - see setBinOrHex(int, Uri) for details

uri - the URI of the file

path - path to the file

Returns:

the builder

setBinOrHex

@Deprecated
public DfuServiceInitiator setBinOrHex(int fileType,
                                                    int rawResId)

Deprecated.

Sets the resource ID pointing the BIN or HEX file containing the new firmware. The file should be in the /res/raw folder. For DFU Bootloader version 0.5 or newer the init file must be specified using one of setInitFile(int) methods.

Parameters:

fileType - see setBinOrHex(int, Uri) for details

rawResId - resource ID

Returns:

the builder

setInitFile

@Deprecated
public DfuServiceInitiator setInitFile(android.net.Uri initFileUri)

Deprecated.

Sets the URI of the Init file. The init file for DFU Bootloader version pre-0.5 (SDK 4.3, 6.0, 6.1) contains only the CRC-16 of the firmware. Bootloader version 0.5 or newer requires the Extended Init Packet.

Parameters:

initFileUri - the URI of the init file

Returns:

the builder

setInitFile

@Deprecated
public DfuServiceInitiator setInitFile(java.lang.String initFilePath)

Deprecated.

Sets the path to the Init file. The init file for DFU Bootloader version pre-0.5 (SDK 4.3, 6.0, 6.1) contains only the CRC-16 of the firmware. Bootloader version 0.5 or newer requires the Extended Init Packet.

Parameters:

initFilePath - the path to the init file

Returns:

the builder

setInitFile

@Deprecated
public DfuServiceInitiator setInitFile(int initFileResId)

Deprecated.

Sets the resource ID of the Init file. The init file for DFU Bootloader version pre-0.5 (SDK 4.3, 6.0, 6.1) contains only the CRC-16 of the firmware. Bootloader version 0.5 or newer requires the Extended Init Packet.

Parameters:

initFileResId - the resource ID of the init file

Returns:

the builder

setInitFile

@Deprecated
public DfuServiceInitiator setInitFile(android.net.Uri initFileUri,
                                                    java.lang.String initFilePath)

Deprecated.

Sets the URI or path to the Init file. The init file for DFU Bootloader version pre-0.5 (SDK 4.3, 6.0, 6.1) contains only the CRC-16 of the firmware. Bootloader version 0.5 or newer requires the Extended Init Packet. If the URI and path are not null the URI will be used.

Parameters:

initFileUri - the URI of the init file

initFilePath - the path of the init file

Returns:

the builder

start

public DfuServiceController start(android.content.Context context,
                                  java.lang.Class<? extends DfuBaseService> service)

Starts the DFU service.

Parameters:

context - the application context

service - the class derived from the BaseDfuService

createDfuNotificationChannel

public static void createDfuNotificationChannel(android.content.Context context)