[feature] Added WiFi Clients check to monitor AP load or inactivity

This new monitoring check generates alerts based on the number of
WiFi clients connected to an access point. It supports two alert types:

- **Maximum WiFi Clients**: Triggers when the total number of connected clients exceeds a predefined threshold,
  helping identify overloaded access points.
- **Minimum WiFi Clients**: Triggers when an access point has zero clients for a prolonged period,
  indicating potential hardware issues or poor placement.

The check is disabled by default. It can be enabled by changing the `OPENWISP_MONITORING_AUTO_WIFI_CLIENTS_CHECK` setting
or added manually from the device page.

A snooze schedule setting allows suppression of alerts
during scheduled maintenance or holiday periods.

docs/user/checks.rst

@@ -62,3 +62,40 @@ parameters used for iperf3 checks (e.g. timing, port, username, password,
     may need to update the :doc:`metric configuration
     <device-checks-and-alert-settings>` to enable alerts for the iperf3
     check.
+
+.. _wifi_clients_check:
+
+WiFi Clients
+------------
+
+This check sends alerts based on the total number of WiFi Clients
+connected to a device. It sends two types of alerts:
+
+- **Maximum WiFi Clients**: When the total number of WiFi clients
+  connected to an access point exceeds a predetermined threshold. This
+  functionality provides valuable insights into the network's performance,
+  signaling when a specific access point is overwhelmed by an excessive
+  number of WiFi clients.
+- **Minimum WiFi Clients**: When the total number of WiFi clients
+  connected to an access point remains at zero for a duration exceeding
+  the specified tolerance period. It serves as an indicator of whether the
+  access point is malfunctioning or if its placement is hindering user
+  connectivity.
+
+This check is **disabled by default**. To enable auto creation of this
+check, set :ref:`openwisp_monitoring_auto_wifi_clients_check` to ``True``
+and configure the task scheduling in your Django project:
+
+.. code-block:: python
+
+    from datetime import timedelta
+
+    OPENWISP_MONITORING_AUTO_WIFI_CLIENTS_CHECK = True
+
+You can also :doc:`add the WiFi Clients check
+<device-checks-and-alert-settings>` directly from the device page.
+
+You can use the
+:ref:`openwisp_monitoring_wifi_clients_check_snooze_schedule` setting to
+disable this check on specific dates, such as during scheduled
+maintenance, to avoid generating unnecessary alerts.

docs/user/settings.rst

@@ -297,6 +297,103 @@ check when running on multiple servers. Make sure it is always greater
 than the total iperf3 check time, i.e. greater than the TCP + UDP test
 time. By default, it is set to **600 seconds (10 mins)**.
 
+.. _openwisp_monitoring_auto_wifi_clients_check:
+
+``OPENWISP_MONITORING_AUTO_WIFI_CLIENTS_CHECK``
+-----------------------------------------------
+
+============ =========
+**type**:    ``bool``
+**default**: ``False``
+============ =========
+
+This setting allows you to choose whether :ref:`WiFi Clients
+<wifi_clients_check>` checks should be created automatically for newly
+registered devices. It's disabled by default.
+
+.. _openwisp_monitoring_wifi_clients_check_snooze_schedule:
+
+``OPENWISP_MONITORING_WIFI_CLIENTS_CHECK_SNOOZE_SCHEDULE``
+----------------------------------------------------------
+
+============ ========
+**type**:    ``list``
+**default**: ``[]``
+============ ========
+
+This setting allows you to configure date-time ranges when the :ref:`WiFi
+Clients <wifi_clients_check>` check should not be executed. The date-time
+ranges should be in the format ``(start_datetime, end_datetime)`` where
+both date-time are in the format ``MM-DD HH:MM`` (24 hours). Both start
+date and end date are inclusive. You can omit the date or time part as
+needed.
+
+E.g.:
+
+.. code-block:: python
+
+    OPENWISP_MONITORING_WIFI_CLIENTS_CHECK_SNOOZE_SCHEDULE = [
+        # Date ranges spanning across months
+        ("12-24", "01-05"),
+        # Single-day exclusion
+        ("01-26", "01-26"),
+        # Daily exclusion between specific times
+        ("22:00", "06:00"),
+        # Specific date and time range exclusion
+        ("08-15 12:00", "08-15 14:00"),
+    ]
+
+.. note::
+
+    **Date or Time Omission**:
+
+        - If you omit the date, the time range will be considered for
+          **every day**.
+        - If you omit the time, the exclusion will apply to the **entire
+          day**.
+
+.. _openwisp_monitoring_wifi_clients_max_check_interval:
+
+``OPENWISP_MONITORING_WIFI_CLIENTS_MAX_CHECK_INTERVAL``
+-------------------------------------------------------
+
+============ ==================
+**type**:    ``int``
+**default**: ``5`` (in minutes)
+============ ==================
+
+Time period in minutes used by :ref:`WiFi Clients checks
+<wifi_clients_check>` to monitor the maximum number of connected clients.
+
+It checks for clients that have connected at least once between the
+current time and the specified interval. For example, if the interval is
+set to *5 minutes*, OpenWISP will look for clients that connected within
+the last 5 minutes.
+
+.. _openwisp_monitoring_wifi_clients_min_check_interval:
+
+``OPENWISP_MONITORING_WIFI_CLIENTS_MIN_CHECK_INTERVAL``
+-------------------------------------------------------
+
+============ ============================
+**type**:    ``int``
+**default**: ``4320`` (3 days in minutes)
+============ ============================
+
+Time period in minutes used by :ref:`WiFi Clients checks
+<wifi_clients_check>` to monitor the minimum number of connected clients.
+
+It checks for clients that have connected at least once between the
+current time and the specified interval. For example, if the interval is
+set to *4320 minutes (3 days)*, OpenWISP will look for clients that
+connected within the last 3 days.
+
+.. note::
+
+    The default value of this setting is intentionally set higher to avoid
+    false alerts that could occur when no devices are connected over
+    holidays (e.g., weekends).
+
 .. _openwisp_monitoring_auto_charts:
 
 ``OPENWISP_MONITORING_AUTO_CHARTS``

openwisp_monitoring/check/apps.py

@@ -3,6 +3,7 @@
 from django.utils.translation import gettext_lazy as _
 from swapper import load_model
 
+from openwisp_monitoring.check import checks  # noqa
 from openwisp_monitoring.check import settings as app_settings
 
 
@@ -40,3 +41,12 @@ def _connect_signals(self):
                 sender=load_model('config', 'Device'),
                 dispatch_uid='auto_iperf3_check',
             )
