modem.proto

/* Modem and message management.
 *
 * Modems are anything capable of sending messages to the system. They have a unique modem number,
 * used to identify them.
 */
syntax = "proto3";

package hiber.modem;

import "google/protobuf/struct.proto";

import "base.proto";
import "health.proto";
import "organization.proto";
import "tag.proto";
import "value.proto";

option java_multiple_files = false;
option java_package = "global.hiber.api.grpc.modem";
option java_outer_classname = "ModemApi";
option go_package = ".;hiber";

/* The core of the Hiber system, modems are the network nodes that send information and user data.
 * This service contains calls to list and manage them, as well as list their messages.
 */
service ModemService {
    /* Get a single modem. */
    rpc Get (GetModemRequest) returns (Modem);

    /* Create new modem(s). This is only available if your organization can create modems. */
    rpc Create (CreateModem.Request) returns (CreateModem.Response);

    /* List the modems in your organization, and, optionally, its child organizations. */
    rpc List (ListModemsRequest) returns (ListModemsRequest.Response);

    /* List the modems in your organization, and, optionally, its child organizations, grouped by dependency.
     * For example, a modem that sends it messages through a gateway (like Hilo) would be grouped under that gateway.
     */
    rpc Grouped (ListModemsGrouped.Request) returns (ListModemsGrouped.Response);

    /* List messages for the selected modems. */
    rpc Messages (ListModemMessagesRequest) returns (ListModemMessagesRequest.Response){
        option deprecated = true;
    };

    /* Add, remove and create new tags for the selected modems. */
    rpc UpdateTags (UpdateModemTagsRequest) returns (UpdateModemTagsRequest.Response);

    rpc TagCount (TagCount.Request) returns (TagCount.Response);
}

/* Modem data, including location and last message (if available).
 * Location, last message and firmware version can be updated by messages, the rest is typically either set
 * when the modem is registered into the system or when a subscription is authorized.
 */
