From 30bf6b43bd76900f097e2965d39932a4dc9dbe08 Mon Sep 17 00:00:00 2001 From: Matthias Hogerheijde Date: Tue, 6 Sep 2022 08:35:21 +0200 Subject: [PATCH] 0.119.0 --- CHANGELOG.md | 34 + base.proto | 6 + docs/html/assignment.html | 42 + docs/html/easypulse.html | 62 + docs/html/event.html | 42 + docs/html/field_service.html | 191 +- docs/html/map.html | 42 + docs/html/modem.html | 42 + docs/html/modem_alarm.html | 42 + docs/html/modem_message_body_parser.html | 42 + docs/html/named_location.html | 42 + docs/html/unit_preferences_service.html | 7 + docs/html/value_service.html | 7925 ++++++++++++++++++++++ docs/html/values.html | 42 + docs/html/webhook.html | 42 + docs/md/assignment.md | 11 + docs/md/easypulse.md | 14 + docs/md/event.md | 11 + docs/md/field_service.md | 53 +- docs/md/map.md | 11 + docs/md/modem.md | 11 + docs/md/modem_alarm.md | 11 + docs/md/modem_message_body_parser.md | 11 + docs/md/named_location.md | 11 + docs/md/unit_preferences_service.md | 1 + docs/md/value_service.md | 1404 ++++ docs/md/values.md | 11 + docs/md/webhook.md | 11 + easypulse.proto | 11 + field.proto | 3 + field_service.proto | 48 +- message.proto | 33 +- sso.proto | 13 + value_service.proto | 250 + 34 files changed, 10525 insertions(+), 7 deletions(-) create mode 100644 docs/html/value_service.html create mode 100644 docs/md/value_service.md create mode 100644 value_service.proto diff --git a/CHANGELOG.md b/CHANGELOG.md index d61415b..87120cc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,40 @@ #### Upcoming Changes +### 0.119 (2022-09-05) + +##### EasypulseService + +- Added `MINIMUM` and `MAXIMUM` aggregation to `Easypulse.History.Request.Aggregation`. + +##### FieldService + +- Added `ForModem` call (with `ListFieldsForModem`) to list the fields for a selection of modems. + - This is an improved version to `MessageService.AvailableBodyFields` + - Added `apply_unit_preferences` to choose whether to apply the unit preferences. + - Added `field_selection` to filter the fields. +- Added `optional` to `Field` to indicate the system should not consider the parser result invalid + if the field is not in it. + - Added `optional` to `UpdateFieldRequest`. + +##### MessageService + +- Added `MINIMUM` and `MAXIMUM` aggregation to `MessageBodyFieldHistory.Request.Aggregation`. +- Deprecated `History` call in favor of the new `ValueService`. +- Deprecated `AvailableBodyFields` call in favor of the new `FieldService.ForModem` call. + +##### SingleSignOnService + +- Added `current_session_id` to `DundasSSO.Request` to submit your current session id. + If it is still valid, no new session is created and the given session id is returned. +- Added `session_id_subdomain` to `DundasSSO.Response` with the subdomain to write the session id to, for convenience. + +##### ValueService + +- Introducing the `ValueService` to fetch time series data from our system. + - Use `List` to list absolute values for a given period of time. + - Use `Aggregated` to aggregate values over a given period of time, optionally partitioned (i.e. average per day). + ### 0.118 (2022-08-22) ### 0.117 (2022-08-15) diff --git a/base.proto b/base.proto index 632c282..33defd2 100644 --- a/base.proto +++ b/base.proto @@ -392,6 +392,12 @@ message Filter { repeated UserPermission include = 2; repeated UserPermission exclude = 3; } + + message FieldEnumValues { + string field = 1; + repeated string include = 2; + repeated string exclude = 3; + } } /* Health is an indicator for issues. It is used for publishers to give a quick indication of issues. diff --git a/docs/html/assignment.html b/docs/html/assignment.html index 329a3de..4b0566a 100644 --- a/docs/html/assignment.html +++ b/docs/html/assignment.html @@ -1089,6 +1089,10 @@

Table of Contents

