From e72c378201de5b7829988e46b77327f21b568af6 Mon Sep 17 00:00:00 2001 From: Wouter Bouvy Date: Mon, 23 Aug 2021 15:10:17 +0200 Subject: [PATCH] 0.85 --- CHANGELOG.md | 36 + assignment.proto | 10 +- base.proto | 65 +- docs/easypulse.html | 4369 ----------------- docs/easypulse.md | 2140 +++----- docs/map.md | 788 +++ docs/modem.md | 1553 ++++++ docs/modem_alarm.md | 1477 ++++++ docs/modem_message_body_parser.md | 1336 +++++ docs/named_location.md | 791 +++ docs/permission.html | 635 --- docs/permission.md | 132 +- easypulse.proto | 7 + .../modem-message-cannot-be-parsed.json | 1 + event.proto | 26 +- health.proto | 3 +- map.proto | 59 +- modem.proto | 32 + modem_alarm.proto | 66 +- modem_message_body_parser.proto | 65 +- modem_transfer.proto | 8 +- permission.proto | 2 +- 22 files changed, 6926 insertions(+), 6675 deletions(-) delete mode 100644 docs/easypulse.html create mode 100644 docs/map.md create mode 100644 docs/modem.md create mode 100644 docs/modem_alarm.md create mode 100644 docs/modem_message_body_parser.md create mode 100644 docs/named_location.md delete mode 100644 docs/permission.html diff --git a/CHANGELOG.md b/CHANGELOG.md index 8152ba1..0bc422f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,41 @@ # Changelog Hiber API +### 0.85 (2021-08-23) + +This release improves the generated API documentation and fixes a few bugs. + +#### Changes + +- Improved API documentation and generated documentation files + - Disabled html file generation for now, since it was prone to breaking. + - Improved markdown file generation significantly + +##### EventService + +- `ModemEvent.MessageEvent.ModemMessageCannotBeParsedEvent` will no longer resolve after a new successful message, + since it indicates an invalid configuration. + - Added `ModemEvent.MessageEvent.ModemMessageCannotBeParsedEvent.resolved` to indicate resolved state. + - Added `ModemEvent.MessageEvent.ModemMessageCannotBeParsedEvent.resolve_identifier` to resolve the event manually. + - Added `EventService.Resolve` and `ResolveEvent` to resolve a `ModemMessageCannotBeParsedEvent` manually + using the provided `resolve_identifier`. +- Fixed the include_resolved filter for some events types for which is was not working properly. + +##### MapService + +- Added more Density options to the map: + - `VERY_SPARSE`: for 2x2 icons in a tile + - `SINGLE`: a single icon in a tile + +##### ModemAlarmService + +- Added the option to update checks to `UpdateModemAlarm`: `add_checks`, `update_checks` and `delete_checks`. +- Fixed an issue where alarms would not resolve correctly when a mix of correct and incorrect messages arrived + at the same time. + +##### ModemMessageBodyParserService + +- Moved validation on `data_fields` and `metadata_fields` from save to execution, for now. + ### 0.84 (2021-08-12) This release contains a few UX improvements, making the API esier to use. diff --git a/assignment.proto b/assignment.proto index 5d8edaf..e374790 100644 --- a/assignment.proto +++ b/assignment.proto @@ -400,7 +400,7 @@ message UpdateAutomaticModemAssignment { UpdateBoolean active = 7; } - /** Pick the organization to use (/impersonate). If unset, your default organization is used. */ + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; string identifier = 2; UpdateClearableString description = 3; @@ -425,7 +425,7 @@ message UpdateAutomaticModemAssignment { message EnableAutomaticModemAssignment { message Request { - /** Pick the organization to use (/impersonate). If unset, your default organization is used. */ + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; string identifier = 2; } @@ -437,7 +437,7 @@ message EnableAutomaticModemAssignment { message DisableAutomaticModemAssignment { message Request { - /** Pick the organization to use (/impersonate). If unset, your default organization is used. */ + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; string identifier = 2; } @@ -449,7 +449,7 @@ message DisableAutomaticModemAssignment { message DeleteAutomaticModemAssignment { message Request { - /** Pick the organization to use (/impersonate). If unset, your default organization is used. */ + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; string identifier = 2; } @@ -459,7 +459,7 @@ message DeleteAutomaticModemAssignment { message UpdateAutomaticModemAssignmentAvailability { message Request { - /** Pick the organization to use (/impersonate). If unset, your default organization is used. */ + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; string identifier = 2; diff --git a/base.proto b/base.proto index 5bbe227..0a56147 100644 --- a/base.proto +++ b/base.proto @@ -11,6 +11,7 @@ option java_package = "global.hiber.api.grpc"; option go_package = "hiber"; /* 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. * @@ -22,6 +23,7 @@ message UpdateZeroableInt { } /* 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. * @@ -52,6 +54,7 @@ message UpdateOptionalDuration { } /* 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. * @@ -75,8 +78,10 @@ message DoubleRange { } /* 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 @@ -88,9 +93,11 @@ message Timestamp { } /* 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. @@ -122,6 +129,7 @@ message Location { } /* 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. */ @@ -136,6 +144,7 @@ message Area { /* 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. */ @@ -147,6 +156,7 @@ message Shape { } /* 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 */ @@ -160,6 +170,7 @@ message LocationSelection { /* 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. */ message BytesOrHex { @@ -202,6 +213,7 @@ message Pagination { } /* 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. */ @@ -284,6 +296,7 @@ enum EventType { * * "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 */ @@ -325,6 +338,7 @@ message Filter { message Modems { /* Include all modems with these modem numbers (HEX) */ repeated string include = 1; + /* Exclude all modems with these modem numbers (HEX). * Exclude takes precedence over include. */ @@ -388,48 +402,49 @@ enum Health { /* 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. */ message NamedFile { /* The binary payload that represents the file */ BytesOrHex data = 1; + /* The media-type of the file, as defined by RFC 6838 or its extensions */ string media_type = 2; - /* A semantic name for this file. - * The 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. - * - * Also note that this file may contain characters that cannot be a valid file name on certain systems. - * - * Specific API calls may limit the validness of this field. - * For example setting a maximum length or disallowing certain characters. - */ + + /* A semantic name for this file. */ string name = 3; } /* 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) */ message Avatar { oneof url_or_image { - /* A URL that contains the location of avatar. - * 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) - */ + /* A URL that contains the location of avatar. */ string url = 1; - /* The data of the avatar as a Named File - * When showing this 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. - */ + + /* The data of the avatar as a Named File. */ NamedFile image = 2; } } diff --git a/docs/easypulse.html b/docs/easypulse.html deleted file mode 100644 index e177729..0000000 --- a/docs/easypulse.html +++ /dev/null @@ -1,4369 +0,0 @@ - - - - - Protocol Documentation - - - - - - - - - - -

Protocol Documentation

- -

Table of Contents

- -
- -
- - - -
-

easypulse.proto

Top -
-

Easypulse specific view and services.

This file contains specific views and services for the easypulse feature set.

This feature set is only available to organizations with the easypulse feature enabled.

For Easypulse, we've introduced the concept of an Asset, which is a modem with some assumptions about the type of

data it sends. Additionally, aggregations can be requested of Asset history when requesting Assets, allowing for a

somewhat customized Asset model.

- - -

Easypulse

-

- - - - - -

Easypulse.Asset

-

Asset in your organization.

An asset is a view of a modem, with assumptions about message data fields handled in the API.

In addition, an Asset can be enriched with aggregations of the data fields when requested (for example,

fuel level average over the past month, or total run time in the past week).

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
organizationstring

The organization the asset is in.

numberstring

The modem number for the Asset.

namestring

The custom name for the Asset, defaults to modem number.

external_identifierstring

Optional external identifier the Asset may have.

peripheralsEasypulse.Asset.PeripheralsEntryrepeated

A key value map of peripherals for the Assets.

notesstring

Add additional notes to an asset.

secure_notesstring

Add additional notes to an asset that only people with the permission can access.

health_levelhiber.health.HealthLevel

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

tagshiber.tag.Tagrepeated

Tags (or groups, when used in Mission Control) this asset is in.

last_updateEasypulse.Asset.LastUpdate

When this asset was last updated.

fuel_levelfloat

The most recent fuel level, as a percentage.

tire_pressurefloat

The most recent tire pressure in bar.

battery_levelfloat

The most recent battery level, as a percentage.

temperaturefloat

The most recent temperature in degrees Celsius.

locationhiber.Location

The most recently reported location.

aggregationsEasypulse.Asset.AggregationsEntryrepeated

Any aggregations added when this asset was requested.

- - - - - -

Easypulse.Asset.AggregationsEntry

-

- - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
keystring

valueEasypulse.History.Response

- - - - - -

Easypulse.Asset.LastUpdate

-

Information about the last update we received from this asset.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
iduint64

received_athiber.Timestamp

Time the server has received the last update.

sent_athiber.Timestamp

Time the asset sent the last update.

bodyhiber.BytesOrHex

The body of the last update.

- - - - - -

Easypulse.Asset.PeripheralsEntry

-

- - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
keystring

valuestring

- - - - - -

Easypulse.AssetSelection

-

An AssetSelection is used to select which Assets should be affected:

- When listing Assets, it is used to determine which Assets are returned

- When updating Assets, it is used to determine which Assets are updated

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
searchstring

Search for assets by name, modem number, tag or notes.

assetshiber.Filter.Modems

Select assets by modem number.

health_levelsstringrepeated

Select assets by health level.

filter_by_tagshiber.tag.TagSelection

Select assets by tag.

- - - - - -

Easypulse.History

-

List the history for a single field, and optionally apply an aggregation and/or grouping to it.

- - - - - -

Easypulse.History.Request

-

Request to get the history of a field, for the selected Assets in the organization.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
organizationstring

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

selectionEasypulse.AssetSelection

Select the asset(s) to update.

time_rangehiber.TimeRange

The time to view the history for.

aggregationEasypulse.History.Request.Aggregation

How to aggregate the data.

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.

fuel_levelbool

Get the history for the fuel level. Only one field can be chosen.

tire_pressurebool

Get the history for the tire pressure. Only one field can be chosen.

battery_levelbool

Get the history for the battery level. Only one field can be chosen.

temperaturebool

Get the history for the temperature. Only one field can be chosen.

run_timebool

Get the history for the run time. Only one field can be chosen.

idle_timebool

Get the history for the idle time. Only one field can be chosen.

- - - - - -

Easypulse.History.Response

-

Response with the (aggregated) history of a field, for the selected Assets in the organization.

- - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
valuesEasypulse.History.Response.Valuerepeated

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.

requestEasypulse.History.Request

The request that was received, corrected and used to produce this result.

- - - - - -

Easypulse.History.Response.Value

-

Processed historical data point. If this is a group, it will have a time range to denote the group.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
timestamphiber.Timestamp

When not grouping, time of the individual point. -When grouping, the time at the end of the group (when the value was true).

time_rangehiber.TimeRange

When grouping, the start and end time for the group.

fuel_levelfloat

The fuel level, as a percentage.

tire_pressurefloat

The tire pressure in bar.

battery_levelfloat

The battery level, as a percentage.

temperaturefloat

The temperature in degrees Celsius.

run_timehiber.Duration

The time the Asset was running.

idle_timehiber.Duration

The time the Asset was idle.

- - - - - -

Easypulse.ListAssets

-

List the Easypulse Assets in your organization.

Optionally, aggregated historical data can be added to the returned Assets, with a given name.

Fails when your organizations does not have the Easypulse feature.

- - - - - -

Easypulse.ListAssets.Request

-

Request to list Assets in your organization.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
organizationstring

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

selectionEasypulse.AssetSelection

Select the Assets to return.

paginationhiber.Pagination

Paginate over the returned Assets.

aggregationsEasypulse.ListAssets.Request.AggregationsEntryrepeated

Any aggregations to return with the assets, specified as a name and a History.Request.

sortEasypulse.ListAssets.Request.Sort

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

- - - - - -

Easypulse.ListAssets.Request.AggregationsEntry

-

- - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
keystring

valueEasypulse.History.Request

- - - - - -

Easypulse.ListAssets.Response

-

Response with a list of Assets

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
assetsEasypulse.Assetrepeated

The selected Assets.

paginationhiber.Pagination.Result

The applied pagination, including total results, page information, etc.

requestEasypulse.ListAssets.Request

The request that was received, corrected and used to produce this result.

- - - - - -

Easypulse.UpdateAssets

-

Update your Assets, renaming, updating tags, etc.

Produces a ModemUpdated event with the changed values.

- - - - - -

Easypulse.UpdateAssets.Request

-

Request to update your Assets, renaming, updating tags, etc.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
organizationstring

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

selectionEasypulse.AssetSelection

Select the asset(s) to update.

result_paginationhiber.Pagination

Pagination for the returned assets. Does not affect the amount of assets that are updated.

renamestring

Change the asset name to the given value. Ignored if empty.

notesstring

Update the notes for the selected assets. -Expects the original notes to be identical, unless allow_override_existing_notes is set.

secure_notesstring

Update the secure notes for the selected assets. -Expects the original notes to be identical, unless allow_override_existing_notes is set.

update_tagshiber.tag.UpdateTagsForItem

Update the tags for the selected assets.

add_peripheralsEasypulse.UpdateAssets.Request.AddPeripheralsEntryrepeated

Add or update peripherals for the selected assets.

remove_peripheralsstringrepeated

Remove peripherals from the selected assets.

allow_override_existing_notesbool

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

- - - - - -

Easypulse.UpdateAssets.Request.AddPeripheralsEntry

-

- - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
keystring

valuestring

- - - - - -

Easypulse.UpdateAssets.Response

-

The updated Assets, paginated to limit the returned amount.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
assetsEasypulse.Assetrepeated

The (page of) updated Assets.

paginationhiber.Pagination.Result

The applied pagination, including total results, page information, etc.

requestEasypulse.UpdateAssets.Request

The request that was received, corrected and used to produce this result.

- - - - - - - -

Easypulse.History.Request.Aggregation

-

Options to aggregate the history data points (in a group).

- - - - - - - - - - - - - - - - - - - - - - - - - -
NameNumberDescription
NONE0

Do not aggregate the history data points, just list all of them.

AVERAGE1

Average value of all history data points (in a group).

SUM2

Sum all history data points (in a group).

- -

Easypulse.ListAssets.Request.Sort

-

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameNumberDescription
NAME0

NAME_DESC1

LAST_UPDATED2

INACTIVITY3

NUMBER_ASC4

NUMBER_DESC5

LOWEST_FUEL_LEVEL6

HIGHEST_FUEL_LEVEL7

LOWEST_TIRE_PRESSURE8

HIGHEST_TIRE_PRESSURE9

LOWEST_BATTERY_LEVEL10

HIGHEST_BATTERY_LEVEL11

- - - - - -

EasypulseService

-

Service to list and manage Assets.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Method NameRequest TypeResponse TypeDescription
AssetsEasypulse.ListAssets.RequestEasypulse.ListAssets.Response

UpdateEasypulse.UpdateAssets.RequestEasypulse.UpdateAssets.Response

HistoryEasypulse.History.RequestEasypulse.History.Response

- - - - -
-

health.proto

Top -
-

- - -

AddHealthLevel

-

- - - - - -

AddHealthLevel.Request

-

- - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
organizationstring

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

new_health_levelHealthLevel

Add the given level to the organizations health levels. -The new health level will be added with the highest severity (at the bottom of the health levels list).

- - - - - -

AddHealthLevel.Response

-

- - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
health_levelsHealthLevelrepeated

- - - - - -

HealthLevel

-

A health level in an organization.

Health can be customized depending on your need.

The default health levels are:

- OK (green): no problems detected

- WARNING (orange): unresolvable problems detected, for example delayed or skipped messages

- ERROR (red): significant problems detected (that typically can be resolved),

for example inactivity or invalid messages (resolved on a successful message)

Health levels can be customized to as many as you need for your operations, for example:

- INTERVENTION

- DEFECT

- BATTERY

- HIGH

- LOW

Health levels are ordered by severity (low to high), and only the most severe level will be returned when

retrieving a modem.

Health can be assigned using modems alarms, which specify the health level they will cause on a modem (and for how

long, if it does not resolve automatically).

Precisely one health level can be assigned as a catch-all for any unknown health levels from alarms (or Hiber systems),

which can happen when a device manufacturer has provided alarms to your device (e.g. a low battery alarm).

By default, any unknown health levels map to the level that is marked catch-all.

Health level have a set of named colors, represented by a map where the key is the name of the color

and the value is a string that represents a valid CSS3 color.

Simple examples are: green, red, orange, grey, #FF00FF for fuchsia, etc (Keep in mind that CSS3 allows for many

ways to define colors, see https://www.w3.org/TR/2003/WD-css3-color-20030214/).

All the following definitions also mean "red":

- rgb(255, 0, 0)

- rgb(100%, 0, 0)

- rgba(100%, 0%, 0%, 100%)

- hsl(0, 100%, 50%)

- hsla(0, 100%, 50%, 1)

The client is responsible for rendering the correct color from the CSS3 color-space and for setting the colors and

their names. There is no verification on missing named colors, so the client must set sensible defaults when colors

are missing.

To assist with sorting, health levels have a numeric severity equal to their index in the sorted list of health

levels (starting at 1). This means higher numbers denote a more severe health.

Since these values are noting more than a list index, they should not be cached, compared to another organization or

compared to values retrieved from the API at another time.

For example, an organization using the default health would have:

- Ok: severity 1

- Warning: severity 2

- Error: severity 3

That organization could then add a new health level in between Ok and Warning, meaning the severity of Warning and

Error will change:

- Ok, severity 1

- ItsComplicated, severity 2

- Warning, severity 3

- Error, severity 4

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
levelstring

The name of this health level. -Levels are identified by their name. -The API does support renaming, where the rename is propagated to all the relevant parts of the system.

colorstring

Deprecated. Default color for the health level, as a string that represents a valid CSS3 color. -DEPRECATED: Maps to the color named "text" in color_data.

color_dataHealthLevel.ColorDataEntryrepeated

Map of named colors, where key is the name and the value is a valid CSS3 color definition.

severityint64

A numeric value equal to the index of this health level in the sorted list of health levels (starting at 1). -This means higher numbers denote a more severe health.

catch_allbool

Precisely one health level can be assigned as a catch-all for any unknown health levels from alarms (or Hiber systems), -which can happen when a device manufacturer has provided alarms for your device (e.g. a low battery alarm). -By default, unknown health levels map to the level of the highest severity, -unless another level is marked as catch-all.

- - - - -

Fields with deprecated option

- - - - - - - - - - - - - - - -
NameOption
color

true

- - - - - -

HealthLevel.ColorDataEntry

-

- - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
keystring

valuestring

- - - - - -

HealthLevelSelection

-

- - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
searchstring

Search for the given string in the levels and colors.

levelsstringrepeated

Filter by exact levels.

- - - - - -

ListHealthLevels

-

- - - - - -

ListHealthLevels.Request

-

- - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
organizationstring

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

selectionHealthLevelSelection

- - - - - -

ListHealthLevels.Response

-

- - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
health_levelsHealthLevelrepeated

requestListHealthLevels.Request

- - - - - -

RemoveHealthLevel

-

- - - - - -

RemoveHealthLevel.Request

-

- - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
organizationstring

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

levelstring

- - - - - -

RemoveHealthLevel.Response

-

- - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
health_levelsHealthLevelrepeated

- - - - - -

ReorderHealthLevels

-

Re-order the health levels for your organization.

- - - - - -

ReorderHealthLevels.Request

-

- - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
organizationstring

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

levelsstringrepeated

The health levels for the organization, ordered by severity (low to high). -This list must include _all_ health levels, or the call will fail. -The implication is, that if someone adds, removes or renames a level just before this call is sent, -then this call will fail to protect against strange results.

- - - - - -

ReorderHealthLevels.Response

-

- - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
reordered_health_levelsHealthLevelrepeated

- - - - - -

UpdateHealthLevel

-

- - - - - -

UpdateHealthLevel.Request

-

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
organizationstring

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

levelstring

renamestring

Optionally, rename this health level. -NOTE! Don't use this to change the semantics of a health level. -All historic events that have this health-level will change with it. -(Unless you are very sure you want to change history, that is)

update_colorhiber.UpdateClearableString

Deprecated. Optionally, set or update the color for this health level. -DEPRECATED, use add_colors with name "text". -Vice versa, this field will also update the "text" color in the color_data field of HealthLevel.

remove_colorsstringrepeated

Remove colors by name. Will remove the named color from the color_data field in HealthLevel.

add_colorsUpdateHealthLevel.Request.AddColorsEntryrepeated

Add colors by name. Will add the named color from the color_data field in HealthLevel. -For backwards compatibility reasons, if add_colors contains a color named "text", it will also update -the field color in HealthLevel

update_catch_allhiber.UpdateBoolean

Optionally, set or unset the catch all flag.

- - - - -

Fields with deprecated option

- - - - - - - - - - - - - - - -
NameOption
update_color

true

- - - - - -

UpdateHealthLevel.Request.AddColorsEntry

-

- - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
keystring

valuestring

- - - - - -

UpdateHealthLevel.Response

-

- - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
health_levelsHealthLevelrepeated

- - - - - - - - - - - -

HealthService

-

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Method NameRequest TypeResponse TypeDescription
ListListHealthLevels.RequestListHealthLevels.Response

List the health levels.

ReorderReorderHealthLevels.RequestReorderHealthLevels.Response

Reorder the health levels, changing the order of severity.

AddAddHealthLevel.RequestAddHealthLevel.Response

Add a new health level at the end of the list (highest severity).

UpdateUpdateHealthLevel.RequestUpdateHealthLevel.Response

Update or rename a health level.

RemoveRemoveHealthLevel.RequestRemoveHealthLevel.Response

Remove a health level. Any events with that level are redirected to the catch-all level.

- - - - -
-

tag.proto

Top -
-

- - -

CreateTagRequest

-

- - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
organizationstring

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

createTag.Label

- - - - - -

DeleteTagRequest

-

- - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
organizationstring

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

idint64

- - - - - -

DeleteTagRequest.Response

-

- - - - - -

ListTagsRequest

-

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
organizationstring

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

selectionTagSelection

modem_countbool

webhook_countbool

- - - - - -

ListTagsRequest.Response

-

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
tagsTagrepeated

requestListTagsRequest

tag_modem_countListTagsRequest.Response.TagModemCountEntryrepeated

tag_webhook_countListTagsRequest.Response.TagWebhookCountEntryrepeated

- - - - - -

ListTagsRequest.Response.TagModemCountEntry

-

- - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
keyint64

valueint32

- - - - - -

ListTagsRequest.Response.TagWebhookCountEntry

-

- - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
keyint64

valueint32

- - - - - -

Tag

-

- - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
idint64

labelTag.Label

- - - - - -

Tag.Label

-

- - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
namestring

- - - - - -

TagSelection

-

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
searchstringrepeated

namesstringrepeated

filterhiber.Filter.Tags

- - - - - -

UpdateTagRequest

-

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
organizationstring

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

idint64

updateTag.Label

- - - - - -

UpdateTagsForItem

-

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
tag_ids_to_addint64repeated

tag_ids_to_removeint64repeated

new_tags_to_addTag.Labelrepeated

- - - - - - - - - - - -

TagService

-

Tag management api calls. You can already get tags for objects when you get their data, and even create new tags

when updating them, so these calls are meant for easier tag management if you need it.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Method NameRequest TypeResponse TypeDescription
ListListTagsRequestListTagsRequest.Response

CreateCreateTagRequestTag

UpdateUpdateTagRequestTag

DeleteDeleteTagRequestDeleteTagRequest.Response

- - - - -
-

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

- - - - - -

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.

- - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
urlstring

A URL that contains the location of avatar. -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)

imageNamedFile

The data of the avatar as a Named File -When showing this 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:<media-type>;base64,<base64-encoded-bytes> - -Other type clients should be able to sort-of-directly set the data bytes as the source for an image.

- - - - - -

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

- - - - - -

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.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
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. -The 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. - -Also note that this file may contain characters that cannot be a valid file name on certain systems. - -Specific API calls may limit the validness of this field. -For example setting a maximum length or disallowing certain characters.

- - - - - -

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

- - - - - -

TimeRange

-

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

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

- - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeLabelDescription
timestampgoogle.protobuf.Timestamp

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_STALE16

MODEM_MESSAGE_RECEIVED5

MODEM_MESSAGE_BODY_PARSED39

MODEM_MESSAGE_BODY_RECEIVED45

MODEM_MESSAGE_DROPPED13

MODEM_MESSAGE_DELAYED14

MODEM_MESSAGE_CANNOT_BE_PARSED15

MODEM_MESSAGE_SUMMARY42

MODEM_MESSAGE_BODY_PARSER_CREATED46

MODEM_MESSAGE_BODY_PARSER_UPDATED47

MODEM_MESSAGE_BODY_PARSER_DELETED48

MODEM_MESSAGE_BODY_PARSER_AUTOMATIC_ASSIGNMENT_CREATED49

MODEM_MESSAGE_BODY_PARSER_AUTOMATIC_ASSIGNMENT_UPDATED50

MODEM_MESSAGE_BODY_PARSER_AUTOMATIC_ASSIGNMENT_DELETED51

MODEM_MESSAGE_BODY_PARSER_ASSIGNED52

MODEM_MESSAGE_BODY_PARSER_UNASSIGNED53

MODEM_ALARM56

MODEM_ALARM_CREATED57

MODEM_ALARM_UPDATED58

MODEM_ALARM_DELETED59

DIRECT_ASSIGNMENT_ADDED63

DIRECT_ASSIGNMENT_REMOVED64

AUTOMATIC_MODEM_ASSIGNMENT_CREATED60

AUTOMATIC_MODEM_ASSIGNMENT_UPDATED61

AUTOMATIC_MODEM_ASSIGNMENT_DELETED62

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

