Deploy for #581

docs/api.html

@@ -810,6 +810,13 @@
      end
   </a>
 
+</li>
+
+          <li class="md-nav__item">
+  <a href="#getconfig" class="md-nav__link">
+     getConfig
+  </a>
+
 </li>
 
           <li class="md-nav__item">
@@ -1458,6 +1465,13 @@
      end
   </a>
 
+</li>
+
+          <li class="md-nav__item">
+  <a href="#getconfig" class="md-nav__link">
+     getConfig
+  </a>
+
 </li>
 
           <li class="md-nav__item">
@@ -1890,6 +1904,14 @@ <h3 id="end"><i class="fa fa-caret-right"></i> end<a class="headerlink" href="#e
 <p class="admonition-title">Attention to end</p>
 <p>The end function releases the instance of ESP8266WebServer/WebServer and DNSServer. It can not process them after the end function.</p>
 </div>
+<h3 id="getconfig"><i class="fa fa-caret-right"></i> getConfig<a class="headerlink" href="#getconfig" title="Permanent link">&para;</a></h3>
+<p class="badge"><img src="images/tag_ac.png"> <img src="images/tag_accore.png"></p>
+
+<div class="highlight" style="background: #272822"><pre style="line-height: 125%;"><span></span><code><span style="color: #f8f8f2">AutoConnectConfig</span><span style="color: #f92672">&amp;</span><span style="color: #f8f8f2"> getConfig(</span><span style="color: #66d9ef">void</span><span style="color: #f8f8f2">)</span>
+</code></pre></div>
+<p>Get the current AutoConnectConfig values held by AutoConnect.<dl class="apidl">
+    <dt><strong>Return value</strong></dt>
+    <dd>A reference to an AutoConnectConfig instance retained by AutoConnect. This reference reflects the actual values captured by the <a href="#config">AutoConnect::config</a> function, unlike the AutoConnectConfig value declared in the sketch.</dd></dl></p>
 <h3 id="geteepromusedsize"><i class="fa fa-caret-right"></i> getEEPROMUsedSize<a class="headerlink" href="#geteepromusedsize" title="Permanent link">&para;</a></h3>
 <p class="badge"><img src="images/tag_ac.png"> <img src="images/tag_accore.png"></p>
 

docs/apiaux.html

@@ -1619,6 +1619,11 @@ <h3 id="menu"><i class="fa fa-caret-right"></i> menu<a class="headerlink" href="
     <dt><strong>Parameter</strong></dt>
     <dd><span class="apidef">true</span><span class="apidesc">Show on the menu.</span></dd>
     <dd><span class="apidef">false</span><span class="apidesc">Hidden on the menu.</span></dd></dl></p>
+<div class="admonition note">
+<p class="admonition-title">AutoConnectAux::menu and isMenu have no effect on AutoConnect built-in menu items</p>
+<p>Some of AutoConnect's built-in pages make use of AutoConnectAux class. You can use the <a href="api.html#aux">AutoConnect::aux</a> or <a href="api.html#locate">AutoConnect::locate</a> function with those URLs to retrieve the AutoConnectAux for built-in pages, but the <a href="apiaux.html#menu">menu</a> function does not show/hide the <a href="menu.html#right-on-top">built-in items</a> of the menu list.  <br />
+Also, it is not recommended to use <a href="api.html#aux">AutoConnect::aux</a> or <a href="api.html#locate">locate</a> functions to get AutoConnect's built-in pages. Instructions on how to show/hide AutoConnect's built-in menu items can be found in the <a href="menu.html#applying-the-active-menu-items">Applying the active menu items</a> section.</p>
+</div>
 <h3 id="on"><i class="fa fa-caret-right"></i> on<a class="headerlink" href="#on" title="Permanent link">&para;</a></h3>
 <div class="highlight" style="background: #272822"><pre style="line-height: 125%;"><span></span><code><span style="color: #66d9ef">void</span><span style="color: #f8f8f2"> on(</span><span style="color: #66d9ef">const</span><span style="color: #f8f8f2"> AuxHandlerFunctionT handler, </span><span style="color: #66d9ef">const</span><span style="color: #f8f8f2"> AutoConnectExitOrder_t order </span><span style="color: #f92672">=</span><span style="color: #f8f8f2"> AC_EXIT_AHEAD)</span>
 </code></pre></div>

