car-bmw.html

<!--

  CAR BMW - config node which represents the ConnectedDrive account. Holds username/password.

-->
<script type="text/javascript">
  RED.nodes.registerType("car-bmw", {
    category: "config",
    defaults: {
      name: {value: "", required: false},
      region: {value: "0", required: true},
      unit: {value: "metric", required: true},
      storage: {value: "", required: false},
      debug: {value: false, required: true}
    },
    credentials: {
      username: {type: "text"},
      password: {type: "password"},
      captcha: {type: "password", required: false},
    },
    label: function() {
      return this.name ? this.name : "BMW ConnectedDrive";
    }
  });
</script>

<script type="text/x-red" data-template-name="car-bmw">
    <div class="form-row">
        <label for="node-config-input-name"><i class="fa fa-tag"></i> Name</label>
        <input type="text" id="node-config-input-name" />
    </div>
    <div class="form-row">
        <label for="node-config-input-username"><i class="fa fa-user"></i> Username</label>
        <input type="text" id="node-config-input-username" />
    </div>
    <div class="form-row">
        <label for="node-config-input-password"><i class="fa fa-key"></i> Password</label>
        <input type="password" id="node-config-input-password" />
    </div>
    <div class="form-row">
      <label for="node-config-input-captcha"><i class="fa fa-barcode"></i> Captcha</label>
      <input type="password" id="node-config-input-captcha" />
    </div>
    <div class="form-row">
      <label for="node-config-input-region"><i class="fa fa-globe"></i> Region</label>
      <select id="node-config-input-region" style="width:70%">
          <option value=0>Rest of World</option>
          <option value=1>USA</option>
          <option value=2>China</option>
      </select>
    </div>
    <div class="form-row">
      <label for="node-config-input-unit"><i class="fa fa-balance-scale"></i> Units</label>
      <select id="node-config-input-unit" style="width:70%">
          <option value=metric>km &amp; l</option>
          <option value=imperial>mi &amp; gal</option>
      </select>
    </div>
    <div class="form-row">
      <label for="node-config-input-storage" title="Name of the persistent context storage to keep the login state. Set only when multiple storages are configured."><i class="fa fa-database"></i> Storage</label>
      <input type="text" id="node-config-input-storage" placeholder="Leave empty for default" />
    </div>
    <div class="form-row">
      <label>&nbsp;</label>
      <input type="checkbox" id="node-config-input-debug" style="display: inline-block; width: auto; vertical-align: top;">
      <label for="node-config-input-debug" style="width: 70%;"> Debug mode</label>
    </div>
    <div class="form-tips">
      <p>You need to configure the username and password of your BMW ConnectedDrive account.</p>
      <p>Hint: Username is usually the email address you registered.</p>
      
      <p>About <b>Captcha</b></p>
      <p>Depending on your region, you will need a one-time token for the initial login that can be generated by solving a captcha. 
         Click one of the following links to obtain the token:
         <a href="https://bimmer-connected.readthedocs.io/en/stable/captcha/rest_of_world.html" target="_blank">Rest of World</a>, 
         <a href="https://bimmer-connected.readthedocs.io/en/stable/captcha/north_america.html" target="_blank">USA</a>.
      </p>
      <p>
         Paste it into the <label for="node-config-input-captcha" style="display: inline"><i>Captcha</i></label> input above and save &amp; deploy the flow that is using this account. 
         The token is valid only for a short period of time.
      </p>
      <p>
        Also ensure that you enabled a persistent <a href="https://nodered.org/docs/user-guide/context#context-stores" target="_blank">context storage</a> in the settings to preserve the login state, or you will have to solve a new captcha after a restart.
        <br>
        When multiple storages are configured, name the one to use in <label for="node-config-input-storage" style="display: inline"><i>Storage</i></label>.
      </p>
    </div>
</script>




<!--

  CAR BMW - "list" node to list all registered vehicles of an account.

-->
<script type="text/javascript">
  RED.nodes.registerType("car-bmw-list", {
    category: "BMW",
    color: "#2E9BDA",
    icon: "car.png",
    defaults: {
      account: {type: "car-bmw", required: true},
      name: {value: "", required: false},
      as: {value: "single", required: true}
    },
    inputs: 1,
    outputs: 1,
    paletteLabel: "BMW List",
    label: function() {
      return this.name ? this.name : "BMW ConnectedDrive List";
    },
    labelStyle: function() {
      return this.name ? "node_label_italic" : "";
    }
  });
</script>

<script type="text/x-red" data-template-name="car-bmw-list">
    <div class="form-row">
        <label for="node-input-account"><i class="fa fa-sign-in"></i> Account</label>
        <input type="text" id="node-input-account">
    </div>
    <div class="form-row">
        <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
        <input type="text" id="node-input-name" />
    </div>
    <div class="form-row">
        <label for="node-input-as"><i class="fa fa-sign-out"></i> Output</label>
        <select id="node-input-as" style="width:70%">
            <option value="single">as a single message containing an array</option>
            <option value="multi">as multiple messages, one for each car</option>
        </select>
    </div>