- - - - - - - -

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/easypulse.md b/docs/easypulse.md index 253e25c..a3de27f 100644 --- a/docs/easypulse.md +++ b/docs/easypulse.md @@ -1,559 +1,324 @@ -# Protocol Documentation - +# easypulse.proto -## Table of Contents - -- [easypulse.proto](#easypulse.proto) - - [Easypulse](#hiber.easypulse.Easypulse) - - [Easypulse.Asset](#hiber.easypulse.Easypulse.Asset) - - [Easypulse.Asset.AggregationsEntry](#hiber.easypulse.Easypulse.Asset.AggregationsEntry) - - [Easypulse.Asset.LastUpdate](#hiber.easypulse.Easypulse.Asset.LastUpdate) - - [Easypulse.Asset.PeripheralsEntry](#hiber.easypulse.Easypulse.Asset.PeripheralsEntry) - - [Easypulse.AssetSelection](#hiber.easypulse.Easypulse.AssetSelection) - - [Easypulse.History](#hiber.easypulse.Easypulse.History) - - [Easypulse.History.Request](#hiber.easypulse.Easypulse.History.Request) - - [Easypulse.History.Response](#hiber.easypulse.Easypulse.History.Response) - - [Easypulse.History.Response.Value](#hiber.easypulse.Easypulse.History.Response.Value) - - [Easypulse.ListAssets](#hiber.easypulse.Easypulse.ListAssets) - - [Easypulse.ListAssets.Request](#hiber.easypulse.Easypulse.ListAssets.Request) - - [Easypulse.ListAssets.Request.AggregationsEntry](#hiber.easypulse.Easypulse.ListAssets.Request.AggregationsEntry) - - [Easypulse.ListAssets.Response](#hiber.easypulse.Easypulse.ListAssets.Response) - - [Easypulse.UpdateAssets](#hiber.easypulse.Easypulse.UpdateAssets) - - [Easypulse.UpdateAssets.Request](#hiber.easypulse.Easypulse.UpdateAssets.Request) - - [Easypulse.UpdateAssets.Request.AddPeripheralsEntry](#hiber.easypulse.Easypulse.UpdateAssets.Request.AddPeripheralsEntry) - - [Easypulse.UpdateAssets.Response](#hiber.easypulse.Easypulse.UpdateAssets.Response) - - - [Easypulse.History.Request.Aggregation](#hiber.easypulse.Easypulse.History.Request.Aggregation) - - [Easypulse.ListAssets.Request.Sort](#hiber.easypulse.Easypulse.ListAssets.Request.Sort) - - - [EasypulseService](#hiber.easypulse.EasypulseService) - -- [health.proto](#health.proto) - - [AddHealthLevel](#hiber.health.AddHealthLevel) - - [AddHealthLevel.Request](#hiber.health.AddHealthLevel.Request) - - [AddHealthLevel.Response](#hiber.health.AddHealthLevel.Response) - - [HealthLevel](#hiber.health.HealthLevel) - - [HealthLevel.ColorDataEntry](#hiber.health.HealthLevel.ColorDataEntry) - - [HealthLevelSelection](#hiber.health.HealthLevelSelection) - - [ListHealthLevels](#hiber.health.ListHealthLevels) - - [ListHealthLevels.Request](#hiber.health.ListHealthLevels.Request) - - [ListHealthLevels.Response](#hiber.health.ListHealthLevels.Response) - - [RemoveHealthLevel](#hiber.health.RemoveHealthLevel) - - [RemoveHealthLevel.Request](#hiber.health.RemoveHealthLevel.Request) - - [RemoveHealthLevel.Response](#hiber.health.RemoveHealthLevel.Response) - - [ReorderHealthLevels](#hiber.health.ReorderHealthLevels) - - [ReorderHealthLevels.Request](#hiber.health.ReorderHealthLevels.Request) - - [ReorderHealthLevels.Response](#hiber.health.ReorderHealthLevels.Response) - - [UpdateHealthLevel](#hiber.health.UpdateHealthLevel) - - [UpdateHealthLevel.Request](#hiber.health.UpdateHealthLevel.Request) - - [UpdateHealthLevel.Request.AddColorsEntry](#hiber.health.UpdateHealthLevel.Request.AddColorsEntry) - - [UpdateHealthLevel.Response](#hiber.health.UpdateHealthLevel.Response) - - - [HealthService](#hiber.health.HealthService) - -- [tag.proto](#tag.proto) - - [CreateTagRequest](#hiber.tag.CreateTagRequest) - - [DeleteTagRequest](#hiber.tag.DeleteTagRequest) - - [DeleteTagRequest.Response](#hiber.tag.DeleteTagRequest.Response) - - [ListTagsRequest](#hiber.tag.ListTagsRequest) - - [ListTagsRequest.Response](#hiber.tag.ListTagsRequest.Response) - - [ListTagsRequest.Response.TagModemCountEntry](#hiber.tag.ListTagsRequest.Response.TagModemCountEntry) - - [ListTagsRequest.Response.TagWebhookCountEntry](#hiber.tag.ListTagsRequest.Response.TagWebhookCountEntry) - - [Tag](#hiber.tag.Tag) - - [Tag.Label](#hiber.tag.Tag.Label) - - [TagSelection](#hiber.tag.TagSelection) - - [UpdateTagRequest](#hiber.tag.UpdateTagRequest) - - [UpdateTagsForItem](#hiber.tag.UpdateTagsForItem) - - - [TagService](#hiber.tag.TagService) - -- [base.proto](#base.proto) - - [Area](#hiber.Area) - - [Avatar](#hiber.Avatar) - - [BytesOrHex](#hiber.BytesOrHex) - - [BytesOrHex.Update](#hiber.BytesOrHex.Update) - - [Date](#hiber.Date) - - [DoubleRange](#hiber.DoubleRange) - - [Duration](#hiber.Duration) - - [Filter](#hiber.Filter) - - [Filter.ChildOrganizations](#hiber.Filter.ChildOrganizations) - - [Filter.ChildOrganizations.Update](#hiber.Filter.ChildOrganizations.Update) - - [Filter.Events](#hiber.Filter.Events) - - [Filter.Events.Update](#hiber.Filter.Events.Update) - - [Filter.Modems](#hiber.Filter.Modems) - - [Filter.Modems.Update](#hiber.Filter.Modems.Update) - - [Filter.OrganizationPermissions](#hiber.Filter.OrganizationPermissions) - - [Filter.Organizations](#hiber.Filter.Organizations) - - [Filter.Publishers](#hiber.Filter.Publishers) - - [Filter.Tags](#hiber.Filter.Tags) - - [Filter.Tags.Update](#hiber.Filter.Tags.Update) - - [Filter.UserPermissions](#hiber.Filter.UserPermissions) - - [Filter.Users](#hiber.Filter.Users) - - [Filter.Webhooks](#hiber.Filter.Webhooks) - - [Location](#hiber.Location) - - [LocationSelection](#hiber.LocationSelection) - - [NamedFile](#hiber.NamedFile) - - [Pagination](#hiber.Pagination) - - [Pagination.Result](#hiber.Pagination.Result) - - [Shape](#hiber.Shape) - - [TimeRange](#hiber.TimeRange) - - [Timestamp](#hiber.Timestamp) - - [UpdateBoolean](#hiber.UpdateBoolean) - - [UpdateClearableString](#hiber.UpdateClearableString) - - [UpdateOptionalDuration](#hiber.UpdateOptionalDuration) - - [UpdateOptionalId](#hiber.UpdateOptionalId) - - [UpdateZeroableInt](#hiber.UpdateZeroableInt) - - - [EventType](#hiber.EventType) - - [Health](#hiber.Health) - -- [Scalar Value Types](#scalar-value-types) - - - - -

Top

- -## easypulse.proto Easypulse specific view and services. This file contains specific views and services for the easypulse feature set. This feature set is only available to organizations with the easypulse feature enabled. -For Easypulse, we've introduced the concept of an Asset, which is a modem with some assumptions about the type of +For Easypulse, we've introduced the concept of an Asset, which is a modem with some assumptions about the type of data it sends. Additionally, aggregations can be requested of Asset history when requesting Assets, allowing for a somewhat customized Asset model. +#### This file was generated from [easypulse.proto](https://github.com/HiberGlobal/api/blob/master/easypulse.proto). - - -### Easypulse - - - - +## Table of Contents +- Services + - [EasypulseService](#easypulseservice) + +- Messages + - [Easypulse](#easypulse) + - [Easypulse.Asset](#easypulseasset) + - [Easypulse.Asset.AggregationsEntry](#easypulseassetaggregationsentry) + - [Easypulse.Asset.LastUpdate](#easypulseassetlastupdate) + - [Easypulse.Asset.PeripheralsEntry](#easypulseassetperipheralsentry) + - [Easypulse.AssetSelection](#easypulseassetselection) + - [Easypulse.History](#easypulsehistory) + - [Easypulse.History.Request](#easypulsehistoryrequest) + - [Easypulse.History.Response](#easypulsehistoryresponse) + - [Easypulse.History.Response.Value](#easypulsehistoryresponsevalue) + - [Easypulse.ListAssets](#easypulselistassets) + - [Easypulse.ListAssets.Request](#easypulselistassetsrequest) + - [Easypulse.ListAssets.Request.AggregationsEntry](#easypulselistassetsrequestaggregationsentry) + - [Easypulse.ListAssets.Response](#easypulselistassetsresponse) + +- Enums + - [Easypulse.History.Request.Aggregation](#easypulsehistoryrequestaggregation) + - [Easypulse.ListAssets.Request.Sort](#easypulselistassetsrequestsort) + +- Referenced messages from [health.proto](#referenced-messages-from-healthproto) + - [hiber.health.HealthLevel](#hiberhealthhealthlevel) + - [hiber.health.HealthLevelSelection](#hiberhealthhealthlevelselection) + + +- Referenced messages from [tag.proto](#referenced-messages-from-tagproto) + - [hiber.tag.Tag](#hibertagtag) + - [hiber.tag.Tag.Label](#hibertagtaglabel) + - [hiber.tag.TagSelection](#hibertagtagselection) + + +- 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.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) - -### Easypulse.Asset -Asset in your organization. -An asset is a view of a modem, with assumptions about message data fields handled in the API. +## EasypulseService +Service to list and manage Assets. -In addition, an Asset can be enriched with aggregations of the data fields when requested (for example, -fuel level average over the past month, or total run time in the past week). +### Assets +> **rpc** Assets([Easypulse.ListAssets.Request](#easypulselistassetsrequest)) + [Easypulse.ListAssets.Response](#easypulselistassetsresponse) +List the Easypulse Assets in your organization. +Optionally, aggregated historical data can be added to the returned Assets, with a given name. -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| organization | [string](#string) | | The organization the asset is in. | -| number | [string](#string) | | The modem number for the Asset. | -| name | [string](#string) | | The custom name for the Asset, defaults to modem number. | -| external_identifier | [string](#string) | | Optional external identifier the Asset may have. | -| peripherals | [Easypulse.Asset.PeripheralsEntry](#hiber.easypulse.Easypulse.Asset.PeripheralsEntry) | repeated | A key value map of peripherals for the Assets. | -| notes | [string](#string) | | Add additional notes to an asset. | -| secure_notes | [string](#string) | | Add additional notes to an asset that only people with the permission can access. | -| health_level | [hiber.health.HealthLevel](#hiber.health.HealthLevel) | | Health level based on the modem alarm and some always-present alarms. | -| tags | [hiber.tag.Tag](#hiber.tag.Tag) | repeated | Tags (or groups, when used in Mission Control) this asset is in. | -| last_update | [Easypulse.Asset.LastUpdate](#hiber.easypulse.Easypulse.Asset.LastUpdate) | | When this asset was last updated. | -| fuel_level | [float](#float) | | The most recent fuel level, as a percentage. | -| tire_pressure | [float](#float) | | The most recent tire pressure in bar. | -| battery_level | [float](#float) | | The most recent battery level, as a percentage. | -| temperature | [float](#float) | | The most recent temperature in degrees Celsius. | -| location | [hiber.Location](#hiber.Location) | | The most recently reported location. | -| aggregations | [Easypulse.Asset.AggregationsEntry](#hiber.easypulse.Easypulse.Asset.AggregationsEntry) | repeated | Any aggregations added when this asset was requested. | +Fails when your organizations does not have the Easypulse feature. +### History +> **rpc** History([Easypulse.History.Request](#easypulsehistoryrequest)) + [Easypulse.History.Response](#easypulsehistoryresponse) +List the history for a single field, and optionally apply an aggregation and/or grouping to it. +## Messages +### Easypulse - -### Easypulse.Asset.AggregationsEntry +### Easypulse.Asset -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| key | [string](#string) | | | -| value | [Easypulse.History.Response](#hiber.easypulse.Easypulse.History.Response) | | | +Asset in your organization. +An asset is a view of a modem, with assumptions about message data fields handled in the API. +In addition, an Asset can be enriched with aggregations of the data fields when requested (for example, +fuel level average over the past month, or total run time in the past week). +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | The organization the asset is in. | +| number | [ string](#string) | The modem number for the Asset. | +| name | [ string](#string) | The custom name for the Asset, defaults to modem number. | +| external_identifier | [ string](#string) | Optional external identifier the Asset may have. | +| peripherals | [map Easypulse.Asset.PeripheralsEntry](#easypulseassetperipheralsentry) | A key value map of peripherals for the Assets. | +| notes | [ string](#string) | Add additional notes to an asset. | +| secure_notes | [ string](#string) | Add additional notes to an asset that only people with the permission can access. | +| health_level | [ hiber.health.HealthLevel](#hiberhealthhealthlevel) | Health level based on the modem alarm and some always-present alarms. | +| tags | [repeated hiber.tag.Tag](#hibertagtag) | Tags (or groups, when used in Mission Control) this asset is in. | +| last_update | [ Easypulse.Asset.LastUpdate](#easypulseassetlastupdate) | When this asset was last updated. | +| fuel_level | [ float](#float) | The most recent fuel level, as a percentage. | +| tire_pressure | [ float](#float) | The most recent tire pressure in bar. | +| battery_level | [ float](#float) | The most recent battery level, as a percentage. | +| temperature | [ float](#float) | The most recent temperature in degrees Celsius. | +| location | [ hiber.Location](#hiberlocation) | The most recently reported location. | +| aggregations | [map Easypulse.Asset.AggregationsEntry](#easypulseassetaggregationsentry) | Any aggregations added when this asset was requested. | +### Easypulse.Asset.AggregationsEntry - +| Field | Type | Description | +| ----- | ---- | ----------- | +| key | [ string](#string) | none | +| value | [ Easypulse.History.Response](#easypulsehistoryresponse) | none | ### Easypulse.Asset.LastUpdate -Information about the last update we received from this asset. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| id | [uint64](#uint64) | | | -| received_at | [hiber.Timestamp](#hiber.Timestamp) | | Time the server has received the last update. | -| sent_at | [hiber.Timestamp](#hiber.Timestamp) | | Time the asset sent the last update. | -| body | [hiber.BytesOrHex](#hiber.BytesOrHex) | | The body of the last update. | - - - - +Information about the last update we received from this asset. - +| Field | Type | Description | +| ----- | ---- | ----------- | +| id | [ uint64](#uint64) | none | +| received_at | [ hiber.Timestamp](#hibertimestamp) | Time the server has received the last update. | +| sent_at | [ hiber.Timestamp](#hibertimestamp) | Time the asset sent the last update. | +| body | [ hiber.BytesOrHex](#hiberbytesorhex) | The body of the last update. | ### Easypulse.Asset.PeripheralsEntry -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| key | [string](#string) | | | -| value | [string](#string) | | | - - - - - - - +| Field | Type | Description | +| ----- | ---- | ----------- | +| key | [ string](#string) | none | +| value | [ string](#string) | none | ### Easypulse.AssetSelection + An AssetSelection is used to select which Assets should be affected: - When listing Assets, it is used to determine which Assets are returned - When updating Assets, it is used to determine which Assets are updated - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| search | [string](#string) | | Search for assets by name, modem number, tag or notes. | -| assets | [hiber.Filter.Modems](#hiber.Filter.Modems) | | Select assets by modem number. | -| health_levels | [string](#string) | repeated | Select assets by health level. | -| filter_by_tags | [hiber.tag.TagSelection](#hiber.tag.TagSelection) | | Select assets by tag. | - - - - - - - +| Field | Type | Description | +| ----- | ---- | ----------- | +| search | [ string](#string) | Search for assets by name, modem number, tag or notes. | +| assets | [ hiber.Filter.Modems](#hiberfiltermodems) | Select assets by modem number. | +| health_levels | [repeated string](#string) | Select assets by health level. | +| filter_by_tags | [ hiber.tag.TagSelection](#hibertagtagselection) | Select assets by tag. | ### Easypulse.History -List the history for a single field, and optionally apply an aggregation and/or grouping to it. - - - - +List the history for a single field, and optionally apply an aggregation and/or grouping to it. - ### Easypulse.History.Request -Request to get the history of a field, for the selected Assets in the organization. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| organization | [string](#string) | | Pick the organization to use (/impersonate). If unset, your default organization is used. | -| selection | [Easypulse.AssetSelection](#hiber.easypulse.Easypulse.AssetSelection) | | Select the asset(s) to update. | -| time_range | [hiber.TimeRange](#hiber.TimeRange) | | The time to view the history for. | -| aggregation | [Easypulse.History.Request.Aggregation](#hiber.easypulse.Easypulse.History.Request.Aggregation) | | How to aggregate the data. | -| split_by_duration | [hiber.Duration](#hiber.Duration) | | Split up the data in time block of the given size. | -| reduce_to_max_size | [uint32](#uint32) | | Limit the results to the given amount of data points, applying the function to each chunk. | -| fuel_level | [bool](#bool) | | Get the history for the fuel level. Only one field can be chosen. | -| tire_pressure | [bool](#bool) | | Get the history for the tire pressure. Only one field can be chosen. | -| battery_level | [bool](#bool) | | Get the history for the battery level. Only one field can be chosen. | -| temperature | [bool](#bool) | | Get the history for the temperature. Only one field can be chosen. | -| run_time | [bool](#bool) | | Get the history for the run time. Only one field can be chosen. | -| idle_time | [bool](#bool) | | Get the history for the idle time. Only one field can be chosen. | - - - - +Request to get the history of a field, for the selected Assets in the organization. - +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| selection | [ Easypulse.AssetSelection](#easypulseassetselection) | Select the asset(s) to get the history for. | +| pagination | [ hiber.Pagination](#hiberpagination) | Paginate the returned values. This may not be relevant, depending on the aggregation (which may result in a single value) and the time range. | +| time_range | [ hiber.TimeRange](#hibertimerange) | The time to view the history for. | +| aggregation | [ Easypulse.History.Request.Aggregation](#easypulsehistoryrequestaggregation) | How to aggregate the data. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **group**.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) **group**.reduce_to_max_size | [ uint32](#uint32) | Limit the results to the given amount of data points, applying the function to each chunk. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **field**.fuel_level | [ bool](#bool) | Get the history for the fuel level. Only one field can be chosen. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **field**.tire_pressure | [ bool](#bool) | Get the history for the tire pressure. Only one field can be chosen. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **field**.battery_level | [ bool](#bool) | Get the history for the battery level. Only one field can be chosen. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **field**.temperature | [ bool](#bool) | Get the history for the temperature. Only one field can be chosen. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **field**.run_time | [ bool](#bool) | Get the history for the run time. Only one field can be chosen. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **field**.idle_time | [ bool](#bool) | Get the history for the idle time. Only one field can be chosen. | ### Easypulse.History.Response -Response with the (aggregated) history of a field, for the selected Assets in the organization. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| values | [Easypulse.History.Response.Value](#hiber.easypulse.Easypulse.History.Response.Value) | repeated | 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. | -| request | [Easypulse.History.Request](#hiber.easypulse.Easypulse.History.Request) | | The request that was received, corrected and used to produce this result. | - - - - +Response with the (aggregated) history of a field, for the selected Assets in the organization. - +| Field | Type | Description | +| ----- | ---- | ----------- | +| values | [repeated Easypulse.History.Response.Value](#easypulsehistoryresponsevalue) | 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. | +| pagination | [ hiber.Pagination.Result](#hiberpaginationresult) | The pagination result, containing information about amounts and pages. | +| request | [ Easypulse.History.Request](#easypulsehistoryrequest) | The request that was received, corrected and used to produce this result. | ### Easypulse.History.Response.Value -Processed historical data point. If this is a group, it will have a time range to denote the group. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| timestamp | [hiber.Timestamp](#hiber.Timestamp) | | When not grouping, time of the individual point. When grouping, the time at the end of the group (when the value was true). | -| time_range | [hiber.TimeRange](#hiber.TimeRange) | | When grouping, the start and end time for the group. | -| fuel_level | [float](#float) | | The fuel level, as a percentage. | -| tire_pressure | [float](#float) | | The tire pressure in bar. | -| battery_level | [float](#float) | | The battery level, as a percentage. | -| temperature | [float](#float) | | The temperature in degrees Celsius. | -| run_time | [hiber.Duration](#hiber.Duration) | | The time the Asset was running. | -| idle_time | [hiber.Duration](#hiber.Duration) | | The time the Asset was idle. | - - - - +Processed historical data point. If this is a group, it will have a time range to denote the group. - +| Field | Type | Description | +| ----- | ---- | ----------- | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **time**.timestamp | [ hiber.Timestamp](#hibertimestamp) | When not grouping, time of the individual point. When grouping, the time at the end of the group (when the value was true). | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **time**.time_range | [ hiber.TimeRange](#hibertimerange) | When grouping, the start and end time for the group. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **value**.fuel_level | [ float](#float) | The fuel level, as a percentage. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **value**.tire_pressure | [ float](#float) | The tire pressure in bar. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **value**.battery_level | [ float](#float) | The battery level, as a percentage. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **value**.temperature | [ float](#float) | The temperature in degrees Celsius. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **value**.run_time | [ hiber.Duration](#hiberduration) | The time the Asset was running. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **value**.idle_time | [ hiber.Duration](#hiberduration) | The time the Asset was idle. | ### Easypulse.ListAssets + List the Easypulse Assets in your organization. Optionally, aggregated historical data can be added to the returned Assets, with a given name. Fails when your organizations does not have the Easypulse feature. - - - - - - ### Easypulse.ListAssets.Request -Request to list Assets in your organization. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| organization | [string](#string) | | Pick the organization to use (/impersonate). If unset, your default organization is used. | -| selection | [Easypulse.AssetSelection](#hiber.easypulse.Easypulse.AssetSelection) | | Select the Assets to return. | -| pagination | [hiber.Pagination](#hiber.Pagination) | | Paginate over the returned Assets. | -| aggregations | [Easypulse.ListAssets.Request.AggregationsEntry](#hiber.easypulse.Easypulse.ListAssets.Request.AggregationsEntry) | repeated | Any aggregations to return with the assets, specified as a name and a History.Request. | -| sort | [Easypulse.ListAssets.Request.Sort](#hiber.easypulse.Easypulse.ListAssets.Request.Sort) | | Sort the returned assets using the given option. By default, Assets are sorted by name. | - - - - +Request to list Assets in your organization. - +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| selection | [ Easypulse.AssetSelection](#easypulseassetselection) | Select the Assets to return. | +| pagination | [ hiber.Pagination](#hiberpagination) | Paginate over the returned Assets. | +| aggregations | [map Easypulse.ListAssets.Request.AggregationsEntry](#easypulselistassetsrequestaggregationsentry) | Any aggregations to return with the assets, specified as a name and a History.Request. | +| sort | [ Easypulse.ListAssets.Request.Sort](#easypulselistassetsrequestsort) | Sort the returned assets using the given option. By default, Assets are sorted by name. | ### Easypulse.ListAssets.Request.AggregationsEntry -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| key | [string](#string) | | | -| value | [Easypulse.History.Request](#hiber.easypulse.Easypulse.History.Request) | | | - - - - - - - +| Field | Type | Description | +| ----- | ---- | ----------- | +| key | [ string](#string) | none | +| value | [ Easypulse.History.Request](#easypulsehistoryrequest) | none | ### Easypulse.ListAssets.Response -Response with a list of Assets - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| assets | [Easypulse.Asset](#hiber.easypulse.Easypulse.Asset) | repeated | The selected Assets. | -| pagination | [hiber.Pagination.Result](#hiber.Pagination.Result) | | The applied pagination, including total results, page information, etc. | -| request | [Easypulse.ListAssets.Request](#hiber.easypulse.Easypulse.ListAssets.Request) | | The request that was received, corrected and used to produce this result. | - - - - - - - - -### Easypulse.UpdateAssets -Update your Assets, renaming, updating tags, etc. - -Produces a ModemUpdated event with the changed values. - - - - - - - - -### Easypulse.UpdateAssets.Request -Request to update your Assets, renaming, updating tags, etc. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| organization | [string](#string) | | Pick the organization to use (/impersonate). If unset, your default organization is used. | -| selection | [Easypulse.AssetSelection](#hiber.easypulse.Easypulse.AssetSelection) | | Select the asset(s) to update. | -| result_pagination | [hiber.Pagination](#hiber.Pagination) | | Pagination for the returned assets. Does not affect the amount of assets that are updated. | -| rename | [string](#string) | | Change the asset name to the given value. Ignored if empty. | -| notes | [string](#string) | | Update the notes for the selected assets. Expects the original notes to be identical, unless allow_override_existing_notes is set. | -| secure_notes | [string](#string) | | Update the secure notes for the selected assets. Expects the original notes to be identical, unless allow_override_existing_notes is set. | -| update_tags | [hiber.tag.UpdateTagsForItem](#hiber.tag.UpdateTagsForItem) | | Update the tags for the selected assets. | -| add_peripherals | [Easypulse.UpdateAssets.Request.AddPeripheralsEntry](#hiber.easypulse.Easypulse.UpdateAssets.Request.AddPeripheralsEntry) | repeated | Add or update peripherals for the selected assets. | -| remove_peripherals | [string](#string) | repeated | Remove peripherals from the selected assets. | -| allow_override_existing_notes | [bool](#bool) | | When you try to set a new notes value to multiple assets, the API returns an error if their previous values were different. Set this to true to apply it anyway. | - - - +Response with a list of Assets +| Field | Type | Description | +| ----- | ---- | ----------- | +| assets | [repeated Easypulse.Asset](#easypulseasset) | The selected Assets. | +| pagination | [ hiber.Pagination.Result](#hiberpaginationresult) | The applied pagination, including total results, page information, etc. | +| request | [ Easypulse.ListAssets.Request](#easypulselistassetsrequest) | The request that was received, corrected and used to produce this result. | - - -### Easypulse.UpdateAssets.Request.AddPeripheralsEntry - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| key | [string](#string) | | | -| value | [string](#string) | | | - - - - - - - - -### Easypulse.UpdateAssets.Response -The updated Assets, paginated to limit the returned amount. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| assets | [Easypulse.Asset](#hiber.easypulse.Easypulse.Asset) | repeated | The (page of) updated Assets. | -| pagination | [hiber.Pagination.Result](#hiber.Pagination.Result) | | The applied pagination, including total results, page information, etc. | -| request | [Easypulse.UpdateAssets.Request](#hiber.easypulse.Easypulse.UpdateAssets.Request) | | The request that was received, corrected and used to produce this result. | - - - - - - - - - +## Enums ### Easypulse.History.Request.Aggregation Options to aggregate the history data points (in a group). -| Name | Number | Description | -| ---- | ------ | ----------- | -| NONE | 0 | Do not aggregate the history data points, just list all of them. | -| AVERAGE | 1 | Average value of all history data points (in a group). | -| SUM | 2 | Sum all history data points (in a group). | - - - - +| Name | Description | Number | +| ---- | ----------- | ------ | +| NONE | Do not aggregate the history data points, just list all of them. | 0 | +| AVERAGE | Average value of all history data points (in a group). | 1 | +| SUM | Sum all history data points (in a group). | 2 | ### Easypulse.ListAssets.Request.Sort -| Name | Number | Description | -| ---- | ------ | ----------- | -| NAME | 0 | | -| NAME_DESC | 1 | | -| LAST_UPDATED | 2 | | -| INACTIVITY | 3 | | -| NUMBER_ASC | 4 | | -| NUMBER_DESC | 5 | | -| LOWEST_FUEL_LEVEL | 6 | | -| HIGHEST_FUEL_LEVEL | 7 | | -| LOWEST_TIRE_PRESSURE | 8 | | -| HIGHEST_TIRE_PRESSURE | 9 | | -| LOWEST_BATTERY_LEVEL | 10 | | -| HIGHEST_BATTERY_LEVEL | 11 | | - - - - - - - - - -### EasypulseService -Service to list and manage Assets. - -| Method Name | Request Type | Response Type | Description | -| ----------- | ------------ | ------------- | ------------| -| Assets | [Easypulse.ListAssets.Request](#hiber.easypulse.Easypulse.ListAssets.Request) | [Easypulse.ListAssets.Response](#hiber.easypulse.Easypulse.ListAssets.Response) | | -| Update | [Easypulse.UpdateAssets.Request](#hiber.easypulse.Easypulse.UpdateAssets.Request) | [Easypulse.UpdateAssets.Response](#hiber.easypulse.Easypulse.UpdateAssets.Response) | | -| History | [Easypulse.History.Request](#hiber.easypulse.Easypulse.History.Request) | [Easypulse.History.Response](#hiber.easypulse.Easypulse.History.Response) | | - - - - - - -

Top

