further work on docs - org an structure of markdown pages

gigapod · gigapod · commit a66719b9d54f · 2024-05-04T10:47:20.000-06:00
diff --git a/docs/act_sysfirmware.md b/docs/act_sysfirmware.md
@@ -1,4 +1,4 @@
-# System Reset and Firmware Update Action - ESP32
+# Firmware Update - ESP32 {#flux-using-esp32-firmware}
 
 > *ESP32*
 
@@ -26,7 +26,6 @@ When this option is selected, the user is presented a prompt to continue. To lau
 
 ![Restart Prompt](images/act_sysfirm_restart.png)
 
-
 ## Factory Reset
 
 A factory reset will move the boot firmware of the device to the firmware imaged installed at the ***factory*** and erase any on-board stored settings on the device. This is helpful if an update fails, or an update has issues that prevent proper operations.
@@ -180,7 +179,7 @@ The `VersionNumber` field is often created by the following formula:
   versionNumber = Major_Version * 10000 + Minor_Version * 100 + Point_Version
 ```
 
-#### MD5 Hash Creation 
+#### MD5 Hash Creation
 
 The following command are used to create an MD5 hash value
 
@@ -201,5 +200,3 @@ Windows - using `Power Shell`
 ```
 Get-FileHash <firmware file> -Algorithm MD5
 ```
-
-
diff --git a/docs/ar_autoload.md b/docs/ar_autoload.md
@@ -1,4 +1,4 @@
-# Device Detection and Loading {#device_detection_loading}
+# I2C Device Detection {#device_detection_loading}
 
 One of the key features of the Flux framework is the ability to automatically detect and load different I2C devices, while placing minimal requirements on the device driver developer.
 
diff --git a/docs/build_with_flux.md b/docs/build_with_flux.md
@@ -1,9 +1,9 @@
 
-# Building with Flux
+# Building with Flux {#building-with-flux}
 
-This section outline the steps needed to support Flux in an Arduino Build Environment. Both support for Arduino IDE development, as well as automated builds that use the Arduino CLI (GitHub actions). 
+This section outline the steps needed to support Flux in an Arduino Build Environment. Both support for Arduino IDE development, as well as automated builds that use the Arduino CLI (GitHub actions).
 
-Since Flux is private, only available to SparkFun employees and approved partners, the build integration is different from standard Open Source projects. 
+Since Flux is private, only available to SparkFun employees and approved partners, the build integration is different from standard Open Source projects.
 
 ## Using Flux within the Arduino IDE
 
@@ -31,9 +31,9 @@ To use Flux in another project that is being build using build automation (GitHu
 git submodule add git@github.com:sparkfun/SparkFun_Flux.git
 ```
 
-With this structure in place, access to the Flux within a GitHub action is accomplished by using ssh keys. 
+With this structure in place, access to the Flux within a GitHub action is accomplished by using ssh keys.
 
-The first step is to generate a new key locally - in a shell 
+The first step is to generate a new key locally - in a shell
 
 ```sh
 ssh-keygen -t rsa -b 4096 -C "Access to flux"
@@ -47,11 +47,11 @@ Next add the public part of the key to the Flux repo as a deploy key. In the Flu
 
 Give the key a descriptive name (***my project access key***) and paste the public part of the key into the dialog. Keep the key read-only.
 
-The next step is to add the private part of the key as a ***secret*** in main project (the project using flux) github repository. This is done in ```Settings > Secrets and variables > Actions``` page. On this page, on the **Secrets** tab, select the ***New repository secret*** button. 
+The next step is to add the private part of the key as a ***secret*** in main project (the project using flux) github repository. This is done in ```Settings > Secrets and variables > Actions``` page. On this page, on the **Secrets** tab, select the ***New repository secret*** button.
 
 ![Action Secret](images/github_action_secret.png)
 
-In the provided dialog, enter a name for the secret (follow  variable naming methodology) and set the value to the private portion of the generated key. 
+In the provided dialog, enter a name for the secret (follow  variable naming methodology) and set the value to the private portion of the generated key.
 
 ## Download the Flux Submodule
 
@@ -73,10 +73,9 @@ Within a github action, the key is used to download the Flux submodule. Once the
 
 NOTE: In this example, ```FLUX_PULL_KEY_2``` is the name of the Flux key secret within this repository.
 
-
 Once the Flux submodule is checked out, the application is setup and built using the Arduino Command Line (```arduino-cli```)
 
-## Using Arduino CLI 
+## Using Arduino CLI
 
 ### Installation
 
@@ -100,11 +99,11 @@ If working within a github action, the following code will install and setup the
         run: arduino-cli core install esp32:esp32
 ```
 