message Modem {
    /* An 8-character hexadecimal string */
    string number = 1;
    string organization = 2;
    /* An optional descriptor given to the modem */
    string name = 3;

    Location location = 4;

    uint64 last_message_id = 16;

    /* Time the server has received the last message. */
    Timestamp last_message_received_at = 5;

    /* Time the modem has sent the last message. */
    Timestamp last_message_sent_at = 14;

    /* The body of the last message. */
    BytesOrHex last_message_body = 15;

    /* The amount of time since the last message from this modem was received on the server. */
    Duration inactivity = 30;

    /* Health level based on the modem alarm and some always-present alarms. */
    health.HealthLevel health_level = 28;

    Lifecycle lifecycle = 12;

    // additional information
    TechnicalData technical = 7;
    Peripherals peripherals = 11;

    /* Notes field that can be used to add additional information to a modem. */
    string notes = 17;

    /* Secure notes field that can be used to add additional information to a modem, with limited accessibility. */
    string secure_notes = 18;

    repeated hiber.tag.Tag tags = 10;

    /* [DEPRECATED] Whether the modem is a gateway, it has been configured as a gateway and has connected devices.
     * Use `type` instead.
     */
    bool is_gateway = 20 [deprecated = true];

    /* [DEPRECATED] Whether the modem is connected to a modem configured as a gateway.
     * Use `type` instead.
     */
    bool is_device_connected_to_gateway = 21 [deprecated = true];

    /* [DEPRECATED] The modem number that this modem is connected to, if any.
     * Use `connected_device_info.connected_to_gateway` instead.
     */
    string connected_to_gateway = 22 [deprecated = true];

    /* [DEPRECATED] External device ids, if any.
     * Use `connected_device_info.external_device_ids` instead.
     */
    repeated string external_device_ids = 23 [deprecated = true];

    /* The type of modem.
     * Used mainly to differentiate in the UI or to sort on.
     */
    Modem.Type type = 25;

    /* Additional information when this modem is a gateway. */
    GatewayInfo gateway_info = 26;

    /* Additional information when this modem is a connected device. */
    ConnectedDeviceInfo connected_device_info = 27;

    /* Modem metadata, typically extracted from messages. */
    google.protobuf.Struct metadata = 31;

    /* The timezone configured for the modem. */
    string time_zone = 32;

    /* The transmission interval for this modem, if configured. */
    Duration transmission_interval = 33;
    /* The expected transmission rate for this modem. */
    optional hiber.value.Value.Numeric.Rate expected_transmission_rate = 34;

    /* The numeric value types that this device produces.
     * The device may produce other values (like battery level), but these are the primary value types.
     */
    repeated value.Value.Numeric.Type numeric_value_types = 35;

    /* Additional information when this modem is a gateway. */
    message GatewayInfo {
        int32 number_of_connected_devices = 1;

        /* Device type for this gateway. */
        string device_type = 2;

        /* Brand for this gateway. */
        string gateway_brand = 3;
    }

    /* Additional information when this modem is a connected device. */
    message ConnectedDeviceInfo {
        /* The gateways that this modem is connected to.
         * This field reflects the gateway that processed the last message for this modem.
         * If the modem is connected to multiple gateways, the last used gateway is tracked here.
         */
        string connected_to_gateway = 1;

        /* External device ids for this modem. */
        repeated string external_device_ids = 2;

        /* Device type for this modem. */
        string device_type = 3;

        /* Brand for this modem's sensor. */
        string sensor_brand = 4;
    }

    message TechnicalData {
        string hardware_production_batch = 6;
        string manufacturer = 7;
        reserved 1, 2, 3, 4, 5;
    }

    /* Peripherals attached to the modem, including antenna, whether it has a gps antenna and an
     * open field for peripherals like battery, sensors, etc.
     */
    message Peripherals {
        bool gps = 2;
        map<string, string> peripherals = 3;
        string custom_antenna = 4;

        reserved 1;
    }

    enum Lifecycle {
        /* Device is being tested by Hiber.
         * Devices in this state are not visible to customers.
         */
        ACCEPTANCE_TESTING = 0;

        /* Device has passed Acceptance Testing and is ready be installed.
         * When it sends it first message, it will automatically go to INSTALLED.
         * Devices in this state are not visible to customers.
         */
        READY_TO_INSTALL = 8;

        /* Device is active and sending messages. */
        INSTALLED = 1;

        /* Device is paused and not sending messages.
         * This should be of a temporary nature (e.g. a change to the installation is being made).
         * On its next message, it will automatically go back to INSTALLED.
         * Offline alarm checks will not be triggered for devices in this lifecycle.
         */
        PAUSED = 6;

        /* Device is disabled and not sending messages.
         * This is a more permanent version of PAUSED.
         * Devices in this state are not visible to customers.
         */
        DISABLED = 5;

        /* Device is (going to be) removed from installation and will not return to installed status again.
         * Devices in this state are not visible to customers.
         */
        DECOMMISSIONED = 4;

        /* Device is defective and should not be used anymore.
         * Devices in this state are typically RMA-ed and (should be) transferred to the RMA organization.
         * Devices in this state are not visible to customers.
         */
        DEFECTIVE = 7;

        /* Spare device sent to customer in case it is needed. */
        SPARE = 9;
    }

    /* The effective type of this modem.
     * Type can depend on the hardware itself as well as network topology.
     */
    enum Type {
        /* A device of which the specific type is not known */
        OTHER = 0;

        /* A device that is not currently connected to a gateway. */
        DISCONNECTED_SENSOR = 1;

        /* A device that can receive messages from sensors in the field and relay them (directly) to the satellite.
         * Typically a LoRaWAN hub.
         * Note that gateways also send messages themselves (e.g. a daily heartbeat).
         */
        GATEWAY = 2;

        /* A sensor that can (only) send data to a gateway. Typically using a LoRaWAN connection. */
        SENSOR = 3;
    }

    reserved 6, 9, 13;
}

/* Selection object for modems.
 * Filter modems by modem id, (child)organization, tags, activation status and time, service type and last message time.
 */
