Configuring a Device: Policies & Parameters
Terso Devices are remotely configurable and each device, with the exception of the handheld, contains dozens of customizable settings, which we call parameters. Performing this configuration with the API takes several sequential steps, but following this guide will ensure that your device configuration goes as smoothly as possible.
Let's review the high-level steps to configure a device's parameters before we dive into the details:
- Create a policy for each type of Terso device you have. You can also add multiple policies for each device type if you want different parameter configurations.
- Add the appropriate policy to each device, overriding individual parameters as desired.
- Sync the configuration parameters to the physical Jetstream device.
- Verify that the policy applied is working as desired.
- Modify as needed.
A policy is a complete set of configuration parameters that can be applied to a Terso Device to override it's factory default parameters. Therefore you only need to create and apply policies if you wish to change the default settings.
- If the device is already registered and communicating, you can find the current FW version by reviewing a StatusEvent sent from the device and referencing the "AgentVersion" property. If you need help determining the firmware version, contact us.
- For that device type, review the Config Parameters section to learn more about what parameters can be configured for that device, as well as what the defaults are, and in what FW version they were introduced.
- Using the Create a Policy endpoint, enter every config parameter for the selected device type and FW version in the body of the request. Whenever you are not sure if you want to change a value, simply enter the default value in your policy. You can always later override individual parameters when adding the policy to a device.
Now that the policy exists in Jetstream, you must link it to each relevant device for which you wish to override the factory defaults:
- You may specify individual parameters to override, or assign the policy as-is.
At this point, Jetstream knows that a policy has been assigned to the device, but the physical device has not yet received the command to use the new parameters.
- For each device that has a policy added to it in Jetstream, use the Set a Device's Configuration Parameters endpoint to apply the policy as it is configured in Jetstream.
Only sync the parameters to a device when the device is online and able to receive the command. If the device does not receive the command within 24 hours, the command will time out and the parameters will not be synced. You can verify that a device is online using the Get Device Status command, an online device should respond with "websockets: enabled".
We have created a standalone policy record in Jetstream, added the Policy to the device in Jetstreamwith possible overrides, and synced the parameters to the device. You can review each of these steps using different endpoints.
- Review the Policy added to a specific device and any overrides in Jetstream
- Review the current parameters the physical device is actually operating with using the Get a Device's Configuration Parameters endpoint. The device will return it's current parameters via a GetConfigValues CommandCompletionEvent in the event queue, which can be retrieved via the Get Events endpoint.
You have successfully created a policy, added it to the device in Jetstream, and set the device's configuration parameters. If you wish to modify the parameters of a device at this point, you have multiple options, depending on your goal:
This option is best when you want to change the exact same parameters for multiple devices.
- Create an entirely new policy with the desired parameter changes following the steps above.
- Add the policy to the device, using the steps above.
- Sync the config parameters to the device, using the steps above.
This option is best if you are only looking to change the parameters for a single device.
- Re-add the policy to the device using the steps above, but override the parameters you would like to change.
- Sync the config parameters to the device, using the steps above.
Removing a Policy from a device in Jetstream does not do anything to change the parameters on the device itself. If you wish to "reset parameters to defaults", you will need to create and sync a policy that have these values set to defaults, or override a policy with the default values. Devices are intentionally designed to remember their last policy settings, so even removing the device from Jetstream entirely will not do anything to clear or reset the parameter settings on the device.