Class 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 promise-based API that will be resolved when the control value changes.

If the ControlToggler#start method is 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.

Example

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

const toggler = new ControlTogger(new SolarUserApi(), auth, 123, '/power/switch/1');
toggler.callback = (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);

Index

Constructors

constructor

new ControlToggler(api, auth, nodeId, controlId, queryApi?): ControlToggler
Constructor.
Parameters
- api: default
  the URL helper to use
- auth: AuthorizationV2Builder
  the auth builder to authenticate requests with; the required credentials must be set appropriately
- nodeId: number
  the ID of the node with the control to manage
- controlId: string
  the ID of the control to manage
- Optional queryApi: default
  a URL helper for accessing node datum via SolarQuery; if not provided one will be created using the environment from api. Useful in a development environment when the SolarUser and SolarQuery hosts are different.
Returns ControlToggler
- Defined in src/main/controlToggler.ts:159

Properties

`Private` `Readonly` #api

#api: default

`Private` `Readonly` #auth

#auth: AuthorizationV2Builder

`Private` `Optional` #lastKnownDatum

#lastKnownDatum?: ControlDatum

The last known instruction status. The val property indicates the control value.

`Private` `Optional` #lastKnownInstruction

#lastKnownInstruction?: default

The last known instruction object.

`Private` `Readonly` #queryApi

#queryApi: default

`Private` `Readonly` #queryAuth

#queryAuth: AuthorizationV2Builder

`Private` `Optional` #timer

#timer?: any

A timeout identifier.

`Optional` callback

callback?: ControlCallbackFn

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.

`Readonly` controlId

controlId: string

The control ID to manage.

`Readonly` nodeId

nodeId: number

The node ID to manage the control on.

pendingRefreshMs

pendingRefreshMs: number = 5000

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

refreshMs

refreshMs: number = 20000

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

Accessors

hasPendingStateChange

get hasPendingStateChange(): boolean
Test if a state change is pending confirmation.

Returns boolean
true if a state change is pending (not complete)
- Defined in src/main/controlToggler.ts:263

Methods

`Private` #currentRefreshMs

#currentRefreshMs(): number
Private
Calculate the refresh rate to use.

Returns number
the refresh rate to use, in milliseconds
- Defined in src/main/controlToggler.ts:252

`Private` #fetch

#fetch<T>(method, url, auth): Promise<T>
Private
Fetch a URL.
Type Parameters
- T
  the expected result type
Parameters
- method: HttpMethod
  the HTTP method to use
- url: string
  the URL to request
- auth: AuthorizationV2Builder
Returns Promise<T>
promise of the results
- Defined in src/main/controlToggler.ts:313

`Private` #getActiveInstruction

#getActiveInstruction(data): undefined | default
Private
Find an active SetControlParameter Instruction for the configured controlId.
Parameters
- data: undefined | InstructionInfo[]
  array of instructions
Returns undefined | default
the active instruction, or undefined
- Defined in src/main/controlToggler.ts:197

`Private` #lastKnownInstructionValue

#lastKnownInstructionValue(): undefined | ControlValueType
Private
Get the last known instruction value, e.g. the state of the control.

Returns undefined | ControlValueType
the last know value of the control (0 or 1), or undefined
- Defined in src/main/controlToggler.ts:241

`Private` #mostRecentValue

#mostRecentValue(controlDatum?, instruction?): undefined | ControlValueType
Private
Return the value from either the controlStatus or the first parameter value of an instruction, whichever is valid and more recent.
Parameters
- Optional controlDatum: ControlDatum
  a control status object
- Optional instruction: default
  an instruction object
Returns undefined | ControlValueType
the control status value, or undefined if not known
- Defined in src/main/controlToggler.ts:277

`Private` #notifyDelegate

#notifyDelegate(error?): void
Parameters
- Optional error: Error
Returns void
- Defined in src/main/controlToggler.ts:179

start

start(when?): this
Start automatically updating the status of the configured control.
Parameters
- Optional when: number
  an optional offset in milliseconds to start at (defaults to 20)
Returns this
this object
- Defined in src/main/controlToggler.ts:622

stop

stop(): this
Stop automatically updating the status of the configured control.

Returns this
this object
- Defined in src/main/controlToggler.ts:637

update

update(): Promise<undefined | void | ControlValueType>
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 Promise<undefined | void | ControlValueType>
promise that resolves after getting the updated state
- Defined in src/main/controlToggler.ts:500

value

value(): undefined | ControlValueType
Get the desired control value.

Returns undefined | ControlValueType
the last known control value
- Defined in src/main/controlToggler.ts:380
value(desiredValue): Promise<InstructionInfo>
Set the desired control value.
Parameters
- desiredValue: ControlValueType
  the control value to set
Returns Promise<InstructionInfo>
a promise that resolves to the enqueued instruction
- Defined in src/main/controlToggler.ts:388

Class ControlToggler

Example

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns ControlToggler

Properties

Private Readonly #api

Private Readonly #auth

Private Optional #lastKnownDatum

Private Optional #lastKnownInstruction

Private Readonly #queryApi

Private Readonly #queryAuth

Private Optional #timer

Optional callback

Readonly controlId

Readonly nodeId

pendingRefreshMs

refreshMs

Accessors

hasPendingStateChange

Returns boolean

Methods

Private #currentRefreshMs

Returns number

Private #fetch

Type Parameters

Parameters

Returns Promise<T>

Private #getActiveInstruction

Parameters

Returns undefined | default

Private #lastKnownInstructionValue

Returns undefined | ControlValueType

Private #mostRecentValue

Parameters

Returns undefined | ControlValueType

Private #notifyDelegate

Parameters

Returns void

start

Parameters

Returns this

stop

Returns this

update

Returns Promise<undefined | void | ControlValueType>

value

Returns undefined | ControlValueType

Parameters

Returns Promise<InstructionInfo>

Settings

Member Visibility

Theme

On This Page

`Private` `Readonly` #api

`Private` `Readonly` #auth

`Private` `Optional` #lastKnownDatum

`Private` `Optional` #lastKnownInstruction

`Private` `Readonly` #queryApi

`Private` `Readonly` #queryAuth

`Private` `Optional` #timer

`Optional` callback

`Readonly` controlId

`Readonly` nodeId

`Private` #currentRefreshMs

`Private` #fetch

`Private` #getActiveInstruction

`Private` #lastKnownInstructionValue

`Private` #mostRecentValue

`Private` #notifyDelegate