message ModemSelection {
    message Transfers {
        repeated string transfers_identifiers = 1;
        reserved 2, 3;
    }
    /* Filter to (de)select modems based on their peripherals.
     *
     * For example:
     * - include { 'bluetooth' -> [ ] }
     *     returns all modems that have any version of bluetooth,
     * - include { 'bluetooth' -> [ '4.0', '5.0' ] }
     *     will only return modems that have bluetooth version 4.0 _or_ 5.0,
     * - include { 'bluetooth' -> [ '' ] }
     *     would only select bluetooth peripherals that don't have any version set,
     * - include { 'bluetooth' -> [ ], 'LoRaWAN' -> [ ] }
     *     will only select modems 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 modems that have bluetooth, but not version 3.0.
     * - exclude { 'bluetooth' -> [ ] }
     *     returns only modems that do not have any version of bluetooth,
     * - exclude { 'bluetooth' -> [ '4.0', '5.0' ] }
     *     returns modems that might have bluetooth as long as it's not versions 4.0 or 5.0,
     * - exclude { 'bluetooth' -> [ '' ] }
     *     returns modems that might have bluetooth as long as it's version is set to a specific value,
     * - exclude { 'bluetooth' -> [ ], 'LoRaWAN' -> [ ] }
     *     returns modems that don't have bluetooth and/or LoRaWAN.
     * - include { 'bluetooth' -> [ ] }, exclude { bluetooth' -> [ ] }
     *     will return an empty list, since exclusion takes precedence, and
     * - include { 'bluetooth' -> [ ] }, exclude { bluetooth' -> [ '3.0' ] }
     *     returns only modems that have bluetooth, but not version 3.0
     */
    message Peripherals {
        message OneOfValues {
            repeated string value = 1;
        }

        /* Filter to only include modems with all of the given set of peripherals.
         * Peripherals are stored as a name-value pair (e.g. bluetooth, 4.0 / bluetooth, BLE).
         * To select for multiple versions of a peripheral,
         * add the name of the peripheral as a map-key and add a repeated list of versions as the map-value.
         */
        map<string, OneOfValues> include_and = 1;

        /* Filter to exclude modems with any of the given set of peripherals.
         * Peripherals are stored as a name-value pair (e.g. bluetooth, 4.0 / bluetooth, BLE).
         * To select for multiple versions of a peripheral,
         * add the name of the peripheral as a map-key and add a repeated list of versions as the map-value.
         */
        map<string, OneOfValues> exclude = 2;
    }

    optional Filter.Modems modems = 1;
    optional string free_text_search = 8;

    /* Use lifecycle filter instead. */
    optional bool only_active = 4 [deprecated = true];
    optional TimeRange activated_in = 5 [deprecated = true];
    optional TimeRange with_last_message_in = 7;

    /* Filter modems by health level. */
    repeated string health_levels = 18;

    /* Filter modems by lifecycle(s).
     * Defaults to nominal lifecycles, excluding disabled or decommissioned modems.
     */
    repeated Modem.Lifecycle lifecycles = 10;
    optional Transfers transfers = 11;

    /* Only include modems that have a type listed in types.
     * In other words, when providing multiple types, this is an "OR" relationship.
     */
    repeated Modem.Type include_types = 16;

    /* Exclude modems that have a type listed in types. */
    repeated Modem.Type exclude_types = 19;

    optional Filter.DeviceTypes device_types = 22;
    optional Filter.SensorBrands sensorBrands = 23;
    optional Filter.ModemIdentifiers identifiers = 24;

    /* [DEPRECATED] Only list devices that are a gateway.
     * Replaced by `types`.
     * If you only want to have gateways in the result, create a selection with only `Modem.Type.GATEWAY` for `types`.
     */
    optional bool only_gateways = 12 [deprecated = true];

    /* [DEPRECATED] Only list devices that are a connected devices. Typically these are LoRaWAN sensors.
     * Replaced by `types`.
     * If you only want to have connected devices in the result,
     * create a selection with only `Modem.Type.CONNECTED_DEVICE` for `types`.
     */
    optional bool only_has_external_device_ids = 13 [deprecated = true];

    optional Filter.Modems connected_to_gateways = 14;
    repeated string external_device_ids = 15 [deprecated = true];

    optional hiber.tag.TagSelection filter_by_tags = 2;

    /* Filter modem result on specific peripherals. */
    oneof peripheral_selection {
        Peripherals peripherals = 20;
        /* When set to true, only modems that do not have any peripheral will be included in the result. */
        bool only_without_peripheral = 21;
    }

    /* Only select modems that are connected to a gateway (connected devices). */
    optional bool only_connected_to_gateway = 25;

    /* Only select modems that are not connected to a gateway (i.e. gateways). */
    optional bool not_connected_to_gateway = 26;

    reserved 3, 6, 9, 17;
}

