Merge ~alfonsosanchezbeato/snappy-hwe-snaps/+git/modem-manager:update-docs into ~snappy-hwe-team/snappy-hwe-snaps/+git/modem-manager:master

[Alfonso Sanchez-Beato]

docs: update to match current state

docs: update to match current state

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Successfully build documentation, rev: 330b0d4c9f06db047a486eef5c9432ddbd7907b3

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/1338/

[System Enablement Bot (system-enablement-ci-bot)]

FAILED: Continuous integration, rev:330b0d4c9f06db047a486eef5c9432ddbd7907b3
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build-prepare/516/
Executed test runs:
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=amd64/549/console
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=arm64/549
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=armhf/549
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=i386/549
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/1338
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-cleanup/1080
    None: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-update-mp/1129/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build-prepare/516/rebuild

review: Needs Fixing (continuous-integration)

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Successfully build documentation, rev: cf4664921aa286e4a7365e2f714f6dfdd0977389

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/1340/

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Continuous integration, rev:cf4664921aa286e4a7365e2f714f6dfdd0977389
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build-prepare/518/
Executed test runs:
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=amd64/551
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=arm64/551
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=armhf/551
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=i386/551
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/1340
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-cleanup/1082
    None: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-update-mp/1131/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build-prepare/518/rebuild

review: Approve (continuous-integration)

diff --git a/docs/index.md b/docs/index.md
index 95e7dc5..25a4ce9 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -5,11 +5,11 @@ table_of_contents: False
 
 # About ModemManager
 
