From eac2b44ea30da1f88fe95045ec1d5cd8d4290adf Mon Sep 17 00:00:00 2001 From: Wouter Bouvy Date: Thu, 5 Aug 2021 11:40:22 +0200 Subject: [PATCH] 0.82 --- CHANGELOG.md | 49 + base.proto | 21 + docs/easypulse.html | 4369 ++++++++++++++++++++++++ docs/easypulse.md | 1846 ++++++++++ docs/permission.html | 635 ++++ docs/permission.md | 113 + easypulse.proto | 267 ++ event-json-examples/modem-created.json | 2 +- health.proto | 89 +- modem_alarm.proto | 1 - modem_claim.proto | 1 - modem_message_body_parser.proto | 48 +- modem_message_downlink.proto | 159 + permission.proto | 10 +- subscription.proto | 3 - user.proto | 1 - webhook.proto | 1 - 17 files changed, 7551 insertions(+), 64 deletions(-) create mode 100644 docs/easypulse.html create mode 100644 docs/easypulse.md create mode 100644 docs/permission.html create mode 100644 docs/permission.md create mode 100644 easypulse.proto create mode 100644 modem_message_downlink.proto diff --git a/CHANGELOG.md b/CHANGELOG.md index 4c5fe97..784b853 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,54 @@ # Changelog Hiber API +### 0.82 (2021-08-05) + +#### Changes + +- Removed a few unnecessary imports. + +##### EasypulseService + +- Introduced the `EasypulseService` for Easypulse-specific implementations. + - This API requires the `Organization.Feature.EASYPULSE` feature flag. + - This is mostly a convenience view on the normal modems and messages. + - `Easypulse.History` allows you to fetch individual message fields and apply aggregations to them, for example + - the average pressure per day + - the sum of run time per week + - This feature will be made available for all organizations soon in the `ModemService`. + +##### EventService + +- Corrected the text for ModemCreatedEvent, which is now produced any time modems are created, whether it is manually + or automatically. + +##### HealthService + +- Cleaned up the documentation for `HealthLevel`. + +##### ModemMessageBodyParserService + +- Added `ModemMessageBodyParser.DataField` to define more properties for data fields in a parser. + This is mostly used internally, to power the new Easypulse service. + - Updated `ModemMessageBodyParser`, `UploadModemMessageBodyParserRequest` and + `UpdateUploadedModemMessageBodyParserRequest`: + - Deprecated and renamed the repeated string `data_fields` to `data_fields_deprecated`. + - Added `data_fields` as the repeated `DataField`s. + - Introduced `UnitOfMeasurement` in `base.proto` to support defining the type for parser data fields. + +##### ModemDownlinkMessageService + +- Introduced the experimental `ModemDownlinkMessageService` to store and fetch messages that should be sent to + your devices. + For now, this is just a CRUD service to prepare and fetch messages, but expect more features in the future. + +##### OrganizationPermissions + +- Added `OrganizationPermission.MODEM_DOWNLINK_MESSAGES` for using the new ModemDownlinkMessageService. + +#### Generated Documentation + +- In this release, we're experimenting with some automatically generated documentation in the `docs` folder. + ### 0.81 (2021-07-05) This release contains a collection of minor features: diff --git a/base.proto b/base.proto index 13d7b1d..79006d3 100644 --- a/base.proto +++ b/base.proto @@ -424,3 +424,24 @@ message Avatar { NamedFile image = 2; } } + +/* Unit of measurement for a numeric value. */ +enum UnitOfMeasurement { + UNIT_UNKNOWN = 0; + DURATION_SECONDS = 1; + DURATION_MINUTES = 2; + DURATION_HOURS = 3; + DURATION_DAYS = 4; + TEMPERATURE_KELVIN = 5; + TEMPERATURE_DEGREES_CELSIUS = 6; + TEMPERATURE_DEGREES_FAHRENHEIT = 7; + DISTANCE_METER = 8; + DISTANCE_MILLIMETER = 9; + DISTANCE_CENTIMETER = 10; + DISTANCE_KILOMETER = 11; + PRESSURE_BAR = 12; + PRESSURE_BAR_GROUND = 13; + PRESSURE_PSI = 14; + VOLTAGE_MILLIVOLT = 15; + PERCENT = 16; +} diff --git a/docs/easypulse.html b/docs/easypulse.html new file mode 100644 index 0000000..e177729 --- /dev/null +++ b/docs/easypulse.html @@ -0,0 +1,4369 @@ + + + + + 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 new file mode 100644 index 0000000..253e25c --- /dev/null +++ b/docs/easypulse.md @@ -0,0 +1,1846 @@ +# Protocol Documentation + + +## 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 +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). + + +| 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. | + + + + + + + + +### Easypulse.Asset.AggregationsEntry + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| key | [string](#string) | | | +| value | [Easypulse.History.Response](#hiber.easypulse.Easypulse.History.Response) | | | + + + + + + + + +### 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. | + + + + + + + + +### Easypulse.Asset.PeripheralsEntry + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| key | [string](#string) | | | +| value | [string](#string) | | | + + + + + + + + +### 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. | + + + + + + + + +### 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. + + +| 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. | + + + + + + + + +### 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. | + + + + + + + + +### 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. | + + + + + + + + +### 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. | + + + + + + + + +### Easypulse.ListAssets.Request.AggregationsEntry + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| key | [string](#string) | | | +| value | [Easypulse.History.Request](#hiber.easypulse.Easypulse.History.Request) | | | + + + + + + + + +### 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. | + + + + + + + + +### 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. | + + + + + + + + + + +### 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). | + + + + + +### 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 + + + + + + + + + +### AddHealthLevel.Request + + + +| 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). | + + + + + + + + +### 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. + +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 + + +| 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. | + + + + + + + + +### HealthLevel.ColorDataEntry + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| key | [string](#string) | | | +| value | [string](#string) | | | + + + + + + + + +### HealthLevelSelection + + + +| 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. | + + + + + + + + +### ListHealthLevels + + + + + + + + + +### ListHealthLevels.Request + + + +| 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) | | | + + + + + + + + +### ListHealthLevels.Response + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| health_levels | [HealthLevel](#hiber.health.HealthLevel) | repeated | | +| request | [ListHealthLevels.Request](#hiber.health.ListHealthLevels.Request) | | | + + + + + + + + +### RemoveHealthLevel + + + + + + + + + +### RemoveHealthLevel.Request + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| organization | [string](#string) | | Pick the organization to use (/impersonate). If unset, your default organization is used. | +| level | [string](#string) | | | + + + + + + + + +### RemoveHealthLevel.Response + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| health_levels | [HealthLevel](#hiber.health.HealthLevel) | repeated | | + + + + + + + + +### ReorderHealthLevels +Re-order the health levels for your organization. + + + + + + + + +### ReorderHealthLevels.Request + + + +| 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. | + + + + + + + + +### ReorderHealthLevels.Response + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| reordered_health_levels | [HealthLevel](#hiber.health.HealthLevel) | repeated | | + + + + + + + + +### UpdateHealthLevel + + + + + + + + + +### UpdateHealthLevel.Request + + + +| 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. | + + + + + + + + +### UpdateHealthLevel.Request.AddColorsEntry + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| key | [string](#string) | | | +| value | [string](#string) | | | + + + + + + + + +### UpdateHealthLevel.Response + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| health_levels | [HealthLevel](#hiber.health.HealthLevel) | repeated | | + + + + + + + + + + + + + + +### HealthService + + +| 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. | + + + + + + +