</script>

<script type="text/x-red" data-help-name="car-bmw-list">
  <p>Read the list of cars, that are assigned to a BMW ConnectedDrive account.</p>

  <h3>Inputs</h3>
    <dl class="message-properties">
      none
    </dl>

  <h3>Outputs</h3>
    <dl class="message-properties">
      <dt>payload <span class="property-type">array | object</span></dt>
      <dd> the result can be either a single message with a payload containing an array of car objects, or multiple
           messages that each contain an object of a car. In any case the object holds various properties describing the car.</dd>
      </dl>

  <h3>Details</h3>
    <p>The LIST node is used to list all cars which are assigned to a ConnectedDrive account.</p>

  <h3>References</h3>
    <ul>
      <li><a href="https://github.com/krauskopf/node-red-contrib-car-bmw">GitHub</a> - the nodes github repository</li>
    </ul>
</script>





<!--

  CAR BMW - "get" node to read different values from the car.

-->
<script type="text/javascript">
  RED.nodes.registerType("car-bmw-get", {
    category: "BMW",
    color: "#2E9BDA",
    icon: "car.png",
    defaults: {
      account: {type: "car-bmw", required: true},
      name: {value: "", required:false},
      datatype: {value: "state", required: true}
    },
    credentials: {
      vin: {type: "text", required: true}
    },
    inputs: 1,
    outputs: 1,
    paletteLabel: "BMW Get",
    label: function() {
      if (this.name) {
        return this.name;
      }

      var text = {
        "service":                          "Service \u2020",
        "specs":                            "Specifications \u2020",
        "dynamic":                          "Dynamic \u2020",
        "navigation":                       "Navigation \u2020",
        "chargingprofile":                  "Charging Profile",
        "servicepartner":                   "Service Partner \u2020",
        "efficiency":                       "Efficiency \u2020",
        "statistics/allTrips":              "All Trips \u2020",
        "statistics/lastTrip":              "Last Trip \u2020",
        "status":                           "Status \u2020",
        "destinations":                     "Destinations \u2020",
        "charging-statistics":              "Charging Statistics",
        "charging-sessions":                "Charging Sessions",
        "state":                            "State"
      };

      return "" + text[this.datatype];
    }
  });
</script>

<script type="text/x-red" data-template-name="car-bmw-get">
    <div class="form-row">
        <label for="node-input-account"><i class="fa fa-sign-in"></i> Account</label>
        <input type="text" id="node-input-account">
    </div>
    <div class="form-row">
        <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
        <input type="text" id="node-input-name" />
    </div>
    <div class="form-row">
        <label for="node-input-vin"><i class="fa fa-car"></i> VIN</label>
        <input type="text" id="node-input-vin" placeholder="e.g. WBSXXXXXXXV123456"/>
    </div>
    <div class="form-row">
        <label for="node-input-datatype"><i class="fa fa-file-text-o"></i> Data type</label>
        <select id="node-input-datatype" style="width:70%">
            <!--<option value="service">Services</option>-->
            <!--<option value="specs">Specifications</option>-->
            <!--<option value="dynamic">Dynamic</option>-->
            <!--<option value="navigation">Navigation</option>-->
            <!--<option value="servicepartner">Service Partner</option>-->
            <!--<option value="efficiency">Efficiency</option>-->
            <option value="state">State</option>
            <option value="charging-statistics">Charging Statistics</option>
            <option value="charging-sessions">Charging Sessions</option>
            <option value="chargingprofile">Charging Profile</option>
        </select>
    </div>
</script>

<script type="text/x-red" data-help-name="car-bmw-get">
  <p>Read different informations about your car.</p>

  <h3>Inputs</h3>
    <dl class="message-properties">
      <dt class="optional">vin <span class="property-type">string</span></dt>
      <dd> if not set in the node configuration panel, this property specifies the VIN (vehicle identification number) of the car to read the infos from.</dd>
    </dl>

  <h3>Outputs</h3>
    <dl class="message-properties">
      <dt>payload <span class="property-type">object</span></dt>
      <dd> the return value. An object which has multiple properties with the data as returned from the ConnectedDrive server.</dd>
    </dl>

  <h3>Details</h3>
    <p>The GET node is used to read the current state of a car. Select the desired data type to read in the editor panel.
    You also have to specify the VIN (vehicle identification number) of your car. You can get the VIN of your car by looking in your
    documents of by using the List node.<br>
    If no VIN is given in the node configuration panel, then the vin in <code>msg.vin</code> is used.</p>

  <h3>References</h3>
    <ul>
      <li><a href="https://github.com/krauskopf/node-red-contrib-car-bmw">GitHub</a> - the nodes github repository</li>
    </ul>
</script>





<!--

  CAR BMW - "action" node to trigger remote service of the car.