+
+        if app_settings.AUTO_WIFI_CLIENTS_CHECK:
+            from .base.models import auto_wifi_clients_check_receiver
+
+            post_save.connect(
+                auto_wifi_clients_check_receiver,
+                sender=load_model('config', 'Device'),
+                dispatch_uid='auto_wifi_clients_check',
+            )

openwisp_monitoring/check/base/models.py

@@ -13,6 +13,7 @@
     auto_create_config_check,
     auto_create_iperf3_check,
     auto_create_ping,
+    auto_create_wifi_clients_check,
 )
 from openwisp_utils.base import TimeStampedEditableModel
 
@@ -160,3 +161,21 @@ def auto_iperf3_check_receiver(sender, instance, created, **kwargs):
             object_id=str(instance.pk),
         )
     )
+
+
+def auto_wifi_clients_check_receiver(sender, instance, created, **kwargs):
+    """Implements OPENWISP_MONITORING_AUTO_WIFI_CLIENTS_CHECK.
+
+    The creation step is executed in the background.
+    """
+    # we need to skip this otherwise this task will be executed
+    # every time the configuration is requested via checksum
+    if not created:
+        return
+    transaction_on_commit(
+        lambda: auto_create_wifi_clients_check.delay(
+            model=sender.__name__.lower(),
+            app_label=sender._meta.app_label,
+            object_id=str(instance.pk),
+        )
+    )

openwisp_monitoring/check/checks.py

@@ -0,0 +1,76 @@
+from datetime import datetime
+
+from django.core.checks import Error, register
+
+from . import settings as app_settings
+
+
+@register()
+def check_wifi_clients_snooze_schedule(app_configs, **kwargs):
+    errors = []
+    setting_name = 'OPENWISP_MONITORING_WIFI_CLIENTS_CHECK_SNOOZE_SCHEDULE'
+    schedule = app_settings.WIFI_CLIENTS_CHECK_SNOOZE_SCHEDULE
+
+    if not isinstance(schedule, (list, tuple)):
+        errors.append(
+            Error(
+                'Invalid schedule format',
+                hint='Schedule must be a list of date-time ranges',
+                obj=setting_name,
+            )
+        )
+        return errors
+
+    for item in schedule:
+        if not isinstance(item, (list, tuple)) or len(item) != 2:
+            errors.append(
+                Error(
+                    f'Invalid schedule entry format: {item}',
+                    hint='Each schedule entry must be a pair of start and end times',
+                    obj=setting_name,
+                )
+            )
+            continue
+
+        start, end = item
+        if not isinstance(start, str) or not isinstance(end, str):
+            errors.append(
+                Error(
+                    f'Invalid time format: {item}',
+                    hint='Use format "MM-DD HH:MM", "MM-DD", or "HH:MM"',
+                    obj=setting_name,
+                )
+            )
+            continue
+
+        try:
+            # Check if both are time format (HH:MM)
+            if '-' not in start and '-' not in end:
+                datetime.strptime(start, '%H:%M')
+                datetime.strptime(end, '%H:%M')
+            # Check if both are date format (MM-DD)
+            elif ':' not in start and ':' not in end:
+                datetime.strptime(start, '%m-%d')
+                datetime.strptime(end, '%m-%d')
+            # Check if both are date-time format (MM-DD HH:MM)
+            elif len(start.split()) == 2 and len(end.split()) == 2:
+                datetime.strptime(start, '%m-%d %H:%M')
+                datetime.strptime(end, '%m-%d %H:%M')
+            else:
+                errors.append(
+                    Error(
+                        f'Inconsistent format: {item}',
+                        hint='Both start and end must be in the same format (either both time or both date)',
+                        obj=setting_name,
+                    )
+                )
+        except ValueError:
+            errors.append(
+                Error(
+                    f'Invalid date-time format: {item}',
+                    hint='Use format "MM-DD HH:MM", "MM-DD", or "HH:MM"',
+                    obj=setting_name,
+                )
+            )
+
+    return errors

openwisp_monitoring/check/classes/__init__.py

@@ -1,3 +1,4 @@
 from .config_applied import ConfigApplied  # noqa
 from .iperf3 import Iperf3  # noqa
 from .ping import Ping  # noqa
+from .wifi_clients import WifiClients  # noqa

openwisp_monitoring/check/classes/base.py

@@ -27,6 +27,18 @@ def validate(self):
     def validate_params(self):
         pass
 
+    @classmethod
+    def may_execute(cls):
+        """
+        Class method that determines whether the check can be executed.
+
+        Returns:
+            bool: Always returns True by default.
+                Subclasses may override this method to implement
+                specific execution conditions.
+        """
+        return True
+
     def check(self, store=True):
         raise NotImplementedError