Devices

Devices are the “instances” of Device Types in the OOP sense. A device type will be represented by many devices. Devices in the EdgeIQ platform are data representations of anything in the world that we either want to gather data from or send commands to. Here are a few examples:

  • GPS tracking device
  • Water quality sensor
  • Thermometer
  • Database
  • Edge gateway
  • Security camera
  • Bluetooth mesh light bulb

Since most devices in the real world do not have a configurable identifier, the “name” field of a device must be a unique identifier gathered from the device itself. In some cases, it may be assigned - if you have a database trigger as a device, for instance. Nonetheless, the “name” field of a device must be unique among all devices within the scope of a company. The identifier must be a piece of data that is received with inbound messages in order to validate and associate its data.

Gateway Devices

Gateway devices are special devices on which EdgeIQ's Edge software runs. Gateways have their own endpoints to allow provisioning and commanding. Gateways may have many "endpoints", or "attached devices" - devices that connect to and report through the gateway.

Here are a few examples of actions specific to gateway devices:

  • Provision a new gateway
  • Configure a gateway's interfaces on unboxing. To learn more about this capability, see Device Configs.
  • Configure a gateway's heartbeat message
  • Change a gateway's log level
  • Add attached devices that are directly connected to the gateway
  • Create rules monitoring reports from the gateway and/or attached devices

Status messages

Gateway devices will relay their status on start/restart and upon any change which affects status. The status message consists of the following:

KeyTypeDescription
config_statusobjectContains configuration status tags "received", "valid", and "configured"
connections_statusobjectContains connection status information (see sample below)
edge_versionstringEdgeIQ Edge software version
firmware_versionstringManufacturer/model specific gateway firmware version
serialstringManufacturer/model specific gateway serial number

Heartbeat messages

Gateways will also relay a heartbeat message periodically. The period can be configured by setting the heartbeat_period (in seconds) key on the device. The values to be relayed in the heartbeat message can be configured by adding one or more of the following strings to the heartbeat_values array on the device:

ValueDescription
cell_signalCellular connection signal strength (0-5)
cell_usageCellular data usage from device interface (RX + TX bytes). The difference between the current and last cell usage values is calculated and accumulated via day, week, month, year, total fields on the Gateway Device model
sim_cardCellular SIM card status
connectionsInternet connectivity status of each WAN interface
wifi_clientsA list of the connected WiFi devices
disk_freeThe size of free disk space (KB)
disk_sizeThe total size of the disk (KB)
disk_usagePercentage of used space (%)

Sample

Status message JSON:

    {
      "config_status": {
        "received": true,
        "valid": true,
        "configured": true 
      },
      "edge_version": "1.0.0-beta_c836f6f",
      "firmware_version": "2.0.23.2",
      "serial": "171211150900163",
      "connections_status": {
        "eth0": {
            "ip": "192.168.1.65",
            "mask": "255.255.255.0",
            "gateway": "192.168.1.1",
            "dns_1": "8.8.8.8",
            "dns_2": "8.8.4.4"
        },
        "wwan0": {
            "imei": "355659070022229",
            "meid": "35565906002227",
            "iccid": "8901260761748077201",
            "version": "SWI9X15C_05.05.16.02",
            "priid": "ATT_005.010_002",
            "band": "LTE Band 4 - 1700Mhz",
            "carrier": "ATT",
            "current_apn": "grid.t-mobile.com"
        }
      }
    }

Heartbeat message JSON:

    {
      "connections": {
        "eth0": "fail",
        "wwan0": "success"
      },
      "cell_signal": "4",
      "cell_usage": "585932",
      "sim_card": "Not inserted",
      "wifi_clients": ["192.168.10.65","192.168.10.66"],
      "disk_free": "3633152",
      "disk_size": "4194304",
      "disk_usage": "13.38"
    }

API

Devices have many supporting API endpoints. As with all endpoints, refer to the API Overrview for information about useful features such as sorting and query parameters.