/* Decrypted modem message. Messages are received encrypted and decrypted asynchronously, which adds the location
 * data and message body. (Your message body is, of course, still encrypted if you've encrypted it yourself)
 */
message ModemMessage {
    option deprecated = true; // moved to modem_message.proto as Message

    enum Source {
        /* A real message from a modem or gateway, sent over Hiberband to the server. */
        HIBERBAND = 0;
        /* A real message from a modem or gateway, sent directly to the API using a persistent connection. */
        DIRECT_TO_API = 1;
        /* A test message sent to the testing API. */
        TEST = 2;
        /* A simulated message, generated by the server. */
        SIMULATION = 3;
    }

    /* Parsed message body.
     * If any parsers are configured for the modem, they are applied to the message.
     * The result is stored either as a json object or an error string.
     */
    message ParsedBody {
        /* Id of the parser that was used, if the parser and modem are owned by the same organization.
         * [DEPRECATED] Deprecated in favour of the identifier, which is globally unique.
         */
        int32 parser_id = 1 [deprecated = true];

        /* Globally unique identifier of the parser that was used. */
        string parser_identifier = 6;

        /* Name of the parser that was used. */
        string parser_name = 2;

        oneof parsed {
            /* Error while parsing the message body. */
            string error = 4;

            /* Result of parsing the body with this parser. */
            google.protobuf.Struct result = 5;
        }

        reserved 3;
    }

    /* Unique message identifier. */
    uint64 message_id = 7;

    /* Modem number of the modem that sent the message. */
    string modem_number = 1;

    /* The name of the modem that sent the message. */
    string modem_name = 17;

    /* The device identifier for the modem that sent the message (e.g. a MAC address). */
    string modem_identifier = 18;

    /* Time the message was sent from the modem. */
    Timestamp sent_at = 3;

    /* Time the message was received on the server. */
    Timestamp received_at = 6;

    /* Modem location when the message was sent. */
    Location location = 4;

    /* Message body. */
    bytes body = 5;

    /* Message body convenience object. */
    BytesOrHex body_bytes = 8;

    /* A list of applied body parsers and their results. */
    repeated ParsedBody body_parsed = 11;

    /* Convenience flag marking whether the body was parsed successfully by at least one parser. */
    bool body_parsed_successfully = 12;

    /* Message source(s) for this message (i.e. it was received through the satellite or directly to the server). */
    repeated Source sources = 10;

    /* True if the the TEST source is in the sources. */
    bool is_test = 9;

    /* Whether this message contains other messages. */
    bool is_gateway_message = 13;

    /* The gateway message this message was sent in. */
    uint64 via_gateway_message = 14;

    /* Message metadata, defined by the modem or gateway. */
    google.protobuf.Struct metadata = 15;

    /* Flattened results of all successful body parsers.
     * This is a convenience to access the fields from body_parsed, but if any fields are present in
     * multiple body_parsed results, it is not defined which field will be used in this Struct.
     * This may change in the future.
     */
    google.protobuf.Struct body_fields = 16;

    /* The tags of the modem that sent the message. */
    repeated tag.Tag tags = 19;

    /* The names of the tags of the modem that sent the message. */
    repeated string tag_names = 20;

    reserved 2;
}

