feat: add support for WiFi site surveys (#619)

Fixes #605

Co-authored-by: Markus Tacker <[email protected]>

docs/app/Index.rst

@@ -36,3 +36,4 @@ The web application offers the following features:
    :caption: Subpages:
 
    CellGeolocation.rst
+   WiFiGeolocation.rst

docs/app/WiFiGeolocation.rst

@@ -0,0 +1,23 @@
+.. _app-wifigeolocation:
+
+Wi-Fi geolocation
+#################
+
+.. contents::
+   :local:
+   :depth: 2
+
+If Wi-Fi site survey geolocation (Ground Fix service) is implemented, the devices can be shown on the map based on the location of the Wi-Fi access points nearby them.
+
+Third-party location APIs
+*************************
+
+nRF Asset Tracker implements the following third-party location APIs:
+
+ * nRF Cloud Location Services
+
+These APIs enable calculation of the rough location of a device as soon as it sends the information for the nearest Wi-Fi access points to the cloud.
+
+Follow the configuration guide in the respective implementation to enable nRF Cloud's Ground Fix API:
+
+* :ref:`AWS <aws-nrf-cloud-location-services>`

docs/cloud-protocol/DeviceDataAndConfiguration.rst

@@ -65,6 +65,14 @@ The cloud publishes a link to the data to the ``<device Id>/pgps`` topic in the
 See the `P-GPS response JSON document <./pgps-response.json>`_ for an example response.
 The device can then use HTTP or HTTPS to download the P-GPS data.
 
+Wi-Fi site survey data
+======================
+
+If supported through enabling :ref:`aws-nrf-cloud-location-services`, the device can request Wi-Fi site survey data through MQTT.
+
+The Wi-Fi site survey message published by the device is described in detail in the `Wi-Fi site survey JSON schema file <./wifi-site-survey.schema.json>`_.
+See the `Wi-Fi site survey request JSON document <./wifi-site-survey.json>`_ for an example request.
+
 .. _batch-messages:
 
 Batch data

docs/cloud-protocol/validate-schema.spec.ts

@@ -28,6 +28,7 @@ describe('schemas', () => {
 		['agps-request', undefined],
 		['pgps-request', undefined],
 		['pgps-response', undefined],
+		['wifi-site-survey', undefined],
 	])('%s should validate', async (schema, example) => {
 		const validate = ajv.getSchema(
 			`https://github.com/NordicSemiconductor/asset-tracker-cloud-docs/blob/saga/docs/cloud-protocol/${schema}.schema.json`,

docs/cloud-protocol/wifi-site-survey.json

@@ -0,0 +1,39 @@
+{
+  "v": [
+    {
+      "mac": "40:01:7a:c9:10:22",
+      "ssid": "TnGroup",
+      "rssi": -65,
+      "chan": 1
+    },
+    {
+      "mac": "96:15:44:ac:6c:87",
+      "ssid": "Geotek",
+      "rssi": -71,
+      "chan": 1
+    },
+    {
+      "mac": "80:e0:1d:2a:92:f2",
+      "ssid": "TnGroup",
+      "rssi": -70
+    },
+    {
+      "mac": "40:01:7a:c9:10:21",
+      "ssid": "Telenor_Guest",
+      "chan": 1
+    },
+    {
+      "mac": "40:01:7a:c9:10:27",
+      "rssi": -65,
+      "chan": 1
+    },
+    {
+      "mac": "80:e0:1d:2a:92:f1",
+      "chan": 1
+    },
+    {
+      "mac": "80:e0:1d:2a:92:f5"
+    }
+  ],
+  "ts": 1670591331896
+}

docs/cloud-protocol/wifi-site-survey.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/NordicSemiconductor/asset-tracker-cloud-docs/blob/saga/docs/cloud-protocol/wifi-site-survey.schema.json",
+  "title": "Asset Tracker v2 Wi-Fi site survey request",
+  "description": "Describes the format used by the device to publish Wi-Fi site surveys.",
+  "type": "object",
+  "properties": {
+    "v": {
+      "type": "array",
+      "description": "The nearby Wi-Fi access points.",
+      "minItems": 2,
+      "items": {
+        "type": "object",
+        "properties": {
+          "mac": {
+            "type": "string",
+            "description": "Access point MAC address. String comprised of 6 hexadecimal pairs, separated by colons or dashes",
+            "pattern": "^([A-Fa-f0-9]{2}[:-]){5}[A-Fa-f0-9]{2}$",
+            "examples": ["80:e0:1d:2a:92:f1"]
+          },
+          "ssid": {
+            "type": "string",
+            "description": "Access point SSID.",
+            "examples": ["Telenor_Guest"]
+          },
+          "rssi": {
+            "type": "integer",
+            "description": "Received signal strength indicator is a measurement of how well your device can hear a signal from an access point measured in dBm",
+            "minimum": -128,
+            "maximum": 0,
+            "examples": [-65]
+          },
+          "chan": {
+            "type": "integer",
+            "description": "A Wi-Fi channel is to send and receive data.",
+            "examples": [1]
+          }
+        },
+        "required": ["mac"],
+        "additionalProperties": false
+      }
+    },
+    "ts": {
+      "description": "Timestamp as Unix epoch with millisecond precision (UTC) when the neighboring cell measurement report was received",
+      "type": "integer",
+      "minimum": 1234567890123,
+      "examples": [1584533788029]
+    }
+  },
+  "required": ["v", "ts"],
+  "additionalProperties": false
+}