@hello.nrfcloud.com/proto-map 4.0.0

package/lwm2m/unwrapNestedArray.spec.ts

@@ -0,0 +1,241 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { unwrapNestedArray } from './unwrapNestedArray.js'
+
+void describe('unwrapNestedArray()', () => {
+	void it('should unwrap an array', () =>
+		assert.deepEqual(
+			unwrapNestedArray({
+				LWM2M: {
+					$: {
+						'xmlns:xsi': 'http://www.w3.org/2001/XMLSchema-instance',
+						'xsi:noNamespaceSchemaLocation':
+							'http://www.openmobilealliance.org/tech/profiles/LWM2M-v1_1.xsd',
+					},
+					Object: [
+						{
+							$: { ObjectType: 'MODefinition' },
+							Name: ['Location'],
+							Description1: [
+								'This LwM2M Object provides a range of location telemetry related information which can be queried by the LwM2M Server.',
+							],
+							ObjectID: ['6'],
+							ObjectURN: ['urn:oma:lwm2m:oma:6'],
+							LWM2MVersion: ['1.0'],
+							ObjectVersion: ['1.0'],
+							MultipleInstances: ['Single'],
+							Mandatory: ['Optional'],
+							Resources: [
+								{
+									Item: [
+										{
+											$: { ID: '0' },
+											Name: ['Latitude'],
+											Operations: ['R'],
+											MultipleInstances: ['Single'],
+											Mandatory: ['Mandatory'],
+											Type: ['Float'],
+											RangeEnumeration: [''],
+											Units: ['lat'],
+											Description: [
+												'The decimal notation of latitude, e.g. -43.5723 [World Geodetic System 1984].',
+											],
+										},
+										{
+											$: { ID: '1' },
+											Name: ['Longitude'],
+											Operations: ['R'],
+											MultipleInstances: ['Single'],
+											Mandatory: ['Mandatory'],
+											Type: ['Float'],
+											RangeEnumeration: [''],
+											Units: ['lon'],
+											Description: [
+												'The decimal notation of longitude, e.g. 153.21760 [World Geodetic System 1984].',
+											],
+										},
+										{
+											$: { ID: '2' },
+											Name: ['Altitude'],
+											Operations: ['R'],
+											MultipleInstances: ['Single'],
+											Mandatory: ['Optional'],
+											Type: ['Float'],
+											RangeEnumeration: [''],
+											Units: ['m'],
+											Description: [
+												'The decimal notation of altitude in meters above sea level.',
+											],
+										},
+										{
+											$: { ID: '3' },
+											Name: ['Radius'],
+											Operations: ['R'],
+											MultipleInstances: ['Single'],
+											Mandatory: ['Optional'],
+											Type: ['Float'],
+											RangeEnumeration: [''],
+											Units: ['m'],
+											Description: [
+												'The value in this resource indicates the radius of a circular area in meters. The circular area is used to describe uncertainty about a point for coordinates in a two-dimensional coordinate reference systems (CRS). The center point of a circular area is specified by using the Latitude and the Longitude Resources.',
+											],
+										},
+										{
+											$: { ID: '4' },
+											Name: ['Velocity'],
+											Operations: ['R'],
+											MultipleInstances: ['Single'],
+											Mandatory: ['Optional'],
+											Type: ['Opaque'],
+											RangeEnumeration: [''],
+											Units: [''],
+											Description: [
+												'The velocity of the LwM2M Client, as defined in [3GPP-TS_23.032].',
+											],
+										},
+										{
+											$: { ID: '5' },
+											Name: ['Timestamp'],
+											Operations: ['R'],
+											MultipleInstances: ['Single'],
+											Mandatory: ['Mandatory'],
+											Type: ['Time'],
+											RangeEnumeration: [''],
+											Units: [''],
+											Description: [
+												'The timestamp of when the location measurement was performed.',
+											],
+										},
+										{
+											$: { ID: '6' },
+											Name: ['Speed'],
+											Operations: ['R'],
+											MultipleInstances: ['Single'],
+											Mandatory: ['Optional'],
+											Type: ['Float'],
+											RangeEnumeration: [''],
+											Units: ['m/s'],
+											Description: [
+												'Speed is the time rate of change in position of a LwM2M Client without regard for direction: the scalar component of velocity.',
+											],
+										},
+									],
+								},
+							],
+							Description2: [''],
+						},
+					],
+				},
+			}),
+			{
+				LWM2M: {
+					$: {
+						'xmlns:xsi': 'http://www.w3.org/2001/XMLSchema-instance',
+						'xsi:noNamespaceSchemaLocation':
+							'http://www.openmobilealliance.org/tech/profiles/LWM2M-v1_1.xsd',
+					},
+					Object: {
+						$: { ObjectType: 'MODefinition' },
+						Name: 'Location',
+						Description1:
+							'This LwM2M Object provides a range of location telemetry related information which can be queried by the LwM2M Server.',
+						ObjectID: '6',
+						ObjectURN: 'urn:oma:lwm2m:oma:6',
+						LWM2MVersion: '1.0',
+						ObjectVersion: '1.0',
+						MultipleInstances: 'Single',
+						Mandatory: 'Optional',
+						Resources: {
+							Item: [
+								{
+									$: { ID: '0' },
+									Name: 'Latitude',
+									Operations: 'R',
+									MultipleInstances: 'Single',
+									Mandatory: 'Mandatory',
+									Type: 'Float',
+									RangeEnumeration: '',
+									Units: 'lat',
+									Description:
+										'The decimal notation of latitude, e.g. -43.5723 [World Geodetic System 1984].',
+								},
+								{
+									$: { ID: '1' },
+									Name: 'Longitude',
+									Operations: 'R',
+									MultipleInstances: 'Single',
+									Mandatory: 'Mandatory',
+									Type: 'Float',
+									RangeEnumeration: '',
+									Units: 'lon',
+									Description:
+										'The decimal notation of longitude, e.g. 153.21760 [World Geodetic System 1984].',
+								},
+								{
+									$: { ID: '2' },
+									Name: 'Altitude',
+									Operations: 'R',
+									MultipleInstances: 'Single',
+									Mandatory: 'Optional',
+									Type: 'Float',
+									RangeEnumeration: '',
+									Units: 'm',
+									Description:
+										'The decimal notation of altitude in meters above sea level.',
+								},
+								{
+									$: { ID: '3' },
+									Name: 'Radius',
+									Operations: 'R',
+									MultipleInstances: 'Single',
+									Mandatory: 'Optional',
+									Type: 'Float',
+									RangeEnumeration: '',
+									Units: 'm',
+									Description:
+										'The value in this resource indicates the radius of a circular area in meters. The circular area is used to describe uncertainty about a point for coordinates in a two-dimensional coordinate reference systems (CRS). The center point of a circular area is specified by using the Latitude and the Longitude Resources.',
+								},
+								{
+									$: { ID: '4' },
+									Name: 'Velocity',
+									Operations: 'R',
+									MultipleInstances: 'Single',
+									Mandatory: 'Optional',
+									Type: 'Opaque',
+									RangeEnumeration: '',
+									Units: '',
+									Description:
+										'The velocity of the LwM2M Client, as defined in [3GPP-TS_23.032].',
+								},
+								{
+									$: { ID: '5' },
+									Name: 'Timestamp',
+									Operations: 'R',
+									MultipleInstances: 'Single',
+									Mandatory: 'Mandatory',
+									Type: 'Time',
+									RangeEnumeration: '',
+									Units: '',
+									Description:
+										'The timestamp of when the location measurement was performed.',
+								},
+								{
+									$: { ID: '6' },
+									Name: 'Speed',
+									Operations: 'R',
+									MultipleInstances: 'Single',
+									Mandatory: 'Optional',
+									Type: 'Float',
+									RangeEnumeration: '',
+									Units: 'm/s',
+									Description:
+										'Speed is the time rate of change in position of a LwM2M Client without regard for direction: the scalar component of velocity.',
+								},
+							],
+						},
+						Description2: '',
+					},
+				},
+			},
+		))
+})