/* Selection object for modem messages.
 * Filter messages by modem id, (child)organization, and time sent (note that this is not the time the message was received)
 */
message ModemMessageSelection {
    option deprecated = true; // moved to modem_message.proto as MessageSelection

    message ModemMessageSourceFilter {
        repeated ModemMessage.Source include = 1;
        repeated ModemMessage.Source exclude = 2;
    }

    /* Define the modems to return messages for, i.e. include = [AAAA AAAA, BBBB BBBB].
     * Deprecated in favor of using the ModemSelection.
     */
    Filter.Modems modems = 1 [deprecated = true];

    /* Select the modems to return messages for. */
    ModemSelection modem_selection = 5;

    /* Filter message by time range. This field is required, to limit the amount of messages. */
    TimeRange time_range = 3;

    /* Filter messages by the given source filter.
     * For example, to exclude test and simulated messages, use exclude = [TEST, SIMULATED]
     * or to only return Hiberband messages, use include = [HIBERBAND].
     * Note that if a message has sources [HIBERBAND, DIRECT_TO_API], including [HIBERBAND] will include the message,
     * and excluding [HIBERBAND] will filter out the message, even though it also has DIRECT_TO_API.
     */
    ModemMessageSourceFilter filter_by_sources = 4;

    reserved 2;
}

message GetModemRequest {
    /* This replaces the child_organizations option, allowing search in all accessible organizations. */
    oneof where {
        /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
        string organization = 1;

        /* If set, look up the modem in multiple organizations, instead of in the given or default organization.
         * This can be used to find a modem if you do not know in which organization it is.
         * Since this is a selection object, an empty selection searches in all accessible organizations, but
         * the organizations can be limited using the fields in the OrganizationSelection.
         */
        organization.OrganizationSelection in_organizations = 3;
    }

    /* The modem to get. */
    string modem_number = 2;

    /* Look for the modem in child organizations.
     * DEPRECATED: use the in_organizations flag instead.
     */
    optional Filter.ChildOrganizations child_organizations = 4 [deprecated = true];
}