-Note: The above example also installed the ESP32 platform 
+Note: The above example also installed the ESP32 platform
 
 ### Install Flux Dependencies
 
-The Flux repository includes a script that installs all library dependencies using the ```arduino-cli```. This command, ```install-libs.sh``` is located within the root directory of the Flux repository. 
+The Flux repository includes a script that installs all library dependencies using the ```arduino-cli```. This command, ```install-libs.sh``` is located within the root directory of the Flux repository.
 
 To run this command within a github Action, the following code is used:
 
@@ -114,13 +113,13 @@ To run this command within a github Action, the following code is used:
         run: ./SparkFun_Flux/install-libs.sh
 ```
 
-Note: The above command assumes Flux is installed in the root directory of the repository. Adjust the command path to the structure of your repository if needed. 
+Note: The above command assumes Flux is installed in the root directory of the repository. Adjust the command path to the structure of your repository if needed.
 
 ### Compile and Build
 
 Once all the dependencies are installed, the ```arduino-cli compile``` option is called to build the desired application. To use Flux as a library, the ```--library``` switch is used with the compile call.
 
-The following is an example of building an ESP32 based sketch, which uses the Flux library. 
+The following is an example of building an ESP32 based sketch, which uses the Flux library.
 
 Note that the location of the Flux library is passed in using the ```--library'`` switch, and that the ***full*** path to the Flux directory is provided. Using a relative path to the Flux library directory causes this command to fail
 
@@ -145,4 +144,4 @@ For reference, once the above compile command is completed, the resultant Firmwa
         with:
           name: SparkFun_DataLoggerIoT.bin
           path: sfeDataLoggerIoT/build/esp32.esp32.esp32/SparkFun_DataLoggerIoT.bin
-```
+```
diff --git a/docs/device_writing.md b/docs/device_writing.md
@@ -111,7 +111,9 @@ The return value should be one of the following:
 |```flxDevConfidenceFuzzy``` | The algorithm has high-confidence in a match, but it's not exact|
 |```flxDevConfidencePing``` | An address "ping" is used - just detecting a device at a location, but not verifying the device type.|
 
-> Note: Only one device with a PING confidence is allowed at an address.
+> [!note]
+>
+> Only one device with a PING confidence is allowed at an address.
 
 #### Example Method Definition
 
@@ -174,9 +176,6 @@ Where `DeviceClassName` is the class name of the device being registered.
 
 Once a device is registered, it is available for auto-detection and loading by the framework during the startup process of system.
 
-> ![note]
-> The ```flxRegisterDevice()``` call is a macro that defines a global object using a c++ template. The object is instantiated on system startup (all globals are), and in the constructor of the object, it registers itself with the device discovery system.
-
 Building off the above BME280 example, the implementation looks like:
 
 ```cpp
@@ -253,6 +252,7 @@ bool flxDevBME280::onInitialize(TwoWire &wirePort)
 ```
 
 > [!note]
+>
 > The ```address()``` method returns the device address for this instance of the driver.
 
 ### Determining if a Device is Initialized
diff --git a/docs/devices.md b/docs/devices.md
@@ -1,4 +1,4 @@
-# Devices
+# Available Devices   {#flux-available-devices}
 
 Supported devices are:
 
diff --git a/docs/doxygen/doxygen-config b/docs/doxygen/doxygen-config
@@ -950,6 +950,9 @@ WARN_LOGFILE           =
 # Note: If this tag is empty the current directory is searched.
 
 INPUT                  =    docs/flux.dox \
+                            docs/flux_using.md \
+                            docs/flux_developing.md \
+                            docs/flux_architecture.md \
                             docs \
                             src \
                             README.md 