- -## health.proto - - - - - -### AddHealthLevel - - - - - - - - +| Name | Description | Number | +| ---- | ----------- | ------ | +| NAME | none | 0 | +| NAME_DESC | none | 1 | +| LAST_UPDATED | none | 2 | +| INACTIVITY | none | 3 | +| NUMBER_ASC | none | 4 | +| NUMBER_DESC | none | 5 | +| LOWEST_FUEL_LEVEL | none | 6 | +| HIGHEST_FUEL_LEVEL | none | 7 | +| LOWEST_TIRE_PRESSURE | none | 8 | +| HIGHEST_TIRE_PRESSURE | none | 9 | +| LOWEST_BATTERY_LEVEL | none | 10 | +| HIGHEST_BATTERY_LEVEL | none | 11 | +| LOWEST_TEMPERATURE | none | 12 | +| HIGHEST_TEMPERATURE | none | 13 | +| HEALTH | Health sorted from least to most severe (i.e. OK, WARNING, ERROR). | 14 | +| HEALTH_DESC | Health sorted from most to least severe (i.e. ERROR, WARNING, OK). | 15 | -### AddHealthLevel.Request +## Referenced messages from health.proto +(Note that these are included because there is a proto dependency on the file, +so not all messages listed here are referenced.) -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| organization | [string](#string) | | Pick the organization to use (/impersonate). If unset, your default organization is used. | -| new_health_level | [HealthLevel](#hiber.health.HealthLevel) | | Add the given level to the organizations health levels. The new health level will be added with the highest severity (at the bottom of the health levels list). | +#### This section was generated from [health.proto](https://github.com/HiberGlobal/api/blob/master/health.proto). +### hiber.health.HealthLevel - - - - - -### AddHealthLevel.Response - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| health_levels | [HealthLevel](#hiber.health.HealthLevel) | repeated | | - - - - - - - - -### HealthLevel A health level in an organization. Health can be customized depending on your need. @@ -585,7 +350,7 @@ and the value is a string that represents a valid CSS3 color. Simple examples are: green, red, orange, grey, #FF00FF for fuchsia, etc (Keep in mind that CSS3 allows for many ways to define colors, see https://www.w3.org/TR/2003/WD-css3-color-20030214/). -All the following definitions also mean "red": +All the following definitions also mean "red": - rgb(255, 0, 0) - rgb(100%, 0, 0) - rgba(100%, 0%, 0%, 100%) @@ -613,1234 +378,609 @@ Error will change: - Warning, severity 3 - Error, severity 4 +| Field | Type | Description | +| ----- | ---- | ----------- | +| level | [ string](#string) | The name of this health level. Levels are identified by their name. The API does support renaming, where the rename is propagated to all the relevant parts of the system. | +| color | [ string](#string) | Default color for the health level, as a string that represents a valid CSS3 color. DEPRECATED: Maps to the color named "text" in color_data. | +| color_data | [map hiber.health.HealthLevel.ColorDataEntry](#hiberhealthhealthlevelcolordataentry) | Map of named colors, where key is the name and the value is a valid CSS3 color definition. | +| severity | [ int64](#int64) | A numeric value equal to the index of this health level in the sorted list of health levels (starting at 1). This means higher numbers denote a more severe health. | +| catch_all | [ bool](#bool) | Precisely one health level can be assigned as a catch-all for any unknown health levels from alarms (or Hiber systems), which can happen when a device manufacturer has provided alarms for your device (e.g. a low battery alarm). By default, unknown health levels map to the level of the highest severity, unless another level is marked as catch-all. | -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| level | [string](#string) | | The name of this health level. Levels are identified by their name. The API does support renaming, where the rename is propagated to all the relevant parts of the system. | -| color | [string](#string) | | **Deprecated.** Default color for the health level, as a string that represents a valid CSS3 color. DEPRECATED: Maps to the color named "text" in color_data. | -| color_data | [HealthLevel.ColorDataEntry](#hiber.health.HealthLevel.ColorDataEntry) | repeated | Map of named colors, where key is the name and the value is a valid CSS3 color definition. | -| severity | [int64](#int64) | | A numeric value equal to the index of this health level in the sorted list of health levels (starting at 1). This means higher numbers denote a more severe health. | -| catch_all | [bool](#bool) | | Precisely one health level can be assigned as a catch-all for any unknown health levels from alarms (or Hiber systems), which can happen when a device manufacturer has provided alarms for your device (e.g. a low battery alarm). By default, unknown health levels map to the level of the highest severity, unless another level is marked as catch-all. | +### hiber.health.HealthLevelSelection +| Field | Type | Description | +| ----- | ---- | ----------- | +| search | [ string](#string) | Search for the given string in the levels and colors. | +| levels | [repeated string](#string) | Filter by exact levels. | +### Enums - -### HealthLevel.ColorDataEntry +## Referenced messages from tag.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 [tag.proto](https://github.com/HiberGlobal/api/blob/master/tag.proto). -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| key | [string](#string) | | | -| value | [string](#string) | | | +### hiber.tag.Tag +| Field | Type | Description | +| ----- | ---- | ----------- | +| id | [ int64](#int64) | none | +| label | [ hiber.tag.Tag.Label](#hibertagtaglabel) | none | +### hiber.tag.Tag.Label - -### HealthLevelSelection +| Field | Type | Description | +| ----- | ---- | ----------- | +| name | [ string](#string) | none | +### hiber.tag.TagSelection -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| search | [string](#string) | | Search for the given string in the levels and colors. | -| levels | [string](#string) | repeated | Filter by exact levels. | +| Field | Type | Description | +| ----- | ---- | ----------- | +| search | [repeated string](#string) | none | +| names | [repeated string](#string) | none | +| filter | [ hiber.Filter.Tags](#hiberfiltertags) | none | +### Enums +## 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). -### ListHealthLevels +### 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) -### ListHealthLevels.Request +| 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. -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| organization | [string](#string) | | Pick the organization to use (/impersonate). If unset, your default organization is used. | -| selection | [HealthLevelSelection](#hiber.health.HealthLevelSelection) | | | +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 -### ListHealthLevels.Response +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 | Label | Description | -| ----- | ---- | ----- | ----------- | -| health_levels | [HealthLevel](#hiber.health.HealthLevel) | repeated | | -| request | [ListHealthLevels.Request](#hiber.health.ListHealthLevels.Request) | | | +| 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 - -### RemoveHealthLevel +| 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. -### RemoveHealthLevel.Request +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 -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| organization | [string](#string) | | Pick the organization to use (/impersonate). If unset, your default organization is used. | -| level | [string](#string) | | | +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 -### RemoveHealthLevel.Response +Update object to update a Filter.Events field. +| Field | Type | Description | +| ----- | ---- | ----------- | +| updated | [ bool](#bool) | none | +| value | [ hiber.Filter.Events](#hiberfilterevents) | none | +### hiber.Filter.Modems -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| health_levels | [HealthLevel](#hiber.health.HealthLevel) | repeated | | +| 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 -### ReorderHealthLevels -Re-order the health levels for your organization. +| 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 | -### ReorderHealthLevels.Request +### hiber.Filter.Publishers -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| organization | [string](#string) | | Pick the organization to use (/impersonate). If unset, your default organization is used. | -| levels | [string](#string) | repeated | The health levels for the organization, ordered by severity (low to high). This list must include _all_ health levels, or the call will fail. The implication is, that if someone adds, removes or renames a level just before this call is sent, then this call will fail to protect against strange results. | +| 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. -### ReorderHealthLevels.Response +| Field | Type | Description | +| ----- | ---- | ----------- | +| updated | [ bool](#bool) | none | +| value | [ hiber.Filter.Tags](#hiberfiltertags) | none | +### hiber.Filter.UserPermissions -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| reordered_health_levels | [HealthLevel](#hiber.health.HealthLevel) | repeated | | +| 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 -### UpdateHealthLevel +| 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. -### UpdateHealthLevel.Request +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 -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| organization | [string](#string) | | Pick the organization to use (/impersonate). If unset, your default organization is used. | -| level | [string](#string) | | | -| rename | [string](#string) | | Optionally, rename this health level. NOTE! Don't use this to change the semantics of a health level. All historic events that have this health-level will change with it. (Unless you are very sure you want to change history, that is) | -| update_color | [hiber.UpdateClearableString](#hiber.UpdateClearableString) | | **Deprecated.** Optionally, set or update the color for this health level. DEPRECATED, use add_colors with name "text". Vice versa, this field will also update the "text" color in the color_data field of HealthLevel. | -| remove_colors | [string](#string) | repeated | Remove colors by name. Will remove the named color from the color_data field in HealthLevel. | -| add_colors | [UpdateHealthLevel.Request.AddColorsEntry](#hiber.health.UpdateHealthLevel.Request.AddColorsEntry) | repeated | Add colors by name. Will add the named color from the color_data field in HealthLevel. For backwards compatibility reasons, if add_colors contains a color named "text", it will also update the field color in HealthLevel | -| update_catch_all | [hiber.UpdateBoolean](#hiber.UpdateBoolean) | | Optionally, set or unset the catch all flag. | +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. -### UpdateHealthLevel.Request.AddColorsEntry +| 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. -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| key | [string](#string) | | | -| value | [string](#string) | | | +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. | -### UpdateHealthLevel.Response +### 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 | Label | Description | -| ----- | ---- | ----- | ----------- | -| health_levels | [HealthLevel](#hiber.health.HealthLevel) | repeated | | +| 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. +| 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. +| Field | Type | Description | +| ----- | ---- | ----------- | +| timestamp | [ google.protobuf.Timestamp](#googleprotobuftimestamp) | none | +| textual | [ string](#string) | none | - +### hiber.UpdateBoolean -### HealthService +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. -| Method Name | Request Type | Response Type | Description | -| ----------- | ------------ | ------------- | ------------| -| List | [ListHealthLevels.Request](#hiber.health.ListHealthLevels.Request) | [ListHealthLevels.Response](#hiber.health.ListHealthLevels.Response) | List the health levels. | -| Reorder | [ReorderHealthLevels.Request](#hiber.health.ReorderHealthLevels.Request) | [ReorderHealthLevels.Response](#hiber.health.ReorderHealthLevels.Response) | Reorder the health levels, changing the order of severity. | -| Add | [AddHealthLevel.Request](#hiber.health.AddHealthLevel.Request) | [AddHealthLevel.Response](#hiber.health.AddHealthLevel.Response) | Add a new health level at the end of the list (highest severity). | -| Update | [UpdateHealthLevel.Request](#hiber.health.UpdateHealthLevel.Request) | [UpdateHealthLevel.Response](#hiber.health.UpdateHealthLevel.Response) | Update or rename a health level. | -| Remove | [RemoveHealthLevel.Request](#hiber.health.RemoveHealthLevel.Request) | [RemoveHealthLevel.Response](#hiber.health.RemoveHealthLevel.Response) | Remove a health level. Any events with that level are redirected to the catch-all level. | +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. - -

Top

+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. -## tag.proto +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. -### CreateTagRequest +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 -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| organization | [string](#string) | | Pick the organization to use (/impersonate). If unset, your default organization is used. | -| create | [Tag.Label](#hiber.tag.Tag.Label) | | | +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. - - - -### DeleteTagRequest - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| organization | [string](#string) | | Pick the organization to use (/impersonate). If unset, your default organization is used. | -| id | [int64](#int64) | | | - - - - - - - - -### DeleteTagRequest.Response - - - - - - - - - -### ListTagsRequest - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| organization | [string](#string) | | Pick the organization to use (/impersonate). If unset, your default organization is used. | -| selection | [TagSelection](#hiber.tag.TagSelection) | | | -| modem_count | [bool](#bool) | | | -| webhook_count | [bool](#bool) | | | - - - - - - - - -### ListTagsRequest.Response - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| tags | [Tag](#hiber.tag.Tag) | repeated | | -| request | [ListTagsRequest](#hiber.tag.ListTagsRequest) | | | -| tag_modem_count | [ListTagsRequest.Response.TagModemCountEntry](#hiber.tag.ListTagsRequest.Response.TagModemCountEntry) | repeated | | -| tag_webhook_count | [ListTagsRequest.Response.TagWebhookCountEntry](#hiber.tag.ListTagsRequest.Response.TagWebhookCountEntry) | repeated | | - - - - - - - - -### ListTagsRequest.Response.TagModemCountEntry - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| key | [int64](#int64) | | | -| value | [int32](#int32) | | | - - - - - - - - -### ListTagsRequest.Response.TagWebhookCountEntry - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| key | [int64](#int64) | | | -| value | [int32](#int32) | | | - - - - - - - - -### Tag - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| id | [int64](#int64) | | | -| label | [Tag.Label](#hiber.tag.Tag.Label) | | | - - - - - - - - -### Tag.Label - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| name | [string](#string) | | | - - - - - - - - -### TagSelection - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| search | [string](#string) | repeated | | -| names | [string](#string) | repeated | | -| filter | [hiber.Filter.Tags](#hiber.Filter.Tags) | | | - - - - - - - - -### UpdateTagRequest - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| organization | [string](#string) | | Pick the organization to use (/impersonate). If unset, your default organization is used. | -| id | [int64](#int64) | | | -| update | [Tag.Label](#hiber.tag.Tag.Label) | | | - - - - - - - - -### UpdateTagsForItem - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| tag_ids_to_add | [int64](#int64) | repeated | | -| tag_ids_to_remove | [int64](#int64) | repeated | | -| new_tags_to_add | [Tag.Label](#hiber.tag.Tag.Label) | repeated | | - - - - - - - - - - - - - - -### TagService -Tag management api calls. You can already get tags for objects when you get their data, and even create new tags -when updating them, so these calls are meant for easier tag management if you need it. - -| Method Name | Request Type | Response Type | Description | -| ----------- | ------------ | ------------- | ------------| -| List | [ListTagsRequest](#hiber.tag.ListTagsRequest) | [ListTagsRequest.Response](#hiber.tag.ListTagsRequest.Response) | | -| Create | [CreateTagRequest](#hiber.tag.CreateTagRequest) | [Tag](#hiber.tag.Tag) | | -| Update | [UpdateTagRequest](#hiber.tag.UpdateTagRequest) | [Tag](#hiber.tag.Tag) | | -| Delete | [DeleteTagRequest](#hiber.tag.DeleteTagRequest) | [DeleteTagRequest.Response](#hiber.tag.DeleteTagRequest.Response) | | - - - - - - -

Top

