BrainClient

Static method to retrieve/create a BrainClient instance. The ipAddress is used as the cache key - if no client exists for that IP, then a new one will be created and initalized. However, if an existing client is found, that client will be returned as-is.

The client is initalized using the BrainClient#connectToBrain method.

Note that this static method is intentionally designed to NOT be async - in otherwords, it is guaranteed to return a BrainClient instance right away. The BrainClient#connectToBrain method is NOT called right away (on a new instance) - it is delayed until the next clock tick. This is done so that callers can attach event listeners, for example, to cach communication failures on connection.

Example

const bc1 = BrainClient.getBrainClient('127.0.0.1:8000');
const bc2 = BrainClient.getBrainClient('127.0.0.1:8000');
console.log("Caching worked? ", (bc1 === bc2) ? true : false);

Auto mode

If you pass an object like { auto: true } as the ipAddress, BrainClient will check the window query string for brainIp=<whatever>, and if not found, will use the origin host/port as brain IP.

If you pass an object like { auto: true, default: "some.host:8000" }, BrainClient will still check the query string, but it will fallback to "some.host:8000" instead of the origin.

If you pass an object like { param: "someParam", default: "some.host:8000" }, BrainClient will check for someParam=<whatever> instead of "brainIp", and fallback to the value given in "default" if not found.

NOTE: Auto mode will not work server-side (e.g. from Node, etc) - it is designed specifically for use client-side. If you try to use { auto: true } or { param: ... } on Node, your program will likely fail with an exception.

In all cases, default is optional. If "auto" or "param" given and "default" not specified, it will fallback to the window origin (e.g. the host/port that the page using BrainClient was served from.) This "origin" mode is only really useful if you are taking advantage of the "bundle upload" mode in the Kramer UI of the SL brains to serve your custom javascript from the Brain's built-in webserver at the /bundle/ URL.

Get an RxJS Observable object. This method is provided to simplify integration of BrainClient into Angluar applications.

This observable is created using a Subject object, allowing the same event from this client to be multicast to any observers attached.

This observable will contain every event emitted by this client. For example, using event listeners, you might do:

bc.on(BrainClient.EVENTS.CONNECTION_STATUS_CHANGED, ({status}) => console.log("Status:", status));
bc.on(BrainClient.PIN_REQUIRED, () => bc.submitPin(prompt("PIN?")));

Using the Observable returned from this method, you can instead do:

bc.asObservable().subscribe(({ event, ...data }) => {
	switch(event) {
		case BrainClient.EVENTS.CONNECTION_STATUS_CHANGED:
			console.log("Status:", data.status);
			break;
		case BrainClient.EVENTS.PIN_REQUIRED:
			bc.submitPin(prompt("PIN?"));
			break;
		default:
			break;
	}
})

The shape of the message emitted by the Observable from this method looks like:

const message = {
	event: "",
	...data
}

The event field above is always and only one of the values from BrainClient.EVENTS. The data spread operator above indicates that all other fields from the event (e.g. the args that would be passed to your event callback if you used the on method to attach callbacks) are spread into the message, so you receive a single flat-ish object.

That means that the message you would receive from the observable for the CONNECTION_STATUS_CHANGED event would look like:

const message = {
	event:  BrainClient.EVENTS.CONNECTION_STATUS_CHANGED,
	status: BrainClient.CONNECTION_ACTIVE // for example...
}

It is useful to note that you can listen for BrainClient.EVENTS.WS_MESSAGE to receive ALL events (WebSocket messages) from the brain, unfiltered and unprocessed by the BrainClient.

You can also listen for just BrainClient.EVENTS.BRAIN_EVENT to listen only for events from the brain that are not handled internally by logic inside the BrainClient.

Retrieve the ID of the connected brain. Promise returned will not resolve until brain is connected in some fashion.

Get the brain information (the "general" API route)

Connect the client to the brain. await this function to ensure the connection is setup before calling other methods. See BrainClient#setupConnection for further notes on connection setup if this method is too opaque for your needs.

Example usage:

const bc = new BrainClient();
await bc.connectToBrain("127.0.0.1");

Disconnect the WebSocket, if connected, closing all communication with the brain.

Get the current connection status of the Brain Client. For possible states, please see BrainClient.CONNECTION. When the connection status of the client changes, the event BrainClient.EVENTS.CONNECTION_STATUS_CHANGED will be emitted by the client as well.

Retrieve a BrainDevice based on name or ID of the device

Return a hash of deviceId => BrainDevice instances for this Brain's devices, allowing you to retrieve/watch states and execute commands.

Get the layout for a specific handset from the brain and notify the Brain of the selected handset.

NOTE: Response to this query is returned as a separate event via the WebSocket

Find and return the BrainDevice instance for this Brain's System Device, which will provide states and commands for things like time, weather, and custom states created in the KC Builder.

Returns a flag indicating if the client has cleanly authorized with the Brain in order to communicate with this space.

Returns a flag indicating if express mode has been enabled in the Manager for the space provisioned to this Brain.

NOTE: Without Express Mode enabled, the client will not be able to control this space via the WebSocket. However, some basic REST APIs will still work to retrieve information about the space.

Returns a flag indicating if authentication is required for this space.

Use BrainClient#submitPin to send PIN to the Brain, then await BrainClient#isAuthorized to be notified when BrainClient ready for use. You can also listen for BrainClient.EVENTS.AUTHORIZED instead of awaiting isAuthorized.

