Scan Packet

The IoT Services use data called a Scan Packet, and this is just as it sounds. A Scan Packet is a packet of data that contains information about the end device; a Scan Packet is also only sent by Hubs. For example, if a Hub sees a temperature-humidity device the scan packet will contain:

Temperature
Humidity
Device ID (The MAC address)
Other info (iBeacon, LoRa data, etc...)

Scan Packets usually are in an array, meaning you can send more than one Scan Packet into the IoT Service at a time. You can send up to 100 every second.

You can customize Scan Packets in any way; there are a few required fields; however, the rest of the packet is up to you!

Type Definitions

ELSData: Object

CODE

{
  location: Boolean
  deviceType: String
}

ELSscans: Object

CODE

{
  adData: String
  rssi: Number
  node: String
  time?: String
  name?: String
  latitude?: Number
  longitude?: Number
}

Scan Packet Breakdown

JSON

{
    hubId: "MyHub1",
    data: {
        location: false,
        deviceType: "echolo"
    },
    scan: [
        {
            adData: "0000001010101",
            rssi: -28,
            node: "AB:CD:EF:12:34:56",
            time: "Tue Aug 29 04:44:36 2017",
            name: "MY Device Name"
        },
        {
            adData: "8765467893232244000000033234ac3b21cb34e33f3d33a2ab3ca30",
            rssi: -51,
            node: "BB:CD:EF:12:34:00",
            time: "Tue Aug 29 04:44:36 2017",
            name: "Echolo Beacon"
        }
    ]
}

hubId: String (required)

The first level of the JSON object requires that you ID what Hub this data is coming from. An example: If Hub1 is scanning for devices it may see hundreds of devices and report them in the scan packet but it must include it's hubId only once in the hubId key.

Key	Required	Description
`hubId`	Yes	The id of the hub that sees the devices can be the MAC address, a custom string, or a number.

data: ELSData (required)

The data key is an object that includes two items, and both are required. The first is a key named location and expects a boolean, this is used for offering up a location on the platform or not. See the Location Packet guide for more information on the location key.

Setting location: true - Note that this requires the proper access plan on the IoT Platform if data is set while the flag is set to true and the access plan is not set up for location services the data will be ignored. - Location Packet

The next key is a string named deviceType, this can be set to the manufacturer or group name of your hub. Example: if you are using Echolo Hubs for hub's deviceType would be set to 'echolo'.

scan: ELSscans[] (required)

The key scan is a required key that contains an Array of Objects containing three keys, all of which are required to build a valid scan packet. The scan Array is the 'meat' of the packet and holds the device details gathered while performing a scan.

Key	Required	Description
`adData`	Yes	This is the RAW advertising data.
`rssi`	Yes	This is the Received Signal Strength Indicator of the device.
`node`	Yes	The MAC address / device ID or other identifier of the scanned end device.
`time`	No	The time and date of the scan
`name`	No	The name of the scanned end device (can submit "Unknown" or the device ID if the name is not used).
`latitude`	No	The `latitude` of the device.
`longitude`	No	The `longitude` of the device.

Location Services

The Echolo IoT Platform provides location services for end devices when using the proper Scan Packet. When sending in scan data it is important to send as much data as your hub will allow you. The more data that the Echolo IoT Platform has to work with the more accurate your readings will be.

The Echolo Platform supports GPS location information that can be included in each packet per device. This latitude and longitude are saved with the device and then can be retrieved via the REST API.

The 'location' boolean should not be set to 'true' when just using GPS location.