[feature] GSoC25: Improve UX and Flexibility of the Firmware Upgrader Module

.github/workflows/ci.yml

@@ -73,21 +73,17 @@ jobs:
           pip install -U ${{ matrix.django-version }}
           sudo npm install -g prettier
 
-      - name: Start InfluxDB and redis
+      - name: Start redis
         if: ${{ !cancelled() && steps.deps.conclusion == 'success' }}
-        run: docker compose up -d postgres redis
+        run: docker compose up -d redis
 
       - name: QA checks
         run: |
           ./run-qa-checks
 
       - name: Tests
         if: ${{ !cancelled() && steps.deps.conclusion == 'success' }}
-        run: |
-          coverage run runtests.py --parallel
-          SAMPLE_APP=1 coverage run ./runtests.py --parallel --exclude-tag=selenium_tests
-          coverage combine
-          coverage xml
+        run: ./runtests
         env:
           SELENIUM_HEADLESS: 1
           GECKO_LOG: 1

.gitignore

@@ -49,6 +49,7 @@ coverage.xml
 tests/openwisp2/media/
 tests/openwisp2/private/
 !tests/openwisp2/private/firmware/fake-img*.bin
+tests/openwisp2/firmware/*
 
 # Sphinx documentation
 docs/_build/

docker-compose.yml

@@ -1,17 +1,6 @@
-version: "3"
-
 services:
   redis:
     image: redis:alpine
     ports:
       - "6379:6379"
     entrypoint: redis-server --appendonly yes
-
-  postgres:
-    image: postgis/postgis:15-3.4-alpine
-    environment:
-      POSTGRES_PASSWORD: openwisp2
-      POSTGRES_USER: openwisp2
-      POSTGRES_DB: openwisp2
-    ports:
-      - 5432:5432

docs/developer/index.rst

@@ -8,6 +8,7 @@ Developer Docs
 
     ./installation.rst
     ./extending.rst
+    ./utils.rst
 
 Other useful resources:
 

docs/developer/installation.rst

@@ -41,11 +41,11 @@ Navigate into the cloned repository:
 
 .. _firmware_upgrader_dev_docker:
 
-Launch Redis and PostgreSQL:
+Launch Redis:
 
 .. code-block:: shell
 
-    docker compose up -d redis postgres
+    docker compose up -d redis
 
 Setup and activate a virtual-environment (we'll be using `virtualenv
 <https://pypi.org/project/virtualenv/>`_):
@@ -99,7 +99,7 @@ windows are needed):
     celery -A openwisp2 worker -l info
     celery -A openwisp2 beat -l info
 
-Run quality assurance tests with:
+Run QA checks with:
 
 .. code-block:: shell
 
@@ -110,31 +110,16 @@ Run tests with (make sure you have the :ref:`selenium dependencies
 
 .. code-block:: shell
 
-    # standard tests
-    ./runtests.py
+    ./runtests
 
-Some tests, such as the Selenium UI tests, require a PostgreSQL database
-to run. If you don't have a PostgreSQL database running on your system,
-you can use the :ref:`Docker Compose configuration provided in this
-repository <firmware_upgrader_dev_docker>`. Once set up, you can run these
-specific tests as follows:
+``./runtests`` is a wrapper that runs tests for both
+``openwisp_firmware_upgrader`` and the SAMPLE_APP. To run only the
+SAMPLE_APP tests:
 
 .. code-block:: shell
 
-    # Run only specific selenium tests classes
-    cd tests/
-    DJANGO_SETTINGS_MODULE=openwisp2.postgresql_settings ./manage.py test openwisp_firmware_upgrader.tests.test_selenium.TestDeviceAdmin
-
-    # tests for the sample app
     SAMPLE_APP=1 ./runtests.py --keepdb --failfast
 
-When running the last line of the previous example, the environment
-variable ``SAMPLE_APP`` activates the app in
-``/tests/openwisp2/sample_firmware_upgrader/`` which is a simple django
-app that extends ``openwisp-firmware-upgrader`` with the sole purpose of
-testing its extensibility, for more information regarding this concept,
-read :doc:`extending`.
-
 .. important::
 
     If you want to add ``openwisp-firmware-upgrader`` to an existing

docs/developer/utils.rst

@@ -0,0 +1,31 @@
+Code Utilities
+==============
+
+.. include:: ../partials/developer-docs.rst
+
+.. contents:: **Table of Contents**:
+    :depth: 2
+    :local:
+
+Signals
+-------
+
+.. include:: /partials/signals-note.rst
+
+``firmware_upgrader_log_updated``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Path**:
+``openwisp_firmware_upgrader.signals.firmware_upgrader_log_updated``
+
+**Arguments**:
+
+- ``sender``: the model class that sent the signal (``UpgradeOperation``)
+- ``instance``: instance of ``UpgradeOperation`` which got its log updated
+- ``line``: the new log line that was appended
+- ``**kwargs``: additional keyword arguments
+
+This signal is emitted when the log content of an upgrade operation is
+updated. You can use this signal to perform custom actions when log
+updates occur, such as sending notifications, updating external systems,
+or logging to custom destinations.

docs/index.rst

@@ -38,9 +38,11 @@ within the OpenWISP architecture.
 
     ./user/intro.rst
     ./user/quickstart.rst
+    ./user/upgrade-status.rst
     ./user/automatic-device-firmware-detection.rst
     ./user/custom-firmware-upgrader.rst
     ./user/rest-api.rst
+    ./user/websocket-api.rst
     ./user/settings.rst
 
 .. toctree::

docs/user/intro.rst

@@ -9,7 +9,8 @@ Firmware Upgrader: Features
   or not
 - Prevents accidental multiple upgrades using the same firmware image
 - Single device upgrade
-- Mass upgrades
+- Mass upgrades with possibility of filtering by device group and/or
+  geographic location
 - Possibility to divide firmware images in categories
 - :doc:`REST API <rest-api>`
 - :doc:`Possibility of writing custom upgraders

docs/user/quickstart.rst

@@ -98,8 +98,8 @@ it.
 4. Perform a Firmware Upgrade to a Specific Device
 --------------------------------------------------
 
-.. image:: https://raw.githubusercontent.com/openwisp/openwisp-firmware-upgrader/docs/docs/images/quickstart-devicefirmware.gif
-    :target: https://raw.githubusercontent.com/openwisp/openwisp-firmware-upgrader/docs/docs/images/quickstart-devicefirmware.gif
+.. image:: https://raw.githubusercontent.com/openwisp/openwisp-firmware-upgrader/docs/docs/images/1.3/quickstart-devicefirmware.gif
+    :target: https://raw.githubusercontent.com/openwisp/openwisp-firmware-upgrader/docs/docs/images/1.3/quickstart-devicefirmware.gif
 
 Once a new build is ready, has been created in the system and its image
 have been uploaded, it will be the time to finally upgrade our devices.
@@ -110,15 +110,39 @@ then go to the "Firmware" tab.
 If you correctly filled **OS identifier** in step 2, you should have a
 situation similar to the one above: in this example, the device is using
 version ``1.0`` and we want to upgrade it to version ``2.0``, once the new
-firmware image is selected we just have to hit save, then a new tab will
-appear in the device page which allows us to see what's going on during
-the upgrade.
+firmware image is selected we just have to hit save, then a new tab
+"Recent Firmware Upgrades" will appear in the device page which allows us
+to observe in real time what's going on during the upgrade without
+requiring page reloads.
 
-Right now, the update of the upgrade information is not asynchronous yet,
-so you will have to reload the page periodically to find new information.
-This will be addressed in a future release.
+5. Canceling a Firmware Upgrade
+-------------------------------
 
-5. Performing Mass Upgrades
+If you need to cancel a firmware upgrade that is currently in progress on
+a specific device, you can do so from the device's firmware upgrade page.
+
+To cancel an ongoing upgrade:
+
+- Navigate to the device details page
+- Go to the "Firmware" tab
+- If an upgrade is in progress, you will see a "Cancel Upgrade" button
+- Click the "Cancel Upgrade" button to stop the upgrade process
+
+.. image:: https://raw.githubusercontent.com/openwisp/openwisp-firmware-upgrader/docs/docs/images/1.3/quickstart-cancel-upgrade.gif
+    :target: https://raw.githubusercontent.com/openwisp/openwisp-firmware-upgrader/docs/docs/images/1.3/quickstart-cancel-upgrade.gif
+
+Cancellation is only possible during the early stages of the upgrade
+process. Once the firmware flashing begins, the cancel button will be
+disabled and the upgrade cannot be stopped, as interrupting the flashing
+process could corrupt the device.
+
+The system automatically prevents cancellation during critical phases to
+ensure device safety.
+
+Once cancelled, the upgrade status will be updated to show that the
+operation was cancelled, and you can attempt a new upgrade if needed.
+
+6. Performing Mass Upgrades
 ---------------------------
 
 Before proceeding, please ensure the following preconditions are met:
@@ -134,16 +158,24 @@ At this stage you can try a mass upgrade by doing the following:
   devices to be upgraded with
 - click on "Mass-upgrade devices related to the selected build".
 
-.. image:: https://raw.githubusercontent.com/openwisp/openwisp-firmware-upgrader/docs/docs/images/quickstart-batch-upgrade.gif
-    :target: https://raw.githubusercontent.com/openwisp/openwisp-firmware-upgrader/docs/docs/images/quickstart-batch-upgrade.gif
+.. image:: https://raw.githubusercontent.com/openwisp/openwisp-firmware-upgrader/docs/docs/images/1.3/quickstart-batch-upgrade.gif
+    :target: https://raw.githubusercontent.com/openwisp/openwisp-firmware-upgrader/docs/docs/images/1.3/quickstart-batch-upgrade.gif
 
 At this point you should see a summary page which will inform you of which
-devices are going to be upgraded, you can either confirm the operation or
-cancel.
+devices are going to be upgraded. On this page, you can optionally filter
+the devices to be upgraded by:
 
-Once the operation is confirmed you will be redirected to a page in which
-you can monitor the progress of the upgrade operations.
+- **Device Group**: limit the upgrade to devices belonging to a specific
+  group
+- **Geographic Location**: limit the upgrade to devices at a specific
+  location
+
+These filters allow for more granular control over which devices are
+upgraded, making it easier to perform staged rollouts or target specific
+subsets of your device fleet.
 
-Right now, the update of the upgrade information is not asynchronous yet,
-so you will have to reload the page periodically to find new information.
-This will be addressed in a future release.
+After reviewing the selection and setting any desired filters, you can
+either confirm the operation or cancel.
+
+Once the operation is confirmed you will be redirected to a page in which
+you can monitor the progress of the upgrade operations in real time.

docs/user/rest-api.rst

@@ -83,7 +83,7 @@ List Mass Upgrade Operations
 The list of batch upgrade operations provides the following filters:
 
 - ``build`` (Firmware build ID)
-- ``status`` (One of: idle, in-progress, success, failed)
+- ``status`` (One of: idle, in-progress, success, failed, cancelled)
 
 Here's a few examples:
 
@@ -210,6 +210,25 @@ Upgrades all the devices related to the specified build ID.
 
     POST /api/v1/firmware-upgrader/build/{id}/upgrade/
 
+**Optional Parameters**
+
+The batch upgrade operation accepts the following optional parameters in
+the request body:
+
+- ``group`` (Device group ID): limit the upgrade to devices belonging to a
+  specific group
+- ``location`` (Location ID): limit the upgrade to devices at a specific
+  geographic location
+
+Example with filters:
+
+.. code-block:: json
+
+    {
+        "group": "{group_id}",
+        "location": "{location_id}"
+    }
+
 Dry-run Batch Upgrade
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -223,6 +242,25 @@ exists for a device which would be upgraded.
 
     GET /api/v1/firmware-upgrader/build/{id}/upgrade/
 
+**Optional Query Parameters**
+
+The dry-run batch upgrade operation accepts the following optional query
+parameters:
+
+- ``group`` (Device group ID): limit the preview to devices belonging to a
+  specific group
+- ``location`` (Location ID): limit the preview to devices at a specific
+  geographic location
+
+If both ``group`` and ``location`` are provided, only devices matching
+both filters are included.
+
+Example with filters:
+
+.. code-block:: text
+
+    GET /api/v1/firmware-upgrader/build/{id}/upgrade/?group={group_id}&location={location_id}
+
 List Firmware Categories
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -280,7 +318,7 @@ The list of upgrade operations provides the following filters:
 - ``device__organization_slug`` (Organization slug of the device)
 - ``device`` (Device ID)
 - ``image`` (Firmware image ID)
-- ``status`` (One of: in-progress, success, failed, aborted)
+- ``status`` (One of: in-progress, success, failed, aborted, cancelled)
 
 Here's a few examples:
 
@@ -299,6 +337,18 @@ Get Upgrade Operation Details
 
     GET /api/v1/firmware-upgrader/upgrade-operation/{id}
 
+Cancel Upgrade Operation
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: text
+
+    POST /api/v1/firmware-upgrader/upgrade-operation/{id}/cancel/
+
+.. note::
+
+    This endpoint may return a 409 status code if the operation cannot be
+    cancelled.
+
 List Device Upgrade Operations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -309,7 +359,7 @@ List Device Upgrade Operations
 **Available filters**
 
 The list of device upgrade operations can be filtered by ``status`` (one
-of: in-progress, success, failed, aborted).
+of: in-progress, success, failed, aborted, cancelled).
 
 .. code-block:: text