Evergateways receive and retransmit sensor readings securely and wirelessly, using the Evernet communications protocol. This protocol currently has two versions (Evernet1 and Evernet2), and sensors use one or the other. Each gateway is configured with settings that control how it communicates with each kind of sensor. An installation can include both kinds of sensors, and sensors can communicate with any available gateway, depending on current conditions.

Each gateway is configured on installation with a serial number and unique identifier; either value can be used as a path parameter to address that device. In addition, each gateway has a display name, a descriptive location string, and an arbitrary note that can be configured through the API.

In addition to relaying sensor data, gateways report their own communication status periodically, using one of two message protocols (v1 and v3).

Resource summary

Base URI is https://api.data.everactive.com/ds/{ds-api-version}

Evergateway endpoints	Supported operations
`{baseURI}/evergateways`	GET retrieves a list of gateways.
`{baseURI}/evergateways/{gatewayIdOrSerialNumber}`	GET retrieves the configuration of a specific gateway. PUT updates a gateway configuration.
`{baseURI}/evergateways/status/{version}`	GET retrieves a history of gateway communication status in a time range, using the v1 or v3 message protocol.
`{baseURI}/evergateways/status/v3/daily`	GET retrieves a detailed daily communication status report, using the v3 message protocol.

Retrieving gateways

A GET request to the {baseURI}/evergateways endpoint returns a list of gateways. You can retrieve all gateways in your installation, or filter the list by various criteria. You can get paged results for large lists.

Query parameters	Description
`serial-number`	Use a match string to filter for serial numbers that contain that string. If matching to a partial serial number returns multiple results, check for the complete serial number to uniquely identify the gateway. Use either the assigned UID or the complete serial number as a path parameter to address an individual device.
`location` `name`	Use a match string to filter for devices whose location or name value contains that string.
`page` `page-size` `sort-by` `sort-dir`	Get paged and sorted results.

Query parameters

Description

serial-number

Use a match string to filter for serial numbers that contain that string.

If matching to a partial serial number returns multiple results, check for the complete serial number to uniquely identify the gateway.

Use either the assigned UID or the complete serial number as a path parameter to address an individual device.

location
name

Use a match string to filter for devices whose location or name value contains that string.

page
page-size
sort-by
sort-dir

Get paged and sorted results.

Retrieving and managing gateway configuration

Each gateway is configured on installation with a serial number and unique identifier; either value can be used as a path parameter to address that device.

Path parameter	Description
{gatewayIdOrSerialNumber}	The serial number or assigned UID of the gateway to query.

Each gateway has a user-defined display name, descriptive location string, and arbitrary note that can be configured through the API.

Retrieve a gateway

To retrieve configuration information for a gateway, send a GET request to the individual gateway endpoint:

{baseURI}/evergateways/{gatewayIdOrSerialNumber}

Response

On success, the body of the response contains a JSON object with the following properties:

Gateway config properties	Description
`authorized`	True if the gateway is installed and associated with a customer.
`brokers`	An array of JSON objects describing the MQTT brokers that a gateway is authorized to use for sending data up to the cloud.
`canSupportEvernet`	True if this gateway can support the Evernet2 protocol.
`configSchema`	The message schema used in the last configuration message sent from this gateway.
`deploymentStatus`	One of “Commissioned”, “To Be Installed”, or “Decommissioned”. A commisioned gateway has been deployed and authorized.
`enableSSH`	True if secure shell protocol (SSH) is enabled for this gateway.
`enableWakeup`	True this gateway signals its paired sensors to turn on and send data. When false, no data is captured.
`evernet1Settings`	A JSON object containing the following settings that support Evernet1 sensors: -- `enabled`: True to enable Evernet 1.0 protocol for communication with 1st-generation Eversensors. -- `syncTime`: A time at which the gateway starts the wake-up process to communicate with sensors. -- `wakeupCode`: A signal the gateway will send to sensors to request data. -- `wakeupOffset`: An interval at which to send wake-up signals, to prevent collisions of signal transmissions. Typically set in increments of 10 seconds. -- `wakeupPeriod`: How often the gateway broadcasts the wake-up signal to turn on all sensors paired with this gateway.
`evernet2Settings`	A JSON object containing the following settings that support Evernet2 sensors: -- `enabled`: True to enable Evernet 2.0 protocol for communication with 2nd-generation Eversensors. -- `beaconOffset`: An interval at which to emit beacons to sensors, to prevent collisions of signal transmissions. . Typically set in increments of 200 milliseconds. -- `broadcastPeriod`: How often the gateway broadcasts the message to turn on all sensors paired with this gateway. -- `panId`: A Personal Area Network (PAN) identifier. Must be different from that of neighboring gateways when their wireless networks overlap.
`id`	A unique identifier for this gateway.
`installNotes`	Notes about the gateway installation.
`location`	The location of the gateway.
`name`	The display name of the gateway. Typically set to the serial number.
`profileImage`	A URI for a profile image file associated with this gateway, if any.
`lastReading` `timestamp`	The most recent reading received from this gateway, and the time it was received.
`lastStatus`	The status-message schema used in the most recent status report sent from this gateway. -- `gateway_status_schema.json` indicates v1. -- `gateway_status_v3.schema.json` indicates v3. See Retrieving gateway status data below for details.
`lastDailyStatus`	For a gateway that uses the v3 message schema, the last v3 daily status message received,
`serialNumber` `gatewaySerialNumber`	The serial number of this gateway. Not configurable, but can be used for partial matching in searches.
`status`	One of "Offline" or "Online"

Manage gateway configuration

To change or update the configurable features of a gateway, send a PUT request to the individual gateway endpoint:

{baseURI}/evergateways/{gatewayIdOrSerialNumber}

The body of the request contains a JSON object with the configuration properties you wish to change and their new values. These are the same as the properties returned in response to the GET request, with the exception of the serial number, status, and last-reading values.

Retrieving gateway status data

Each Evergateway reports its own status periodically throughout the day, using one of two message schemas. Use the status endpoints to retrieve a time-sliced set of these series reports. When it is configured to use the newer message schema, a gateway can also send a smaller digest of its daily status.

📘
Gateway status message schemas
The first version of the status message schema (v1) will be deprecated as gateways are migrated to the newer version (v3). Once a gateway is migrated, it will always use the new version, which also supports a smaller, less detailed daily report suitable for display to users.
The gateway configuration, as returned in the list of gateways or for an individual gateway, includes an indication of the status message schema currently in use.

Series status

All gateways send periodic reports of its own system and connectivity status, using either the v1 or v3 message schema.

To retrieve a set of series reports from a gateway , send a GET request to the versioned status endpoint for that gateway:

{baseURI}/evergateways/{gatewayIdOrSerialNumber}/status/v1
{baseURI}/evergateways/{gatewayIdOrSerialNumber}/status/v3

Response
On success, the body of the response contains a JSON object with the following status properties.

Status message properties	Description
`gatewaySerialNumber`	The unique serial number of the reporting gateway.
`timestamp`	The Unix date-time for when the report was sent.
`schema`	The status message schema used in the payload. -- `gateway_status_schema.json` indicates v1. -- `gateway_status_v3.schema.json` indicates v3.
`payload`	A JSON object containing the status data. See Message schemas below for details.

Daily status

Gateways that have been migrated to the v3 message schema send a daily status report. This report is very large, and Typically, the rate is one report per day.
(1 day=24 hours=86400 seconds)

To retrieve this report, send a GET request to:

{baseURI}/evergateways/{gatewayIdOrSerialNumber}/status/v3/daily

Query parameters
`start-time` `end-time`	The date range of status reports to retrieve, as UNIX date-time values. Range is inclusive.
`downsample-rate`	Optional. The number of seconds for the interval between status readings. A lower interval returns more status data, and a higher interval returns less status data.