package/lwm2m/unwrapNestedArray.ts

@@ -0,0 +1,27 @@
+/**
+ * A recursive function that walks through the given object and for each property checks if its value is an array and only has one element. If that is the case it takes the first element and uses it instead.
+ */
+export const unwrapNestedArray = (
+	object: Record<string, unknown>,
+): Record<string, unknown> => {
+	if (typeof object === 'string') return object
+	return Object.entries(object).reduce((result, [k, v]) => {
+		if (typeof v === 'string') return { ...result, [k]: v }
+		if (Array.isArray(v)) {
+			if (v.length === 1) {
+				return {
+					...result,
+					[k]: unwrapNestedArray(v[0]),
+				}
+			}
+			return {
+				...result,
+				[k]: v.map(unwrapNestedArray),
+			}
+		}
+		return {
+			...result,
+			[k]: unwrapNestedArray(v as Record<string, unknown>),
+		}
+	}, {})
+}

package/lwm2m/validate.ts

@@ -0,0 +1,30 @@
+import type { LwM2MObject } from './LwM2MObject.js'
+import { isLwM2MObject } from './validation.js'
+import { LwM2MObjectID } from './LwM2MObjectID.js'
+import type { LwM2MResourceValue } from '../senml/senMLtoLwM2M.js'
+
+export const validate =
+	(
+		validators: Map<
+			LwM2MObjectID,
+			(o: unknown, onError?: (error: Error) => void) => boolean
+		>,
+	) =>
+	(
+		o: unknown,
+		onError?: (error: Error) => void,
+	): o is LwM2MObject<{
+		ObjectID: LwM2MObjectID
+		ObjectVersion: string
+		Resources: Record<number, LwM2MResourceValue | undefined>
+	}> => {
+		if (!isLwM2MObject(o, onError)) {
+			return false
+		}
+		const validator = validators.get(o.ObjectID)
+		if (validator === undefined) {
+			onError?.(new Error(`No validator defined for ObjectID: ${o.ObjectID}!`))
+			return false
+		}
+		return validator(o, onError)
+	}