diff --git a/docs/flux_architecture.md b/docs/flux_architecture.md
@@ -0,0 +1,3 @@
+# Flux Architecture {#framework_architecture}
+
+* @subpage device_detection_loading
diff --git a/docs/flux_developing.md b/docs/flux_developing.md
@@ -1,6 +1,5 @@
-# Framework Development {#framework_development}
+# Flux Development {#framework_development}
 
 * @subpage properties_overview
 * @subpage parameters_overview
 * @subpage writing_a_device_class
-* @subpage device_detection_loading
diff --git a/docs/flux_using.md b/docs/flux_using.md
@@ -0,0 +1,6 @@
+# Using Flux {#flux-using}
+
+* @subpage building-with-flux
+* @subpage flux-using-iot
+* @subpage flux-available-devices
+* @subpage flux-using-esp32
diff --git a/docs/flux_using_esp32.md b/docs/flux_using_esp32.md
@@ -0,0 +1,3 @@
+# Using Flux on ESP32 {#flux-using-esp32}
+
+* @subpage flux-using-esp32-firmware
diff --git a/docs/flux_using_iot.md b/docs/flux_using_iot.md
@@ -0,0 +1,8 @@
+# Flux IoT Destinations {#flux-using-iot}
+
+* @subpage flux-using-iot-arduino
+* @subpage flux-using-iot-aws
+* @subpage flux-using-iot-azure
+* @subpage flux-using-iot-http
+* @subpage flux-using-iot-mqtt
+* @subpage flux-using-iot-thingspeak
diff --git a/docs/iot_arduino.md b/docs/iot_arduino.md
@@ -1,4 +1,4 @@
-# Creating and Connecting to an Arduino IoT Device
+# Arduino IoT Device {#flux-using-iot-arduino}
 
 One of the key features of the Flux Framework is it's simplified access to IoT service providers. This document outlines how an Arduino IoT Device is used by the Flux framework.
 
diff --git a/docs/iot_aws.md b/docs/iot_aws.md
@@ -1,4 +1,4 @@
-# Creating and Connecting to an AWS IoT Device (Thing)
+# AWS IoT Device (Thing) {#flux-using-iot-aws}
 
 One of the key features of the Flux Framework is it's simplified access to IoT service providers. This document outlines how an AWS IoT device is used by the Flux framework.
 
diff --git a/docs/iot_azure.md b/docs/iot_azure.md
@@ -1,6 +1,6 @@
-# Creating and Connecting to an Azure IoT Device
+# Azure IoT Device {#flux-using-iot-azure}
 
-One of the key features of the Flux Framework is it's simplified access to IoT service providers. This document outlines how an Azure IoT device is used by the Flux framework. 
+One of the key features of the Flux Framework is it's simplified access to IoT service providers. This document outlines how an Azure IoT device is used by the Flux framework.
 
 The following is covered by this document:
 
@@ -17,13 +17,13 @@ Azure IoT enables connectivity between an IoT / Edge device and the Azure Cloud
 
 In Azure IoT, an virtual representation of an actual device is created and referred to as a *Device*. The virtual device is allocated a connection endpoint, security certificates and a device **digital twin** - a JSON document used to persist, communicate and manage device state within Azure. Unlike AWS IoT, data from the device isn't posted to the devices digital twin (AWS Shadow), but to the device directly.
 
-The actual IoT device communicates with it's Azure representation via a secure MQTT connection, posting JSON document payloads to a set of pre-defined topics. Updates are posted directly to the Azure device, which is then accessed within Azure for further process as defined by the users particular cloud implementation. 
+The actual IoT device communicates with it's Azure representation via a secure MQTT connection, posting JSON document payloads to a set of pre-defined topics. Updates are posted directly to the Azure device, which is then accessed within Azure for further process as defined by the users particular cloud implementation.
 
 ![Azure IoT Overview](images/iot_az_iot_overview.png)
 
 ## Creating a Device in Azure IoT
 
-The following discussion outlines the basic steps taken to create a Device in Azure IoT that the Flux Framework can connect to. 
+The following discussion outlines the basic steps taken to create a Device in Azure IoT that the Flux Framework can connect to.
 
 First step is to log into your Azure account and Select **Internet of Things > IoT Hub** from the menu of services.
 
@@ -131,15 +131,15 @@ The Device ID is obtained from the device detail page. This page is accessible v
 
 ![Azure IoT Device Details](images/iot_az_device_details.png)
 
