Configuring Duty Cycle Modulation
Duty cycle modulation enables developers to control the time that an EMS is connected to the ThingWorx Platform. It defines the frequency and duration of the connection between an EMS and a ThingWorx Platform. If you need to conserve power or bandwidth at the expense of availability/responsiveness, you can use duty cycle modulation. This feature may be useful if you have critical processes during which you want to disable communications for a device. By configuring duty cycle modulation in the duty_cycle group in the config.json file of your EMS, you can put the EMS into an offline mode.
As of v.5.4.3, duty cycle modulation keeps the WebSocket connection alive as long as there is activity within a configurable amount of time on the EMS ( delay_duty_cycle property). The WebSocket connection enters a duty cycle OFF state only if there have not been any messages from the ThingWorx Platform in the configured number of seconds. For example, if a file transfer is in progress, you may need to keep the connection open for an additional two minutes. The duty cycle has a separate configuration group in config.json, as follows:
"duty_cycle" : {
"connect_period" " 60000,
"duty_cycle" " 100,
"delay_duty_cycle" : 60000
}
where
• connect_period — Defines the period of time set for duty cycle intervals. A value of 0 means that the EMS is always connected. The default rate is 60000 (one minute).
• duty_cycle — Determines what percentage of time during the connection period that the EMS is connected to the ThingWorx Platform. The default value is 100 percent, which means that the EMS is always connected. This value is also the maximum value for this property. A value of 0 also means that the EMS is always connected during the connection period.
• delay_duty_cycle — Defines the time interval (in milliseconds) for which the duty cycle should not be entered after receiving a message from the platform. The default value is 60000 milliseconds (one minute).
 |
If the config.json file does not have the "duty_cycle" group, the EMS assumes that its connection is always on (that is, duty_cycle is set to 0 or 100 percent).
|
The following diagram illustrates the effects of the duty cycle parameters on the connection between an EMS and a ThingWorx Platform:
In addition to the configuration file changes for duty cycle in v.5.4.3, the EMS has changed to enable it to track file transfers and tunnels, as well as property and service requests from the ThingWorx Platform. Duty cycle will not disconnect the EMS from the platform if any of the following conditions are true:
• A message has been received from the platform during the last delay_duty_cycle time interval.
• A message has been sent to the platform but no response has been received yet.
• A file transfer is pending or in progress.
• A remote session (tunnel) is in progress (open).
Finally the EMS will not be disconnected from the ThingWorx Platform immediately after starting up. Instead, the EMS will disconnect at the next Duty Cycle event after startup. The next Duty Cycle event is the next time when the EMS should connect to or disconnect from the platform.
If the EMS is connected to the ThingWorx Platform, the next Duty Cycle event is calculated as follows:
nextDutyCycleEvent = Current time + ((connect_period * duty_cycle)/100)
For example, if the connect_period is one minute (60,000 ms) and the duty_cycle is 30 percent, the EMS will disconnect after 18,000 milliseconds. That is, the EMS will remain connected for 30 percent of the connect_period:
(30/100) * 60000 = 18000
If the EMS is disconnected from the platform, the next Duty Cycle event is calculated as follows:
nextDutyCycleEvent = Current time + ((connect_period * (100 duty_cycle))/100)
For example, if the connect_period is one minute (60,000 ms) and the duty_cycle is 30 percent, the EMS will connect after 42,000 milliseconds. That is, the EMS will remain disconnected for 70 percent of the connect_period:
((100 = 30)/100) * 60000 = 42000
Duty cycle is considered to be enabled if the following conditions are true:
• The connect_period is greater than zero. That is, the total number of milliseconds that the WebSocket will stay connected is greater than zero. The value of 0 indicates “AlwaysOn”.
• The duty_cycle is less than 100 and greater than 0. That is the percentage of the connect_period that the EMS remains connected to a ThingWorx Platform is less than 100 and greater than 0. A value of 100 or 0 indicates “AlwaysOn”.
If an LSR pushes data (e.g., property value changes) to an EMS while the EMS is in the OFF state of a duty cycle, the data is stored in the offline message store and sent to the ThingWorx Platform once the EMS is connected again (duty cycle ON state).