[feature] Added device groups #203

README.rst

@@ -134,6 +134,7 @@ Config App
 * **configuration templates**: reduce repetition to the minimum
 * `configuration variables <#how-to-use-configuration-variables>`_: reference ansible-like variables in the configuration and templates
 * **template tags**: tag templates to automate different types of auto-configurations (eg: mesh, WDS, 4G)
+* **device groups**: add `devices to dedicated groups <#device-groups>`_ for easy management
 * **simple HTTP resources**: allow devices to automatically download configuration updates
 * **VPN management**: automatically provision VPN tunnels with unique x509 certificates
 
@@ -625,7 +626,18 @@ Allows to specify backend URL for API requests, if the frontend is hosted separa
 +--------------+----------+
 
 Allows to specify a `list` of tuples for adding commands as described in
-`'How to add commands"   <#how-to-add-commands>`_ section.
+`'How to add commands" <#how-to-add-commands>`_ section.
+
+``OPENWISP_CONTROLLER_DEVICEGROUP_SCHEMA``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
++--------------+------------------------------------------+
+| **type**:    | ``dict``                                 |
++--------------+------------------------------------------+
+| **default**: | ``{'type': 'object', 'properties': {}}`` |
++--------------+------------------------------------------+
+
+Allows specifying JSONSchema used for validating meta-data of `Device Group <#device-groups>`_.
 
 REST API
 --------
@@ -807,6 +819,27 @@ List locations with devices deployed (in GeoJSON format)
 
     GET api/v1/controller/location/geojson/
 
+List device groups
+^^^^^^^^^^^^^^^^^^
+
+.. code:: text
+
+    GET api/v1/controller/group/
+
+Create device group
+^^^^^^^^^^^^^^^^^^^
+
+.. code:: text
+
+    POST api/v1/controller/group/
+
+Get device group detail
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: text
+
+    GET /api/v1/controller/group/{id}/
+
 List templates
 ^^^^^^^^^^^^^^
 
@@ -1050,6 +1083,21 @@ Please refer
 `troubleshooting issues related to geospatial libraries
 <https://docs.djangoproject.com/en/2.1/ref/contrib/gis/install/#library-environment-settings/>`_.
 
+Device Groups
+-------------
+
+Device Groups provide an easy way to organize devices of a particular organization.
+You can achieve following by using Device Groups:
+
+- Group similar devices by having dedicated groups for access points, routers, etc.
+- Store additional information regarding a group in the structured metadata field.
+- Customize structure and validation of metadata field of DeviceGroup to standardize
+  information across all groups using `"OPENWISP_CONTROLLER_DEVICEGROUP_SCHEMA" <#openwisp-controller-devicegroup-schema>`_
+  setting.
+
+.. image:: https://raw.githubusercontent.com/openwisp/openwisp-controller/master/docs/device-groups.png
+  :alt: Device Group example
+
 How to use configuration variables
 ----------------------------------
 
@@ -1632,6 +1680,21 @@ The signal is emitted when the device name changes.
 
 It is not emitted when the device is created.
 
+``devicegroup_changed``
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Path**: ``openwisp_controller.config.signals.devicegroup_changed``
+
+**Arguments**:
+
+- ``instance``: instance of ``Device``.
+- ``group_id``: primary key of ``DeviceGroup`` of ``Device``
+- ``old_group_id``: primary key of previous ``DeviceGroup`` of ``Device``
+
+The signal is emitted when the device group changes.
+
+It is not emitted when the device is created.
+
 Setup (integrate in an existing django project)
 -----------------------------------------------
 
@@ -2013,6 +2076,7 @@ Once you have created the models, add the following to your ``settings.py``:
 
     # Setting models for swapper module
     CONFIG_DEVICE_MODEL = 'sample_config.Device'
+    CONFIG_DEVICEGROUP_MODEL = 'sample_config.DeviceGroup'
     CONFIG_CONFIG_MODEL = 'sample_config.Config'
     CONFIG_TEMPLATETAG_MODEL = 'sample_config.TemplateTag'
     CONFIG_TAGGEDTEMPLATE_MODEL = 'sample_config.TaggedTemplate'
@@ -2082,7 +2146,12 @@ sample_config
 
 .. code-block:: python
 
-    from openwisp_controller.config.admin import DeviceAdmin, TemplateAdmin, VpnAdmin
+    from openwisp_controller.config.admin import (
+        DeviceAdmin,
+        DeviceGroupAdmin,
+        TemplateAdmin,
+        VpnAdmin,
+    )
 
     # DeviceAdmin.fields += ['example'] <-- monkey patching example
 
@@ -2129,14 +2198,17 @@ sample_config
         DeviceAdmin as BaseDeviceAdmin,
         TemplateAdmin as BaseTemplateAdmin,
         VpnAdmin as BaseVpnAdmin,
