The Switch Interface seems complex and confusing. Help me.

The Switch interface is designed to provide control of a variety of sources of power including ordinary power outlets as well as variable output power sources. There are a few confusing aspects of this interface, and this article will try to shed some light on them. The interface provides support for one or more “switches”.

In the specification, an on/off outlet type, an on/off sensor type, a variable output rheostat type, and a variable value sensor type, are all referred to as a switch.

An on-off outlet is controlled by SetSwitch() and read back by GetSwitch().
Rheostat switches are controlled by SetSwitchValue() and read back by GetSwitchValue().
If the CanWrite property of a switch is False then it is not a controllable switch, it is a sensor, and can only be read back via GetSwitch() and GetSwitchValue().

Note

Despite its name, MaxSwitch is not the maximum value of the Id for a switch, it is the total number of switches supported by the device. The maximum legal value for Id for a switch device is MaxSwitch - 1. Think of MaxSwitch as the size of an array with indices ranging from 0 to MaxSwitch - 1.

For Application Developers

[Q] How do I turn an outlet on and off?

Given the switch number (or Id), call SetSwitch() with the Id and True or False for on or off respectively. You can read back the state of an outlet by calling GetSwitch() with the Id. The allowable range of Id values is from 0 through MaxSwitch - 1.

[Q] How do I control the output level of a rheostat?

Given the switch number (or Id), call SetSwitchValue() with the Id and the output level you want. You can read back the output level by calling GetSwitchValue() with the Id. The allowable range of output levels is given by MinSwitchValue() and MaxSwitchValue(). The allowable range of Id values is from 0 through MaxSwitch - 1.

[Q] How can I tell if a switch is an outlet type (on/off) or a rheostat?

When the difference between MinValue and MaxValue equals the value of SwitchStep you can assume that the switch is a binary on/off switch.

[Q] How do I tell if a switch is controllable or just a sensor?

Read the switch’s CanWrite() value using the switch’s Id.

[Q] I can’t set the variable value I want. It keeps coming back different

Besides MinSwitchValue() and MaxSwitchValue(), the switch’s output values may be restricted to successive steps given by SwitchStep() increments. Unfortunately, setting the switch to an unsupported value (not one of the steps) does not result in an exception, instead it will be set by rounding up to next higher legal value. See the related question for developers below.

For Device Developers

The behavior of your switch device can be inferred from the above section.

Note

A confusing aspect of this interface is that the Value methods must be implemented even for on/off switches, and the on/off methods must be implemented even for output value switches.

[Q] What must I do with the Value methods for my simple on/off switches?

Make the Value methods use a value of 0.0 to 1.0. For MinSwitchValue() return 0, and for MaxSwitchValue() return 1.0. Then make SetSwitchValue() take 1.0 or 0.0 for on and off respectively. GetSwitchValue() must return 1.0 for on and 0.0 for off. Implied by this is that SwitchStep() should return 1.0, just one step from 0.0 to 1.0.

[Q] What happens to a variable value switch when SetSwitchValue sets a value between steps as defined by SwitchStep?

The output value should be rounded to the nearest step. For example say MinSwitchValue() = 5.0, MaxSwitchValue() = 8.0, and SwitchStep() = 1.0, then

Values in the range of 5.0 to 5.499999 => 5.0

Values in the range of 5.5 to 6.499999 => 6.0

Values in the range of 6.0 to 7.499999 => 7.0

Values in the range of 7.5 to 8.0 => 8.0

[Q] What must I do with SetSwitch() for my variable value switches?

A call to SetSwitch() True must set the value to MaxSwitchValue(). A call to SetSwitch() False must set the value to MinSwitchValue().

[Q] What must I do with GetSwitch() for my variable value switches?

A call to GetSwitch() must return False if the value is at MinSwitchValue(), otherwise True.

[Q] Conform is reporting an error for my SwitchStep() value. What could be the problem?

The specs require that (int(MaxSwitchValue) - int(MinSwitchValue)) must be an exact multiple of int(SwitchStep).

[Q] My variable output device has continuous values. What must I return for SwitchStep()?

Since SwitchStep() cannot be 0, return a “small” step that relates to the resolution of the A/D converter or to practical usefulness. As just mentioned, be sure to choose a SwitchStep() value that gives rise to an even number of steps within the range.

[Q] How can I “turn off” a variable value switch with a non-zero MinSwitchValue()?

Use a separate switch for on/off. An example might be a dew heater with 5 - 10 volts output. Make one on/off switch with SwitchName() of “DewOnOff”, with SwitchDescription() of “Dew Heater Power On/Off”. Then label the variable output switch “DewPower” with SwitchDescription() of “Dew Heater Output Power Level (low to high)”.

[Q] How can I create a “momentary switch” effect?

A momentary switch activates for a short period when triggered before self-resetting, but there is no direct analogue of this behaviour in the ASCOM switch device. Momentary action can be implemented using an ASCOM switch by activating the momentary action on only one of the SetSwitch() operations, either True or False leaving the other to have no effect.