package/lwm2m/validation.ts

@@ -0,0 +1,120 @@
+import type { LwM2MResourceValue } from '../senml/senMLtoLwM2M.js'
+import { LwM2MObjectIDs, type LwM2MObjectID } from './LwM2MObjectID.js'
+
+export const isLwM2MObject = (
+	object: unknown,
+	onError?: (error: Error) => void,
+): object is {
+	ObjectID: LwM2MObjectID
+	/**
+	 * The Object Version of an Object is composed of 2 digits separated by a dot '.'
+	 *
+	 * @see https://www.openmobilealliance.org/release/LightweightM2M/V1_1_1-20190617-A/OMA-TS-LightweightM2M_Core-V1_1_1-20190617-A.pdf Section 7.2.2
+	 *
+	 * @default 1.0
+	 */
+	ObjectVersion?: string
+	Resources: Record<number, LwM2MResourceValue>
+} => {
+	const error = (message: string) => {
+		onError?.(new Error(message))
+		return false
+	}
+	// Must be an object
+	if (typeof object !== 'object' || object === null)
+		return error(`Not an object`)
+	// Must have valid ObjectID
+	if (
+		!('ObjectID' in object) ||
+		typeof object.ObjectID !== 'number' ||
+		object.ObjectID < 14200 ||
+		object.ObjectID > 15000 ||
+		LwM2MObjectIDs.includes(object.ObjectID) === false
+	)
+		return error(
+			`Not an valid Object ID: ${JSON.stringify((object as any).ObjectID)}`,
+		)
+	// ObjectVersion must be valid
+	if ('ObjectVersion' in object) {
+		if (
+			typeof object.ObjectVersion !== 'string' ||
+			!/^\d+\.\d+$/.test(object.ObjectVersion)
+		)
+			return error(`Invalid ObjectVersion`)
+	}
+	// Must have valid resources
+	if (
+		!('Resources' in object) ||
+		typeof object.Resources !== 'object' ||
+		object.Resources === null
+	)
+		return error(`Resources must be an object`)
+	// All keys must be numbers
+	if (
+		(Object.keys(object.Resources).find((k) => /[^\d]/.test(k))?.length ?? 0) >
+		0
+	)
+		return error(`All resource IDs must be a number`)
+	// All values must be number, string, boolean, or Date
+	for (const v of Object.values(object.Resources)) {
+		if (typeof v === 'string') continue
+		if (typeof v === 'boolean') continue
+		if (typeof v === 'number') continue
+		if (typeof v === 'object' && v instanceof Date) continue
+		return error(`Invalid value type ${typeof v}`)
+	}
+	return true
+}
+
+export const validate =
+	(
+		ObjectID: LwM2MObjectID,
+		ObjectVersion: string,
+		Resources: Record<number, (r: unknown) => boolean>,
+	) =>
+	(o: unknown, onError?: (error: Error) => void): boolean => {
+		const error = (message: string) => {
+			onError?.(new Error(message))
+			return false
+		}
+		if (!isLwM2MObject(o, onError)) return false
+		if (o.ObjectID !== ObjectID)
+			return error(
+				`Given Object ID ${o.ObjectID} does not match expected ${ObjectID}`,
+			)
+		if ((o.ObjectVersion ?? '1.0') !== ObjectVersion)
+			return error(
+				`Given Object version ${o.ObjectVersion} does not match expected ${ObjectVersion}`,
+			)
+		return Object.entries(Resources).reduce(
+			(allValid, [ResourceID, validator]) => {
+				if (!allValid) return false
+				if (validator(o.Resources[parseInt(ResourceID, 10)]) === false) {
+					return error(`Resource ${ResourceID} is invalid.`)
+				}
+				return allValid
+			},
+			true,
+		)
+	}
+
+export const NumberResource = (r: unknown): r is number => typeof r === 'number'
+export const StringResource = (r: unknown): r is string => typeof r === 'string'
+export const DateResource = (r: unknown): r is Date =>
+	typeof r === 'object' && r instanceof Date
+export const BooleanResource = (r: unknown): r is boolean =>
+	typeof r === 'boolean'
+
+export const OptionalResource =
+	(
+		validator:
+			| typeof NumberResource
+			| typeof StringResource
+			| typeof DateResource
+			| typeof BooleanResource,
+	) =>
+	(r: unknown): boolean =>
+		r === undefined ? true : validator(r)
+
+export const isLwM2MObjectID = (o: unknown): o is LwM2MObjectID =>
+	typeof o === 'number' && LwM2MObjectIDs.includes(o)