- -## base.proto - - - - - -### 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 | Label | Description | -| ----- | ---- | ----- | ----------- | -| center | [Location](#hiber.Location) | | | -| bottom_left | [Location](#hiber.Location) | | | -| top_right | [Location](#hiber.Location) | | | - - - - - - - - -### 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. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| url | [string](#string) | | A URL that contains the location of avatar. 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) | -| image | [NamedFile](#hiber.NamedFile) | | The data of the avatar as a Named File When showing this 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:<media-type>;base64,<base64-encoded-bytes> - -Other type clients should be able to sort-of-directly set the data bytes as the source for an image. | - - - - - - - - -### 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 | Label | Description | -| ----- | ---- | ----- | ----------- | -| bytes | [bytes](#bytes) | | | -| hex | [string](#string) | | | - - - - - - - - -### BytesOrHex.Update - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| updated | [bool](#bool) | | | -| value | [BytesOrHex](#hiber.BytesOrHex) | | | - - - - - - - - -### 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 | Label | Description | -| ----- | ---- | ----- | ----------- | -| year | [uint32](#uint32) | | | -| month | [uint32](#uint32) | | | -| day | [uint32](#uint32) | | | -| textual | [string](#string) | | | - - - - - - - - -### DoubleRange -Decimal range. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| start | [double](#double) | | | -| end | [double](#double) | | | - - - - - - - - -### Duration - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| duration | [google.protobuf.Duration](#google.protobuf.Duration) | | | -| textual | [string](#string) | | | - - - - - - - - -### 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 - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| include_all | [bool](#bool) | | | -| include | [string](#string) | repeated | | -| exclude | [string](#string) | repeated | | - - - - - - - - -### Filter.ChildOrganizations.Update -Update object to update a Filter.ChildOrganizations field. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| updated | [bool](#bool) | | | -| value | [Filter.ChildOrganizations](#hiber.Filter.ChildOrganizations) | | | - - - - - - - - -### Filter.Events - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| include | [EventType](#hiber.EventType) | repeated | | -| exclude | [EventType](#hiber.EventType) | repeated | | - - - - - - - - -### Filter.Events.Update -Update object to update a Filter.Events field. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| updated | [bool](#bool) | | | -| value | [Filter.Events](#hiber.Filter.Events) | | | - - - - - - - - -### Filter.Modems - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| include | [string](#string) | repeated | Include all modems with these modem numbers (HEX) | -| exclude | [string](#string) | repeated | Exclude all modems with these modem numbers (HEX). Exclude takes precedence over include. | - - - - - - - - -### Filter.Modems.Update -Update object to update a Filter.Modems field. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| updated | [bool](#bool) | | | -| value | [Filter.Modems](#hiber.Filter.Modems) | | | - - - - - - - - -### Filter.OrganizationPermissions - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| include_all | [bool](#bool) | | | -| include | [OrganizationPermission](#hiber.OrganizationPermission) | repeated | | -| exclude | [OrganizationPermission](#hiber.OrganizationPermission) | repeated | | - - - - - - - - -### Filter.Organizations - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| include | [string](#string) | repeated | | -| exclude | [string](#string) | repeated | | - - - - - - - - -### Filter.Publishers - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| include | [int64](#int64) | repeated | | -| exclude | [int64](#int64) | repeated | | -| only_active | [bool](#bool) | | | - - - - - - - - -### Filter.Tags - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| include | [int64](#int64) | repeated | | -| exclude | [int64](#int64) | repeated | | - - - - - - - - -### Filter.Tags.Update -Update object to update a Filter.Tags field. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| updated | [bool](#bool) | | | -| value | [Filter.Tags](#hiber.Filter.Tags) | | | - - - - - - - - -### Filter.UserPermissions - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| include_all | [bool](#bool) | | | -| include | [UserPermission](#hiber.UserPermission) | repeated | | -| exclude | [UserPermission](#hiber.UserPermission) | repeated | | - - - - - - - - -### Filter.Users - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| include | [string](#string) | repeated | | -| exclude | [string](#string) | repeated | | - - - - - - - - -### Filter.Webhooks - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| include | [int64](#int64) | repeated | | -| exclude | [int64](#int64) | repeated | | -| only_active | [bool](#bool) | | | - - - - - - - - -### 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 | Label | Description | -| ----- | ---- | ----- | ----------- | -| latitude | [double](#double) | | Decimal degrees north. | -| longitude | [double](#double) | | Decimal degrees east. | - - - - - - - - -### 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 | Label | Description | -| ----- | ---- | ----- | ----------- | -| areas | [Area](#hiber.Area) | repeated | Rectangular areas, each defined by two locations, normalized to bottom-left and top-right points. | -| shapes | [Shape](#hiber.Shape) | repeated | 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. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| data | [BytesOrHex](#hiber.BytesOrHex) | | 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. The 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. - -Also note that this file may contain characters that cannot be a valid file name on certain systems. - -Specific API calls may limit the validness of this field. For example setting a maximum length or disallowing certain characters. | - - - - - - - - -### 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 | Label | Description | -| ----- | ---- | ----- | ----------- | -| size | [int32](#int32) | | | -| page | [int32](#int32) | | | - - - - - - - - -### Pagination.Result - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| size | [int32](#int32) | | | -| page | [int32](#int32) | | | -| total | [int32](#int32) | | | -| total_pages | [int32](#int32) | | | -| previous | [Pagination](#hiber.Pagination) | | | -| next | [Pagination](#hiber.Pagination) | | | -| 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. | - - - - - - - - -### 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 | Label | Description | -| ----- | ---- | ----- | ----------- | -| path | [Location](#hiber.Location) | repeated | | - - - - - - - - -### TimeRange -Period of time between two timestamps. Typically used for filtering. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| start | [Timestamp](#hiber.Timestamp) | | | -| end | [Timestamp](#hiber.Timestamp) | | | - - - - - - - - -### 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. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| timestamp | [google.protobuf.Timestamp](#google.protobuf.Timestamp) | | | -| textual | [string](#string) | | | - - - - - - - - -### 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 | Label | Description | -| ----- | ---- | ----- | ----------- | -| updated | [bool](#bool) | | | -| value | [bool](#bool) | | | - - - - - - - - -### 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 | Label | Description | -| ----- | ---- | ----- | ----------- | -| updated | [bool](#bool) | | | -| value | [string](#string) | | | - - - - - - - - -### 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 | Label | Description | -| ----- | ---- | ----- | ----------- | -| updated | [bool](#bool) | | | -| value | [Duration](#hiber.Duration) | | | - - - - - - - - -### 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 | Label | Description | -| ----- | ---- | ----- | ----------- | -| updated | [bool](#bool) | | | -| value | [int64](#int64) | | | - - - - - - - - -### 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 | Label | Description | -| ----- | ---- | ----- | ----------- | -| updated | [bool](#bool) | | | -| value | [uint32](#uint32) | | | - - - - - - +| Field | Type | Description | +| ----- | ---- | ----------- | +| updated | [ bool](#bool) | none | +| value | [ uint32](#uint32) | none | - - -### EventType +### 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 | Number | Description | -| ---- | ------ | ----------- | -| DEFAULT | 0 | | -| ORGANIZATION_CREATED | 34 | | -| ORGANIZATION_UPDATED | 12 | | -| ORGANIZATION_DELETED | 35 | | -| ORGANIZATION_EVENT_CONFIGURATION_UPDATED | 43 | | -| MODEM_CREATED | 55 | | -| MODEM_UPDATED | 36 | | -| MODEM_LOCATION_UPDATED | 4 | | -| MODEM_ACTIVATED | 33 | | -| MODEM_STALE | 16 | | -| MODEM_MESSAGE_RECEIVED | 5 | | -| MODEM_MESSAGE_BODY_PARSED | 39 | | -| MODEM_MESSAGE_BODY_RECEIVED | 45 | | -| MODEM_MESSAGE_DROPPED | 13 | | -| MODEM_MESSAGE_DELAYED | 14 | | -| MODEM_MESSAGE_CANNOT_BE_PARSED | 15 | | -| MODEM_MESSAGE_SUMMARY | 42 | | -| MODEM_MESSAGE_BODY_PARSER_CREATED | 46 | | -| MODEM_MESSAGE_BODY_PARSER_UPDATED | 47 | | -| MODEM_MESSAGE_BODY_PARSER_DELETED | 48 | | -| MODEM_MESSAGE_BODY_PARSER_AUTOMATIC_ASSIGNMENT_CREATED | 49 | | -| MODEM_MESSAGE_BODY_PARSER_AUTOMATIC_ASSIGNMENT_UPDATED | 50 | | -| MODEM_MESSAGE_BODY_PARSER_AUTOMATIC_ASSIGNMENT_DELETED | 51 | | -| MODEM_MESSAGE_BODY_PARSER_ASSIGNED | 52 | | -| MODEM_MESSAGE_BODY_PARSER_UNASSIGNED | 53 | | -| MODEM_ALARM | 56 | | -| MODEM_ALARM_CREATED | 57 | | -| MODEM_ALARM_UPDATED | 58 | | -| MODEM_ALARM_DELETED | 59 | | -| DIRECT_ASSIGNMENT_ADDED | 63 | | -| DIRECT_ASSIGNMENT_REMOVED | 64 | | -| AUTOMATIC_MODEM_ASSIGNMENT_CREATED | 60 | | -| AUTOMATIC_MODEM_ASSIGNMENT_UPDATED | 61 | | -| AUTOMATIC_MODEM_ASSIGNMENT_DELETED | 62 | | -| MODEM_TRANSFER_STARTED | 17 | | -| MODEM_TRANSFER_RECEIVED | 18 | | -| MODEM_TRANSFER_CANCELLED | 19 | | -| MODEM_TRANSFER_NOT_RECEIVED | 20 | | -| MODEM_TRANSFER_RETURN_TRANSFER_STARTED | 21 | | -| MODEM_CLAIMED | 22 | | -| PUBLISHER_CREATED | 1 | | -| PUBLISHER_UPDATED | 2 | | -| PUBLISHER_DELETED | 3 | | -| PUBLISHER_AUTO_DISABLED | 37 | | -| PUBLISHER_FAILED | 11 | | -| USER_ACCESS_REQUEST | 8 | | -| USER_INVITED | 38 | | -| USER_ADDED | 9 | | -| USER_REMOVED | 10 | | -| USER_VALIDATION_UPDATED | 54 | | -| TOKEN_CREATED | 31 | | -| TOKEN_EXPIRY_WARNING | 25 | | -| TOKEN_EXPIRED | 26 | | -| TOKEN_DELETED | 32 | | -| EXPORT_CREATED | 65 | | -| EXPORT_READY | 66 | | -| EXPORT_FAILED | 67 | | - - - - - -### Health +| 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_STALE | none | 16 | +| MODEM_MESSAGE_RECEIVED | none | 5 | +| MODEM_MESSAGE_BODY_PARSED | none | 39 | +| MODEM_MESSAGE_BODY_RECEIVED | none | 45 | +| MODEM_MESSAGE_DROPPED | none | 13 | +| MODEM_MESSAGE_DELAYED | none | 14 | +| 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_MESSAGE_BODY_PARSER_AUTOMATIC_ASSIGNMENT_CREATED | none | 49 | +| MODEM_MESSAGE_BODY_PARSER_AUTOMATIC_ASSIGNMENT_UPDATED | none | 50 | +| MODEM_MESSAGE_BODY_PARSER_AUTOMATIC_ASSIGNMENT_DELETED | none | 51 | +| MODEM_MESSAGE_BODY_PARSER_ASSIGNED | none | 52 | +| MODEM_MESSAGE_BODY_PARSER_UNASSIGNED | none | 53 | +| MODEM_ALARM | none | 56 | +| MODEM_ALARM_CREATED | none | 57 | +| MODEM_ALARM_UPDATED | none | 58 | +| MODEM_ALARM_DELETED | none | 59 | +| DIRECT_ASSIGNMENT_ADDED | none | 63 | +| DIRECT_ASSIGNMENT_REMOVED | none | 64 | +| AUTOMATIC_MODEM_ASSIGNMENT_CREATED | none | 60 | +| AUTOMATIC_MODEM_ASSIGNMENT_UPDATED | none | 61 | +| AUTOMATIC_MODEM_ASSIGNMENT_DELETED | none | 62 | +| 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 | Number | Description | -| ---- | ------ | ----------- | -| OK | 0 | | -| WARNING | 1 | | -| ERROR | 2 | | - - - - - - - - - +| 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_SECONDS | none | 1 | +| DURATION_MINUTES | none | 2 | +| DURATION_HOURS | none | 3 | +| DURATION_DAYS | none | 4 | +| TEMPERATURE_KELVIN | none | 5 | +| TEMPERATURE_DEGREES_CELSIUS | none | 6 | +| TEMPERATURE_DEGREES_FAHRENHEIT | none | 7 | +| DISTANCE_METER | none | 8 | +| DISTANCE_MILLIMETER | none | 9 | +| DISTANCE_CENTIMETER | none | 10 | +| DISTANCE_KILOMETER | none | 11 | +| PRESSURE_BAR | none | 12 | +| PRESSURE_BAR_GROUND | none | 13 | +| PRESSURE_PSI | none | 14 | +| VOLTAGE_MILLIVOLT | none | 15 | +| PERCENT | none | 16 | ## Scalar Value Types -| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby | -| ----------- | ----- | --- | ---- | ------ | -- | -- | --- | ---- | -| double | | double | double | float | float64 | double | float | Float | -| float | | float | float | float | float32 | 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 | int32 | int | integer | Bignum or Fixnum (as required) | -| 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 | int64 | long | integer/string | Bignum | -| uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) | -| uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) | -| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | -| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | int64 | long | integer/string | Bignum | -| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | uint32 | uint | integer | Bignum or Fixnum (as required) | -| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum | -| sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | -| sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum | -| bool | | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass | -| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) | -| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) | +| .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/map.md b/docs/map.md new file mode 100644 index 0000000..e13d181 --- /dev/null +++ b/docs/map.md @@ -0,0 +1,788 @@ +# map.proto + +Show modems on a map, using the calculated state of the map. + +Uses a tile-based system where the map is split up into tiles, and modems can be efficiently grouped into the tiles. +The tiles are based on the Google Maps output, which allows us to draw thousands of markers on a map efficiently. + +This works as follows: +Assume the world is a grid of 256x256 tiles, and every point can be represented as an x (from lon) and y (from lat) +coordinate, for example: +- (0,0) maps to world coordinate (128.0, 128.0) +- (13.24,122.04) maps roughly to (214.78, 118.49) +- (-84.27,175.36) maps roughly to (252.70, 250.05) +Keep in mind that the order is reversed, lat -> -y, long -> x, to get a grid that goes +from 0,0 at the bottom left of the map to 256,256 at the top right. + +Now that we have a simple numeric model of the world, we can start grouping numerically as well. +If we want 256 horizontal and 256 vertical tiles, all we have to do is `floor` the values to determine their tile. +Then, we can use the remainder to calculate their position within the tile on another 256x256 grid. +For example: +- (0,0) is in tile (128, 128) at (0.0,0.0) +- (13.24,122.04) is in tile (214, 118) +- (-84.27,175.36) is in tile (252, 250) + +While 65k tiles seems like a lot, it's not enough for the world, of course. So, we're using Google Maps' map levels +to have more detail. These increase in size exponentially: +- Level 0 : 1x1 : a single tile for the whole world, containing all of the modems +- Level 1 : 2x2 : 4 tiles for the whole world. +- Level 2 : 4x4 : 16 tiles for the whole world. +- Level 3 : 8x8 : 64 tiles for the whole world. +- Level 4 : 16x16 : 256 tiles for the whole world. +- Level 5 : 32x32 : 1024 tiles for the whole world. +- Level 6 : 64x64 : 4096 tiles for the whole world. +- Level 7 : 128x128 : 16 384 tiles for the whole world. +- Level 8 : 256x256 : 65 536 tiles for the whole world. +- Level 9 : 512x512 : 262 144 tiles for the whole world. +- Level 10 : 1024x1024 : 1 048 576 tiles for the whole world. +- Level 11 : 2048x2048 : 4 194 304 tiles for the whole world. +- Level 12 : 4096x4096 : 16 777 216 tiles for the whole world. +- Level 13 : 8192x8192 : 67 108 864 tiles for the whole world. +- Level 14 : 16384x16384 : 268 435 456 tiles for the whole world. +- Level 15 : 32768x32768 : 1 073 741 824 tiles for the whole world. +- Level 16 : 65536x65536 : 4 294 967 296 tiles for the whole world. +- Level 17 : 131072x131072 : 17 179 869 184 tiles for the whole world. +- Level 18 : 262144x262144 : 68 719 476 736 tiles for the whole world. +- Level 19 : 524288x524288 : 274 877 906 944 tiles for the whole world. +- Level 20 : 1048576x1048576 : 1 099 511 627 776 tiles for the whole world. +- Level 21 : 2097152x2097152 : 4 398 046 511 104 tiles for the whole world. + +Finally, we can do the same `floor`-based grouping within the tile. Using the TileMapRequest.Density, we decide +how many groups to split our tiles into. This means we can still align our tiles to Google Maps, but allow for +a controlled amount of groups. + +#### This file was generated from [map.proto](https://github.com/HiberGlobal/api/blob/master/map.proto). + +## Table of Contents + +- Services + - [MapService](#mapservice) + +- Messages + - [GroundStation](#groundstation) + - [MapTileItem](#maptileitem) + - [MapTileItem.Group](#maptileitemgroup) + - [MapTileItem.Modem](#maptileitemmodem) + - [Satellite](#satellite) + - [Satellite.Position](#satelliteposition) + - [TileCoordinate](#tilecoordinate) + - [TileMapRequest](#tilemaprequest) + - [TileMapRequest.Response](#tilemaprequestresponse) + +- Enums + - [TileMapRequest.Density](#tilemaprequestdensity) + +- 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.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) + + +## MapService +Map of modems, in different map levels to enable data to be displayed efficiently + +### TileMap +> **rpc** TileMap([TileMapRequest](#tilemaprequest)) + [TileMapRequest.Response](#tilemaprequestresponse) + +Show the selected modems on the map, in a selected area. + + +## Messages + +### GroundStation + +The location of ground stations that receive the data sent from the satellite(s). +Currently, ground station is just a marker on the map. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| location | [ hiber.Location](#hiberlocation) | none | +| name | [ string](#string) | none | + +### MapTileItem + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| tile | [ TileCoordinate](#tilecoordinate) | Google maps tile coordinates, counted from the top left of the map. | +| in_tile | [ TileCoordinate](#tilecoordinate) | Google maps in-tile coordinate, x axis, using a 256x256 grid in the tile. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **modems**.modem | [ MapTileItem.Modem](#maptileitemmodem) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **modems**.modem_group | [ MapTileItem.Group](#maptileitemgroup) | none | + +### MapTileItem.Group + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| count | [ int32](#int32) | none | +| area | [ hiber.Area](#hiberarea) | Area that the group covers. Modems are somewhere in this area. More details can be requested from the modem list or by zooming in, | +| most_severe_health_level | [ hiber.health.HealthLevel](#hiberhealthhealthlevel) | The most severe health for the modems in this group. | + +### MapTileItem.Modem + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| number | [ string](#string) | none | +| location | [ hiber.Location](#hiberlocation) | none | +| health_level | [ hiber.health.HealthLevel](#hiberhealthhealthlevel) | none | + +### Satellite + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| id | [ int32](#int32) | none | +| name | [ string](#string) | none | +| positions | [repeated Satellite.Position](#satelliteposition) | none | + +### Satellite.Position + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| time | [ hiber.Timestamp](#hibertimestamp) | none | +| location | [ hiber.Location](#hiberlocation) | none | + +### TileCoordinate + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| x | [ int32](#int32) | none | +| y | [ int32](#int32) | none | + +### TileMapRequest + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| selection | [ hiber.LocationSelection](#hiberlocationselection) | Visible part of the map. | +| level | [ int32](#int32) | Google Maps zoom level, from 0 to 21, where is a view of the whole world and 21 is zoomed in as possible. | +| modem_selection | [ hiber.modem.ModemSelection](#hibermodemmodemselection) | Selection to filter the modems on the map. | +| include_satellites | [ bool](#bool) | Whether to fill the "satellites" field in the Response. | +| include_ground_stations | [ bool](#bool) | Whether to fill the "ground_stations" field in the Response. | +| density | [ TileMapRequest.Density](#tilemaprequestdensity) | The icon density on the map. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **expanded**.child_organizations | [ hiber.Filter.ChildOrganizations](#hiberfilterchildorganizations) | Whether to include any modems from child organizations. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **expanded**.include_health | [ bool](#bool) | Whether to include the health for groups. | + +### TileMapRequest.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| ground_stations | [repeated GroundStation](#groundstation) | none | +| map_items | [repeated MapTileItem](#maptileitem) | none | +| request | [ TileMapRequest](#tilemaprequest) | none | +| satellites | [repeated Satellite](#satellite) | none | + + +## Enums +### TileMapRequest.Density + + +| Name | Description | Number | +| ---- | ----------- | ------ | +| DEFAULT | Fills a tile with 8x8 icons. | 0 | +| DENSE | Fills a tile with 16x16 icons. | 1 | +| SPARSE | Fills a tile with 4x4 icons. | 2 | +| VERY_SPARSE | Fills a tile with 2x2 icons. | 3 | +| SINGLE | Fills a tile with 1 icon. | 4 | + + + +## 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.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. + +| 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. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| timestamp | [ google.protobuf.Timestamp](#googleprotobuftimestamp) | 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_STALE | none | 16 | +| MODEM_MESSAGE_RECEIVED | none | 5 | +| MODEM_MESSAGE_BODY_PARSED | none | 39 | +| MODEM_MESSAGE_BODY_RECEIVED | none | 45 | +| MODEM_MESSAGE_DROPPED | none | 13 | +| MODEM_MESSAGE_DELAYED | none | 14 | +| 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_MESSAGE_BODY_PARSER_AUTOMATIC_ASSIGNMENT_CREATED | none | 49 | +| MODEM_MESSAGE_BODY_PARSER_AUTOMATIC_ASSIGNMENT_UPDATED | none | 50 | +| MODEM_MESSAGE_BODY_PARSER_AUTOMATIC_ASSIGNMENT_DELETED | none | 51 | +| MODEM_MESSAGE_BODY_PARSER_ASSIGNED | none | 52 | +| MODEM_MESSAGE_BODY_PARSER_UNASSIGNED | none | 53 | +| MODEM_ALARM | none | 56 | +| MODEM_ALARM_CREATED | none | 57 | +| MODEM_ALARM_UPDATED | none | 58 | +| MODEM_ALARM_DELETED | none | 59 | +| DIRECT_ASSIGNMENT_ADDED | none | 63 | +| DIRECT_ASSIGNMENT_REMOVED | none | 64 | +| AUTOMATIC_MODEM_ASSIGNMENT_CREATED | none | 60 | +| AUTOMATIC_MODEM_ASSIGNMENT_UPDATED | none | 61 | +| AUTOMATIC_MODEM_ASSIGNMENT_DELETED | none | 62 | +| 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_SECONDS | none | 1 | +| DURATION_MINUTES | none | 2 | +| DURATION_HOURS | none | 3 | +| DURATION_DAYS | none | 4 | +| TEMPERATURE_KELVIN | none | 5 | +| TEMPERATURE_DEGREES_CELSIUS | none | 6 | +| TEMPERATURE_DEGREES_FAHRENHEIT | none | 7 | +| DISTANCE_METER | none | 8 | +| DISTANCE_MILLIMETER | none | 9 | +| DISTANCE_CENTIMETER | none | 10 | +| DISTANCE_KILOMETER | none | 11 | +| PRESSURE_BAR | none | 12 | +| PRESSURE_BAR_GROUND | none | 13 | +| PRESSURE_PSI | none | 14 | +| VOLTAGE_MILLIVOLT | none | 15 | +| PERCENT | none | 16 | + +## 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/modem.md b/docs/modem.md new file mode 100644 index 0000000..1517540 --- /dev/null +++ b/docs/modem.md @@ -0,0 +1,1553 @@ +# modem.proto + +Modem and message management. + +Modems are anything capable of sending messages to the system. They have a unique modem number, +used to identify them. + +#### This file was generated from [modem.proto](https://github.com/HiberGlobal/api/blob/master/modem.proto). + +## Table of Contents + +- Services + - [ModemService](#modemservice) + +- Messages + - [AvailableModemMessageFields](#availablemodemmessagefields) + - [AvailableModemMessageFields.Request](#availablemodemmessagefieldsrequest) + - [AvailableModemMessageFields.Response](#availablemodemmessagefieldsresponse) + - [CreateModem](#createmodem) + - [CreateModem.Request](#createmodemrequest) + - [CreateModem.Request.PeripheralsEntry](#createmodemrequestperipheralsentry) + - [CreateModem.Response](#createmodemresponse) + - [CreateModem.Response.CreatedModem](#createmodemresponsecreatedmodem) + - [GetModemRequest](#getmodemrequest) + - [LicenseKeysRequest](#licensekeysrequest) + - [LicenseKeysRequest.Response](#licensekeysrequestresponse) + - [LicenseKeysRequest.Response.ModemLicenseKey](#licensekeysrequestresponsemodemlicensekey) + - [ListModemMessagesRequest](#listmodemmessagesrequest) + - [ListModemMessagesRequest.Response](#listmodemmessagesrequestresponse) + - [ListModemsGrouped](#listmodemsgrouped) + - [ListModemsGrouped.Request](#listmodemsgroupedrequest) + - [ListModemsGrouped.Response](#listmodemsgroupedresponse) + - [ListModemsRequest](#listmodemsrequest) + - [ListModemsRequest.Response](#listmodemsrequestresponse) + - [MessageCountRequest](#messagecountrequest) + - [MessageCountRequest.Response](#messagecountrequestresponse) + - [MessageCountRequest.Response.MessageCount](#messagecountrequestresponsemessagecount) + - [Modem](#modem) + - [Modem.ActiveSubscription](#modemactivesubscription) + - [Modem.ConnectedDeviceInfo](#modemconnecteddeviceinfo) + - [Modem.GatewayInfo](#modemgatewayinfo) + - [Modem.HealthConfig](#modemhealthconfig) + - [Modem.Peripherals](#modemperipherals) + - [Modem.Peripherals.PeripheralsEntry](#modemperipheralsperipheralsentry) + - [Modem.TechnicalData](#modemtechnicaldata) + - [Modem.Transfer](#modemtransfer) + - [ModemHealthCount](#modemhealthcount) + - [ModemHealthCount.HealthCount](#modemhealthcounthealthcount) + - [ModemHealthCount.HealthCountGroupedPerTag](#modemhealthcounthealthcountgroupedpertag) + - [ModemHealthCount.Request](#modemhealthcountrequest) + - [ModemHealthCount.Response](#modemhealthcountresponse) + - [ModemMessage](#modemmessage) + - [ModemMessage.ParsedBody](#modemmessageparsedbody) + - [ModemMessageFieldSelection](#modemmessagefieldselection) + - [ModemMessageSelection](#modemmessageselection) + - [ModemMessageSelection.ModemMessageSourceFilter](#modemmessageselectionmodemmessagesourcefilter) + - [ModemSelection](#modemselection) + - [ModemSelection.Peripherals](#modemselectionperipherals) + - [ModemSelection.Peripherals.ExcludeEntry](#modemselectionperipheralsexcludeentry) + - [ModemSelection.Peripherals.IncludeAndEntry](#modemselectionperipheralsincludeandentry) + - [ModemSelection.Peripherals.OneOfValues](#modemselectionperipheralsoneofvalues) + - [ModemSelection.Transfers](#modemselectiontransfers) + - [RenameModemRequest](#renamemodemrequest) + - [UpdateModemHealthConfig](#updatemodemhealthconfig) + - [UpdateModemHealthConfig.Request](#updatemodemhealthconfigrequest) + - [UpdateModemHealthConfig.Response](#updatemodemhealthconfigresponse) + - [UpdateModemNotesRequest](#updatemodemnotesrequest) + - [UpdateModemNotesRequest.Response](#updatemodemnotesrequestresponse) + - [UpdateModemSecureNotesRequest](#updatemodemsecurenotesrequest) + - [UpdateModemSecureNotesRequest.Response](#updatemodemsecurenotesrequestresponse) + - [UpdateModemStatusRequest](#updatemodemstatusrequest) + - [UpdateModemStatusRequest.Response](#updatemodemstatusrequestresponse) + - [UpdateModemTagsRequest](#updatemodemtagsrequest) + - [UpdateModemTagsRequest.Response](#updatemodemtagsrequestresponse) + - [UpdatePeripheralsRequest](#updateperipheralsrequest) + - [UpdatePeripheralsRequest.AddPeripheralsEntry](#updateperipheralsrequestaddperipheralsentry) + - [UpdatePeripheralsRequest.Response](#updateperipheralsrequestresponse) + +- Enums + - [ListModemsRequest.Sort](#listmodemsrequestsort) + - [Modem.Peripherals.HiberAntenna](#modemperipheralshiberantenna) + - [Modem.Status](#modemstatus) + - [Modem.Transfer.Status](#modemtransferstatus) + - [Modem.Type](#modemtype) + - [ModemMessage.Source](#modemmessagesource) + +- 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.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) + + +## 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. + +### Get +> **rpc** Get([GetModemRequest](#getmodemrequest)) + [Modem](#modem) + +Get a single modem. + +### Create +> **rpc** Create([CreateModem.Request](#createmodemrequest)) + [CreateModem.Response](#createmodemresponse) + +Create new modem(s). This is only available if your organization can create modems. + +### List +> **rpc** List([ListModemsRequest](#listmodemsrequest)) + [ListModemsRequest.Response](#listmodemsrequestresponse) + +List the modems in your organization, and, optionally, its child organizations. + +### Grouped +> **rpc** Grouped([ListModemsGrouped.Request](#listmodemsgroupedrequest)) + [ListModemsGrouped.Response](#listmodemsgroupedresponse) + +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. + +### Messages +> **rpc** Messages([ListModemMessagesRequest](#listmodemmessagesrequest)) + [ListModemMessagesRequest.Response](#listmodemmessagesrequestresponse) + +List messages for the selected modems. + +### MessageCount +> **rpc** MessageCount([MessageCountRequest](#messagecountrequest)) + [MessageCountRequest.Response](#messagecountrequestresponse) + +Count messages for the selected modems. + +### AvailableMessageFields +> **rpc** AvailableMessageFields([AvailableModemMessageFields.Request](#availablemodemmessagefieldsrequest)) + [AvailableModemMessageFields.Response](#availablemodemmessagefieldsresponse) + + + +### Rename +> **rpc** Rename([RenameModemRequest](#renamemodemrequest)) + [Modem](#modem) + +Change the name of a modem to the given value. + +### UpdateTags +> **rpc** UpdateTags([UpdateModemTagsRequest](#updatemodemtagsrequest)) + [UpdateModemTagsRequest.Response](#updatemodemtagsrequestresponse) + +Add, remove and create new tags for the selected modems. + +### UpdateNotes +> **rpc** UpdateNotes([UpdateModemNotesRequest](#updatemodemnotesrequest)) + [UpdateModemNotesRequest.Response](#updatemodemnotesrequestresponse) + +Change the notes for the selected modems to the given value. + +### UpdateSecureNotes +> **rpc** UpdateSecureNotes([UpdateModemSecureNotesRequest](#updatemodemsecurenotesrequest)) + [UpdateModemSecureNotesRequest.Response](#updatemodemsecurenotesrequestresponse) + +Change the secure notes for the selected modems to the given value, if you have permission. + +### UpdateStatus +> **rpc** UpdateStatus([UpdateModemStatusRequest](#updatemodemstatusrequest)) + [UpdateModemStatusRequest.Response](#updatemodemstatusrequestresponse) + +Change the status of the selected modems to the given value. + +### UpdateModemHealthConfig +> **rpc** UpdateModemHealthConfig([UpdateModemHealthConfig.Request](#updatemodemhealthconfigrequest)) + [UpdateModemHealthConfig.Response](#updatemodemhealthconfigresponse) + +Update the health configuration for the selected modems. + +### UpdatePeripherals +> **rpc** UpdatePeripherals([UpdatePeripheralsRequest](#updateperipheralsrequest)) + [UpdatePeripheralsRequest.Response](#updateperipheralsrequestresponse) + +Add and remove peripherals for the selected modems. + +### LicenseKeys +> **rpc** LicenseKeys([LicenseKeysRequest](#licensekeysrequest)) + [LicenseKeysRequest.Response](#licensekeysrequestresponse) + + + +### HealthCount +> **rpc** HealthCount([ModemHealthCount.Request](#modemhealthcountrequest)) + [ModemHealthCount.Response](#modemhealthcountresponse) + +Count the modems in your organization by health. + + +## Messages + +### AvailableModemMessageFields + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| modem | [ string](#string) | The modem the field specification is for. | +| fields | [ ModemMessageFieldSelection](#modemmessagefieldselection) | The available fields to be filtered. + +The message body fields are only set when the fields are marked explicitly using the data fields option on any assigned modem message body parsers. | + +### AvailableModemMessageFields.Request + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| modems | [ ModemSelection](#modemselection) | none | +| pagination | [ hiber.Pagination](#hiberpagination) | none | +| include_total | [ bool](#bool) | Whether to also calculate the total fields for all selected modems, and return them as a single ModemMessageFieldSelection in the response. This can be useful to display table columns, for example. | + +### AvailableModemMessageFields.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| modem_message_fields | [repeated AvailableModemMessageFields](#availablemodemmessagefields) | none | +| request | [ AvailableModemMessageFields.Request](#availablemodemmessagefieldsrequest) | none | +| pagination | [ hiber.Pagination.Result](#hiberpaginationresult) | none | +| total | [ ModemMessageFieldSelection](#modemmessagefieldselection) | A merged result of all fields, for all modems. This can be useful to display table columns, for example. | + +### 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 + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| amount | [ uint32](#uint32) | The amount of modems to create. | +| names | [repeated string](#string) | The name(s) to give the new modem(s). Must not contain more values than the amount of modems to create. | +| external_device_identifiers | [repeated string](#string) | 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. | +| status | [ Modem.Status](#modemstatus) | The status for the new modems. | +| technical | [ Modem.TechnicalData](#modemtechnicaldata) | The technical data, such as manufacturer and hardware information for the new modems. | +| peripherals | [map CreateModem.Request.PeripheralsEntry](#createmodemrequestperipheralsentry) | The peripherals for the new modems. | +| notes | [ string](#string) | Notes for all new modems. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **initial_location**.location | [ hiber.Location](#hiberlocation) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **initial_location**.random_location_in_area | [ hiber.Area](#hiberarea) | none | +| tags | [ hiber.tag.UpdateTagsForItem](#hibertagupdatetagsforitem) | The tags to set to the new modems, either existing or created by this call. | +| include_modems_in_response | [ bool](#bool) | Whether to return the full Modem in addition to the modem number and verification code. | +| include_verification_code | [ bool](#bool) | Whether to return the verification code for the modem. | + +### CreateModem.Request.PeripheralsEntry + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| key | [ string](#string) | none | +| value | [ string](#string) | none | + +### CreateModem.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| modems | [repeated CreateModem.Response.CreatedModem](#createmodemresponsecreatedmodem) | none | +| request | [ CreateModem.Request](#createmodemrequest) | none | + +### CreateModem.Response.CreatedModem + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| modem_number | [ string](#string) | The modem number that was created. | +| verification_code | [ string](#string) | The verification code for this modem number, used to, for example, claim modems. Only available when include_verification_code was set to true. | +| modem | [ Modem](#modem) | Only available when include_modems_in_response was set to true. | + +### GetModemRequest + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| modem_number | [ string](#string) | none | +| child_organizations | [ hiber.Filter.ChildOrganizations](#hiberfilterchildorganizations) | none | + +### LicenseKeysRequest + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| selection | [ ModemSelection](#modemselection) | none | +| pagination | [ hiber.Pagination](#hiberpagination) | none | + +### LicenseKeysRequest.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| request | [ LicenseKeysRequest](#licensekeysrequest) | none | +| license_keys | [repeated LicenseKeysRequest.Response.ModemLicenseKey](#licensekeysrequestresponsemodemlicensekey) | none | +| pagination | [ hiber.Pagination.Result](#hiberpaginationresult) | none | + +### LicenseKeysRequest.Response.ModemLicenseKey + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| modem_number | [ string](#string) | none | +| license_key | [ string](#string) | none | + +### ListModemMessagesRequest + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| selection | [ ModemMessageSelection](#modemmessageselection) | none | +| pagination | [ hiber.Pagination](#hiberpagination) | none | + +### ListModemMessagesRequest.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| messages | [repeated ModemMessage](#modemmessage) | none | +| request | [ ListModemMessagesRequest](#listmodemmessagesrequest) | none | +| pagination | [ hiber.Pagination.Result](#hiberpaginationresult) | none | + +### 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 + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| group_content | [ ListModemsRequest](#listmodemsrequest) | 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. | +| groups | [ ListModemsRequest](#listmodemsrequest) | 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_parent | [ bool](#bool) | 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 + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| groups | [repeated ListModemsRequest.Response](#listmodemsrequestresponse) | 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. | +| request | [ ListModemsGrouped.Request](#listmodemsgroupedrequest) | none | +| pagination | [ hiber.Pagination.Result](#hiberpaginationresult) | none | +| sorted_by | [repeated ListModemsRequest.Sort](#listmodemsrequestsort) | none | + +### ListModemsRequest + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| selection | [ ModemSelection](#modemselection) | Select which modems to return. | +| pagination | [ hiber.Pagination](#hiberpagination) | Paginate through results. | +| sort_by | [repeated ListModemsRequest.Sort](#listmodemsrequestsort) | Sort the modem with the given sort options. | +| include_inbound_modems | [ bool](#bool) | 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_modems | [ bool](#bool) | 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_organizations | [ hiber.Filter.ChildOrganizations](#hiberfilterchildorganizations) | Include modems from the selected child organizations. | +| location_selection | [ hiber.LocationSelection](#hiberlocationselection) | Filter modems by location. | +| include_missing_group_parents | [ bool](#bool) | 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. | + +### ListModemsRequest.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| modems | [repeated Modem](#modem) | none | +| request | [ ListModemsRequest](#listmodemsrequest) | none | +| pagination | [ hiber.Pagination.Result](#hiberpaginationresult) | none | +| sorted_by | [repeated ListModemsRequest.Sort](#listmodemsrequestsort) | none | +| group_parents | [repeated Modem](#modem) | 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 + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| selection | [ ModemMessageSelection](#modemmessageselection) | none | +| time_zone_offset | [ int32](#int32) | Numeric timezone offset for day grouping. Optional. | +| time_zone | [ string](#string) | Timezone string for day grouping. Optional. | + +### MessageCountRequest.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| message_count_per_day | [repeated MessageCountRequest.Response.MessageCount](#messagecountrequestresponsemessagecount) | none | +| request | [ MessageCountRequest](#messagecountrequest) | none | + +### MessageCountRequest.Response.MessageCount + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| date | [ hiber.Date](#hiberdate) | none | +| count | [ int32](#int32) | none | + +### 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. | +| maximum_inactivity_period | [ int32](#int32) | Period in days, if modem inactivity exceeds this period, alerts will be triggered and health will go to error | +| maximum_inactivity | [ hiber.Duration](#hiberduration) | If modem inactivity exceeds this period, alerts will be triggered and health will go to error | +| 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. | +| health_config | [ Modem.HealthConfig](#modemhealthconfig) | Health configuration for unresolvable built-in modem alarms, like delayed or skipped messages. | +| status | [ Modem.Status](#modemstatus) | none | +| active_subscription | [ Modem.ActiveSubscription](#modemactivesubscription) | additional information | +| technical | [ Modem.TechnicalData](#modemtechnicaldata) | none | +| peripherals | [ Modem.Peripherals](#modemperipherals) | none | +| in_transfer | [ Modem.Transfer](#modemtransfer) | 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 | [ Modem.Type](#modemtype) | The type of modem. Used mainly to differentiate in the UI or to sort on. | +| gateway_info | [ Modem.GatewayInfo](#modemgatewayinfo) | Additional information when this modem is a gateway. | +| connected_device_info | [ Modem.ConnectedDeviceInfo](#modemconnecteddeviceinfo) | Additional information when this modem is a connected device. | + +### Modem.ActiveSubscription + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| type | [ hiber.organization.subscription.ServiceType](#hiberorganizationsubscriptionservicetype) | none | +| start_date | [ hiber.Timestamp](#hibertimestamp) | none | +| end_date | [ hiber.Timestamp](#hibertimestamp) | none | + +### Modem.ConnectedDeviceInfo + +Additional information when this modem is a connected device. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| connected_to_gateway | [ string](#string) | 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_ids | [repeated string](#string) | External device ids for this modem. | + +### Modem.GatewayInfo + +Additional information when this modem is a gateway. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| number_of_connected_devices | [ int32](#int32) | none | + +### Modem.HealthConfig + +Health configuration for the modem. Defines how the health is calculated for certain built-in alarms. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| health_level | [ string](#string) | The health level that unresolvable alarms, like delayed or skipped messages, set the modem to. | +| health_unresolvable_period | [ hiber.Duration](#hiberduration) | Period to consider when determining health from warning events. Warning events cannot be resolved. | + +### 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. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| hiber_antenna | [ Modem.Peripherals.HiberAntenna](#modemperipheralshiberantenna) | none | +| gps | [ bool](#bool) | none | +| peripherals | [map Modem.Peripherals.PeripheralsEntry](#modemperipheralsperipheralsentry) | none | +| custom_antenna | [ string](#string) | none | + +### Modem.Peripherals.PeripheralsEntry + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| key | [ string](#string) | none | +| value | [ string](#string) | none | + +### Modem.TechnicalData + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| hardware_name | [ string](#string) | none | +| firmware_version_name | [ string](#string) | none | +| hardware_production_batch | [ string](#string) | none | +| manufacturer | [ string](#string) | none | + +### Modem.Transfer + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| status | [ Modem.Transfer.Status](#modemtransferstatus) | none | +| identifier | [ string](#string) | none | + +### ModemHealthCount + + + + +### ModemHealthCount.HealthCount + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| health_level | [ hiber.health.HealthLevel](#hiberhealthhealthlevel) | Health level based on the modem alarm and some always-present alarms. | +| count | [ uint32](#uint32) | The number of modems matching the modem selection with this health level | +| 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. | + +### ModemHealthCount.HealthCountGroupedPerTag + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| tag | [ hiber.tag.Tag](#hibertagtag) | The tag this count is for. | +| health_counts | [repeated ModemHealthCount.HealthCount](#modemhealthcounthealthcount) | none | + +### ModemHealthCount.Request + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| modem_selection | [ ModemSelection](#modemselection) | Selection of modems to count. If default, all modems are counted. | +| include_tag_count | [ bool](#bool) | Whether to return specific counts for tags, selected using the tag_count_selection. | +| tag_count_selection | [ hiber.tag.TagSelection](#hibertagtagselection) | Selection of tags to return specific counts for. If default, count is calculated for all tags. | + +### ModemHealthCount.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| health_totals | [repeated ModemHealthCount.HealthCount](#modemhealthcounthealthcount) | none | +| health_grouped_per_tag | [repeated ModemHealthCount.HealthCountGroupedPerTag](#modemhealthcounthealthcountgroupedpertag) | none | +| request | [ ModemHealthCount.Request](#modemhealthcountrequest) | none | + +### 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) + +| Field | Type | Description | +| ----- | ---- | ----------- | +| message_id | [ uint64](#uint64) | Unique message identifier. | +| modem_number | [ string](#string) | Modem number of the modem that sent the message. | +| modem_name | [ string](#string) | The name of the modem that sent the message. | +| modem_identifier | [ string](#string) | The device identifier for the modem that sent the message (e.g. a MAC address). | +| sent_at | [ hiber.Timestamp](#hibertimestamp) | Time the message was sent from the modem. | +| received_at | [ hiber.Timestamp](#hibertimestamp) | Time the message was received on the server. | +| location | [ hiber.Location](#hiberlocation) | Modem location when the message was sent. | +| body | [ bytes](#bytes) | Message body. | +| body_bytes | [ hiber.BytesOrHex](#hiberbytesorhex) | Message body convenience object. | +| body_parsed | [repeated ModemMessage.ParsedBody](#modemmessageparsedbody) | A list of applied body parsers and their results. | +| body_parsed_successfully | [ bool](#bool) | Convenience flag marking whether the body was parsed successfully by at least one parser. | +| sources | [repeated ModemMessage.Source](#modemmessagesource) | Message source(s) for this message (i.e. it was received through the satellite or directly to the server). | +| is_test | [ bool](#bool) | True if the the TEST source is in the sources. | +| is_gateway_message | [ bool](#bool) | Whether this message contains other messages. | +| via_gateway_message | [ uint64](#uint64) | The gateway message this message was sent in. | +| metadata | [ google.protobuf.Struct](#googleprotobufstruct) | Message metadata, defined by the modem or gateway. | +| body_fields | [ google.protobuf.Struct](#googleprotobufstruct) | 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. | +| tags | [repeated hiber.tag.Tag](#hibertagtag) | 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. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| parser_id | [ int32](#int32) | 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_identifier | [ string](#string) | Globally unique identifier of the parser that was used. | +| parser_name | [ string](#string) | Name of the parser that was used. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **parsed**.error | [ string](#string) | Error while parsing the message body. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **parsed**.result | [ google.protobuf.Struct](#googleprotobufstruct) | Result of parsing the body with this parser. | + +### ModemMessageFieldSelection + +Selects the fields included in a ModemMessage. +Use this to get, for example, only the message sentAt and body. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| fields | [repeated string](#string) | Fields in the ModemMessage structure to include in the response. Nested fields are not supported. | +| message_body_fields | [repeated string](#string) | Data fields in the body_fields Struct to include in the response. + +Nested fields are supported, using a json path expression. See the Json Path documentation at https://goessner.net/articles/JsonPath/ for details on json path. | + +### 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) + +| Field | Type | Description | +| ----- | ---- | ----------- | +| modems | [ hiber.Filter.Modems](#hiberfiltermodems) | Define the modems to return messages for, i.e. include = [AAAA AAAA, BBBB BBBB]. Deprecated in favor of using the ModemSelection. | +| modem_selection | [ ModemSelection](#modemselection) | Select the modems to return messages for. | +| time_range | [ hiber.TimeRange](#hibertimerange) | Filter message by time range. This field is required, to limit the amount of messages. | +| filter_by_sources | [ ModemMessageSelection.ModemMessageSourceFilter](#modemmessageselectionmodemmessagesourcefilter) | 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. | + +### ModemMessageSelection.ModemMessageSourceFilter + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| include | [repeated ModemMessage.Source](#modemmessagesource) | none | +| exclude | [repeated ModemMessage.Source](#modemmessagesource) | none | + +### 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 Modem.Status](#modemstatus) | Filter modems by status(es). Defaults to nominal statuses, excluding disabled, dead, lost or damaged modems. | +| transfers | [ ModemSelection.Transfers](#modemselectiontransfers) | none | +| include_types | [repeated Modem.Type](#modemtype) | 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 Modem.Type](#modemtype) | 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 | [ ModemSelection.Peripherals](#modemselectionperipherals) | 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. | + +### ModemSelection.Peripherals + +Filter to (de)select modems based on their peripherals. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| include_and | [map ModemSelection.Peripherals.IncludeAndEntry](#modemselectionperipheralsincludeandentry) | 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. | +| exclude | [map ModemSelection.Peripherals.ExcludeEntry](#modemselectionperipheralsexcludeentry) | 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 + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| key | [ string](#string) | none | +| value | [ ModemSelection.Peripherals.OneOfValues](#modemselectionperipheralsoneofvalues) | none | + +### ModemSelection.Peripherals.IncludeAndEntry + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| key | [ string](#string) | none | +| value | [ ModemSelection.Peripherals.OneOfValues](#modemselectionperipheralsoneofvalues) | none | + +### ModemSelection.Peripherals.OneOfValues + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| value | [repeated string](#string) | none | + +### ModemSelection.Transfers + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| transfers_identifiers | [repeated string](#string) | none | + +### RenameModemRequest + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| modem_number | [ string](#string) | none | +| name | [ string](#string) | none | + +### UpdateModemHealthConfig + + + + +### UpdateModemHealthConfig.Request + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| selection | [ ModemSelection](#modemselection) | none | +| health_warning_period | [ hiber.Duration](#hiberduration) | Period to consider when determining health from warning events. Warning events cannot be resolved. | + +### UpdateModemHealthConfig.Response + + + + +### UpdateModemNotesRequest + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| selection | [ ModemSelection](#modemselection) | none | +| pagination | [ hiber.Pagination](#hiberpagination) | none | +| notes | [ string](#string) | Notes content | +| allow_override_existing_notes | [ bool](#bool) | 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 + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| modems | [repeated Modem](#modem) | none | +| request | [ UpdateModemNotesRequest](#updatemodemnotesrequest) | none | +| pagination | [ hiber.Pagination.Result](#hiberpaginationresult) | none | + +### UpdateModemSecureNotesRequest + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| modem_number | [ string](#string) | none | +| secure_notes | [ string](#string) | none | + +### UpdateModemSecureNotesRequest.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| modem | [ Modem](#modem) | none | +| request | [ UpdateModemSecureNotesRequest](#updatemodemsecurenotesrequest) | none | + +### UpdateModemStatusRequest + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| modem_number | [ string](#string) | Either pick a single modem to update. DEPRECATED, since ModemSelection is more flexible. | +| modem_selection | [ ModemSelection](#modemselection) | Or a modem selection. | +| update_status | [ Modem.Status](#modemstatus) | The new status for the modem(s). | +| pagination | [ hiber.Pagination](#hiberpagination) | Pagination for the modems in the Response. | + +### UpdateModemStatusRequest.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| modem | [ Modem](#modem) | none | +| modems | [repeated Modem](#modem) | none | +| request | [ UpdateModemStatusRequest](#updatemodemstatusrequest) | none | +| pagination | [ hiber.Pagination.Result](#hiberpaginationresult) | none | + +### UpdateModemTagsRequest + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| update | [ hiber.tag.UpdateTagsForItem](#hibertagupdatetagsforitem) | none | +| selection | [ ModemSelection](#modemselection) | none | +| pagination | [ hiber.Pagination](#hiberpagination) | none | + +### UpdateModemTagsRequest.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| modems | [repeated Modem](#modem) | none | +| request | [ UpdateModemTagsRequest](#updatemodemtagsrequest) | none | +| pagination | [ hiber.Pagination.Result](#hiberpaginationresult) | none | + +### UpdatePeripheralsRequest + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| selection | [ ModemSelection](#modemselection) | none | +| hiber_antenna | [ Modem.Peripherals.HiberAntenna](#modemperipheralshiberantenna) | none | +| gps | [ hiber.UpdateBoolean](#hiberupdateboolean) | none | +| hardcoded_gps_location | [ hiber.Location](#hiberlocation) | none | +| add_peripherals | [map UpdatePeripheralsRequest.AddPeripheralsEntry](#updateperipheralsrequestaddperipheralsentry) | none | +| remove_peripherals | [repeated string](#string) | none | +| pagination | [ hiber.Pagination](#hiberpagination) | none | +| custom_antenna | [ string](#string) | none | + +### UpdatePeripheralsRequest.AddPeripheralsEntry + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| key | [ string](#string) | none | +| value | [ string](#string) | none | + +### UpdatePeripheralsRequest.Response + +The result is paginated if affecting more than 100 modems. Use the list call to paginate further. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| request | [ UpdatePeripheralsRequest](#updateperipheralsrequest) | none | +| modems | [repeated Modem](#modem) | none | +| pagination | [ hiber.Pagination.Result](#hiberpaginationresult) | none | + + +## Enums +### 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 | + +### 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 | + +### 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 | + +### 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 | + +### 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 | + +### 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.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. + +| 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. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| timestamp | [ google.protobuf.Timestamp](#googleprotobuftimestamp) | 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_STALE | none | 16 | +| MODEM_MESSAGE_RECEIVED | none | 5 | +| MODEM_MESSAGE_BODY_PARSED | none | 39 | +| MODEM_MESSAGE_BODY_RECEIVED | none | 45 | +| MODEM_MESSAGE_DROPPED | none | 13 | +| MODEM_MESSAGE_DELAYED | none | 14 | +| 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_MESSAGE_BODY_PARSER_AUTOMATIC_ASSIGNMENT_CREATED | none | 49 | +| MODEM_MESSAGE_BODY_PARSER_AUTOMATIC_ASSIGNMENT_UPDATED | none | 50 | +| MODEM_MESSAGE_BODY_PARSER_AUTOMATIC_ASSIGNMENT_DELETED | none | 51 | +| MODEM_MESSAGE_BODY_PARSER_ASSIGNED | none | 52 | +| MODEM_MESSAGE_BODY_PARSER_UNASSIGNED | none | 53 | +| MODEM_ALARM | none | 56 | +| MODEM_ALARM_CREATED | none | 57 | +| MODEM_ALARM_UPDATED | none | 58 | +| MODEM_ALARM_DELETED | none | 59 | +| DIRECT_ASSIGNMENT_ADDED | none | 63 | +| DIRECT_ASSIGNMENT_REMOVED | none | 64 | +| AUTOMATIC_MODEM_ASSIGNMENT_CREATED | none | 60 | +| AUTOMATIC_MODEM_ASSIGNMENT_UPDATED | none | 61 | +| AUTOMATIC_MODEM_ASSIGNMENT_DELETED | none | 62 | +| 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_SECONDS | none | 1 | +| DURATION_MINUTES | none | 2 | +| DURATION_HOURS | none | 3 | +| DURATION_DAYS | none | 4 | +| TEMPERATURE_KELVIN | none | 5 | +| TEMPERATURE_DEGREES_CELSIUS | none | 6 | +| TEMPERATURE_DEGREES_FAHRENHEIT | none | 7 | +| DISTANCE_METER | none | 8 | +| DISTANCE_MILLIMETER | none | 9 | +| DISTANCE_CENTIMETER | none | 10 | +| DISTANCE_KILOMETER | none | 11 | +| PRESSURE_BAR | none | 12 | +| PRESSURE_BAR_GROUND | none | 13 | +| PRESSURE_PSI | none | 14 | +| VOLTAGE_MILLIVOLT | none | 15 | +| PERCENT | none | 16 | + +## 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/modem_alarm.md b/docs/modem_alarm.md new file mode 100644 index 0000000..5a2af37 --- /dev/null +++ b/docs/modem_alarm.md @@ -0,0 +1,1477 @@ +# modem_alarm.proto + + + +#### This file was generated from [modem_alarm.proto](https://github.com/HiberGlobal/api/blob/master/modem_alarm.proto). + +## Table of Contents + +- Services + - [ModemAlarmService](#modemalarmservice) + +- Messages + - [AssignModemAlarms](#assignmodemalarms) + - [AssignModemAlarms.Request](#assignmodemalarmsrequest) + - [AssignModemAlarms.Request.ParametersEntry](#assignmodemalarmsrequestparametersentry) + - [AssignModemAlarms.Response](#assignmodemalarmsresponse) + - [AssignedModemAlarm](#assignedmodemalarm) + - [CreateModemAlarm](#createmodemalarm) + - [CreateModemAlarm.Request](#createmodemalarmrequest) + - [CreateModemAlarm.Response](#createmodemalarmresponse) + - [DeleteModemAlarm](#deletemodemalarm) + - [DeleteModemAlarm.Request](#deletemodemalarmrequest) + - [DeleteModemAlarm.Response](#deletemodemalarmresponse) + - [ListModemAlarms](#listmodemalarms) + - [ListModemAlarms.Request](#listmodemalarmsrequest) + - [ListModemAlarms.Response](#listmodemalarmsresponse) + - [MakeModemAlarmAvailableToChildOrganizationRequest](#makemodemalarmavailabletochildorganizationrequest) + - [MakeModemAlarmUnavailableToChildOrganizationRequest](#makemodemalarmunavailabletochildorganizationrequest) + - [ModemAlarm](#modemalarm) + - [ModemAlarm.Check](#modemalarmcheck) + - [ModemAlarm.Check.DelayCheck](#modemalarmcheckdelaycheck) + - [ModemAlarm.Check.FieldCheck](#modemalarmcheckfieldcheck) + - [ModemAlarm.Check.FieldCheck.DeltaCheck](#modemalarmcheckfieldcheckdeltacheck) + - [ModemAlarm.Check.FieldCheck.EqualsCheck](#modemalarmcheckfieldcheckequalscheck) + - [ModemAlarm.Check.FieldCheck.MaximumCheck](#modemalarmcheckfieldcheckmaximumcheck) + - [ModemAlarm.Check.FieldCheck.MinimumCheck](#modemalarmcheckfieldcheckminimumcheck) + - [ModemAlarm.Check.FieldCheck.OneOfCheck](#modemalarmcheckfieldcheckoneofcheck) + - [ModemAlarm.Check.FieldCheck.ThresholdCheck](#modemalarmcheckfieldcheckthresholdcheck) + - [ModemAlarm.Check.InactivityCheck](#modemalarmcheckinactivitycheck) + - [ModemAlarm.Check.LocationCheck](#modemalarmchecklocationcheck) + - [ModemAlarm.HealthLevelAfterResolved](#modemalarmhealthlevelafterresolved) + - [ModemAlarmSelection](#modemalarmselection) + - [TestModemAlarmTestParameters](#testmodemalarmtestparameters) + - [TestModemAlarmTestParameters.Request](#testmodemalarmtestparametersrequest) + - [TestModemAlarmTestParameters.Response](#testmodemalarmtestparametersresponse) + - [UnassignModemAlarms](#unassignmodemalarms) + - [UnassignModemAlarms.Request](#unassignmodemalarmsrequest) + - [UnassignModemAlarms.Response](#unassignmodemalarmsresponse) + - [UpdateModemAlarm](#updatemodemalarm) + - [UpdateModemAlarm.Request](#updatemodemalarmrequest) + - [UpdateModemAlarm.Request.UpdateChecksEntry](#updatemodemalarmrequestupdatechecksentry) + - [UpdateModemAlarm.Response](#updatemodemalarmresponse) + - [UpdateModemAlarmAddCheck](#updatemodemalarmaddcheck) + - [UpdateModemAlarmAddCheck.Request](#updatemodemalarmaddcheckrequest) + - [UpdateModemAlarmAddCheck.Response](#updatemodemalarmaddcheckresponse) + - [UpdateModemAlarmAvailability](#updatemodemalarmavailability) + - [UpdateModemAlarmAvailability.Request](#updatemodemalarmavailabilityrequest) + - [UpdateModemAlarmAvailability.Response](#updatemodemalarmavailabilityresponse) + - [UpdateModemAlarmRemoveCheck](#updatemodemalarmremovecheck) + - [UpdateModemAlarmRemoveCheck.Request](#updatemodemalarmremovecheckrequest) + - [UpdateModemAlarmRemoveCheck.Response](#updatemodemalarmremovecheckresponse) + - [UpdateModemAlarmUpdateCheck](#updatemodemalarmupdatecheck) + - [UpdateModemAlarmUpdateCheck.Request](#updatemodemalarmupdatecheckrequest) + - [UpdateModemAlarmUpdateCheck.Request.UpdateUsingParametersEntry](#updatemodemalarmupdatecheckrequestupdateusingparametersentry) + - [UpdateModemAlarmUpdateCheck.Response](#updatemodemalarmupdatecheckresponse) + +- Enums + - [ModemAlarm.TriggerCondition](#modemalarmtriggercondition) + +- 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.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) + + +## ModemAlarmService + + +### List +> **rpc** List([ListModemAlarms.Request](#listmodemalarmsrequest)) + [ListModemAlarms.Response](#listmodemalarmsresponse) + +List available modem alarms (including inherited from your parent organizations). + +### Create +> **rpc** Create([CreateModemAlarm.Request](#createmodemalarmrequest)) + [CreateModemAlarm.Response](#createmodemalarmresponse) + +Create a new modem alarm with any number of checks. + +### Update +> **rpc** Update([UpdateModemAlarm.Request](#updatemodemalarmrequest)) + [UpdateModemAlarm.Response](#updatemodemalarmresponse) + +Update a modem alarm and its checks, if you are the owner. + +### Delete +> **rpc** Delete([DeleteModemAlarm.Request](#deletemodemalarmrequest)) + [DeleteModemAlarm.Response](#deletemodemalarmresponse) + +Delete a modem alarm, if you are the owner. + +### AddCheck +> **rpc** AddCheck([UpdateModemAlarmAddCheck.Request](#updatemodemalarmaddcheckrequest)) + [UpdateModemAlarmAddCheck.Response](#updatemodemalarmaddcheckresponse) + +Add a check to a modem alarm, if you are the owner. + +### UpdateCheck +> **rpc** UpdateCheck([UpdateModemAlarmUpdateCheck.Request](#updatemodemalarmupdatecheckrequest)) + [UpdateModemAlarmUpdateCheck.Response](#updatemodemalarmupdatecheckresponse) + +Update a check in a modem alarm, if you are the owner. + +### RemoveCheck +> **rpc** RemoveCheck([UpdateModemAlarmRemoveCheck.Request](#updatemodemalarmremovecheckrequest)) + [UpdateModemAlarmRemoveCheck.Response](#updatemodemalarmremovecheckresponse) + +Remove a check from a modem alarm, if you are the owner. + +### TestParameters +> **rpc** TestParameters([TestModemAlarmTestParameters.Request](#testmodemalarmtestparametersrequest)) + [TestModemAlarmTestParameters.Response](#testmodemalarmtestparametersresponse) + +Test a set of parameters on a modem alarm, to see the result when they are applied during assignment. + +### UpdateAvailability +> **rpc** UpdateAvailability([UpdateModemAlarmAvailability.Request](#updatemodemalarmavailabilityrequest)) + [UpdateModemAlarmAvailability.Response](#updatemodemalarmavailabilityresponse) + +Make a modem alarm (un)available to (a selection of) child organizations. + +### MakeAvailableToChildOrganization +> **rpc** MakeAvailableToChildOrganization([MakeModemAlarmAvailableToChildOrganizationRequest](#makemodemalarmavailabletochildorganizationrequest)) + [ModemAlarm](#modemalarm) + +Make a modem alarm available to a child organization. + +### MakeUnavailableToChildOrganization +> **rpc** MakeUnavailableToChildOrganization([MakeModemAlarmUnavailableToChildOrganizationRequest](#makemodemalarmunavailabletochildorganizationrequest)) + [ModemAlarm](#modemalarm) + +Make a modem alarm unavailable to a child organization. + +### Assign +> **rpc** Assign([AssignModemAlarms.Request](#assignmodemalarmsrequest)) + [AssignModemAlarms.Response](#assignmodemalarmsresponse) + +Assign a modem alarm to a modem. + +### Unassign +> **rpc** Unassign([UnassignModemAlarms.Request](#unassignmodemalarmsrequest)) + [UnassignModemAlarms.Response](#unassignmodemalarmsresponse) + +Unassign a modem alarm from a modem. + + +## Messages + +### AssignModemAlarms + +Add direct assignments. +If an overlapping assignment using a rule exists, it is shadowed by the direct assignment. + +Simplified version of assign.AssignDirectly. + + +### AssignModemAlarms.Request + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| alarms | [ ModemAlarmSelection](#modemalarmselection) | none | +| modems | [ hiber.modem.ModemSelection](#hibermodemmodemselection) | none | +| parameters | [map AssignModemAlarms.Request.ParametersEntry](#assignmodemalarmsrequestparametersentry) | The alarm parameters, by alarm identifier, if any, overriding any default values in the alarm(s). | + +### AssignModemAlarms.Request.ParametersEntry + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| key | [ string](#string) | none | +| value | [ google.protobuf.Struct](#googleprotobufstruct) | none | + +### AssignModemAlarms.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| created | [repeated AssignedModemAlarm](#assignedmodemalarm) | none | +| request | [ AssignModemAlarms.Request](#assignmodemalarmsrequest) | none | + +### AssignedModemAlarm + +Directly assigned modem alarm to a modem. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| alarm_identifier | [ string](#string) | none | +| modem_number | [ string](#string) | none | + +### CreateModemAlarm + +Create a new alarm. + +The request contains the option to add checks as well. +This is a shortcut for creating an alarm and then adding checks, and as such can result in multiple events: +- a created event on the alarm +- an update event on the alarm checks, iff any checks were added + + +### CreateModemAlarm.Request + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| description | [ string](#string) | A short description of what the alarm should do. | +| trigger_condition | [ ModemAlarm.TriggerCondition](#modemalarmtriggercondition) | Condition determining when an alarm is triggered if it has multiple checks. | +| checks | [repeated ModemAlarm.Check](#modemalarmcheck) | The checks to add to this alarm. Shortcut for creating an alarm and then adding checks to it. | +| default_health_level | [ string](#string) | The default health level for this alarm. See ModemAlarm.default_health_level for more information. | +| health_level_after_resolved | [ ModemAlarm.HealthLevelAfterResolved](#modemalarmhealthlevelafterresolved) | The health level this alarm should cause after it is resolved. See ModemAlarm.health_level_after_resolved for more information. | + +### CreateModemAlarm.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| created | [ ModemAlarm](#modemalarm) | none | + +### DeleteModemAlarm + + + + +### DeleteModemAlarm.Request + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| identifier | [ string](#string) | none | + +### DeleteModemAlarm.Response + + + + +### ListModemAlarms + + + + +### ListModemAlarms.Request + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| selection | [ ModemAlarmSelection](#modemalarmselection) | none | +| pagination | [ hiber.Pagination](#hiberpagination) | none | + +### ListModemAlarms.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| modem_alarms | [repeated ModemAlarm](#modemalarm) | none | +| pagination | [ hiber.Pagination.Result](#hiberpaginationresult) | none | +| request | [ ListModemAlarms.Request](#listmodemalarmsrequest) | none | + +### MakeModemAlarmAvailableToChildOrganizationRequest + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| identifier | [ string](#string) | The identifier of the alarm that should be updated. | +| available_to | [repeated string](#string) | The child organization(s) that the alarm should be available to. This will - when the organization is on the exclude list, remove it - when the includeAll flag is false, add it to the include list (if not already present) | + +### MakeModemAlarmUnavailableToChildOrganizationRequest + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| identifier | [ string](#string) | The identifier of the alarm that should be updated. | +| unavailable_to | [repeated string](#string) | The child organization(s) that the alarm should be unavailable to. This will - when the organization is on the include list, remove it - when the includeAll flag is true, add it to the exclude list (if not already present) | + +### ModemAlarm + +Alarm for a modem, monitoring message data, location or activity. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| identifier | [ string](#string) | The identifier for this alarm. This identifier is globally unique, since the alarm can be shared to child organizations. | +| description | [ string](#string) | none | +| available_to_child_organizations | [ hiber.Filter.ChildOrganizations](#hiberfilterchildorganizations) | Availability to child organizations. This alarm can be shared to child organizations, so it can be assigned to their modems, either directly or automatically over all selected child organizations. Only the owner organization is able to edit the alarm. | +| trigger_condition | [ ModemAlarm.TriggerCondition](#modemalarmtriggercondition) | Condition determining when an alarm is triggered if it has multiple checks. | +| default_health_level | [ string](#string) | The default health level for checks in this alarm, if they have no health_level configured. Health for an alarm event is determined by taking the most severe health level from the health_levels configured on the failing checks, using this default for any checks that do not have a health_level configured. + +This can be changed on assignment with the default_health_level parameter, to fit the needs of the organization. + +Note, when an alarm is inherited the health levels may not match yours. If the health level matches one of your health levels, that level is used. Otherwise, the catch-all health level is used. See the health definition for more information on the catch all health level (typically the most severe). Note that the health level displayed here is the result of the steps above. | +| health_level_after_resolved | [ ModemAlarm.HealthLevelAfterResolved](#modemalarmhealthlevelafterresolved) | Allow the alarm to cause a health level for the modem even after a new message has come in. + +Typically, an alarm event only affects the modem health while it is from the last message from that modem. By configuring this, you can specify the modem health should be affected for a longer period. + +For example, when using an inactivity check, this would could be used to configure modem health ERROR while inactive, lowering to INVESTIGATE for a day after a new message comes in. | +| checks | [repeated ModemAlarm.Check](#modemalarmcheck) | The checks in this alarm, | +| alarm_parameters | [ google.protobuf.Struct](#googleprotobufstruct) | Parameters for this alarm. This field displays all the parameters that can be set for the alarm on assignment, with their current value. + +Parameters are based on the check fields, and are used in the check error message template. For the alarm parameters, check parameters are prefixed with the check identifier. + +For example: An alarm with check A (field "healthy" equals 1) and check B (field "state" oneof ["OK", "ACTIVE"]) would have the following parameters: { "A": { "expected": 1, "field.path": "healthy", "field.equals.expected": 1 }, "B": { "expected": ["OK", "ACTIVE"], "field.path": "state", "field.oneof.expected": ["OK", "ACTIVE"] } } | + +### ModemAlarm.Check + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| identifier | [ string](#string) | Identifier for this check, unique within the alarm. This is used to update or remove the check, and to determine the destination for any parameters. | +| health_level | [ string](#string) | The health level that this check would cause for a modem, when it fails. This can be changed on assignment, to fit the needs of the organization. If not configured, health is unaffected. + +Note, when an alarm is inherited the health levels may not match yours. If the health level matches one of your health levels, that level is used. Otherwise, the catch-all health level is used. See the health definition for more information on the catch all health level (typically the most severe). Note that the health level displayed here is the result of the steps above. | +| error_message_template | [ string](#string) | The error message for this check, with parameters that will be filled in based on the check. The parameters are included as {parameter}, which gets replaced with the value. + +The supported parameters are different per check, but the parameters below are always supported: - modem: the modem number. - message: the id of the message, if any. - expected: a shortcut for the expected value(s), depending on the check: - equals check: expected value - oneof check: expected values as [a, b, c] - threshold check: expected range as minimum..maximum - location check: expected area as [(bottom left), (top right)], and shape as [(point), (point), ..., (point)] - actual: the invalid actual value(s) for this check. + +The checks below define other available parameters. + +For example (using some parameters for specific checks): - "Your device {modem} has left its designated area! It is now at {actual}." - "Your device battery is at {actual}%, which is below the recommended minimum of {field.threshold.minimum}%." - "Your device battery is draining faster than expected: {actual}% over the past {field.delta.period}." - "Your device temperature has exceeded {value.threshold.maximum} degrees: {actual}." - "Your device reported an unhealthy state {actual}. Healthy states are: {expected}." - "Your device reported an unhealthy state {actual}. Healthy states are: {field.oneof.expected}." - "Your device reported an unhealthy state {actual}. Please set it back to {expected}." - "Your device reported an unhealthy state {actual}. Please set it back to {field.equals.expected}." - "Unexpected value {actual} for field {field.path}!" + +Numeric values can be formatted with an extra postfix on the parameters - Round numeric values by adding ":.2f" (for 2 decimals). For example: "{actual:.3f}" (rounds to 3 decimals) - Always sign numeric values (when rounded) by prefixing the format with a plus. For example: `{actual:+.3f}` - This is applied to numeric fields and fields that can be numeric, like `{actual}` and `{expected}`. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **check**.location | [ ModemAlarm.Check.LocationCheck](#modemalarmchecklocationcheck) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **check**.field | [ ModemAlarm.Check.FieldCheck](#modemalarmcheckfieldcheck) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **check**.inactivity | [ ModemAlarm.Check.InactivityCheck](#modemalarmcheckinactivitycheck) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **check**.delay | [ ModemAlarm.Check.DelayCheck](#modemalarmcheckdelaycheck) | none | + +### ModemAlarm.Check.DelayCheck + +Check whether the message was delayed more than a configured limit. +The delay is the time between the message was sent (ModemMessage.sent_at) and the time it was +received on the server (ModemMessage.received_at). + +Has the following parameters: +- delay.maximum: the maximum allowed delay + +| Field | Type | Description | +| ----- | ---- | ----------- | +| maximum | [ hiber.Duration](#hiberduration) | The maximum value for the message delay (duration between sent and received time). | + +### ModemAlarm.Check.FieldCheck + +A check that evaluates each new message, and checks selected field(s) in the parsed body. + +Has the following parameters (matches the fields): +- field.path: replace the path for this field +- field.ignoreFieldNotFound: replace the value for ignore_field_not_found + +For the equals check: +- field.equals.expected: iff this is an equals check, replace the expected value + +For the oneof check: +- field.oneof.expected: iff this is a oneof check, replace the expected values + +For the threshold check: +- field.threshold.expected: iff this is a threshold check, replace the expected range +- field.threshold.minimum: iff this is a threshold check, replace the expected minimum +- field.threshold.maximum: iff this is a threshold check, replace the expected maximum + +For the delta check: +- field.delta.period: +- field.delta.threshold.expected: iff this is a delta check, replace the expected range +- field.delta.threshold.minimum: iff this is a delta check, replace the expected minimum +- field.delta.threshold.maximum: iff this is a delta check, replace the expected maximum + +All of the parameters above can be used in the error message template. + +The delta check also adds a few additional error message variables: +- {field.delta.previous}: the previous value for the field +- {field.delta.difference} (also {actual}): the difference between previous and current value for the field +- {field.delta.current}: the current value for the field + +| Field | Type | Description | +| ----- | ---- | ----------- | +| path | [ string](#string) | Select the field(s) that this check is applied to, using a json path. When multiple fields are selected, the checks are applied to all of them individually. + +See the Json Path documentation at https://goessner.net/articles/JsonPath/ for details on json path. + +Simple examples selecting a field: - $.my_field: a field in the root of the parsed object - $.my_obj.my_field: a field in a deeper structure - $.my_array[x].my_field: the field my_field of the element at index x is selected + +Complex use cases are also possible, but they require a bit more understanding of json path logic: - $.my_array.length(): the length of my_array is selected. Combine with an equals or threshold check, to require that an array has a certain length. - $.my_array[?(@.name == 'D')]: the array of all objects in my_array where name equals 'D' is selected. - $.my_array[?(@.name == 'D')]..my_field: the array of my_field values from all objects in my_array where name equals 'D' is selected. - $.my_array..my_field: the array of my_field values (for all objects in my_array) is selected - $.my_array[*].my_field: the array of my_field values (for all objects in my_array) is selected + +Note that this for the examples above, if they return an array, the entire array is used as the value in the comparison for equals and oneof. | +| ignore_field_not_found | [ bool](#bool) | Whether to ignore this check if the field is not found. This can be useful if your path selects multiple values in an array, like my_array[*].value, and not all entries have the field, or when fields are omitted if they have a default value. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **check**.equals | [ ModemAlarm.Check.FieldCheck.EqualsCheck](#modemalarmcheckfieldcheckequalscheck) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **check**.oneof | [ ModemAlarm.Check.FieldCheck.OneOfCheck](#modemalarmcheckfieldcheckoneofcheck) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **check**.minimum | [ ModemAlarm.Check.FieldCheck.MinimumCheck](#modemalarmcheckfieldcheckminimumcheck) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **check**.maximum | [ ModemAlarm.Check.FieldCheck.MaximumCheck](#modemalarmcheckfieldcheckmaximumcheck) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **check**.threshold | [ ModemAlarm.Check.FieldCheck.ThresholdCheck](#modemalarmcheckfieldcheckthresholdcheck) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **check**.delta | [ ModemAlarm.Check.FieldCheck.DeltaCheck](#modemalarmcheckfieldcheckdeltacheck) | none | + +### ModemAlarm.Check.FieldCheck.DeltaCheck + +A check that evaluates the differences in values over time, for the selected field(s) in the parsed body. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| period | [ hiber.Duration](#hiberduration) | The period to evaluate when determining the value difference. | +| threshold | [ ModemAlarm.Check.FieldCheck.ThresholdCheck](#modemalarmcheckfieldcheckthresholdcheck) | Check that the delta is within a given numeric range. | +| encrypted | [ bool](#bool) | Whether the field data should be encrypted in cache storage. Delta checks use a cache for field from messages that are affected by a delta check. Encrypting the individual field values is (relatively) computationally expensive and may lead to a slightly delayed alarm event. In the future, some delta features may only be available to unencrypted values due to performance issues. | +| ignore_previous_value_not_found | [ bool](#bool) | Whether to ignore this check if the previous value is not found (i.e. there is no history). | + +### ModemAlarm.Check.FieldCheck.EqualsCheck + +Check that the field is equal to the given value. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| expected | [ google.protobuf.Value](#googleprotobufvalue) | none | + +### ModemAlarm.Check.FieldCheck.MaximumCheck + +Check that the field is lower than the given value. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| maximum | [ double](#double) | The maximum numeric value the field should have. | + +### ModemAlarm.Check.FieldCheck.MinimumCheck + +Check that the field is higher than the given value. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| minimum | [ double](#double) | The minimum numeric value the field should have. | + +### ModemAlarm.Check.FieldCheck.OneOfCheck + +Check that the field is in a set of expected values. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| expected | [repeated google.protobuf.Value](#googleprotobufvalue) | The list of allowed values, one of which should match the field value. | + +### ModemAlarm.Check.FieldCheck.ThresholdCheck + +Check that the field is within a given numeric range. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| expected | [ hiber.DoubleRange](#hiberdoublerange) | The range the value must be in. | +| minimum | [ double](#double) | The minimum expected value, available separately for convenience and check parameters. | +| maximum | [ double](#double) | The maximum expected value, available separately for convenience and check parameters. | + +### ModemAlarm.Check.InactivityCheck + +Check whether the device exceeds inactivity limits. + +Has the following parameters: +- inactivity.maximum: the maximum allowed inactivity + +| Field | Type | Description | +| ----- | ---- | ----------- | +| maximum | [ hiber.Duration](#hiberduration) | The maximum value for the modem's inactivity (time since last message was received on the server). | +| deprecated_maximum | [ hiber.Duration](#hiberduration) | none | + +### ModemAlarm.Check.LocationCheck + +Check that the device location is within a given area. + +Has the following parameters: +- location.expected: replace the expected area or shape +- location.area: replace the expected area +- location.shape: replace the expected shape + +| Field | Type | Description | +| ----- | ---- | ----------- | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **expected**.area | [ hiber.Area](#hiberarea) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **expected**.shape | [ hiber.Shape](#hibershape) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **expected**.named | [ string](#string) | Specify the name of a name location (NamedLocation) that the device must be in. | + +### ModemAlarm.HealthLevelAfterResolved + +Allow the alarm to cause a health level for the modem even after a new message has come in. + +Typically, an alarm event only affects the modem health while it is from the last message from that modem. +By configuring this, you can specify the modem health should be affected for a longer period. + +For example, when using an inactivity check, this would could be used to configure modem health ERROR while +inactive, lowering to INVESTIGATE for a day after a new message comes in. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| health_level | [ string](#string) | The health level that this check would cause for a modem, when the original failure is resolved. | +| period | [ hiber.Duration](#hiberduration) | The amount of time that this health level would be active. | + +### ModemAlarmSelection + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| identifiers | [repeated string](#string) | none | +| search | [ string](#string) | Search for the given string in identifier, description, fields and values. | +| owner_organizations | [repeated string](#string) | Only return alarms that were created by the given organizations. | +| only_owned_alarms | [ bool](#bool) | none | + +### TestModemAlarmTestParameters + + + + +### TestModemAlarmTestParameters.Request + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| alarm_identifier | [ string](#string) | none | +| parameters | [ google.protobuf.Struct](#googleprotobufstruct) | none | + +### TestModemAlarmTestParameters.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| result | [ ModemAlarm](#modemalarm) | none | + +### UnassignModemAlarms + +Remove a direct assignment. +If an overlapping assignment using a rule exists, it is not affected, except that it is longer shadowed. + +Simplified version of assign.UnassignDirectly. + + +### UnassignModemAlarms.Request + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| alarms | [ ModemAlarmSelection](#modemalarmselection) | none | +| modems | [ hiber.modem.ModemSelection](#hibermodemmodemselection) | none | + +### UnassignModemAlarms.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| removed_direct_assignments | [repeated AssignedModemAlarm](#assignedmodemalarm) | none | +| request | [ UnassignModemAlarms.Request](#unassignmodemalarmsrequest) | none | + +### UpdateModemAlarm + +Update the alarm, iff you are the owner or can impersonate the owner organization. + +The request contains the option to add, remove or update checks as well. +This is a shortcut for updating an alarm and then adding, removing and/or updating checks, +and as such can result in multiple events: +- an update event on the alarm, iff there were any non-check changes to the alarm. +- an update event on the alarm checks, iff there were any check addition, updates or deletions + + +### UpdateModemAlarm.Request + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| identifier | [ string](#string) | The identifiers of the alarm to update | +| update_description | [ hiber.UpdateClearableString](#hiberupdateclearablestring) | Update the description, optionally. | +| update_trigger_condition | [ ModemAlarm.TriggerCondition](#modemalarmtriggercondition) | Update the trigger condition, optionally. | +| update_default_health_level | [ hiber.UpdateClearableString](#hiberupdateclearablestring) | Update the default health level, optionally. | +| update_health_level_after_resolved | [ ModemAlarm.HealthLevelAfterResolved](#modemalarmhealthlevelafterresolved) | Update the health after resolved, optionally. | +| remove_health_level_after_resolved | [ bool](#bool) | Remove the health after resolved, optionally. | +| add_checks | [repeated ModemAlarm.Check](#modemalarmcheck) | The checks to add to this alarm. Shortcut for updating an alarm and then adding checks to it. | +| update_checks | [map UpdateModemAlarm.Request.UpdateChecksEntry](#updatemodemalarmrequestupdatechecksentry) | The checks to update in this alarm. Shortcut for updating an alarm and then updating checks. | +| delete_checks | [repeated string](#string) | The checks to remove from this alarm. Shortcut for updating an alarm and then removing checks. | + +### UpdateModemAlarm.Request.UpdateChecksEntry + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| key | [ string](#string) | none | +| value | [ ModemAlarm.Check](#modemalarmcheck) | none | + +### UpdateModemAlarm.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| updated | [ ModemAlarm](#modemalarm) | none | + +### UpdateModemAlarmAddCheck + +Add a check to the alarm, iff you are the owner or can impersonate the owner organization. + + +### UpdateModemAlarmAddCheck.Request + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| alarm_identifier | [ string](#string) | none | +| check | [ ModemAlarm.Check](#modemalarmcheck) | The check to add to the Modem Alarm. Identifier must be unique within the alarm. | + +### UpdateModemAlarmAddCheck.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| updated | [ ModemAlarm](#modemalarm) | none | + +### UpdateModemAlarmAvailability + + + + +### UpdateModemAlarmAvailability.Request + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| alarm_identifier | [ string](#string) | none | +| replace_apply_to_child_organizations | [ hiber.Filter.ChildOrganizations](#hiberfilterchildorganizations) | The new set of child organizations that this rule applies to. Replaces the original value! | + +### UpdateModemAlarmAvailability.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| updated | [ ModemAlarm](#modemalarm) | none | + +### UpdateModemAlarmRemoveCheck + + + + +### UpdateModemAlarmRemoveCheck.Request + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| alarm_identifier | [ string](#string) | none | +| check_identifier | [ string](#string) | none | + +### UpdateModemAlarmRemoveCheck.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| updated | [ ModemAlarm](#modemalarm) | none | + +### UpdateModemAlarmUpdateCheck + + + + +### UpdateModemAlarmUpdateCheck.Request + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| alarm_identifier | [ string](#string) | none | +| check_identifier | [ string](#string) | none | +| update_check | [ ModemAlarm.Check](#modemalarmcheck) | none | +| update_using_parameters | [map UpdateModemAlarmUpdateCheck.Request.UpdateUsingParametersEntry](#updatemodemalarmupdatecheckrequestupdateusingparametersentry) | Use parameters to update the check, as it would be when they were added when the alarm was assigned. | +| test_parameters_only | [ bool](#bool) | If set, the update is not actually saved, but only applied and returned. This is a convenience to easily test parameters for a check similar to TestModemAlarmTestParameters. | + +### UpdateModemAlarmUpdateCheck.Request.UpdateUsingParametersEntry + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| key | [ string](#string) | none | +| value | [ google.protobuf.Value](#googleprotobufvalue) | none | + +### UpdateModemAlarmUpdateCheck.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| updated | [ ModemAlarm](#modemalarm) | none | + + +## Enums +### ModemAlarm.TriggerCondition +Condition determining when an alarm is triggered if it has multiple checks. + +| Name | Description | Number | +| ---- | ----------- | ------ | +| DEFAULT | Defaults to the current value when updating, or to ANY_CHECK_FAILED when creating. | 0 | +| ANY_CHECK_FAILED | Trigger the alarm when any of the checks fail. This is useful when providing a single device health alarm, that checks, for example, battery, operating temperature, etc. and should trigger when any of those are outside the expected range. | 1 | +| ALL_CHECKS_FAILED | Trigger the alarm only when all checks fail. This is useful when creating a combined alarm, where several data points factor into the decisions to trigger the alarm, for example, combining a check on the current value with a delta check on the historical values, to trigger only if the value is high for a longer period. | 2 | + + + +## 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. | +| maximum_inactivity_period | [ int32](#int32) | Period in days, if modem inactivity exceeds this period, alerts will be triggered and health will go to error | +| maximum_inactivity | [ hiber.Duration](#hiberduration) | If modem inactivity exceeds this period, alerts will be triggered and health will go to error | +| 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. | +| health_config | [ hiber.modem.Modem.HealthConfig](#hibermodemmodemhealthconfig) | Health configuration for unresolvable built-in modem alarms, like delayed or skipped messages. | +| 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. | + +### 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.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. + +| 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. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| timestamp | [ google.protobuf.Timestamp](#googleprotobuftimestamp) | 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_STALE | none | 16 | +| MODEM_MESSAGE_RECEIVED | none | 5 | +| MODEM_MESSAGE_BODY_PARSED | none | 39 | +| MODEM_MESSAGE_BODY_RECEIVED | none | 45 | +| MODEM_MESSAGE_DROPPED | none | 13 | +| MODEM_MESSAGE_DELAYED | none | 14 | +| 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_MESSAGE_BODY_PARSER_AUTOMATIC_ASSIGNMENT_CREATED | none | 49 | +| MODEM_MESSAGE_BODY_PARSER_AUTOMATIC_ASSIGNMENT_UPDATED | none | 50 | +| MODEM_MESSAGE_BODY_PARSER_AUTOMATIC_ASSIGNMENT_DELETED | none | 51 | +| MODEM_MESSAGE_BODY_PARSER_ASSIGNED | none | 52 | +| MODEM_MESSAGE_BODY_PARSER_UNASSIGNED | none | 53 | +| MODEM_ALARM | none | 56 | +| MODEM_ALARM_CREATED | none | 57 | +| MODEM_ALARM_UPDATED | none | 58 | +| MODEM_ALARM_DELETED | none | 59 | +| DIRECT_ASSIGNMENT_ADDED | none | 63 | +| DIRECT_ASSIGNMENT_REMOVED | none | 64 | +| AUTOMATIC_MODEM_ASSIGNMENT_CREATED | none | 60 | +| AUTOMATIC_MODEM_ASSIGNMENT_UPDATED | none | 61 | +| AUTOMATIC_MODEM_ASSIGNMENT_DELETED | none | 62 | +| 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_SECONDS | none | 1 | +| DURATION_MINUTES | none | 2 | +| DURATION_HOURS | none | 3 | +| DURATION_DAYS | none | 4 | +| TEMPERATURE_KELVIN | none | 5 | +| TEMPERATURE_DEGREES_CELSIUS | none | 6 | +| TEMPERATURE_DEGREES_FAHRENHEIT | none | 7 | +| DISTANCE_METER | none | 8 | +| DISTANCE_MILLIMETER | none | 9 | +| DISTANCE_CENTIMETER | none | 10 | +| DISTANCE_KILOMETER | none | 11 | +| PRESSURE_BAR | none | 12 | +| PRESSURE_BAR_GROUND | none | 13 | +| PRESSURE_PSI | none | 14 | +| VOLTAGE_MILLIVOLT | none | 15 | +| PERCENT | none | 16 | + +## 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/modem_message_body_parser.md b/docs/modem_message_body_parser.md new file mode 100644 index 0000000..83a0c24 --- /dev/null +++ b/docs/modem_message_body_parser.md @@ -0,0 +1,1336 @@ +# modem_message_body_parser.proto + +Modem message body parsers management. + +Modem message body parsers (short: parsers) are small scripts defined using the Kaitai Struct specification +to parse binary data. +Parsers are assigned to modems to parse the body of their messages dynamically. + +Parsers can be written manually as a .ksy file and uploaded through the API, or the simplified API implementation +can be used to create a parser. + +For more information on Kaitai Struct, see [http://kaitai.io/](http://kaitai.io/), +where you can find documentation, examples and a web IDE. + +#### This file was generated from [modem_message_body_parser.proto](https://github.com/HiberGlobal/api/blob/master/modem_message_body_parser.proto). + +## Table of Contents + +- Services + - [ModemMessageBodyParserService](#modemmessagebodyparserservice) + +- Messages + - [AssignModemMessageBodyParsers](#assignmodemmessagebodyparsers) + - [AssignModemMessageBodyParsers.Request](#assignmodemmessagebodyparsersrequest) + - [AssignModemMessageBodyParsers.Response](#assignmodemmessagebodyparsersresponse) + - [AssignedModemMessageBodyParser](#assignedmodemmessagebodyparser) + - [CreateSimpleModemMessageBodyParserRequest](#createsimplemodemmessagebodyparserrequest) + - [DeleteModemMessageBodyParserRequest](#deletemodemmessagebodyparserrequest) + - [DeleteModemMessageBodyParserRequest.Response](#deletemodemmessagebodyparserrequestresponse) + - [ListModemMessageBodyParsersRequest](#listmodemmessagebodyparsersrequest) + - [ListModemMessageBodyParsersRequest.Response](#listmodemmessagebodyparsersrequestresponse) + - [MakeModemMessageBodyParserAvailableToChildOrganizationRequest](#makemodemmessagebodyparseravailabletochildorganizationrequest) + - [MakeModemMessageBodyParserUnavailableToChildOrganizationRequest](#makemodemmessagebodyparserunavailabletochildorganizationrequest) + - [ModemMessageBodyParser](#modemmessagebodyparser) + - [ModemMessageBodyParser.AvailableToChildOrganizations](#modemmessagebodyparseravailabletochildorganizations) + - [ModemMessageBodyParser.DataField](#modemmessagebodyparserdatafield) + - [ModemMessageBodyParser.MetadataFields](#modemmessagebodyparsermetadatafields) + - [ModemMessageBodyParser.MetadataFields.LocationFields](#modemmessagebodyparsermetadatafieldslocationfields) + - [ModemMessageBodyParserSelection](#modemmessagebodyparserselection) + - [RenameModemMessageBodyParserRequest](#renamemodemmessagebodyparserrequest) + - [RetryModemMessageBodyParsing](#retrymodemmessagebodyparsing) + - [RetryModemMessageBodyParsing.Request](#retrymodemmessagebodyparsingrequest) + - [RetryModemMessageBodyParsing.Response](#retrymodemmessagebodyparsingresponse) + - [SimpleModemMessageBodyParser](#simplemodemmessagebodyparser) + - [SimpleModemMessageBodyParser.DelimitedSize](#simplemodemmessagebodyparserdelimitedsize) + - [SimpleModemMessageBodyParser.Field](#simplemodemmessagebodyparserfield) + - [SimpleModemMessageBodyParser.Field.Bytes](#simplemodemmessagebodyparserfieldbytes) + - [SimpleModemMessageBodyParser.Field.Float](#simplemodemmessagebodyparserfieldfloat) + - [SimpleModemMessageBodyParser.Field.Integer](#simplemodemmessagebodyparserfieldinteger) + - [SimpleModemMessageBodyParser.Field.String](#simplemodemmessagebodyparserfieldstring) + - [TestModemMessageBodyParserRequest](#testmodemmessagebodyparserrequest) + - [TestModemMessageBodyParserRequest.Response](#testmodemmessagebodyparserrequestresponse) + - [UnassignModemMessageBodyParsers](#unassignmodemmessagebodyparsers) + - [UnassignModemMessageBodyParsers.Request](#unassignmodemmessagebodyparsersrequest) + - [UnassignModemMessageBodyParsers.Response](#unassignmodemmessagebodyparsersresponse) + - [UpdateChildOrganizationAvailabilityRequest](#updatechildorganizationavailabilityrequest) + - [UpdateSimpleModemMessageBodyParserRequest](#updatesimplemodemmessagebodyparserrequest) + - [UpdateUploadedModemMessageBodyParserRequest](#updateuploadedmodemmessagebodyparserrequest) + - [UpdateUploadedModemMessageBodyParserRequest.MetadataFields](#updateuploadedmodemmessagebodyparserrequestmetadatafields) + - [UploadModemMessageBodyParserRequest](#uploadmodemmessagebodyparserrequest) + +- Enums + - [ModemMessageBodyParser.DataField.Type](#modemmessagebodyparserdatafieldtype) + - [SimpleModemMessageBodyParser.Endian](#simplemodemmessagebodyparserendian) + +- 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.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) + + +## ModemMessageBodyParserService + + +### List +> **rpc** List([ListModemMessageBodyParsersRequest](#listmodemmessagebodyparsersrequest)) + [ListModemMessageBodyParsersRequest.Response](#listmodemmessagebodyparsersrequestresponse) + +List available message body parsers (including inherited from your parent organizations). + +### Upload +> **rpc** Upload([UploadModemMessageBodyParserRequest](#uploadmodemmessagebodyparserrequest)) + [ModemMessageBodyParser](#modemmessagebodyparser) + +Upload a .ksy file as a message body parser. + +### UpdateUploaded +> **rpc** UpdateUploaded([UpdateUploadedModemMessageBodyParserRequest](#updateuploadedmodemmessagebodyparserrequest)) + [ModemMessageBodyParser](#modemmessagebodyparser) + +Re-upload a .ksy file to update a message body parser, if you are the owner. + +### CreateSimple +> **rpc** CreateSimple([CreateSimpleModemMessageBodyParserRequest](#createsimplemodemmessagebodyparserrequest)) + [ModemMessageBodyParser](#modemmessagebodyparser) + +Create a simple message body parser using API elements. + +### UpdateSimple +> **rpc** UpdateSimple([UpdateSimpleModemMessageBodyParserRequest](#updatesimplemodemmessagebodyparserrequest)) + [ModemMessageBodyParser](#modemmessagebodyparser) + +Update a simple message body parser created using API elements, if you are the owner. + +### Rename +> **rpc** Rename([RenameModemMessageBodyParserRequest](#renamemodemmessagebodyparserrequest)) + [ModemMessageBodyParser](#modemmessagebodyparser) + +Rename a message body parser, if you are the owner. + +### UpdateChildOrganizationAvailability +> **rpc** UpdateChildOrganizationAvailability([UpdateChildOrganizationAvailabilityRequest](#updatechildorganizationavailabilityrequest)) + [ModemMessageBodyParser](#modemmessagebodyparser) + +Make a message body parser (un)available to (a selection of) child organizations. + +### MakeAvailableToChildOrganization +> **rpc** MakeAvailableToChildOrganization([MakeModemMessageBodyParserAvailableToChildOrganizationRequest](#makemodemmessagebodyparseravailabletochildorganizationrequest)) + [ModemMessageBodyParser](#modemmessagebodyparser) + +Make a message body parser available to a child organization. + +### MakeUnavailableToChildOrganization +> **rpc** MakeUnavailableToChildOrganization([MakeModemMessageBodyParserUnavailableToChildOrganizationRequest](#makemodemmessagebodyparserunavailabletochildorganizationrequest)) + [ModemMessageBodyParser](#modemmessagebodyparser) + +Make a message body parser unavailable to a child organization. + +### Delete +> **rpc** Delete([DeleteModemMessageBodyParserRequest](#deletemodemmessagebodyparserrequest)) + [DeleteModemMessageBodyParserRequest.Response](#deletemodemmessagebodyparserrequestresponse) + +Delete a message body parser, if you are the owner. + +### Test +> **rpc** Test([TestModemMessageBodyParserRequest](#testmodemmessagebodyparserrequest)) + [TestModemMessageBodyParserRequest.Response](#testmodemmessagebodyparserrequestresponse) + +Test a message body parser with an existing message or provided binary message body. +This can also be used without an existing parser by uploading a .ksy file or specifying a simple parser. + +### Retry +> **rpc** Retry([RetryModemMessageBodyParsing.Request](#retrymodemmessagebodyparsingrequest)) + [RetryModemMessageBodyParsing.Response](#retrymodemmessagebodyparsingresponse) + +Retry parsing messages with a message body parser (for example after updating the parser). + +### Assign +> **rpc** Assign([AssignModemMessageBodyParsers.Request](#assignmodemmessagebodyparsersrequest)) + [AssignModemMessageBodyParsers.Response](#assignmodemmessagebodyparsersresponse) + +Assign a parser to a modem. + +### Unassign +> **rpc** Unassign([UnassignModemMessageBodyParsers.Request](#unassignmodemmessagebodyparsersrequest)) + [UnassignModemMessageBodyParsers.Response](#unassignmodemmessagebodyparsersresponse) + +Unassign a parser from a modem. + + +## Messages + +### AssignModemMessageBodyParsers + +Add direct assignments. +If an overlapping assignment using a rule exists, it is shadowed by the direct assignment. + +Simplified version of assign.AssignDirectly. + + +### AssignModemMessageBodyParsers.Request + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| assign_parsers | [ ModemMessageBodyParserSelection](#modemmessagebodyparserselection) | none | +| to_modems | [ hiber.modem.ModemSelection](#hibermodemmodemselection) | none | + +### AssignModemMessageBodyParsers.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| created | [repeated AssignedModemMessageBodyParser](#assignedmodemmessagebodyparser) | none | +| request | [ AssignModemMessageBodyParsers.Request](#assignmodemmessagebodyparsersrequest) | none | + +### AssignedModemMessageBodyParser + +Directly assigned modem message parser to a modem. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| parser_identifier | [ string](#string) | none | +| modem_number | [ string](#string) | none | + +### CreateSimpleModemMessageBodyParserRequest + +Create a simple modem message parser, which generates a .ksy specification. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| parser | [ SimpleModemMessageBodyParser](#simplemodemmessagebodyparser) | none | + +### DeleteModemMessageBodyParserRequest + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| selection | [ ModemMessageBodyParserSelection](#modemmessagebodyparserselection) | A selection of parsers to be deleted. | + +### DeleteModemMessageBodyParserRequest.Response + + + + +### ListModemMessageBodyParsersRequest + +List the parser your organizations has access to. This may include inherited parsers. + +If include_content is not set, this call may omit parser specifications, like the ksy, since those are +typically larger multi-line strings. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| selection | [ ModemMessageBodyParserSelection](#modemmessagebodyparserselection) | none | +| pagination | [ hiber.Pagination](#hiberpagination) | none | +| exclude_content | [ bool](#bool) | Whether to omit the content in the resulting ModemMessageBodyParsers. | + +### ListModemMessageBodyParsersRequest.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| parsers | [repeated ModemMessageBodyParser](#modemmessagebodyparser) | none | +| pagination | [ hiber.Pagination.Result](#hiberpaginationresult) | none | +| request | [ ListModemMessageBodyParsersRequest](#listmodemmessagebodyparsersrequest) | none | + +### MakeModemMessageBodyParserAvailableToChildOrganizationRequest + +Make this parser available to a specific child organizations. + +This will +- when the organization is on the exclude list, remove it +- when the includeAll flag is false, add it to the include list (if not already present) + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| identifier | [ string](#string) | The identifier of the parser that should be updated. | +| available_to | [repeated string](#string) | The child organization(s) that the parser should be available to. | + +### MakeModemMessageBodyParserUnavailableToChildOrganizationRequest + +Make this parser unavailable to a specific child organizations. + +This will +- when the organization is on the include list, remove it +- when the includeAll flag is true, add it to the exclude list (if not already present) + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| identifier | [ string](#string) | The identifier of the parser that should be updated. | +| unavailable_to | [repeated string](#string) | The child organization(s) that the parser should be unavailable to. | + +### ModemMessageBodyParser + +Modem message body parser. This defines a parsing strategy for the body of a message. +A parser can be defined in two ways: using a .ksy (Kaitai struct https://kaitai.io/) file or using the simple parser. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| identifier | [ string](#string) | The globally (across organizations) unique identifier for this parser. | +| organization | [ string](#string) | The organization that created the parser. | +| name | [ string](#string) | The name for this parser. | +| content_ksy | [ string](#string) | The content of this parsers script. If simple_parser is set, this content is generated from that definition. This field may be omitted by the list call to save data. | +| simple_parser | [ SimpleModemMessageBodyParser](#simplemodemmessagebodyparser) | The simple parser this .ksy was generated from, if it was generated from a simple parser. This field may be omitted on demand to save data in the list call. | +| data_fields | [repeated ModemMessageBodyParser.DataField](#modemmessagebodyparserdatafield) | Fields in the parsed result that contain data. Data fields are cached for efficient retrieval and allow all kinds of processing. | +| data_fields_deprecated | [repeated string](#string) | none | +| metadata_fields | [ ModemMessageBodyParser.MetadataFields](#modemmessagebodyparsermetadatafields) | Fields in the parsed result that contain metadata, and special things like a location. | +| available_to_child_organizations | [ ModemMessageBodyParser.AvailableToChildOrganizations](#modemmessagebodyparseravailabletochildorganizations) | If set, this parser is available to your child organizations, as a Provided parser. | + +### ModemMessageBodyParser.AvailableToChildOrganizations + +A modem message body parser with this object is available to child organizations. +This means the child organization can use it, but not update or delete it. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| child_organizations | [ hiber.Filter.ChildOrganizations](#hiberfilterchildorganizations) | none | + +### ModemMessageBodyParser.DataField + +Fields in the parsed result that contain data. +Data fields are cached for efficient retrieval and allow all kinds of processing. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| name | [ string](#string) | The name of the field (if in the root structure) or a JsonPath to the field. | +| display_name | [ string](#string) | An optional display name for the field. | +| encrypted | [ bool](#bool) | Whether this field should be stored encrypted or not. If it is, some processing options may be unavailable or slower. For example, determining the time between ENUM state transitions requires encryption to be disabled for that field. | +| unit_of_measurement | [ hiber.UnitOfMeasurement](#hiberunitofmeasurement) | If numeric, the unit of the value. | +| type | [ ModemMessageBodyParser.DataField.Type](#modemmessagebodyparserdatafieldtype) | The type of field. | + +### ModemMessageBodyParser.MetadataFields + +Fields in the parsed result that match common things that can be processed by the system, +like a location or battery percentage. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| metadata_fields | [repeated string](#string) | Other metadata fields, which will be added to the metadata json for easy processing. | +| location_fields | [ ModemMessageBodyParser.MetadataFields.LocationFields](#modemmessagebodyparsermetadatafieldslocationfields) | Specify a pair of fields in the message body that contain location data, which will update the modem location and the map. | + +### ModemMessageBodyParser.MetadataFields.LocationFields + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| latitude | [ string](#string) | none | +| longitude | [ string](#string) | none | + +### ModemMessageBodyParserSelection + +Selection object for parsers. Used to select which parser to list, assign, etc. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| identifiers | [repeated string](#string) | Filter parsers by their identifiers. | +| search | [ string](#string) | Find parsers by searching for this text in the name, content_ksy, data fields or simple parser definition. | +| only_simple | [ bool](#bool) | Only return simple parsers, created using SimpleModemMessageBodyParser. | +| only_ksy_file | [ bool](#bool) | Only return parsers created from an uploaded .ksy file. | +| only_owned_parsers | [ bool](#bool) | Exclude parsers that are not owned by your organization (those that you did not create yourself). | +| owner_organizations | [repeated string](#string) | Only return parsers that were created by the given parent organizations. | +| has_data_fields | [repeated string](#string) | Only return parsers that have one of the given data fields This only works when the fields are marked explicitly using the data fields option. | + +### RenameModemMessageBodyParserRequest + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| identifier | [ string](#string) | The identifier of the parser that should be updated. | +| name | [ string](#string) | The new name for this parser. | + +### RetryModemMessageBodyParsing + +Retry a message, parsing it with all the currently assigned parsers that are in the given selection. +If the message was previously parsed by any of those parsers, the previous result is replaced. + + +### RetryModemMessageBodyParsing.Request + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| modem_message_ids | [repeated uint64](#uint64) | The messages to parse. | +| parser_selection | [ ModemMessageBodyParserSelection](#modemmessagebodyparserselection) | A selection of parsers to apply, if they are assigned. | + +### RetryModemMessageBodyParsing.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| parsed_messages | [repeated hiber.modem.ModemMessage.ParsedBody](#hibermodemmodemmessageparsedbody) | none | + +### SimpleModemMessageBodyParser + +Simple modem message body parser. This can be used a convenient way to create a .ksy parser. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| name | [ string](#string) | Parser name. When this structure is used as a custom type inside a parser, this name is a reduced to a value containing only lowercase letters, numbers and underscores, like field names. | +| documentation | [ string](#string) | A short, single line description of the field. | +| fields | [repeated SimpleModemMessageBodyParser.Field](#simplemodemmessagebodyparserfield) | The fields in this object. | +| default_endian | [ SimpleModemMessageBodyParser.Endian](#simplemodemmessagebodyparserendian) | Sets a default endianness for this parser's fields and any fields in custom types. | +| default_text_encoding | [ string](#string) | Sets a default string encoding for this parser's fields and any fields in custom types. | +| custom_types | [repeated SimpleModemMessageBodyParser](#simplemodemmessagebodyparser) | A list of custom types used for custom types fields. Each is effectively a simple parser, and can have its own custom types again, which can only be used within that parser structure. The parser name is used for custom type fields. | + +### SimpleModemMessageBodyParser.DelimitedSize + +Delimited size definition, used for Bytes and Text. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **size**.size_bytes | [ int32](#int32) | Specifies the number of bytes in this field. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **size**.end_of_stream | [ bool](#bool) | Specifies that this field parses all bytes until the end of the stream. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **size**.field_name | [ string](#string) | Specifies the number of bytes in this field using the value of an Integer field. This integer field must be parsed before this field is parsed. | +| terminator | [ bytes](#bytes) | Specify a terminator that marks the point the field terminates, optionally, and we should continue to the next field. This is typically a single byte (i.e. 0x00). This can be combined with a size to limit the amounts of bytes that are parsed. | + +### SimpleModemMessageBodyParser.Field + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| name | [ string](#string) | Field name. This is a reduced to a value containing only lowercase letters, numbers and underscores. | +| documentation | [ string](#string) | A short, single line description of the field. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **type**.integer | [ SimpleModemMessageBodyParser.Field.Integer](#simplemodemmessagebodyparserfieldinteger) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **type**.float | [ SimpleModemMessageBodyParser.Field.Float](#simplemodemmessagebodyparserfieldfloat) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **type**.bytes | [ SimpleModemMessageBodyParser.Field.Bytes](#simplemodemmessagebodyparserfieldbytes) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **type**.string | [ SimpleModemMessageBodyParser.Field.String](#simplemodemmessagebodyparserfieldstring) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **type**.magic | [ bytes](#bytes) | Specify an expected magic sequence (some bytes that are always the same). | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **type**.custom_type | [ string](#string) | Specify a custom type name. | + +### SimpleModemMessageBodyParser.Field.Bytes + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| size | [ SimpleModemMessageBodyParser.DelimitedSize](#simplemodemmessagebodyparserdelimitedsize) | none | + +### SimpleModemMessageBodyParser.Field.Float + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| size_bytes | [ int32](#int32) | Specifies the size of this floating point number in bytes. | +| endian | [ SimpleModemMessageBodyParser.Endian](#simplemodemmessagebodyparserendian) | Specifies endian encoding for this field. This can be omitted if default endianness specified. | + +### SimpleModemMessageBodyParser.Field.Integer + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| size_bytes | [ int32](#int32) | Specifies the size of this integer in bytes. | +| signed | [ bool](#bool) | Specifies whether this integer is signed or unsigned. | +| endian | [ SimpleModemMessageBodyParser.Endian](#simplemodemmessagebodyparserendian) | Specifies endian encoding for this field. This can be omitted if default endianness specified. | + +### SimpleModemMessageBodyParser.Field.String + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| size | [ SimpleModemMessageBodyParser.DelimitedSize](#simplemodemmessagebodyparserdelimitedsize) | none | +| encoding | [ string](#string) | Specifies encoding for the string. This can be omitted if default encoding specified. | + +### TestModemMessageBodyParserRequest + +Test a parsers on a message. + +This method provides a number of options and can be used in multiple ways: +- Test a real message or an uploaded message body. +- Test using an existing parser, an ksy definition or a simple parser definition. + +This can be used to test a parser with a modem's past messages, before assigning it, +or while developing a parser to validate it with an expected body. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **parser**.identifier | [ string](#string) | The identifier of the parser you want to test. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **parser**.content_ksy | [ string](#string) | A ksy definition you want to test. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **parser**.simple_parser | [ SimpleModemMessageBodyParser](#simplemodemmessagebodyparser) | A simple parser definition you want to test. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **data**.parse_bytes | [ hiber.BytesOrHex](#hiberbytesorhex) | A byte array (message body) to parse. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **data**.modem_message_id | [ uint64](#uint64) | The id of an existing message, testing the parser on its body. | + +### TestModemMessageBodyParserRequest.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **result**.parsed | [ google.protobuf.Struct](#googleprotobufstruct) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **result**.error | [ string](#string) | none | + +### UnassignModemMessageBodyParsers + +Remove a direct assignment. +If an overlapping assignment using a rule exists, it is not affected, except that it is longer shadowed. + +Simplified version of assign.UnassignDirectly. + + +### UnassignModemMessageBodyParsers.Request + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| unassign_parsers | [ ModemMessageBodyParserSelection](#modemmessagebodyparserselection) | none | +| from_modems | [ hiber.modem.ModemSelection](#hibermodemmodemselection) | none | + +### UnassignModemMessageBodyParsers.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| removed_direct_assignments | [repeated AssignedModemMessageBodyParser](#assignedmodemmessagebodyparser) | none | +| request | [ UnassignModemMessageBodyParsers.Request](#unassignmodemmessagebodyparsersrequest) | none | + +### UpdateChildOrganizationAvailabilityRequest + +Update the child availability for a parser. +Parsers can be made available to child organizations, which means that they can be viewed in, +and assigned to modems in, child organizations. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| identifier | [ string](#string) | The identifier of the parser that should be updated. | +| available_to_child_organizations | [ hiber.Filter.ChildOrganizations](#hiberfilterchildorganizations) | The new child organization availability filter for this parser. | + +### UpdateSimpleModemMessageBodyParserRequest + +Update a simple modem message parser, updating the generated .ksy specification. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| identifier | [ string](#string) | The identifier of the parser that should be updated. | +| parser | [ SimpleModemMessageBodyParser](#simplemodemmessagebodyparser) | none | + +### UpdateUploadedModemMessageBodyParserRequest + +Upload an updated body parser from a .ksy file, replacing the previous file. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| identifier | [ string](#string) | The identifier of the parser that should be updated. | +| content_ksy | [ string](#string) | The new ksy definition for this parser. | +| add_data_fields | [repeated ModemMessageBodyParser.DataField](#modemmessagebodyparserdatafield) | Add fields to the data fields list. | +| add_data_fields_deprecated | [repeated string](#string) | none | +| remove_data_fields | [repeated string](#string) | Remove fields from the data fields list. | +| metadata_fields | [ UpdateUploadedModemMessageBodyParserRequest.MetadataFields](#updateuploadedmodemmessagebodyparserrequestmetadatafields) | Fields in the parsed result that match special things that can be processed by the system, like a location. | + +### UpdateUploadedModemMessageBodyParserRequest.MetadataFields + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| add_metadata_fields | [repeated string](#string) | Add metadata fields to the metadata fields list. | +| remove_metadata_fields | [repeated string](#string) | Remove metadata fields from the metadata fields list. | +| update_location_fields | [ ModemMessageBodyParser.MetadataFields.LocationFields](#modemmessagebodyparsermetadatafieldslocationfields) | Update the location fields. | + +### UploadModemMessageBodyParserRequest + +Upload a new body parser from a .ksy file. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| name | [ string](#string) | A descriptive name for this parser. | +| content_ksy | [ string](#string) | The ksy definition for this parser. | +| data_fields | [repeated ModemMessageBodyParser.DataField](#modemmessagebodyparserdatafield) | Fields in the parsed result that contain data. This can be useful to track which fields could be plotted, etc. | +| data_fields_deprecated | [repeated string](#string) | none | +| metadata_fields | [ ModemMessageBodyParser.MetadataFields](#modemmessagebodyparsermetadatafields) | Fields in the parsed result that match special things that can be processed by the system, like a location. | + + +## Enums +### ModemMessageBodyParser.DataField.Type + + +| 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 | + +### SimpleModemMessageBodyParser.Endian + + +| Name | Description | Number | +| ---- | ----------- | ------ | +| DEFAULT | none | 0 | +| LITTLE_ENDIAN | none | 1 | +| BIG_ENDIAN | none | 2 | + + + +## 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. | +| maximum_inactivity_period | [ int32](#int32) | Period in days, if modem inactivity exceeds this period, alerts will be triggered and health will go to error | +| maximum_inactivity | [ hiber.Duration](#hiberduration) | If modem inactivity exceeds this period, alerts will be triggered and health will go to error | +| 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. | +| health_config | [ hiber.modem.Modem.HealthConfig](#hibermodemmodemhealthconfig) | Health configuration for unresolvable built-in modem alarms, like delayed or skipped messages. | +| 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. | + +### 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.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. + +| 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. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| timestamp | [ google.protobuf.Timestamp](#googleprotobuftimestamp) | 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_STALE | none | 16 | +| MODEM_MESSAGE_RECEIVED | none | 5 | +| MODEM_MESSAGE_BODY_PARSED | none | 39 | +| MODEM_MESSAGE_BODY_RECEIVED | none | 45 | +| MODEM_MESSAGE_DROPPED | none | 13 | +| MODEM_MESSAGE_DELAYED | none | 14 | +| 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_MESSAGE_BODY_PARSER_AUTOMATIC_ASSIGNMENT_CREATED | none | 49 | +| MODEM_MESSAGE_BODY_PARSER_AUTOMATIC_ASSIGNMENT_UPDATED | none | 50 | +| MODEM_MESSAGE_BODY_PARSER_AUTOMATIC_ASSIGNMENT_DELETED | none | 51 | +| MODEM_MESSAGE_BODY_PARSER_ASSIGNED | none | 52 | +| MODEM_MESSAGE_BODY_PARSER_UNASSIGNED | none | 53 | +| MODEM_ALARM | none | 56 | +| MODEM_ALARM_CREATED | none | 57 | +| MODEM_ALARM_UPDATED | none | 58 | +| MODEM_ALARM_DELETED | none | 59 | +| DIRECT_ASSIGNMENT_ADDED | none | 63 | +| DIRECT_ASSIGNMENT_REMOVED | none | 64 | +| AUTOMATIC_MODEM_ASSIGNMENT_CREATED | none | 60 | +| AUTOMATIC_MODEM_ASSIGNMENT_UPDATED | none | 61 | +| AUTOMATIC_MODEM_ASSIGNMENT_DELETED | none | 62 | +| 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_SECONDS | none | 1 | +| DURATION_MINUTES | none | 2 | +| DURATION_HOURS | none | 3 | +| DURATION_DAYS | none | 4 | +| TEMPERATURE_KELVIN | none | 5 | +| TEMPERATURE_DEGREES_CELSIUS | none | 6 | +| TEMPERATURE_DEGREES_FAHRENHEIT | none | 7 | +| DISTANCE_METER | none | 8 | +| DISTANCE_MILLIMETER | none | 9 | +| DISTANCE_CENTIMETER | none | 10 | +| DISTANCE_KILOMETER | none | 11 | +| PRESSURE_BAR | none | 12 | +| PRESSURE_BAR_GROUND | none | 13 | +| PRESSURE_PSI | none | 14 | +| VOLTAGE_MILLIVOLT | none | 15 | +| PERCENT | none | 16 | + +## 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/named_location.md b/docs/named_location.md new file mode 100644 index 0000000..6d713b1 --- /dev/null +++ b/docs/named_location.md @@ -0,0 +1,791 @@ +# named_location.proto + + + +#### This file was generated from [named_location.proto](https://github.com/HiberGlobal/api/blob/master/named_location.proto). + +## Table of Contents + +- Services + - [NamedLocationService](#namedlocationservice) + +- Messages + - [CreateNamedLocations](#createnamedlocations) + - [CreateNamedLocations.Request](#createnamedlocationsrequest) + - [CreateNamedLocations.Response](#createnamedlocationsresponse) + - [DeleteNamedLocation](#deletenamedlocation) + - [DeleteNamedLocation.Request](#deletenamedlocationrequest) + - [DeleteNamedLocation.Response](#deletenamedlocationresponse) + - [ListNamedLocations](#listnamedlocations) + - [ListNamedLocations.Request](#listnamedlocationsrequest) + - [ListNamedLocations.Response](#listnamedlocationsresponse) + - [LocationOverlapSelection](#locationoverlapselection) + - [NamedLocation](#namedlocation) + - [NamedLocationSelection](#namedlocationselection) + - [UpdateNamedLocation](#updatenamedlocation) + - [UpdateNamedLocation.Request](#updatenamedlocationrequest) + - [UpdateNamedLocation.Response](#updatenamedlocationresponse) + +- Enums + +- 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.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) + + +## NamedLocationService +Manage saved locations for your organization. +This allows you to save locations to be displayed on the map or used in alarms. +Note that when a saved location is used in an alarm, it may be exposed to child organization when the alarm +is available to child organizations. + +### List +> **rpc** List([ListNamedLocations.Request](#listnamedlocationsrequest)) + [ListNamedLocations.Response](#listnamedlocationsresponse) + + + +### Create +> **rpc** Create([CreateNamedLocations.Request](#createnamedlocationsrequest)) + [CreateNamedLocations.Response](#createnamedlocationsresponse) + + + +### Update +> **rpc** Update([UpdateNamedLocation.Request](#updatenamedlocationrequest)) + [UpdateNamedLocation.Response](#updatenamedlocationresponse) + + + +### Delete +> **rpc** Delete([DeleteNamedLocation.Request](#deletenamedlocationrequest)) + [DeleteNamedLocation.Response](#deletenamedlocationresponse) + + + + +## Messages + +### CreateNamedLocations + + + + +### CreateNamedLocations.Request + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| create | [repeated NamedLocation](#namedlocation) | The locations to save. If the name for any of the given locations already exists, the request fails. | + +### CreateNamedLocations.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| added | [repeated NamedLocation](#namedlocation) | none | + +### DeleteNamedLocation + + + + +### DeleteNamedLocation.Request + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| name | [ string](#string) | The name of the saved location to delete. | + +### DeleteNamedLocation.Response + + + + +### ListNamedLocations + + + + +### ListNamedLocations.Request + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| selection | [ NamedLocationSelection](#namedlocationselection) | none | +| pagination | [ hiber.Pagination](#hiberpagination) | none | + +### ListNamedLocations.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| named_locations | [repeated NamedLocation](#namedlocation) | none | +| pagination | [ hiber.Pagination.Result](#hiberpaginationresult) | none | +| request | [ ListNamedLocations.Request](#listnamedlocationsrequest) | none | + +### LocationOverlapSelection + +Selection for overlapping with (saved) locations. + +For example: +- Select everything that overlaps with saved location "my-area": + { overlaps = { saved = "my-area" } } +- Select everything that overlaps with a custom shape: + { overlaps = { shape = { path = ... } } } +- Select everything that overlaps with the intersection of a saved location and a custom area: + { overlaps_all = [{ saved = "my-saved-location" }, { area = ... }] } +- Recursive selection using a combination of any and all by adding deeper selections: + { overlaps_any = [{ overlap_all = { ... } }, { saved = { .. } }] } + +| Field | Type | Description | +| ----- | ---- | ----------- | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **element**.location | [ hiber.Location](#hiberlocation) | Matches anything that contains this location. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **element**.area | [ hiber.Area](#hiberarea) | Matching anything that overlaps with this shape. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **element**.shape | [ hiber.Shape](#hibershape) | Matching anything that overlaps with this area. | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **element**.name | [ string](#string) | Matches anything that overlaps with this named location. | +| overlaps_all | [repeated LocationOverlapSelection](#locationoverlapselection) | Must overlap with all items. If used in combination with element or overlaps_any, they must all match. | +| overlaps_any | [repeated LocationOverlapSelection](#locationoverlapselection) | Must overlap with at least one of the items. If used in combination with element or overlaps_all, they must all match. | + +### NamedLocation + +A saved location within an organization. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| name | [ string](#string) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **definition**.location | [ hiber.Location](#hiberlocation) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **definition**.area | [ hiber.Area](#hiberarea) | none | +| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) **definition**.shape | [ hiber.Shape](#hibershape) | none | + +### NamedLocationSelection + +Look up saved locations by name, or by overlap with a given selection. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| search | [ string](#string) | Free text search in the saved location names. | +| names | [repeated string](#string) | Select the saved locations with the given names. | +| overlaps | [ LocationOverlapSelection](#locationoverlapselection) | Select all saved locations that overlap with the given LocationOverlapSelection. | + +### UpdateNamedLocation + + + + +### UpdateNamedLocation.Request + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| organization | [ string](#string) | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| name | [ string](#string) | The name of the saved location to update. | +| updated | [ NamedLocation](#namedlocation) | The new saved location. If the name is different, the saved location is renamed. | + +### UpdateNamedLocation.Response + + + +| Field | Type | Description | +| ----- | ---- | ----------- | +| updated | [ NamedLocation](#namedlocation) | none | + + +## Enums + + +## 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.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. + +| 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. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| timestamp | [ google.protobuf.Timestamp](#googleprotobuftimestamp) | 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_STALE | none | 16 | +| MODEM_MESSAGE_RECEIVED | none | 5 | +| MODEM_MESSAGE_BODY_PARSED | none | 39 | +| MODEM_MESSAGE_BODY_RECEIVED | none | 45 | +| MODEM_MESSAGE_DROPPED | none | 13 | +| MODEM_MESSAGE_DELAYED | none | 14 | +| 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_MESSAGE_BODY_PARSER_AUTOMATIC_ASSIGNMENT_CREATED | none | 49 | +| MODEM_MESSAGE_BODY_PARSER_AUTOMATIC_ASSIGNMENT_UPDATED | none | 50 | +| MODEM_MESSAGE_BODY_PARSER_AUTOMATIC_ASSIGNMENT_DELETED | none | 51 | +| MODEM_MESSAGE_BODY_PARSER_ASSIGNED | none | 52 | +| MODEM_MESSAGE_BODY_PARSER_UNASSIGNED | none | 53 | +| MODEM_ALARM | none | 56 | +| MODEM_ALARM_CREATED | none | 57 | +| MODEM_ALARM_UPDATED | none | 58 | +| MODEM_ALARM_DELETED | none | 59 | +| DIRECT_ASSIGNMENT_ADDED | none | 63 | +| DIRECT_ASSIGNMENT_REMOVED | none | 64 | +| AUTOMATIC_MODEM_ASSIGNMENT_CREATED | none | 60 | +| AUTOMATIC_MODEM_ASSIGNMENT_UPDATED | none | 61 | +| AUTOMATIC_MODEM_ASSIGNMENT_DELETED | none | 62 | +| 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_SECONDS | none | 1 | +| DURATION_MINUTES | none | 2 | +| DURATION_HOURS | none | 3 | +| DURATION_DAYS | none | 4 | +| TEMPERATURE_KELVIN | none | 5 | +| TEMPERATURE_DEGREES_CELSIUS | none | 6 | +| TEMPERATURE_DEGREES_FAHRENHEIT | none | 7 | +| DISTANCE_METER | none | 8 | +| DISTANCE_MILLIMETER | none | 9 | +| DISTANCE_CENTIMETER | none | 10 | +| DISTANCE_KILOMETER | none | 11 | +| PRESSURE_BAR | none | 12 | +| PRESSURE_BAR_GROUND | none | 13 | +| PRESSURE_PSI | none | 14 | +| VOLTAGE_MILLIVOLT | none | 15 | +| PERCENT | none | 16 | + +## 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/permission.html b/docs/permission.html deleted file mode 100644 index ac2de08..0000000 --- a/docs/permission.html +++ /dev/null @@ -1,635 +0,0 @@ - - - - - Protocol Documentation - - - - - - - - - - -

