virtual-device.html

<script type="text/javascript">
  function vshOnEditPrepare() {
    $('#node-input-deviceId').val('vshd-' + this.id.replace('.', ''))

    $('#node-input-metadata').typedInput({
      type: 'json',
      types: ['json'],
    })

    const vshConnectionNodeId = $('#node-input-connection')[0].value

    if (vshConnectionNodeId === '_ADD_') {
      return
    }

    $.getJSON(
      'vsh-connection/' + vshConnectionNodeId + '?_=' + new Date().getTime(),
      function ({ plan }) {
        $('#vsh-current-plan')
          .text(plan.toUpperCase())
          .addClass('vsh-plan-' + plan)

        if (plan === 'free') {
          setTimeout(() => $('#subscription-hint').fadeIn('slow'), 1500)
        }

        if (plan === 'pro') {
          $('#node-input-retrievable').prop('disabled', false)
          $('#retrievable-label').removeClass('retrievable-option-disabled')
        }
      }
    )
  }

  RED.nodes.registerType('vsh-virtual-device', {
    category: 'virtual smart home',
    defaults: {
      name: { value: '', required: true },
      //deviceId: { value: 'vshd-xxx', required: false },
      topic: { value: '', required: false },
      metadata: {
        value: '',
        required: false,
        validate: (value) => {
          if (value === '') {
            // empty metadata should not be marked as invalid
            return true
          }

          try {
            return typeof JSON.parse(value) === 'object'
          } catch (e) {
            return false
          }
        },
      },
      connection: { type: 'vsh-connection', required: true },
      template: { value: 'SWITCH', required: true },
      retrievable: { value: false },
      passthrough: { value: false },
      diff: { value: false },
      filter: { value: false },
      filterTopic: { value: false },
      plan: { value: 'free' },
    },
    inputs: 1,
    outputs: 1,
    icon: 'vsh_icon.svg',
    color: '#31C4F3',
    paletteLabel: 'virtual device',
    label: function () {
      return this.name || 'virtual device'
    },
    oneditprepare: vshOnEditPrepare,
  })
</script>

<style>
  #subscription-hint {
    display: none;
    padding: 12px;
    text-align: center;
    border: 3px #00691c solid;
    margin-top: 30px;
    background-color: #e3fddd;
    color: #00691c;
    width: 90%;
  }

  #subscription-hint > h1 {
    line-height: normal;
  }

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

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

  #subscription-hint > ul > li a {
    text-decoration: underline;
    color: #00691c;
  }

  #subscription-hint img {
    height: 5em;
  }

  .retrievable-option-disabled {
    color: var(--red-ui-secondary-text-color-disabled);
  }

  .vsh-plan-unknown {
    padding: 3px;
    border: #615f5f solid 1px;
    background-color: rgb(190, 190, 190);
  }

  .vsh-plan-free {
    padding: 3px;
    border: #f8dc09 solid 1px;
    background-color: #ffff7a;
  }

  .vsh-plan-pro {
    padding: 3px;
    border: #00691c solid 1px;
    background-color: #e3fddd;
  }