package/lwm2m/validators.ts

@@ -0,0 +1,21 @@
+import { LwM2MObjectID } from "./LwM2MObjectID.js";
+import { validate14201 } from "./object/validate14201.js";
+import { validate14202 } from "./object/validate14202.js";
+import { validate14203 } from "./object/validate14203.js";
+import { validate14204 } from "./object/validate14204.js";
+import { validate14205 } from "./object/validate14205.js";
+import { validate14210 } from "./object/validate14210.js";
+import { validate14220 } from "./object/validate14220.js";
+import { validate14230 } from "./object/validate14230.js";
+/**
+ * Contains the validators for all registered LwM2M objects.
+ */
+export const validators = new Map<LwM2MObjectID, (o: unknown) => boolean>();
+validators.set(LwM2MObjectID.Geolocation_14201, validate14201)
+validators.set(LwM2MObjectID.BatteryAndPower_14202, validate14202)
+validators.set(LwM2MObjectID.ConnectionInformation_14203, validate14203)
+validators.set(LwM2MObjectID.DeviceInformation_14204, validate14204)
+validators.set(LwM2MObjectID.Environment_14205, validate14205)
+validators.set(LwM2MObjectID.SolarCharge_14210, validate14210)
+validators.set(LwM2MObjectID.ButtonPress_14220, validate14220)
+validators.set(LwM2MObjectID.SeaWaterLevel_14230, validate14230)

package/models/PCA20035+solar/README.md

@@ -0,0 +1,10 @@
+# Thingy:91 with Solar Shield
+
+The Nordic Thingy:91 Solar Shield is a plug-and-play prototyping platform.
+Powerfoyle solar cell is mounted onto the Thingy to quickly get started
+exploring the endless possibilities with solar powered IoT applications and to
+develop products with eternal life or even battery-free products.​
+
+The Thingy:91 runs the
+[`asset_tracker_v2`](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/applications/asset_tracker_v2/README.html)
+application and sends messages to nRF Cloud using MQTT.

package/models/PCA20035+solar/transforms/airQuality.md

