Skip to end of metadata
Go to start of metadata

You are viewing an old version of this content. View the current version.

Compare with Current View Version History

« Previous Version 5 Next »

Device Simulator support added January 2022 (limited release with official announce to be later).

The Device Simulator functionality allows you to add devices from our catalog to an account and use them as if they were real hardware. Everything about the process is the same as real hardware - readings can be triggered, configured alerts will fire, device history is the same, etc.

Set Simulator flag enabled

Before a device will appear in the list of simulated devices, it must be enabled in the Device Template.

To allow a device to appears in the list of simulated devices, add the allow_simulator = true Attribute in the template.

Sample Payloads

By default, simulated devices will pull randomly from available data points based on the device type. So if a device type is popular, you may not need to add simulated payloads - it will magically work.

When not enough data exists, data points can be added as sample payloads by defining the sample_payloads Attribute in the template.

There are two sample_payloads allowed:

(Preferred) Hex payloads

Grabbing real payloads from devices is the best way to provide sample data. The only downside here is that you need to be able to find good examples from real devices - it’s not as easy to make them up or slightly tweak them than it is with say the JSON alternative (see below).

[
    {
        "format": "hex",
        "payload": "0300b00300b9"
    },
    {
        "format": "hex",
        "payload": "0500b00300b9"
    },
    {
        "format": "hex",
        "payload": "0201E01B01A5"
    }
]

Decoded JSON

If you cannot use raw hex payloads, you can send decoded data that matches the appropriate data as well.

This works (and in many cases is the only way to easily provide sample payloads) but Hex payloads are preferable because this step skips the codec decoding step - the extra step of using the codec and letting it decode the data more closely resembles the process a real data point coming in would follow.

[
  {
    "format": "json",
    "ignore_codec": true,
    "payload": [
      {
        "channel": 5,
        "type": "batt",
        "unit": "p",
        "name": "Battery",
        "value": 88
      },
      {
        "channel": 506,
        "type": "co2",
        "unit": "ppm",
        "name": "CO2",
        "value": 250
      }
    ]
  },
  {
    "format": "json",
    "ignore_codec": true,
    "payload": [
      {
        "channel": 5,
        "type": "batt",
        "unit": "p",
        "name": "Battery",
        "value": 28.57
      },
      {
        "channel": 506,
        "type": "co2",
        "unit": "ppm",
        "name": "CO2",
        "value": 500
      }
    ]
  }
]

FAQs

Must I enable Simulator and add Payloads?

Technically, no. Enabling the simulator flag is the only requirement. But in adding devices to the simulator, QA found that very few devices had enough live data to get away with adding the flag only.

After enabling a device in the simulated device list, be sure to add it into an account. If you find that it says ‘Waiting on data’ after being added, that’s an indication that you need to add sample payloads before calling it ready for customers.

Another good indicator that samples are needed is if you click the Update button a few times and nothing changes (or it’s so subtle it won’t be noticed easily).

How to locate sample payloads from the codec

You can either dig through Kibana logs or possibly you can grab samples (if they exist) from the codec directly.

If you need to grab samples from the codec (especially helpful if you need to find and then decode a sample because you want to tweak things slightly and output JSON):

  1. Search for the template in Device Templates on Console.

  2. Make note of the Codec ID

  3. Open the Codec Editor (Super Admin)

  4. Click on Library button

  5. Search for the library and the click the Edit icon

  6. IF there are sample payloads, they will be at the top of the codec.

Clicking on Update Data button in UI doesn’t update reading

  1. Device may not have sample payloads - There may no longer be enough live data to pull from. In this case look to see if sample_payloads is defined in the Template. If not, add it with good data that can always be pulled from [Shramik currently handling this].

  2. Sample readings are random, can be duplicated - The data pulled for the sample (whether live or sample) is random. This means it is entirely possible the same data can be pulled multiple times even though you’ve clicked the button. There is an enhancement request for this [See eptak’s list of tasks] where we want the sample payloads to be sent in order, one after another when provided.

Special Case: BLE / Beacons required (requires_template_id)

We added this to solve the ‘Beacon also needs to be present’ scenario, but one could imagine we’ll have more situations where a device won’t work unless ‘this or that is also present’ that will need to be solved as well.

There are some special cases where an additional BLE device or beacon is also required or the device won’t function properly. E.g. it’s not much use to allow a customer to add a BLE Tag if there isn’t an appropriate BLE gateway device also added that would tell us which location is being pinged.

In this case we allow an additional requires_template_id Attribute which will then pull in say a beacon device as well. I.e. when you add a GlobalSat Multi-Press button, during the Add process it will also add a simulated beacon device (the Add process walks the user through adding both when the simulated device is added). The sample payload for the simulated button refers to the simulated beacon for position info.

Here is an example from the GlobalSat Panic Button (Multi-Press) template.

  • No labels