Documentation updated
This commit is contained in:
Aleksander Nowakowski
parent
20fb869982
commit
edf52b9c43
|
|
@ -4,37 +4,53 @@ The DFU Library for Android 4.3+ adds the DFU feature to the Android project.
|
|||
|
||||
### Features:
|
||||
|
||||
* DFU Library version 1.0.0+ supports **Secure DFU** introduced in SDK 12.0.0 and is fully backwards compatible with all versions of Legacy DFU.
|
||||
* Allows to program Application, Soft Device and Bootloader Over-the-Air on the nRF5 Series SoC over Bluetooth Smart.
|
||||
* Supports HEX or BIN files.
|
||||
* Supports zip files with Soft Device, Bootloader and Application together.
|
||||
* DFU Library version 1.0.0+ supports **Secure DFU** introduced in SDK 12.0.0 and is fully backwards
|
||||
compatible with all versions of Legacy DFU.
|
||||
* Allows to program Application, Soft Device and Bootloader Over-the-Air on the nRF5 Series SoC over
|
||||
Bluetooth Low Energy.
|
||||
* Supports ZIP files with Soft Device, Bootloader and Application together.
|
||||
* Supports legacy HEX or BIN files.
|
||||
* Supports the Init packet (which has been required since Bootloader/DFU from SDK 7.0+).
|
||||
* Performs the DFU operation in the background service.
|
||||
* Displays the notification with progress.
|
||||
* Performs the DFU operation in a foreground service (option to keep in background service).
|
||||
* Displays the notification with progress (option to disable).
|
||||
* Sends local broadcasts with progress, errors and log events to the application.
|
||||
* Handles bonded devices and buttonless update.
|
||||
* Android DFU Library is compatible with all Bootloader/DFU versions.
|
||||
* Only the application may be updated with the bootloader from SDK 4.3.0. An error will be broadcast in case of sending a Soft Device or a Bootloader.
|
||||
* When App, SD and BL files are in a zip file, the service will first try to send all three files together, which will result in an Unsupported Operation DFU error, because currently this operation is not supported by the bootloader. Then, the service will try to send the SD and BL together, which is supported by Bootloader/DFU from SDK 6.1+. Once completed, the service will reconnect to the new bootloader and send the Application in the second connection as part two.
|
||||
* Only the application may be updated with the bootloader from SDK 4.3.0.
|
||||
An error will be broadcast in case of sending a Soft Device or a Bootloader.
|
||||
* When App, SD and BL files are in a ZIP file, the service will first try to send all three files
|
||||
together, which will result in an Unsupported Operation DFU error, because currently this
|
||||
operation is not supported by the bootloader. Then, the service will try to send the SD and BL
|
||||
together, which is supported by Bootloader/DFU from SDK 6.1+. Once completed, the service will
|
||||
reconnect to the new bootloader and send the Application in the second connection as part two.
|
||||
|
||||
#### Error handling
|
||||
In case of any communication error the peripheral device will never be bricked. When an application or a bootloader is updated, the previous application (or bootloader, in case there was no application) is restored. When a Soft Device is updated, the previous bootloader will be restored as the application has to be removed to in order to save the new version of the Soft Device. You will still be able to repeat the update and flash the Soft Device and the new application again.
|
||||
In case of any communication error the peripheral device will never be bricked. When an application
|
||||
or a bootloader is updated, the previous application (or bootloader, in case there was no application)
|
||||
is restored. When a Soft Device is updated, the previous bootloader will be restored as the application
|
||||
has to be removed to in order to save the new version of the Soft Device. You will still be able to
|
||||
repeat the update and flash the Soft Device and the new application again.
|
||||
|
||||
### Requirements
|
||||
|
||||
* **An Android 4.3+ device.**
|
||||
|
||||
Support for the Bluetooth 4.0 technology is required. Android introduced Bluetooth Smart in version 4.3. Android 4.4.4 or newer is recommended for better user experience.
|
||||
Support for the Bluetooth 4.0 technology is required. Android introduced Bluetooth LE in
|
||||
version 4.3. Android 4.4.4 or newer is recommended for better user experience.
|
||||
* **Android Studio IDE** or **Eclipse ADT**
|
||||
|
||||
Projects are compatible with Android Studio and the Gradle build engine. It is possible to convert them to Eclipse ADT projects. See Integration for more details.
|
||||
Projects are compatible with Android Studio and the Gradle build engine. It is possible to
|
||||
convert them to Eclipse ADT projects. See Integration for more details.
|
||||
* **nRF5 device for testing.**
|
||||
|
||||
A nRF5 Series device is required to test the working solution. If your final product is not available, use the nRF51 DK, which you can find [here](http://www.nordicsemi.com/eng/Products/Bluetooth-low-energy/nRF52-DK "nRF52 DK").
|
||||
A nRF5 Series device is required to test the working solution. If your final product is not
|
||||
available, use one of the nRF5 DK, which you can find
|
||||
[here](https://www.nordicsemi.com/Software-and-tools/Development-Kits "Development Kits").
|
||||
|
||||
### Integration
|
||||
|
||||
The DFULibrary is compatible as such with Android Studio IDE. If you are using Eclipse ADT, you will have to convert the project to match the Eclipse project structure.
|
||||
The DFU Library is compatible as such with Android Studio IDE. If you are using Eclipse ADT,
|
||||
you will have to convert the project to match the Eclipse project structure.
|
||||
|
||||
#### Android Studio
|
||||
|
||||
|
|
@ -46,14 +62,17 @@ line to your build.gradle file. And that's it.
|
|||
|
||||
However, if you want to modify the code to your needs you have to clone the project and add it as follows:
|
||||
|
||||
1. Clone the project into DFULibrary folder (by default it will be cloned into Android-DFU-Library folder) to your projects root, for example to *AndroidstudioProjects*.
|
||||
1. Clone the project into DFULibrary folder (by default it will be cloned into Android-DFU-Library
|
||||
folder) to your projects root, for example to *AndroidstudioProjects*.
|
||||
2. Add the **dfu** module to your project:
|
||||
1. Add **'..:DFULibrary:dfu'** to the *settings.gradle* file:
|
||||
1. Add **'..:[Folder Name]:dfu'** to the *settings.gradle* file:
|
||||
```
|
||||
include ':dfu'
|
||||
project(':dfu').projectDir = file('../DFULibrary/dfu')
|
||||
project(':dfu').projectDir = file('../[Folder Name]/dfu')
|
||||
```
|
||||
2. Open Project Structure -> Modules -> app -> Dependencies tab and add dfu module dependency. You may also edit the *build.gradle* file in your app module manually by adding the following dependency: `compile project(':dfu')`
|
||||
2. Open Project Structure -> Modules -> app -> Dependencies tab and add dfu module dependency.
|
||||
You may also edit the *build.gradle* file in your app module manually by adding the following
|
||||
dependency: `implementation project(':dfu')`
|
||||
|
||||
#### Eclipse
|
||||
|
||||
|
|
@ -61,12 +80,16 @@ However, if you want to modify the code to your needs you have to clone the proj
|
|||
2. Create an empty *DFULibrary* project in Eclipse. Make it a library.
|
||||
3. Copy the content of *java* code folder to the *src*.
|
||||
4. Copy the content of the *res* folder to the *res* in your Eclipse project.
|
||||
5. Make sure that *android support library v4* is available in *libs* folders. It should have been added automatically when creating the project.
|
||||
5. Make sure that *android support library v4* is available in *libs* folders. It should have been
|
||||
added automatically when creating the project.
|
||||
6. In your application project, open Properties->Android and add DFULibrary as a library.
|
||||
|
||||
### Usage
|
||||
|
||||
Extend the **DfuBaseService** in your project and implement the `protected Class<? extends Activity> getNotificationTarget()` method. This method should return an activity class that will be open when you press the DFU notification while transfering the firmware. This activity will be started with the 'Intent.FLAG_ACTIVITY_NEW_TASK' flag.
|
||||
Extend the **DfuBaseService** in your project and implement the
|
||||
`protected Class<? extends Activity> getNotificationTarget()` method. This method should return an
|
||||
activity class that will be open when you press the DFU notification while transferring the firmware.
|
||||
This activity will be started with the 'Intent.FLAG_ACTIVITY_NEW_TASK' flag.
|
||||
|
||||
```java
|
||||
package com.example.coolproject;
|
||||
|
|
@ -106,6 +129,11 @@ public class DfuService extends DfuBaseService {
|
|||
// make sure you return true or your.app.BuildConfig.DEBUG here.
|
||||
return BuildConfig.DEBUG;
|
||||
}
|
||||
|
||||
@Override
|
||||
protected void updateForegroundNotification(@NonNull final NotificationCompat.Builder builder) {
|
||||
// Customize the foreground service notification here.
|
||||
}
|
||||
}
|
||||
```
|
||||
Remember to add your service to *AndroidManifest.xml*.
|
||||
|
|
@ -148,7 +176,8 @@ Start the DFU service with the following code:
|
|||
final DfuServiceInitiator starter = new DfuServiceInitiator(mSelectedDevice.getAddress())
|
||||
.setDeviceName(mSelectedDevice.getName())
|
||||
.setKeepBond(keepBond);
|
||||
// If you want to have experimental buttonless DFU feature supported call additionally:
|
||||
// If you want to have experimental buttonless DFU feature (DFU from SDK 12.x only!) supported call
|
||||
// additionally:
|
||||
starter.setUnsafeExperimentalButtonlessServiceInSecureDfuEnabled(true);
|
||||
// but be aware of this: https://devzone.nordicsemi.com/question/100609/sdk-12-bootloader-erased-after-programming/
|
||||
// and other issues related to this experimental service.
|
||||
|
|
@ -164,23 +193,25 @@ final DfuServiceController controller = starter.start(this, DfuService.class);
|
|||
// You may use the controller to pause, resume or abort the DFU process.
|
||||
```
|
||||
|
||||
Please, see [How to create init packet](https://github.com/NordicSemiconductor/Android-nRF-Connect/tree/master/init%20packet%20handling "Init packet handling") document for more information about the init packet.
|
||||
Please, see
|
||||
[How to create init packet](https://github.com/NordicSemiconductor/Android-nRF-Connect/tree/master/init%20packet%20handling "Init packet handling")
|
||||
document for more information about the init packet.
|
||||
|
||||
The service will send local broadcast events using **LocalBroadcastManager**.
|
||||
|
||||
|
||||
```java
|
||||
private final DfuProgressListener mDfuProgressListener = new DfuProgressListenerAdapter() {
|
||||
private final DfuProgressListener dfuProgressListener = new DfuProgressListenerAdapter() {
|
||||
@Override
|
||||
public void onDeviceConnecting(final String deviceAddress) {
|
||||
mProgressBar.setIndeterminate(true);
|
||||
mTextPercentage.setText(R.string.dfu_status_connecting);
|
||||
progressBar.setIndeterminate(true);
|
||||
textPercentage.setText(R.string.dfu_status_connecting);
|
||||
}
|
||||
|
||||
@Override
|
||||
public void onDfuProcessStarting(final String deviceAddress) {
|
||||
mProgressBar.setIndeterminate(true);
|
||||
mTextPercentage.setText(R.string.dfu_status_starting);
|
||||
progressBar.setIndeterminate(true);
|
||||
textPercentage.setText(R.string.dfu_status_starting);
|
||||
}
|
||||
///...
|
||||
}
|
||||
|
|
@ -189,18 +220,19 @@ private final DfuProgressListener mDfuProgressListener = new DfuProgressListener
|
|||
protected void onResume() {
|
||||
super.onResume();
|
||||
|
||||
DfuServiceListenerHelper.registerProgressListener(this, mDfuProgressListener);
|
||||
DfuServiceListenerHelper.registerProgressListener(this, dfuProgressListener);
|
||||
}
|
||||
|
||||
@Override
|
||||
protected void onPause() {
|
||||
super.onPause();
|
||||
|
||||
DfuServiceListenerHelper.unregisterProgressListener(this, mDfuProgressListener);
|
||||
DfuServiceListenerHelper.unregisterProgressListener(this, dfuProgressListener);
|
||||
}
|
||||
```
|
||||
|
||||
For Android Oreo and above, if you want the DfuService to show a notification with the progress, you have to create a notification channel. The easiest way to do this is to call
|
||||
For Android Oreo and above, if you want the DfuService to show a notification with the progress,
|
||||
you have to create a notification channel. The easiest way to do this is to call
|
||||
|
||||
```java
|
||||
DfuServiceInitiator.createDfuNotificationChannel(context);
|
||||
|
|
@ -208,7 +240,8 @@ DfuServiceInitiator.createDfuNotificationChannel(context);
|
|||
|
||||
### Example
|
||||
|
||||
Check the Android projects: nRF Toolbox ([here](https://github.com/NordicSemiconductor/Android-nRF-Toolbox "nRF Toolbox")) or nRF Beacon ([here](https://github.com/NordicSemiconductor/Android-nRF-Beacon "nRF Beacon")) for usage examples.
|
||||
Check the Android projects: [nRF Toolbox](https://github.com/NordicSemiconductor/Android-nRF-Toolbox "nRF Toolbox")
|
||||
or [nRF Beacon](https://github.com/NordicSemiconductor/Android-nRF-Beacon "nRF Beacon") for usage examples.
|
||||
|
||||
### Issues
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue