rusefi
/
Android-DFU-Library
mirror of https://github.com/rusefi/Android-DFU-Library.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update README

This commit is contained in:
Aleksander Nowakowski 2015-02-24 12:55:53 +01:00
parent 6753a7c39c
commit b10213f5e6
1 changed files with 75 additions and 75 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

92
documentation/README.md
View File

@ -4,20 +4,20 @@ The DFU Library for Android 4.3+ adds the DFU feature to the Android project.
### Features: ### Features:
* Allows to program Application, Soft Device and Bootloader Over-the-Air on the nRF51 Series chip over Bluetooth Smart. * Allows to program Application, Soft Device and Bootloader Over-the-Air on the nRF51 Series SoC over Bluetooth Smart.
* Supports HEX or BIN files. * Supports HEX or BIN files.
* Supports ZIP files with Soft Device, Bootloader and Application together. * Supports zip files with Soft Device, Bootloader and Application together.
* Supports the Init packet (which is required since Bootloader/DFU from SDK 7.0+). * Supports the Init packet (which has been required since Bootloader/DFU from SDK 7.0+).
* Performs the DFU operation in the background service. * Performs the DFU operation in the background service.
* Displays the notification with progress. * Displays the notification with progress.
* Sends local broadcasts with progress, errors and log events to the application. * Sends local broadcasts with progress, errors and log events to the application.
* Handles bonded devices and buttonless update. * Handles bonded devices and buttonless update.
* Android DFU Library is compatible with all Bootloader/DFU versions. * 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. * 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 are in a ZIP file the service will first try to send all 3 files together (this operation is currently not supported by the bootloader and will result in an Unsupported Operation DFU error), than will try to send the SD and BL (supported by Bootloader/DFU from SDK 6.1+). When done, the service will reconnect to the new bootloader and send the Application in the second connection as a part two. * 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 #### Error handling
In case of any communication error the peripheral device will never be bricked. When an application or a bootloader were updated, the previous application (or bootloader, in case there was no application) is restored. When a Soft Device was updated the previous bootloader will be restored as the application had to be removed to save the new Soft Device. User 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 ### Requirements
@ -26,19 +26,19 @@ In case of any communication error the peripheral device will never be bricked.
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 Smart in version 4.3. Android 4.4.4 or newer is recommended for better user experience.
* **Android Studio IDE** or **Eclipse ADT** * **Android Studio IDE** or **Eclipse ADT**
Projects are compatible with Android Studio and 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.
* **nRF51 device for testing.** * **nRF51 device for testing.**
A nRF51 Series device is required to test the working solution. If your final product is not available we recommend using the nRF51 DK, which can be found [here](http://www.nordicsemi.com/eng/Products/nRF51-DK "nRF51 DK"). A nRF51 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/nRF51-DK "nRF51 DK").
### Integration ### Integration
The DFULibrary 'as is' is compatible with Android Studio 1.0.2 IDE. If you are using Eclipse ADT you will have to convert the project to match Eclipse project structure. The DFULibrary is compatible as such with Android Studio 1.0.2 IDE. If you are using Eclipse ADT, you will have to convert the project to match the Eclipse project structure.
#### Android Studio #### Android Studio
1. Clone the project, or just the *DFULibrary* folder (using sparse-checkout) to a temporary location. 1. Clone the project, or just the *DFULibrary* folder (using sparse-checkout) to a temporary location.
2. Copy the *DFULibrary* folder to your projects root, f.e. to *AndroidstudioProjects*. 2. Copy the *DFULibrary* folder to your projects root, for example to *AndroidstudioProjects*.
3. Add the **dfu** module to your project: 3. Add the **dfu** module to your project:
1. Add **'..:DFULibrary:dfu'** to the *settings.gradle* file: `include ':app', '..:DFULibrary:dfu'` 1. Add **'..:DFULibrary:dfu'** to the *settings.gradle* file: `include ':app', '..:DFULibrary: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(':..:DFULibrary: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(':..:DFULibrary:dfu')`
@ -48,21 +48,21 @@ The DFULibrary 'as is' is compatible with Android Studio 1.0.2 IDE. If you are u
1. Clone the project, or just the *DFULibrary* folder (using sparse-checkout) to a temporary location. 1. Clone the project, or just the *DFULibrary* folder (using sparse-checkout) to a temporary location.
2. Create an empty *DFULibrary* project in Eclipse. Make it a library. 2. Create an empty *DFULibrary* project in Eclipse. Make it a library.
3. Copy the content of *java* code folder to the *src*. 3. Copy the content of *java* code folder to the *src*.
4. Copy the content of *res* folder to the *res* in your Eclipse project. 4. Copy the content of the *res* folder to the *res* in your Eclipse project.
5. Make sure that *android support libraty v4* is in *libs* foldes. 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. 6. In your application project, open Properties->Android and add DFULibrary as a library.
### Usage ### 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 user press the DFU notification while transferring 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 transfering the firmware. This activity will be started with the 'Intent.FLAG_ACTIVITY_NEW_TASK' flag.
```java ```java
package com.example.coolproject; package com.example.coolproject;
import no.nordicsemi.android.dfu.DfuBaseService; import no.nordicsemi.android.dfu.DfuBaseService;
import android.app.Activity; import android.app.Activity;
public class DfuService extends DfuBaseService { public class DfuService extends DfuBaseService {
@Override @Override
protected Class<? extends Activity> getNotificationTarget() { protected Class<? extends Activity> getNotificationTarget() {
@ -72,11 +72,11 @@ Extend the **DfuBaseService** in your project and implement the `protected Class
* *
* intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK); * intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
* *
* when user press it. Using NotificationActivity we can check whether the new activity * when you press it. You can use NotificationActivity to check whether the new activity
* is a root activity (that means no other activity was open before) or that there is * is a root activity (that means no other activity was open earlier) or that some
* other activity already open. In the later case the NotificationActivity will just be * other activity is already open. In the latter case the NotificationActivity will just be
* closed. System will restore the previous activity. However if application has been * closed. The system will restore the previous activity. However, if the application has been
* closed during upload and user click the notification a NotificationActivity will * closed during upload and you click the notification, a NotificationActivity will
* be launched as a root activity. It will create and start the main activity and * be launched as a root activity. It will create and start the main activity and
* terminate itself. * terminate itself.
* *
@ -86,21 +86,21 @@ Extend the **DfuBaseService** in your project and implement the `protected Class
*/ */
return NotificationActivity.class; return NotificationActivity.class;
} }
} }
``` ```
You may use the following class in order to prevent from starting another instance of your application: You may use the following class in order to prevent starting another instance of your application:
```java ```java
package com.example.coolproject; package com.example.coolproject;
import com.example.coolproject.MyActivity; import com.example.coolproject.MyActivity;
import android.app.Activity; import android.app.Activity;
import android.content.Intent; import android.content.Intent;
import android.os.Bundle; import android.os.Bundle;
public class NotificationActivity extends Activity { public class NotificationActivity extends Activity {
@Override @Override
protected void onCreate(Bundle savedInstanceState) { protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState); super.onCreate(savedInstanceState);
@ -114,10 +114,10 @@ You may use the following class in order to prevent from starting another instan
startActivity(intent); startActivity(intent);
} }
// Now finish, which will drop the user in to the activity that was at the top of the task stack // Now finish, which will drop you to the activity at which you were at the top of the task stack
finish(); finish();
} }
} }
``` ```
Remember to add your service to the *AndroidManifest.xml*. Remember to add your service to the *AndroidManifest.xml*.
@ -125,24 +125,24 @@ Remember to add your service to the *AndroidManifest.xml*.
Start the DFU service with the following code: Start the DFU service with the following code:
```java ```java
final Intent service = new Intent(this, MyDfuService.class); final Intent service = new Intent(this, MyDfuService.class);
service.putExtra(DfuService.EXTRA_DEVICE_ADDRESS, mSelectedDevice.getAddress()); service.putExtra(DfuService.EXTRA_DEVICE_ADDRESS, mSelectedDevice.getAddress());
service.putExtra(DfuService.EXTRA_DEVICE_NAME, mSelectedDevice.getName()); service.putExtra(DfuService.EXTRA_DEVICE_NAME, mSelectedDevice.getName());
service.putExtra(DfuService.EXTRA_FILE_MIME_TYPE, service.putExtra(DfuService.EXTRA_FILE_MIME_TYPE,
mFileType == DfuService.TYPE_AUTO ? DfuService.MIME_TYPE_ZIP : DfuService.MIME_TYPE_OCTET_STREAM); mFileType == DfuService.TYPE_AUTO ? DfuService.MIME_TYPE_ZIP : DfuService.MIME_TYPE_OCTET_STREAM);
service.putExtra(DfuService.EXTRA_FILE_TYPE, mFileType); service.putExtra(DfuService.EXTRA_FILE_TYPE, mFileType);
service.putExtra(DfuService.EXTRA_FILE_PATH, mFilePath); // a path or URI must be provided. service.putExtra(DfuService.EXTRA_FILE_PATH, mFilePath); // a path or URI must be provided.
service.putExtra(DfuService.EXTRA_FILE_URI, mFileStreamUri); service.putExtra(DfuService.EXTRA_FILE_URI, mFileStreamUri);
// Init packet is required by Bootloader/DFU from SDK 7.0+ if HEX or BIN file is given above. // Init packet is required by Bootloader/DFU from SDK 7.0+ if HEX or BIN file is given above.
// In case of a ZIP file, the init packet (a DAT file) must be included inside the ZIP file. // In case of a ZIP file, the init packet (a DAT file) must be included inside the ZIP file.
service.putExtra(DfuService.EXTRA_INIT_FILE_PATH, mInitFilePath); service.putExtra(DfuService.EXTRA_INIT_FILE_PATH, mInitFilePath);
service.putExtra(DfuService.EXTRA_INIT_FILE_URI, mInitFileStreamUri); service.putExtra(DfuService.EXTRA_INIT_FILE_URI, mInitFileStreamUri);
startService(service); startService(service);
``` ```
Please, see the [How to create init packet](https://github.com/NordicSemiconductor/nRF-Master-Control-Panel/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/nRF-Master-Control-Panel/tree/master/init%20packet%20handling "Init packet handling") document for more information about the init packet.
The service will send local broadcast events using **LocalBroadcaseManager**. The service will send local broadcast events using **LocalBroadcaseManager**.
@ -152,7 +152,7 @@ The service will send local broadcast events using **LocalBroadcaseManager**.
protected void onResume() { protected void onResume() {
super.onResume(); super.onResume();
// We are using LocalBroadcastReceiver instead of normal BroadcastReceiver for // We are using LocalBroadcastReceiver instead of a normal BroadcastReceiver for
// optimization purposes // optimization purposes
final LocalBroadcastManager broadcastManager = LocalBroadcastManager.getInstance(this); final LocalBroadcastManager broadcastManager = LocalBroadcastManager.getInstance(this);
broadcastManager.registerReceiver(mDfuUpdateReceiver, makeDfuUpdateIntentFilter()); broadcastManager.registerReceiver(mDfuUpdateReceiver, makeDfuUpdateIntentFilter());