+        DeviceGroupAdmin as BaseDeviceGroupAdmin,
     from swapper import load_model
 
     Vpn = load_model('openwisp_controller', 'Vpn')
     Device = load_model('openwisp_controller', 'Device')
+    DeviceGroup = load_model('openwisp_controller', 'DeviceGroup')
     Template = load_model('openwisp_controller', 'Template')
 
     admin.site.unregister(Vpn)
     admin.site.unregister(Device)
+    admin.site.unregister(DeviceGroup)
     admin.site.unregister(Template)
 
     @admin.register(Vpn)
@@ -2147,6 +2219,10 @@ sample_config
     class DeviceAdmin(BaseDeviceAdmin):
         # add your changes here
 
+    @admin.register(DeviceGroup)
+    class DeviceGroupAdmin(BaseDeviceGroupAdmin):
+        # add your changes here
+
     @admin.register(Template)
     class TemplateAdmin(BaseTemplateAdmin):
         # add your changes here

openwisp_controller/config/admin.py

@@ -13,11 +13,11 @@
     ObjectDoesNotExist,
     ValidationError,
 )
-from django.http import Http404, HttpResponse
+from django.http import Http404, HttpResponse, JsonResponse
 from django.shortcuts import get_object_or_404
 from django.template.loader import get_template
 from django.template.response import TemplateResponse
-from django.urls import reverse
+from django.urls import path, reverse
 from django.utils.translation import ugettext_lazy as _
 from flat_json_widget.widgets import FlatJsonWidget
 from swapper import load_model
@@ -41,12 +41,13 @@
 from . import settings as app_settings
 from .base.vpn import AbstractVpn
 from .utils import send_file
-from .widgets import JsonSchemaWidget
+from .widgets import DeviceGroupJsonSchemaWidget, JsonSchemaWidget
 
 logger = logging.getLogger(__name__)
 prefix = 'config/'
 Config = load_model('config', 'Config')
 Device = load_model('config', 'Device')
+DeviceGroup = load_model('config', 'DeviceGroup')
 Template = load_model('config', 'Template')
 Vpn = load_model('config', 'Vpn')
 Organization = load_model('openwisp_users', 'Organization')
@@ -385,6 +386,7 @@ class DeviceAdmin(MultitenantAdminMixin, BaseConfigAdmin, UUIDAdmin):
     list_display = [
         'name',
         'backend',
+        'group',
         'config_status',
         'mac_address',
         'ip',
@@ -408,12 +410,14 @@ class DeviceAdmin(MultitenantAdminMixin, BaseConfigAdmin, UUIDAdmin):
         'devicelocation__location__address',
     ]
     readonly_fields = ['last_ip', 'management_ip', 'uuid']
+    autocomplete_fields = ['group']
     fields = [
         'name',
         'organization',
         'mac_address',
         'uuid',
         'key',
+        'group',
         'last_ip',
         'management_ip',
         'model',
@@ -707,9 +711,58 @@ class Media(BaseConfigAdmin):
         js = list(BaseConfigAdmin.Media.js) + [f'{prefix}js/vpn.js']
 
 
+class DeviceGroupForm(BaseForm):
+    class Meta(BaseForm.Meta):
+        model = DeviceGroup
+        widgets = {'meta_data': DeviceGroupJsonSchemaWidget}
+        labels = {'meta_data': _('Metadata')}
+        help_texts = {
+            'meta_data': _(
+                'Group meta data, use this field to store data which is related'
+                'to this group and can be retrieved via the REST API.'
+            )
+        }
+
+
+class DeviceGroupAdmin(MultitenantAdminMixin, BaseAdmin):
+    form = DeviceGroupForm
+    fields = [
+        'name',
+        'organization',
+        'description',
+        'meta_data',
+        'created',
+        'modified',
+    ]
+    search_fields = ['name']
+    list_filter = [
+        ('organization', MultitenantOrgFilter),
+    ]
+
+    class Media:
+        css = {'all': (f'{prefix}css/admin.css',)}
+
+    def get_urls(self):
+        options = self.model._meta
+        url_prefix = f'{options.app_label}_{options.model_name}'
+        urls = super().get_urls()
+        urls += [
+            path(
+                f'{options.app_label}/{options.model_name}/ui/schema.json',
+                self.admin_site.admin_view(self.schema_view),
+                name=f'{url_prefix}_schema',
+            ),
+        ]
+        return urls
+
+    def schema_view(self, request):
+        return JsonResponse(app_settings.DEVICEGROUP_SCHEMA)
+
+
 admin.site.register(Device, DeviceAdmin)
 admin.site.register(Template, TemplateAdmin)
 admin.site.register(Vpn, VpnAdmin)
+admin.site.register(DeviceGroup, DeviceGroupAdmin)
 
 
 if getattr(app_settings, 'REGISTRATION_ENABLED', True):

openwisp_controller/config/api/serializers.py

@@ -10,6 +10,7 @@
 Template = load_model('config', 'Template')
 Vpn = load_model('config', 'Vpn')
 Device = load_model('config', 'Device')
+DeviceGroup = load_model('config', 'DeviceGroup')
 Config = load_model('config', 'Config')
 Organization = load_model('openwisp_users', 'Organization')
 
@@ -132,6 +133,7 @@ class Meta(BaseMeta):
             'id',
             'name',
             'organization',
+            'group',
             'mac_address',
             'key',
             'last_ip',
@@ -184,6 +186,7 @@ class Meta(BaseMeta):
             'id',
             'name',
             'organization',
+            'group',
             'mac_address',
             'key',
             'last_ip',
@@ -256,3 +259,19 @@ def update(self, instance, validated_data):
             instance.config.full_clean()
             instance.config.save()
         return super().update(instance, validated_data)
+
+
+class DeviceGroupSerializer(BaseSerializer):
+    meta_data = serializers.JSONField(required=False, initial={})
+
+    class Meta(BaseMeta):
+        model = DeviceGroup
+        fields = [
+            'id',
+            'name',
+            'organization',
+            'description',
+            'meta_data',
+            'created',
+            'modified',
+        ]

openwisp_controller/config/api/urls.py

@@ -38,6 +38,16 @@ def get_api_urls(api_views):
                 api_views.device_detail,
                 name='device_detail',
             ),
