0.126.0

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 #### Upcoming Changes
 
+### 0.126 (2022-10-24)
+
+##### DeviceService
+
+- Added a new device service to make updates to devices easier.
+
 ### 0.125 (2022-10-17)
 
 ##### EasypulseService

base.proto

@@ -353,6 +353,11 @@ message Filter {
         }
     }
 
+    message ModemIdentifiers {
+        repeated string include = 1;
+        repeated string exclude = 2;
+    }
+
     message Tags {
         repeated int64 include = 1;
         repeated int64 exclude = 2;
@@ -403,8 +408,59 @@ message Filter {
         repeated string include = 2;
         repeated string exclude = 3;
     }
+
+    message HealthLevels {
+        repeated string include = 1;
+        repeated string exclude = 2;
+    }
+
+    /* Filter result on specific properties encoded in map-value pairs. */
+    message Properties {
+        oneof selection {
+            MapFilter properties = 1;
+            /* When set to true, match only empty property-sets. */
+            bool include_only_empty = 2;
+        }
+    }
 }
 
+/* Some properties are stored as a name-value pair (e.g. bluetooth: 4.0, bluetooth: BLE).
+ * This filter allows selecting a range of values for a specific name.
+ * One could imagine wanting to include "all devices with bluetooth 4.0 or 4.1".
+ *
+ * To select for multiple versions of a property,
+ * add the name of the property as a map-key and add a repeated list of versions as the map-value.
+ *
+ * For example:
+ * - include { 'bluetooth' -> [ ] }
+ *     returns all items that have any version of bluetooth,
+ * - include { 'bluetooth' -> [ '4.0', '5.0' ] }
+ *     will only return items that have bluetooth version 4.0 _or_ 5.0 (inclusive or),
+ * - include { 'bluetooth' -> [ '' ] }
+ *     would only select bluetooth peripherals that don't have any version set,
+ * - include { 'bluetooth' -> [ ], 'LoRaWAN' -> [ ] }
+ *     will only select items that have both bluetooth (any version) _and_ LoRaWAN (any version),
+ * - include { 'bluetooth' -> [ ] }, exclude { 'bluetooth' -> [ ] }
+ *     will return an empty list since exclude will take precedence, and
+ * - include { 'bluetooth' -> [ ] }, exclude { 'bluetooth' -> [ '3.0' ] }
+ *     returns only items that have bluetooth, but not version 3.0.
+ */
+message MapFilter {
+
+    /* Technical solution to make map<k, v> into a map<k, repeated v>,
+     * which is not possible in protobuf without trickery. */
+    message OneOfValues {
+        repeated string value = 1;
+    }
+
+    /* Filter to only include items with all of the given set of properties. */
+    map<string, OneOfValues> include_and = 1;
+
+    /* Filter to exclude items with any of the given set of properties.*/
+    map<string, OneOfValues> exclude = 2;
+}
+
+
 /* Health is an indicator for issues. It is used for publishers to give a quick indication of issues.
  */
 enum Health {

device.proto

@@ -0,0 +1,148 @@
+syntax = "proto3";
+
+package hiber.device;
+
+import "google/protobuf/struct.proto";
+
+import "base.proto";
+import "health.proto";
+import "modem.proto";
+import "tag.proto";
+
+option java_multiple_files = false;
+option java_package = "global.hiber.api.grpc.device";
+option java_outer_classname = "DeviceApi";
+option go_package = "hiber";
+
+/* Information about a device.
+ * A device is anything in the Hiber network that can send data to our systems.
+ * They have a unique device number in our system, used to identify them.
+ */
+message Device {
+    /* An 8-character hexadecimal string, formatted for human readability. System ignores spaces. */
+    string number = 1;
+    /* The organization that owns this device */
+    string organization = 2;
+
+    /* A descriptor given to the device, defaults to it's number. */
+    string name = 3;
+
+    hiber.Location location = 4;
+
+    /* The amount of time since the last message from this modem was received on the server. */
+    optional hiber.Duration inactivity = 5;
+
+    /* Health level based on the modem alarm and some always-present alarms. */
+    health.HealthLevel health_level = 6;
+
+    /* The current lifecycle the modem is in. */
+    hiber.modem.Modem.Lifecycle lifecycle = 7;
+
+    // additional information
+    map<string, string> peripherals = 8;
+
+    /* Notes field that can be used to add additional information to a modem. */
+    string notes = 9;
+
+    /* Secure notes field that can be used to add additional information to a modem, with limited accessibility. */
+    optional string secure_notes = 10;
+
+    repeated hiber.tag.Tag tags = 11;
+
+    /* Optional information about what other devices this devices is linked to.*/
+    optional Links link = 12;
+
+    /* Modem metadata, typically extracted from messages. */
+    google.protobuf.Struct metadata = 13;
+
+    /* The timezone configured for the modem. */
+    optional string time_zone = 14;
+
+    /* The transmission interval for this modem, if configured. */
+    optional hiber.Duration transmission_interval = 15;
+
+    /* Collection of data about the devices it is connected to. */
+    message Links {
+        /* Other identifiers for this devices. Could include data like its MAC-address or otherwise unique identifier. */
+        repeated string identifiers = 1;
+
+        /* The device directly downstream from this device.
+         * Usually a gateway of some sorts. This device sends its data directly to its parent.
+         * The parent will relay the data to our systems. */
+        optional string parent = 2;
+
+//        /* The devices that are directly upstream form this device if any.
+//         * The upstream devices use this device to relay messages for them. */
+//        TODO(WEB-6273) Implement list of children
+//        repeated string children = 3;
+    }
+}
+
+/* Selection object for devices.
+ * Filter devices by device number, tags, etc.
+ */
+message DeviceSelection {
+    string free_text_search = 1;
+
+    Filter.Modems modems = 2;
+    Filter.ModemIdentifiers identifiers = 3;
+    Filter.HealthLevels health_level = 4;
+    ModemFilter.Lifecycles lifecycles = 5;
+    Filter.Modems with_parents = 6;
+    Filter.Properties peripherals = 7;
+
+    hiber.tag.TagSelection filter_by_tags = 8;
+
+    TimeRange with_last_message_in = 9;
+}
+
+/* Sorting options for the results. */
+enum Sort {
+    /* Sort alphabetically on the name of the device.
+    * De default name of the device is its HEX number, in ascending order. */
+    DEVICE_NAME_ASC = 0;
+    /* Sort alphabetically on the name of the device.
+     * De default name of the device is its HEX number, in descending order. */
+    DEVICE_NAME_DESC = 1;
+
+    /* Sort numerically on the number of the device, in ascending order. */
+    DEVICE_NUMBER_ASC = 2;
+    /* Sort numerically on the number of the device, in descending order. */
+    DEVICE_NUMBER_DESC = 3;
+
+    /* Sort devices on most recent activity first (e.g. newest message received). */
+    ACTIVITY = 4;
+    /* Sort devices on least recent activity first (e.g. longest no message received). */
+    INACTIVITY = 5;
+
+    /* Sort device on its lifecycle state. */
+    LIFECYCLE_ASC = 6;
+    /* Sort device on its lifecycle state in reverse order. */
+    LIFECYCLE_DESC = 7;
+    /* Sort device on lifecycle name, alphabetically. */
+    LIFECYCLE_ALPHABETICAL_ASC = 8;
+    /* Sort device on lifecycle name, alphabetically in reverse order. */
+    LIFECYCLE_ALPHABETICAL_DESC = 9;
+
+    /* Sort alphabetically on the name of the organization that owns the device, in ascending order. */
+    ORGANIZATION_ASC = 10;
+    /* Sort alphabetically on the name of the organization that owns the device, in descending order. */
+    ORGANIZATION_DESC = 11;
+
+    /* Health sorted from least to most severe (i.e. OK, WARNING, ERROR). */
+    HEALTH_ASC = 12;
+    /* Health sorted from most to least severe (i.e. ERROR, WARNING, OK). */
+    HEALTH_DESC = 13;
+    /* Health sorted alphabetically by health level name. */
+    HEALTH_ALPHABETICAL_ASC = 14;
+    /* Health sorted alphabetically by health level name, descending order. */
+    HEALTH_ALPHABETICAL_DESC = 15;
+}
+
+
+message ModemFilter {
+    message Lifecycles {
+        repeated hiber.modem.Modem.Lifecycle include = 1;
+        repeated hiber.modem.Modem.Lifecycle exclude = 2;
+    }
+}

device_service.proto

@@ -0,0 +1,142 @@
+/* Device management.
+ *
+ * Devices are anything capable of sending messages to the system.
+ * They have a unique device (previously modem) number, used to identify them.
+ */
+syntax = "proto3";
+
+package hiber.device;
+
+import "base.proto";
+import "device.proto";
+import "modem.proto";
+
+option java_multiple_files = false;
+option java_package = "global.hiber.api.grpc.device";
+option java_outer_classname = "DeviceServiceApi";
+option go_package = "hiber";
+
+/* At the core of the Hiber system, devices are the network nodes that send information and user data.
+ * This service contains calls to list and manage devices.
+ */
+service DeviceService {
+    /* List the devices in your organization, and, optionally, its child organizations. */
+    rpc List (ListDevice.Request) returns (ListDevice.Response);
+
+    /* Update a device. */
+    rpc Update(UpdateDevice.Request) returns (UpdateDevice.Response);
+}
+
+message UpdateDevice {
+
+    hiber.device.DeviceSelection selection = 1;
+
+    /* Change the name for the selected devices.
+     * To prevent confusion, the selection can only effectively target 1 device when changing the name.
+     * Unless you specifically set `allow_bulk_rename`.
+     * You'd be left with multiple devices with the same name (technically allowed),
+     * but probably something you don't want.
+     */
+    optional string name = 2;
+    /* Allow a rename that results in multiple devices with the same name.
+     * Could be useful if you have different sites with devices that fulfill
+     * a similar job but are located at different sites.
+     * It is advised to make sure those devices have different tags/groups.
+     */
+    bool allow_bulk_rename = 3;
+
+    /* Change the notes for the selected devices. */
+    optional string notes = 4;
+    /* Allow changing notes in bulk if the notes are different.
+     * Must set this explicitly to prevent accidental loss of notes.
+     */
+    bool allow_bulk_notes = 5;
+
+    /* Change the notes for the selected devices. */
+    optional string secure_notes = 6;
+    /* Allow changing notes in bulk if the notes are different.
+     * Must set this explicitly to prevent accidental loss of notes.
+     */
+    bool allow_bulk_secure_notes = 7;
+
+    /* Updates the devices peripherals, by adding, removing or replacing. */
+    optional UpdatePeripherals peripherals = 8;
+    /* Set the timezone the device is located in. */
+    optional string time_zone = 9;
+    /* Update the lifecycle for this device. */
+    optional hiber.modem.Modem.Lifecycle lifecycle = 10;
+    /* Sets the interval this devices is transmitting on.
+     * Mainly useful for devices that have a regular interval for transmissions. */
+    optional Duration transmission_interval = 11;
+
+    /* When updating peripherals, you can choose to add and delete peripherals,
+     * or to do a wholesome replace of all peripherals.
+     */
+    message UpdatePeripherals {
+        message Partial {
+            /* Removes peripherals by name in this list. Leaves other peripherals untouched. */
+            repeated string remove_peripherals = 1;
+            /* Adds peripherals by name-value from this mapping. Leaves other peripherals untouched. */
+            map<string, string> add_peripherals = 2;
+        }
+        message Replace {
+            /* Replaces the entire set of peripherals. All peripherals not named in this map will be removed. */
+            map<string, string> replace_peripherals = 1;
+        }
+        oneof replace {
+            Partial partial_update = 1;
+            Replace full_replace = 2;
+        }
+    }
+
+    message Request {
+        /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
+        string organization = 1;
+        /* Multiple different updates can be made.
+         * Every update contains a device selection (historically modem selection)
+         * which targets the devices that should be updated.
+         */
+        repeated UpdateDevice devices = 2;
+    }
+    message Response {
+        repeated Device devices = 1;
+        Request request = 2;
+    }
+}
+
+message ListDevice {
+    message Request {
+        /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
+        string organization = 1;
+
+        /* Select which devices to return. Uses ModemSelection, which is the historical name for device. */
+        hiber.device.DeviceSelection selection = 2;
+
+        /* Paginate through results. */
+        Pagination pagination = 3;
+
+        /* Sort the devices with the given sort options. */
+        repeated hiber.device.Sort sort_by = 4;
+
+        /* Filter devices by location. */
+        LocationSelection location_selection = 5;
+
+        /* Set this to true to populate the parents field in the response.
+         * This will be populated with missing parents (e.g. gateways) for the the devices on this page.
+         * Any parent that is on the current page is not included in this list to avoid duplicate data.
+         */
+        bool include_missing_parents = 6;
+    }
+    message Response {
+        repeated Device devices = 1;
+        ListDevice.Request request = 2;
+        Pagination.Result pagination = 3;
+        repeated Sort sorted_by = 4;
+
+        /* This will be populated with missing parents (e.g. gateways) for the the devices on this page.
+         * Any parent that is on the current page is not included in this list to avoid duplicate data.
+         * Only set when include_missing_parents is true in the request.
+         */
+        repeated Device parents = 5;
+    }
+}