-->
<script type="text/javascript">
  RED.nodes.registerType("car-bmw-action", {
    category: "BMW",
    color: "#2E9BDA",
    icon: "car.png",
    defaults: {
      account: {type: "car-bmw", required: true},
      name: {value: "", required:false},
      action: {value: "RLF", required: true}
    },
    credentials: {
      vin: {type: "text", required: true}
    },
    inputs: 1,
    outputs: 1,
    paletteLabel: "BMW Action",
    label: function() {
      if (this.name) {
        return this.name;
      }

      var text = {
        "RLF": "Flash Headlights",
        "RHB": "Blow Horn",
        "RDL": "Lock Door",
        "RDU": "Unlock Door",
        "RCN": "Start Climate",
        "RCNSTOP": "Stop Climate",
        "RVF": "Vehicle Finder",
        "CHARGE_NOW": "Charge Now \u2020",
        "CHANGE_CHARGING_MODE": "Change Charging Mode",
        "CHANGE_CHARGING_SETTINGS": "Change Charging Settings",
        "CHARGE_START": "Start Charging",
        "CHARGE_STOP": "Stop Charging"
      };

      return "Action: " + text[this.action];
    }
  });
</script>

<script type="text/x-red" data-template-name="car-bmw-action">
    <div class="form-row">
        <label for="node-input-account"><i class="fa fa-sign-in"></i> Account</label>
        <input type="text" id="node-input-account">
    </div>
    <div class="form-row">
        <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
        <input type="text" id="node-input-name" />
    </div>
    <div class="form-row">
        <label for="node-input-vin"><i class="fa fa-car"></i> VIN</label>
        <input type="text" id="node-input-vin" placeholder="e.g. WBSXXXXXXXV123456"/>
    </div>
    <div class="form-row">
        <label for="node-input-action"><i class="fa fa-car"></i> Action</label>
        <select id="node-input-action" style="width:70%">
            <option value="RLF">Flash Headlights</option>
            <option value="RHB">Blow Horn</option>
            <option value="RDL">Lock Door</option>
            <option value="RDU">Unlock Door</option>
            <option value="RCN">Start Climate</option>
            <option value="RCNSTOP">Stop Climate</option>
            <option value="RVF">Vehicle Finder</option>
            <!--<option value="CHARGE_NOW">Charge Now</option>-->
            <option value="CHANGE_CHARGING_MODE">Change Charging Mode</option>
            <option value="CHANGE_CHARGING_SETTINGS">Change Charging Settings</option>
            <option value="CHARGE_START">Start Charging</option>
            <option value="CHARGE_STOP">Stop Charging</option>
        </select>
    </div>
</script>

<script type="text/x-red" data-help-name="car-bmw-action">
  <p>Trigger an action on your car.</p>

  <h3>Inputs</h3>
    <dl class="message-properties">
      <dt class="optional">vin <span class="property-type">string</span></dt>
      <dd> if not set in the node configuration panel, this property specifies the VIN (vehicle identification number) of the car to read the infos from.</dd>
    </dl>
    <dl class="message-properties">
      <dt class="optional">payload <span class="property-type">string</span></dt>
      <dd> If provided, this property specifies the JSON payload body which will be sent to the car.</dd>
    </dl>

  <h3>Outputs</h3>
    <dl class="message-properties">
      <dt>payload <span class="property-type">object</span></dt>
      <dd> the return value. An object which has multiple properties with the data as returned from the ConnectedDrive server.</dd>
    </dl>

  <h3>Details</h3>
    <p>The ACTION node is used to trigger a remote service of a car. Select the desired action in the editor panel.
    You also have to specify the VIN (vehicle identification number) of your car. You can get the VIN of your car by looking in your
    documents of by using the List node.<br>
    If no VIN is given in the node configuration panel, then the vin in <code>msg.vin</code> is used.<br></p>

    <p>For some remote services (e.g. <code>Change Charging Mode</code>) a payload body has to be provided in <code>msg.payload</code>, which is sent to the car.</p>

    <p>For the <code>Change Charging Mode</code> action the payload body must contain the charge and climate timer details to which the charging mode should be changed.
    In this case the payload body must follow the object structure of the <code>chargeAndClimateTimerDetail</code> object returned by the <code>BMW Get</code> node for the data type <code>Charging Profile</code>.</p>

    <p>For the <code>Change Charging Settings</code> action the payload body must contain the following properties:
    <code>
    {
      "chargingTarget": xx,
      "acLimitValue": xx
    }
    </code><br>
    The <code>chargingTarget</code> must be a value between 20 and 100 in steps of 5.<br>
    The <code>acLimitValue</code> must be a value as returned by the <code>chargingSettingsDetail.acLimit.values</code> of the <code>Charging Profile</code> data type of the <code>BMW Get</code> node.<br>
    </p>

  <h3>References</h3>
    <ul>
      <li><a href="https://github.com/krauskopf/node-red-contrib-car-bmw">GitHub</a> - the nodes github repository</li>
    </ul>
</script>