virtual-device.html

<script type="text/javascript">
  function vshOnEditPrepare() {
    setTimeout(() => $('#donation').fadeIn('slow'), 2000)
  }

  RED.nodes.registerType('vsh-virtual-device', {
    category: 'virtual smart home',
    defaults: {
      name: { value: '', required: true },
      topic: { value: '', required: false },
      connection: { type: 'vsh-connection', required: true },
      template: { value: 'SWITCH', required: true },
      passthrough: { value: false },
      diff: { value: false },
      filter: { value: false },
    },
    inputs: 1,
    outputs: 1,
    icon: 'vsh_icon.svg',
    color: '#31C4F3',
    paletteLabel: 'virtual device',
    label: function () {
      return this.name || 'virtual device'
    },
    oneditprepare: vshOnEditPrepare,
  })
</script>

<style>
  #donation {
    display: none;
    padding: 15px;
    text-align: center;
    border: 3px #253b80 solid;
    margin-top: 30px;
    background-color: #cad7de;
    color: #253b80;
    width: 90%;
  }

  #donation > h1 {
    line-height: normal;
  }

  #donation > h2 {
    margin-top: 50px;
  }

  #donation > ul > li {
    list-style-position: inside;
  }

  #donation > ul > li a {
    text-decoration: underline;
    color: #253b80;
  }

  #donation img {
    height: 5em;
  }
</style>

<script type="text/html" data-template-name="vsh-virtual-device">
  <div class="form-row">
    <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
    <input type="text" id="node-input-name" placeholder="Name" />
  </div>

  <div class="form-row">
    <label for="node-input-topic"><i class="fa fa-tasks"></i> Topic</label>
    <input type="text" id="node-input-topic" placeholder="Topic" />
  </div>

  <div class="form-row">
    <label for="node-input-connection"
      ><i class="fa fa-amazon"></i> Connection</label
    >
    <input type="text" id="node-input-connection" placeholder="connection" />
  </div>

  <div class="form-row">
    <label for="node-input-template"><i class="fa fa-cubes"></i> Type</label>
    <select id="node-input-template">
      <option value="BLINDS">Blinds</option>
      <option value="COLOR_CHANGING_LIGHT_BULB">Color Changing Light Bulb</option>
      <option value="DIMMABLE_LIGHT_BULB">Dimmable Light Bulb</option>
      <option value="DIMMER_SWITCH">Dimmer Switch</option>
      <option value="FAN">Fan</option>
      <option value="GARAGE_DOOR_OPENER">Garage Door Opener</option>
      <option value="PLUG">Plug</option>
      <option value="SCENE">Scene</option>
      <option value="SWITCH">Switch</option>
      <option value="TEMPERATURE_SENSOR">Temperature Sensor</option>
      <option value="THERMOSTAT">Thermostat</option>
    </select>
  </div>

  <div class="form-row">
    <label for="node-input-passthrough"
      ><i class="fa fa-forward"></i> Passthrough</label
    >
    <input
      type="checkbox"
      id="node-input-passthrough"
      style="display:inline-block;width:22px;vertical-align:top;"
      autocomplete="off"
    /> Emit state on inbound message
  </div>

  <div class="form-row">
    <label for="node-input-filter"
      ><i class="fa fa-filter"></i> Filter</label
    >
    <input
      type="checkbox"
      id="node-input-filter"
      style="display:inline-block;width:22px;vertical-align:top;"
      autocomplete="off"
    /> Ignore inbound messages unless name matches
  </div>

  <div class="form-row">
    <label for="node-input-diff"
      ><i class="fa fa-clone"></i> Diff</label
    >
    <input
      type="checkbox"
      id="node-input-diff"
      style="display:inline-block;width:22px;vertical-align:top;"
      autocomplete="off"
    /> Emit only attributes set by Alexa
  </div>

  <div id="donation">
    <h1>Please Support</h1>
    <p>
      Your <i>virtual smart home</i> can only function as long as I am
      paying the bills for the backend infrastructure.
    </p>
    <p>If you are satisfied with this project, please help me to keep the system up.</p>
    <a
      target="_blank"
      href="https://paypal.me/cornelius/5"
      ><img src="icons/node-red-contrib-virtual-smart-home/donate.png"
    /></a>
    <h2>... and Spread the Love</h2>
    <p>
      I dedicated many hours to this project and really hope it adds value for you!
      Nothing is more rewarding to me than your feedback. So if you are a happy user, please
      <ul>
        <li>rate the <i>virtual smart home</i> skill on the <a href="https://skills-store.amazon.com/deeplink/dp/B08JV9RT7H?deviceType=app&share&refSuffix=ss_copy">Alexa skill store</a></li>
        <li>rate the <i>virtual smart home</i> <a href="https://flows.nodered.org/node/node-red-contrib-virtual-smart-home">Node-RED package</a></li>
        <li>mention this package in your next blog post / podcast / YouTube</li>
      </ul>
    </p>
    <h1>THANK YOU</h1>
  </div>
</script>

