[feature] Implemented device deactivation and reactivation #625

docs/developer/utils.rst

@@ -146,6 +146,55 @@ object are changed, but only on ``post_add`` or ``post_remove`` actions,
 ``post_clear`` is ignored for the same reason explained in the previous
 section.
 
+``config_deactivating``
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Path**: ``openwisp_controller.config.signals.config_deactivating``
+
+**Arguments**:
+
+- ``instance``: instance of the object being deactivated
+- ``previous_status``: previous status of the object before deactivation
+
+This signal is emitted when a configuration status of device is set to
+``deactivating``.
+
+``config_deactivated``
+~~~~~~~~~~~~~~~~~~~~~~
+
+**Path**: ``openwisp_controller.config.signals.config_deactivated``
+
+**Arguments**:
+
+- ``instance``: instance of the object being deactivated
+- ``previous_status``: previous status of the object before deactivation
+
+This signal is emitted when a configuration status of device is set to
+``deactivated``.
+
+``device_deactivated``
+~~~~~~~~~~~~~~~~~~~~~~
+
+**Path**: ``openwisp_controller.config.signals.device_deactivated``
+
+**Arguments**:
+
+- ``instance``: instance of the device being deactivated
+
+This signal is emitted when a device is flagged for deactivation.
+
+``device_activated``
+~~~~~~~~~~~~~~~~~~~~
+
+**Path**: ``openwisp_controller.config.signals.device_activated``
+
+**Arguments**:
+
+- ``instance``: instance of the device being activated
+
+This signal is emitted when a device is flagged for activation (after
+deactivation).
+
 .. _config_backend_changed:
 
 ``config_backend_changed``

docs/index.rst

@@ -35,6 +35,7 @@ the OpenWISP architecture.
     :maxdepth: 1
 
     user/intro.rst
+    user/device-config-status.rst
     user/templates.rst
     user/variables.rst
     user/device-groups.rst

docs/user/device-config-status.rst

@@ -0,0 +1,38 @@
+Device Configuration Status
+===========================
+
+The device's configuration status (`Device.config.status`) indicates the
+current state of the configuration as managed by OpenWISP. The possible
+statuses and their meanings are explained below.
+
+``modified``
+------------
+
+The device configuration has been updated in OpenWISP, but these changes
+have not yet been applied to the device. The device is pending an update.
+
+``applied``
+-----------
+
+The device has successfully applied the configuration changes made in
+OpenWISP. The current configuration on the device matches the latest
+changes.
+
+``error``
+---------
+
+An issue occurred while applying the configuration to the device, causing
+the device to revert to its previous working configuration.
+
+``deactivating``
+----------------
+
+The device is in the process of being deactivated. The configuration is
+scheduled to be removed from the device.
+
+``deactivated``
+---------------
+
+The device has been deactivated. The configuration applied through
+OpenWISP has been removed, and any other operation to manage the device
+will be prevented or rejected.

docs/user/rest-api.rst

@@ -233,10 +233,29 @@ from the config of a device,
 Delete Device
 ~~~~~~~~~~~~~
 
+.. note::
+
+    A device must be deactivated before it can be deleted. Otherwise, an
+    ``HTTP 403 Forbidden`` response will be returned.
+
 .. code-block:: text
 
     DELETE /api/v1/controller/device/{id}/
 
+Deactivate Device
+~~~~~~~~~~~~~~~~~
+
+.. code-block:: text
+
+    POST /api/v1/controller/device/{id}/deactivate/
+
+Activate Device
+~~~~~~~~~~~~~~~
+
+.. code-block:: text
+
+    POST /api/v1/controller/device/{id}/activate/
+
 List Device Connections
 ~~~~~~~~~~~~~~~~~~~~~~~