Skip to content

Commit

Permalink
Version 0.13.0
Browse files Browse the repository at this point in the history
  • Loading branch information
@philips77
philips77 committed Aug 30, 2021
1 parent 5a299a3 commit 63b5f4b
Show file tree
Hide file tree
Showing 8 changed files with 215 additions and 257 deletions.
88 changes: 62 additions & 26 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,50 +1,64 @@
# nRF Connect Device Manager

This repository extends the [McuManager Android Library](https://github.com/JuulLabs-OSS/mcumgr-android).
It contains the Android library for nRF Connect Device Manager and a sample app, called nRF Connect Device Manager.
All changes in the *nordic* branch modify only to the app, to which Nordic look & feel has been applied.
The underlying library, as of now, is 1 to 1 copy of the original. All PRs should be submitted to
the original repository.
This repository is a fork of the [McuManager Android Library](https://github.com/JuulLabs-OSS/mcumgr-android),
which has been DEPRECATED. All new features and bug fixes will be added here. Please, migrate to the
new version to get future updates.

nRF Connect Device Manager is compatible with Mcu Manager that is supported by Apache Mynewt and Zephyr.
The sample application has been named nRF Connect Device Manager and is available on
[Google Play](https://play.google.com/store/apps/details?id=no.nordicsemi.android.nrfconnectdevicemanager).

Below find the original documentation from the forked repository.
nRF Connect Device Manager library is compatible with Mcu Manager, a management subsystem supported
by nRF Connect SDK, Zephyr and Apache Mynewt.

---

[![codecov](https://codecov.io/gh/JuulLabs-OSS/mcumgr-android/branch/master/graph/badge.svg)](https://codecov.io/gh/JuulLabs-OSS/mcumgr-android)

# McuManager Android

A transport agnostic implementation of the McuManager protocol. Contains a default implementation for BLE transport.
Minimum required Android version is 5.0 (Android Lollipop) due to a requirement for high MTU.

## Gradle Install

**Note:** For the faster firmware upgrade implementation, use version `0.12.0-beta4` (this version is less stable and should be tested thoroughly with your app and device before being released into a production environment)
[ ![Download](https://maven-badges.herokuapp.com/maven-central/no.nordicsemi.android/mcumgr-ble/badge.svg?style=plastic) ](https://search.maven.org/search?q=g:no.nordicsemi.android)

#### McuManager BLE (Recommended)
Contains the core and a BLE transport implementation using Nordic's [Android-BLE-Library v2](https://github.com/NordicSemiconductor/Android-BLE-Library).

```
implementation 'io.runtime.mcumgr:mcumgr-ble:0.11.0'
```groovy
implementation 'no.nordicsemi.android:mcumgr-ble:0.13.0'
```

The core module will be included automatically.

#### McuManager Core
Core dependency only. Use if you want to provide your own transport implementation.

```groovy
implementation 'no.nordicsemi.android:mcumgr-code:0.13.0'
```
implementation 'io.runtime.mcumgr:mcumgr-core:0.11.0'

### Migration from the original repo

When migrating from the version 0.12 and older, change
```groovy
implementation 'io.runtime.mcumgr:mcumgr-ble:0.XX.X'
```
to the above.

# Introduction

McuManager is an application layer protocol used to manage and monitor microcontrollers running Apache Mynewt and Zephyr. More specifically, McuManagr implements over-the-air (OTA) firmware upgrades, log and stat collection, and file-system and configuration management.
McuManager is an application layer protocol used to manage and monitor microcontrollers running
Apache Mynewt and Zephyr. More specifically, McuManagr implements over-the-air (OTA) firmware upgrades,
log and stat collection, and file-system and configuration management.

## Command Groups

McuManager are organized by functionality into command groups. In _mcumgr-android_, command groups are called managers and extend the `McuManager` class. The managers (groups) implemented in _mcumgr-android_ are:
McuManager are organized by functionality into command groups. In _mcumgr-android_, command groups
are called managers and extend the `McuManager` class. The managers (groups) implemented in
_mcumgr-android_ are:

* **`DefaultManager`**: Contains commands relevent to the OS. This includes task and memory pool statistics, device time read & write, and device reset.
* **`DefaultManager`**: Contains commands relevant to the OS. This includes task and memory pool
statistics, device time read & write, and device reset.
* **`ImageManager`**: Manage image state on the device and perform image uploads.
* **`StatsManager`**: Read stats from the device.
* **`ConfigManager`**: Read/Write config values on the device.
Expand All @@ -53,7 +67,8 @@ McuManager are organized by functionality into command groups. In _mcumgr-androi

# Firmware Upgrade

Firmware upgrade is generally a four step process performed using commands from the `image` and `default` commands groups: `upload`, `test`, `reset`, and `confirm`.
Firmware upgrade is generally a four step process performed using commands from the `image` and
`default` commands groups: `upload`, `test`, `reset`, and `confirm`.

This library provides a `FirmwareUpgradeManager` as a convenience for upgrading the image running on a device.

Expand All @@ -71,21 +86,42 @@ dfuManager.start(imageData);

## FirmwareUpgradeManager

A `FirmwareUpgradeManager` provides an easy way to perform firmware upgrades on a device. A `FirmwareUpgradeManager` must be initialized with an `McuMgrTransport` which defines the transport scheme and device. Once initialized, a `FirmwareUpgradeManager` can perform one firmware upgrade at a time. Firmware upgrades are started using the `start(byte[] imageData)` method and can be paused, resumed, and canceled using `pause()`, `resume()`, and `cancel()` respectively.
A `FirmwareUpgradeManager` provides an easy way to perform firmware upgrades on a device.
A `FirmwareUpgradeManager` must be initialized with an `McuMgrTransport` which defines the transport
scheme and device. Once initialized, a `FirmwareUpgradeManager` can perform one firmware upgrade at a time.
Firmware upgrades are started using the `start(byte[] imageData)` method and can be paused, resumed,
and canceled using `pause()`, `resume()`, and `cancel()` respectively.

### Firmware Upgrade Mode

McuManager firmware upgrades can actually be performed in few different ways. These different upgrade modes determine the commands sent after the upload step. The `FirmwareUpgradeManager` can be configured to perform these different methods using `setMode(FirmwareUpgradeManager.Mode mode)`. The different firmware upgrade modes are as follows:

* **`TEST_AND_CONFIRM`**: This mode is the **default and recommended mode** for performing upgrades due to it's ability to recover from a bad firmware upgrade. The process for this mode is `UPLOAD`, `TEST`, `RESET`, `CONFIRM`.
* **`CONFIRM_ONLY`**: This mode is **not recommended**. If the device fails to boot into the new image, it will not be able to recover and will need to be re-flashed. The process for this mode is `UPLOAD`, `CONFIRM`, `RESET`.
* **`TEST_ONLY`**: This mode is useful if you want to run tests on the new image running before confirming it manually as the primary boot image. The process for this mode is `UPLOAD`, `TEST`, `RESET`.
McuManager firmware upgrades can actually be performed in few different ways. These different upgrade
modes determine the commands sent after the upload step. The `FirmwareUpgradeManager` can be
configured to perform these different methods using `setMode(FirmwareUpgradeManager.Mode mode)`.
The different firmware upgrade modes are as follows:

* **`TEST_AND_CONFIRM`**: This mode is the **default and recommended mode** for performing upgrades
due to it's ability to recover from a bad firmware upgrade.
The process for this mode is `UPLOAD`, `TEST`, `RESET`, `CONFIRM`.
* **`CONFIRM_ONLY`**: This mode is **not recommended**. If the device fails to boot into the new
image, it will not be able to recover and will need to be re-flashed.
The process for this mode is `UPLOAD`, `CONFIRM`, `RESET`.
* **`TEST_ONLY`**: This mode is useful if you want to run tests on the new image running before
confirming it manually as the primary boot image.
The process for this mode is `UPLOAD`, `TEST`, `RESET`.

### Firmware Upgrade State

`FirmwareUpgradeManager` acts as a simple, mostly linear state machine which is determined by the `Mode`. As the manager moves through the firmware upgrade process, state changes are provided through the `FirmwareUpgradeCallback`'s `onStateChanged` method.

The `FirmwareUpgradeManager` contains an additional state, `VALIDATE`, which precedes the upload. The `VALIDATE` state checks the current image state of the device in an attempt to bypass certain states of the firmware upgrade. For example, if the image to upload is already in slot 1 on the device, the `State` will skip `UPLOAD` and move directly to `TEST` (or `CONFIRM` if `Mode.CONFIRM_ONLY` has been set). If the uploaded image is already active, and confirmed in slot 0, the upgrade will succeed immediately. The `VALIDATE` state makes it easy to reattempt an upgrade without needing to re-upload the image or manually determine where to start.
`FirmwareUpgradeManager` acts as a simple, mostly linear state machine which is determined by the `Mode`.
As the manager moves through the firmware upgrade process, state changes are provided through the
`FirmwareUpgradeCallback`'s `onStateChanged` method.

The `FirmwareUpgradeManager` contains an additional state, `VALIDATE`, which precedes the upload.
The `VALIDATE` state checks the current image state of the device in an attempt to bypass certain
states of the firmware upgrade. For example, if the image to upload is already in slot 1 on the
device, the `State` will skip `UPLOAD` and move directly to `TEST` (or `CONFIRM` if `Mode.CONFIRM_ONLY`
has been set). If the uploaded image is already active, and confirmed in slot 0, the upgrade will
succeed immediately. The `VALIDATE` state makes it easy to reattempt an upgrade without needing to
re-upload the image or manually determine where to start.

## License

Expand Down
9 changes: 9 additions & 0 deletions build.gradle
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,11 @@
*/

buildscript {
// https://kotlinlang.org/docs/releases.html#release-details
ext.kotlin_version = '1.5.30'
// https://plugins.gradle.org/plugin/io.github.gradle-nexus.publish-plugin
ext.gradle_nexus_publish_plugin = '1.1.0'

repositories {
google()
mavenCentral()
Expand All @@ -17,6 +21,7 @@ buildscript {
dependencies {
classpath 'com.android.tools.build:gradle:7.0.1'
classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
classpath "io.github.gradle-nexus:publish-plugin:$gradle_nexus_publish_plugin"
classpath 'com.hiya:jacoco-android:0.2'
}
}
Expand All @@ -27,3 +32,7 @@ allprojects {
mavenCentral()
}
}

// Maven Central publishing
apply plugin: 'io.github.gradle-nexus.publish-plugin'
apply from: rootProject.file('gradle/publish-root.gradle')
26 changes: 13 additions & 13 deletions gradle.properties
View file
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
VERSION_NAME=0.12.0-SNAPSHOT
GROUP=io.runtime.mcumgr
android.useAndroidX=true

VERSION_NAME=0.13.0
GROUP=no.nordicsemi.android

POM_DESCRIPTION=A mobile management library for devices running Apache Mynewt and Zephyr (DFU, logs, stats, config, etc.)
POM_URL=https://github.com/runtimeco/mcumgr-android
POM_SCM_URL=https://github.com/runtimeco/mcumgr-android
POM_SCM_CONNECTION=scm:[email protected]:runtimeco/mcumgr-android.git
POM_SCM_DEV_CONNECTION=scm:[email protected]:runtimeco/mcumgr-android.git
POM_URL=https://github.com/NordicSemiconductor/Android-nRF-Connect-Device-Manager
POM_SCM_URL=https://github.com/NordicSemiconductor/Android-nRF-Connect-Device-Manager
POM_SCM_CONNECTION=scm:[email protected]:NordicSemiconductor/Android-nRF-Connect-Device-Manager.git
POM_SCM_DEV_CONNECTION=scm:[email protected]:NordicSemiconductor/Android-nRF-Connect-Device-Manager.git
POM_LICENCE=Apache-2.0
POM_LICENCE_NAME=The Apache Software License, Version 2.0
POM_LICENCE_URL=http://www.apache.org/licenses/LICENSE-2.0.txt
POM_LICENCE_DIST=repo
POM_DEVELOPER_ID=runtimeco
POM_DEVELOPER_NAME=Runtime, Inc.

android.useAndroidX=true
android.enableJetifier=true
POM_LICENCE_URL=https://opensource.org/licenses/Apache-2.0
POM_DEVELOPER_ID=philips77
POM_DEVELOPER_NAME=Aleksander Nowakowski
POM_DEVELOPER_EMAIL[email protected]
Loading

0 comments on commit 63b5f4b

Please sign in to comment.