<script type="text/html" data-help-name="vsh-virtual-device">
  <p>A virtual device that can be controlled via Amazon Alexa.</p>
  <p>
    The node gets invoked through Amazon Alexa (either via a voice command or
    via the Alexa app) and outputs a <code>msg</code> object containing the
    updated device state as <code>payload</code>.
  </p>

  <p>
    If the &quot;Diff&quot; option is enabled, the outgoing msg object will only
    contain those attributes that were set by the Alexa command. For example,
    &quot;Alexa, dim the light to fifty percent&quot; results in only the
    'directive' and 'brightness' attributes being emitted.
  </p>

  <p>
    The node also accepts inbound messages that can be used to inform Alexa
    about local device changes, which will then be reflected in the Alexa app.
    If the &quot;Passthrough&quot; option is enabled, this will also trigger an
    outgoing message with the complete current local state. In this case
    <code>payload.source</code> is set to 'device' instead of 'alexa'.
  </p>

  <h3>Inputs</h3>
  <dl class="message-properties">
    <dt>
      payload
      <span class="property-type">object</span>
    </dt>
    <dd>
      key/value pairs of device attributes to update. Invalid attributes will be
      silently ignored. (Available attributes are documented below). If the
      'Filter' option is enabled, inbound messages will also be ignored unless
      <code>msg.payload.name</code> matches the device name.
    </dd>
  </dl>

  <h3>Outputs</h3>
  <dl class="message-properties">
    <dt>
      topic
      <span class="property-type">string</span>
    </dt>
    <dd>topic string as configured in the virtual device node</dd>
  </dl>
  <dl class="message-properties">
    <dt>
      payload
      <span class="property-type">object</span>
    </dt>
    <dd>key/value pairs of device attributes.</dd>
  </dl>
  <h3>Details</h3>
  <p>
    This node requires a connection to be configured, which links the node to an
    Amazon account. This can be done by clicking the pencil icon. Also, the
    Alexa skill 'virtual smart home' needs to be enabled for the same Amazon
    account.
  </p>
  <p>
    All virtual device nodes that belong to one Alexa account should share the
    same connection!
  </p>

  <h3>Payload attributes</h3>
  <p>
    Depending on the configured device type, the node accepts and outputs
    payloads with different attributes. For example, a switch device has the
    attribute 'powerState' and a dimmable light bulb device has an additional
    'brightness' attribute.
  </p>
  <p>
    This node ships with examples that illustrate the payload structure. They
    can be found in the 'import nodes' section underneath the 'import' menu.
  </p>

  <h4>General Attributes (always present)</h4>
  <dl class="message-properties">
    <dt>
      payload.name
      <span class="property-type">string</span>
    </dt>
    <dd>Name of the virtual device</dd>
  </dl>

  <dl class="message-properties">
    <dt>
      payload.type
      <span class="property-type">string</span>
    </dt>
    <dd>Type of the virtual device</dd>
  </dl>

  <dl class="message-properties">
    <dt>
      payload.source
      <span class="property-type">string</span>
    </dt>
    <dd>
      <ul>
        <li>'alexa' if the device update was triggered by Alexa</li>
        <li>
          'device' if the device update was triggered by an inbound message.
        </li>
      </ul>
    </dd>
  </dl>

  <dl class="message-properties">
    <dt>
      payload.directive
      <span class="property-type">string</span>
    </dt>
    <dd>
      Name of the directive that was invoked by Alexa, e.g. 'TurnOn'. Only
      present for state changes triggered by Alexa (payload.source == 'alexa')
    </dd>
  </dl>

  <h4>Blinds</h4>
  <dl class="message-properties">
    <dt>
      payload.percentage
      <span class="property-type">int</span>
    </dt>
    <dd>Position in % (0...100). 100 = Open</dd>
  </dl>

  <h4>Color Changing Light Bulb</h4>
  <dl class="message-properties">
    <dt>
      payload.powerState
      <span class="property-type">string</span>
    </dt>
    <dd>'ON' or 'OFF'</dd>
    <dt>
      payload.brightness
      <span class="property-type">int</span>
    </dt>
    <dd>Brightness in % (0...100)</dd>
    <dt>
      payload.lightMode
      <span class="property-type">string</span>
    </dt>
    <dd>
      <ul>
        <li>'temp': colorTemperatureInKelvin attribute is applied</li>
        <li>
          'hsb': color attribute is applied. For convenience, the color will
          also be populated as <code>payload.color_rgb</code>,
          <code>payload.color_hex</code>, and <code>payload.color_cmyk</code>.
        </li>
      </ul>
    </dd>
    <dt>
      payload.colorTemperatureInKelvin
      <span class="property-type">int</span>
    </dt>
    <dd>Color Temperature in Kelvin (1000...10000)</dd>
    <dt>
      payload.color
      <span class="property-type">object</span>
    </dt>
    <dd>Color expressed as hue, saturation and brightness (hsb)</dd>
    <dt>
      payload.color.hue
      <span class="property-type">int</span>
    </dt>
    <dd>Hue (0...360)</dd>
    <dt>
      payload.color.saturation
      <span class="property-type">float</span>
    </dt>
    <dd>Saturation (0.0...1.0)</dd>
    <dt>
      payload.color.brightness
      <span class="property-type">float</span>
    </dt>
    <dd>Brightness (0.0...1.0)</dd>
    <dt>
      payload.color_rgb
      <span class="property-type">array(3)</span>
    </dt>
    <dd>RGB representation of <code>payload.color</code> (0...255)</dd>
    <dt>
      payload.color_hex
      <span class="property-type">string</span>
    </dt>
    <dd>
      Hexadecimal representation of <code>payload.color</code>, e.g.
      &quot;#FF00AA&quot;
    </dd>
    <dt>
      payload.color_cmyk
      <span class="property-type">array(4)</span>
    </dt>
    <dd>CMYK representation of <code>payload.color</code> (0...100)</dd>
    <dt>
      payload.color_lab
      <span class="property-type">array(3)</span>
    </dt>
    <dd>[EXPERIMENTAL] LAB representation of <code>payload.color</code></dd>
    <dt>
      payload.color_xy
      <span class="property-type">array(2)</span>
    </dt>
    <dd>
      [EXPERIMENTAL] XY representation of <code>payload.color</code>. color_xy
      is only set for outbound messages and cannot yet be set on inbound
      messages.
    </dd>
    <dt>
      payload.color_xyz
      <span class="property-type">array(3)</span>
    </dt>
    <dd>[EXPERIMENTAL] XYZ representation of <code>payload.color</code></dd>
  </dl>

  <h4>Dimmable Light Bulb</h4>
  <dl class="message-properties">
    <dt>
      payload.powerState
      <span class="property-type">string</span>
    </dt>
    <dd>'ON' or 'OFF'</dd>
    <dt>
      payload.brightness
      <span class="property-type">int</span>
    </dt>
    <dd>Brightness in % (0...100)</dd>
  </dl>

  <h4>Dimmer Switch</h4>
  <dl class="message-properties">
    <dt>
      payload.powerState
      <span class="property-type">string</span>
    </dt>
    <dd>'ON' or 'OFF'</dd>
    <dt>
      payload.brightness
      <span class="property-type">int</span>
    </dt>
    <dd>Brightness in % (0...100)</dd>
  </dl>

  <h4>Fan</h4>
  <dl class="message-properties">
    <dt>
      payload.powerState
      <span class="property-type">string</span>
    </dt>
    <dd>'ON' or 'OFF'</dd>
    <dt>
      payload.speed
      <span class="property-type">int</span>
    </dt>
    <dd>Fan speed (0...10)</dd>
  </dl>

  <h4>Garage Door Opener</h4>
  <dl class="message-properties">
    <dt>
      payload.mode
      <span class="property-type">string</span>
    </dt>
    <dd>'Position.Up' or 'Position.Down'</dd>
  </dl>

  <h4>Plug</h4>
  <dl class="message-properties">
    <dt>
      payload.powerState
      <span class="property-type">string</span>
    </dt>
    <dd>'ON' or 'OFF'</dd>
  </dl>

  <h4>Switch</h4>
  <dl class="message-properties">
    <dt>
      payload.powerState
      <span class="property-type">string</span>
    </dt>
    <dd>'ON' or 'OFF'</dd>
  </dl>

  <h4>Scene</h4>
  <p>
    Scene nodes do not accept inbound messages and can only be triggered by
    Alexa.
  </p>
  <dl class="message-properties">
    <dt>
      payload.isActivated
      <span class="property-type">boolean</span>
    </dt>
    <dd>
      <code>true</code> when the scene was activated, <code>false</code> when
      the scene was deactivated
    </dd>
  </dl>

  <h4>Temperature Sensor</h4>
  <dl class="message-properties">
    <dt>
      payload.temperature
      <span class="property-type">float</span>
    </dt>
    <dd>Temperature</dd>
    <dt>
      payload.scale
      <span class="property-type">string</span>
    </dt>
    <dd>
      Scale / unit of temperature. Allowed values: 'CELSIUS', 'FAHRENHEIT',
      'KELVIN'
    </dd>
  </dl>

  <h4>Thermostat</h4>
  <dl class="message-properties">
    <dt>
      payload.targetTemperature
      <span class="property-type">float</span>
    </dt>
    <dd>Target temperature</dd>
    <dt>
      payload.targetScale
      <span class="property-type">string</span>
    </dt>
    <dd>
      Scale / unit of targetTemperature. Allowed values: 'CELSIUS',
      'FAHRENHEIT', 'KELVIN'
    </dd>
    <dt>
      payload.temperature
      <span class="property-type">float</span>
    </dt>
    <dd>Measured temperature</dd>
    <dt>
      payload.scale
      <span class="property-type">string</span>
    </dt>
    <dd>
      Scale / unit of temperature. Allowed values: 'CELSIUS', 'FAHRENHEIT',
      'KELVIN'
    </dd>
  </dl>
</script>