Protocol Documentation

- -

Table of Contents

- - - - - -
-

permission.proto

Top -
-

Permissions limit what a user can do through the API.

- - - - -

OrganizationPermission

-

OrganizationPermissions limit what a user can do in an Organization.

By default, everyone who has access to an organization, can access:

- organization data

- dashboard (including the map, and message count for the past days, and any events they have access to)

- tags

- deleting tags, but only if they are allowed to update the modems and webhooks the tag is assigned to

Events are filtered by permission, i.e. if you cannot access the users, you would not see user-related events.

Requesting user-related events explicitly if you cannot access the users will return an error.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameNumberDescription
PERMISSION_DEFAULT0

ORGANIZATION_CREATE1

Create a new child organization.

ORGANIZATION_UPDATE2

Update the organizations data, such as billing information, address, and contact.

ORGANIZATION_DELETE3

Delete child organizations. -You cannot delete your own organization. To delete your organization, contact support.

MODEMS10

List modems, see their details and health

MODEMS_CREATE50

Create new modems. Includes MODEMS permission.

MODEMS_UPDATE11

Update modems, such as their peripherals, display name and tags. Includes MODEMS permission.

MODEMS_LICENSE_KEYS12

Show and regenerate license keys. Includes MODEMS permission.

MODEMS_MESSAGE_BODY_PARSERS43