message ListModemsRequest {
    message Response {
        repeated Modem modems = 1;
        ListModemsRequest request = 2;
        Pagination.Result pagination = 3;
        repeated Sort sorted_by = 4;

        /* This will be populated with missing group parents (i.e. gateways) for the the modems on this page.
         * Any group parent that is on the current page is not included in this list to avoid duplicate data.
         * Only set when include_missing_group_parents is true in the request.
         */
        repeated Modem group_parents = 5;
    }

    /* Sorting options for the results. */
    enum Sort {
        /* Sorts messages in descending time order. */
        LAST_MESSAGE_RECEIVED = 0;
        /* Sorts messages in ascending time order. */
        LAST_MESSAGE_RECEIVED_INVERTED = 1;

        /* Sort numerically on the number of the modem, in ascending order. */
        MODEM_NUMBER_ASC = 2;
        /* Sort numerically on the number of the modem, in descending order. */
        MODEM_NUMBER_DESC = 3;

        /* Sort modem on its Status. */
        STATUS_ASC = 4;
        /* Sort modem on its Status in reverse order. */
        STATUS_DESC = 5;
        /* Status sorted alphabetically by Status name. */
        STATUS_ASC_ALPHABETICAL = 14;
        /* Status sorted alphabetically by Status name, descending order. */
        STATUS_DESC_ALPHABETICAL = 15;

        /* Sort alphabetically on the name of the modem. De default name of the modem is its HEX number, in ascending order. */
        MODEM_NAME_ASC = 6;
        /* Sort alphabetically on the name of the modem. De default name of the modem is its HEX number, in descending order. */
        MODEM_NAME_DESC = 7;

        /* Sort alphabetically on the name of the organization that owns the modem, in ascending order. */
        ORGANIZATION_ASC = 8;
        /* Sort alphabetically on the name of the organization that owns the modem, in descending order. */
        ORGANIZATION_DESC = 9;

        /* Health sorted from least to most severe (i.e. OK, WARNING, ERROR). */
        HEALTH = 10;
        /* Health sorted from most to least severe (i.e. ERROR, WARNING, OK). */
        HEALTH_DESC = 11;
        /* Health sorted alphabetically by health level name. */
        HEALTH_ASC_ALPHABETICAL = 12;
        /* Health sorted alphabetically by health level name, descending order. */
        HEALTH_DESC_ALPHABETICAL = 13;

        /* Sort alphabetically on the brand of the sensor, in ascending order. */
        SENSOR_BRAND_ASC = 16;
        /* Sort alphabetically on the brand of the sensor, in descending order. */
        SENSOR_BRAND_DESC = 17;

        /* Sort alphabetically on the device type, in ascending order. */
        DEVICE_TYPE_ASC = 18;
        /* Sort alphabetically on the device type, in descending order. */
        DEVICE_TYPE_DESC = 19;

        /* Sort alphabetically on any tags of type 'well', in ascending order. */
        TAG_TYPE_WELL_ASC = 20;
        /* Sort alphabetically on any tags of type 'well', in descending order. */
        TAG_TYPE_WELL_DESC = 21;
        /* Sort alphabetically on any tags of type 'site', in ascending order. */
        TAG_TYPE_SITE_ASC = 22;
        /* Sort alphabetically on any tags of type 'site', in descending order. */
        TAG_TYPE_SITE_DESC = 23;
        /* Sort alphabetically on any tags of type 'production_area', in ascending order. */
        TAG_TYPE_PRODUCTION_AREA_ASC = 24;
        /* Sort alphabetically on any tags of type 'production_area', in descending order. */
        TAG_TYPE_PRODUCTION_AREA_DESC = 25;
    }

    /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
    optional string organization = 1;

    /* Select which modems to return. Optional, when omitted or empty everything is included. */
    optional ModemSelection selection = 2;

    /* Paginate through results. */
    optional Pagination pagination = 3;

    /* Sort the modem with the given sort options. */
    repeated Sort sort_by = 4 [packed = false];

    /* Include modems from the selected child organizations. */
    optional Filter.ChildOrganizations child_organizations = 8;

    /* Filter modems by location. */
    optional LocationSelection location_selection = 9;

    /* Set this to true to populate the group_parents field in the response.
     * This will be populated with missing group parents (i.e. gateways) for the the modems on this page.
     * Any group parent that is on the current page is not included in this list to avoid duplicate data.
     */
    optional bool include_missing_group_parents = 10;

    reserved 5 to 7;
}

/* Lists all modems the given criteria, grouped by gateway.
 * Pagination is applied to modems in a group, not to the groups themselves.
 */
message ListModemsGrouped {
    /* The usage of ListModemsRequest and ListModemsRequest.Response in the Response.Group was intentionally
     * chosen to simplify pagination withing a group, since the response contains the request
     * (which will be updated with the group it is in) and pagination to select the next page using the
     * list method.
     */
    message Request {
        /* The modems you want to display in the groups.
         * This is a ListModemsRequest that is used to fetch the modems for each group, with the added limitation
         * that the modems must be in the group.
         */
        ListModemsRequest group_content = 1;

        /* Select the parents for the groups to display.
         * Anything selected here that cannot have any connected modems (i.e. a direct modem) wil be omitted
         * unless allow_any_group_parent is set to true.
         * Only gateways will have connected devices, so unless allow_any_group_parent is true,
         * type is replaced with GATEWAY. This may change in the future if more grouping options are introduced.
         */
        ListModemsRequest groups = 2;

        /* Set to true to allow group request to return modems that can never be the parent of a group.
         * - If this flag is false, the modems for the groups are automatically filtered on being a parent of a group.
         *   Note that the group may still be empty, i.e. when a gateway has no connected devices.
         * - If this flag is true, the group parents can include modems which cannot be a parent and for which
         *   the group can only be empty.
         */
        optional bool allow_any_group_parent = 3;
    }

    /* The usage of ListModemsRequest and ListModemsRequest.Response in the Response.Group was intentionally
     * chosen to simplify pagination withing a group, since the response contains the request
     * (which will be updated with the group it is in) and pagination to select the next page using the
     * list method.
     */
    message Response {
        /* The groups, based on a parent (typically a gateway unless allow_any_group_parent was set).
         * This is a ListModemsRequest.Response, with the selection updated with its parent and includes
         * the group parent in the group_parents field.
         */
        repeated ListModemsRequest.Response groups = 1;
        Request request = 2;
        Pagination.Result pagination = 3;
        repeated ListModemsRequest.Sort sorted_by = 4;
        Total total = 5;

        message Total {
            uint32 groups = 1;
            uint32 content = 2;
            uint32 all = 3;
        }
    }
}