-### Device Primary Key 
+### Device Primary Key
 
 This is obtained via the Device details page, as outlined in the previous section. Note - you view and copy the key via the icons on the right of the key entry line.
 
 ### Root Certificate Authority - CA file
 
 The Certificate Authority file for Azure is downloaded from this page:
 
-https://learn.microsoft.com/en-us/azure/security/fundamentals/azure-ca-details
+<https://learn.microsoft.com/en-us/azure/security/fundamentals/azure-ca-details>
 
 The file to download is the ***Baltimore CyberTrust Root*** entry in the **Root Certificate Authorities** section of the page.
 
@@ -169,23 +169,23 @@ The above property values must be set on the Flux Azure IoT object before use. T
 
 Once the Flux-based device is configured and running, the Azure IoT capability in Flux posts messages via MQTT to the connected Azure Device via it's IoT Hub. Messages to the device are posted as ***Telemetry Data*** for the device.
 
-The easiest method to view the Telemetry data being sent to an Azure Iot Device is via the Azure IoT Hub extension for the Visual Studio Code editor. 
+The easiest method to view the Telemetry data being sent to an Azure Iot Device is via the Azure IoT Hub extension for the Visual Studio Code editor.
 
 ![Azure IoT Hub Extension](images/iot_az_iot_hub_ext.png)
 
 Once installed, and connected to Azure via the Azure Account extension, you can connect to the target IoT Hub, and monitor telemetry data for a IoT device.
 
 ### Connect to your Azure IoT Hub
 
-On the Explorer pain of Visual Studio Code, click on the **...** menu of the **AZURE IOT HUB** section. In the popup menu, select the **Select IoT Hub** menu entry. 
+On the Explorer pain of Visual Studio Code, click on the **...** menu of the **AZURE IOT HUB** section. In the popup menu, select the **Select IoT Hub** menu entry.
 
 ![Select IoT Hub](images/iot_az_iot_hub_sel.png)
 
 The available IoT Hubs are displayed in the editors command prompt. Select the desired hub and press enter (or click).
 
 ![Select IoT Hub](images/iot_az_iot_hub_sel_menu.png)
 
-The hub is then displayed in the **AZURE IOT HUB** section of the editor Explorer. Expanding the **Devices** section of the Hub will list the example device created above. 
+The hub is then displayed in the **AZURE IOT HUB** section of the editor Explorer. Expanding the **Devices** section of the Hub will list the example device created above.
 
 ![Select IoT Hub](images/iot_az_iot_hub_exp.png)
 
@@ -199,9 +199,8 @@ Once selected, the editor output console will start displaying output for the se
 
 ![Monitor Output](images/iot_az_iot_mon_output.png)
 
-To stop monitoring, click the **Stop Monitoring build-in event endpoint** item that is displayed in the status bar of the editor. 
+To stop monitoring, click the **Stop Monitoring build-in event endpoint** item that is displayed in the status bar of the editor.
 
 ![Stop Monitoring](images/iot_az_iot_stop_mon.png)
 
-A menu option to stop monitoring is also available from the **...** menu of the **AZURE IOT HUB** section in the editor Explorer panel. 
-
+A menu option to stop monitoring is also available from the **...** menu of the **AZURE IOT HUB** section in the editor Explorer panel.
diff --git a/docs/iot_http.md b/docs/iot_http.md
@@ -1,11 +1,11 @@
-# Connecting and Sending Output to an HTTP Server
+# Sending Output to an HTTP Server {#flux-using-iot-http}
 
 One of the key features of the Flux Framework is it's simplified access to IoT service providers and servers. This document outlines how output from a Flux/DataLogger device is sent to an HTTP server.
 
 The following is covered by this document:
 
 * Overview of the HTTP connection
-* How a user configures and uses the HTTP connection 
+* How a user configures and uses the HTTP connection
 * Use examples
 * Development use of the HTTP connection in Flux
 
@@ -19,7 +19,7 @@ HTTP connectivity allows data generated by the DataLogger/Flux framework to be s
 
 Data is sent to the HTTP server as a JSON object, which contains a collection of sub-object. Each sub-object represents a data source in the Flux framework (sensor), and contains the current readings from that source.
 
