feat(measuremodels): add optional local names and unit to measure definitions

doc/2/concepts/models/index.md

@@ -2,7 +2,7 @@
 code: false
 type: page
 title: Models
-description: Assets and Devices Models
+description: Assets, Measure and Devices Models
 ---
 
 # Models
@@ -58,6 +58,53 @@ The API also allows to:
 - list available models `device-manager/models:listDevices`
 - get a model `device-manager/models:getDevices`
 
+
+## Measure Model
+
+A measure model contains the following information:
+
+- `model`: model name
+- `measure`: type of the measure
+- `valuesMappings`: measurements mappings (See [Collection Mappings](https://docs.kuzzle.io/core/2/guides/main-concepts/data-storage/#collection-mappings))
+- `valuesDetails`: (optional) Metadata and translations of measurements. You can use it to keep consistency on translations between your apps
+
+It is possible to create new models on the Kuzzle IoT Platform using either:
+
+- the API through the action `device-manager/models:writeMeasure`
+- the framework with the method `deviceManager.models.registerMeasure`
+
+**Example: declaration of a model via API**
+
+```typescript
+await sdk.query({
+      controller: 'device-manager/models',
+      action: 'writeMeasure',
+      body: {
+        type: 'light',
+        valuesMappings: {
+          light: { type: 'integer' },
+        },
+        valuesDetails: {
+          light: {
+            en: {
+              friendlyName: 'Light intensity',
+              unit: 'lux',
+            },
+            fr: {
+              friendlyName: 'Intensité lumineuse',
+              unit: 'lux',
+            },
+          },
+        },
+      },
+    });
+```
+
+The API also allows to:
+
+- list registered measures `device-manager/models:listMeasures`
+- get a measure model `device-manager/models:getMeasure`
+
 ## Asset Model
 
 Unlike sensors and metrics which are available for all engine groups, asset models are specific to a particular engine group.

doc/2/controllers/models/write-measure/index.md

@@ -31,6 +31,10 @@ Method: POST
     "valuesMappings": {
       // Values mappings
     },
+      // Optional
+    "valuesDetails":{
+      // Values details and translation
+    }
   }
 }
 ```
@@ -41,6 +45,7 @@ Method: POST
 
 - `model`: Measure model name
 - `valuesMappings`: Mappings of the measure values in Elasticsearch format
+- `valuesDetails`: (optional) Measurement translations and units
 
 ---
 

lib/modules/measure/measures/BatteryMeasure.ts

@@ -8,4 +8,17 @@ export type BatteryMeasurement = {
 
 export const batteryMeasureDefinition: MeasureDefinition = {
   valuesMappings: { battery: { type: "integer" } },
+
+  valuesDetails: {
+    battery: {
+      en: {
+        friendlyName: "Battery level",
+        unit: "%",
+      },
+      fr: {
+        friendlyName: "Niveau de batterie",
+        unit: "%",
+      },
+    },
+  },
 };

lib/modules/measure/measures/HumidityMeasure.ts

@@ -8,4 +8,16 @@ export type HumidityMeasurement = {
 
 export const humidityMeasureDefinition: MeasureDefinition = {
   valuesMappings: { humidity: { type: "float" } },
+  valuesDetails: {
+    humidity: {
+      en: {
+        friendlyName: "Relative humidity",
+        unit: "%",
+      },
+      fr: {
+        friendlyName: "Humidité relative",
+        unit: "%",
+      },
+    },
+  },
 };

lib/modules/measure/measures/MovementMeasure.ts

@@ -8,4 +8,14 @@ export type MovementMeasurement = {
 
 export const movementMeasureDefinition: MeasureDefinition = {
   valuesMappings: { movement: { type: "boolean" } },
+  valuesDetails: {
+    movement: {
+      en: {
+        friendlyName: "Movement detection",
+      },
+      fr: {
+        friendlyName: "Détection de mouvement",
+      },
+    },
+  },
 };

lib/modules/measure/measures/PositionMeasure.ts

@@ -17,4 +17,26 @@ export const positionMeasureDefinition: MeasureDefinition = {
     accuracy: { type: "float" },
     altitude: { type: "float" },
   },
+  valuesDetails: {
+    position: {
+      en: {
+        friendlyName: "Localization",
+        unit: "(lat,lon)",
+      },
+      fr: {
+        friendlyName: "Localisation",
+        unit: "(lat,lon)",
+      },
+    },
+    altitude: {
+      en: {
+        friendlyName: "Altitude",
+        unit: "m",
+      },
+      fr: {
+        friendlyName: "Altitude",
+        unit: "m",
+      },
+    },
+  },
 };

lib/modules/measure/measures/TemperatureMeasure.ts

@@ -8,4 +8,16 @@ export type TemperatureMeasurement = {
 
 export const temperatureMeasureDefinition: MeasureDefinition = {
   valuesMappings: { temperature: { type: "float" } },
+  valuesDetails: {
+    temperature: {
+      en: {
+        friendlyName: "Temperature",
+        unit: "°C",
+      },
+      fr: {
+        friendlyName: "Température",
+        unit: "°C",
+      },
+    },
+  },
 };

lib/modules/measure/types/MeasureDefinition.ts

@@ -1,16 +1,58 @@
 import { JSONObject } from "kuzzle-sdk";
 
+/* *
+ * Represents a measure information and localization
+ *
+ * @example
+ * {
+ *  en: {
+ *    friendlyName: "Temperature",
+ *    unit: "°C",
+ *  },
+ *  fr: {
+ *    friendlyName: "Température",
+ *    unit: "°C",
+ *  },
+ *}
+ */
+
+interface MeasureLocales {
+  [localeString: string]: {
+    friendlyName: string;
+    unit?: string;
+  };
+}
+
+export interface MeasureValuesDetails {
+  [valueName: string]: MeasureLocales;
+}
 /**
  * Represents a measure definition registered by the Device Manager
  *
  * @example
- * {
- *   valuesMappings: { temperature: { type: 'float' } },
- * }
+ *{
+ * valuesMappings: { temperature: { type: "float" } },
+ * valuesDetails: {
+ *   temperature: {
+ *     en: {
+ *       friendlyName: "Temperature",
+ *       unit: "°C",
+ *     },
+ *     fr: {
+ *       friendlyName: "Température",
+ *       unit: "°C",
+ *     },
+ *   },
+ * },
+ *}
  */
+
 export interface MeasureDefinition {
   /**
    * Mappings for the measurement values in order to index the fields
    */
   valuesMappings: JSONObject;
+  valuesDetails?: {
+    [valueName: string]: MeasureLocales;
+  };
 }

lib/modules/model/ModelService.ts

@@ -36,6 +36,7 @@ import {
   AskModelMeasureGet,
 } from "./types/ModelEvents";
 import { MappingsConflictsError } from "./MappingsConflictsError";
+import { MeasureValuesDetails } from "../measure";
 
 export class ModelService extends BaseService {
   constructor(plugin: DeviceManagerPlugin) {
@@ -316,9 +317,14 @@ export class ModelService extends BaseService {
   async writeMeasure(
     type: string,
     valuesMappings: JSONObject,
+    valuesDetails?: MeasureValuesDetails,
   ): Promise<KDocument<MeasureModelContent>> {
     const modelContent: MeasureModelContent = {
-      measure: { type, valuesMappings },
+      measure: {
+        type,
+        valuesDetails,
+        valuesMappings,
+      },
       type: "measure",
     };
 

lib/modules/model/ModelsController.ts

@@ -154,10 +154,11 @@ export class ModelsController {
   ): Promise<ApiModelWriteMeasureResult> {
     const type = request.getBodyString("type");
     const valuesMappings = request.getBodyObject("valuesMappings");
-
+    const valuesDetails = request.getBodyObject("valuesDetails", {});
     const measureModel = await this.modelService.writeMeasure(
       type,
       valuesMappings,
+      valuesDetails,
     );
 
     return measureModel;

lib/modules/model/ModelsRegister.ts

@@ -132,7 +132,11 @@ export class ModelsRegister {
 
   registerMeasure(type: string, measureDefinition: MeasureDefinition) {
     this.measureModels.push({
-      measure: { type, valuesMappings: measureDefinition.valuesMappings },
+      measure: {
+        type,
+        valuesDetails: measureDefinition.valuesDetails,
+        valuesMappings: measureDefinition.valuesMappings,
+      },
       type: "measure",
     });
   }

lib/modules/model/collections/modelsMappings.ts

@@ -21,6 +21,10 @@ export const modelsMappings: CollectionMappings = {
           dynamic: "false",
           properties: {},
         },
+        valuesDetails: {
+          dynamic: "false",
+          properties: {},
+        },
       },
     },
 

lib/modules/model/types/ModelApi.ts

@@ -8,6 +8,7 @@ import {
   MetadataGroups,
   MetadataMappings,
 } from "./ModelContent";
+import { MeasureValuesDetails } from "../../measure/types/MeasureDefinition";
 
 interface ModelsControllerRequest {
   controller: "device-manager/models";
@@ -67,6 +68,7 @@ export interface ApiModelWriteMeasureRequest extends ModelsControllerRequest {
   body: {
     type: string;
     valuesMappings: JSONObject;
+    valuesDetails?: MeasureValuesDetails;
   };
 }
 export type ApiModelWriteMeasureResult = KDocument<MeasureModelContent>;

tests/fixtures/rights.ts

@@ -22,6 +22,14 @@ export default {
         },
       },
     },
+    "default-user": {
+      content: {
+        profileIds: ["default-user"],
+      },
+      credentials: {
+        local: { username: "default-user", password: "password" },
+      },
+    },
   },
   profiles: {
     "ayse-admin": {
@@ -70,7 +78,21 @@ export default {
         },
       ],
     },
+    "default-user": {
+      rateLimit: 0,
+      policies: [
+        {
+          roleId: "default-user",
+        },
+      ],
+      optimizedPolicies: [
+        {
+          roleId: "default-user",
+        },
+      ],
+    },
   },
+
   roles: {
     tests: {
       controllers: {
@@ -92,5 +114,14 @@ export default {
         },
       },
     },
+    "default-user": {
+      controllers: {
+        "device-manager/assets": {
+          actions: {
+            "*": true,
+          },
+        },
+      },
+    },
   },
 };

tests/hooks/engines.ts

@@ -1,4 +1,5 @@
 import { BaseRequest, JSONObject, Kuzzle } from "kuzzle-sdk";
+import { loadSecurityDefault } from "./security";
 
 async function createEngineIfNotExists(
   sdk: Kuzzle,
@@ -24,6 +25,7 @@ async function createEngineIfNotExists(
 }
 
 export async function beforeAllCreateEngines(sdk: Kuzzle) {
+  await loadSecurityDefault(sdk);
   await Promise.all([
     createEngineIfNotExists(sdk, "engine-ayse"),
     createEngineIfNotExists(sdk, "engine-kuzzle"),