SolarNetwork Control Toggler

Class: ControlToggler

ControlToggler

Manage the state of a boolean control switch using SolarNetwork SetControlParameter instructions.

Use an instance of this class to keep track of, and update the state of, a single switch-like control configured on a SolarNode. Because updating the state of a control is an asynchronous process involving multiple steps, this class simplifies this with a simple callback API that will be invoked whenever the control value changes.

Once the ControlToggler#start method has been called, the toggler will make periodic calls to SolarNetwork to get the most recent value for the configured control ID, which it treats as a ControlDatum sourceId value. Thus if some other process changes the control, the toggler will eventually pick up that change and invoke the callback function.

new ControlToggler(urlHelper, authBuilder, controlId [, queryUrlHelper])

Constructor.

Parameters:
Name Type Argument Description
urlHelper NodeInstructionUrlHelper

the URL helper to use, which must support node instructions with the NodeInstructionUrlHelperMixin and be configured with the nodeId property for the node to be managed
authBuilder AuthorizationV2Builder

the auth builder to authenticate requests with; the required credentials must be set appropriately
controlId string

the ID of the control to manage
queryUrlHelper NodeDatumUrlHelper <optional>

a URL helper for accessing node datum via SolarQuery; if not provided one will be created using the environment from urlHelper
Example
const urlHelper = new NodeInstructionUrlHelper();
urlHelper.nodeId = 123;

const auth = new TestAuthBuilder('token');
auth.saveSigningKey('secret');

const toggler = new ControlTogger(urlHelper, auth, '/power/switch/1');
toggler.callback = function(error) {
  // invoked when instruction states change, or the control value changes
  console.log(`Control ${toggler.controlId} value == ${toggler.value()}; pending == ${toggler.hasPendingStateChange}`);
};

// enable automatic keeping track of state and the callback hook
toggler.start();

// ... at some point later, maybe in response to a UI event, update the state;
// the callback will be invoked then the value changes
toggler.value(1);

Members

authBuilder :AuthorizationV2Builder

The auth builder to use for authorizing requets. The credentials must be configured to support posting instructions and viewing the data for the configured controlId.

Type:
  • AuthorizationV2Builder

callback :function

A callback function, which is called after the state of the control changes. The this reference will be set to this object. If an error has occurred, the error will be passed as the first argument.

Type:
  • function

controlId :string

The control ID to manage.

Type:
  • string

hasPendingStateChange

Test if a state change is pending confirmation.

instructionUrlHelper :NodeInstructionUrlHelper

The URL helper to use, which must support node instructions with the NodeInstructionUrlHelperMixin and be configured with the nodeId property for the node to be managed.

Type:
  • NodeInstructionUrlHelper

pendingRefreshMs :number

The refresh rate, in milliseconds, when a toggle instruction is queued. Defaults to 5 seconds.

Type:
  • number

queryUrlHelper :NodeDatumUrlHelper

The SolarQuery URL helper.

Type:
  • NodeDatumUrlHelper

refreshMs :number

The refresh rate, in milliseconds. Defaults to 20 seconds.

Type:
  • number

Methods

start( [when])

Start automatically updating the status of the configured control.

Parameters:
Name Type Argument Default Description
when number <optional>
 20

an optional offset in milliseconds to start at
Returns:

this object

Type
ControlToggler

stop()

Stop automatically updating the status of the configured control.

Returns:

this object

Type
ControlToggler

update()

Refresh the control state from SolarNetwork.

Once the ControlToggler#start method is called, this method is invoked periodically automatically. Only call this directly if you need to manually update the state of the control.

Returns:

this object

Type
ControlToggler

value( [desiredValue])

Get or set the desired control value.

Parameters:
Name Type Argument Description
desiredValue number <optional>

the control value to set
Returns:

when called as a getter, the last known control value; when called as a setter, this object

Type
number | ControlToggler

Type Definitions

statusCallback( [error])

The status callback function.

This function will be invoked whenever the control value has changed. Additionally, it will be invoked periodically while a state change has not been completed, even if the control value has not changed. Use ControlToggler#value to get the current control value and ControlToggler#hasPendingStateChange to test if that value is still pending.

This:
Parameters:
Name Type Argument Description
error Error <optional>

an error if a failure occurred