NOTE: You can also be notified of the need for a PIN by listening for the BrainClient.EVENTS.PIN_REQUIRED event. See BrainClient.EVENTS for discussion of that event.

Returns a flag indicating if any space has been provisioned to the brain. Without a space provisioned to the brain, there is nothing to control.

Remove an event attached with BrainClient#on. Inherited from the core node module EventEmitter - see that class for more complete on/off documentation. Included here for documentation purposes and to link to BrainClient.EVENTS for event names.

Attach listeners to events. Inherited from the core node module EventEmitter - see that class for more complete on/off documentation. Included here for documentation purposes and to link to BrainClient.EVENTS for event names.

Remove event listeners with BrainClient#off

Prepare the BrainClient to connect to a brain by setting up REST client and WebSocket connections.

You usually will not need to call this. Instead, we recommend awaiting BrainClient#connectToBrain instead. However, if you wish to reimplement BrainClient#setupConnection (which connectToBrain uses internally to bootstrap the client), then you should NOT call connectToBrain. Instead, create your client and call prepareConnection then implement whatever connection steps you want to use.

NOTE: You can/should await this method if you call it to ensure the Brain connection works. This method WILL throw an Error of undetermined type if there is a problem connecting with the Brain.

Example usage:

const bc = new BrainClient();
await bc.prepareConnection("10.0.1.138:8000");
if(await bc.isLoginNeeded()) {
	const pin = prompt("Please enter your PIN to connect to the Brain")
	bc.submitPin(pin);
}
await bc.isAuthorized();
const sys = bc.getSystemDevice();
// ...

Query to see if express mode is enabled.

For more a user-friendly interface to this information, see BrainClient#isExpressModeEnabled.

NOTE: Response to this query is returned as a separate event via the WebSocket

Query handsets from the brain

NOTE: Response to this query is returned as a separate event via the WebSocket

Request the brain's provisioning status.

For more a user-friendly interface to this information, see BrainClient#isProvisioned.

NOTE: Response to this query is returned as a separate event via the WebSocket

Request the brain's gateway status.

For more a user-friendly interface to similar information, see BrainClient#brainInfo and BrainInfo.

NOTE: Response to this query is returned as a separate event via the WebSocket

Send a UI action from the handset layout to the Brain. This function deals with prebuilt layouts from the Builder.

NOTE: To send actions/commands from specific devices, see BrainDevice.

Send the string or object over the WebSocket to the brain as-is, no checking/changes.

Send a prebuilt authorization structure to the Brain

This method promises to return only when the client is completely setup and free of any obvious error states, such is not being provisioned or not having express mode enabled.

It's important to note that consumers of BrainClient can implement all the checks/steps of this setup routine themselves - for example, to prompt for a PIN code interactively.

However, note that you CAN supply a function as the pin argument, which will be used as a callback if the brain requires a non-blank PIN. This function will be awaited. That means you could use still this method in a UI and simply provide a callback arg to pop up a dialog, for example.

A creative user of BrainClient could decide to not use setupConnection at all, and instead implement each of the steps that setupConnection does in their own code.

setupConnection does not use any private data, it just reuses accessors from BrainClient and packages them in the form of an easy-to-use and simple awaitable method. setupConnection will work for the majority of users that use BrainClient as-is.

However, if you find yourself needing more control over the init process of the connection, just call BrainClient#prepareConnection after constructing your BrainClient instance and then setup the connection however you would like.

Send the Authorization token to the brain

Once you submit the token, you can await BrainClient#isAuthorized or listen for BrainClient.EVENTS.AUTHORIZED to be notified when the authorization succeeeds.

If the token submitted fails, the BrainClient.EVENTS.PIN_REQUIRED event will be emitted again, but the connection status will not change.

NOTE: Response returned as a separate event via the WebSocket

Send the PIN to the brain

Once you submit the pin, you can await BrainClient#isAuthorized or listen for BrainClient.EVENTS.AUTHORIZED to be notified when the authorization succeeeds.

If the pin submitted fails, the BrainClient.EVENTS.PIN_REQUIRED event will be emitted again, but the connection status will not change.

NOTE: Response returned as a separate event via the WebSocket

Inform the Brain that this client wants to receive notifications of changes to a device's states via the WebSocket.

NOTE: This function is not designed for direct user access, although you can call if it desired, no ill side effects.

However, a more user-friendly way of watching for state changes would be to get the BrainDevice instance you want to work with and calling BrainDevice#on, for example:

device.on(BrainDevice.STATE_CHANGED, myCallback)

When you attach a listener to the STATE_CHANGED event, BrainDevice#on will automatically notify the Brain to send state changes using this method.

The BrainClient.CONNECTION_* properties define the various connection states that the BrainClient can be in. To get the current connection state, see BrainClient#getConnectionStatus. You cannot directly set the Brain Client's connectionStatus.

Example usage:

const bc = new BrainClient();
const state = bc.getConnectionStatus();

The BrainClient.EVENTS object holds keys that function as the event names for various events emitted by the BrainClient.

It's important to note that BrainDevice also emits it's own events when states change. See: BrainDevice and STATE_CHANGED property.

Use these properties below in conjunction with BrainClient#on to attach listeners.

Example usage:

const bc = new BrainClient();
bc.on(BrainClient.EVENTS.STATUS_MESSAGE, data => console.log(data));