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:

  1. 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.
  2. Add the appropriate policy to each device, overriding individual parameters as desired.
  3. Sync the configuration parameters to the physical Jetstream device.
  4. Verify that the policy applied is working as desired.
  5. Modify as needed.

Creating a Policy

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.

  1. Determine which device type and firmware version you are creating a policy for.
    1. 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.
  2. 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.
  3. 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.

Networking parameters (DNS, Gateway IP, Subnet) should be left as default and carefully overridden per device as needed. Overrides to those settings should only be applied while you have physical access to the unit, so that if you send incorrect networking settings, you can correct these settings locally on the unit, and quickly restore Jetstream connectivity. Errors or typos when setting networking parameters cannot be fixed remotely, as the invalid settings now set on the unit will prevent communication.

Adding a 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:

  1. Use the Add a Policy to a Device endpoint to create the link between the policy and the device.
    1. You may specify individual parameters to override, or assign the policy as-is.

Syncing the Parameters to a Device

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.

  1. 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".

Reviewing Policies, Policies added to Devices, and Synced Parameters

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.

Modifying a Device's Configuration Parameters

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:

Create a New Policy

This option is best when you want to change the exact same parameters for multiple devices.

  1. Create an entirely new policy with the desired parameter changes following the steps above.
  2. Remove the existing policy from devices using the Remove a Device's Policy endpoint.
  3. Add the policy to the device, using the steps above.
  4. Sync the config parameters to the device, using the steps above.

Remove and Add the Policy to the Device with new Overrides

This option is best if you are only looking to change the parameters for a single device.

  1. Remove the existing policy from devices using the Remove a Device's Policy endpoint.
  2. Re-add the policy to the device using the steps above, but override the parameters you would like to change.
  3. 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.