Top

+ +## tag.proto + + + + + +### CreateTagRequest + + + +| 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) | | | + + + + + + + + +### 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) | | | + + + + + + + + + + +### 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 +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 | | + + + + + + + + + + +## 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) | + diff --git a/docs/permission.html b/docs/permission.html new file mode 100644 index 0000000..ac2de08 --- /dev/null +++ b/docs/permission.html @@ -0,0 +1,635 @@ + + + + + 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 new file mode 100644 index 0000000..80b22eb --- /dev/null +++ b/docs/permission.md @@ -0,0 +1,113 @@ +# Protocol Documentation + + +## Table of Contents + +- [permission.proto](#permission.proto) + - [OrganizationPermission](#hiber.OrganizationPermission) + - [UserPermission](#hiber.UserPermission) + +- [Scalar Value Types](#scalar-value-types) + + + + +

Top

+ +## permission.proto +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. + +| 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. | + + + + + +### 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) | + diff --git a/easypulse.proto b/easypulse.proto new file mode 100644 index 0000000..e5601df --- /dev/null +++ b/easypulse.proto @@ -0,0 +1,267 @@ +/* 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. + */ +syntax = "proto3"; + +package hiber.easypulse; + +import "base.proto"; +import "health.proto"; +import "tag.proto"; + +option java_multiple_files = false; +option java_package = "global.hiber.api.grpc.easypulse"; +option java_outer_classname = "EasypulseApi"; +option go_package = "hiber"; + +/* Service to list and manage Assets. */ +service EasypulseService { + rpc Assets (Easypulse.ListAssets.Request) returns (Easypulse.ListAssets.Response); + rpc History (Easypulse.History.Request) returns (Easypulse.History.Response); +} + +message Easypulse { + + /* 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). + */ + message Asset { + /* The organization the asset is in. */ + string organization = 1; + + /* The modem number for the Asset. */ + string number = 2; + + /* The custom name for the Asset, defaults to modem number. */ + string name = 3; + + /* Optional external identifier the Asset may have. */ + string external_identifier = 4; + + /* A key value map of peripherals for the Assets. */ + map peripherals = 5; + + /* Add additional notes to an asset. */ + string notes = 6; + + /* Add additional notes to an asset that only people with the permission can access. */ + string secure_notes = 7; + + /* Health level based on the modem alarm and some always-present alarms. */ + health.HealthLevel health_level = 8; + + /* Tags (or groups, when used in Mission Control) this asset is in. */ + repeated hiber.tag.Tag tags = 9; + + /* When this asset was last updated. */ + LastUpdate last_update = 10; + + /* The most recent fuel level, as a percentage. */ + float fuel_level = 11; + + /* The most recent tire pressure in bar. */ + float tire_pressure = 12; + + /* The most recent battery level, as a percentage. */ + float battery_level = 13; + + /* The most recent temperature in degrees Celsius. */ + float temperature = 14; + + /* The most recently reported location. */ + Location location = 15; + + /* Any aggregations added when this asset was requested. */ + map aggregations = 16; + + /* Information about the last update we received from this asset. */ + message LastUpdate { + uint64 id = 1; + + /* Time the server has received the last update. */ + Timestamp received_at = 2; + + /* Time the asset sent the last update. */ + Timestamp sent_at = 3; + + /* The body of the last update. */ + BytesOrHex body = 4; + } + } + + /* 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 + */ + message AssetSelection { + /* Search for assets by name, modem number, tag or notes. */ + string search = 1; + + /* Select assets by modem number. */ + Filter.Modems assets = 2; + + /* Select assets by health level. */ + repeated string health_levels = 3; + + /* Select assets by tag. */ + hiber.tag.TagSelection filter_by_tags = 4; + } + + /* 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. + */ + message ListAssets { + + /* Request to list Assets in your organization. */ + message Request { + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ + string organization = 1; + + /* Select the Assets to return. */ + AssetSelection selection = 2; + + /* Paginate over the returned Assets. */ + Pagination pagination = 3; + + /* Any aggregations to return with the assets, specified as a name and a History.Request. */ + map aggregations = 4; + + /* Sort the returned assets using the given option. By default, Assets are sorted by name. */ + Sort sort = 5; + + enum Sort { + 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; + LOWEST_TEMPERATURE = 12; + HIGHEST_TEMPERATURE = 13; + } + } + + /* Response with a list of Assets */ + message Response { + /* The selected Assets. */ + repeated Asset assets = 1; + + /* The applied pagination, including total results, page information, etc. */ + Pagination.Result pagination = 2; + + /* The request that was received, corrected and used to produce this result. */ + Request request = 3; + } + } + + /* List the history for a single field, and optionally apply an aggregation and/or grouping to it. */ + message History { + + /* Request to get the history of a field, for the selected Assets in the organization. */ + message Request { + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ + string organization = 1; + + /* Select the asset(s) to get the history for. */ + AssetSelection selection = 2; + + /* Paginate the returned values. + * This may not be relevant, depending on the aggregation (which may result in a single value) and the + * time range. + */ + Pagination pagination = 13; + + /* The time to view the history for. */ + TimeRange time_range = 3; + + /* How to aggregate the data. */ + Aggregation aggregation = 4; + + /* Options to group the data, reducing data points to a set of groups. + * If no grouping is set, the aggregation typically returns a single value. + */ + oneof group { + /* Split up the data in time block of the given size. */ + Duration split_by_duration = 5; + + /* Limit the results to the given amount of data points, applying the function to each chunk. */ + uint32 reduce_to_max_size = 6; + } + + oneof field { + bool fuel_level = 7; // Get the history for the fuel level. Only one field can be chosen. + bool tire_pressure = 8; // Get the history for the tire pressure. Only one field can be chosen. + bool battery_level = 9; // Get the history for the battery level. Only one field can be chosen. + bool temperature = 10; // Get the history for the temperature. Only one field can be chosen. + bool run_time = 11; // Get the history for the run time. Only one field can be chosen. + bool idle_time = 12; // Get the history for the idle time. Only one field can be chosen. + } + + /* Options to aggregate the history data points (in a group). */ + enum Aggregation { + /* Do not aggregate the history data points, just list all of them. */ + NONE = 0; + + /* Average value of all history data points (in a group). */ + AVERAGE = 1; + + /* Sum all history data points (in a group). */ + SUM = 2; + } + } + + /* Response with the (aggregated) history of a field, for the selected Assets in the organization. */ + message Response { + /* 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. + */ + repeated Value values = 1; + + /* The pagination result, containing information about amounts and pages. */ + Pagination.Result pagination = 2; + + /* The request that was received, corrected and used to produce this result. */ + Request request = 3; + + /* Processed historical data point. If this is a group, it will have a time range to denote the group. */ + message Value { + oneof time { + /* When not grouping, time of the individual point. + * When grouping, the time at the end of the group (when the value was true). + */ + Timestamp timestamp = 1; + + /* When grouping, the start and end time for the group. */ + TimeRange time_range = 2; + } + + oneof value { + float fuel_level = 3; // The fuel level, as a percentage. + float tire_pressure = 4; // The tire pressure in bar. + float battery_level = 5; // The battery level, as a percentage. + float temperature = 6; // The temperature in degrees Celsius. + Duration run_time = 7; // The time the Asset was running. + Duration idle_time = 8; // The time the Asset was idle. + } + } + } + } +} diff --git a/event-json-examples/modem-created.json b/event-json-examples/modem-created.json index afb1520..869420e 100644 --- a/event-json-examples/modem-created.json +++ b/event-json-examples/modem-created.json @@ -20,7 +20,7 @@ } } ], - "title": "Modem AAAA AAAA was automatically created.", + "title": "Modem AAAA AAAA was created.", "description": "Modem AAAA AAAA was automatically created for device 00 11 22 33 AA BB CC DD.", "modemExternalDeviceId": "00 11 22 33 AA BB CC DD" } diff --git a/health.proto b/health.proto index 60cdd8b..e8ac974 100644 --- a/health.proto +++ b/health.proto @@ -51,6 +51,39 @@ service HealthService { * 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 */ message HealthLevel { /* The name of this health level. @@ -59,63 +92,17 @@ message HealthLevel { */ string level = 1; - /* A string that represents a valid CSS3 colour. - * Simple examples are: green, red, orange, grey, #FF00FF for fuchsia, etc. - * Keep in mind that CSS3 allows for more ways to define colors. - * (See https://www.w3.org/TR/2003/WD-css3-color-20030214/) - * All the following definitions 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. - * - * DEPRECATED Use the color "text" from color_data; + /* 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. */ string color = 2 [deprecated = true]; - /* 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 colour. - * Simple examples are: green, red, orange, grey, #FF00FF for fuchsia, etc. - * Keep in mind that CSS3 allows for more ways to define colors. - * (See https://www.w3.org/TR/2003/WD-css3-color-20030214/) - * All the following definitions 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. - * - * The client is responsible 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. - */ + /* Map of named colors, where key is the name and the value is a valid CSS3 color definition. */ map color_data = 4; /** - * A numeric representation of the severity of this health level. - * Higher numbers denote a more severe health. - * Note that severity numbers are specific per organization and can change in time. - * For example, some organization might 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 - * - * Long story short: - * - don't cache these levels - * - don't compare levels between organizations - * - only compare these levels when you get them in the same call + * 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/modem_alarm.proto b/modem_alarm.proto index d417dbb..c42c090 100644 --- a/modem_alarm.proto +++ b/modem_alarm.proto @@ -6,7 +6,6 @@ import "google/protobuf/struct.proto"; import "base.proto"; import "modem.proto"; -import "modem_message_body_parser.proto"; option java_multiple_files = false; option java_package = "global.hiber.api.grpc.modem.alarm"; diff --git a/modem_claim.proto b/modem_claim.proto index 4630598..0fe92f8 100644 --- a/modem_claim.proto +++ b/modem_claim.proto @@ -3,7 +3,6 @@ syntax = "proto3"; package hiber.modem; import "base.proto"; -import "modem.proto"; import "tag.proto"; option java_multiple_files = false; diff --git a/modem_message_body_parser.proto b/modem_message_body_parser.proto index 2a6cee6..37c76c6 100644 --- a/modem_message_body_parser.proto +++ b/modem_message_body_parser.proto @@ -62,6 +62,43 @@ message ModemMessageBodyParser { Filter.ChildOrganizations child_organizations = 1; } + /* Fields in the parsed result that contain data. + * Data fields are cached for efficient retrieval and allow all kinds of processing. + */ + message DataField { + enum Type { + OTHER = 0; + + /* This field contains numeric values, with an optional unit of measurement defined below. */ + NUMERIC = 1; + + /* This field contains text to be displayed. */ + TEXT = 2; + + /* This field switches between several predefined values. Typically used for status fields. */ + ENUM = 3; + } + + /* The name of the field (if in the root structure) or a JsonPath to the field. */ + string name = 1; + + /* An optional display name for the field. */ + string display_name = 2; + + /* 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. + */ + bool encrypted = 3; + + /* If numeric, the unit of the value. */ + UnitOfMeasurement unit_of_measurement = 4; + + /* The type of field. */ + Type type = 5; + } + /* Fields in the parsed result that match common things that can be processed by the system, * like a location or battery percentage. */ message MetadataFields { @@ -102,9 +139,10 @@ message ModemMessageBodyParser { SimpleModemMessageBodyParser simple_parser = 4; /* Fields in the parsed result that contain data. - * This can be useful to track which fields could be plotted, etc. + * Data fields are cached for efficient retrieval and allow all kinds of processing. */ - repeated string data_fields = 9; + repeated DataField data_fields = 11; + repeated string data_fields_deprecated = 9 [deprecated = true]; /* Fields in the parsed result that contain metadata, and special things like a location. */ MetadataFields metadata_fields = 10; @@ -284,7 +322,8 @@ message UploadModemMessageBodyParserRequest { /* Fields in the parsed result that contain data. * This can be useful to track which fields could be plotted, etc. */ - repeated string data_fields = 4; + repeated ModemMessageBodyParser.DataField data_fields = 5; + repeated string data_fields_deprecated = 4 [deprecated = true]; /* Fields in the parsed result that match special things that can be processed by the system, like a location. */ ModemMessageBodyParser.MetadataFields metadata_fields = 10; @@ -318,7 +357,8 @@ message UpdateUploadedModemMessageBodyParserRequest { string content_ksy = 3; /* Add fields to the data fields list. */ - repeated string add_data_fields = 5; + repeated ModemMessageBodyParser.DataField add_data_fields = 7; + repeated string add_data_fields_deprecated = 5 [deprecated = true]; /* Remove fields from the data fields list. */ repeated string remove_data_fields = 6; diff --git a/modem_message_downlink.proto b/modem_message_downlink.proto new file mode 100644 index 0000000..4c141f0 --- /dev/null +++ b/modem_message_downlink.proto @@ -0,0 +1,159 @@ +syntax = "proto3"; + +package hiber.modem.downlink; + +import "google/protobuf/struct.proto"; + +import "base.proto"; +import "modem.proto"; + +option java_multiple_files = false; +option java_package = "global.hiber.api.grpc.modem.downlink"; +option java_outer_classname = "ModemDownlinkMessageApi"; +option go_package = "hiber"; + +service ModemDownlinkMessageService { + rpc List (ListDownlinkMessages.Request) returns (ListDownlinkMessages.Response); + rpc Create (CreateDownlinkMessages.Request) returns (CreateDownlinkMessages.Response); + rpc UpdateStatus (UpdateDownlinkMessagesStatus.Request) returns (UpdateDownlinkMessagesStatus.Response); +} + +/* A message to send to a device. + * This is typically used to update device configuration or trigger certain message types. + */ +message ModemDownlinkMessage { + enum Status { + /* Message was created but not sent to the device. */ + CREATED = 0; + + /* Message was sent to the device, but not acknowledged. */ + SENT = 1; + + /* Message was sent to the device, and acknowledged. */ + ACKNOWLEDGED = 2; + } + + /* Identifier for this downlink message. + * Unique within the organization. + * Can be set manually or, if omitted on creation, automatically generated. + */ + string identifier = 1; + + /* The modem number of the device this message should be sent to. */ + string modem_number = 2; + + /* The binary body of the message. */ + BytesOrHex body = 3; + + /* Any metadata for the message, like fPort for LoRaWAN. */ + google.protobuf.Struct metadata = 4; + + /* The status of this message. */ + Status status = 5; + + /* When this downlink message was created. */ + Timestamp created_at = 6; + + /* When this downlink message was sent to the device. */ + Timestamp sent_at = 7; + + /* When this downlink message was acknowledged by the device. */ + Timestamp acknowledged_at = 8; + + /* Whether acknowledgement is required, determining when this messages is considered completed. */ + bool acknowledgement_required = 9; +} + +/* Selection object to select ModemDownlinkMessages. */ +message ModemDownlinkMessageSelection { + /* Search downlink messages by identifier, modem number, modem tags or metadata */ + string search = 1; + + /* Select downlink messages by identifier(s). */ + repeated string identifiers = 2; + + /* Select modems to list downlink messages for. */ + modem.ModemSelection modems = 3; + + /* Select downlink messages that have one of the given statuses. */ + repeated ModemDownlinkMessage.Status include_status = 4; + + /* Select downlink messages that have none of the given statuses. */ + repeated ModemDownlinkMessage.Status exclude_status = 5; + + /* Select downlink messages that were created or updated withing the time range. */ + TimeRange time_range = 6; + + /* Whether to include downlink messages that have already been sent and acknowledged (if required). */ + bool include_completed = 7; +} + +message CreateDownlinkMessages { + message Request { + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ + string organization = 1; + + /* Downlink messages to send. + * All ModemDownlinkMessage fields are optional except for modem_number and content. + */ + repeated ModemDownlinkMessage messages = 2; + } + message Response { + /* The created messages. */ + repeated ModemDownlinkMessage messages = 1; + } +} + +message ListDownlinkMessages { + enum Sort { + /* Sort by last change, last changed first. */ + DEFAULT = 0; + + /* Sort by created time, oldest first. */ + CREATED_OLDEST_FIRST = 1; + /* Sort by created time, newest first. */ + CREATED_NEWEST_FIRST = 2; + + /* Sort numerically on the number of the modem. */ + MODEM_NUMBER = 3; + /* Sort numerically on the number of the modem, inverted. */ + MODEM_NUMBER_INVERTED = 4; + } + + message Request { + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ + string organization = 1; + ModemDownlinkMessageSelection selection = 2; + Pagination pagination = 3; + Sort sort = 4; + } + message Response { + repeated ModemDownlinkMessage messages = 1; + Pagination.Result pagination = 2; + Request request = 3; + } +} + +message UpdateDownlinkMessagesStatus { + message Request { + /* Pick the organization to use (/impersonate). If unset, your default organization is used. */ + string organization = 1; + + /* The downlink messages to update. */ + ModemDownlinkMessageSelection selection = 2; + + /* The new status for the selected messages. */ + ModemDownlinkMessage.Status update_status = 3; + + /* Pagination for the downlink messages listed in the response. + * (All selected messages are updated, regardless of pagination). + */ + Pagination pagination = 4; + } + message Response { + /* The updated messages. */ + repeated ModemDownlinkMessage messages = 1; + Pagination.Result pagination = 2; + Request request = 3; + } +} diff --git a/permission.proto b/permission.proto index 13e75fd..d1dafe4 100644 --- a/permission.proto +++ b/permission.proto @@ -1,3 +1,5 @@ +/* Permissions limit what a user can do through the API. + */ syntax = "proto3"; package hiber; @@ -6,7 +8,7 @@ option java_multiple_files = true; option java_package = "global.hiber.api.grpc"; option go_package = "hiber"; -/* Permissions limit what a user can do through the API. +/* 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) @@ -49,6 +51,8 @@ enum OrganizationPermission { MODEM_MESSAGES_SEND_TEST_MESSAGES = 16; /* Send modem messages using real message sources (i.e. gateway). Does not include MODEMS or MESSAGES permission. */ MODEM_MESSAGES_SEND_REAL_MESSAGES = 41; + /* Send modem downlink messages. */ + MODEM_DOWNLINK_MESSAGES = 51; /* See modem transfers, inbound and outbound modems. Includes modems permission. */ MODEM_TRANSFERS = 20; @@ -98,6 +102,10 @@ enum OrganizationPermission { reserved 40, 37; } +/* 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. + */ enum UserPermission { /* Read your name, email, linked organizations and mission-control settings. */ READ = 0; diff --git a/subscription.proto b/subscription.proto index a5149e7..6bd0f21 100644 --- a/subscription.proto +++ b/subscription.proto @@ -2,9 +2,6 @@ syntax = "proto3"; package hiber.organization.subscription; -import "base.proto"; -import "google/protobuf/timestamp.proto"; - option java_multiple_files = false; option java_package = "global.hiber.api.grpc.organization.subscription"; option java_outer_classname = "SubscriptionApi"; diff --git a/user.proto b/user.proto index 83f942d..d5bb3ba 100644 --- a/user.proto +++ b/user.proto @@ -3,7 +3,6 @@ syntax = "proto3"; package hiber.user; import "base.proto"; -import "permission.proto"; option java_multiple_files = false; option java_package = "global.hiber.api.grpc.user"; diff --git a/webhook.proto b/webhook.proto index 4becfb2..5f2dc63 100644 --- a/webhook.proto +++ b/webhook.proto @@ -3,7 +3,6 @@ syntax = "proto3"; package hiber.webhook; import "base.proto"; -import "google/protobuf/timestamp.proto"; import "tag.proto"; option java_multiple_files = false;