</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><i class="fa fa-code"></i> Metadata</label>
    <input
      type="text"
      id="node-input-metadata"
      placeholder="arbitrary optional metadata"
    />
  </div>

  <div class="form-row">
    <label for="node-input-deviceId"
      ><i class="fa fa-hashtag"></i> Device ID</label
    >
    <input
      type="text"
      readonly
      id="node-input-deviceId"
      placeholder="vshd-???"
    />
  </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><i class="fa fa-credit-card"></i> Plan</label>
    <span id="vsh-current-plan">
      <i>available when at least 1 device is connected</i>
    </span>
  </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="CONTACT_SENSOR">Contact Sensor</option>
      <option value="DIMMABLE_LIGHT_BULB">Dimmable Light Bulb</option>
      <option value="DIMMER_SWITCH">Dimmer Switch</option>
      <option value="DOORBELL_EVENT_SOURCE">Doorbell Event Source</option>
      <option value="ENTERTAINMENT_DEVICE">Entertainment Device</option>
      <option value="FAN">Fan</option>
      <option value="GARAGE_DOOR_OPENER">Garage Door Opener</option>
      <option value="LOCK">Lock</option>
      <option value="MOTION_SENSOR">Motion Sensor</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 (Single-setpoint)</option>
      <option value="THERMOSTAT_2">Thermostat (Dual-setpoint)</option>
    </select>
  </div>

  <div class="form-row">
    <label for="node-input-retrievable"
      ><i class="fa fa-arrow-up"></i> Retrievable</label
    >
    <input
      type="checkbox"
      id="node-input-retrievable"
      disabled
      style="display:inline-block;width:22px;vertical-align:top;"
      autocomplete="off"
    />
    <span id="retrievable-label" class="retrievable-option-disabled"
      >Alexa can retrieve device state (&quot;Pro&quot; feature)</span
    >
  </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 by name</label
    >
    <input
      type="checkbox"
      id="node-input-filter"
      style="display:inline-block;width:22px;vertical-align:top;"
      autocomplete="off"
    />
    Ignore inbound messages unless &quot;name&quot; matches
  </div>
  <div class="form-row">
    <label for="node-input-filterTopic"
      ><i class="fa fa-filter"></i> Filter by topic</label
    >
    <input
      type="checkbox"
      id="node-input-filterTopic"
      style="display:inline-block;width:22px;vertical-align:top;"
      autocomplete="off"
    />
    Ignore inbound messages unless &quot;topic&quot; 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="subscription-hint">
    <h1>Upgrade to VSH Pro</h1>
    <ul>
      <li>control up to 200 virtual devices</li>
      <li>device status retrievable by Alexa</li>
      <li>cancellable at any time</li>
    </ul>
    <p>Switch to &quot;Pro&quot; on the <i>Connection</i> page</p>
  </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'. If the
    inbound message has a <code>topic</code> attribute, its value will be
    present in the outbound msg instead of the topic configured in the editor.
  </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. If the 'Filter
      topic' option is enabled, inbound messages will also be ignored unless
      <code>msg.topic</code> matches the topic of the node.
    </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>
      metadata
      <span class="property-type">object</span>
    </dt>
    <dd>metadata 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 unless stated otherwise)</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>

  <dl class="message-properties">
    <dt>
      payload.rawDirective
      <span class="property-type">object</span>
    </dt>
    <dd>
      Raw directive object received from the
      <a
        href="https://developer.amazon.com/en-US/docs/alexa/device-apis/smart-home-general-apis.html"
        >Alexa Smart Home Skill API</a
      >. Sensitive attributes (e.g. OAuth tokens) are excluded on purpose. 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>Contact Sensor</h4>
  <dl class="message-properties">
    <dt>
      payload.detectionState
      <span class="property-type">string</span>
    </dt>
    <dd>
      'DETECTED' = The sensor is open and the two pieces of the sensor are not
      in contact with each other. For example, after a window has been opened.
    </dd>
    <dd>
      'NOT_DETECTED' = The sensor is closed and the two pieces of the sensor are
      in contact with each other.
    </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>Doorbell Event Source</h4>
  <dl class="message-properties">
    <dt>
      payload.detectionState
      <span class="property-type">string</span>
    </dt>
    <dd>'DETECTED' = Doorbell is pressed.</dd>
    <dd>'NOT_DETECTED' = Doorbell is not pressed.</dd>
  </dl>

  <h4>Entertainment Device</h4>
  <dl class="message-properties">
    <dt>
      payload.channel
      <span class="property-type">int</span>
    </dt>
    <dd>Channel number (1...999)</dd>
    <dt>
      payload.input
      <span class="property-type">string</span>
    </dt>
    <dd>
      Input source (e.g. 'HDMI 1',
      <a
        href="https://developer.amazon.com/en-US/docs/alexa/device-apis/alexa-inputcontroller.html"
        >etc.</a
      >)
    </dd>
    <dt>
      payload.muted
      <span class="property-type">boolean</span>
    </dt>
    <dd>
      <code>true</code> when the speaker is muted, otherwise <code>false</code>
    </dd>
    <dt>
      payload.powerState
      <span class="property-type">string</span>
    </dt>
    <dd>'ON' or 'OFF'</dd>
    <dt>
      payload.volume
      <span class="property-type">int</span>
    </dt>
    <dd>Volume 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>
  <p>
    Garage Door Opener is supported by Alexa only in the following locales:
    en-US.
  </p>
  <dl class="message-properties">
    <dt>
      payload.mode
      <span class="property-type">string</span>
    </dt>
    <dd>'Position.Up' or 'Position.Down'</dd>
  </dl>

  <h4>Lock</h4>
  <dl class="message-properties">
    <dt>
      payload.lockState
      <span class="property-type">string</span>
    </dt>
    <dd>'LOCKED' = The device is currently locked.</dd>
    <dd>'UNLOCKED' = The device is currently unlocked.</dd>
    <dd>
      'JAMMED' = The lock can't transition to locked or unlocked because the
      locking mechanism is jammed.
    </dd>
  </dl>

  <h4>Motion Sensor</h4>
  <dl class="message-properties">
    <dt>
      payload.detectionState
      <span class="property-type">string</span>
    </dt>
    <dd>'DETECTED' = Motion is detected.</dd>
    <dd>'NOT_DETECTED' = Motion is not detected.</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 (Single-setpoint)</h4>
  <dl class="message-properties">
    <dt>
      payload.powerState
      <span class="property-type">string</span>
    </dt>
    <dd>'ON' or 'OFF'</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>
    <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.thermostatMode
      <span class="property-type">string</span>
    </dt>
    <dd>'AUTO', 'HEAT', 'COOL', 'ECO', 'OFF'</dd>
  </dl>
  <h4>Thermostat (Dual-setpoint)</h4>
  <dl class="message-properties">
    <dt>
      payload.powerState
      <span class="property-type">string</span>
    </dt>
    <dd>'ON' or 'OFF'</dd>
    <dt>
      payload.lowerSetpoint
      <span class="property-type">float</span>
    </dt>
    <dd>Lower setpoint temperature</dd>
    <dt>
      payload.lowerSetpointScale
      <span class="property-type">string</span>
    </dt>
    <dd>
      Scale / unit of lowerSetpoint. Allowed values: 'CELSIUS', 'FAHRENHEIT',
      'KELVIN'
    </dd>
    <dt>
      payload.upperSetpoint
      <span class="property-type">float</span>
    </dt>
    <dd>Upper setpoint temperature</dd>
    <dt>
      payload.upperSetpointScale
      <span class="property-type">string</span>
    </dt>
    <dd>
      Scale / unit of upperSetpoint. 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>
    <dt>
      payload.thermostatMode
      <span class="property-type">string</span>
    </dt>
    <dd>'AUTO', 'HEAT', 'COOL', 'ECO', 'OFF'</dd>
  </dl>
</script>