[docs] Documented geographic & indoor map features #660

Closes #660

Author: dee077

docs/index.rst

@@ -39,6 +39,7 @@ the OpenWISP architecture.
     ./user/intro.rst
     ./user/quickstart.rst
     ./user/device-health-status.rst
+    ./user/geo-indoor-maps.rst
     ./user/metrics.rst
     ./user/checks.rst
     ./user/alerts.rst

docs/user/geo-indoor-maps.rst

@@ -0,0 +1,66 @@
+Geographic and Indoor Maps
+==========================
+
+.. image:: https://raw.githubusercontent.com/openwisp/openwisp-monitoring/docs/docs/1.3/intro.gif
+    :alt: Intro
+
+OpenWISP provides a unified web interface to monitor network status across
+all scales: start with a global geographic overview, drill down into
+specific buildings via indoor maps, and switch between floors to track
+devices in real time.
+
+- **Indoor Map View with Floor Navigation:** The dashboard map includes an
+  indoor view with floor switching and fullscreen mode.
+
+  .. image:: https://raw.githubusercontent.com/openwisp/openwisp-monitoring/docs/docs/1.3/indoor-map-view.gif
+      :alt: Indoor map view
+
+- **Location View on Dedicated Map Page from Device Details Page:** The
+  device detail page provides navigation to a full-page geographic map for
+  the associated location.
+
+  .. image:: https://raw.githubusercontent.com/openwisp/openwisp-monitoring/docs/docs/1.3/view-on-general-map-button.gif
+      :alt: Location View from Device Details Page
+
+- **Indoor Device View on Dedicated Map Page from Device Details Page:**
+  The device detail page provides navigation to a full-page indoor map
+  showing the device position.
+
+  .. image:: https://raw.githubusercontent.com/openwisp/openwisp-monitoring/docs/docs/1.3/view-on-indoor-map-button.gif
+      :alt: Indoor Device View from Device Details Page
+
+- **Shareable Geographic Map URLs:** Interactions with location or device
+  nodes on the geographic map update the URL.
+
+  .. image:: https://raw.githubusercontent.com/openwisp/openwisp-monitoring/docs/docs/1.3/bookmark-url-map.gif
+      :alt: Shareable Geographic Map URLs
+
+- **Shareable Indoor Map URLs:** Interactions with indoor device nodes
+  update the URL.
+
+  .. image:: https://raw.githubusercontent.com/openwisp/openwisp-monitoring/docs/docs/1.3/bookmark-url-indoor-map.gif
+      :alt: Shareable Indoor Map URLs
+
+- **Real-Time Device Position Updates:** Device positions on the map are
+  updated when new location data is received.
+
+  .. image:: https://raw.githubusercontent.com/openwisp/openwisp-monitoring/docs/docs/1.3/moving-devices.gif
+      :alt: Real-Time Device Position Updates
+
+- **WebSocket-Based Real-Time Location Updates:** Real-time map updates
+  are delivered using WebSocket connections, allowing the frontend to
+  receive live location data without polling. The common location
+  broadcast channel is available at ``/ws/loci/location/`` and is used to
+  push device location updates to geographic map views as soon as new data
+  is received.
+
+  The location broadcast channel requires authentication. Access is
+  controlled based on organization membership:
+
+  - **Superusers:** Can receive location updates for all organizations.
+  - **Regular Users:** Can only receive location updates for organizations
+    they manage.
+
+  This ensures that location data is properly scoped and users can only
+  receive real-time updates for locations within their managed
+  organizations.

docs/user/intro.rst

@@ -16,6 +16,10 @@ OpenWISP provides the following monitoring capabilities:
   like uptime, RAM status, CPU load averages, Interface properties and
   addresses, WiFi interface status and associated clients, Neighbors
   information, DHCP Leases, Disk/Flash status
+- Provides advanced geographic and indoor map visualizations, including
+  floor-based indoor maps, shareable map URLs and navigation, and
+  real-time device position updates as described in :doc:`Geographic and
+  Indoor Maps <geo-indoor-maps>`.
 - Monitoring charts for :ref:`ping success rate <ping>`, :ref:`packet loss
   <ping>`, :ref:`round trip time (latency) <ping>`, :ref:`associated wifi
   clients <wifi_clients>`, :ref:`interface traffic <traffic>`, :ref:`RAM

docs/user/rest-api.rst

@@ -237,7 +237,7 @@ Returns a list of network devices deployed in the specified location.
 
 **Available filters**
 
-- ``search`` (search by device name)
+- ``search`` (search by device name or MAC address)
 - ``status`` (monitoring status of the device; multiple statuses can be
   provided and will be treated as OR filters)