Response

This call is not intended for downloading large volumes of gateway status messages. You can control the amount of data to collect by setting the date range and downsample rate.

If the requested time period and downsample-rate will produce a payload that exceeds the maximum of 5000 data points, the body of the response contains an error message.
If the request does not specify a downsample-rate, the call calculates a downsample rate that results in a number of data points close to the maximum. The expected number of daily status messages assumes 1 daily status message every 24 hours. (1 day=24 hours=86400 seconds)

On success, the body of the response is a JSON object that contains a summary of the parameters (start and end times, the returned item count, and the downsample rate used), in addition to the status data. The status data is very large, including a process list that describes thousands of processes.

Status message schemas

The following examples illustrate the basic status-report schemas using sample values.

V1 basic status-report message schema

{
  "gatewaySerialNumber": "44XCF92",
  "timestamp": 1647887507,
  "schema": "gateway_status.schema.json",
  "payload": {
    "schema": "gateway_status.schema.json",
    "system": {
      "uptime": 3021044,
      "cpuUsage": [
        {
          "id": "cpu0",
          "idle": 287349240,
          "user": 2809720,
          "ioWait": 285309,
          "system": 5387405
        },
        {
          "id": "cpu1",
          "idle": 293741303,
          "user": 2411020,
          "ioWait": 288900,
          "system": 2558487
        }
      ],
      "diskUsage": [
        {
          "free": 24140016,
          "size": 27782168,
          "used": 3642152,
          "mount": "/",
          "available": 22705700
        }
      ],
      "memoryUsage": 793366528
    },
    "timestamp": "2022-03-21T14:31:47-04:00",
    "connectivity": {
      "devices": [
        {
          "type": "Wifi",
          "status": "Disconnected"
        },
        {
          "type": "Ethernet",
          "status": "Activated",
          "address": ["192.168.86.176", "fe80::2664:33cc:f89f:efdf"]
        },
        {
          "type": "Modem",
          "status": "Activated",
          "address": ["10.69.69.38", "fe80::564:b91:2cc3:bb22"],
          "quality": {
            "signalStrength": 41
          }
        }
      ],
      "provider": "Network Manager"
    },
    "serialNumber": "44XCF92",
    "cpuUsagePercentage": 44
  }
}

V3 basic status-report message schema