@@ -0,0 +1,48 @@
+---
+type: messages
+---
+
+# Environment sensor: air quality
+
+The Bosch BME680 sensor calculates an Air Quality Index.
+
+See
+<https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bme680-ds001.pdf>
+
+## Match Expression
+
+```jsonata
+appId = 'AIR_QUAL'
+```
+
+## Transform Expression
+
+```jsonata
+[
+    {"bn": "/14205/0/", "n": "10", "v": $number(data), "bt": ts }
+]
+```
+
+## Input Example
+
+```json
+{
+  "appId": "AIR_QUAL",
+  "messageType": "DATA",
+  "ts": 1681985384511,
+  "data": "177"
+}
+```
+
+## Result Example
+
+```json
+[
+  {
+    "bn": "/14205/0/",
+    "n": "10",
+    "v": 177,
+    "bt": 1681985384511
+  }
+]
+```

package/models/PCA20035+solar/transforms/battery.md

@@ -0,0 +1,46 @@
+---
+type: messages
+---
+
+# Battery state of charge
+
+This is the legacy battery state of charge using the modem's battery
+information.
+
+## Match Expression
+
+```jsonata
+appId = 'BATTERY'
+```
+
+## Transform Expression
+
+```jsonata
+[
+    {"bn": "/14202/0/", "n": "0", "v": $number(data), "bt": ts }
+]
+```
+
+## Input Example
+
+```json
+{
+  "appId": "BATTERY",
+  "messageType": "DATA",
+  "ts": 1687448260542,
+  "data": "94"
+}
+```
+
+## Result Example
+
+```json
+[
+  {
+    "bn": "/14202/0/",
+    "n": "0",
+    "v": 94,
+    "bt": 1687448260542
+  }
+]
+```

package/models/PCA20035+solar/transforms/button.md

@@ -0,0 +1,45 @@
+---
+type: messages
+---
+
+# Button Press
+
+Describes a button press.
+
+## Match Expression
+
+```jsonata
+appId = 'BUTTON'
+```
+
+## Transform Expression
+
+```jsonata
+[
+    {"bn": "/14220/0/", "n": "0", "v": $number(data), "bt": ts }
+]
+```
+
+## Input Example
+
+```json
+{
+  "data": "1",
+  "appId": "BUTTON",
+  "messageType": "DATA",
+  "ts": 1676366857236
+}
+```
+
+## Result Example
+
+```json
+[
+  {
+    "bn": "/14220/0/",
+    "n": "0",
+    "v": 1,
+    "bt": 1676366857236
+  }
+]
+```

package/models/PCA20035+solar/transforms/deviceInfo.md

@@ -0,0 +1,72 @@
+---
+type: messages
+---
+
+# Device info
+
+## Match Expression
+
+```jsonata
+appId = 'DEVICE' and $exists(data.deviceInfo)
+```
+
+## Transform Expression
+
+```jsonata
+[
+    {"bn": "/14204/0/", "n": "0", "vs": data.deviceInfo.imei, "bt": ts },
+    {"n": "1", "vs": data.deviceInfo.iccid },
+    {"n": "2", "vs": data.deviceInfo.modemFirmware },
+    {"n": "3", "vs": data.deviceInfo.appVersion },
+    {"n": "4", "vs": data.deviceInfo.board },
+    {"n": "5", "vs": data.deviceInfo.bat }
+]
+```
+
+## Input Example
+
+```json
+{
+  "appId": "DEVICE",
+  "messageType": "DATA",
+  "ts": 1676369307189,
+  "data": {
+    "deviceInfo": {
+      "imei": "350457794611739",
+      "iccid": "8931080620054223678",
+      "modemFirmware": "mfw_nrf9160_1.3.3",
+      "board": "thingy91_nrf9160",
+      "appVersion": "0.0.0-development"
+    }
+  }
+}
+```
+
+## Result Example
+
+```json
+[
+  {
+    "bn": "/14204/0/",
+    "n": "0",
+    "vs": "350457794611739",
+    "bt": 1676369307189
+  },
+  {
+    "n": "1",
+    "vs": "8931080620054223678"
+  },
+  {
+    "n": "2",
+    "vs": "mfw_nrf9160_1.3.3"
+  },
+  {
+    "n": "3",
+    "vs": "0.0.0-development"
+  },
+  {
+    "n": "4",
+    "vs": "thingy91_nrf9160"
+  }
+]
+```