Device Simulator support
- Brent Meriwether (Unlicensed)
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. Both templates & codec must support the feature before it can be enabled.
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
When to add Simulator support
Per Upper Management - by default all new templates should have this enabled.
Always add support in the following situations:
Hardware support is being added to the platform for the first time.
New version of hardware, with different sensors or different behavior. Use common sense here - if to a user of the dashboard there are no differences in data displayed, alerts or widgets present, etc then there’s no need for another entry in Simulated devices.
When to NOT have simulator support enabled:
Unless directed to do so specifically, we do not want Templates that were created specifically for our partners to be enabled in the Simulator.
Do not forget that if you make a Duplicate of an existing template that has the simulator flag enabled, the copy will get it too. This is a common mistake we make when copying templates in order to customize for our partners.
Must I add sample Payloads?
Technically, no (but effectively yes). Enabling the simulator flag is the only requirement - live data points will be pulled where possible for existing devices of the same type. But when adding devices to the simulator for release, QA found that very few devices had enough live data to get away with adding the flag only. We went back and added payloads for basically every old device as a result of this finding.
We really only recommend relying on live data points to be found if you are dealing with a template that will be a widely deployed piece of hardware with tons of data always coming in.
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):
Search for the template in Device Templates on Console.
Make note of the Codec ID
Open the Codec Editor (Super Admin)
Click on Library button
Search for the library and the click the Edit icon
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
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].
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.
You haven’t customized the sample payloads well enough - When grabbing the sample payloads, make sure that each one if very different from the others. E.g. don’t change the Temperature slightly, change it by a bigger amount. Always fill in valid GPS coordinates and make them change location intelligently, etc.
Special Case: BLE / Beacons required (requires_template_id)
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.