Under the work of v0.9.7 documentation

examples/mqttRSSI/README.md

@@ -0,0 +1,63 @@
+## mqttRSSI
+
+### Publish ESP8266/ESP32 WiFi signal strength to MQTT broker
+
+This example is based on the description of the MQTT client application in the [AutoConnect documentation](https://hieromon.github.io/AutoConnect/examples/index.html#used-with-mqtt-as-a-client-application). To experience this example, you need to prepare the [ThingSpeak](https://thingspeak.com/) account and the channel for MQTT message exchange in advance. 
+
+<img src="https://hieromon.github.io/AutoConnect/images/ac_mqtt_setting.png" width="40%"/>
+&nbsp;&nbsp;
+<img src="https://hieromon.github.io/AutoConnect/images/ChannelStatus.png" width="40%"/>
+
+The ThingSpeak is the open IoT platform. It is capable of sending data privately to the cloud and analyzing, visualizing its data. If you do not have an account of ThingSpeak, you need that account to proceed further.
+
+### Advance procedures
+
+- Arduino Client for MQTT - It's the [PubSubClient](https://github.com/knolleary/pubsubclient), install it to Arduino IDE. If you have the latest version already, this step does not need.
+- Create a channel on ThingSpeak.
+- Get the Channel API Keys from ThingSpeak, put its keys to the sketch.
+
+You can sign up with the [ThingSpeak sign-up page](https://thingspeak.com/users/sign_up). (You are entrusted with the final judgment of account creation for ThingSpeak. Create an account at your own risk.) And you can learn about other steps from the [explanation page](https://hieromon.github.io/AutoConnect/examples/index.html#advance-procedures) of this example.
+
+### Obtaining the keys you need
+
+A mqttRSSI requires the following three key data. After completing the above preparation you should be able to get the three key data. Specify those key data to the `value` in each element of the `param.json` file in the `data` folder.
+
+#### Channel ID
+
+```json
+{
+  "name": "channelid",
+  "type": "ACInput",
+  "value": "",
+  "label": "Channel ID"
+}
+```
+
+#### User API key
+
+```json
+{
+  "name": "userkey",
+  "type": "ACInput",
+  "value": "",
+  "label": "User Key"
+}
+```
+
+#### Write API key
+
+```json
+{
+  "name": "apikey",
+  "type": "ACInput",
+  "value": "",
+  "label": "API Key"
+}
+```
+
+### Sketch data upload
+
+To `param.json` file upload to ESP8266/ESP32 flash memory, you need use the plugin tools as sketch data uploader. You can get one (or both) of the plugins below and upload the `param.json` file to the module.
+
+- [Arduino ESP8266 filesystem uploader](https://github.com/esp8266/arduino-esp8266fs-plugin)
+- [Arduino ESP32 filesystem uploader](https://github.com/me-no-dev/arduino-esp32fs-plugin)

examples/mqttRSSI/data/param.json

@@ -9,19 +9,19 @@
   {
     "name": "channelid",
     "type": "ACInput",
-    "value": "454951",
+    "value": "",
     "label": "Channel ID"
   },
   {
     "name": "userkey",
     "type": "ACInput",
-    "value": "NRTFYGJ6TJFGX4RC",
+    "value": "",
     "label": "User Key"
   },
   {
     "name": "apikey",
     "type": "ACInput",
-    "value": "HBVQ2XV6VYBI4582",
+    "value": "",
     "label": "API Key"
   }
 ]

examples/mqttRSSI/mqttRSSI.ino

@@ -16,13 +16,12 @@ https://opensource.org/licenses/MIT
 #if defined(ARDUINO_ARCH_ESP8266)
 #include <ESP8266WiFi.h>
 #include <ESP8266HTTPClient.h>
-#define GET_CHIPID()	(ESP.getChipId())
+#define GET_CHIPID()  (ESP.getChipId())
 #elif defined(ARDUINO_ARCH_ESP32)
 #include <WiFi.h>
-#include <WebServer.h>
 #include <SPIFFS.h>
 #include <HTTPClient.h>
-#define GET_CHIPID()	((uint16_t)(ESP.getEfuseMac()>>32))
+#define GET_CHIPID()  ((uint16_t)(ESP.getEfuseMac()>>32))
 #endif
 #include <FS.h>
 #include <PubSubClient.h>
@@ -35,10 +34,9 @@ https://opensource.org/licenses/MIT
 
 // JSON definition of AutoConnectAux.
 // Multiple AutoConnectAux can be defined in the JSON array.
-// In this example, JSON is hard-coded to make it easier to
+// In this example, JSON is hard-coded to make it easier to understand
-// understand the AutoConnectAux API. In practice, it will be
+// the AutoConnectAux API. In practice, it will be an external content
-// an external content which separated from the sketch,
+// which separated from the sketch, as the mqtt_RSSI_FS example shows.
-// as the mqtt_RSSI_FS example shows.
 static const char AUX_mqtt_setting[] PROGMEM = R"raw(
 [
   {
@@ -50,7 +48,7 @@ static const char AUX_mqtt_setting[] PROGMEM = R"raw(
         "name": "header",
         "type": "ACText",
         "value": "<h2>MQTT broker settings</h2>",
-        "style": "text-align:center;color:#2f4f4f;"
+        "style": "text-align:center;color:#2f4f4f;padding:10px;"
       },
       {
         "name": "caption",
@@ -212,15 +210,16 @@ bool mqttConnect() {
 
 void mqttPublish(String msg) {
   String path = String("channels/") + channelId + String("/publish/") + apiKey;
-  int    tLen = path.length();
+  // int    tLen = path.length();
-  char   topic[tLen];
+  // char   topic[tLen];
-  path.toCharArray(topic, tLen + 1);
+  // path.toCharArray(topic, tLen + 1);
 
-  int    mLen = msg.length();
+  // int    mLen = msg.length();
-  char   payload[mLen];
+  // char   payload[mLen];
-  msg.toCharArray(payload, mLen + 1);
+  // msg.toCharArray(payload, mLen + 1);
 
-  mqttClient.publish(topic, payload);
+  // mqttClient.publish(topic, payload);
+  mqttClient.publish(path.c_str(), msg.c_str());
 }
 
 int getStrength(uint8_t points) {
@@ -234,8 +233,8 @@ int getStrength(uint8_t points) {
   return points ? static_cast<int>(rssi / points) : 0;
 }
 
-// Load parameters saved with  saveParams from SPIFFS into
+// Load parameters saved with  saveParams from SPIFFS into the
-// the elements defined in /mqtt_setting JSON.
+// elements defined in /mqtt_setting JSON.
 String loadParams(AutoConnectAux& aux, PageArgument& args) {
   (void)(args);
   SPIFFS.begin();
@@ -252,43 +251,50 @@ String loadParams(AutoConnectAux& aux, PageArgument& args) {
     Serial.println("If you get error as 'SPIFFS: mount failed, -10025', Please modify with 'SPIFFS.begin(true)'.");
   }
   SPIFFS.end();
-  return "";
+  return String();
 }
 
-// Save the value of each element entered by /mqtt_setting to
+// Save the value of each element entered by '/mqtt_setting' to the
-// the parameter file. The saveParams as below is a callback
+// parameter file. The saveParams as below is a callback function of
-// function of /mqtt_save.
+// /mqtt_save. When invoking this handler, the input value of each
-// When this callback is invoked, the input value of each element
+// element is already stored in '/mqtt_setting'.
-// of /mqtt_setting is already stored in the AutoConnectAux object.
 // In Sketch, you can output to stream its elements specified by name.
 String saveParams(AutoConnectAux& aux, PageArgument& args) {
-  // PageArgument is a copy set of the elements that AutoConnectAux has.
+  // The 'where()' function returns the AutoConnectAux that caused
-  serverName = args.arg("mqttserver");
+  // the transition to this page.
+  AutoConnectAux*   mqtt_setting = portal.where();
+
+  AutoConnectInput& mqttserver = mqtt_setting->getElement<AutoConnectInput>("mqttserver");
+  serverName = mqttserver.value;
   serverName.trim();
 
-  channelId = args.arg("channelid");
+  AutoConnectInput& channelid = mqtt_setting->getElement<AutoConnectInput>("channelid");
+  channelId = channelid.value;
   channelId.trim();
 
-  userKey = args.arg("userkey");
+  AutoConnectInput& userkey = mqtt_setting->getElement<AutoConnectInput>("userkey");
+  userKey = userkey.value;
   userKey.trim();
 
-  apiKey = args.arg("apikey");
+  AutoConnectInput& apikey = mqtt_setting->getElement<AutoConnectInput>("apikey");
+  apiKey = apikey.value;
   apiKey.trim();
 
-  String upd = args.arg("period");
+  AutoConnectRadio& period = mqtt_setting->getElement<AutoConnectRadio>("period");
-  updateInterval = upd.substring(0, 2).toInt() * 1000;
+  updateInterval = period.value().substring(0, 2).toInt() * 1000;
 
-  String uniqueid = args.arg("uniqueid");
+  String uniqueid = mqtt_setting->getElement<AutoConnectInput>("uniqueid").value;
 
-  hostName = args.arg("hostname");
+  AutoConnectInput& hostname = mqtt_setting->getElement<AutoConnectInput>("hostname");
+  hostName = hostname.value;
   hostName.trim();
 
   // The entered value is owned by AutoConnectAux of /mqtt_setting.
-  // In order to retrieve the elements of /mqtt_setting,
+  // To retrieve the elements of /mqtt_setting, it is necessary to get
-  // it is necessary to get the AutoConnectAux object of /mqtt_setting.
+  // the AutoConnectAux object of /mqtt_setting.
   SPIFFS.begin();
   File param = SPIFFS.open(PARAM_FILE, "w");
-  portal.aux("/mqtt_setting")->saveElement(param, { "mqttserver", "channelid", "userkey", "apikey", "uniqueid", "hostname" });
+  mqtt_setting->saveElement(param, { "mqttserver", "channelid", "userkey", "apikey", "uniqueid", "hostname" });
   param.close();
   SPIFFS.end();
 
@@ -302,7 +308,7 @@ String saveParams(AutoConnectAux& aux, PageArgument& args) {
   echo.value += "Use APID unique: " + uniqueid + "<br>";
   echo.value += "ESP host name: " + hostName + "<br>";
 
-  return "";
+  return String();
 }
 
 void handleRoot() {
@@ -339,8 +345,7 @@ void handleClearChannel() {
   else
     Serial.println(" failed");
 
-  // Returns the redirect response. The page is reloaded and its contents
+  // Returns the redirect response.
-  // are updated to the state after deletion.
   WiFiWebServer&  server = portal.host();
   server.sendHeader("Location", String("http://") + server.client().localIP().toString() + String("/"));
   server.send(302, "text/plain", "");
@@ -354,11 +359,9 @@ void setup() {
   Serial.println();
 
   if (portal.load(FPSTR(AUX_mqtt_setting))) {
-    AutoConnectAux* setting = portal.aux(AUX_SETTING_URI);
+    AutoConnectAux* mqtt_setting = portal.aux(AUX_SETTING_URI);
-    PageArgument  args;
+    AutoConnectCheckbox&  uniqueidElm = mqtt_setting->getElement<AutoConnectCheckbox>("uniqueid");
-    loadParams(*setting, args);
+    AutoConnectInput&     hostnameElm = mqtt_setting->getElement<AutoConnectInput>("hostname");
-    AutoConnectCheckbox&  uniqueidElm = setting->getElement<AutoConnectCheckbox>("uniqueid");
-    AutoConnectInput&     hostnameElm = setting->getElement<AutoConnectInput>("hostname");
     if (uniqueidElm.checked) {
       config.apid = String("ESP") + "-" + String(GET_CHIPID(), HEX);
       Serial.println("apid set to " + config.apid);

examples/mqttRSSI_FS/mqttRSSI_FS.ino

@@ -153,8 +153,9 @@ String saveParams(AutoConnectAux& aux, PageArgument& args) {
   hostName = args.arg("hostname");
   hostName.trim();
   
-  // In order to retrieve the elements of /mqtt_setting,
+  // The entered value is owned by AutoConnectAux of /mqtt_setting.
-  // it is necessary to get the AutoConnectAux object of /mqtt_setting.
+  // To retrieve the elements of /mqtt_setting, it is necessary to get
+  // the AutoConnectAux object of /mqtt_setting.
   SPIFFS.begin();
   File param = SPIFFS.open(PARAM_FILE, "w");
   portal.aux("/mqtt_setting")->saveElement(param, { "mqttserver", "channelid", "userkey", "apikey", "period", "uniqueid", "hostname" });