Manage and assign message body parsers. Includes MODEMS permission.

MODEMS_SECURE_NOTES42

Show and update secure notes. Includes MODEMS permission.

MODEMS_ALARMS44

Manage and assign message alerts. Includes MODEMS permission.

MODEM_MESSAGES15

Read modem messages.

MODEM_MESSAGES_SEND_TEST_MESSAGES16

Send modem messages using the TestingService. Does not include MODEMS or MESSAGES permission.

MODEM_MESSAGES_SEND_REAL_MESSAGES41

Send modem messages using real message sources (i.e. gateway). Does not include MODEMS or MESSAGES permission.

MODEM_DOWNLINK_MESSAGES51

Send modem downlink messages.

MODEM_TRANSFERS20

See modem transfers, inbound and outbound modems. Includes modems permission.

MODEM_TRANSFERS_SEND21

Transfer modems to another organization, cancel open transfers and send return transfers. -Includes modems_transfers permission.

MODEM_TRANSFERS_PROCESS22

Mark transfers as received, prepare modems for return. This does not include actually sending the return transfer. -Includes modems_transfers permission.

MODEM_CLAIM25

Claiming modems.

USERS30

List all users, see their names and email addresses.

USERS_MANAGE31

Approve or create new users, remove users from the organization. Includes users permission.