-The following is an n example of the data posted - note, this representation was "pretty printed" for readability. 
+The following is an n example of the data posted - note, this representation was "pretty printed" for readability.
 
 ```json
 {
@@ -109,7 +109,7 @@ Where:
 
 * `Enabled` - set to true to enable the connection
 * `URL` - Set to the URL for the connection
-* `CA Cert Filename` - set to the cert filename on the SD card if being used. 
+* `CA Cert Filename` - set to the cert filename on the SD card if being used.
 
 ## Example - Connecting to a HTTP Server
 
@@ -130,7 +130,7 @@ var myServer = http.createServer(function (req, res) {
 
   // on data callback, append chunk to our body string
   req.on('data', function(chunk){
-	body += chunk;
+ body += chunk;
   });
 
   // On end callback, output the body to the console
@@ -146,7 +146,7 @@ var myServer = http.createServer(function (req, res) {
 }).listen(8090);
 ```
 
-The setup and use of node js is system dependant is beyond the scope of this document. However, Node JS is easily installed with your systems package manager (`brew` on macOS, Linux distribution package manager (apt, yum, ...etc), on Windows, the WSL is recommended). 
+The setup and use of node js is system dependant is beyond the scope of this document. However, Node JS is easily installed with your systems package manager (`brew` on macOS, Linux distribution package manager (apt, yum, ...etc), on Windows, the WSL is recommended).
 
 Once Node is setup, the above server is run via the following command (assuming the implementation is in a file called `simple_http.js`):
 
@@ -160,8 +160,7 @@ As data is sent by the Flux Application/DataLogger IoT, the following is output
 
 ## Obtaining a Sites Security Certificate
 
-Accessing a sites SSL/Secure Certificate is done via a web browser. The method for each browser is different. The following example uses Edge, which is similar to the operation in Chrome. 
-
+Accessing a sites SSL/Secure Certificate is done via a web browser. The method for each browser is different. The following example uses Edge, which is similar to the operation in Chrome.
 
 First, browse to the desired site/server. Click the Secure/Security area/button next to the URL to bring up the security detail page.
 
@@ -177,7 +176,7 @@ When you select this button, the certificate details dialog is displayed.
 
 ![cert step 3](images/iot_http_cert_3.png)
 
-On this page, select the *Details* tab, and select the *Export...* button on the lower right of the dialog. This will save the sites SSL/Security certificate to a location you specify. 
+On this page, select the *Details* tab, and select the *Export...* button on the lower right of the dialog. This will save the sites SSL/Security certificate to a location you specify.
 
 Once saved, place this file on the SD card your system/DataLogger is using, and set the filename in the HTTP connection menu or settings JSON file.
 
@@ -227,4 +226,3 @@ During the setup of the framework - at initialization, the following steps finis
     // to the HTTP server.
     _fmtJSON.add(_iotHTTP);
 ```
-
diff --git a/docs/iot_mqtt.md b/docs/iot_mqtt.md
@@ -1,4 +1,4 @@
-# Connecting and Publishing Data to MQTT
+# Publishing Data to MQTT {#flux-using-iot-mqtt}
 
 One of the key features of the Flux Framework is it's simplified access to IoT service providers and servers. This document outlines how output from a Flux/DataLogger device is sent to an MQTT Broker.
 
@@ -179,4 +179,3 @@ During the setup of the framework - at initialization, the following steps finis
     // to the MQTT Broker.
     _fmtJSON.add(_mqttClient);
 ```
-
diff --git a/docs/iot_thingspeak.md b/docs/iot_thingspeak.md
diff --git a/docs/parameters.md b/docs/parameters.md
diff --git a/docs/properties.md b/docs/properties.md

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Device Detection and Loading {#device_detection_loading}`
	`1`	`+# I2C Device Detection {#device_detection_loading}`
`2`	`2`
`3`	`3`	`One of the key features of the Flux framework is the ability to automatically detect and load different I2C devices, while placing minimal requirements on the device driver developer.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Devices`
	`1`	`+# Available Devices {#flux-available-devices}`
`2`	`2`
`3`	`3`	`Supported devices are:`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Flux Architecture {#framework_architecture}`
	`2`	`+`
	`3`	`+* @subpage device_detection_loading`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Using Flux on ESP32 {#flux-using-esp32}`
	`2`	`+`
	`3`	`+* @subpage flux-using-esp32-firmware`