message ListModemMessagesRequest {
    option deprecated = true; // moved to modem_message.proto as ListMessages

    message Response {
        repeated ModemMessage messages = 1;
        ListModemMessagesRequest request = 2;
        Pagination.Result pagination = 3;
    }

    /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
    string organization = 1;
    ModemMessageSelection selection = 2;
    Pagination pagination = 3;

    reserved 4;
}

/* Create modems for your organization.
 * This call is not available to all organizations, and is typically used to create modems for testing or
 * when you want to connect a device to the API using just the API calls in the TestingService.
 */
message CreateModem {
    message Request {
        /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
        optional string organization = 1;

        /* The amount of modems to create. */
        uint32 amount = 2;

        /* The name(s) to give the new modem(s).
         * Must not contain more values than the amount of modems to create.
         */
        repeated string names = 3;

        /* The external device identifiers for the new modems.
         * Must not contain more values than the amount of modems to create.
         * The order of this list matches the order of the name, values in the same index are applied to the same modem.
         */
        repeated string external_device_identifiers = 4;

        /* The status for the new modems. */
        optional Modem.Lifecycle lifecycle = 5;

        /* The technical data, such as manufacturer and hardware information for the new modems. */
        optional Modem.TechnicalData technical = 6;

        /* The peripherals for the new modems. */
        map<string, string> peripherals = 7;

        /* Notes for all new modems. */
        optional string notes = 8;

        /* The location for the new modems, either set or randomly within an area. */
        oneof initial_location {
            Location location = 9;
            Area random_location_in_area = 10;
        }

        /* The tags to set to the new modems, either existing or created by this call. */
        optional hiber.tag.UpdateTagsForItem tags = 11;

        /* Whether to return the full Modem in addition to the modem number and verification code. */
        optional bool include_modems_in_response = 12;

        /* Whether to return the verification code for the modem. */
        optional bool include_verification_code = 13;
    }

    message Response {
        message CreatedModem {
            /* The modem number that was created. */
            string modem_number = 1;

            /* The verification code for this modem number, used to, for example, claim modems.
             * Only available when include_verification_code was set to true.
             */
            string verification_code = 2;

            /* Only available when include_modems_in_response was set to true. */
            Modem modem = 3;
        }

        repeated CreatedModem modems = 1;
        Request request = 2;
    }
}

message UpdateModemTagsRequest {
    message Response {
        repeated Modem modems = 1;
        UpdateModemTagsRequest request = 2;
        Pagination.Result pagination = 3;
    }

    /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
    optional string organization = 1;
    hiber.tag.UpdateTagsForItem update = 3;
    ModemSelection selection = 5;
    optional Pagination pagination = 6;
}

message TagCount {
    hiber.tag.Tag tag = 1;
    uint32 modems = 2;

    message Request {
        /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
        optional string organization = 1;

        /* Select the modems to count. Optional, when omitted or empty everything is included. */
        optional ModemSelection selection = 2;

        /* Select the tags to list. Optional, when omitted or empty everything is included. */
        optional tag.TagSelection tag_selection = 3;
    }

    message Response {
        repeated TagCount tags = 1;
        Request request = 2;
    }
}