PUBLISHERS35

Manage publishers: webhooks, MQTT integration, AWS IoT integration and custom email publishers.

TOKENS36

Manage tokens.

CERTIFICATES38

Read and use uploaded certificates (i.e. for publishers).

CERTIFICATES_MANAGE39

Upload certificates, and update or delete uploaded certificates.

ASSIGNMENTS45

Manage assignments using the assignment services and individual calls on, for example, ModemService.

SIMULATION_MANAGE46

Manage simulations, like modem message simulation.

HEALTH_MANAGE47

Manage custom health levels.

LOCATIONS_MANAGE48

Manage saved locations using the OrganizationLocationService.

EXPORT49

Create, access and download exports.

- -

UserPermission

-

UserPermissions are generally used to limit what a token can do to its user.

By default, a user has all UserPermissions, which apply only to himself.

When creating a token, however, the token typically does not need permission to affect the user at all.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameNumberDescription
READ0

Read your name, email, linked organizations and mission-control settings.

UPDATE1

Update your personal information, mission-control settings and default organization. Includes read permission.

REQUEST_ACCESS2

Request access to an organization and cancel open requests. Does not include read permission.

DELETE3

Delete your user account permanently. Includes read permission.

- - - - - - - -

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/permission.md b/docs/permission.md index 80b22eb..78f671c 100644 --- a/docs/permission.md +++ b/docs/permission.md @@ -1,27 +1,22 @@ -# Protocol Documentation - +# permission.proto -## Table of Contents +Permissions limit what a user can do through the API. -- [permission.proto](#permission.proto) - - [OrganizationPermission](#hiber.OrganizationPermission) - - [UserPermission](#hiber.UserPermission) - -- [Scalar Value Types](#scalar-value-types) +#### This file was generated from [permission.proto](https://github.com/HiberGlobal/api/blob/master/permission.proto).## Table of Contents - -

Top

