Merge pull request #168 from sparkfun/feature/sdk-documentation

Feature/sdk documentation

Author: gigapod

.gitignore

@@ -0,0 +1,2 @@
+
+docs/html/

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "docs/doxygen/doxygen-awesome-css"]
+	path = docs/doxygen/doxygen-awesome-css
+	url = https://github.com/jothepro/doxygen-awesome-css.git

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
 ```
-
-

docs/ar_autoload.md

@@ -1,4 +1,4 @@
-# Architecture - Device Detection and 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.
 
@@ -18,9 +18,9 @@ The key classes to support this pattern are:
 
 | | |
 |------|-------|
-**Device Driver** | The device specific driver, often implemented based on an existing Arduino Library |
-**Device Builder** | A device specific class that is automatically generated and used by the Framework to detect and instantiate a device
-**Device Factory** | An overall singleton within the system that enables device registration at startup and device discovery, instantiation and initialization at runtime
+|**Device Driver** | The device specific driver, often implemented based on an existing Arduino Library |
+|**Device Builder** | A device specific class that is automatically generated and used by the Framework to detect and instantiate a device |
+|**Device Factory** | An overall singleton within the system that enables device registration at startup and device discovery, instantiation and initialization at runtime|
 
 ### Device Class
 
@@ -36,38 +36,38 @@ The class hierarchy for the Device class is outlined in the following diagram:
 
 The following **static** methods form the device discovery interface:
 
-|||
-|----|---|
-```isConnected()``` | Called with an I2C bus object - should return true of the device is connected
-```connectedConfidence()``` | Returns a confidence level to indicate the accuracy of the ```isConnected()``` algorithm used. Helpful when resolving device address conflicts
-```getDeviceName()``` | Returns the name of the device - should be a static constant
-```getDefaultAddress()``` | Returns the default I2C address for the device. *This method is deprecated*
-```getDefaultAddresses()``` | Returns a list of I2C addresses the device can use. The first address should be the default address for the device. This array is terminated with the value ```kSparkDeviceAddressNull```
+| | |
+|----|----|
+|```isConnected()``` | Called with an I2C bus object - should return true of the device is connected|
+|```connectedConfidence()``` | Returns a confidence level to indicate the accuracy of the ```isConnected()``` algorithm used. Helpful when resolving device address conflicts|
+|```getDeviceName()``` | Returns the name of the device - should be a static constant|
+|```getDefaultAddress()``` | Returns the default I2C address for the device. *This method is deprecated*|
+|```getDefaultAddresses()``` | Returns a list of I2C addresses the device can use. The first address should be the default address for the device. This array is terminated with the value ```kSparkDeviceAddressNull```|
 
 #### Instance Methods
 
 For the startup sequence the following instance methods are important
-|||
+| | |
 |------|--------|
-```onInitialize()``` | Called during the initialization process allowing the performance of the driver specific startup sequence. The Arduino TwoWire (Wire) object is passed in for use by the driver. Note: to get the address to use for the device, the driver calls the ```address()``` method.
-```address()``` | Inherited - this method returns the address for the attached device
-```isInitialized()``` | Returns true of the method ```onInitialized()``` returned true - indicating the driver is initialized.
+|```onInitialize()``` | Called during the initialization process allowing the performance of the driver specific startup sequence. The Arduino TwoWire (Wire) object is passed in for use by the driver. Note: to get the address to use for the device, the driver calls the ```address()``` method.|
+|```address()``` | Inherited - this method returns the address for the attached device|
+|```isInitialized()``` | Returns true of the method ```onInitialized()``` returned true - indicating the driver is initialized.|
 
 ### Device Builder Class
 
 This class provides a common interface for the Factory class to use during the discovery and instantiation phase of device creation. The class is defined as a template, with the only template parameter being the class name of the Driver it represents.
 
 The template definition for the ```DeviceBuilder``` class:
 
-```c++
+```cpp
 template <class DeviceType> class DeviceBuilder : public flxDeviceBuilderI2C
 ```
 
 For the most part, all the methods in this class just wrap the *introspection* methods provided by the underlying Device class it represents. This allows allows the Factory class to work with object instances that bridge calls to the *static* methods of a Device object.
 
 Example of a wrapped method in the ```DeviceBuilder``` template:
 
-```C++
+```cpp
 bool isConnected(flxBusI2C &i2cDriver, uint8_t address)
 {
     return DeviceType::isConnected(i2cDriver, address);
@@ -82,7 +82,7 @@ In the implementation file of each device driver, a static ```global``` instance
 
 The definition of the ```DeviceBuilder``` constructor:
 
-```C++
+```cpp
 DeviceBuilder()
 {
     flxDeviceFactory::get().registerDevice(this);
@@ -95,19 +95,19 @@ The Flux Factory class ```flxDeviceFactory``` is a *singleton*, and globally acc
 
 To register a device driver, a static ```DeviceBuilder``` is added to the drivers implementation file.
 
-```C++
+```cpp
 static DeviceBuilder<kDevice> global_##kDevice##Builder;
 ```
 
 But to make this easier, the following macro is defined.
 
-```C++
+```cpp
 #define flxRegisterDevice(kDevice) static DeviceBuilder<kDevice> global_##kDevice##Builder;
 ```
 
 Using this macro, device registration looks like the following (using the BME280 driver)
 
-```C++
+```cpp
 flxRegisterDevice(flxDevBME280);
 ```
 

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 [email protected]: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
-```
+```