{
  "gatewaySerialNumber": "F82KP42",
  "timestamp": 1647887244,
  "schema": "gateway_status_v3.schema.json",
  "payload": {
    "System": {
      "uptime": 33361,
      "loadAvg": {
        "l1": 0.08,
        "l5": 0.09,
        "l15": 0.08
      },
      "diskUsage": [
        {
          "used": 5501676,
          "mount": "/var/lib/snapd/hostfs/etc/cloud",
          "total": 26118220,
          "device": "/dev/mmcblk0p4"
        },
        {
          "used": 3699,
          "mount": "/var/lib/snapd/hostfs/boot/efi",
          "total": 64511,
          "device": "/dev/mmcblk0p2"
        }
      ],
      "memoryUsage": {
        "used": 620300,
        "total": 1916504
      },
      "processList": [
        {
          "pid": 24800,
          "name": "run-evernet",
          "cpuPercentage": 1.5,
          "memPercentage": 0.17,
          "wallClockSeconds": 8
        },
        {
          "pid": 4390,
          "name": "EveractiveReceiver",
          "cpuSeconds": 419,
          "cpuPercentage": 1.26,
          "memPercentage": 0.93,
          "wallClockSeconds": 33306
        },
        {
          "pid": 3865,
          "name": "mysqld",
          "cpuSeconds": 85,
          "cpuPercentage": 0.26,
          "memPercentage": 8.15,
          "wallClockSeconds": 33318
        },
        {
          "pid": 520,
          "name": "systemd-journald",
          "cpuSeconds": 38,
          "cpuPercentage": 0.13,
          "memPercentage": 4.25,
          "wallClockSeconds": 33349
        }
      ]
    },
    "schema": "gateway_status_v3.schema.json",
    "serial": "F82KP42",
    "Services": {
      "online": true,
      "ntpDrift": {
        "rmsoffset": 0.00443447707220912,
        "lastoffset": -0.0007297749980352819
      },
      "mqttQueueSize": {
        "heapSize": 60242088,
        "queueSize": 80235
      },
      "firmwareVersions": {
        "ramcharger": "May 14 2018 15:03:58 4144"
      },
      "softwareVersions": {
        "core": "16-2.54.2",
        "caracalla": "16.04-1.43",
        "everactive-ufw": "611cb42",
        "everactive-nats": "2.2.2-6e7a1f1",
        "caracalla-kernel": "4.4.0-221.254",
        "everactive-dingo": "0.1-38-g0eb6be5",
        "everactive-chrony": "afb51a3",
        "everactive-dnsmasq": "2.80snap1",
        "everactive-evernet": "v2.0.0-21-g35bc0ad",
        "everactive-psiclone": "1.3-151-g5cd37eb",
        "everactive-iot-agent": "0.4",
        "everactive-ramcharger": "prestable-24-gcb7aecd",
        "everactive-modemreboot": "prestable-75-geb0454f",
        "everactive-gateway-base": "v2.0.0-rc1-87-g7d838a7",
        "everactive-cloud-connector": "07654ad",
        "everactive-gateway-services": "v2.0.0-dev-rc2-130-gee32f3d",
        "everactive-firmware-utilities": "b6cca3e",
        "everactive-gateway-controller": "e480ed2",
        "everactive-gateway-essentials": "c5e8640",
        "everactive-firmware-ramcharger": "4144-prestable-20-g8ac01e4"
      }
    },
    "timestamp": "2022-03-21T18:27:24Z",
    "Connectivity": {
      "devices": [
        {
          "name": "wlan0",
          "type": "Wifi",
          "status": "Unavailable"
        },
        {
          "name": "eth0",
          "type": "Ethernet",
          "status": "Activated",
          "address": ["192.168.86.135", "fe80::5d74:336d:ae6c:7baf"]
        },
        {
          "name": "cdc-wdm0",
          "type": "Modem",
          "status": "Disconnected"
        }
      ]
    },
    "Environmental": {
      "sensors": {
        "caseHumidity": 22.264499233134075,
        "caseTemperature": 312.4801265760158
      },
      "ledState": {}
    }
  }
}

V3 daily status-report message schema

The process list in the daily status data is very large, including three to six data points for each of thousands of processes. Only the first few processes are included here.

{
  "gatewaySerialNumber": "AP24210117",
  "timestamp": 1647985091,
  "schema": "gateway_status_daily_v3.schema.json",
  "payload": {
    "schema": "gateway_status_daily_v3.schema.json",
    "serial": "AP24210117",
    "timestamp": "2022-03-22T21:38:11Z",
    "wakeupRadio": {
      "partNumber": "830-00023",
      "productSerial": "974514210031",
      "firmwareVersion": "Feb 11 2021 14:50:20 boomerang/v1.3.0-0-g6c2b2e9",
      "firmwarePartNumber": "90-1006",
      "productDescription": ""
    },
    "networkRouting": {
      "dnsResolvers": ["172.20.0.1"],
      "defaultGateways": ["172.20.0.1"]
    },
    "processListDaily": [
      {
        "pid": 1,
        "name": "systemd",
        "cpuSeconds": 11419,
        "cpuPercentage": 1.81,
        "memPercentage": 0.38,
        "wallClockSeconds": 632516
      },
      {
        "pid": 2,
        "name": "kthreadd",
        "cpuSeconds": 1,
        "wallClockSeconds": 632516
      },
      {
        "pid": 3,
        "name": "rcu_gp",
        "wallClockSeconds": 632516
      },
...