-ModemManager is a DBus-activated daemon which controls mobile broadband
+The modem-manager snap is based on [upstream ModemManager](https://www.freedesktop.org/wiki/Software/ModemManager/), which is a DBus-activated daemon which controls mobile broadband
 (2G/3G/4G) devices and connections. ModemManager is able to prepare and
 configure a wide variety of modems and setup connections with them.
 
-ModemManager should be used in most cases jointly with the
+The modem-manager snap should be used in most cases jointly with the
 [network-manager](https://docs.ubuntu.com/core/en/stacks/network/network-manager/docs/index)
 snap. NetworkManager can be used to set cellular connection settings and to
 start and stop the connection. The recommended way of using a modem in [Ubuntu
@@ -21,20 +21,12 @@ automatically performed when using NetworkManager.
 
 ## What ModemManager Offers
 
-ModemManager offers a wide range of features, with the vast majority of them
-available in the snap version.
-
-The main features provided by the ModemManager snap are:
+The main features provided by ModemManager are:
 
  * Cellular connectivity for a [wide variety of
    modems](https://www.freedesktop.org/wiki/Software/ModemManager/SupportedDevices/)
- * SMS messages Support for USB modems Support for AT commands, QMI, and MBIM
- * interfaces
-
-What is not yet supported:
-
- * RS232 devices
- * Bluetooth-paired phones
+ * Support for AT commands, QMI, and MBIM interfaces
+ * SMS messages support for USB modems
 
 ## Upstream documentation
 
diff --git a/docs/installation.md b/docs/installation.md
index c74fda3..8b9d098 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -13,28 +13,22 @@ You can install the snap with the following command:
 
 ```text
 $ snap install modem-manager
-modem-manager 1.6.2-3 from 'canonical' installed
+modem-manager (1.10/stable) 1.10.0-4 from Canonical✓ installed
 ```
 
-Although the modem-manager snap is available from other channels (candidate,
-beta, edge), only the stable version should be used for production devices. The
-meaning of the other channels is internal to the development team of the
-modem-manager snap.
-
 All necessary plugs and slots will be automatically connected within the
 installation process. You can verify this with:
 
 ```text
-$ snap interfaces modem-manager
-Slot                   Plug
-modem-manager:service  modem-manager:mmcli
+$ snap connections modem-manager
+Interface      Plug                           Slot                   Notes
+modem-manager  modem-manager:mmcli            modem-manager:service  -
+modem-manager  network-manager:modem-manager  modem-manager:service  -
 ```
 
 We see here that the _mmcli_ command line utility can use the ModemManager
-service.
-
-**NOTE:** The _network-manager:modem-manager_ plug is connected to the
-_modem-manager:service_ slot when the NetworkManager snap is installed too.
+service and that network-manager can do the same (we will see that if
+the network-manager snap is already installed in the system).
 
 Once the installation has successfully finished the ModemManager service is
 running in the background. You can check its current status with
@@ -43,11 +37,11 @@ running in the background. You can check its current status with
 $ systemctl status snap.modem-manager.modemmanager.service 
 ● snap.modem-manager.modemmanager.service - Service for snap application modem-manager.modemmanager
    Loaded: loaded (/etc/systemd/system/snap.modem-manager.modemmanager.service; enabled; vendor preset: enabled)
-   Active: active (running) since Wed 2017-03-22 10:41:02 UTC; 3min 27s ago
- Main PID: 2518 (modemmanager)
+   Active: active (running) since Fri 2020-07-10 08:34:43 UTC; 2min 20s ago
+ Main PID: 2047 (ModemManager)
+    Tasks: 3 (limit: 569)
    CGroup: /system.slice/snap.modem-manager.modemmanager.service
-           ├─2518 /bin/sh /snap/modem-manager/39/bin/modemmanager
-           └─2525 /snap/modem-manager/39/usr/sbin/ModemManager
+           └─2047 /snap/modem-manager/414/usr/sbin/ModemManager --filter-policy=STRICT --log-level=INFO
 ```
 
 Now you have ModemManager successfully installed. In the next sections we will
@@ -63,6 +57,20 @@ desired.
 Finally, note that to run both _mmcli_ and _dbus-send_ we need root permissions, so
 we use _sudo_ with them.
 
+# modem-manager tracks and channels
+
+The modem-manager snap has currently three tracks:
+
+* __20__: Contains upstream version 1.12.8 and has a core20 base. The track name
+refers to the base snap and it is the convention being used at the moment.
+* __1.10__: Contains upstream version 1.10.0 and has a core18
+base. Nowadays, this is the one installed by default if the channel is
+not specified when running `snap install`. The track name refers to the
+upstream version. More modern releases have changed the convention so
+the track now refers to the base snap.
+* __latest__: Contains upstream version 1.8.0 and has a core16 base. Despite
+the unfortunate name (there are historical reasons for that) it is the oldest version.
+
 ## Next Steps
 
  * [Gathering Modem Information](gathering-modem-information.md)
diff --git a/docs/reference/available-commands.md b/docs/reference/available-commands.md
index a326fc5..acaaaf2 100644
--- a/docs/reference/available-commands.md
+++ b/docs/reference/available-commands.md
@@ -12,8 +12,34 @@ Further details about their usage is given on linked pages.
 
 ## mmcli
 
-The mmcli command offers a command-line based way to control and manage the
+The __mmcli__ command offers a command-line based way to control and manage the
 ModemManager service.
 
 An explanatory description of the command and available options is available
 [here](https://www.freedesktop.org/software/ModemManager/man/latest/mmcli.8.html)
+
+## modem-manager.mbimcli
+
+__mbimcli__ can be used to control directly devices that use the MBIM protocol.
+
+More details can be found in the [man page](http://manpages.ubuntu.com/manpages/focal/man1/mbimcli.1.html).
+
+## modem-manager.qmicli
+
+__qmicli__ can be used to control directly devices that use the QMI protocol.
+
+More details can be found in the [man page](http://manpages.ubuntu.com/manpages/focal/man1/qmicli.1.html).
+
+## modem-manager.mbim-network
+
+__mbim-network__ can be used to start a cellular connection for devices
+that support the MBIM protocol, mainly for debugging purposes.
+
+More details can be found in the [man page](http://manpages.ubuntu.com/manpages/focal/man1/mbim-network.1.html).
+
+## modem-manager.qmi-network
+
+__qmi-network__ can be used to start a cellular connection for devices
+that support the QMI protocol, mainly for debugging purposes.
+
+More details can be found in the [man page](http://manpages.ubuntu.com/manpages/focal/man1/qmi-network.1.html).
diff --git a/docs/reference/snap-configuration/debug.md b/docs/reference/snap-configuration/debug.md
index 16b3bd8..8250ec6 100644
--- a/docs/reference/snap-configuration/debug.md
+++ b/docs/reference/snap-configuration/debug.md
@@ -9,7 +9,7 @@ The debug configuration option controls the amount of logs produced by the
 modem-manager snap. It is useful for collecting information required to either
 report a bug or investigate a modem-manager failure.
 
-It is disabled by default and has to be explicitely turned on for usage.
+It is disabled by default and has to be explicitly turned on for usage.
 
 Note that the debug logs may contain sensitive information.
 
@@ -30,14 +30,14 @@ affects future executions of the MM daemon.
 
 **Example:** Enable debug feature
 
-```
+```text
 $ snap set modem-manager debug.enable=true
 ```
 
 <br/>
 **Example:** Disable debug feature.
 
-```
+```text
 $ snap set modem-manager debug.enable=false
 ```
 
@@ -46,6 +46,6 @@ $ snap set modem-manager debug.enable=false
 The debug information, when enabled, will be available in the journal and can
 be viewed with:
 
-```
+```text
 $ journalctl --no-pager -u snap.modem-manager.modemmanager.service
 ```
diff --git a/docs/release-notes.md b/docs/release-notes.md
index fe70927..3bfaeeb 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -14,30 +14,56 @@ installed:
 ```text
 $ snap info modem-manager
 name:      modem-manager
-summary:   "ModemManager is a service which controls mobile broadband"
-publisher: canonical
-contact:   [e-mail]
+summary:   ModemManager is a service which controls mobile broadband
+publisher: Canonical✓
+store-url: https://snapcraft.io/modem-manager
+contact:   [e-mail]
+license:   unset
 description: |
-  ModemManager is a DBus-activated daemon which controls mobile broadband
-  (2G/3G/4G) devices and connections. Whether built-in devices, USB dongles,
-  bluetooth-paired telephones or professional RS232/USB devices with external
-  power supplies, ModemManager is able to prepare and configure the modems and
-  setup connections with them.
+  ModemManager is a DBus-activated daemon which controls mobile broadband (2G/3G/4G) devices and
+  connections. Whether built-in devices, USB dongles, bluetooth-paired telephones or professional
+  RS232/USB devices with external power supplies, ModemManager is able to prepare and configure the
+  modems and setup connections with them.
+  
+  The modem-manager snap is usually used together with the network-manager snap. The snap is geared
+  towards devices and IoT and is optimized for Ubuntu Core. Its usage on desktop/server Ubuntu is
+  possible, but manual connection of interfaces is needed and do not expect full integration with
+  the GUI.
+  
+  Documentation on how to use the snap can be found in
+  https://docs.ubuntu.com/core/en/stacks/network/modem-manager/docs/.
+  
   Please find the source code at
   https://code.launchpad.net/~snappy-hwe-team/snappy-hwe-snaps/+git/modem-manager
-  
 commands:
-  - modem-manager.mmcli (mmcli)
-tracking:    stable
-installed:   1.6.2-3 (39) 5MB -
-refreshed:   2017-03-02 07:49:36 +0000 UTC
-channels:                 
-  stable:    1.6.2-3 (39) 5MB -
-  candidate: 1.6.2-3 (39) 5MB -
-  beta:      1.6.2-3 (39) 5MB -
-  edge:      1.6.2-3 (42) 5MB -
+  - modem-manager.mbim-network
+  - modem-manager.mbimcli
+  - modem-manager.mmcli
+  - modem-manager.qmi-network
+  - modem-manager.qmicli
+services:
+  modem-manager.modemmanager: simple, enabled, active
+snap-id:      KtwxgRlwCAVKFw92BUdt1WloH1Va3QPo
+tracking:     1.10/stable
+refresh-date: today at 08:34 UTC
+channels:
+  1.10/stable:      1.10.0-4     2020-01-21 (414) 1MB -
+  1.10/candidate:   1.10.0-4     2020-01-21 (414) 1MB -
+  1.10/beta:        1.10.0-4     2020-01-20 (414) 1MB -
+  1.10/edge:        1.10.0-5-dev 2020-02-11 (438) 1MB -
+  latest/stable:    1.8.0-12     2020-02-04 (426) 1MB -
+  latest/candidate: 1.8.0-12     2020-02-04 (426) 1MB -
+  latest/beta:      1.8.0-12     2020-01-21 (426) 1MB -
+  latest/edge:      1.8.0-12     2020-02-04 (426) 1MB -
+  20/stable:        –                                 
+  20/candidate:     –                                 
+  20/beta:          1.12.8-1     2020-06-22 (454) 1MB -
+  20/edge:          1.12.8-1-dev 2020-06-22 (451) 1MB -
+installed:          1.10.0-4                (414) 1MB -
 ```
-</br>
-## 1.6.2-3
 
- * Update to upstream version 1.6.2
+The detailed changelog for each version can be consulted in the sources for each track:
+
+* For track 20, [here](https://git.launchpad.net/~snappy-hwe-team/snappy-hwe-snaps/+git/modem-manager/tree/ChangeLog?h=snap-20)
+* For track 1.10, [here](https://git.launchpad.net/~snappy-hwe-team/snappy-hwe-snaps/+git/modem-manager/tree/ChangeLog?h=snap-1.10)
+* For track latest (note again this is not actually the more modern MM), [here](https://git.launchpad.net/~snappy-hwe-team/snappy-hwe-snaps/+git/modem-manager/tree/ChangeLog)
diff --git a/docs/report-bug.md b/docs/report-bug.md
index b263433..2ee29d2 100644
--- a/docs/report-bug.md
+++ b/docs/report-bug.md
@@ -6,6 +6,8 @@ table_of_contents: False
 # Report a Bug
 
 Bugs can be reported [here](https://bugs.launchpad.net/snappy-hwe-snaps/+filebug).
+Note that this is only for bugs for the snap, if you are using the debian
+package you should file bugs against the Ubuntu package.
 
 If the bug can be reproduced, [enabling the debug
 output](reference/snap-configuration/debug.md) before doing so is
@@ -21,7 +23,7 @@ And the output of the following command:
 $ sudo modem-manager.mmcli -m <N>
 ```
 
-, being <N> the modem number as reported by
+, being `<N>` the modem number as reported by
 
 ```text
 $ sudo modem-manager.mmcli -L
diff --git a/run-tests.sh b/run-tests.sh
index 0b0679d..7f827b6 100755
--- a/run-tests.sh
+++ b/run-tests.sh
@@ -1,4 +1,4 @@
-#!/bin/sh
+#!/bin/bash
 #
 # Copyright (C) 2016 Canonical Ltd
 #
@@ -16,64 +16,82 @@
 
 set -e
 
-TESTS_EXTRAS_URL="https://git.launchpad.net/~snappy-hwe-team/snappy-hwe-snaps/+git/tests-extras"
-TESTS_EXTRAS_PATH=".tests-extras"
+TESTS_EXTRAS_URL="https://git.launchpad.net/~snappy-hwe-team/snappy-hwe-snaps/+git/stack-snaps-tools"
+TESTS_EXTRAS_PATH="tests-extras"
 
-# Display help.
-# This has to be in sync with the tests-extras/test-runner.sh script
-# functionalities as the parameters to this one are passed directly there
-# this function will quit the script because of the 'exec' keyword
 show_help() {
     exec cat <<'EOF'
 Usage: run-tests.sh [OPTIONS]
 
 This is fetch & forget script and what it does is to fetch the
-tests-extras repository and execute the run-tests.sh script from
+stack-snaps-tools repository and execute the run-tests.sh script from
 there passing arguments as-is.
 
-optional arguments:
-  --help                 Show this help message and exit
-  --channel              Select another channel to build the base image from (default: stable)
-  --snap                 Extra snap to install
-  --debug                Enable verbose debugging output
-  --test-from-channel    Pull network-manager snap from the specified channel instead of building it from source
-  --force-new-image      Force generating a new image used for testing
+When you see this message you don't have the tests-extras folder
+successfully populated in your workspace yet. Please rerun without
+specifying --help to proceed with the initial clone of the git repository.
 EOF
 }
 
-# Clone the tests-extras repository
+# Clone the stack-snaps-tools repository
 clone_tests_extras() {
-	echo "INFO: Fetching tests-extras scripts into $TESTS_EXTRAS_PATH ..."
-	git clone -b master $TESTS_EXTRAS_URL $TESTS_EXTRAS_PATH >/dev/null 2>&1
-	if [ $? -ne 0 ]; then
-		echo "ERROR: Failed to fetch the $TESTS_EXTRAS_URL repo, exiting.."
-		exit 1
-	fi
+    echo "INFO: Fetching stack-snaps-tools scripts into $TESTS_EXTRAS_PATH ..."
+    if ! git clone -b master $TESTS_EXTRAS_URL $TESTS_EXTRAS_PATH >/dev/null 2>&1; then
+        echo "ERROR: Failed to fetch the $TESTS_EXTRAS_URL repo, exiting.."
+        exit 1
+    fi
 }
 
-# Make sure the already cloned tests-extras repository is in a known and update
+# Make sure the already cloned stack-snaps-tools repository is in a known and update
 # state before it is going to be used.
 restore_and_update_tests_extras() {
-	echo "INFO: Restoring and updating $TESTS_EXTRAS_PATH"
-	cd $TESTS_EXTRAS_PATH && git reset --hard && git clean -dfx && git pull
-	cd -
+    echo "INFO: Restoring and updating $TESTS_EXTRAS_PATH"
+    cd $TESTS_EXTRAS_PATH && git reset --hard && git clean -dfx && git pull
+    cd -
 }
 
 # ==============================================================================
-# This is fetch & forget script and what it does is to fetch the tests-extras
+# This is fetch & forget script and what it does is to fetch the stack-snaps-tools
 # repo and execute the run-tests.sh script from there passing arguments as-is.
 #
-# The tests-extras repository ends up checked out in the snap tree but as a
+# The stack-snaps-tools repository ends up checked out in the snap tree but as a
 # hidden directory which is re-used since then.
 
-# Display help w/o fetching anything and exit
-[ "$1" = "--help" ] && show_help
+# Find snap to use in the tests
+snaps=$(find . -maxdepth 1 -type f -name \
+             "*_*_$(dpkg-architecture -q DEB_HOST_ARCH).snap")
+while read -r snap_file; do
+    if [ -n "$snap" ]; then
+        printf "More than one snap revision in the folder\n"
+        exit 1
+    fi
+    snap=$PWD/${snap_file#*/}
+done < <(printf "%s\n" "$snaps")
+
+[ ! -d "$TESTS_EXTRAS_PATH" ] && [ "$1" = "--help" ] && show_help
 
 if [ -d "$TESTS_EXTRAS_PATH" ]; then
-	restore_and_update_tests_extras
+    restore_and_update_tests_extras
 else
-	clone_tests_extras
+    clone_tests_extras
+fi
+
+# Any project-specific options for test-runner should be specified in
+# .tests_config under EXTRA_ARGS
+if [ -f ".tests_config" ]; then
+    # shellcheck disable=SC1091
+    . .tests_config
 fi
 
+# Get backends
+backends="--backends="
+separator=""
+while read -r be; do
+    backends=$backends$separator${be##*.}
+    separator=,
+done < <(yq r spread.yaml --printMode p 'backends.qemu.systems[*].*')
+
 echo "INFO: Executing tests runner"
-cd $TESTS_EXTRAS_PATH && ./tests-runner.sh "$@"
+# shellcheck disable=SC2086
+cd $TESTS_EXTRAS_PATH &&
+    ./tests-runner.sh "$@" --snap="$snap" "$backends" $EXTRA_ARGS