docs/menu.html

@@ -359,6 +359,19 @@
      Applying the active menu items
   </a>
 
+    <nav class="md-nav" aria-label=" Applying the active menu items">
+      <ul class="md-nav__list">
+
+          <li class="md-nav__item">
+  <a href="#enable-ota-menu-on-demand-using-an-external-switch-connected-to-a-gpio" class="md-nav__link">
+    Enable OTA menu on demand using an external switch connected to a GPIO.
+  </a>
+
+</li>
+
+      </ul>
+    </nav>
+
 </li>
 
         <li class="md-nav__item">
@@ -1201,6 +1214,19 @@
      Applying the active menu items
   </a>
 
+    <nav class="md-nav" aria-label=" Applying the active menu items">
+      <ul class="md-nav__list">
+
+          <li class="md-nav__item">
+  <a href="#enable-ota-menu-on-demand-using-an-external-switch-connected-to-a-gpio" class="md-nav__link">
+    Enable OTA menu on demand using an external switch connected to a GPIO.
+  </a>
+
+</li>
+
+      </ul>
+    </nav>
+
 </li>
 
         <li class="md-nav__item">
@@ -1278,7 +1304,7 @@ <h2 id="reset"><i class="fa fa-bars"></i> Reset...<a class="headerlink" href="#r
 <p>The Reset menu is using the <strong>ESP.reset()</strong> function for ESP8266. This is an almost hardware reset. In order to resume the Sketch normally, the <a href="https://github.com/esp8266/esp8266-wiki/wiki/Boot-Process#esp-boot-modes">state of GPIO0</a> is important. Since this depends on the circuit implementation for each module, not every module will be rebooted normally. See also <a href="faq.html#hang-up-after-reset">FAQ</a>.</p>
 </div>
 <h2 id="custom-menu-items"><i class="fa fa-bars"></i> Custom menu items<a class="headerlink" href="#custom-menu-items" title="Permanent link">&para;</a></h2>
-<p>If the Sketch has custom Web pages, the AutoConnect menu lines them up with the AutoConnect's items. Details for <a href="acintro.html#custom-web-pages-in-autoconnectmenu">Custom Web pages in AutoConnect menu</a>.</p>
+<p>If the Sketch has custom Web pages, the AutoConnect menu lines them up with the AutoConnect's items. Details for <a href="acintro.html#custom-web-pages-in-autoconnect-menu">Custom Web pages in AutoConnect menu</a>.</p>
 <h2 id="update"><i class="fa fa-bars"></i> Update<a class="headerlink" href="#update" title="Permanent link">&para;</a></h2>
 <p>If you specify <a href="apiconfig.html#ota">AutoConnectConfig::ota</a> to import the OTA update feature into Sketch, an item will appear in the menu list as <strong>Update</strong>.</p>
 <div class="admonition note">
@@ -1301,17 +1327,58 @@ <h2 id="applying-the-active-menu-items"><i class="fa fa-bars"></i> Applying the
 <span style="color: #f8f8f2">  portal.config(config);</span>
 <span style="color: #f8f8f2">}</span>
 </code></pre></div>
-<p>The next is another way to achieve the same effect.</p>
+<p>Following code snippet is another way to achieve the same effect.</p>
 <div class="highlight" style="background: #272822"><pre style="line-height: 125%;"><span></span><code><span style="color: #f8f8f2">AutoConnect portal;</span>
 
 <span style="color: #66d9ef">void</span><span style="color: #f8f8f2"> </span><span style="color: #a6e22e">setup</span><span style="color: #f8f8f2">() {</span>
 <span style="color: #f8f8f2">  portal.disableMenu(AC_MENUITEM_CONFIGNEW </span><span style="color: #f92672">|</span><span style="color: #f8f8f2"> AC_MENUITEM_DISCONNECT);</span>
 <span style="color: #f8f8f2">  portal.config(config);</span>
 <span style="color: #f8f8f2">}</span>
 </code></pre></div>