MFilter.Events.Update +
  • + MFilter.FieldEnumValues +
    • +
  • MFilter.Modems
    • @@ -10152,6 +10156,44 @@

    Filter.Events.Update

    +

    Filter.FieldEnumValues

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    fieldstring

    includestringrepeated

    excludestringrepeated

    + + + + +

    Filter.Modems

    diff --git a/docs/html/easypulse.html b/docs/html/easypulse.html index 62d64f3..6632f69 100644 --- a/docs/html/easypulse.html +++ b/docs/html/easypulse.html @@ -531,6 +531,10 @@

    Table of Contents

    MFilter.Events.Update +
  • + MFilter.FieldEnumValues +
    • +
  • MFilter.Modems
    • @@ -1970,6 +1974,14 @@

    Easypulse.TargetVal

    Sort the returned assets using the given option. By default, Assets are sorted by name.

    + + apply_unit_preferences + bool + +

    Whether to apply the unit preferences to the fields. +This will convert any fields into your preferred unit, for convenience.

    + + @@ -2434,6 +2446,18 @@

    Easypulse.History

    Just take the last value (in a group).

    + + MINIMUM + 4 +

    Take the lowest value (in a group).

    + + + + MAXIMUM + 5 +

    Take the highest value (in a group).

    + + @@ -4130,6 +4154,44 @@

    Filter.Events.Update

    +

    Filter.FieldEnumValues

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    fieldstring

    includestringrepeated

    excludestringrepeated

    + + + + +

    Filter.Modems

    diff --git a/docs/html/event.html b/docs/html/event.html index 1a14ef7..1c2ad3b 100644 --- a/docs/html/event.html +++ b/docs/html/event.html @@ -764,6 +764,10 @@

    Table of Contents

    MFilter.Events.Update +
  • + MFilter.FieldEnumValues +
    • +
  • MFilter.Modems
    • @@ -9383,6 +9387,44 @@

    Filter.Events.Update

    +

    Filter.FieldEnumValues

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    fieldstring

    includestringrepeated

    excludestringrepeated

    + + + + +

    Filter.Modems

    diff --git a/docs/html/field_service.html b/docs/html/field_service.html index 1e7aa66..9397dd1 100644 --- a/docs/html/field_service.html +++ b/docs/html/field_service.html @@ -202,6 +202,22 @@

    Table of Contents

    MListFields.Response +
  • + MListFieldsForModem +
    • + +
  • + MListFieldsForModem.Request +
    • + +
  • + MListFieldsForModem.Response +
    • + +
  • + MListFieldsForModem.Response.ModemWithFields +
    • +
  • MReplaceAllFieldsRequest
    • @@ -835,7 +851,7 @@

    ListFields.Request

    bool

    Whether to apply the unit preferences to the fields. -This will convert any fields into you preferred unit, for convenience.

    +This will convert any fields into your preferred unit, for convenience.

    @@ -883,6 +899,158 @@

    ListFields.Response

    +

    ListFieldsForModem

    +

    + + + + + +

    ListFieldsForModem.Request

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    organizationstring

    Pick the organization to use (/impersonate). If unset, your default organization is used.

    modem_selectionhiber.modem.ModemSelection

    Select the modems to fetch the fields for.

    field_selectionFieldSelection

    Select which fields to return.

    paginationhiber.Pagination

    sortListFields.Sort

    apply_unit_preferencesbool

    Whether to apply the unit preferences to the fields. +This will convert any fields into you preferred unit, for convenience.

    include_totalbool

    Whether to also calculate the total fields for all selected modems, +and return them as a single list in the response. +This can be useful to display table columns, for example.

    + + + + + +

    ListFieldsForModem.Response

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    modem_fieldsListFieldsForModem.Response.ModemWithFieldsrepeated

    requestListFieldsForModem.Request

    paginationhiber.Pagination.Result

    totalFieldrepeated

    A merged result of all fields, for all modems. This can be useful to display table columns, for example.

    + + + + + +

    ListFieldsForModem.Response.ModemWithFields

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    modemstring

    fieldsFieldrepeated

    + + + + +

    ReplaceAllFieldsRequest

    Replace all fields for a parser with the fields given.

    @@ -1201,6 +1369,13 @@

    UpdateFieldRequest

    When set to true at a later point, earlier values are not encrypted retro-actively.

    + + optional + hiber.UpdateBoolean + +

    Whether this field is optional or not.

    + + numeric UpdateFieldNumericDetails @@ -1272,6 +1447,13 @@

    FieldService

    + + ForModem + ListFieldsForModem.Request + ListFieldsForModem.Response +

    + + Add AddFieldsRequest @@ -1393,6 +1575,13 @@

    Field

    If it is, some processing options may be unavailable or slower.

    + + optional + bool + +

    Whether this field should be validated from the parser output.

    + + unit_of_measurement hiber.UnitOfMeasurement diff --git a/docs/html/map.html b/docs/html/map.html index 71f1700..0f242b4 100644 --- a/docs/html/map.html +++ b/docs/html/map.html @@ -293,6 +293,10 @@

    Table of Contents

    MFilter.Events.Update +
  • + MFilter.FieldEnumValues +
    • +
  • MFilter.Modems
    • @@ -1370,6 +1374,44 @@

    Filter.Events.Update

    +

    Filter.FieldEnumValues

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    fieldstring

    includestringrepeated

    excludestringrepeated

    + + + + +

    Filter.Modems

    diff --git a/docs/html/modem.html b/docs/html/modem.html index cfe89c4..96da296 100644 --- a/docs/html/modem.html +++ b/docs/html/modem.html @@ -469,6 +469,10 @@

    Table of Contents

    MFilter.Events.Update +
  • + MFilter.FieldEnumValues +
    • +
  • MFilter.Modems
    • @@ -4130,6 +4134,44 @@

    Filter.Events.Update

    +

    Filter.FieldEnumValues

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    fieldstring

    includestringrepeated

    excludestringrepeated

    + + + + +

    Filter.Modems

    diff --git a/docs/html/modem_alarm.html b/docs/html/modem_alarm.html index c176c7a..a74a2d7 100644 --- a/docs/html/modem_alarm.html +++ b/docs/html/modem_alarm.html @@ -704,6 +704,10 @@

    Table of Contents

    MFilter.Events.Update +
  • + MFilter.FieldEnumValues +
    • +
  • MFilter.Modems
    • @@ -6262,6 +6266,44 @@

    Filter.Events.Update

    +

    Filter.FieldEnumValues

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    fieldstring

    includestringrepeated

    excludestringrepeated

    + + + + +

    Filter.Modems

    diff --git a/docs/html/modem_message_body_parser.html b/docs/html/modem_message_body_parser.html index 0d59daf..92c7f8c 100644 --- a/docs/html/modem_message_body_parser.html +++ b/docs/html/modem_message_body_parser.html @@ -640,6 +640,10 @@

    Table of Contents

    MFilter.Events.Update +
  • + MFilter.FieldEnumValues +
    • +
  • MFilter.Modems
    • @@ -5943,6 +5947,44 @@

    Filter.Events.Update

    +

    Filter.FieldEnumValues

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    fieldstring

    includestringrepeated

    excludestringrepeated

    + + + + +

    Filter.Modems

    diff --git a/docs/html/named_location.html b/docs/html/named_location.html index d67954a..d887c7a 100644 --- a/docs/html/named_location.html +++ b/docs/html/named_location.html @@ -309,6 +309,10 @@

    Table of Contents

    MFilter.Events.Update +
  • + MFilter.FieldEnumValues +
    • +
  • MFilter.Modems
    • @@ -1477,6 +1481,44 @@

    Filter.Events.Update

    +

    Filter.FieldEnumValues

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    fieldstring

    includestringrepeated

    excludestringrepeated

    + + + + +

    Filter.Modems

    diff --git a/docs/html/unit_preferences_service.html b/docs/html/unit_preferences_service.html index 429397b..7c8177e 100644 --- a/docs/html/unit_preferences_service.html +++ b/docs/html/unit_preferences_service.html @@ -1178,6 +1178,13 @@

    Field

    If it is, some processing options may be unavailable or slower.

    + + optional + bool + +

    Whether this field should be validated from the parser output.

    + + unit_of_measurement hiber.UnitOfMeasurement diff --git a/docs/html/value_service.html b/docs/html/value_service.html new file mode 100644 index 0000000..25fd45b --- /dev/null +++ b/docs/html/value_service.html @@ -0,0 +1,7925 @@ + + + + + Protocol Documentation + + + + + + + + + + +

    Protocol Documentation

    + +

    Table of Contents

    + +
    + +
    + + + +
    +

    value_service.proto

    Top +
    +

    Service to fetch time series data from our system.

    Time series data is produced by the device and sent in the form of messages.

    Messages are parsed to a number of values (depending on the parser), which can be retrieved using this service.

    + + +

    AggregatedValues

    +

    Aggregate values for a (set of) modem(s), filtering by field and time.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    time_rangehiber.TimeRange

    The time range that was aggregated.

    valuesValueContextrepeated

    The aggregated values for the requested fields. + +Timestamp is only set if the aggregation can return an exact data point: +- if the aggregation would return an exact point: LAST, MAXIMUM, MINIMUM. +- if the aggregation is applied to a single value, for a single field.

    locationhiber.Location

    The last location in the time range.

    + + + + + +

    AggregatedValues.Request

    +

    Request aggregated values, reducing the selected time range to a single value per field.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    organizationstring

    Pick the organization to use (/impersonate). If unset, your default organization is used.

    selectionValueSelection

    The values to return.

    aggregationsAggregatedValues.Request.AggregationsEntryrepeated

    The aggregations to use for the fields, resulting in a single value for each field. +When an aggregation is not specified for a field, the default aggregation for that field type is used. + +Fields specified here must have been specified in the selection.

    transform_fieldsAggregatedValues.Request.TransformFieldsEntryrepeated

    Transform the values for a field into a derived value. + +Fields specified here must have been specified in the selection.

    partitionAggregatedValues.Request.Partition

    Partition the time range and apply aggregation to each part.

    + + + + + +

    AggregatedValues.Request.AggregationsEntry

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    keystring

    valueValueAggregation

    + + + + + +

    AggregatedValues.Request.Partition

    +

    Partition the time range and apply aggregation to each part (instead of over all values in the time range).

    If no partition is set, the aggregation returns a single value.

    For example:

    - get the average value per day for a month

    - get the sum of all values per hour in a day

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    split_by_durationhiber.Duration

    Split up the data in time block of the given size.

    reduce_to_max_sizeuint32

    Limit the results to the given amount of data points, applying the function to each chunk.

    paginationhiber.Pagination

    Paginate the returned partitions of the time range.

    sortListValues.Sort

    How to sort the returned values.

    exclude_emptybool

    Exclude any partitions that do not have any data from response. +This is especially useful when the amount of partitions exceeds your pagination size.

    + + + + + +

    AggregatedValues.Request.TransformFieldsEntry

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    keystring

    valueValueTransformation

    + + + + + +

    AggregatedValues.Response

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    aggregated_valuesAggregatedValuesrepeated

    paginationhiber.Pagination.Result

    requestAggregatedValues.Request

    + + + + + +

    ListValues

    +

    List values for a (set of) modem(s), filtering by field and time.

    + + + + + +

    ListValues.Request

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    organizationstring

    Pick the organization to use (/impersonate). If unset, your default organization is used.

    selectionValueSelection

    paginationhiber.Pagination

    sortListValues.Sort

    transform_fieldsListValues.Request.TransformFieldsEntryrepeated

    Transform the values for a field into a derived value. +Fields specified here must have been specified in the selection.

    + + + + + +

    ListValues.Request.TransformFieldsEntry

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    keystring

    valueValueTransformation

    + + + + + +

    ListValues.Response

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    valuesValueContextrepeated

    paginationhiber.Pagination.Result

    requestListValues.Request

    + + + + + +

    ValueContext

    +

    A Value at a time, for a given modem and field.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    modemstring

    fieldstring

    timehiber.Timestamp

    The time for this value.

    valueValue

    The value at this time.

    durationValueContext.ValueDurations

    The value at this time.

    deltaValueContext.ValueDelta

    The value at this time.

    + + + + + +

    ValueContext.ValueDelta

    +

    The delta of a value: the difference between a value and the previous value.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    deltaValue

    The delta of the two values.

    currentValue

    The value at this time.

    previousValue

    The previous value to compare it with.

    + + + + + +

    ValueContext.ValueDuration

    +

    The amount of time a field for a modem was in this value.

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    valueValue

    The value the duration is for.

    durationhiber.Duration

    The aggregated duration the field was this value.

    + + + + + +

    ValueContext.ValueDurations

    +

    The amount of time a field for a modem was at different values.

    + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    durationsValueContext.ValueDurationrepeated

    + + + + + +

    ValueSelection

    +

    Select the values to return.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    modemshiber.modem.ModemSelection

    Select the modem(s) to get the values for.

    fieldsstringrepeated

    Get the values for the selected fields.

    time_rangehiber.TimeRange

    The time to view the values for.

    include_locationbool

    Include the location (which is not a field).

    filter_enum_valueshiber.Filter.FieldEnumValuesrepeated

    Filter the values for enum fields.

    + + + + + + + +

    ListValues.Sort

    +

    How to sort the values.

    + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    TIME_ASCENDING0

    TIME_DESCENDING1

    + +

    ValueAggregation

    +

    Get the values for the selected field.

    There are a few limitations here:

    - text fields can only use the LAST aggregation.

    - enum fields support a subset of aggregations:

    - DEFAULT and LAST return the last value.

    - MINIMUM and MAXIMUM return the lowest or highest value (respectively) based on the enum value order.

    - AVERAGE and SUM are not supported.

    - enum duration

    An enum example:

    Field "status" with this timeline: 00:00 OK, 00:10 FAILED, 00:20 OK, 00:25 FAILED, 00:40 OK

    - aggregation DEFAULT or LAST: OK, since it's OK at the end of the time range.

    - aggregation SUM: OK: 35m, FAILED: 25m

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    DEFAULT0

    AVERAGE1

    Return the average value. +Not supported for textual and enum fields. When used with these fields, LAST is used instead.

    SUM2

    Return the sum all values. +Not supported for textual and enum fields. When used with these fields, LAST is used instead.

    LAST3

    Just take the last value.

    MINIMUM4

    Return the lowest value. +For enum fields, the order of values is used to determine the MINIMUM. +Not supported for textual fields. When used with these fields, LAST is used instead.

    MAXIMUM5

    Return the highest value. +For enum fields, the order of values is used to determine the MAXIMUM. +Not supported for textual fields. When used with these fields, LAST is used instead.

    + +

    ValueTransformation

    +

    Transform the values into a derived value.

    + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    DURATION0

    Instead of returning the value, return the amount of time a value was active. +Aggregation (if applicable) is applied afterwards on the duration value.

    DELTA1

    Instead of returning the value, return the difference between the value and the previous value. +Aggregation (if applicable) is applied before the delta is calculated.

    + + + + + +

    ValueService

    +

    + + + + + + + + + + + + + + + + + + + + + +
    Method NameRequest TypeResponse TypeDescription
    ListListValues.RequestListValues.Response

    AggregatedAggregatedValues.RequestAggregatedValues.Response

    + + + + +
    +

    value.proto

    Top +
    +

    + + +

    Value

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    typeValue.Type

    numericValue.Numeric

    textstring

    enumValue.Enum

    + + + + + +

    Value.Enum

    +

    If this value is an enum, this specifies the value, display name and color for this enum value.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    valuestring

    The enum value. This might be a cryptic value, see the display_name and description for more information.

    display_namestring

    User-facing name for this value.

    descriptionstring

    More details for this enum value.

    colorstring

    (Optional) color for this enum value.

    priorityint32

    Priority of the value, typically used for ordering.

    + + + + + +

    Value.Numeric

    +

    If the value is numeric, this specifies the unit, value, etc.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    typeValue.Numeric.Type

    battery_levelValue.Numeric.BatteryLevel

    distanceValue.Numeric.Distance

    durationhiber.Duration

    fuel_efficiencyValue.Numeric.FuelEfficiency

    percentageValue.Numeric.Percentage

    pressureValue.Numeric.Pressure

    speedValue.Numeric.Speed

    temperatureValue.Numeric.Temperature

    voltageValue.Numeric.Voltage

    volumeValue.Numeric.Volume

    massValue.Numeric.Mass

    flowValue.Numeric.Flow

    unknowndouble

    + + + + + +

    Value.Numeric.BatteryLevel

    +

    Special case for battery level, since it can be provided in many units.

    Not included in the UnitPreferences, since it cannot be converted.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    valuedouble

    unitValue.Numeric.BatteryLevel.Unit

    textualstring

    Textual representation including unit symbol, rounded based on the user preferences and field config.

    converted_fromValue.Numeric.BatteryLevel.Unit

    The original unit, iff this value was converted from another unit because of user preferences.

    + + + + + +

    Value.Numeric.Distance

    +

    The value is a distance value, converted to your preferred distance unit.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    valuedouble

    unitValue.Numeric.Distance.Unit

    textualstring

    Textual representation including unit symbol, rounded based on the user preferences and field config.

    converted_fromValue.Numeric.Distance.Unit

    The original unit, iff this value was converted from another unit because of user preferences.

    + + + + + +

    Value.Numeric.Flow

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    valuedouble

    unitValue.Numeric.Flow.Unit

    textualstring

    Textual representation including unit symbol, rounded based on the user preferences and field config.

    converted_fromValue.Numeric.Flow.Unit

    The original unit, iff this value was converted from another unit because of user preferences.

    + + + + + +

    Value.Numeric.FuelEfficiency

    +

    The value is a distance value, converted to your preferred distance unit.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    valuedouble

    unitValue.Numeric.FuelEfficiency.Unit

    textualstring

    Textual representation including unit symbol, rounded based on the user preferences and field config.

    converted_fromValue.Numeric.FuelEfficiency.Unit

    The original unit, iff this value was converted from another unit because of user preferences.

    + + + + + +

    Value.Numeric.Mass

    +

    The value is a volume value, converted to your preferred volume unit.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    valuedouble

    unitValue.Numeric.Mass.Unit

    textualstring

    Textual representation including unit symbol, rounded based on the user preferences and field config.

    converted_fromValue.Numeric.Mass.Unit

    The original unit, iff this value was converted from another unit because of user preferences.

    + + + + + +

    Value.Numeric.Percentage

    +

    The value is a percentage.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    valuefloat

    unitValue.Numeric.Percentage.Unit

    textualstring

    Textual representation with % symbol, rounded based on the user preferences and field config.

    + + + + + +

    Value.Numeric.Pressure

    +

    The value is a pressure value, converted to your preferred pressure unit.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    valuedouble

    unitValue.Numeric.Pressure.Unit

    textualstring

    Textual representation including unit symbol, rounded based on the user preferences and field config.

    converted_fromValue.Numeric.Pressure.Unit

    The original unit, iff this value was converted from another unit because of user preferences.

    + + + + + +

    Value.Numeric.Speed

    +

    The value is a speed value, converted to your preferred speed unit.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    valuedouble

    unitValue.Numeric.Speed.Unit

    textualstring

    Textual representation including unit symbol, rounded based on the user preferences and field config.

    converted_fromValue.Numeric.Speed.Unit

    The original unit, iff this value was converted from another unit because of user preferences.

    + + + + + +

    Value.Numeric.Temperature

    +

    The value is a temperature, converted to your preferred temperature unit.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    valuedouble

    unitValue.Numeric.Temperature.Unit

    textualstring

    Textual representation including unit symbol, rounded based on the user preferences and field config.

    converted_fromValue.Numeric.Temperature.Unit

    The original unit, iff this value was converted from another unit because of user preferences.

    + + + + + +

    Value.Numeric.Voltage

    +

    The value is a voltage, converted to your preferred voltage unit.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    valuedouble

    unitValue.Numeric.Voltage.Unit

    textualstring

    Textual representation including unit symbol, rounded based on the user preferences and field config.

    converted_fromValue.Numeric.Voltage.Unit

    The original unit, iff this value was converted from another unit because of user preferences.

    + + + + + +

    Value.Numeric.Volume

    +

    The value is a volume value, converted to your preferred volume unit.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    valuedouble

    unitValue.Numeric.Volume.Unit

    textualstring

    Textual representation including unit symbol, rounded based on the user preferences and field config.

    converted_fromValue.Numeric.Volume.Unit

    The original unit, iff this value was converted from another unit because of user preferences.

    + + + + + + + +

    Value.Numeric.BatteryLevel.Unit

    +

    + + + + + + + + + + + + + +
    NameNumberDescription
    PERCENT0

    Battery level as a percentage (technically not a unit). + +other units will be added here later, like voltage

    + +

    Value.Numeric.Distance.Unit

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    METER0

    MILLIMETER1

    CENTIMETER2

    KILOMETER3

    YARD5

    MILE4

    FOOT6

    INCH7

    NAUTICAL_MILE8

    This is a special case unit and may not be auto-converted to your UnitPreference.

    + +

    Value.Numeric.DurationUnit

    +

    The duration enum is not wrapped in Duration, since duration is always returned as a normalize Duration.

    This unit is still used for fields, however.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    MILLISECONDS0

    SECONDS1

    MINUTES2

    HOURS3

    DAYS4

    WEEKS5

    + +

    Value.Numeric.Flow.Unit

    +

    + + + + + + + + + + + + + +
    NameNumberDescription
    CUBIC_METER_PER_HOUR0

    + +

    Value.Numeric.FuelEfficiency.Unit

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    LITER_PER_100_KILOMETER0

    KILOMETER_PER_LITER1

    KILOMETER_PER_GALLON2

    KILOMETER_PER_IMPERIAL_GALLON3

    MILE_PER_GALLON4

    MILE_PER_IMPERIAL_GALLON5

    MILE_PER_LITER6

    + +

    Value.Numeric.Mass.Unit

    +

    + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    KILOGRAMS0

    POUNDS1

    + +

    Value.Numeric.Percentage.Unit

    +

    + + + + + + + + + + + + + +
    NameNumberDescription
    PERCENT0

    Technically not a unit, but for consistency, we've added it here.

    + +

    Value.Numeric.Pressure.Unit

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    BAR0

    PSI1

    K_PA2

    + +

    Value.Numeric.Speed.Unit

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    KILOMETERS_PER_HOUR0

    KNOTS1

    This is a special case unit and may not be auto-converted to your UnitPreference.

    METERS_PER_SECOND2

    MILES_PER_HOUR3

    + +

    Value.Numeric.Temperature.Unit

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    KELVIN0

    DEGREES_CELSIUS1

    DEGREES_FAHRENHEIT2

    + +

    Value.Numeric.Type

    +

    The type of numeric value that is represented.

    Supported types will automatically convert to the preferred unit (based on the user settings).

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    TYPE_UNKNOWN0

    PERCENTAGE1

    TEMPERATURE2

    DISTANCE3

    PRESSURE4

    VOLTAGE5

    SPEED6

    VOLUME7

    DURATION8

    FUEL_EFFICIENCY9

    MASS10

    BATTERY_LEVEL11

    FLOW12

    + +

    Value.Numeric.Voltage.Unit

    +

    + + + + + + + + + + + + + +
    NameNumberDescription
    MILLIVOLT0

    + +

    Value.Numeric.Volume.Unit

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    LITER0

    GALLON_US1

    GALLON_IMPERIAL2

    CUBIC_METER3

    CUBIC_FEET4

    + +

    Value.Type

    +

    The type of value that is represented.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    OTHER0

    NUMERIC1

    This field contains numeric values, with an optional unit of measurement defined below.

    TEXT2

    This field contains text to be displayed.

    ENUM3

    This field switches between several predefined values. Typically used for status fields.

    + + + + + + + +
    +

    modem.proto

    Top +
    +

    Modem and message management.

    Modems are anything capable of sending messages to the system. They have a unique modem number,

    used to identify them.

    + + +

    CreateModem

    +

    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.

    + + + + + +

    CreateModem.Request

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    organizationstring

    Pick the organization to use (/impersonate). If unset, your default organization is used.

    amountuint32

    The amount of modems to create.

    namesstringrepeated

    The name(s) to give the new modem(s). +Must not contain more values than the amount of modems to create.

    external_device_identifiersstringrepeated

    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.

    statusModem.Status

    The status for the new modems.

    technicalModem.TechnicalData

    The technical data, such as manufacturer and hardware information for the new modems.

    peripheralsCreateModem.Request.PeripheralsEntryrepeated

    The peripherals for the new modems.

    notesstring

    Notes for all new modems.

    locationhiber.Location

    random_location_in_areahiber.Area

    tagshiber.tag.UpdateTagsForItem

    The tags to set to the new modems, either existing or created by this call.

    include_modems_in_responsebool

    Whether to return the full Modem in addition to the modem number and verification code.

    include_verification_codebool

    Whether to return the verification code for the modem.

    + + + + + +

    CreateModem.Request.PeripheralsEntry

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    keystring

    valuestring

    + + + + + +

    CreateModem.Response

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    modemsCreateModem.Response.CreatedModemrepeated

    requestCreateModem.Request

    + + + + + +

    CreateModem.Response.CreatedModem

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    modem_numberstring

    The modem number that was created.

    verification_codestring

    The verification code for this modem number, used to, for example, claim modems. +Only available when include_verification_code was set to true.

    modemModem

    Only available when include_modems_in_response was set to true.

    + + + + + +

    GetModemRequest

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    organizationstring

    Pick the organization to use (/impersonate). If unset, your default organization is used.

    in_organizationshiber.organization.OrganizationSelection

    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. + +This replaces the child_organizations option, allowing search in all accessible organizations.

    modem_numberstring

    The modem to get.

    child_organizationshiber.Filter.ChildOrganizations

    Deprecated. Look for the modem in child organizations. +DEPRECATED: use the in_organizations flag instead.

    + + + + +

    Fields with deprecated option

    + + + + + + + + + + + + + + + +
    NameOption
    child_organizations

    true

    + + + + + +

    ListModemMessagesRequest

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    organizationstring

    Pick the organization to use (/impersonate). If unset, your default organization is used.

    selectionModemMessageSelection

    paginationhiber.Pagination

    + + + + + +

    ListModemMessagesRequest.Response

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    messagesModemMessagerepeated

    requestListModemMessagesRequest

    paginationhiber.Pagination.Result

    + + + + + +

    ListModemsGrouped

    +

    Lists all modems the given criteria, grouped by gateway.

    Pagination is applied to modems in a group, not to the groups themselves.

    + + + + + +

    ListModemsGrouped.Request

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    group_contentListModemsRequest

    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. + +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.

    groupsListModemsRequest

    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.

    allow_any_group_parentbool

    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.

    + + + + + +

    ListModemsGrouped.Response

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    groupsListModemsRequest.Responserepeated

    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. + +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.

    requestListModemsGrouped.Request

    paginationhiber.Pagination.Result

    sorted_byListModemsRequest.Sortrepeated

    + + + + + +

    ListModemsRequest

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    organizationstring

    Pick the organization to use (/impersonate). If unset, your default organization is used.

    selectionModemSelection

    Select which modems to return.

    paginationhiber.Pagination

    Paginate through results.

    sort_byListModemsRequest.Sortrepeated

    Sort the modem with the given sort options.

    include_inbound_modemsbool

    Whether to include inbound modems in the results. +Inbound modems are modems that are in a transfer that has been sent *to* your organization, but that has not +been marked as received yet.

    include_outbound_modemsbool

    Whether to include outbound modems in the results. +Inbound modems are modems that are in a transfer that has been sent *from* your organization, but that has not +been marked as received yet.

    child_organizationshiber.Filter.ChildOrganizations

    Deprecated. Include modems from the selected child organizations. +DEPRECATED: this option will be removed in the future!

    location_selectionhiber.LocationSelection

    Filter modems by location.

    include_missing_group_parentsbool

    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.

    + + + + +

    Fields with deprecated option

    + + + + + + + + + + + + + + + +
    NameOption
    child_organizations

    true

    + + + + + +

    ListModemsRequest.Response

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    modemsModemrepeated

    requestListModemsRequest

    paginationhiber.Pagination.Result

    sorted_byListModemsRequest.Sortrepeated

    group_parentsModemrepeated

    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.

    + + + + + +

    MessageCountRequest

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    organizationstring

    Pick the organization to use (/impersonate). If unset, your default organization is used.

    selectionModemMessageSelection

    time_zone_offsetint32

    Numeric timezone offset for day grouping. Optional.

    time_zonestring

    Timezone string for day grouping. Optional.

    + + + + + +

    MessageCountRequest.Response

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    message_count_per_dayMessageCountRequest.Response.MessageCountrepeated

    requestMessageCountRequest

    + + + + + +

    MessageCountRequest.Response.MessageCount

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    datehiber.Date

    countint32

    + + + + + +

    Modem

    +

    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.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    numberstring

    An 8-character hexadecimal string

    organizationstring

    namestring

    An optional descriptor given to the modem

    locationhiber.Location

    last_message_iduint64

    last_message_received_athiber.Timestamp

    Time the server has received the last message.

    last_message_sent_athiber.Timestamp

    Time the modem has sent the last message.

    last_message_bodyhiber.BytesOrHex

    The body of the last message.

    inactivityhiber.Duration

    The amount of time since the last message from this modem was received on the server.

    healthhiber.Health

    Deprecated. Deprecated health based on the number of error and warning events this modem has received in the past 30 days +Uses the OK, WARNING, ERROR format.

    health_levelhiber.health.HealthLevel

    Health level based on the modem alarm and some always-present alarms.

    statusModem.Status

    active_subscriptionModem.ActiveSubscription

    additional information

    technicalModem.TechnicalData

    peripheralsModem.Peripherals

    in_transferModem.Transfer

    notesstring

    Notes field that can be used to add additional information to a modem.

    secure_notesstring

    Secure notes field that can be used to add additional information to a modem, with limited accessibility.

    tagshiber.tag.Tagrepeated

    is_gatewaybool

    Deprecated. [DEPRECATED] Whether the modem is a gateway, it has been configured as a gateway and has connected devices. +Use `type` instead.

    is_device_connected_to_gatewaybool

    Deprecated. [DEPRECATED] Whether the modem is connected to a modem configured as a gateway. +Use `type` instead.

    connected_to_gatewaystring

    Deprecated. [DEPRECATED] The modem number that this modem is connected to, if any. +Use `connected_device_info.connected_to_gateway` instead.

    external_device_idsstringrepeated

    Deprecated. [DEPRECATED] External device ids, if any. +Use `connected_device_info.external_device_ids` instead.

    typeModem.Type

    The type of modem. +Used mainly to differentiate in the UI or to sort on.

    gateway_infoModem.GatewayInfo

    Additional information when this modem is a gateway.

    connected_device_infoModem.ConnectedDeviceInfo

    Additional information when this modem is a connected device.

    metadatagoogle.protobuf.Struct

    Modem metadata, typically extracted from messages.

    time_zonestring

    The timezone configured for the modem.

    transmission_intervalhiber.Duration

    The transmission interval for this modem, if configured.

    + + + + +

    Fields with deprecated option

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameOption
    health

    true

    is_gateway

    true

    is_device_connected_to_gateway

    true

    connected_to_gateway

    true

    external_device_ids

    true

    + + + + + +

    Modem.ActiveSubscription

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    typehiber.organization.subscription.ServiceType

    start_datehiber.Timestamp

    end_datehiber.Timestamp

    + + + + + +

    Modem.ConnectedDeviceInfo

    +

    Additional information when this modem is a connected device.

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    connected_to_gatewaystring

    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.

    external_device_idsstringrepeated

    External device ids for this modem.

    + + + + + +

    Modem.GatewayInfo

    +

    Additional information when this modem is a gateway.

    + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    number_of_connected_devicesint32

    + + + + + +

    Modem.Peripherals

    +

    Peripherals attached to the modem, including antenna, whether it has a gps antenna and an

    open field for peripherals like battery, sensors, etc.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    hiber_antennaModem.Peripherals.HiberAntenna

    gpsbool

    peripheralsModem.Peripherals.PeripheralsEntryrepeated

    custom_antennastring

    + + + + + +

    Modem.Peripherals.PeripheralsEntry

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    keystring

    valuestring

    + + + + + +

    Modem.TechnicalData

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    hardware_namestring

    firmware_version_namestring

    hardware_production_batchstring

    manufacturerstring

    + + + + + +

    Modem.Transfer

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    statusModem.Transfer.Status

    identifierstring

    + + + + + +

    ModemHealthCount

    +

    + + + + + +

    ModemHealthCount.HealthCount

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    health_levelhiber.health.HealthLevel

    Health level based on the modem alarm and some always-present alarms.

    countuint32

    The number of modems matching the modem selection with this health level

    healthhiber.Health

    Deprecated. Deprecated health based on the number of error and warning events this modem has received in the past 30 days +Uses the OK, WARNING, ERROR format.

    + + + + +

    Fields with deprecated option

    + + + + + + + + + + + + + + + +
    NameOption
    health

    true

    + + + + + +

    ModemHealthCount.HealthCountGroupedPerTag

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    taghiber.tag.Tag

    The tag this count is for.

    health_countsModemHealthCount.HealthCountrepeated

    + + + + + +

    ModemHealthCount.Request

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    organizationstring

    Pick the organization to use (/impersonate). If unset, your default organization is used.

    modem_selectionModemSelection

    Selection of modems to count. If default, all modems are counted.

    include_tag_countbool

    Whether to return specific counts for tags, selected using the tag_count_selection.

    tag_count_selectionhiber.tag.TagSelection

    Selection of tags to return specific counts for. If default, count is calculated for all tags.

    + + + + + +

    ModemHealthCount.Response

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    health_totalsModemHealthCount.HealthCountrepeated

    health_grouped_per_tagModemHealthCount.HealthCountGroupedPerTagrepeated

    requestModemHealthCount.Request

    + + + + + +

    ModemMessage

    +

    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)

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    message_iduint64

    Unique message identifier.

    modem_numberstring

    Modem number of the modem that sent the message.

    modem_namestring

    The name of the modem that sent the message.

    modem_identifierstring

    The device identifier for the modem that sent the message (e.g. a MAC address).

    sent_athiber.Timestamp

    Time the message was sent from the modem.

    received_athiber.Timestamp

    Time the message was received on the server.

    locationhiber.Location

    Modem location when the message was sent.

    bodybytes

    Message body.

    body_byteshiber.BytesOrHex

    Message body convenience object.

    body_parsedModemMessage.ParsedBodyrepeated

    A list of applied body parsers and their results.

    body_parsed_successfullybool

    Convenience flag marking whether the body was parsed successfully by at least one parser.

    sourcesModemMessage.Sourcerepeated

    Message source(s) for this message (i.e. it was received through the satellite or directly to the server).

    is_testbool

    True if the the TEST source is in the sources.

    is_gateway_messagebool

    Whether this message contains other messages.

    via_gateway_messageuint64

    The gateway message this message was sent in.

    metadatagoogle.protobuf.Struct

    Message metadata, defined by the modem or gateway.

    body_fieldsgoogle.protobuf.Struct

    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.

    tagshiber.tag.Tagrepeated

    The tags of the modem that sent the message.

    tag_namesstringrepeated

    The names of the tags of the modem that sent the message.

    + + + + + +

    ModemMessage.ParsedBody

    +

    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.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    parser_idint32

    Deprecated. 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.

    parser_identifierstring

    Globally unique identifier of the parser that was used.

    parser_namestring

    Name of the parser that was used.

    errorstring

    Error while parsing the message body.

    resultgoogle.protobuf.Struct

    Result of parsing the body with this parser.

    + + + + +

    Fields with deprecated option

    + + + + + + + + + + + + + + + +
    NameOption
    parser_id

    true

    + + + + + +

    ModemMessageSelection

    +

    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)

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    modemshiber.Filter.Modems

    Deprecated. Define the modems to return messages for, i.e. include = [AAAA AAAA, BBBB BBBB]. +Deprecated in favor of using the ModemSelection.

    modem_selectionModemSelection

    Select the modems to return messages for.

    time_rangehiber.TimeRange

    Filter message by time range. This field is required, to limit the amount of messages.

    filter_by_sourcesModemMessageSelection.ModemMessageSourceFilter

    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.

    + + + + +

    Fields with deprecated option

    + + + + + + + + + + + + + + + +
    NameOption
    modems

    true

    + + + + + +

    ModemMessageSelection.ModemMessageSourceFilter

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    includeModemMessage.Sourcerepeated

    excludeModemMessage.Sourcerepeated

    + + + + + +

    ModemSelection

    +

    Selection object for modems.

    Filter modems by modem id, (child)organization, tags, activation status and time, service type and last message time.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    modemshiber.Filter.Modems

    free_text_searchstring

    only_activebool

    activated_inhiber.TimeRange

    with_last_message_inhiber.TimeRange

    with_service_typehiber.organization.subscription.ServiceTyperepeated

    healthhiber.Healthrepeated

    Deprecated. Deprecated health that uses the OK, WARNING, ERROR format.

    health_levelsstringrepeated

    Filter modems by health level.

    statusModem.Statusrepeated

    Filter modems by status(es). +Defaults to nominal statuses, excluding disabled, dead, lost or damaged modems.

    transfersModemSelection.Transfers

    include_typesModem.Typerepeated

    Only include modems that have a type listed in types. +In other words, when providing multiple types, this is an "OR" relationship.

    exclude_typesModem.Typerepeated

    Exclude modems that have a type listed in types.

    only_gatewaysbool

    Deprecated. [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`.

    only_has_external_device_idsbool

    Deprecated. [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`.

    connected_to_gatewayshiber.Filter.Modems

    external_device_idsstringrepeated

    filter_by_tagshiber.tag.TagSelection

    peripheralsModemSelection.Peripherals

    only_without_peripheralbool

    When set to true, only modems that do not have any peripheral will be included in the result.

    + + + + +

    Fields with deprecated option

    + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameOption
    health

    true

    only_gateways

    true

    only_has_external_device_ids

    true

    + + + + + +

    ModemSelection.Peripherals

    +

    Filter to (de)select modems based on their peripherals.

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    include_andModemSelection.Peripherals.IncludeAndEntryrepeated

    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. + +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.

    excludeModemSelection.Peripherals.ExcludeEntryrepeated

    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. + +For example: +- 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

    + + + + + +

    ModemSelection.Peripherals.ExcludeEntry

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    keystring

    valueModemSelection.Peripherals.OneOfValues

    + + + + + +

    ModemSelection.Peripherals.IncludeAndEntry

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    keystring

    valueModemSelection.Peripherals.OneOfValues

    + + + + + +

    ModemSelection.Peripherals.OneOfValues

    +

    + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    valuestringrepeated

    + + + + + +

    ModemSelection.Transfers

    +

    + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    transfers_identifiersstringrepeated

    + + + + + +

    RenameModemRequest

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    organizationstring

    Pick the organization to use (/impersonate). If unset, your default organization is used.

    modem_numberstring

    namestring

    + + + + + +

    UpdateModemNotesRequest

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    organizationstring

    Pick the organization to use (/impersonate). If unset, your default organization is used.

    selectionModemSelection

    paginationhiber.Pagination

    notesstring

    Notes content

    allow_override_existing_notesbool

    When you try to set a new notes value to multiple modems, the API returns an error if their previous +values were different. Set this to true to apply it anyway.

    + + + + + +

    UpdateModemNotesRequest.Response

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    modemsModemrepeated

    requestUpdateModemNotesRequest

    paginationhiber.Pagination.Result

    + + + + + +

    UpdateModemSecureNotesRequest

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    organizationstring

    Pick the organization to use (/impersonate). If unset, your default organization is used.

    modem_numberstring

    secure_notesstring

    + + + + + +

    UpdateModemSecureNotesRequest.Response

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    modemModem

    requestUpdateModemSecureNotesRequest

    + + + + + +

    UpdateModemStatusRequest

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    organizationstring

    Pick the organization to use (/impersonate). If unset, your default organization is used.

    modem_numberstring

    Deprecated. Either pick a single modem to update. DEPRECATED, since ModemSelection is more flexible.

    modem_selectionModemSelection

    Or a modem selection.

    update_statusModem.Status

    The new status for the modem(s).

    paginationhiber.Pagination

    Pagination for the modems in the Response.

    + + + + +

    Fields with deprecated option

    + + + + + + + + + + + + + + + +
    NameOption
    modem_number

    true

    + + + + + +

    UpdateModemStatusRequest.Response

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    modemModem

    Deprecated.

    modemsModemrepeated

    requestUpdateModemStatusRequest

    paginationhiber.Pagination.Result

    + + + + +

    Fields with deprecated option

    + + + + + + + + + + + + + + + +
    NameOption
    modem

    true

    + + + + + +

    UpdateModemTagsRequest

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    organizationstring

    Pick the organization to use (/impersonate). If unset, your default organization is used.

    updatehiber.tag.UpdateTagsForItem

    selectionModemSelection

    paginationhiber.Pagination

    + + + + + +

    UpdateModemTagsRequest.Response

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    modemsModemrepeated

    requestUpdateModemTagsRequest

    paginationhiber.Pagination.Result

    + + + + + +

    UpdatePeripheralsRequest

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    organizationstring

    Pick the organization to use (/impersonate). If unset, your default organization is used.

    selectionModemSelection

    hiber_antennaModem.Peripherals.HiberAntenna

    gpshiber.UpdateBoolean

    hardcoded_gps_locationhiber.Location

    add_peripheralsUpdatePeripheralsRequest.AddPeripheralsEntryrepeated

    remove_peripheralsstringrepeated

    paginationhiber.Pagination

    custom_antennastring

    time_zonehiber.UpdateClearableString

    update_transmission_intervalhiber.Duration

    remove_transmission_intervalbool

    + + + + + +

    UpdatePeripheralsRequest.AddPeripheralsEntry

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    keystring

    valuestring

    + + + + + +

    UpdatePeripheralsRequest.Response

    +

    The result is paginated if affecting more than 100 modems. Use the list call to paginate further.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    requestUpdatePeripheralsRequest

    modemsModemrepeated

    paginationhiber.Pagination.Result

    + + + + + + + +

    ListModemsRequest.Sort

    +

    Sorting options for the results.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    LAST_MESSAGE_RECEIVED0

    LAST_MESSAGE_RECEIVED_INVERTED1

    MODEM_NUMBER_ASC2

    Sort numerically on the number of the modem.

    MODEM_NUMBER_DESC3

    STATUS_ASC4

    STATUS_DESC5

    MODEM_NAME_ASC6

    Sort alphabetically on the name of the modem. De default name of the modem is its HEX number

    MODEM_NAME_DESC7

    ORGANIZATION_ASC8

    Sort alphabetically on the name of the organization that owns the modem

    ORGANIZATION_DESC9

    HEALTH10

    Health sorted from least to most severe (i.e. OK, WARNING, ERROR).

    HEALTH_DESC11

    Health sorted from most to least severe (i.e. ERROR, WARNING, OK).

    + +

    Modem.Peripherals.HiberAntenna

    +

    A Hiber antenna is required for the modem to function.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    DEFAULT0

    HIBER_PANDA1

    HIBER_GRIZZLY2

    HIBER_BLACK3

    CUSTOM4

    + +

    Modem.Status

    +

    Modem statuses for its lifecycle.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    DEFAULT0

    Modem is in your inventory, but not deployed or active.

    ACTIVE1

    Modem is active and sending messages. +See health for more details on its health, based on the past messages.

    DAMAGED2

    LOST3

    DEAD4

    DISABLED5

    + +

    Modem.Transfer.Status

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    NONE0

    INBOUND1

    Modem has been shipped or transferred to you and is inbound. +When you mark the transfer as received, the modems are added to your organization. +If you encounter any issues, you can mark modems for return using the ModemTransferReturnService.

    OUTBOUND2

    Modem has been shipped or transferred by you and is outbound. +When the transfer is received, the modems are removed from your organization, though the recipient may +still return them later.

    RETURNING3

    You shipped this modem to another organization, but they are returning it. +When you mark the transfer as received, the modems are added back to your organization.

    + +

    Modem.Type

    +

    The effective type of this modem.

    Type can depend on the hardware itself as well as network topology.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    OTHER0

    A device of which the specific type is not known

    DIRECT1

    A devices that directly connects to the satellite

    GATEWAY2

    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).

    CONNECTED_DEVICE3

    A sensor that can (only) send data to a gateway. Typically using a LoRaWAN connection.

    + +

    ModemMessage.Source

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    HIBERBAND0

    A real message from a modem or gateway, sent over Hiberband to the server.

    DIRECT_TO_API1

    A real message from a modem or gateway, sent directly to the API using a persistent connection.

    TEST2

    A test message sent to the testing API.

    SIMULATION3

    A simulated message, generated by the server.

    + + + + + +

    ModemService

    +

    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.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Method NameRequest TypeResponse TypeDescription
    GetGetModemRequestModem

    Get a single modem.

    CreateCreateModem.RequestCreateModem.Response

    Create new modem(s). This is only available if your organization can create modems.

    ListListModemsRequestListModemsRequest.Response

    List the modems in your organization, and, optionally, its child organizations.

    GroupedListModemsGrouped.RequestListModemsGrouped.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.

    MessagesListModemMessagesRequestListModemMessagesRequest.Response

    List messages for the selected modems.

    MessageCountMessageCountRequestMessageCountRequest.Response

    Count messages for the selected modems.

    RenameRenameModemRequestModem

    Change the name of a modem to the given value.

    UpdateTagsUpdateModemTagsRequestUpdateModemTagsRequest.Response

    Add, remove and create new tags for the selected modems.

    UpdateNotesUpdateModemNotesRequestUpdateModemNotesRequest.Response

    Change the notes for the selected modems to the given value.

    UpdateSecureNotesUpdateModemSecureNotesRequestUpdateModemSecureNotesRequest.Response

    Change the secure notes for the selected modems to the given value, if you have permission.

    UpdateStatusUpdateModemStatusRequestUpdateModemStatusRequest.Response

    Change the status of the selected modems to the given value.

    UpdatePeripheralsUpdatePeripheralsRequestUpdatePeripheralsRequest.Response

    Add and remove peripherals for the selected modems.

    HealthCountModemHealthCount.RequestModemHealthCount.Response

    Count the modems in your organization by health.

    + + + + +

    Methods with deprecated option

    + + + + + + + + + + + + + + + + + + + + +
    Method NameOption
    Messages

    true

    MessageCount

    true

    + + + + +
    +

    base.proto

    Top +
    +

    + + +

    Area

    +

    Rectangular area between two locations, normalized to bottom-left and top-right points.

    Center point is added for convenience; it's simple the point directly between the two corner points.

    When sending an Area to the api, the center location is ignored.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    centerLocation

    bottom_leftLocation

    top_rightLocation

    textualstring

    Text representation. Can be used as an alternative input in a request, filled in by the API in responses.

    + + + + + +

    Avatar

    +

    An avatar is represented either by a (publicly) fetchable URL that serves an image,

    xor a binary payload that knows its name and mime-type.

    If it is a url, it must be obtainable without credentials, though this is not validated by the API.

    Because the content behind URL's can change or become unavailable over time,

    the client should make sure it properly caches the data fetched from the URL.

    ("Properly" means [among other things] respecting the response headers for this resource)

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    urlstring

    A URL that contains the location of avatar.

    imageNamedFile

    The data of the avatar as a Named File.

    + + + + + +

    BytesOrHex

    +

    Some clients may prefer direct binary data, while other prefer a hexadecimal string,

    both for input and output. To support both methods, this object is used to represent binary data.

    When you receive this from the api, both fields are set. When sending it to the api, only one field is required.

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    bytesbytes

    hexstring

    + + + + + +

    BytesOrHex.Update

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    updatedbool

    valueBytesOrHex

    + + + + + +

    Date

    +

    Date type for convenience.

    Some clients are better at parsing year, month and day of month as separate fields,

    while others prefer a text-based format.

    To accommodate this, this Date type supports both.

    When used as API output, both the int fields and textual fields will be set.

    The textual field has the commonly used ISO 8601 local date format (i.e. "2018-01-01").

    When used an API input, either specify the int fields or the textual field.

    If both are specified, the textual field will be discarded.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    yearuint32

    monthuint32

    dayuint32

    textualstring

    + + + + + +

    DoubleRange

    +

    Decimal range.

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    startdouble

    enddouble

    + + + + + +

    Duration

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    durationgoogle.protobuf.Duration

    textualstring

    + + + + + +

    Filter

    +

    Filters used in many api calls to filter the data sources, results, etc.

    "Include" fields filter out anything not in the include set.

    When not set, all items will be returned (except excluded items)

    "Exclude" fields filter out anything in the exclude set.

    When combined with include, exclude takes precedence when determining whether an item is filtered

    + + + + + +

    Filter.ChildOrganizations

    +

    Specify which organizations to get data from. By default, data is only retrieved for the current organization, but

    using ChildOrganizations we can specify to include a number of, or all, sub-organizations.

    Note: ChildOrganization differs from other filters in that it defaults to not allowing anything, where the

    other filters default to allowing everything

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    include_allbool

    includestringrepeated

    excludestringrepeated

    + + + + + +

    Filter.ChildOrganizations.Update

    +

    Update object to update a Filter.ChildOrganizations field.

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    updatedbool

    valueFilter.ChildOrganizations

    + + + + + +

    Filter.Events

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    includeEventTyperepeated

    excludeEventTyperepeated

    + + + + + +

    Filter.Events.Update

    +

    Update object to update a Filter.Events field.

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    updatedbool

    valueFilter.Events

    + + + + + +

    Filter.FieldEnumValues

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    fieldstring

    includestringrepeated

    excludestringrepeated

    + + + + + +

    Filter.Modems

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    includestringrepeated

    Include all modems with these modem numbers (HEX)

    excludestringrepeated

    Exclude all modems with these modem numbers (HEX). +Exclude takes precedence over include.

    + + + + + +

    Filter.Modems.Update

    +

    Update object to update a Filter.Modems field.

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    updatedbool

    valueFilter.Modems

    + + + + + +

    Filter.OrganizationPermissions

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    include_allbool

    includeOrganizationPermissionrepeated

    excludeOrganizationPermissionrepeated

    + + + + + +

    Filter.Organizations

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    includestringrepeated

    excludestringrepeated

    + + + + + +

    Filter.Publishers

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    includeint64repeated

    excludeint64repeated

    only_activebool

    + + + + + +

    Filter.Tags

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    includeint64repeated

    excludeint64repeated

    + + + + + +

    Filter.Tags.Update

    +

    Update object to update a Filter.Tags field.

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    updatedbool

    valueFilter.Tags

    + + + + + +

    Filter.UserPermissions

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    include_allbool

    includeUserPermissionrepeated

    excludeUserPermissionrepeated

    + + + + + +

    Filter.Users

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    includestringrepeated

    excludestringrepeated

    + + + + + +

    Filter.Webhooks

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    includeint64repeated

    excludeint64repeated

    only_activebool

    + + + + + +

    Location

    +

    Geographic latitude and longitude coordinates specified in decimal degrees.

    For more information, see the WGS-84 coordinate system, which is used for most GPS systems.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    latitudedouble

    Decimal degrees north.

    longitudedouble

    Decimal degrees east.

    textualstring

    Text representation. Can be used as an alternative input in a request, filled in by the API in responses.

    + + + + + +

    LocationSelection

    +

    Selection object for map data. Filter modems on the map by id, (child)organization.

    Also, filter the map data by level and area restriction, to only display a small area at a detailed map level,

    for example

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    areasArearepeated

    Rectangular areas, each defined by two locations, normalized to bottom-left and top-right points.

    shapesShaperepeated

    Polygon shapes, each defined by a list of locations, which draw a shape on the map.

    + + + + + +

    NamedFile

    +

    A NamedFile contains bytes with its mime-type and name.

    It can represent any file of any type.

    Note that depending on where in the API this is used,

    the server might put restrictions on file size, media-type or name length.

    The file name should be interpreted as-is.

    No hierarchical information is stored in the name, nor should you look at the "extension" to know its media-type.

    It might not even have a file extension.

    The file name may contain characters that cannot be a valid file name on certain systems.

    Specific API calls may pur restrictions on the name or size of the file.

    When showing this as an image in a browser, one can make use of a `data` URI.

    The client must convert the bytes to base64 and can then construct a data URI like this

    data:;base64,

    Other type clients should be able to sort-of-directly set the data bytes as the source for an image.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    dataBytesOrHex

    The binary payload that represents the file

    media_typestring

    The media-type of the file, as defined by RFC 6838 or its extensions

    namestring

    A semantic name for this file.

    + + + + + +

    Pagination

    +

    Pagination is normalized across the api. Provide a pagination object to get a specific page or offset,

    or limit your data.

    Calls that have a pagination option automatically return a Pagination.Result, which contains

    either the specified pagination options or the defaults, as well as total counts. It also contains Pagination

    objects that can be used for the previous and next page.

    This effectively means that an api user would never need to create their own pagination object; as long as they

    start at the first page and continue to the next, they can use the provided Pagination object.

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    sizeint32

    pageint32

    + + + + + +

    Pagination.Result

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    sizeint32

    pageint32

    totalint32

    total_pagesint32

    previousPagination

    nextPagination

    approximated_totalbool

    Indicates that the total is an approximation, and not an exact value. +This can be set for data that changes often, or is generally only fetched in an infinite scrolling manner. +For example, unbundled events are likely to return an approximated total, but not guaranteed to do so.

    + + + + + +

    Shape

    +

    Polygon shape defined by a list of locations, which draw a shape on the map.

    The last point is connected to the first to close the shape.

    For example, the outline of a city would be defined using a Shape,

    while a rectangular region is easier to define using Area.

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    pathLocationrepeated

    textualstring

    Text representation. Can be used as an alternative input in a request, filled in by the API in responses.

    + + + + + +

    TimeRange

    +

    Period of time between two timestamps. Typically used for filtering.

    This can be used with textual shortcuts for timestamp, and some additional duration textual shortcuts:

    - a duration as an offset of now, i.e. "-10h" or "PT-10h": converted to now + offset, so start.textual -10h is

    10 hours before the end time (using the ISO 8601 duration format)

    Examples:

    - start "-10h" end "now": a time range from 10 hours before the request time, to the request time

    - start "-10h" end "2022-01-01 20:00": becomes start 2022-01-01 10:00 end 2022-01-01 20:00

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    startTimestamp

    endTimestamp

    + + + + + +

    Timestamp

    +

    Timestamp type for convenience.

    Some clients are better at parsing Google's seconds/nanos based timestamp, while others prefer a text-based format.

    To accommodate this, this Timestamp type supports both.

    When used as API output, both the timestamp and textual fields will be set. The textual field has the commonly

    used ISO 8601 format (i.e. "2018-01-01T13:00:00Z").

    When used an API input, only one of the fields is needed, there is no need to set both. When both are set, the

    timestamp field will be used, the textual field will be discarded.

    In addition, the textual field, when used as input, allows for a number of shortcuts that get converted into

    timestamps:

    - "now": converted to the current timestamp at the time of the request

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    timestampgoogle.protobuf.Timestamp

    time_zonestring

    textualstring

    + + + + + +

    UpdateBoolean

    +

    Update object for a boolean.

    Since false is the default value, we need to distinguish between an omitted value and setting the value to false,

    in an update object.

    To use this to update, set a value and set updated to true

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    updatedbool

    valuebool

    + + + + + +

    UpdateClearableString

    +

    Update object for a string that can be empty.

    Since an empty string is also the default value, we need to distinguish between an omitted value and

    setting the value to an empty string, in an update object.

    To use this to update, set a value and set updated to true

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    updatedbool

    valuestring

    + + + + + +

    UpdateOptionalDuration

    +

    Update object for an optional Duration.

    To use this to update, set a value and set updated to true.

    To clear the duration, set updated to true, but set no value.

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    updatedbool

    valueDuration

    + + + + + +

    UpdateOptionalId

    +

    Update object for an optional id.

    To use this to update, set a value and set updated to true. To clear the id, set updated to true, but set no value.

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    updatedbool

    valueint64

    + + + + + +

    UpdateZeroableInt

    +

    Update object for an int that can be set to 0.

    Since 0 is also the default value, we need to distinguish between an omitted value and setting the value to 0,

    in an update object.

    To use this to update, set a value and set updated to true

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    updatedbool

    valueuint32

    + + + + + + + +

    EventType

    +

    Enum of api-accessible events.

    The event types in this enum have a protobuf implementation, and can be used, for example, in the

    api event stream and publishers.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    DEFAULT0

    ORGANIZATION_CREATED34

    ORGANIZATION_UPDATED12

    ORGANIZATION_DELETED35

    ORGANIZATION_EVENT_CONFIGURATION_UPDATED43

    MODEM_CREATED55

    MODEM_UPDATED36

    MODEM_LOCATION_UPDATED4

    MODEM_ACTIVATED33

    MODEM_MESSAGE_RECEIVED5

    MODEM_MESSAGE_BODY_PARSED39

    MODEM_MESSAGE_BODY_RECEIVED45

    MODEM_MESSAGE_CANNOT_BE_PARSED15

    MODEM_MESSAGE_SUMMARY42

    MODEM_MESSAGE_BODY_PARSER_CREATED46

    MODEM_MESSAGE_BODY_PARSER_UPDATED47

    MODEM_MESSAGE_BODY_PARSER_DELETED48

    MODEM_ALARM56

    MODEM_ALARM_CREATED57

    MODEM_ALARM_UPDATED58

    MODEM_ALARM_DELETED59

    ASSIGNED63

    UNASSIGNED64

    MODEM_TRANSFER_STARTED17

    MODEM_TRANSFER_RECEIVED18

    MODEM_TRANSFER_CANCELLED19

    MODEM_TRANSFER_NOT_RECEIVED20

    MODEM_TRANSFER_RETURN_TRANSFER_STARTED21

    MODEM_CLAIMED22

    PUBLISHER_CREATED1

    PUBLISHER_UPDATED2

    PUBLISHER_DELETED3

    PUBLISHER_AUTO_DISABLED37

    PUBLISHER_FAILED11

    USER_ACCESS_REQUEST8

    USER_INVITED38

    USER_ADDED9

    USER_REMOVED10

    USER_VALIDATION_UPDATED54

    TOKEN_CREATED31

    TOKEN_EXPIRY_WARNING25

    TOKEN_EXPIRED26

    TOKEN_DELETED32

    EXPORT_CREATED65

    EXPORT_READY66

    EXPORT_FAILED67

    + +

    Health

    +

    Health is an indicator for issues. It is used for publishers to give a quick indication of issues.

    + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    OK0

    WARNING1

    ERROR2

    + +

    UnitOfMeasurement

    +

    Unit of measurement for a numeric value.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    UNIT_UNKNOWN0

    DURATION_MILLISECONDS40

    DURATION_SECONDS1

    DURATION_MINUTES2

    DURATION_HOURS3

    DURATION_DAYS4

    DURATION_WEEKS41

    FUEL_EFFICIENCY_LITER_PER_100_KILOMETER30

    FUEL_EFFICIENCY_KILOMETER_PER_LITER31

    FUEL_EFFICIENCY_KILOMETER_PER_US_GALLON32

    FUEL_EFFICIENCY_KILOMETER_PER_IMPERIAL_GALLON33

    FUEL_EFFICIENCY_MILE_PER_US_GALLON34

    FUEL_EFFICIENCY_MILE_PER_IMPERIAL_GALLON35

    FUEL_EFFICIENCY_MILE_PER_LITER36

    DISTANCE_METER8

    DISTANCE_MILLIMETER9

    DISTANCE_CENTIMETER10

    DISTANCE_KILOMETER11

    DISTANCE_NAUTICAL_MILE26

    DISTANCE_MILE21

    DISTANCE_YARD27

    DISTANCE_FOOT28

    DISTANCE_INCH29

    PERCENT16

    PRESSURE_BAR12

    PRESSURE_PSI14

    PRESSURE_K_PA17

    SPEED_KILOMETERS_PER_HOUR18

    SPEED_KNOTS19

    SPEED_METERS_PER_SECOND20

    SPEED_MILES_PER_HOUR22

    TEMPERATURE_KELVIN5

    TEMPERATURE_DEGREES_CELSIUS6

    TEMPERATURE_DEGREES_FAHRENHEIT7

    VOLTAGE_MILLIVOLT15

    VOLUME_LITER23

    VOLUME_GALLON_US24

    VOLUME_GALLON_IMPERIAL25

    VOLUME_CUBIC_METER42

    VOLUME_CUBIC_FOOT43

    MASS_KILOGRAMS37

    MASS_POUNDS38

    FLOW_CUBIC_METERS_PER_HOUR39

    + + + + + + + +

    Scalar Value Types

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    .proto TypeNotesC++JavaPythonGoC#PHPRuby
    doubledoubledoublefloatfloat64doublefloatFloat
    floatfloatfloatfloatfloat32floatfloatFloat
    int32Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.int32intintint32intintegerBignum or Fixnum (as required)
    int64Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.int64longint/longint64longinteger/stringBignum
    uint32Uses variable-length encoding.uint32intint/longuint32uintintegerBignum or Fixnum (as required)
    uint64Uses variable-length encoding.uint64longint/longuint64ulonginteger/stringBignum or Fixnum (as required)
    sint32Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.int32intintint32intintegerBignum or Fixnum (as required)
    sint64Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.int64longint/longint64longinteger/stringBignum
    fixed32Always four bytes. More efficient than uint32 if values are often greater than 2^28.uint32intintuint32uintintegerBignum or Fixnum (as required)
    fixed64Always eight bytes. More efficient than uint64 if values are often greater than 2^56.uint64longint/longuint64ulonginteger/stringBignum
    sfixed32Always four bytes.int32intintint32intintegerBignum or Fixnum (as required)
    sfixed64Always eight bytes.int64longint/longint64longinteger/stringBignum
    boolboolbooleanbooleanboolboolbooleanTrueClass/FalseClass
    stringA string must always contain UTF-8 encoded or 7-bit ASCII text.stringStringstr/unicodestringstringstringString (UTF-8)
    bytesMay contain any arbitrary sequence of bytes.stringByteStringstr[]byteByteStringstringString (ASCII-8BIT)
    + + + diff --git a/docs/html/values.html b/docs/html/values.html index 01111ab..82ac948 100644 --- a/docs/html/values.html +++ b/docs/html/values.html @@ -349,6 +349,10 @@

    Table of Contents

    MFilter.Events.Update +
  • + MFilter.FieldEnumValues +
    • +
  • MFilter.Modems
    • @@ -2084,6 +2088,44 @@

    Filter.Events.Update

    +

    Filter.FieldEnumValues

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    fieldstring

    includestringrepeated

    excludestringrepeated

    + + + + +

    Filter.Modems

    diff --git a/docs/html/webhook.html b/docs/html/webhook.html index 95c30b0..cb59cc3 100644 --- a/docs/html/webhook.html +++ b/docs/html/webhook.html @@ -452,6 +452,10 @@

    Table of Contents

    MFilter.Events.Update +
  • + MFilter.FieldEnumValues +
    • +
  • MFilter.Modems
    • @@ -3197,6 +3201,44 @@

    Filter.Events.Update

    +

    Filter.FieldEnumValues

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    fieldstring

    includestringrepeated

    excludestringrepeated

    + + + + +

    Filter.Modems

    diff --git a/docs/md/assignment.md b/docs/md/assignment.md index faf0b41..5de4bdc 100644 --- a/docs/md/assignment.md +++ b/docs/md/assignment.md @@ -177,6 +177,7 @@ - [hiber.Filter.ChildOrganizations.Update](#hiberfilterchildorganizationsupdate) - [hiber.Filter.Events](#hiberfilterevents) - [hiber.Filter.Events.Update](#hiberfiltereventsupdate) + - [hiber.Filter.FieldEnumValues](#hiberfilterfieldenumvalues) - [hiber.Filter.Modems](#hiberfiltermodems) - [hiber.Filter.Modems.Update](#hiberfiltermodemsupdate) - [hiber.Filter.OrganizationPermissions](#hiberfilterorganizationpermissions) @@ -2026,6 +2027,16 @@ Update object to update a Filter.Events field. | updated | [ bool](#bool) | none | | value | [ hiber.Filter.Events](#hiberfilterevents) | none | +### hiber.Filter.FieldEnumValues + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| field | [ string](#string) | none | +| include | [repeated string](#string) | none | +| exclude | [repeated string](#string) | none | + ### hiber.Filter.Modems diff --git a/docs/md/easypulse.md b/docs/md/easypulse.md index e95fcb9..2411e80 100644 --- a/docs/md/easypulse.md +++ b/docs/md/easypulse.md @@ -78,6 +78,7 @@ somewhat customized Asset model. - [hiber.Filter.ChildOrganizations.Update](#hiberfilterchildorganizationsupdate) - [hiber.Filter.Events](#hiberfilterevents) - [hiber.Filter.Events.Update](#hiberfiltereventsupdate) + - [hiber.Filter.FieldEnumValues](#hiberfilterfieldenumvalues) - [hiber.Filter.Modems](#hiberfiltermodems) - [hiber.Filter.Modems.Update](#hiberfiltermodemsupdate) - [hiber.Filter.OrganizationPermissions](#hiberfilterorganizationpermissions) @@ -423,6 +424,7 @@ A target value that measures fuel efficiency. | selection | [ Easypulse.AssetSelection](#easypulseassetselection) | Select the Assets to return. | | pagination | [ hiber.Pagination](#hiberpagination) | Paginate over the returned Assets. | | sort | [ Easypulse.ListAssets.Request.Sort](#easypulselistassetsrequestsort) | Sort the returned assets using the given option. By default, Assets are sorted by name. | +| apply_unit_preferences | [ bool](#bool) | Whether to apply the unit preferences to the fields. This will convert any fields into your preferred unit, for convenience. | ### Easypulse.TargetValues.List.Response @@ -541,6 +543,8 @@ Options to aggregate the history data points (in a group). | AVERAGE | Average value of all history data points (in a group). | 1 | | SUM | Sum all history data points (in a group). | 2 | | LAST | Just take the last value (in a group). | 3 | +| MINIMUM | Take the lowest value (in a group). | 4 | +| MAXIMUM | Take the highest value (in a group). | 5 | ### Easypulse.History.Request.Sort How to sort the returned values. @@ -863,6 +867,16 @@ Update object to update a Filter.Events field. | updated | [ bool](#bool) | none | | value | [ hiber.Filter.Events](#hiberfilterevents) | none | +### hiber.Filter.FieldEnumValues + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| field | [ string](#string) | none | +| include | [repeated string](#string) | none | +| exclude | [repeated string](#string) | none | + ### hiber.Filter.Modems diff --git a/docs/md/event.md b/docs/md/event.md index d2f8760..8353e33 100644 --- a/docs/md/event.md +++ b/docs/md/event.md @@ -156,6 +156,7 @@ - [hiber.Filter.ChildOrganizations.Update](#hiberfilterchildorganizationsupdate) - [hiber.Filter.Events](#hiberfilterevents) - [hiber.Filter.Events.Update](#hiberfiltereventsupdate) + - [hiber.Filter.FieldEnumValues](#hiberfilterfieldenumvalues) - [hiber.Filter.Modems](#hiberfiltermodems) - [hiber.Filter.Modems.Update](#hiberfiltermodemsupdate) - [hiber.Filter.OrganizationPermissions](#hiberfilterorganizationpermissions) @@ -2263,6 +2264,16 @@ Update object to update a Filter.Events field. | updated | [ bool](#bool) | none | | value | [ hiber.Filter.Events](#hiberfilterevents) | none | +### hiber.Filter.FieldEnumValues + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| field | [ string](#string) | none | +| include | [repeated string](#string) | none | +| exclude | [repeated string](#string) | none | + ### hiber.Filter.Modems diff --git a/docs/md/field_service.md b/docs/md/field_service.md index 63c084b..69771fa 100644 --- a/docs/md/field_service.md +++ b/docs/md/field_service.md @@ -16,6 +16,10 @@ - [ListFields](#listfields) - [ListFields.Request](#listfieldsrequest) - [ListFields.Response](#listfieldsresponse) + - [ListFieldsForModem](#listfieldsformodem) + - [ListFieldsForModem.Request](#listfieldsformodemrequest) + - [ListFieldsForModem.Response](#listfieldsformodemresponse) + - [ListFieldsForModem.Response.ModemWithFields](#listfieldsformodemresponsemodemwithfields) - [ReplaceAllFieldsRequest](#replaceallfieldsrequest) - [UpdateFieldEnumValues](#updatefieldenumvalues) - [UpdateFieldEnumValues.Request](#updatefieldenumvaluesrequest) @@ -90,6 +94,12 @@ +### ForModem +> **rpc** ForModem([ListFieldsForModem.Request](#listfieldsformodemrequest)) + [ListFieldsForModem.Response](#listfieldsformodemresponse) + + + ### Add > **rpc** Add([AddFieldsRequest](#addfieldsrequest)) [.hiber.modem.message.bodyparser.ModemMessageBodyParser](#hibermodemmessagebodyparsermodemmessagebodyparser) @@ -176,7 +186,7 @@ Delete the given fields from a parser. | selection | [ FieldSelection](#fieldselection) | Select which fields to return. | | pagination | [ hiber.Pagination](#hiberpagination) | none | | sort | [ ListFields.Sort](#listfieldssort) | none | -| apply_unit_preferences | [ bool](#bool) | Whether to apply the unit preferences to the fields. This will convert any fields into you preferred unit, for convenience. | +| apply_unit_preferences | [ bool](#bool) | Whether to apply the unit preferences to the fields. This will convert any fields into your preferred unit, for convenience. | ### ListFields.Response @@ -188,6 +198,45 @@ Delete the given fields from a parser. | request | [ ListFields.Request](#listfieldsrequest) | none | | pagination | [ hiber.Pagination.Result](#hiberpaginationresult) | none | +### ListFieldsForModem + + + + +### ListFieldsForModem.Request + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| modem_selection | [ hiber.modem.ModemSelection](#hibermodemmodemselection) | Select the modems to fetch the fields for. | +| field_selection | [ FieldSelection](#fieldselection) | Select which fields to return. | +| pagination | [ hiber.Pagination](#hiberpagination) | none | +| sort | [ ListFields.Sort](#listfieldssort) | none | +| apply_unit_preferences | [ bool](#bool) | Whether to apply the unit preferences to the fields. This will convert any fields into you preferred unit, for convenience. | +| include_total | [ bool](#bool) | Whether to also calculate the total fields for all selected modems, and return them as a single list in the response. This can be useful to display table columns, for example. | + +### ListFieldsForModem.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| modem_fields | [repeated ListFieldsForModem.Response.ModemWithFields](#listfieldsformodemresponsemodemwithfields) | none | +| request | [ ListFieldsForModem.Request](#listfieldsformodemrequest) | none | +| pagination | [ hiber.Pagination.Result](#hiberpaginationresult) | none | +| total | [repeated Field](#field) | A merged result of all fields, for all modems. This can be useful to display table columns, for example. | + +### ListFieldsForModem.Response.ModemWithFields + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| modem | [ string](#string) | none | +| fields | [repeated Field](#field) | none | + ### ReplaceAllFieldsRequest Replace all fields for a parser with the fields given. @@ -262,6 +311,7 @@ Replace all fields for a parser with the fields given. | display_name | [ hiber.UpdateClearableString](#hiberupdateclearablestring) | An optional display name for the field. | | priority | [ hiber.UpdateZeroableInt](#hiberupdatezeroableint) | Priority of the field, typically used for ordering. | | encrypted | [ hiber.UpdateBoolean](#hiberupdateboolean) | Whether this field should be stored encrypted or not. When set to true at a later point, earlier values are not encrypted retro-actively. | +| optional | [ hiber.UpdateBoolean](#hiberupdateboolean) | Whether this field is optional or not. | | [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **update_details**.numeric | [ UpdateFieldNumericDetails](#updatefieldnumericdetails) | none | | [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **update_details**.enum | [ UpdateFieldEnumValues](#updatefieldenumvalues) | none | @@ -299,6 +349,7 @@ so not all messages listed here are referenced.) | [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **details**.numeric | [ hiber.field.Field.Numeric](#hiberfieldfieldnumeric) | none | | [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **details**.enum | [ hiber.field.Field.Enum](#hiberfieldfieldenum) | none | | encrypted | [ bool](#bool) | Whether this field should be stored encrypted or not. If it is, some processing options may be unavailable or slower. | +| optional | [ bool](#bool) | Whether this field should be validated from the parser output. | | unit_of_measurement | [ hiber.UnitOfMeasurement](#hiberunitofmeasurement) | If numeric, the unit of the field. Deprecated: use numeric.numeric_unit oneof instead | | unit_symbol | [ string](#string) | The symbol for the unit. Deprecated: use numeric.symbol instead | diff --git a/docs/md/map.md b/docs/md/map.md index 50cf5af..fbfe7d3 100644 --- a/docs/md/map.md +++ b/docs/md/map.md @@ -88,6 +88,7 @@ a controlled amount of groups. - [hiber.Filter.ChildOrganizations.Update](#hiberfilterchildorganizationsupdate) - [hiber.Filter.Events](#hiberfilterevents) - [hiber.Filter.Events.Update](#hiberfiltereventsupdate) + - [hiber.Filter.FieldEnumValues](#hiberfilterfieldenumvalues) - [hiber.Filter.Modems](#hiberfiltermodems) - [hiber.Filter.Modems.Update](#hiberfiltermodemsupdate) - [hiber.Filter.OrganizationPermissions](#hiberfilterorganizationpermissions) @@ -429,6 +430,16 @@ Update object to update a Filter.Events field. | updated | [ bool](#bool) | none | | value | [ hiber.Filter.Events](#hiberfilterevents) | none | +### hiber.Filter.FieldEnumValues + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| field | [ string](#string) | none | +| include | [repeated string](#string) | none | +| exclude | [repeated string](#string) | none | + ### hiber.Filter.Modems diff --git a/docs/md/modem.md b/docs/md/modem.md index 66da4ba..ffb70b1 100644 --- a/docs/md/modem.md +++ b/docs/md/modem.md @@ -86,6 +86,7 @@ used to identify them. - [hiber.Filter.ChildOrganizations.Update](#hiberfilterchildorganizationsupdate) - [hiber.Filter.Events](#hiberfilterevents) - [hiber.Filter.Events.Update](#hiberfiltereventsupdate) + - [hiber.Filter.FieldEnumValues](#hiberfilterfieldenumvalues) - [hiber.Filter.Modems](#hiberfiltermodems) - [hiber.Filter.Modems.Update](#hiberfiltermodemsupdate) - [hiber.Filter.OrganizationPermissions](#hiberfilterorganizationpermissions) @@ -1028,6 +1029,16 @@ Update object to update a Filter.Events field. | updated | [ bool](#bool) | none | | value | [ hiber.Filter.Events](#hiberfilterevents) | none | +### hiber.Filter.FieldEnumValues + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| field | [ string](#string) | none | +| include | [repeated string](#string) | none | +| exclude | [repeated string](#string) | none | + ### hiber.Filter.Modems diff --git a/docs/md/modem_alarm.md b/docs/md/modem_alarm.md index 89d43d0..201e199 100644 --- a/docs/md/modem_alarm.md +++ b/docs/md/modem_alarm.md @@ -99,6 +99,7 @@ advanced use cases, like assigning to a tag. - [hiber.Filter.ChildOrganizations.Update](#hiberfilterchildorganizationsupdate) - [hiber.Filter.Events](#hiberfilterevents) - [hiber.Filter.Events.Update](#hiberfiltereventsupdate) + - [hiber.Filter.FieldEnumValues](#hiberfilterfieldenumvalues) - [hiber.Filter.Modems](#hiberfiltermodems) - [hiber.Filter.Modems.Update](#hiberfiltermodemsupdate) - [hiber.Filter.OrganizationPermissions](#hiberfilterorganizationpermissions) @@ -1153,6 +1154,16 @@ Update object to update a Filter.Events field. | updated | [ bool](#bool) | none | | value | [ hiber.Filter.Events](#hiberfilterevents) | none | +### hiber.Filter.FieldEnumValues + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| field | [ string](#string) | none | +| include | [repeated string](#string) | none | +| exclude | [repeated string](#string) | none | + ### hiber.Filter.Modems diff --git a/docs/md/modem_message_body_parser.md b/docs/md/modem_message_body_parser.md index 699137a..768c99c 100644 --- a/docs/md/modem_message_body_parser.md +++ b/docs/md/modem_message_body_parser.md @@ -86,6 +86,7 @@ where you can find documentation, examples and a web IDE. - [hiber.Filter.ChildOrganizations.Update](#hiberfilterchildorganizationsupdate) - [hiber.Filter.Events](#hiberfilterevents) - [hiber.Filter.Events.Update](#hiberfiltereventsupdate) + - [hiber.Filter.FieldEnumValues](#hiberfilterfieldenumvalues) - [hiber.Filter.Modems](#hiberfiltermodems) - [hiber.Filter.Modems.Update](#hiberfiltermodemsupdate) - [hiber.Filter.OrganizationPermissions](#hiberfilterorganizationpermissions) @@ -925,6 +926,16 @@ Update object to update a Filter.Events field. | updated | [ bool](#bool) | none | | value | [ hiber.Filter.Events](#hiberfilterevents) | none | +### hiber.Filter.FieldEnumValues + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| field | [ string](#string) | none | +| include | [repeated string](#string) | none | +| exclude | [repeated string](#string) | none | + ### hiber.Filter.Modems diff --git a/docs/md/named_location.md b/docs/md/named_location.md index 52e2930..cfefde3 100644 --- a/docs/md/named_location.md +++ b/docs/md/named_location.md @@ -43,6 +43,7 @@ - [hiber.Filter.ChildOrganizations.Update](#hiberfilterchildorganizationsupdate) - [hiber.Filter.Events](#hiberfilterevents) - [hiber.Filter.Events.Update](#hiberfiltereventsupdate) + - [hiber.Filter.FieldEnumValues](#hiberfilterfieldenumvalues) - [hiber.Filter.Modems](#hiberfiltermodems) - [hiber.Filter.Modems.Update](#hiberfiltermodemsupdate) - [hiber.Filter.OrganizationPermissions](#hiberfilterorganizationpermissions) @@ -426,6 +427,16 @@ Update object to update a Filter.Events field. | updated | [ bool](#bool) | none | | value | [ hiber.Filter.Events](#hiberfilterevents) | none | +### hiber.Filter.FieldEnumValues + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| field | [ string](#string) | none | +| include | [repeated string](#string) | none | +| exclude | [repeated string](#string) | none | + ### hiber.Filter.Modems diff --git a/docs/md/unit_preferences_service.md b/docs/md/unit_preferences_service.md index ddf4124..fbdf11f 100644 --- a/docs/md/unit_preferences_service.md +++ b/docs/md/unit_preferences_service.md @@ -266,6 +266,7 @@ so not all messages listed here are referenced.) | [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **details**.numeric | [ hiber.field.Field.Numeric](#hiberfieldfieldnumeric) | none | | [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **details**.enum | [ hiber.field.Field.Enum](#hiberfieldfieldenum) | none | | encrypted | [ bool](#bool) | Whether this field should be stored encrypted or not. If it is, some processing options may be unavailable or slower. | +| optional | [ bool](#bool) | Whether this field should be validated from the parser output. | | unit_of_measurement | [ hiber.UnitOfMeasurement](#hiberunitofmeasurement) | If numeric, the unit of the field. Deprecated: use numeric.numeric_unit oneof instead | | unit_symbol | [ string](#string) | The symbol for the unit. Deprecated: use numeric.symbol instead | diff --git a/docs/md/value_service.md b/docs/md/value_service.md new file mode 100644 index 0000000..bd1d07f --- /dev/null +++ b/docs/md/value_service.md @@ -0,0 +1,1404 @@ +# value_service.proto + +Service to fetch time series data from our system. + +Time series data is produced by the device and sent in the form of messages. +Messages are parsed to a number of values (depending on the parser), which can be retrieved using this service. + +#### This file was generated from [value_service.proto](https://github.com/HiberGlobal/api/blob/master/value_service.proto). + +## Table of Contents + +- Services + - [ValueService](#valueservice) + +- Messages + - [AggregatedValues](#aggregatedvalues) + - [AggregatedValues.Request](#aggregatedvaluesrequest) + - [AggregatedValues.Request.AggregationsEntry](#aggregatedvaluesrequestaggregationsentry) + - [AggregatedValues.Request.Partition](#aggregatedvaluesrequestpartition) + - [AggregatedValues.Request.TransformFieldsEntry](#aggregatedvaluesrequesttransformfieldsentry) + - [AggregatedValues.Response](#aggregatedvaluesresponse) + - [ListValues](#listvalues) + - [ListValues.Request](#listvaluesrequest) + - [ListValues.Request.TransformFieldsEntry](#listvaluesrequesttransformfieldsentry) + - [ListValues.Response](#listvaluesresponse) + - [ValueContext](#valuecontext) + - [ValueContext.ValueDelta](#valuecontextvaluedelta) + - [ValueContext.ValueDuration](#valuecontextvalueduration) + - [ValueContext.ValueDurations](#valuecontextvaluedurations) + - [ValueSelection](#valueselection) + +- Enums + - [ListValues.Sort](#listvaluessort) + - [ValueAggregation](#valueaggregation) + - [ValueTransformation](#valuetransformation) + +- Referenced messages from [value.proto](#referenced-messages-from-valueproto) + - [hiber.value.Value](#hibervaluevalue) + - [hiber.value.Value.Enum](#hibervaluevalueenum) + - [hiber.value.Value.Numeric](#hibervaluevaluenumeric) + - [hiber.value.Value.Numeric.BatteryLevel](#hibervaluevaluenumericbatterylevel) + - [hiber.value.Value.Numeric.Distance](#hibervaluevaluenumericdistance) + - [hiber.value.Value.Numeric.Flow](#hibervaluevaluenumericflow) + - [hiber.value.Value.Numeric.FuelEfficiency](#hibervaluevaluenumericfuelefficiency) + - [hiber.value.Value.Numeric.Mass](#hibervaluevaluenumericmass) + - [hiber.value.Value.Numeric.Percentage](#hibervaluevaluenumericpercentage) + - [hiber.value.Value.Numeric.Pressure](#hibervaluevaluenumericpressure) + - [hiber.value.Value.Numeric.Speed](#hibervaluevaluenumericspeed) + - [hiber.value.Value.Numeric.Temperature](#hibervaluevaluenumerictemperature) + - [hiber.value.Value.Numeric.Voltage](#hibervaluevaluenumericvoltage) + - [hiber.value.Value.Numeric.Volume](#hibervaluevaluenumericvolume) + + - [hiber.value.Value.Numeric.BatteryLevel.Unit](#hibervaluevaluenumericbatterylevelunit) + - [hiber.value.Value.Numeric.Distance.Unit](#hibervaluevaluenumericdistanceunit) + - [hiber.value.Value.Numeric.DurationUnit](#hibervaluevaluenumericdurationunit) + - [hiber.value.Value.Numeric.Flow.Unit](#hibervaluevaluenumericflowunit) + - [hiber.value.Value.Numeric.FuelEfficiency.Unit](#hibervaluevaluenumericfuelefficiencyunit) + - [hiber.value.Value.Numeric.Mass.Unit](#hibervaluevaluenumericmassunit) + - [hiber.value.Value.Numeric.Percentage.Unit](#hibervaluevaluenumericpercentageunit) + - [hiber.value.Value.Numeric.Pressure.Unit](#hibervaluevaluenumericpressureunit) + - [hiber.value.Value.Numeric.Speed.Unit](#hibervaluevaluenumericspeedunit) + - [hiber.value.Value.Numeric.Temperature.Unit](#hibervaluevaluenumerictemperatureunit) + - [hiber.value.Value.Numeric.Type](#hibervaluevaluenumerictype) + - [hiber.value.Value.Numeric.Voltage.Unit](#hibervaluevaluenumericvoltageunit) + - [hiber.value.Value.Numeric.Volume.Unit](#hibervaluevaluenumericvolumeunit) + - [hiber.value.Value.Type](#hibervaluevaluetype) + +- Referenced messages from [modem.proto](#referenced-messages-from-modemproto) + - [hiber.modem.Modem](#hibermodemmodem) + - [hiber.modem.ModemSelection](#hibermodemmodemselection) + + - [hiber.modem.ListModemsRequest.Sort](#hibermodemlistmodemsrequestsort) + - [hiber.modem.Modem.Peripherals.HiberAntenna](#hibermodemmodemperipheralshiberantenna) + - [hiber.modem.Modem.Status](#hibermodemmodemstatus) + - [hiber.modem.Modem.Transfer.Status](#hibermodemmodemtransferstatus) + - [hiber.modem.Modem.Type](#hibermodemmodemtype) + - [hiber.modem.ModemMessage.Source](#hibermodemmodemmessagesource) + +- Referenced messages from [base.proto](#referenced-messages-from-baseproto) + - [hiber.Area](#hiberarea) + - [hiber.Avatar](#hiberavatar) + - [hiber.BytesOrHex](#hiberbytesorhex) + - [hiber.BytesOrHex.Update](#hiberbytesorhexupdate) + - [hiber.Date](#hiberdate) + - [hiber.DoubleRange](#hiberdoublerange) + - [hiber.Duration](#hiberduration) + - [hiber.Filter](#hiberfilter) + - [hiber.Filter.ChildOrganizations](#hiberfilterchildorganizations) + - [hiber.Filter.ChildOrganizations.Update](#hiberfilterchildorganizationsupdate) + - [hiber.Filter.Events](#hiberfilterevents) + - [hiber.Filter.Events.Update](#hiberfiltereventsupdate) + - [hiber.Filter.FieldEnumValues](#hiberfilterfieldenumvalues) + - [hiber.Filter.Modems](#hiberfiltermodems) + - [hiber.Filter.Modems.Update](#hiberfiltermodemsupdate) + - [hiber.Filter.OrganizationPermissions](#hiberfilterorganizationpermissions) + - [hiber.Filter.Organizations](#hiberfilterorganizations) + - [hiber.Filter.Publishers](#hiberfilterpublishers) + - [hiber.Filter.Tags](#hiberfiltertags) + - [hiber.Filter.Tags.Update](#hiberfiltertagsupdate) + - [hiber.Filter.UserPermissions](#hiberfilteruserpermissions) + - [hiber.Filter.Users](#hiberfilterusers) + - [hiber.Filter.Webhooks](#hiberfilterwebhooks) + - [hiber.Location](#hiberlocation) + - [hiber.LocationSelection](#hiberlocationselection) + - [hiber.NamedFile](#hibernamedfile) + - [hiber.Pagination](#hiberpagination) + - [hiber.Pagination.Result](#hiberpaginationresult) + - [hiber.Shape](#hibershape) + - [hiber.TimeRange](#hibertimerange) + - [hiber.Timestamp](#hibertimestamp) + - [hiber.UpdateBoolean](#hiberupdateboolean) + - [hiber.UpdateClearableString](#hiberupdateclearablestring) + - [hiber.UpdateOptionalDuration](#hiberupdateoptionalduration) + - [hiber.UpdateOptionalId](#hiberupdateoptionalid) + - [hiber.UpdateZeroableInt](#hiberupdatezeroableint) + - Enums + - [hiber.EventType](#hibereventtype) + - [hiber.Health](#hiberhealth) + - [hiber.UnitOfMeasurement](#hiberunitofmeasurement) + +- [Scalar Value Types](#scalar-value-types) + + +## ValueService + + +### List +> **rpc** List([ListValues.Request](#listvaluesrequest)) + [ListValues.Response](#listvaluesresponse) + + + +### Aggregated +> **rpc** Aggregated([AggregatedValues.Request](#aggregatedvaluesrequest)) + [AggregatedValues.Response](#aggregatedvaluesresponse) + + + + +## Messages + +### AggregatedValues + +Aggregate values for a (set of) modem(s), filtering by field and time. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| time_range | [ hiber.TimeRange](#hibertimerange) | The time range that was aggregated. | +| values | [repeated ValueContext](#valuecontext) | The aggregated values for the requested fields. + +Timestamp is only set if the aggregation can return an exact data point: - if the aggregation would return an exact point: LAST, MAXIMUM, MINIMUM. - if the aggregation is applied to a single value, for a single field. | +| location | [ hiber.Location](#hiberlocation) | The last location in the time range. | + +### AggregatedValues.Request + +Request aggregated values, reducing the selected time range to a single value per field. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| selection | [ ValueSelection](#valueselection) | The values to return. | +| aggregations | [map AggregatedValues.Request.AggregationsEntry](#aggregatedvaluesrequestaggregationsentry) | The aggregations to use for the fields, resulting in a single value for each field. When an aggregation is not specified for a field, the default aggregation for that field type is used. + +Fields specified here must have been specified in the selection. | +| transform_fields | [map AggregatedValues.Request.TransformFieldsEntry](#aggregatedvaluesrequesttransformfieldsentry) | Transform the values for a field into a derived value. + +Fields specified here must have been specified in the selection. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **optional_partition**.partition | [ AggregatedValues.Request.Partition](#aggregatedvaluesrequestpartition) | Partition the time range and apply aggregation to each part. | + +### AggregatedValues.Request.AggregationsEntry + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| key | [ string](#string) | none | +| value | [ ValueAggregation](#valueaggregation) | none | + +### AggregatedValues.Request.Partition + +Partition the time range and apply aggregation to each part (instead of over all values in the time range). +If no partition is set, the aggregation returns a single value. + +For example: +- get the average value per day for a month +- get the sum of all values per hour in a day + +| Field | Type | Description | +| ----- | ---- | ----------- | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **partition**.split_by_duration | [ hiber.Duration](#hiberduration) | Split up the data in time block of the given size. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **partition**.reduce_to_max_size | [ uint32](#uint32) | Limit the results to the given amount of data points, applying the function to each chunk. | +| pagination | [ hiber.Pagination](#hiberpagination) | Paginate the returned partitions of the time range. | +| sort | [ ListValues.Sort](#listvaluessort) | How to sort the returned values. | +| exclude_empty | [ bool](#bool) | Exclude any partitions that do not have any data from response. This is especially useful when the amount of partitions exceeds your pagination size. | + +### AggregatedValues.Request.TransformFieldsEntry + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| key | [ string](#string) | none | +| value | [ ValueTransformation](#valuetransformation) | none | + +### AggregatedValues.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| aggregated_values | [repeated AggregatedValues](#aggregatedvalues) | none | +| pagination | [ hiber.Pagination.Result](#hiberpaginationresult) | none | +| request | [ AggregatedValues.Request](#aggregatedvaluesrequest) | none | + +### ListValues + +List values for a (set of) modem(s), filtering by field and time. + + +### ListValues.Request + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| selection | [ ValueSelection](#valueselection) | none | +| pagination | [ hiber.Pagination](#hiberpagination) | none | +| sort | [ ListValues.Sort](#listvaluessort) | none | +| transform_fields | [map ListValues.Request.TransformFieldsEntry](#listvaluesrequesttransformfieldsentry) | Transform the values for a field into a derived value. Fields specified here must have been specified in the selection. | + +### ListValues.Request.TransformFieldsEntry + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| key | [ string](#string) | none | +| value | [ ValueTransformation](#valuetransformation) | none | + +### ListValues.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| values | [repeated ValueContext](#valuecontext) | none | +| pagination | [ hiber.Pagination.Result](#hiberpaginationresult) | none | +| request | [ ListValues.Request](#listvaluesrequest) | none | + +### ValueContext + +A Value at a time, for a given modem and field. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| modem | [ string](#string) | none | +| field | [ string](#string) | none | +| time | [ hiber.Timestamp](#hibertimestamp) | The time for this value. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **value_type**.value | [ Value](#value) | The value at this time. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **value_type**.duration | [ ValueContext.ValueDurations](#valuecontextvaluedurations) | The value at this time. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **value_type**.delta | [ ValueContext.ValueDelta](#valuecontextvaluedelta) | The value at this time. | + +### ValueContext.ValueDelta + +The delta of a value: the difference between a value and the previous value. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| delta | [ Value](#value) | The delta of the two values. | +| current | [ Value](#value) | The value at this time. | +| previous | [ Value](#value) | The previous value to compare it with. | + +### ValueContext.ValueDuration + +The amount of time a field for a modem was in this value. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| value | [ Value](#value) | The value the duration is for. | +| duration | [ hiber.Duration](#hiberduration) | The aggregated duration the field was this value. | + +### ValueContext.ValueDurations + +The amount of time a field for a modem was at different values. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| durations | [repeated ValueContext.ValueDuration](#valuecontextvalueduration) | none | + +### ValueSelection + +Select the values to return. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| modems | [ hiber.modem.ModemSelection](#hibermodemmodemselection) | Select the modem(s) to get the values for. | +| fields | [repeated string](#string) | Get the values for the selected fields. | +| time_range | [ hiber.TimeRange](#hibertimerange) | The time to view the values for. | +| include_location | [ bool](#bool) | Include the location (which is not a field). | +| filter_enum_values | [repeated hiber.Filter.FieldEnumValues](#hiberfilterfieldenumvalues) | Filter the values for enum fields. | + + +## Enums +### ListValues.Sort +How to sort the values. + +| Name | Description | Number | +| ---- | ----------- | ------ | +| TIME_ASCENDING | none | 0 | +| TIME_DESCENDING | none | 1 | + +### ValueAggregation +Get the values for the selected field. + +There are a few limitations here: +- text fields can only use the LAST aggregation. +- enum fields support a subset of aggregations: + - DEFAULT and LAST return the last value. + - MINIMUM and MAXIMUM return the lowest or highest value (respectively) based on the enum value order. + - AVERAGE and SUM are not supported. + +- enum duration + +An enum example: +Field "status" with this timeline: 00:00 OK, 00:10 FAILED, 00:20 OK, 00:25 FAILED, 00:40 OK +- aggregation DEFAULT or LAST: OK, since it's OK at the end of the time range. +- aggregation SUM: OK: 35m, FAILED: 25m + +| Name | Description | Number | +| ---- | ----------- | ------ | +| DEFAULT | none | 0 | +| AVERAGE | Return the average value. Not supported for textual and enum fields. When used with these fields, LAST is used instead. | 1 | +| SUM | Return the sum all values. Not supported for textual and enum fields. When used with these fields, LAST is used instead. | 2 | +| LAST | Just take the last value. | 3 | +| MINIMUM | Return the lowest value. For enum fields, the order of values is used to determine the MINIMUM. Not supported for textual fields. When used with these fields, LAST is used instead. | 4 | +| MAXIMUM | Return the highest value. For enum fields, the order of values is used to determine the MAXIMUM. Not supported for textual fields. When used with these fields, LAST is used instead. | 5 | + +### ValueTransformation +Transform the values into a derived value. + +| Name | Description | Number | +| ---- | ----------- | ------ | +| DURATION | Instead of returning the value, return the amount of time a value was active. Aggregation (if applicable) is applied afterwards on the duration value. | 0 | +| DELTA | Instead of returning the value, return the difference between the value and the previous value. Aggregation (if applicable) is applied before the delta is calculated. | 1 | + + + +## Referenced messages from value.proto +(Note that these are included because there is a proto dependency on the file, +so not all messages listed here are referenced.) + +#### This section was generated from [value.proto](https://github.com/HiberGlobal/api/blob/master/value.proto). + + +### hiber.value.Value + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| type | [ hiber.value.Value.Type](#hibervaluevaluetype) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **value**.numeric | [ hiber.value.Value.Numeric](#hibervaluevaluenumeric) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **value**.text | [ string](#string) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **value**.enum | [ hiber.value.Value.Enum](#hibervaluevalueenum) | none | + +### hiber.value.Value.Enum + +If this value is an enum, this specifies the value, display name and color for this enum value. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| value | [ string](#string) | The enum value. This might be a cryptic value, see the display_name and description for more information. | +| display_name | [ string](#string) | User-facing name for this value. | +| description | [ string](#string) | More details for this enum value. | +| color | [ string](#string) | (Optional) color for this enum value. | +| priority | [ int32](#int32) | Priority of the value, typically used for ordering. | + +### hiber.value.Value.Numeric + +If the value is numeric, this specifies the unit, value, etc. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| type | [ hiber.value.Value.Numeric.Type](#hibervaluevaluenumerictype) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **value**.battery_level | [ hiber.value.Value.Numeric.BatteryLevel](#hibervaluevaluenumericbatterylevel) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **value**.distance | [ hiber.value.Value.Numeric.Distance](#hibervaluevaluenumericdistance) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **value**.duration | [ hiber.Duration](#hiberduration) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **value**.fuel_efficiency | [ hiber.value.Value.Numeric.FuelEfficiency](#hibervaluevaluenumericfuelefficiency) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **value**.percentage | [ hiber.value.Value.Numeric.Percentage](#hibervaluevaluenumericpercentage) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **value**.pressure | [ hiber.value.Value.Numeric.Pressure](#hibervaluevaluenumericpressure) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **value**.speed | [ hiber.value.Value.Numeric.Speed](#hibervaluevaluenumericspeed) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **value**.temperature | [ hiber.value.Value.Numeric.Temperature](#hibervaluevaluenumerictemperature) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **value**.voltage | [ hiber.value.Value.Numeric.Voltage](#hibervaluevaluenumericvoltage) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **value**.volume | [ hiber.value.Value.Numeric.Volume](#hibervaluevaluenumericvolume) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **value**.mass | [ hiber.value.Value.Numeric.Mass](#hibervaluevaluenumericmass) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **value**.flow | [ hiber.value.Value.Numeric.Flow](#hibervaluevaluenumericflow) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **value**.unknown | [ double](#double) | none | + +### hiber.value.Value.Numeric.BatteryLevel + +Special case for battery level, since it can be provided in many units. +Not included in the UnitPreferences, since it cannot be converted. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| value | [ double](#double) | none | +| unit | [ hiber.value.Value.Numeric.BatteryLevel.Unit](#hibervaluevaluenumericbatterylevelunit) | none | +| textual | [ string](#string) | Textual representation including unit symbol, rounded based on the user preferences and field config. | +| converted_from | [ hiber.value.Value.Numeric.BatteryLevel.Unit](#hibervaluevaluenumericbatterylevelunit) | The original unit, iff this value was converted from another unit because of user preferences. | + +### hiber.value.Value.Numeric.Distance + +The value is a distance value, converted to your preferred distance unit. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| value | [ double](#double) | none | +| unit | [ hiber.value.Value.Numeric.Distance.Unit](#hibervaluevaluenumericdistanceunit) | none | +| textual | [ string](#string) | Textual representation including unit symbol, rounded based on the user preferences and field config. | +| converted_from | [ hiber.value.Value.Numeric.Distance.Unit](#hibervaluevaluenumericdistanceunit) | The original unit, iff this value was converted from another unit because of user preferences. | + +### hiber.value.Value.Numeric.Flow + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| value | [ double](#double) | none | +| unit | [ hiber.value.Value.Numeric.Flow.Unit](#hibervaluevaluenumericflowunit) | none | +| textual | [ string](#string) | Textual representation including unit symbol, rounded based on the user preferences and field config. | +| converted_from | [ hiber.value.Value.Numeric.Flow.Unit](#hibervaluevaluenumericflowunit) | The original unit, iff this value was converted from another unit because of user preferences. | + +### hiber.value.Value.Numeric.FuelEfficiency + +The value is a distance value, converted to your preferred distance unit. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| value | [ double](#double) | none | +| unit | [ hiber.value.Value.Numeric.FuelEfficiency.Unit](#hibervaluevaluenumericfuelefficiencyunit) | none | +| textual | [ string](#string) | Textual representation including unit symbol, rounded based on the user preferences and field config. | +| converted_from | [ hiber.value.Value.Numeric.FuelEfficiency.Unit](#hibervaluevaluenumericfuelefficiencyunit) | The original unit, iff this value was converted from another unit because of user preferences. | + +### hiber.value.Value.Numeric.Mass + +The value is a volume value, converted to your preferred volume unit. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| value | [ double](#double) | none | +| unit | [ hiber.value.Value.Numeric.Mass.Unit](#hibervaluevaluenumericmassunit) | none | +| textual | [ string](#string) | Textual representation including unit symbol, rounded based on the user preferences and field config. | +| converted_from | [ hiber.value.Value.Numeric.Mass.Unit](#hibervaluevaluenumericmassunit) | The original unit, iff this value was converted from another unit because of user preferences. | + +### hiber.value.Value.Numeric.Percentage + +The value is a percentage. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| value | [ float](#float) | none | +| unit | [ hiber.value.Value.Numeric.Percentage.Unit](#hibervaluevaluenumericpercentageunit) | none | +| textual | [ string](#string) | Textual representation with % symbol, rounded based on the user preferences and field config. | + +### hiber.value.Value.Numeric.Pressure + +The value is a pressure value, converted to your preferred pressure unit. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| value | [ double](#double) | none | +| unit | [ hiber.value.Value.Numeric.Pressure.Unit](#hibervaluevaluenumericpressureunit) | none | +| textual | [ string](#string) | Textual representation including unit symbol, rounded based on the user preferences and field config. | +| converted_from | [ hiber.value.Value.Numeric.Pressure.Unit](#hibervaluevaluenumericpressureunit) | The original unit, iff this value was converted from another unit because of user preferences. | + +### hiber.value.Value.Numeric.Speed + +The value is a speed value, converted to your preferred speed unit. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| value | [ double](#double) | none | +| unit | [ hiber.value.Value.Numeric.Speed.Unit](#hibervaluevaluenumericspeedunit) | none | +| textual | [ string](#string) | Textual representation including unit symbol, rounded based on the user preferences and field config. | +| converted_from | [ hiber.value.Value.Numeric.Speed.Unit](#hibervaluevaluenumericspeedunit) | The original unit, iff this value was converted from another unit because of user preferences. | + +### hiber.value.Value.Numeric.Temperature + +The value is a temperature, converted to your preferred temperature unit. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| value | [ double](#double) | none | +| unit | [ hiber.value.Value.Numeric.Temperature.Unit](#hibervaluevaluenumerictemperatureunit) | none | +| textual | [ string](#string) | Textual representation including unit symbol, rounded based on the user preferences and field config. | +| converted_from | [ hiber.value.Value.Numeric.Temperature.Unit](#hibervaluevaluenumerictemperatureunit) | The original unit, iff this value was converted from another unit because of user preferences. | + +### hiber.value.Value.Numeric.Voltage + +The value is a voltage, converted to your preferred voltage unit. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| value | [ double](#double) | none | +| unit | [ hiber.value.Value.Numeric.Voltage.Unit](#hibervaluevaluenumericvoltageunit) | none | +| textual | [ string](#string) | Textual representation including unit symbol, rounded based on the user preferences and field config. | +| converted_from | [ hiber.value.Value.Numeric.Voltage.Unit](#hibervaluevaluenumericvoltageunit) | The original unit, iff this value was converted from another unit because of user preferences. | + +### hiber.value.Value.Numeric.Volume + +The value is a volume value, converted to your preferred volume unit. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| value | [ double](#double) | none | +| unit | [ hiber.value.Value.Numeric.Volume.Unit](#hibervaluevaluenumericvolumeunit) | none | +| textual | [ string](#string) | Textual representation including unit symbol, rounded based on the user preferences and field config. | +| converted_from | [ hiber.value.Value.Numeric.Volume.Unit](#hibervaluevaluenumericvolumeunit) | The original unit, iff this value was converted from another unit because of user preferences. | + + +### Enums +#### hiber.value.Value.Numeric.BatteryLevel.Unit + + +| Name | Description | Number | +| ---- | ----------- | ------ | +| PERCENT | Battery level as a percentage (technically not a unit). + +other units will be added here later, like voltage | 0 | + +#### hiber.value.Value.Numeric.Distance.Unit + + +| Name | Description | Number | +| ---- | ----------- | ------ | +| METER | none | 0 | +| MILLIMETER | none | 1 | +| CENTIMETER | none | 2 | +| KILOMETER | none | 3 | +| YARD | none | 5 | +| MILE | none | 4 | +| FOOT | none | 6 | +| INCH | none | 7 | +| NAUTICAL_MILE | This is a special case unit and may not be auto-converted to your UnitPreference. | 8 | + +#### hiber.value.Value.Numeric.DurationUnit +The duration enum is not wrapped in Duration, since duration is always returned as a normalize Duration. +This unit is still used for fields, however. + +| Name | Description | Number | +| ---- | ----------- | ------ | +| MILLISECONDS | none | 0 | +| SECONDS | none | 1 | +| MINUTES | none | 2 | +| HOURS | none | 3 | +| DAYS | none | 4 | +| WEEKS | none | 5 | + +#### hiber.value.Value.Numeric.Flow.Unit + + +| Name | Description | Number | +| ---- | ----------- | ------ | +| CUBIC_METER_PER_HOUR | none | 0 | + +#### hiber.value.Value.Numeric.FuelEfficiency.Unit + + +| Name | Description | Number | +| ---- | ----------- | ------ | +| LITER_PER_100_KILOMETER | none | 0 | +| KILOMETER_PER_LITER | none | 1 | +| KILOMETER_PER_GALLON | none | 2 | +| KILOMETER_PER_IMPERIAL_GALLON | none | 3 | +| MILE_PER_GALLON | none | 4 | +| MILE_PER_IMPERIAL_GALLON | none | 5 | +| MILE_PER_LITER | none | 6 | + +#### hiber.value.Value.Numeric.Mass.Unit + + +| Name | Description | Number | +| ---- | ----------- | ------ | +| KILOGRAMS | none | 0 | +| POUNDS | none | 1 | + +#### hiber.value.Value.Numeric.Percentage.Unit + + +| Name | Description | Number | +| ---- | ----------- | ------ | +| PERCENT | Technically not a unit, but for consistency, we've added it here. | 0 | + +#### hiber.value.Value.Numeric.Pressure.Unit + + +| Name | Description | Number | +| ---- | ----------- | ------ | +| BAR | none | 0 | +| PSI | none | 1 | +| K_PA | none | 2 | + +#### hiber.value.Value.Numeric.Speed.Unit + + +| Name | Description | Number | +| ---- | ----------- | ------ | +| KILOMETERS_PER_HOUR | none | 0 | +| KNOTS | This is a special case unit and may not be auto-converted to your UnitPreference. | 1 | +| METERS_PER_SECOND | none | 2 | +| MILES_PER_HOUR | none | 3 | + +#### hiber.value.Value.Numeric.Temperature.Unit + + +| Name | Description | Number | +| ---- | ----------- | ------ | +| KELVIN | none | 0 | +| DEGREES_CELSIUS | none | 1 | +| DEGREES_FAHRENHEIT | none | 2 | + +#### hiber.value.Value.Numeric.Type +The type of numeric value that is represented. +Supported types will automatically convert to the preferred unit (based on the user settings). + +| Name | Description | Number | +| ---- | ----------- | ------ | +| TYPE_UNKNOWN | none | 0 | +| PERCENTAGE | none | 1 | +| TEMPERATURE | none | 2 | +| DISTANCE | none | 3 | +| PRESSURE | none | 4 | +| VOLTAGE | none | 5 | +| SPEED | none | 6 | +| VOLUME | none | 7 | +| DURATION | none | 8 | +| FUEL_EFFICIENCY | none | 9 | +| MASS | none | 10 | +| BATTERY_LEVEL | none | 11 | +| FLOW | none | 12 | + +#### hiber.value.Value.Numeric.Voltage.Unit + + +| Name | Description | Number | +| ---- | ----------- | ------ | +| MILLIVOLT | none | 0 | + +#### hiber.value.Value.Numeric.Volume.Unit + + +| Name | Description | Number | +| ---- | ----------- | ------ | +| LITER | none | 0 | +| GALLON_US | none | 1 | +| GALLON_IMPERIAL | none | 2 | +| CUBIC_METER | none | 3 | +| CUBIC_FEET | none | 4 | + +#### hiber.value.Value.Type +The type of value that is represented. + +| Name | Description | Number | +| ---- | ----------- | ------ | +| OTHER | none | 0 | +| NUMERIC | This field contains numeric values, with an optional unit of measurement defined below. | 1 | +| TEXT | This field contains text to be displayed. | 2 | +| ENUM | This field switches between several predefined values. Typically used for status fields. | 3 | + + + +## Referenced messages from modem.proto +(Note that these are included because there is a proto dependency on the file, +so not all messages listed here are referenced.) + +#### This section was generated from [modem.proto](https://github.com/HiberGlobal/api/blob/master/modem.proto). + + +### hiber.modem.Modem + +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. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| number | [ string](#string) | An 8-character hexadecimal string | +| organization | [ string](#string) | none | +| name | [ string](#string) | An optional descriptor given to the modem | +| location | [ hiber.Location](#hiberlocation) | none | +| last_message_id | [ uint64](#uint64) | none | +| last_message_received_at | [ hiber.Timestamp](#hibertimestamp) | Time the server has received the last message. | +| last_message_sent_at | [ hiber.Timestamp](#hibertimestamp) | Time the modem has sent the last message. | +| last_message_body | [ hiber.BytesOrHex](#hiberbytesorhex) | The body of the last message. | +| inactivity | [ hiber.Duration](#hiberduration) | The amount of time since the last message from this modem was received on the server. | +| health | [ hiber.Health](#hiberhealth) | Deprecated health based on the number of error and warning events this modem has received in the past 30 days Uses the OK, WARNING, ERROR format. | +| health_level | [ hiber.health.HealthLevel](#hiberhealthhealthlevel) | Health level based on the modem alarm and some always-present alarms. | +| status | [ hiber.modem.Modem.Status](#hibermodemmodemstatus) | none | +| active_subscription | [ hiber.modem.Modem.ActiveSubscription](#hibermodemmodemactivesubscription) | additional information | +| technical | [ hiber.modem.Modem.TechnicalData](#hibermodemmodemtechnicaldata) | none | +| peripherals | [ hiber.modem.Modem.Peripherals](#hibermodemmodemperipherals) | none | +| in_transfer | [ hiber.modem.Modem.Transfer](#hibermodemmodemtransfer) | none | +| notes | [ string](#string) | Notes field that can be used to add additional information to a modem. | +| secure_notes | [ string](#string) | Secure notes field that can be used to add additional information to a modem, with limited accessibility. | +| tags | [repeated hiber.tag.Tag](#hibertagtag) | none | +| is_gateway | [ bool](#bool) | [DEPRECATED] Whether the modem is a gateway, it has been configured as a gateway and has connected devices. Use `type` instead. | +| is_device_connected_to_gateway | [ bool](#bool) | [DEPRECATED] Whether the modem is connected to a modem configured as a gateway. Use `type` instead. | +| connected_to_gateway | [ string](#string) | [DEPRECATED] The modem number that this modem is connected to, if any. Use `connected_device_info.connected_to_gateway` instead. | +| external_device_ids | [repeated string](#string) | [DEPRECATED] External device ids, if any. Use `connected_device_info.external_device_ids` instead. | +| type | [ hiber.modem.Modem.Type](#hibermodemmodemtype) | The type of modem. Used mainly to differentiate in the UI or to sort on. | +| gateway_info | [ hiber.modem.Modem.GatewayInfo](#hibermodemmodemgatewayinfo) | Additional information when this modem is a gateway. | +| connected_device_info | [ hiber.modem.Modem.ConnectedDeviceInfo](#hibermodemmodemconnecteddeviceinfo) | Additional information when this modem is a connected device. | +| metadata | [ google.protobuf.Struct](#googleprotobufstruct) | Modem metadata, typically extracted from messages. | +| time_zone | [ string](#string) | The timezone configured for the modem. | +| transmission_interval | [ hiber.Duration](#hiberduration) | The transmission interval for this modem, if configured. | + +### hiber.modem.ModemSelection + +Selection object for modems. +Filter modems by modem id, (child)organization, tags, activation status and time, service type and last message time. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| modems | [ hiber.Filter.Modems](#hiberfiltermodems) | none | +| free_text_search | [ string](#string) | none | +| only_active | [ bool](#bool) | none | +| activated_in | [ hiber.TimeRange](#hibertimerange) | none | +| with_last_message_in | [ hiber.TimeRange](#hibertimerange) | none | +| with_service_type | [repeated hiber.organization.subscription.ServiceType](#hiberorganizationsubscriptionservicetype) | none | +| health | [repeated hiber.Health](#hiberhealth) | Deprecated health that uses the OK, WARNING, ERROR format. | +| health_levels | [repeated string](#string) | Filter modems by health level. | +| status | [repeated hiber.modem.Modem.Status](#hibermodemmodemstatus) | Filter modems by status(es). Defaults to nominal statuses, excluding disabled, dead, lost or damaged modems. | +| transfers | [ hiber.modem.ModemSelection.Transfers](#hibermodemmodemselectiontransfers) | none | +| include_types | [repeated hiber.modem.Modem.Type](#hibermodemmodemtype) | Only include modems that have a type listed in types. In other words, when providing multiple types, this is an "OR" relationship. | +| exclude_types | [repeated hiber.modem.Modem.Type](#hibermodemmodemtype) | Exclude modems that have a type listed in types. | +| only_gateways | [ bool](#bool) | [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`. | +| only_has_external_device_ids | [ bool](#bool) | [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`. | +| connected_to_gateways | [ hiber.Filter.Modems](#hiberfiltermodems) | none | +| external_device_ids | [repeated string](#string) | none | +| filter_by_tags | [ hiber.tag.TagSelection](#hibertagtagselection) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **peripheral_selection**.peripherals | [ hiber.modem.ModemSelection.Peripherals](#hibermodemmodemselectionperipherals) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **peripheral_selection**.only_without_peripheral | [ bool](#bool) | When set to true, only modems that do not have any peripheral will be included in the result. | + + +### Enums +#### hiber.modem.ListModemsRequest.Sort +Sorting options for the results. + +| Name | Description | Number | +| ---- | ----------- | ------ | +| LAST_MESSAGE_RECEIVED | none | 0 | +| LAST_MESSAGE_RECEIVED_INVERTED | none | 1 | +| MODEM_NUMBER_ASC | Sort numerically on the number of the modem. | 2 | +| MODEM_NUMBER_DESC | none | 3 | +| STATUS_ASC | none | 4 | +| STATUS_DESC | none | 5 | +| MODEM_NAME_ASC | Sort alphabetically on the name of the modem. De default name of the modem is its HEX number | 6 | +| MODEM_NAME_DESC | none | 7 | +| ORGANIZATION_ASC | Sort alphabetically on the name of the organization that owns the modem | 8 | +| ORGANIZATION_DESC | none | 9 | +| HEALTH | Health sorted from least to most severe (i.e. OK, WARNING, ERROR). | 10 | +| HEALTH_DESC | Health sorted from most to least severe (i.e. ERROR, WARNING, OK). | 11 | + +#### hiber.modem.Modem.Peripherals.HiberAntenna +A Hiber antenna is required for the modem to function. + +| Name | Description | Number | +| ---- | ----------- | ------ | +| DEFAULT | none | 0 | +| HIBER_PANDA | none | 1 | +| HIBER_GRIZZLY | none | 2 | +| HIBER_BLACK | none | 3 | +| CUSTOM | none | 4 | + +#### hiber.modem.Modem.Status +Modem statuses for its lifecycle. + +| Name | Description | Number | +| ---- | ----------- | ------ | +| DEFAULT | Modem is in your inventory, but not deployed or active. | 0 | +| ACTIVE | Modem is active and sending messages. See health for more details on its health, based on the past messages. | 1 | +| DAMAGED | none | 2 | +| LOST | none | 3 | +| DEAD | none | 4 | +| DISABLED | none | 5 | + +#### hiber.modem.Modem.Transfer.Status + + +| Name | Description | Number | +| ---- | ----------- | ------ | +| NONE | none | 0 | +| INBOUND | Modem has been shipped or transferred to you and is inbound. When you mark the transfer as received, the modems are added to your organization. If you encounter any issues, you can mark modems for return using the ModemTransferReturnService. | 1 | +| OUTBOUND | Modem has been shipped or transferred by you and is outbound. When the transfer is received, the modems are removed from your organization, though the recipient may still return them later. | 2 | +| RETURNING | You shipped this modem to another organization, but they are returning it. When you mark the transfer as received, the modems are added back to your organization. | 3 | + +#### hiber.modem.Modem.Type +The effective type of this modem. +Type can depend on the hardware itself as well as network topology. + +| Name | Description | Number | +| ---- | ----------- | ------ | +| OTHER | A device of which the specific type is not known | 0 | +| DIRECT | A devices that directly connects to the satellite | 1 | +| GATEWAY | 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). | 2 | +| CONNECTED_DEVICE | A sensor that can (only) send data to a gateway. Typically using a LoRaWAN connection. | 3 | + +#### hiber.modem.ModemMessage.Source + + +| Name | Description | Number | +| ---- | ----------- | ------ | +| HIBERBAND | A real message from a modem or gateway, sent over Hiberband to the server. | 0 | +| DIRECT_TO_API | A real message from a modem or gateway, sent directly to the API using a persistent connection. | 1 | +| TEST | A test message sent to the testing API. | 2 | +| SIMULATION | A simulated message, generated by the server. | 3 | + + + +## Referenced messages from base.proto +(Note that these are included because there is a proto dependency on the file, +so not all messages listed here are referenced.) + +#### This section was generated from [base.proto](https://github.com/HiberGlobal/api/blob/master/base.proto). + + +### hiber.Area + +Rectangular area between two locations, normalized to bottom-left and top-right points. + +Center point is added for convenience; it's simple the point directly between the two corner points. +When sending an Area to the api, the center location is ignored. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| center | [ hiber.Location](#hiberlocation) | none | +| bottom_left | [ hiber.Location](#hiberlocation) | none | +| top_right | [ hiber.Location](#hiberlocation) | none | +| textual | [ string](#string) | Text representation. Can be used as an alternative input in a request, filled in by the API in responses. | + +### hiber.Avatar + +An avatar is represented either by a (publicly) fetchable URL that serves an image, +xor a binary payload that knows its name and mime-type. + +If it is a url, it must be obtainable without credentials, though this is not validated by the API. +Because the content behind URL's can change or become unavailable over time, +the client should make sure it properly caches the data fetched from the URL. +("Properly" means [among other things] respecting the response headers for this resource) + +| Field | Type | Description | +| ----- | ---- | ----------- | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **url_or_image**.url | [ string](#string) | A URL that contains the location of avatar. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **url_or_image**.image | [ hiber.NamedFile](#hibernamedfile) | The data of the avatar as a Named File. | + +### hiber.BytesOrHex + +Some clients may prefer direct binary data, while other prefer a hexadecimal string, +both for input and output. To support both methods, this object is used to represent binary data. + +When you receive this from the api, both fields are set. When sending it to the api, only one field is required. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| bytes | [ bytes](#bytes) | none | +| hex | [ string](#string) | none | + +### hiber.BytesOrHex.Update + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| updated | [ bool](#bool) | none | +| value | [ hiber.BytesOrHex](#hiberbytesorhex) | none | + +### hiber.Date + +Date type for convenience. + +Some clients are better at parsing year, month and day of month as separate fields, +while others prefer a text-based format. +To accommodate this, this Date type supports both. + +When used as API output, both the int fields and textual fields will be set. +The textual field has the commonly used ISO 8601 local date format (i.e. "2018-01-01"). +When used an API input, either specify the int fields or the textual field. +If both are specified, the textual field will be discarded. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| year | [ uint32](#uint32) | none | +| month | [ uint32](#uint32) | none | +| day | [ uint32](#uint32) | none | +| textual | [ string](#string) | none | + +### hiber.DoubleRange + +Decimal range. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| start | [ double](#double) | none | +| end | [ double](#double) | none | + +### hiber.Duration + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| duration | [ google.protobuf.Duration](#googleprotobufduration) | none | +| textual | [ string](#string) | none | + +### hiber.Filter + +Filters used in many api calls to filter the data sources, results, etc. + +"Include" fields filter out anything not in the include set. +When not set, all items will be returned (except excluded items) + +"Exclude" fields filter out anything in the exclude set. +When combined with include, exclude takes precedence when determining whether an item is filtered + + +### hiber.Filter.ChildOrganizations + +Specify which organizations to get data from. By default, data is only retrieved for the current organization, but +using ChildOrganizations we can specify to include a number of, or all, sub-organizations. + +Note: ChildOrganization differs from other filters in that it defaults to not allowing anything, where the +other filters default to allowing everything + +| Field | Type | Description | +| ----- | ---- | ----------- | +| include_all | [ bool](#bool) | none | +| include | [repeated string](#string) | none | +| exclude | [repeated string](#string) | none | + +### hiber.Filter.ChildOrganizations.Update + +Update object to update a Filter.ChildOrganizations field. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| updated | [ bool](#bool) | none | +| value | [ hiber.Filter.ChildOrganizations](#hiberfilterchildorganizations) | none | + +### hiber.Filter.Events + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| include | [repeated hiber.EventType](#hibereventtype) | none | +| exclude | [repeated hiber.EventType](#hibereventtype) | none | + +### hiber.Filter.Events.Update + +Update object to update a Filter.Events field. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| updated | [ bool](#bool) | none | +| value | [ hiber.Filter.Events](#hiberfilterevents) | none | + +### hiber.Filter.FieldEnumValues + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| field | [ string](#string) | none | +| include | [repeated string](#string) | none | +| exclude | [repeated string](#string) | none | + +### hiber.Filter.Modems + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| include | [repeated string](#string) | Include all modems with these modem numbers (HEX) | +| exclude | [repeated string](#string) | Exclude all modems with these modem numbers (HEX). Exclude takes precedence over include. | + +### hiber.Filter.Modems.Update + +Update object to update a Filter.Modems field. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| updated | [ bool](#bool) | none | +| value | [ hiber.Filter.Modems](#hiberfiltermodems) | none | + +### hiber.Filter.OrganizationPermissions + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| include_all | [ bool](#bool) | none | +| include | [repeated hiber.OrganizationPermission](#hiberorganizationpermission) | none | +| exclude | [repeated hiber.OrganizationPermission](#hiberorganizationpermission) | none | + +### hiber.Filter.Organizations + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| include | [repeated string](#string) | none | +| exclude | [repeated string](#string) | none | + +### hiber.Filter.Publishers + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| include | [repeated int64](#int64) | none | +| exclude | [repeated int64](#int64) | none | +| only_active | [ bool](#bool) | none | + +### hiber.Filter.Tags + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| include | [repeated int64](#int64) | none | +| exclude | [repeated int64](#int64) | none | + +### hiber.Filter.Tags.Update + +Update object to update a Filter.Tags field. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| updated | [ bool](#bool) | none | +| value | [ hiber.Filter.Tags](#hiberfiltertags) | none | + +### hiber.Filter.UserPermissions + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| include_all | [ bool](#bool) | none | +| include | [repeated hiber.UserPermission](#hiberuserpermission) | none | +| exclude | [repeated hiber.UserPermission](#hiberuserpermission) | none | + +### hiber.Filter.Users + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| include | [repeated string](#string) | none | +| exclude | [repeated string](#string) | none | + +### hiber.Filter.Webhooks + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| include | [repeated int64](#int64) | none | +| exclude | [repeated int64](#int64) | none | +| only_active | [ bool](#bool) | none | + +### hiber.Location + +Geographic latitude and longitude coordinates specified in decimal degrees. +For more information, see the WGS-84 coordinate system, which is used for most GPS systems. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| latitude | [ double](#double) | Decimal degrees north. | +| longitude | [ double](#double) | Decimal degrees east. | +| textual | [ string](#string) | Text representation. Can be used as an alternative input in a request, filled in by the API in responses. | + +### hiber.LocationSelection + +Selection object for map data. Filter modems on the map by id, (child)organization. + +Also, filter the map data by level and area restriction, to only display a small area at a detailed map level, +for example + +| Field | Type | Description | +| ----- | ---- | ----------- | +| areas | [repeated hiber.Area](#hiberarea) | Rectangular areas, each defined by two locations, normalized to bottom-left and top-right points. | +| shapes | [repeated hiber.Shape](#hibershape) | Polygon shapes, each defined by a list of locations, which draw a shape on the map. | + +### hiber.NamedFile + +A NamedFile contains bytes with its mime-type and name. +It can represent any file of any type. + +Note that depending on where in the API this is used, +the server might put restrictions on file size, media-type or name length. + +The file name should be interpreted as-is. +No hierarchical information is stored in the name, nor should you look at the "extension" to know its media-type. +It might not even have a file extension. +The file name may contain characters that cannot be a valid file name on certain systems. + +Specific API calls may pur restrictions on the name or size of the file. + +When showing this as an image in a browser, one can make use of a `data` URI. +The client must convert the bytes to base64 and can then construct a data URI like this + + data:;base64, + +Other type clients should be able to sort-of-directly set the data bytes as the source for an image. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| data | [ hiber.BytesOrHex](#hiberbytesorhex) | The binary payload that represents the file | +| media_type | [ string](#string) | The media-type of the file, as defined by RFC 6838 or its extensions | +| name | [ string](#string) | A semantic name for this file. | + +### hiber.Pagination + +Pagination is normalized across the api. Provide a pagination object to get a specific page or offset, +or limit your data. + +Calls that have a pagination option automatically return a Pagination.Result, which contains +either the specified pagination options or the defaults, as well as total counts. It also contains Pagination +objects that can be used for the previous and next page. + +This effectively means that an api user would never need to create their own pagination object; as long as they +start at the first page and continue to the next, they can use the provided Pagination object. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| size | [ int32](#int32) | none | +| page | [ int32](#int32) | none | + +### hiber.Pagination.Result + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| size | [ int32](#int32) | none | +| page | [ int32](#int32) | none | +| total | [ int32](#int32) | none | +| total_pages | [ int32](#int32) | none | +| previous | [ hiber.Pagination](#hiberpagination) | none | +| next | [ hiber.Pagination](#hiberpagination) | none | +| approximated_total | [ bool](#bool) | Indicates that the total is an approximation, and not an exact value. This can be set for data that changes often, or is generally only fetched in an infinite scrolling manner. For example, unbundled events are likely to return an approximated total, but not guaranteed to do so. | + +### hiber.Shape + +Polygon shape defined by a list of locations, which draw a shape on the map. +The last point is connected to the first to close the shape. + +For example, the outline of a city would be defined using a Shape, +while a rectangular region is easier to define using Area. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| path | [repeated hiber.Location](#hiberlocation) | none | +| textual | [ string](#string) | Text representation. Can be used as an alternative input in a request, filled in by the API in responses. | + +### hiber.TimeRange + +Period of time between two timestamps. Typically used for filtering. + +This can be used with textual shortcuts for timestamp, and some additional duration textual shortcuts: +- a duration as an offset of now, i.e. "-10h" or "PT-10h": converted to now + offset, so start.textual -10h is + 10 hours before the end time (using the ISO 8601 duration format) +Examples: +- start "-10h" end "now": a time range from 10 hours before the request time, to the request time +- start "-10h" end "2022-01-01 20:00": becomes start 2022-01-01 10:00 end 2022-01-01 20:00 + +| Field | Type | Description | +| ----- | ---- | ----------- | +| start | [ hiber.Timestamp](#hibertimestamp) | none | +| end | [ hiber.Timestamp](#hibertimestamp) | none | + +### hiber.Timestamp + +Timestamp type for convenience. + +Some clients are better at parsing Google's seconds/nanos based timestamp, while others prefer a text-based format. +To accommodate this, this Timestamp type supports both. + +When used as API output, both the timestamp and textual fields will be set. The textual field has the commonly +used ISO 8601 format (i.e. "2018-01-01T13:00:00Z"). +When used an API input, only one of the fields is needed, there is no need to set both. When both are set, the +timestamp field will be used, the textual field will be discarded. + +In addition, the textual field, when used as input, allows for a number of shortcuts that get converted into +timestamps: +- "now": converted to the current timestamp at the time of the request + +| Field | Type | Description | +| ----- | ---- | ----------- | +| timestamp | [ google.protobuf.Timestamp](#googleprotobuftimestamp) | none | +| time_zone | [ string](#string) | none | +| textual | [ string](#string) | none | + +### hiber.UpdateBoolean + +Update object for a boolean. + +Since false is the default value, we need to distinguish between an omitted value and setting the value to false, +in an update object. + +To use this to update, set a value and set updated to true + +| Field | Type | Description | +| ----- | ---- | ----------- | +| updated | [ bool](#bool) | none | +| value | [ bool](#bool) | none | + +### hiber.UpdateClearableString + +Update object for a string that can be empty. + +Since an empty string is also the default value, we need to distinguish between an omitted value and +setting the value to an empty string, in an update object. + +To use this to update, set a value and set updated to true + +| Field | Type | Description | +| ----- | ---- | ----------- | +| updated | [ bool](#bool) | none | +| value | [ string](#string) | none | + +### hiber.UpdateOptionalDuration + +Update object for an optional Duration. + +To use this to update, set a value and set updated to true. +To clear the duration, set updated to true, but set no value. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| updated | [ bool](#bool) | none | +| value | [ hiber.Duration](#hiberduration) | none | + +### hiber.UpdateOptionalId + +Update object for an optional id. + +To use this to update, set a value and set updated to true. To clear the id, set updated to true, but set no value. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| updated | [ bool](#bool) | none | +| value | [ int64](#int64) | none | + +### hiber.UpdateZeroableInt + +Update object for an int that can be set to 0. + +Since 0 is also the default value, we need to distinguish between an omitted value and setting the value to 0, +in an update object. + +To use this to update, set a value and set updated to true + +| Field | Type | Description | +| ----- | ---- | ----------- | +| updated | [ bool](#bool) | none | +| value | [ uint32](#uint32) | none | + + +### Enums +#### hiber.EventType +Enum of api-accessible events. + +The event types in this enum have a protobuf implementation, and can be used, for example, in the +api event stream and publishers. + +| Name | Description | Number | +| ---- | ----------- | ------ | +| DEFAULT | none | 0 | +| ORGANIZATION_CREATED | none | 34 | +| ORGANIZATION_UPDATED | none | 12 | +| ORGANIZATION_DELETED | none | 35 | +| ORGANIZATION_EVENT_CONFIGURATION_UPDATED | none | 43 | +| MODEM_CREATED | none | 55 | +| MODEM_UPDATED | none | 36 | +| MODEM_LOCATION_UPDATED | none | 4 | +| MODEM_ACTIVATED | none | 33 | +| MODEM_MESSAGE_RECEIVED | none | 5 | +| MODEM_MESSAGE_BODY_PARSED | none | 39 | +| MODEM_MESSAGE_BODY_RECEIVED | none | 45 | +| MODEM_MESSAGE_CANNOT_BE_PARSED | none | 15 | +| MODEM_MESSAGE_SUMMARY | none | 42 | +| MODEM_MESSAGE_BODY_PARSER_CREATED | none | 46 | +| MODEM_MESSAGE_BODY_PARSER_UPDATED | none | 47 | +| MODEM_MESSAGE_BODY_PARSER_DELETED | none | 48 | +| MODEM_ALARM | none | 56 | +| MODEM_ALARM_CREATED | none | 57 | +| MODEM_ALARM_UPDATED | none | 58 | +| MODEM_ALARM_DELETED | none | 59 | +| ASSIGNED | none | 63 | +| UNASSIGNED | none | 64 | +| MODEM_TRANSFER_STARTED | none | 17 | +| MODEM_TRANSFER_RECEIVED | none | 18 | +| MODEM_TRANSFER_CANCELLED | none | 19 | +| MODEM_TRANSFER_NOT_RECEIVED | none | 20 | +| MODEM_TRANSFER_RETURN_TRANSFER_STARTED | none | 21 | +| MODEM_CLAIMED | none | 22 | +| PUBLISHER_CREATED | none | 1 | +| PUBLISHER_UPDATED | none | 2 | +| PUBLISHER_DELETED | none | 3 | +| PUBLISHER_AUTO_DISABLED | none | 37 | +| PUBLISHER_FAILED | none | 11 | +| USER_ACCESS_REQUEST | none | 8 | +| USER_INVITED | none | 38 | +| USER_ADDED | none | 9 | +| USER_REMOVED | none | 10 | +| USER_VALIDATION_UPDATED | none | 54 | +| TOKEN_CREATED | none | 31 | +| TOKEN_EXPIRY_WARNING | none | 25 | +| TOKEN_EXPIRED | none | 26 | +| TOKEN_DELETED | none | 32 | +| EXPORT_CREATED | none | 65 | +| EXPORT_READY | none | 66 | +| EXPORT_FAILED | none | 67 | + +#### hiber.Health +Health is an indicator for issues. It is used for publishers to give a quick indication of issues. + +| Name | Description | Number | +| ---- | ----------- | ------ | +| OK | none | 0 | +| WARNING | none | 1 | +| ERROR | none | 2 | + +#### hiber.UnitOfMeasurement +Unit of measurement for a numeric value. + +| Name | Description | Number | +| ---- | ----------- | ------ | +| UNIT_UNKNOWN | none | 0 | +| DURATION_MILLISECONDS | none | 40 | +| DURATION_SECONDS | none | 1 | +| DURATION_MINUTES | none | 2 | +| DURATION_HOURS | none | 3 | +| DURATION_DAYS | none | 4 | +| DURATION_WEEKS | none | 41 | +| FUEL_EFFICIENCY_LITER_PER_100_KILOMETER | none | 30 | +| FUEL_EFFICIENCY_KILOMETER_PER_LITER | none | 31 | +| FUEL_EFFICIENCY_KILOMETER_PER_US_GALLON | none | 32 | +| FUEL_EFFICIENCY_KILOMETER_PER_IMPERIAL_GALLON | none | 33 | +| FUEL_EFFICIENCY_MILE_PER_US_GALLON | none | 34 | +| FUEL_EFFICIENCY_MILE_PER_IMPERIAL_GALLON | none | 35 | +| FUEL_EFFICIENCY_MILE_PER_LITER | none | 36 | +| DISTANCE_METER | none | 8 | +| DISTANCE_MILLIMETER | none | 9 | +| DISTANCE_CENTIMETER | none | 10 | +| DISTANCE_KILOMETER | none | 11 | +| DISTANCE_NAUTICAL_MILE | none | 26 | +| DISTANCE_MILE | none | 21 | +| DISTANCE_YARD | none | 27 | +| DISTANCE_FOOT | none | 28 | +| DISTANCE_INCH | none | 29 | +| PERCENT | none | 16 | +| PRESSURE_BAR | none | 12 | +| PRESSURE_PSI | none | 14 | +| PRESSURE_K_PA | none | 17 | +| SPEED_KILOMETERS_PER_HOUR | none | 18 | +| SPEED_KNOTS | none | 19 | +| SPEED_METERS_PER_SECOND | none | 20 | +| SPEED_MILES_PER_HOUR | none | 22 | +| TEMPERATURE_KELVIN | none | 5 | +| TEMPERATURE_DEGREES_CELSIUS | none | 6 | +| TEMPERATURE_DEGREES_FAHRENHEIT | none | 7 | +| VOLTAGE_MILLIVOLT | none | 15 | +| VOLUME_LITER | none | 23 | +| VOLUME_GALLON_US | none | 24 | +| VOLUME_GALLON_IMPERIAL | none | 25 | +| VOLUME_CUBIC_METER | none | 42 | +| VOLUME_CUBIC_FOOT | none | 43 | +| MASS_KILOGRAMS | none | 37 | +| MASS_POUNDS | none | 38 | +| FLOW_CUBIC_METERS_PER_HOUR | none | 39 | + +## Scalar Value Types + +| .proto Type | Notes | C++ Type | Java Type | Python Type | +| ----------- | ----- | -------- | --------- | ----------- | +|

    double | | double | double | float | +|

    float | | float | float | float | +|

    int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | +|

    int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | +|

    uint32 | Uses variable-length encoding. | uint32 | int | int/long | +|

    uint64 | Uses variable-length encoding. | uint64 | long | int/long | +|

    sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | +|

    sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | +|

    fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | +|

    fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | +|

    sfixed32 | Always four bytes. | int32 | int | int | +|

    sfixed64 | Always eight bytes. | int64 | long | int/long | +|

    bool | | bool | boolean | boolean | +|

    string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | +|

    bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | + diff --git a/docs/md/values.md b/docs/md/values.md index c28ce9e..c52aa12 100644 --- a/docs/md/values.md +++ b/docs/md/values.md @@ -53,6 +53,7 @@ - [hiber.Filter.ChildOrganizations.Update](#hiberfilterchildorganizationsupdate) - [hiber.Filter.Events](#hiberfilterevents) - [hiber.Filter.Events.Update](#hiberfiltereventsupdate) + - [hiber.Filter.FieldEnumValues](#hiberfilterfieldenumvalues) - [hiber.Filter.Modems](#hiberfiltermodems) - [hiber.Filter.Modems.Update](#hiberfiltermodemsupdate) - [hiber.Filter.OrganizationPermissions](#hiberfilterorganizationpermissions) @@ -549,6 +550,16 @@ Update object to update a Filter.Events field. | updated | [ bool](#bool) | none | | value | [ hiber.Filter.Events](#hiberfilterevents) | none | +### hiber.Filter.FieldEnumValues + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| field | [ string](#string) | none | +| include | [repeated string](#string) | none | +| exclude | [repeated string](#string) | none | + ### hiber.Filter.Modems diff --git a/docs/md/webhook.md b/docs/md/webhook.md index e7f09ae..c518947 100644 --- a/docs/md/webhook.md +++ b/docs/md/webhook.md @@ -69,6 +69,7 @@ - [hiber.Filter.ChildOrganizations.Update](#hiberfilterchildorganizationsupdate) - [hiber.Filter.Events](#hiberfilterevents) - [hiber.Filter.Events.Update](#hiberfiltereventsupdate) + - [hiber.Filter.FieldEnumValues](#hiberfilterfieldenumvalues) - [hiber.Filter.Modems](#hiberfiltermodems) - [hiber.Filter.Modems.Update](#hiberfiltermodemsupdate) - [hiber.Filter.OrganizationPermissions](#hiberfilterorganizationpermissions) @@ -764,6 +765,16 @@ Update object to update a Filter.Events field. | updated | [ bool](#bool) | none | | value | [ hiber.Filter.Events](#hiberfilterevents) | none | +### hiber.Filter.FieldEnumValues + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| field | [ string](#string) | none | +| include | [repeated string](#string) | none | +| exclude | [repeated string](#string) | none | + ### hiber.Filter.Modems diff --git a/easypulse.proto b/easypulse.proto index 81ba50c..4af9fc1 100644 --- a/easypulse.proto +++ b/easypulse.proto @@ -330,6 +330,12 @@ message Easypulse { /* Just take the last value (in a group). */ LAST = 3; + + /* Take the lowest value (in a group). */ + MINIMUM = 4; + + /* Take the highest value (in a group). */ + MAXIMUM = 5; } /* How to sort the returned values. */ @@ -511,6 +517,11 @@ message Easypulse { /* Sort the returned assets using the given option. By default, Assets are sorted by name. */ ListAssets.Request.Sort sort = 4; + + /* Whether to apply the unit preferences to the fields. + * This will convert any fields into your preferred unit, for convenience. + */ + bool apply_unit_preferences = 5; } message Response { diff --git a/field.proto b/field.proto index cc3590b..770a1c3 100644 --- a/field.proto +++ b/field.proto @@ -130,6 +130,9 @@ message Field { */ bool encrypted = 3; + /* Whether this field should be validated from the parser output. */ + bool optional = 12; + /* If numeric, the unit of the field. * Deprecated: use numeric.numeric_unit oneof instead */ diff --git a/field_service.proto b/field_service.proto index 9f3f073..266fbfe 100644 --- a/field_service.proto +++ b/field_service.proto @@ -15,6 +15,7 @@ option go_package = "hiber"; service FieldService { rpc List (ListFields.Request) returns (ListFields.Response); + rpc ForModem (ListFieldsForModem.Request) returns (ListFieldsForModem.Response); rpc Add (AddFieldsRequest) returns (modem.message.bodyparser.ModemMessageBodyParser); rpc ReplaceAll (ReplaceAllFieldsRequest) returns (modem.message.bodyparser.ModemMessageBodyParser); @@ -65,7 +66,7 @@ message ListFields { Sort sort = 4; /* Whether to apply the unit preferences to the fields. - * This will convert any fields into you preferred unit, for convenience. + * This will convert any fields into your preferred unit, for convenience. */ bool apply_unit_preferences = 5; } @@ -77,6 +78,48 @@ message ListFields { } } +message ListFieldsForModem { + message Request { + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ + string organization = 1; + + /* Select the modems to fetch the fields for. */ + modem.ModemSelection modem_selection = 2; + + /* Select which fields to return. */ + FieldSelection field_selection = 3; + + Pagination pagination = 4; + ListFields.Sort sort = 5; + + /* Whether to apply the unit preferences to the fields. + * This will convert any fields into you preferred unit, for convenience. + */ + bool apply_unit_preferences = 6; + + /* Whether to also calculate the total fields for all selected modems, + * and return them as a single list in the response. + * This can be useful to display table columns, for example. + */ + bool include_total = 7; + } + + message Response { + message ModemWithFields { + string modem = 1; + repeated Field fields = 2; + } + + repeated ModemWithFields modem_fields = 1; + Request request = 2; + Pagination.Result pagination = 3; + + /* A merged result of all fields, for all modems. This can be useful to display table columns, for example. */ + repeated field.Field total = 4; + } +} + + message AddFieldsRequest { /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; @@ -130,6 +173,9 @@ message UpdateFieldRequest { */ UpdateBoolean encrypted = 5; + /* Whether this field is optional or not. */ + UpdateBoolean optional = 8; + /* Update field details, like numeric details or enum values. */ oneof update_details { UpdateFieldNumericDetails numeric = 6; diff --git a/message.proto b/message.proto index 2cac276..0358a75 100644 --- a/message.proto +++ b/message.proto @@ -27,9 +27,13 @@ service MessageService { /* Count messages for the selected modems. */ rpc Count (CountMessages.Request) returns (CountMessages.Response); - rpc AvailableBodyFields (AvailableMessageBodyFields.Request) returns (AvailableMessageBodyFields.Response); + rpc AvailableBodyFields (AvailableMessageBodyFields.Request) returns (AvailableMessageBodyFields.Response) { + option deprecated = true; + } - rpc History (MessageBodyFieldHistory.Request) returns (MessageBodyFieldHistory.Response); + rpc History (MessageBodyFieldHistory.Request) returns (MessageBodyFieldHistory.Response) { + option deprecated = true; + } } /* Message received from a device in the field. @@ -182,7 +186,11 @@ message CountMessages { } message AvailableMessageBodyFields { + option deprecated = true; + message Request { + option deprecated = true; + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; modem.ModemSelection modems = 2; @@ -196,6 +204,8 @@ message AvailableMessageBodyFields { } message Response { + option deprecated = true; + /* Deprecated wrapper for backwards compatibility */ message FieldWrapperDeprecated { option deprecated = true; @@ -219,9 +229,12 @@ message AvailableMessageBodyFields { /* List the history for a single field, and optionally apply an aggregation and/or grouping to it. */ message MessageBodyFieldHistory { + option deprecated = true; /* Request to get the history of (a) field(s), for the selected modems in the organization. */ message Request { + option deprecated = true; + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; @@ -253,11 +266,13 @@ message MessageBodyFieldHistory { uint32 reduce_to_max_size = 7; } - /* Get the history for the selected fields. */ + /* Get the history for the selected fields. + * Text and Enum fields cannot be summed, or averaged, they always use LAST aggregation when aggregating. + */ repeated string message_body_fields = 8; /* Get the history for the location. - * Locations cannot be summed, or averaged, so default to the LAST aggregation when aggregating. + * Locations cannot be summed, or averaged, they always use LAST aggregation when aggregating. */ bool include_location = 9; @@ -266,6 +281,8 @@ message MessageBodyFieldHistory { /* Options to aggregate the history data points (in a group). */ enum Aggregation { + option deprecated = true; + /* Do not aggregate the history data points, just list all of them. */ NONE = 0; @@ -277,6 +294,12 @@ message MessageBodyFieldHistory { /* Just take the last value (in a group). */ LAST = 3; + + /* Take the lowest value (in a group). */ + MINIMUM = 4; + + /* Take the highest value (in a group). */ + MAXIMUM = 5; } /* How to sort the returned values. */ @@ -288,6 +311,8 @@ message MessageBodyFieldHistory { /* Response with the (aggregated) history of (a) field(s), for the selected modems in the organization. */ message Response { + option deprecated = true; + /* The processed historical data points. * For example, when applying the SUM aggregation to all data points, this list would only contains a * single value, the sum of values. diff --git a/sso.proto b/sso.proto index 7a7c756..0d9d1e6 100644 --- a/sso.proto +++ b/sso.proto @@ -23,11 +23,24 @@ message ZendeskTokenRequest { } } +/* Create a session id for the Dundas BI tool. */ message DundasSSO { message Request { + /* The organization to get a session id for. */ string organization = 1; + + /* Include the current session id to validate it. If it is valid, the server will not create a new session id. + * This makes it easier to avoid having multiple sessions. + */ + string current_session_id = 2; } message Response { + /* A valid session id for the given organization. + * If a session id was given, and it was valid, this is that session id. + */ string session_id = 1; + + /* The subdomain to write the session id to, for convenience. */ + string session_id_subdomain = 2; } } diff --git a/value_service.proto b/value_service.proto new file mode 100644 index 0000000..9fafcd5 --- /dev/null +++ b/value_service.proto @@ -0,0 +1,250 @@ +/* Service to fetch time series data from our system. + * + * Time series data is produced by the device and sent in the form of messages. + * Messages are parsed to a number of values (depending on the parser), which can be retrieved using this service. + */ +syntax = "proto3"; + +package hiber.value; + +import "base.proto"; +import "modem.proto"; +import "value.proto"; + +option java_multiple_files = false; +option java_package = "global.hiber.api.grpc.value"; +option java_outer_classname = "ValueServiceApi"; +option go_package = "hiber"; + +service ValueService { + rpc List (ListValues.Request) returns (ListValues.Response); + rpc Aggregated (AggregatedValues.Request) returns (AggregatedValues.Response); +} + +/* Select the values to return. */ +message ValueSelection { + /* Select the modem(s) to get the values for. */ + modem.ModemSelection modems = 1; + + /* Get the values for the selected fields. */ + repeated string fields = 2; + + /* The time to view the values for. */ + TimeRange time_range = 3; + + /* Include the location (which is not a field). */ + bool include_location = 4; + + /* Filter the values for enum fields. */ + repeated Filter.FieldEnumValues filter_enum_values = 6; +} + +/* A Value at a time, for a given modem and field. */ +message ValueContext { + string modem = 1; + string field = 2; + + /* The time for this value. */ + Timestamp time = 3; + + oneof value_type { + /* The value at this time. */ + Value value = 4; + + /* The value at this time. */ + ValueDurations duration = 5; + + /* The value at this time. */ + ValueDelta delta = 6; + } + + /* The amount of time a field for a modem was at different values. */ + message ValueDurations { + repeated ValueDuration durations = 1; + } + + /* The amount of time a field for a modem was in this value. */ + message ValueDuration { + /* The value the duration is for. */ + Value value = 1; + + /* The aggregated duration the field was this value. */ + Duration duration = 2; + } + + /* The delta of a value: the difference between a value and the previous value. */ + message ValueDelta { + /* The delta of the two values. */ + Value delta = 1; + + /* The value at this time. */ + Value current = 2; + + /* The previous value to compare it with. */ + Value previous = 3; + } +} + +/* Transform the values into a derived value. */ +enum ValueTransformation { + /* Instead of returning the value, return the amount of time a value was active. + * Aggregation (if applicable) is applied afterwards on the duration value. + */ + DURATION = 0; + + /* Instead of returning the value, return the difference between the value and the previous value. + * Aggregation (if applicable) is applied before the delta is calculated. + */ + DELTA = 1; +} + +/* List values for a (set of) modem(s), filtering by field and time. */ +message ListValues { + /* How to sort the values. */ + enum Sort { + TIME_ASCENDING = 0; + TIME_DESCENDING = 1; + } + + message Request { + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ + string organization = 1; + ValueSelection selection = 2; + Pagination pagination = 3; + Sort sort = 4; + + /* Transform the values for a field into a derived value. + * Fields specified here must have been specified in the selection. + */ + map transform_fields = 5; + } + + message Response { + repeated ValueContext values = 1; + Pagination.Result pagination = 2; + Request request = 3; + } +} + +/* Get the values for the selected field. + * + * There are a few limitations here: + * - text fields can only use the LAST aggregation. + * - enum fields support a subset of aggregations: + * - DEFAULT and LAST return the last value. + * - MINIMUM and MAXIMUM return the lowest or highest value (respectively) based on the enum value order. + * - AVERAGE and SUM are not supported. + * + * - enum duration + * + * An enum example: + * Field "status" with this timeline: 00:00 OK, 00:10 FAILED, 00:20 OK, 00:25 FAILED, 00:40 OK + * - aggregation DEFAULT or LAST: OK, since it's OK at the end of the time range. + * - aggregation SUM: OK: 35m, FAILED: 25m + */ +enum ValueAggregation { + DEFAULT = 0; + + /* Return the average value. + * Not supported for textual and enum fields. When used with these fields, LAST is used instead. + */ + AVERAGE = 1; + + /* Return the sum all values. + * Not supported for textual and enum fields. When used with these fields, LAST is used instead. + */ + SUM = 2; + + /* Just take the last value. */ + LAST = 3; + + /* Return the lowest value. + * For enum fields, the order of values is used to determine the MINIMUM. + * Not supported for textual fields. When used with these fields, LAST is used instead. + */ + MINIMUM = 4; + + /* Return the highest value. + * For enum fields, the order of values is used to determine the MAXIMUM. + * Not supported for textual fields. When used with these fields, LAST is used instead. + */ + MAXIMUM = 5; +} + +/* Aggregate values for a (set of) modem(s), filtering by field and time. */ +message AggregatedValues { + /* The time range that was aggregated. */ + TimeRange time_range = 1; + + /* The aggregated values for the requested fields. + * + * Timestamp is only set if the aggregation can return an exact data point: + * - if the aggregation would return an exact point: LAST, MAXIMUM, MINIMUM. + * - if the aggregation is applied to a single value, for a single field. + */ + repeated ValueContext values = 2; + + /* The last location in the time range. */ + Location location = 3; + + /* Request aggregated values, reducing the selected time range to a single value per field. */ + message Request { + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ + string organization = 1; + + /* The values to return. */ + ValueSelection selection = 2; + + /* The aggregations to use for the fields, resulting in a single value for each field. + * When an aggregation is not specified for a field, the default aggregation for that field type is used. + * + * Fields specified here must have been specified in the selection. + */ + map aggregations = 3; + + /* Transform the values for a field into a derived value. + * + * Fields specified here must have been specified in the selection. + */ + map transform_fields = 4; + + oneof optional_partition { + /* Partition the time range and apply aggregation to each part. */ + Partition partition = 5; + } + + /* Partition the time range and apply aggregation to each part (instead of over all values in the time range). + * If no partition is set, the aggregation returns a single value. + * + * For example: + * - get the average value per day for a month + * - get the sum of all values per hour in a day + */ + message Partition { + oneof partition { + /* Split up the data in time block of the given size. */ + Duration split_by_duration = 1; + + /* Limit the results to the given amount of data points, applying the function to each chunk. */ + uint32 reduce_to_max_size = 2; + } + + /* Paginate the returned partitions of the time range. */ + Pagination pagination = 3; + + /* How to sort the returned values. */ + ListValues.Sort sort = 4; + + /* Exclude any partitions that do not have any data from response. + * This is especially useful when the amount of partitions exceeds your pagination size. + */ + bool exclude_empty = 5; + } + } + + message Response { + repeated AggregatedValues aggregated_values = 1; + Pagination.Result pagination = 2; + Request request = 3; + } +}