Command Buttons & Monitors

commands.htm (hint: right click, save as)

  1<!--
  2  Test/Development/Documentation page; install as plugin to test
  3-->
  4
  5<style>
  6h3 {
  7  margin-top: 40px;
  8  margin-bottom: 20px;
  9}
 10</style>
 11
 12<div class="panel panel-primary">
 13  <div class="panel-heading">Commands &amp; Monitors</div>
 14  <div class="panel-body">
 15
 16  <p>Command execution is only allowed for an authorized session. The command API will
 17    output "Unauthorized" and a Login button as necessary. The login state is also
 18    available in the global variable <code>loggedin</code>. To send the user to the
 19    login page and return to the current page after login, call <code>login()</code>:</p>
 20
 21  <p>
 22    <button type="button" class="btn btn-default action-login" onclick="login()">Login</button>
 23    <button type="button" class="btn btn-default action-logout" onclick="logout()">Logout</button>
 24  </p>
 25
 26  <script>
 27    $('.action-login').prop('disabled', loggedin);
 28    $('.action-logout').prop('disabled', !loggedin);
 29  </script>
 30
 31
 32  <h3>Command Execution on Load</h3>
 33
 34  <p>To execute a command automatically on page load, simply add the <code>monitor</code> class
 35    to an output element, set <code>data-updcmd</code> to the command to be executed and
 36    <code>data-updcnt</code> to 1:</p>
 37
 38  <pre class="monitor" data-updcmd="boot status" data-updcnt="1">Fetching boot status…</pre>
 39
 40  <p>Output elements typically are <code>samp</code> or <code>pre</code>, as commands
 41    normally output formatted plain text, but any element can be used. <code>samp</code>
 42    by default compresses white space and has no visible area, while <code>pre</code>
 43    is visible and preserves all spacing.</p>
 44
 45  <p><code>updcnt</code> will count down to zero and stop, or run indefinitely if started
 46    below zero. The execution interval can be given in <code>data-updint</code> (in seconds).
 47    You can set the data attributes any time using jQuery, all monitors are checked and
 48    updated by the framework once per second.</p>
 49
 50
 51  <h3>Command Execution on Events</h3>
 52
 53  <p>To automatically trigger a monitor update on OVMS events, additionally set the
 54    <code>data-events</code> attribute to a regular expression matching the event(s) of
 55    interest. This example monitor lists the active network channels and automatically
 56    updates on all server connection events:</p>
 57
 58  <p><pre class="monitor"
 59    data-events="server.*(connect|open|close|stop)"
 60    data-updcmd="network list"
 61    data-updcnt="1"></pre></p>
 62
 63  <p>
 64    Try:
 65    <a class="btn btn-default" onclick="window.open('/', '_blank', 'width=400,height=500')">Open new window</a>
 66    <a class="btn btn-default" href="#" data-cmd="server v2 stop">Stop V2 server</a>
 67    <a class="btn btn-default" href="#" data-cmd="server v2 start">Start V2 server</a>
 68    <a class="btn btn-default" href="#" data-cmd="event raise server.fake.open">Send fake event</a>
 69  </p>
 70
 71
 72  <h3>Command Buttons</h3>
 73
 74  <p>A bootstrap button has the base class <code>btn</code>. Add the command to execute
 75    as attribute <code>data-cmd</code> and optionally the output element as
 76    <code>data-target</code> and you're done.</p>
 77
 78  <div class="row">
 79
 80    <div class="col-sm-6">
 81      <button type="button" class="btn btn-default" data-target="#out1" data-cmd="wifi status">
 82        Wifi Status → <code>&lt;samp&gt;</code>
 83      </button>
 84      <samp id="out1" />
 85    </div>
 86
 87    <div class="col-sm-6">
 88      <button type="button" class="btn btn-default" data-target="#out2" data-cmd="wifi status">
 89        Wifi Status → <code>&lt;pre&gt;</code>
 90      </button>
 91      <pre id="out2" />
 92    </div>
 93
 94  </div>
 95
 96  <p>Add class <code>samp-inline</code> or wrap in a <code>ul.list-inline</code> to place
 97    the output element on the same line with the button. Prefix the target with a "+" to
 98    append to it:</p>
 99
100  <p>
101    External 12V power
102    <button type="button" class="btn btn-info" data-target="+#out3" data-cmd="power ext12v on">on</button>
103    <button type="button" class="btn btn-info" data-target="+#out3" data-cmd="power ext12v off">off</button>
104    <samp class="samp-inline" id="out3" />
105  </p>
106
107
108  <h3>Combining Buttons &amp; Monitors</h3>
109
110  <p>By combination of a button and a monitor, you can let the button start a repeated
111    execution of a command: set <code>data-watchcnt</code> on the button to the number of
112    repetitions (default 0) and <code>data-watchint</code> to the interval in seconds
113    (default 2).</p>
114
115  <p>
116    <button type="button" class="btn btn-default" data-target="#out4"
117      data-cmd="power cellular on" data-watchcnt="-1" data-watchint="3">
118      Power on cellular modem &amp; get status updates every 3 seconds
119    </button>
120    <pre class="monitor" id="out4" data-updcmd="cellular status" />
121  </p>
122
123  <p>Note: to stop a monitor, set <code>data-updcnt</code> to 0:
124    <button type="button" class="btn btn-default" onclick="$('#out4').data('updcnt', 0)">
125      Stop updates
126    </button></p>
127
128
129  <h3>Execute Javascript</h3>
130
131  <p>To execute Javascript code directly (i.e. without calling <code>script eval</code>),
132    simply exchange the <code>data-cmd / data-updcmd</code> attribute by
133    <code>data-js / data-updjs</code>. Example:</p>
134
135  <p>
136    <button type="button" class="btn btn-default" data-target="#out5"
137      data-js="JSON.print(OvmsConfig.GetValues('vehicle'))">
138      Show vehicle config
139    </button>
140    <pre id="out5" />
141  </p>
142
143  </div>
144</div>
145
146
147<script>
148(function(){
149  /* Show page source: */
150  var pagesrc = $('#main').html();
151  $('.panel-heading').prepend('<button type="button" class="btn btn-sm btn-info action-showsrc"' +
152    ' style="float:right; position:relative; top:-5px;">Show page source</button>');
153  $('.action-showsrc').on('click', function() {
154    $('<div/>').dialog({
155      title: 'Source Code',
156      body: '<pre style="font-size:85%; height:calc(100vh - 230px);">'
157        + encode_html(pagesrc) + '</pre>',
158      size: 'lg',
159    });
160  });
161})();
162</script>