-<p>The result of executing the above Sketch is as below:</p>
+<p>Here is the result of running the above sketch:</p>
 <p><img src="images/applymenu.png" style="border-style:solid;border-width:1px;border-color:lightgrey;width:280px;" /></p>
-<p>Details for <a href="apiconfig.html#menuitems">AutoConnectConfig::menuItems</a>.</p>
+<p><a href="apiconfig.html#menuitems">AutoConnectConfig::menuItems</a> section has more details.</p>
+<p>AutoConnect shows and hides menu items when <a href="api.html#begin">AutoConnect::begin</a> is executed and when <a href="api.html#handleclient">AutoConnect::handleClient</a> is executed in a <code>loop</code> function. You can dynamically change the available menu items during the <em>loop()</em> by setting the show/hide items before executing those functions with <a href="api.html#enablemenu">AutoConnect::enableMenu</a> and <a href="api.html#disablemenu">AutoConnect::disableMenu</a>.</p>
+<p>The current menu item settings held by AutoConnectConfig can be retrieved with the <a href="api.html#getconfig">AutoConnect::getConfig</a> function, and the code snippet to reconfigure menu items based on the <code>getConfig</code> return value is as follows:</p>
+<h4 id="enable-ota-menu-on-demand-using-an-external-switch-connected-to-a-gpio">Enable OTA menu on demand using an external switch connected to a GPIO.<a class="headerlink" href="#enable-ota-menu-on-demand-using-an-external-switch-connected-to-a-gpio" title="Permanent link">&para;</a></h4>
+<p><img src="images/menu_ondemand.png" width="320px" /></p>
+<div class="highlight" style="background: #272822"><pre style="line-height: 125%;"><span></span><code><span style="color: #66d9ef">const</span><span style="color: #f8f8f2"> </span><span style="color: #66d9ef">int</span><span style="color: #f8f8f2"> externalSwitch </span><span style="color: #f92672">=</span><span style="color: #f8f8f2"> </span><span style="color: #ae81ff">5</span><span style="color: #f8f8f2">;  </span><span style="color: #75715e">// Assign the OTA activation switch to D1 (GPIO5).</span>
+<span style="color: #f8f8f2">AutoConnect portal;</span>
+<span style="color: #f8f8f2">AutoConnectConfig config;</span>
+
+<span style="color: #66d9ef">void</span><span style="color: #f8f8f2"> </span><span style="color: #a6e22e">setup</span><span style="color: #f8f8f2">() {</span>
+<span style="color: #f8f8f2">  </span><span style="color: #75715e">// The logic level of the external switch assumes active LOW.</span>
+<span style="color: #f8f8f2">  </span><span style="color: #75715e">// Note: A said switch is an alternate and must retain its state.</span>
+<span style="color: #f8f8f2">  pinMode(externalSwitch, INPUT_PULLUP);</span>
+
+<span style="color: #f8f8f2">  </span><span style="color: #75715e">// Set up OTA, but hide the Update item from the menu list until an external</span>
+<span style="color: #f8f8f2">  </span><span style="color: #75715e">// switch is pressed.</span>
+<span style="color: #f8f8f2">  config.ota </span><span style="color: #f92672">=</span><span style="color: #f8f8f2"> AC_OTA_BUILTIN;</span>
+<span style="color: #f8f8f2">  portal.config(config);</span>
+<span style="color: #f8f8f2">  portal.disableMenu(AC_MENUITEM_UPDATE);</span>
+<span style="color: #f8f8f2">  portal.begin(); </span>
+<span style="color: #f8f8f2">}</span>
+
+<span style="color: #66d9ef">void</span><span style="color: #f8f8f2"> </span><span style="color: #a6e22e">loop</span><span style="color: #f8f8f2">() {</span>
+<span style="color: #f8f8f2">  </span><span style="color: #75715e">// Use AutoConnect::getConfig to obtain the current AutoConnectConfig values</span>
+<span style="color: #f8f8f2">  </span><span style="color: #75715e">// and indicate the display state of an Update item.</span>
+<span style="color: #f8f8f2">  </span><span style="color: #66d9ef">bool</span><span style="color: #f8f8f2">  menuUpdate </span><span style="color: #f92672">=</span><span style="color: #f8f8f2"> portal.getConfig().menuItems </span><span style="color: #f92672">&amp;</span><span style="color: #f8f8f2"> AC_MENUITEM_UPDATE;</span>
+
+<span style="color: #f8f8f2">  </span><span style="color: #75715e">// Hides the Update item from the menu list depending on the state of the switch.</span>
+<span style="color: #f8f8f2">  </span><span style="color: #66d9ef">if</span><span style="color: #f8f8f2"> (digitalRead(externalSwitch) </span><span style="color: #f92672">==</span><span style="color: #f8f8f2"> LOW </span><span style="color: #f92672">&amp;&amp;</span><span style="color: #f8f8f2"> </span><span style="color: #f92672">!</span><span style="color: #f8f8f2">(menuUpdate)) {</span>
+<span style="color: #f8f8f2">    portal.enableMenu(AC_MENUITEM_UPDATE);</span>
+<span style="color: #f8f8f2">  }</span>
+<span style="color: #f8f8f2">  </span><span style="color: #66d9ef">else</span><span style="color: #f8f8f2"> {</span>
+<span style="color: #f8f8f2">    portal.disableMenu(AC_MENUITEM_UPDATE);</span>
+<span style="color: #f8f8f2">  }</span>
+
+<span style="color: #f8f8f2">  portal.handleClient();</span>
+<span style="color: #f8f8f2">}</span>
+</code></pre></div>
+<div class="admonition note">
+<p class="admonition-title">enableMenu/disableMenu has no effect for custom web page items</p>
+<p><em>AutoConnect::enableMenu</em> and <em>disableMenu</em> functions are not enabled to show/hide menu items for <a href="acintro.html">custom web pages</a>. They only work on AutoConnect's built-in pages<sup id="fnref:2"><a class="footnote-ref" href="#fn:2">2</a></sup>. Use the <a href="apiaux.html#menu">AutoConnectAux::menu</a> and <a href="apiaux.html#ismenu">AutoConnectAux::isMenu</a> functions to show/hide menu items for custom web pages. For more information, see <a href="acintro.html#custom-web-pages-in-autoconnect-menu">Custom Web pages in AutoConnect menu</a> section.</p>
+</div>
 <h2 id="attaching-to-autoconnect-menu"><i class="fa fa-bars"></i> Attaching to AutoConnect menu<a class="headerlink" href="#attaching-to-autoconnect-menu" title="Permanent link">&para;</a></h2>
 <p>The AutoConnect menu can contain your sketch's web pages as extra items as a custom. It works for HTML pages implemented by the <strong>ESP8266WebServer::on</strong> handler or the <strong>WebServer::on</strong> handler for ESP32. That is, you can make them invoke the legacy web pages from the AutoConnect menu. The below screen-shot is the result of adding an example sketch for the ESP8266WebServer library known as <a href="https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WebServer/examples/FSBrowser">FSBrowser</a> to the AutoConnect menu item. It can add Edit and List items with little modification to the legacy sketch code.</p>
 <div style="float:left;width:auto;height:420px;"><img style="width:auto;height:420px;" src="images/fsbmenu.png"></div>
@@ -1323,6 +1390,9 @@ <h2 id="attaching-to-autoconnect-menu"><i class="fa fa-bars"></i> Attaching to A
 <li id="fn:1">
 <p>AutoConnect does not check the syntax and validity of the entered IP address. If the entered static IPs are incorrect, it cannot connect to the access point.&#160;<a class="footnote-backref" href="#fnref:1" title="Jump back to footnote 1 in the text">&#8617;</a></p>
 </li>
+<li id="fn:2">
+<p>AutoConnect built-in pages are predefined by the <a href="api.html#enablemenu">AC_MENUITEM_t</a> enum value.&#160;<a class="footnote-backref" href="#fnref:2" title="Jump back to footnote 2 in the text">&#8617;</a></p>
+</li>
 </ol>
 </div>