-## permission.proto -Permissions limit what a user can do through the API. - +- Enums + - [OrganizationPermission](#organizationpermission) + - [UserPermission](#userpermission) + - + +## Enums ### OrganizationPermission OrganizationPermissions limit what a user can do in an Organization. By default, everyone who has access to an organization, can access: @@ -33,81 +28,48 @@ By default, everyone who has access to an organization, can access: Events are filtered by permission, i.e. if you cannot access the users, you would not see user-related events. Requesting user-related events explicitly if you cannot access the users will return an error. -| Name | Number | Description | -| ---- | ------ | ----------- | -| PERMISSION_DEFAULT | 0 | | -| ORGANIZATION_CREATE | 1 | Create a new child organization. | -| ORGANIZATION_UPDATE | 2 | Update the organizations data, such as billing information, address, and contact. | -| ORGANIZATION_DELETE | 3 | Delete child organizations. You cannot delete your own organization. To delete your organization, contact support. | -| MODEMS | 10 | List modems, see their details and health | -| MODEMS_CREATE | 50 | Create new modems. Includes MODEMS permission. | -| MODEMS_UPDATE | 11 | Update modems, such as their peripherals, display name and tags. Includes MODEMS permission. | -| MODEMS_LICENSE_KEYS | 12 | Show and regenerate license keys. Includes MODEMS permission. | -| MODEMS_MESSAGE_BODY_PARSERS | 43 | Manage and assign message body parsers. Includes MODEMS permission. | -| MODEMS_SECURE_NOTES | 42 | Show and update secure notes. Includes MODEMS permission. | -| MODEMS_ALARMS | 44 | Manage and assign message alerts. Includes MODEMS permission. | -| MODEM_MESSAGES | 15 | Read modem messages. | -| MODEM_MESSAGES_SEND_TEST_MESSAGES | 16 | Send modem messages using the TestingService. Does not include MODEMS or MESSAGES permission. | -| MODEM_MESSAGES_SEND_REAL_MESSAGES | 41 | Send modem messages using real message sources (i.e. gateway). Does not include MODEMS or MESSAGES permission. | -| MODEM_DOWNLINK_MESSAGES | 51 | Send modem downlink messages. | -| MODEM_TRANSFERS | 20 | See modem transfers, inbound and outbound modems. Includes modems permission. | -| MODEM_TRANSFERS_SEND | 21 | Transfer modems to another organization, cancel open transfers and send return transfers. Includes modems_transfers permission. | -| MODEM_TRANSFERS_PROCESS | 22 | Mark transfers as received, prepare modems for return. This does not include actually sending the return transfer. Includes modems_transfers permission. | -| MODEM_CLAIM | 25 | Claiming modems. | -| USERS | 30 | List all users, see their names and email addresses. | -| USERS_MANAGE | 31 | Approve or create new users, remove users from the organization. Includes users permission. | -| PUBLISHERS | 35 | Manage publishers: webhooks, MQTT integration, AWS IoT integration and custom email publishers. | -| TOKENS | 36 | Manage tokens. | -| CERTIFICATES | 38 | Read and use uploaded certificates (i.e. for publishers). | -| CERTIFICATES_MANAGE | 39 | Upload certificates, and update or delete uploaded certificates. | -| ASSIGNMENTS | 45 | Manage assignments using the assignment services and individual calls on, for example, ModemService. | -| SIMULATION_MANAGE | 46 | Manage simulations, like modem message simulation. | -| HEALTH_MANAGE | 47 | Manage custom health levels. | -| LOCATIONS_MANAGE | 48 | Manage saved locations using the OrganizationLocationService. | -| EXPORT | 49 | Create, access and download exports. | - - - - +| Name | Description | Number | +| ---- | ----------- | ------ | +| PERMISSION_DEFAULT | none | 0 | +| ORGANIZATION_CREATE | Create a new child organization. | 1 | +| ORGANIZATION_UPDATE | Update the organizations data, such as billing information, address, and contact. | 2 | +| ORGANIZATION_DELETE | Delete child organizations. You cannot delete your own organization. To delete your organization, contact support. | 3 | +| MODEMS | List modems, see their details and health | 10 | +| MODEMS_CREATE | Create new modems. Includes MODEMS permission. | 50 | +| MODEMS_UPDATE | Update modems, such as their peripherals, display name and tags. Includes MODEMS permission. | 11 | +| MODEMS_LICENSE_KEYS | Show and regenerate license keys. Includes MODEMS permission. | 12 | +| MODEMS_MESSAGE_BODY_PARSERS | Manage and assign message body parsers. Includes MODEMS permission. | 43 | +| MODEMS_SECURE_NOTES | Show and update secure notes. Includes MODEMS permission. | 42 | +| MODEMS_ALARMS | Manage and assign message alerts. Includes MODEMS permission. | 44 | +| MODEM_MESSAGES | Read modem messages. | 15 | +| MODEM_MESSAGES_SEND_TEST_MESSAGES | Send modem messages using the TestingService. Does not include MODEMS or MESSAGES permission. | 16 | +| MODEM_MESSAGES_SEND_REAL_MESSAGES | Send modem messages using real message sources (i.e. gateway). Does not include MODEMS or MESSAGES permission. | 41 | +| MODEM_DOWNLINK_MESSAGES | Send modem downlink messages. | 51 | +| MODEM_TRANSFERS | See modem transfers, inbound and outbound modems. Includes modems permission. | 20 | +| MODEM_TRANSFERS_SEND | Transfer modems to another organization, cancel open transfers and send return transfers. Includes modems_transfers permission. | 21 | +| MODEM_TRANSFERS_PROCESS | Mark transfers as received, prepare modems for return. This does not include actually sending the return transfer. Includes modems_transfers permission. | 22 | +| MODEM_CLAIM | Claiming modems. | 25 | +| USERS | List all users, see their names and email addresses. | 30 | +| USERS_MANAGE | Approve or create new users, remove users from the organization. Includes users permission. | 31 | +| PUBLISHERS | Manage publishers: webhooks, MQTT integration, AWS IoT integration and custom email publishers. | 35 | +| TOKENS | Manage tokens. | 36 | +| CERTIFICATES | Read and use uploaded certificates (i.e. for publishers). | 38 | +| CERTIFICATES_MANAGE | Upload certificates, and update or delete uploaded certificates. | 39 | +| ASSIGNMENTS | Manage assignments using the assignment services and individual calls on, for example, ModemService. | 45 | +| SIMULATION_MANAGE | Manage simulations, like modem message simulation. | 46 | +| HEALTH_MANAGE | Manage custom health levels. | 47 | +| LOCATIONS_MANAGE | Manage saved locations using the OrganizationLocationService. | 48 | +| EXPORT | Create, access and download exports. | 49 | ### UserPermission UserPermissions are generally used to limit what a token can do to its user. By default, a user has all UserPermissions, which apply only to himself. When creating a token, however, the token typically does not need permission to affect the user at all. -| Name | Number | Description | -| ---- | ------ | ----------- | -| READ | 0 | Read your name, email, linked organizations and mission-control settings. | -| UPDATE | 1 | Update your personal information, mission-control settings and default organization. Includes read permission. | -| REQUEST_ACCESS | 2 | Request access to an organization and cancel open requests. Does not include read permission. | -| DELETE | 3 | Delete your user account permanently. Includes read permission. | - - - - - - - - - - -## Scalar Value Types - -| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby | -| ----------- | ----- | --- | ---- | ------ | -- | -- | --- | ---- | -| double | | double | double | float | float64 | double | float | Float | -| float | | float | float | float | float32 | 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 | int32 | int | integer | Bignum or Fixnum (as required) | -| 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 | int64 | long | integer/string | Bignum | -| uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) | -| uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) | -| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | -| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | int64 | long | integer/string | Bignum | -| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | uint32 | uint | integer | Bignum or Fixnum (as required) | -| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum | -| sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | -| sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum | -| bool | | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass | -| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) | -| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) | +| Name | Description | Number | +| ---- | ----------- | ------ | +| READ | Read your name, email, linked organizations and mission-control settings. | 0 | +| UPDATE | Update your personal information, mission-control settings and default organization. Includes read permission. | 1 | +| REQUEST_ACCESS | Request access to an organization and cancel open requests. Does not include read permission. | 2 | +| DELETE | Delete your user account permanently. Includes read permission. | 3 | diff --git a/easypulse.proto b/easypulse.proto index 78dd5f1..883e7da 100644 --- a/easypulse.proto +++ b/easypulse.proto @@ -22,7 +22,14 @@ option go_package = "hiber"; /* Service to list and manage Assets. */ service EasypulseService { + /* List the Easypulse Assets in your organization. + * Optionally, aggregated historical data can be added to the returned Assets, with a given name. + * + * Fails when your organizations does not have the Easypulse feature. + */ rpc Assets (Easypulse.ListAssets.Request) returns (Easypulse.ListAssets.Response); + + /* List the history for a single field, and optionally apply an aggregation and/or grouping to it. */ rpc History (Easypulse.History.Request) returns (Easypulse.History.Response); } diff --git a/event-json-examples/modem-message-cannot-be-parsed.json b/event-json-examples/modem-message-cannot-be-parsed.json index 3844c98..82e96ed 100644 --- a/event-json-examples/modem-message-cannot-be-parsed.json +++ b/event-json-examples/modem-message-cannot-be-parsed.json @@ -19,6 +19,7 @@ "catchAll": true, "severity": "3" }, + "resolveIdentifier": "", "tags": [ { "id": "1", diff --git a/event.proto b/event.proto index 8934935..890ee73 100644 --- a/event.proto +++ b/event.proto @@ -34,6 +34,7 @@ option go_package = "hiber"; service EventService { rpc List (ListEventsRequest) returns (ListEventsRequest.Response); rpc Stream (EventStreamRequest) returns (stream Event); + rpc Resolve (ResolveEvent.Request) returns (ResolveEvent.Response); rpc GetEventConfiguration (EventConfiguration.Request) returns (EventConfiguration); rpc UpdateEventConfiguration (EventConfiguration) returns (EventConfiguration); @@ -433,6 +434,14 @@ message Event { /* The health level caused for the modem (and organization) by this event. */ health.HealthLevel health_level = 10; + + oneof resolved_status { + /* Whether this event was resolved. */ + bool resolved = 11; + + /* The identifier to use when resolving this event. Only present when not resolved */ + string resolve_identifier = 12; + } } } @@ -1006,8 +1015,7 @@ message Event { } } -/** A bundle/set of events, all of the same event-type. - */ +/* A bundle/set of events, all of the same event-type. */ message BundledEvent { EventType type = 1; string title = 3; @@ -1139,6 +1147,20 @@ message EventStreamRequest { Filter.ChildOrganizations child_organizations = 3; } +/* Resolve a resolvable event using its resolve_identifier. */ +message ResolveEvent { + message Request { + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ + string organization = 1; + + /* The resolve identifier of the event you wish to resolve. */ + string resolve_identifier = 2; + } + message Response { + Event event = 1; + } +} + /* Configuration for configurable events. * Some events are disable by default, or can be configured in different ways. Their configuration is available here. */ diff --git a/health.proto b/health.proto index e8ac974..69b1baf 100644 --- a/health.proto +++ b/health.proto @@ -100,8 +100,7 @@ message HealthLevel { /* Map of named colors, where key is the name and the value is a valid CSS3 color definition. */ map color_data = 4; - /** - * A numeric value equal to the index of this health level in the sorted list of health levels (starting at 1). + /* A numeric value equal to the index of this health level in the sorted list of health levels (starting at 1). * This means higher numbers denote a more severe health. */ int64 severity = 5; diff --git a/map.proto b/map.proto index 76da372..861be36 100644 --- a/map.proto +++ b/map.proto @@ -1,3 +1,54 @@ +/* Show modems on a map, using the calculated state of the map. + * + * Uses a tile-based system where the map is split up into tiles, and modems can be efficiently grouped into the tiles. + * The tiles are based on the Google Maps output, which allows us to draw thousands of markers on a map efficiently. + * + * This works as follows: + * Assume the world is a grid of 256x256 tiles, and every point can be represented as an x (from lon) and y (from lat) + * coordinate, for example: + * - (0,0) maps to world coordinate (128.0, 128.0) + * - (13.24,122.04) maps roughly to (214.78, 118.49) + * - (-84.27,175.36) maps roughly to (252.70, 250.05) + * Keep in mind that the order is reversed, lat -> -y, long -> x, to get a grid that goes + * from 0,0 at the bottom left of the map to 256,256 at the top right. + * + * Now that we have a simple numeric model of the world, we can start grouping numerically as well. + * If we want 256 horizontal and 256 vertical tiles, all we have to do is `floor` the values to determine their tile. + * Then, we can use the remainder to calculate their position within the tile on another 256x256 grid. + * For example: + * - (0,0) is in tile (128, 128) at (0.0,0.0) + * - (13.24,122.04) is in tile (214, 118) + * - (-84.27,175.36) is in tile (252, 250) + * + * While 65k tiles seems like a lot, it's not enough for the world, of course. So, we're using Google Maps' map levels + * to have more detail. These increase in size exponentially: + * - Level 0 : 1x1 : a single tile for the whole world, containing all of the modems + * - Level 1 : 2x2 : 4 tiles for the whole world. + * - Level 2 : 4x4 : 16 tiles for the whole world. + * - Level 3 : 8x8 : 64 tiles for the whole world. + * - Level 4 : 16x16 : 256 tiles for the whole world. + * - Level 5 : 32x32 : 1024 tiles for the whole world. + * - Level 6 : 64x64 : 4096 tiles for the whole world. + * - Level 7 : 128x128 : 16 384 tiles for the whole world. + * - Level 8 : 256x256 : 65 536 tiles for the whole world. + * - Level 9 : 512x512 : 262 144 tiles for the whole world. + * - Level 10 : 1024x1024 : 1 048 576 tiles for the whole world. + * - Level 11 : 2048x2048 : 4 194 304 tiles for the whole world. + * - Level 12 : 4096x4096 : 16 777 216 tiles for the whole world. + * - Level 13 : 8192x8192 : 67 108 864 tiles for the whole world. + * - Level 14 : 16384x16384 : 268 435 456 tiles for the whole world. + * - Level 15 : 32768x32768 : 1 073 741 824 tiles for the whole world. + * - Level 16 : 65536x65536 : 4 294 967 296 tiles for the whole world. + * - Level 17 : 131072x131072 : 17 179 869 184 tiles for the whole world. + * - Level 18 : 262144x262144 : 68 719 476 736 tiles for the whole world. + * - Level 19 : 524288x524288 : 274 877 906 944 tiles for the whole world. + * - Level 20 : 1048576x1048576 : 1 099 511 627 776 tiles for the whole world. + * - Level 21 : 2097152x2097152 : 4 398 046 511 104 tiles for the whole world. + * + * Finally, we can do the same `floor`-based grouping within the tile. Using the TileMapRequest.Density, we decide + * how many groups to split our tiles into. This means we can still align our tiles to Google Maps, but allow for + * a controlled amount of groups. + */ syntax = "proto3"; package hiber.map; @@ -11,9 +62,9 @@ option java_package = "global.hiber.api.grpc.map"; option java_outer_classname = "MapApi"; option go_package = "hiber"; -/* Map of modems, in different map levels to enable data to be displayed efficiently - */ +/* Map of modems, in different map levels to enable data to be displayed efficiently */ service MapService { + /* Show the selected modems on the map, in a selected area. */ rpc TileMap (TileMapRequest) returns (TileMapRequest.Response); } @@ -74,6 +125,10 @@ message TileMapRequest { DENSE = 1; /* Fills a tile with 4x4 icons. */ SPARSE = 2; + /* Fills a tile with 2x2 icons. */ + VERY_SPARSE = 3; + /* Fills a tile with 1 icon. */ + SINGLE = 4; } /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ diff --git a/modem.proto b/modem.proto index 4fdd024..e546b32 100644 --- a/modem.proto +++ b/modem.proto @@ -1,3 +1,8 @@ +/* Modem and message management. + * + * Modems are anything capable of sending messages to the system. They have a unique modem number, + * used to identify them. + */ syntax = "proto3"; package hiber.modem; @@ -18,25 +23,52 @@ option go_package = "hiber"; * This service contains calls to list and manage them, as well as list their messages. */ service ModemService { + /* Get a single modem. */ rpc Get (GetModemRequest) returns (Modem); + + /* Create new modem(s). This is only available if your organization can create modems. */ rpc Create (CreateModem.Request) returns (CreateModem.Response); + + /* List the modems in your organization, and, optionally, its child organizations. */ rpc List (ListModemsRequest) returns (ListModemsRequest.Response); + + /* List the modems in your organization, and, optionally, its child organizations, grouped by dependency. + * For example, a modem that sends it messages through a gateway (like Hilo) would be grouped under that gateway. + */ rpc Grouped (ListModemsGrouped.Request) returns (ListModemsGrouped.Response); + + /* List messages for the selected modems. */ rpc Messages (ListModemMessagesRequest) returns (ListModemMessagesRequest.Response); + + /* Count messages for the selected modems. */ rpc MessageCount (MessageCountRequest) returns (MessageCountRequest.Response); + rpc AvailableMessageFields (AvailableModemMessageFields.Request) returns (AvailableModemMessageFields.Response); + /* Change the name of a modem to the given value. */ rpc Rename (RenameModemRequest) returns (Modem); + /* Add, remove and create new tags for the selected modems. */ rpc UpdateTags (UpdateModemTagsRequest) returns (UpdateModemTagsRequest.Response); + + /* Change the notes for the selected modems to the given value. */ rpc UpdateNotes (UpdateModemNotesRequest) returns (UpdateModemNotesRequest.Response); + + /* Change the secure notes for the selected modems to the given value, if you have permission. */ rpc UpdateSecureNotes (UpdateModemSecureNotesRequest) returns (UpdateModemSecureNotesRequest.Response); + + /* Change the status of the selected modems to the given value. */ rpc UpdateStatus (UpdateModemStatusRequest) returns (UpdateModemStatusRequest.Response); + + /* Update the health configuration for the selected modems. */ rpc UpdateModemHealthConfig (UpdateModemHealthConfig.Request) returns (UpdateModemHealthConfig.Response); + + /* Add and remove peripherals for the selected modems. */ rpc UpdatePeripherals (UpdatePeripheralsRequest) returns (UpdatePeripheralsRequest.Response); rpc LicenseKeys (LicenseKeysRequest) returns (LicenseKeysRequest.Response); + /* Count the modems in your organization by health. */ rpc HealthCount (ModemHealthCount.Request) returns (ModemHealthCount.Response); } diff --git a/modem_alarm.proto b/modem_alarm.proto index 2f105cb..9220532 100644 --- a/modem_alarm.proto +++ b/modem_alarm.proto @@ -103,8 +103,7 @@ message ModemAlarm { */ string default_health_level = 7; - /** - * Allow the alarm to cause a health level for the modem even after a new message has come in. + /* Allow the alarm to cause a health level for the modem even after a new message has come in. * * Typically, an alarm event only affects the modem health while it is from the last message from that modem. * By configuring this, you can specify the modem health should be affected for a longer period. @@ -366,8 +365,7 @@ message ModemAlarm { } } - /** - * Allow the alarm to cause a health level for the modem even after a new message has come in. + /* Allow the alarm to cause a health level for the modem even after a new message has come in. * * Typically, an alarm event only affects the modem health while it is from the last message from that modem. * By configuring this, you can specify the modem health should be affected for a longer period. @@ -398,7 +396,7 @@ message ModemAlarmSelection { message ListModemAlarms { message Request { - /** Pick the organization to use (/impersonate). If unset, your default organization is used. */ + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; ModemAlarmSelection selection = 2; @@ -411,9 +409,16 @@ message ListModemAlarms { } } +/* Create a new alarm. + * + * The request contains the option to add checks as well. + * This is a shortcut for creating an alarm and then adding checks, and as such can result in multiple events: + * - a created event on the alarm + * - an update event on the alarm checks, iff any checks were added + */ message CreateModemAlarm { message Request { - /** Pick the organization to use (/impersonate). If unset, your default organization is used. */ + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; /* A short description of what the alarm should do. */ @@ -422,11 +427,7 @@ message CreateModemAlarm { /* Condition determining when an alarm is triggered if it has multiple checks. */ ModemAlarm.TriggerCondition trigger_condition = 3; - /* The checks to add to this alarm. - * This is a shortcut for creating an alarm and then adding checks to it, and as such results in two events: - * - the created event for the alarm - * - an update event on the alarm, adding the checks - */ + /* The checks to add to this alarm. Shortcut for creating an alarm and then adding checks to it. */ repeated ModemAlarm.Check checks = 4; /* The default health level for this alarm. See ModemAlarm.default_health_level for more information. */ @@ -442,16 +443,45 @@ message CreateModemAlarm { } } +/* Update the alarm, iff you are the owner or can impersonate the owner organization. + * + * The request contains the option to add, remove or update checks as well. + * This is a shortcut for updating an alarm and then adding, removing and/or updating checks, + * and as such can result in multiple events: + * - an update event on the alarm, iff there were any non-check changes to the alarm. + * - an update event on the alarm checks, iff there were any check addition, updates or deletions + */ message UpdateModemAlarm { message Request { - /** Pick the organization to use (/impersonate). If unset, your default organization is used. */ + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; + + /* The identifiers of the alarm to update */ string identifier = 2; + + /* Update the description, optionally. */ UpdateClearableString update_description = 3; + + /* Update the trigger condition, optionally. */ ModemAlarm.TriggerCondition update_trigger_condition = 4; + + /* Update the default health level, optionally. */ UpdateClearableString update_default_health_level = 5; + + /* Update the health after resolved, optionally. */ ModemAlarm.HealthLevelAfterResolved update_health_level_after_resolved = 6; + + /* Remove the health after resolved, optionally. */ bool remove_health_level_after_resolved = 7; + + /* The checks to add to this alarm. Shortcut for updating an alarm and then adding checks to it. */ + repeated ModemAlarm.Check add_checks = 8; + + /* The checks to update in this alarm. Shortcut for updating an alarm and then updating checks. */ + map update_checks = 9; + + /* The checks to remove from this alarm. Shortcut for updating an alarm and then removing checks. */ + repeated string delete_checks = 10; } message Response { ModemAlarm updated = 1; @@ -461,7 +491,7 @@ message UpdateModemAlarm { /* Add a check to the alarm, iff you are the owner or can impersonate the owner organization. */ message UpdateModemAlarmAddCheck { message Request { - /** Pick the organization to use (/impersonate). If unset, your default organization is used. */ + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; string alarm_identifier = 2; @@ -475,7 +505,7 @@ message UpdateModemAlarmAddCheck { message UpdateModemAlarmUpdateCheck { message Request { - /** Pick the organization to use (/impersonate). If unset, your default organization is used. */ + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; string alarm_identifier = 2; string check_identifier = 3; @@ -496,7 +526,7 @@ message UpdateModemAlarmUpdateCheck { message UpdateModemAlarmRemoveCheck { message Request { - /** Pick the organization to use (/impersonate). If unset, your default organization is used. */ + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; string alarm_identifier = 2; string check_identifier = 3; @@ -508,7 +538,7 @@ message UpdateModemAlarmRemoveCheck { message DeleteModemAlarm { message Request { - /** Pick the organization to use (/impersonate). If unset, your default organization is used. */ + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; string identifier = 2; } @@ -518,7 +548,7 @@ message DeleteModemAlarm { message TestModemAlarmTestParameters { message Request { - /** Pick the organization to use (/impersonate). If unset, your default organization is used. */ + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; string alarm_identifier = 2; google.protobuf.Struct parameters = 3; @@ -530,7 +560,7 @@ message TestModemAlarmTestParameters { message UpdateModemAlarmAvailability { message Request { - /** Pick the organization to use (/impersonate). If unset, your default organization is used. */ + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; string alarm_identifier = 2; diff --git a/modem_message_body_parser.proto b/modem_message_body_parser.proto index 18d3526..914609a 100644 --- a/modem_message_body_parser.proto +++ b/modem_message_body_parser.proto @@ -1,3 +1,15 @@ +/* Modem message body parsers management. + * + * Modem message body parsers (short: parsers) are small scripts defined using the Kaitai Struct specification + * to parse binary data. + * Parsers are assigned to modems to parse the body of their messages dynamically. + * + * Parsers can be written manually as a .ksy file and uploaded through the API, or the simplified API implementation + * can be used to create a parser. + * + * For more information on Kaitai Struct, see [http://kaitai.io/](http://kaitai.io/), + * where you can find documentation, examples and a web IDE. + */ syntax = "proto3"; package hiber.modem.message.bodyparser; @@ -133,9 +145,7 @@ message ModemMessageBodyParser { /* The content of this parsers script. * If simple_parser is set, this content is generated from that definition. - * This field may be omitted on demand to save data in the list call. - * - * See Kaitai struct (https://kaitai.io/) for more information about the ksy format. + * This field may be omitted by the list call to save data. */ string content_ksy = 3; @@ -266,6 +276,7 @@ message SimpleModemMessageBodyParser { repeated SimpleModemMessageBodyParser custom_types = 6; } +/* Selection object for parsers. Used to select which parser to list, assign, etc. */ message ModemMessageBodyParserSelection { /* Filter parsers by their identifiers. */ repeated string identifiers = 8; @@ -293,6 +304,11 @@ message ModemMessageBodyParserSelection { reserved 1, 7; } +/* List the parser your organizations has access to. This may include inherited parsers. + * + * If include_content is not set, this call may omit parser specifications, like the ksy, since those are + * typically larger multi-line strings. + */ message ListModemMessageBodyParsersRequest { message Response { repeated ModemMessageBodyParser parsers = 1; @@ -309,12 +325,7 @@ message ListModemMessageBodyParsersRequest { bool exclude_content = 4; } -/* Upload a new body parser from a .ksy file. - * A .ksy file is a file defined using the Kaitai Struct specification. - * For more information on Kaitai Struct, see http://kaitai.io/, where you can find examples and a web ide. - * For more information on how .ksy files are use, see - * https://github.com/HiberGlobal/api/blob/master/modem_message_body_parser.proto for the API documentation. - */ +/* Upload a new body parser from a .ksy file. */ message UploadModemMessageBodyParserRequest { /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; @@ -335,12 +346,7 @@ message UploadModemMessageBodyParserRequest { ModemMessageBodyParser.MetadataFields metadata_fields = 10; } -/* Upload a new body parser from a .ksy file, replacing the previous file. - * A .ksy file is a file defined using the Kaitai Struct specification. - * For more information on Kaitai Struct, see http://kaitai.io/, where you can find examples and a web ide. - * For more information on how .ksy files are use, see - * https://github.com/HiberGlobal/api/blob/master/modem_message_body_parser.proto for the API documentation. - */ +/* Upload an updated body parser from a .ksy file, replacing the previous file. */ message UpdateUploadedModemMessageBodyParserRequest { message MetadataFields { /* Add metadata fields to the metadata fields list. */ @@ -425,6 +431,12 @@ message UpdateChildOrganizationAvailabilityRequest { reserved 2; } +/* Make this parser available to a specific child organizations. + * + * This will + * - when the organization is on the exclude list, remove it + * - when the includeAll flag is false, add it to the include list (if not already present) + */ message MakeModemMessageBodyParserAvailableToChildOrganizationRequest { /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; @@ -432,14 +444,16 @@ message MakeModemMessageBodyParserAvailableToChildOrganizationRequest { /* The identifier of the parser that should be updated. */ string identifier = 2; - /* The child organization(s) that the parser should be available to. - * This will - * - when the organization is on the exclude list, remove it - * - when the includeAll flag is false, add it to the include list (if not already present) - */ + /* The child organization(s) that the parser should be available to. */ repeated string available_to = 3; } +/* Make this parser unavailable to a specific child organizations. + * + * This will + * - when the organization is on the include list, remove it + * - when the includeAll flag is true, add it to the exclude list (if not already present) + */ message MakeModemMessageBodyParserUnavailableToChildOrganizationRequest { /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ string organization = 1; @@ -447,11 +461,7 @@ message MakeModemMessageBodyParserUnavailableToChildOrganizationRequest { /* The identifier of the parser that should be updated. */ string identifier = 2; - /* The child organization(s) that the parser should be unavailable to. - * This will - * - when the organization is on the include list, remove it - * - when the includeAll flag is true, add it to the exclude list (if not already present) - */ + /* The child organization(s) that the parser should be unavailable to. */ repeated string unavailable_to = 3; } @@ -466,8 +476,9 @@ message DeleteModemMessageBodyParserRequest { ModemMessageBodyParserSelection selection = 2; } -/* Test a parsers with a message. - * This method provides a bunch of options and can be used in multiple ways: +/* Test a parsers on a message. + * + * This method provides a number of options and can be used in multiple ways: * - Test a real message or an uploaded message body. * - Test using an existing parser, an ksy definition or a simple parser definition. * diff --git a/modem_transfer.proto b/modem_transfer.proto index 83ebe28..185da69 100644 --- a/modem_transfer.proto +++ b/modem_transfer.proto @@ -170,12 +170,12 @@ message TransferModemsRequest { TRANSFER_EXTERNAL_DEVICES = 3; } - /** What to do with the messages, events and other related data. */ + /* What to do with the messages, events and other related data. */ enum DataTransferMode { - /** Include all related data in the transfer. */ + /* Include all related data in the transfer. */ INCLUDE = 0; - /** Exclude messages and all events. The data will be deleted. */ + /* Exclude messages and all events. The data will be deleted. */ EXCLUDE_ALL = 1; } @@ -236,7 +236,7 @@ message TransferModemsRequest { GatewayTransferMode gateway_transfer_mode = 8; } - /** What to do with the modem's data, like messages and events. */ + /* What to do with the modem's data, like messages and events. */ DataTransferMode data_transfer_mode = 9; } diff --git a/permission.proto b/permission.proto index d1dafe4..b8b2645 100644 --- a/permission.proto +++ b/permission.proto @@ -42,7 +42,7 @@ enum OrganizationPermission { MODEMS_MESSAGE_BODY_PARSERS = 43; /* Show and update secure notes. Includes MODEMS permission. */ MODEMS_SECURE_NOTES = 42; - /** Manage and assign message alerts. Includes MODEMS permission. */ + /* Manage and assign message alerts. Includes MODEMS permission. */ MODEMS_ALARMS = 44; /* Read modem messages. */