rvl-node

RVL Node

A Node.js implementation of rvl based on Web Assembly. For a fully functioning example, take a look at the Home Lights server I wrote.

Installation

Install using npm:

npm install rvl-node

Usage

The below code instantiates an RVL instance in controller mode, and then sets the animation pattern to be displayed on all other RVL devices listening on channel 1.

import { createManager } from 'rvl-node';
import {
  createWaveParameters,
  createSolidColorWave,
} from 'rvl-node-animations';

async function run() {
  const manager = await createManager();
  controller.setAnimationParameters(
    1, // Channel 1
    createAnimationParameters(
      createSolidColorAnimation(0, 255, 255) // Set the LED animation to solid red in the HSV space
    )
  );
}
run();

API

Note: the signatures below use the TypeScript definitions for clarity. The types are not enforced in pure JavaScript, so in theory you can mix and match, but honestly I never tested that scenario and have no idea what will happen.

If you're not familiar with TypeScript syntax, there are basically three things you need to know:

1. A variables type is specified after the variable name, and separated by a :. For example, x: number means we have a variable named x, and it's a number.
2. A ? after the variable name and before the : means that the variable is optional. For example, { x?: number } means the x property in this object can be left out.

getAvailableInterfaces

Gets the list of available network interfaces that RVL Node can use. To be considered valid, it must have an IPv4 address, and the name must start with en, eth, wlan, Wi-Fi, or Ethernet.

Signature:

function getAvailableInterfaces(): string[];

Arguments: none.

Returns: a list of interface names that can be used with RVL Node

getDefaultInterface

Gets the default network interface that RVL Node will use, if no value is supplied for networkInterface in a call to createManager.

Signature:

function getDefaultInterface(): string | undefined;

Arguments: none.

Returns: The name of the interface that will be used, or undefined if there is no suitable interface.

createManager

Instantiates a new RVL manager, which can be used to create controllers.

Signature:

interface RVLManagerOptions {
  networkInterface?: string;
  port?: number;
}

function createManager(options?: RVLManagerOptions): Promise<RVLManager>;

Arguments:

Argument	Type	Description
options	Object	The options to instantiate the RVL manager with
	Property Type Description networkInterface (optional) string The network interface to send/receive RVL packets on, e.g. "wlan0". If no value is provided, RVL will use the first interface it can find with an IPv4 address that's not 127.0.0.1 port (optional) number The UDP port to bind to. Default is 4978.

Returns: a promise that resolves to the manager once the manager has been initialized.

RVL Manager Instance Properties

networkInterface: string

This read-only property returns the network interface the manager is bound to.

address: string

This read-only property returns the IP address of the network interface the manager is bound to.

port: string

This read-only property returns the port the manager is bound to.

deviceId: string

This read-only property returns the device ID that this manager will appear as to other RVL nodes. As of this writing, this is the last octet of the IP address.

RVL Manager Instance Methods

setAnimationParameters

Sets the animation parameters for the system on a specific channel. These parameters will be synced to any other RVL devices on this channel within 2 seconds at most. You can craft animation parameters by hand, but it's recommended to use the rvl-node-animations helper libraries instead. Crafting parameters by hand is a pain.

This method can only be called when the device is in controller mode, and cannot be called until the initialized event is emitted.

Signature:

setAnimationParameters(channel: number, parameters: AnimationParameters): void

Arguments:

Argument	Type	Description
channel	number	The channel number to set the animation parameters for.
parameters	AnimationParameters	The animation parameters to set in the system.

Returns: none.

setPowerState

Sets the power state for the controller. This is a handy way to turn off lights instead of setting the color to black.

Signature:

setPowerState(channel: number, newPowerState: boolean): void

Arguments:

Argument	Type	Description
channel	number	The channel number to set the power state for.
newPowerState	boolean	The power state, with `true` meaning "on" and `false` meaning "off."

Returns: none

License

Copyright (c) Bryan Hughes bryan@nebri.us

This file is part of RVL Node.

RVL Node is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

RVL Node is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with RVL Node. If not, see http://www.gnu.org/licenses/.