+            path(
+                'controller/group/',
+                api_views.devicegroup_list,
+                name='devicegroup_list',
+            ),
+            path(
+                'controller/group/<str:pk>/',
+                api_views.devicegroup_detail,
+                name='devicegroup_detail',
+            ),
             path(
                 'controller/device/<str:pk>/configuration/',
                 api_views.download_device_config,

openwisp_controller/config/api/views.py

@@ -15,6 +15,7 @@
 from ..admin import BaseConfigAdmin
 from .serializers import (
     DeviceDetailSerializer,
+    DeviceGroupSerializer,
     DeviceListSerializer,
     TemplateSerializer,
     VpnSerializer,
@@ -23,6 +24,7 @@
 Template = load_model('config', 'Template')
 Vpn = load_model('config', 'Vpn')
 Device = load_model('config', 'Device')
+DeviceGroup = load_model('config', 'DeviceGroup')
 Config = load_model('config', 'Config')
 
 
@@ -87,7 +89,9 @@ class DeviceListCreateView(ProtectedAPIMixin, ListCreateAPIView):
     """
 
     serializer_class = DeviceListSerializer
-    queryset = Device.objects.select_related('config').order_by('-created')
+    queryset = Device.objects.select_related(
+        'config', 'group', 'organization'
+    ).order_by('-created')
     pagination_class = ListViewPagination
 
 
@@ -98,7 +102,7 @@ class DeviceDetailView(ProtectedAPIMixin, RetrieveUpdateDestroyAPIView):
     """
 
     serializer_class = DeviceDetailSerializer
-    queryset = Device.objects.select_related('config')
+    queryset = Device.objects.select_related('config', 'group', 'organization')
 
 
 class DownloadDeviceView(ProtectedAPIMixin, RetrieveAPIView):
@@ -110,6 +114,17 @@ def retrieve(self, request, *args, **kwargs):
         return BaseConfigAdmin.download_view(self, request, pk=kwargs['pk'])
 
 
+class DeviceGroupListCreateView(ProtectedAPIMixin, ListCreateAPIView):
+    serializer_class = DeviceGroupSerializer
+    queryset = DeviceGroup.objects.select_related('organization').order_by('-created')
+    pagination_class = ListViewPagination
+
+
+class DeviceGroupDetailView(ProtectedAPIMixin, RetrieveUpdateDestroyAPIView):
+    serializer_class = DeviceGroupSerializer
+    queryset = DeviceGroup.objects.select_related('organization').order_by('-created')
+
+
 template_list = TemplateListCreateView.as_view()
 template_detail = TemplateDetailView.as_view()
 download_template_config = DownloadTemplateconfiguration.as_view()
@@ -118,4 +133,6 @@ def retrieve(self, request, *args, **kwargs):
 download_vpn_config = DownloadVpnView.as_view()
 device_list = DeviceListCreateView.as_view()
 device_detail = DeviceDetailView.as_view()
+devicegroup_list = DeviceGroupListCreateView.as_view()
+devicegroup_detail = DeviceGroupDetailView.as_view()
 download_device_config = DownloadDeviceView().as_view()

openwisp_controller/config/apps.py

@@ -89,6 +89,7 @@ def add_default_menu_items(self):
             {'model': get_model_name('config', 'Device')},
             {'model': get_model_name('config', 'Template')},
             {'model': get_model_name('config', 'Vpn')},
+            {'model': get_model_name('config', 'DeviceGroup')},
         ]
         if not hasattr(settings, menu_setting):
             setattr(settings, menu_setting, items)