Merge branch 'master' of https://github.com/HomeSpan/HomeSpan

docs/Extras.md

@@ -0,0 +1,65 @@
+# HomeSpan Extras
+
+HomeSpan includes integrated access to a number of ESP32 features you'll likely find particularly useful when constructing your HomeSpan devices.
+
+## Pulse Width Modulation (PWM)
+
+PWM on the ESP32 is more flexible, but slighly more complicated, than PWM on most Arduino devices (like the Uno or Mega).  On the ESP32, you use one of 16 built-in timer-channels to create a PWM signal, and then link that channel to any ESP32 pin.  HomeSpan includes a library that makes this very easy, and is accessed as follows:
+
+`#include "extras/PwmPin.h"`
+
+### *PwmPin(uint8_t channel, uint8_t pin)*
+
+Creating an instance of this **class** links one of 16 timer-channels to an ESP32 pin.
+
+* *channel* - the ESP32 timer-channel number (0-15) to generate the PWM signal
+* *pin* - the ESP32 pin that will output the PWM signal produced by the channel
+
+The following methods are supported:
+
+* `void set(uint8_t channel, uint8_t level)`
+
+  * sets the PWM %duty-cycle of timer-channel *channel* (0-15) to *level*, where *level* ranges from 0 (off) to 100 (steady on)
+  
+* `int getPin()`
+
+  * returns the pin number
+  
+PwmPin also includes a static class function that converts Hue/Saturation/Brightness values (typically used by HomeKit) to Red/Green/Blue values (typically used to control multi-color LEDS).
+
+* `static void HSVtoRGB(float h, float s, float v, float *r, float *g, float *b)`
+
+  * *h* - input Hue value, range 0-360
+  * *s* - input Saturation value, range 0-1
+  * *v* - input Brightness value, range 0-1
+  * *r* - output Red value, range 0-1
+  * *g* - output Green value, range 0-1
+  * *b* - output Blue value, range 0-1
+
+See tutorial sketch [#10 (RGB_LED)](../examples/10-RGB_LED) for an example of using PwmPin to control an RGB LED.
+
+## Radio Frequency / Infrared Signal Generation
+
+The ESP32 has an on-chip signal-generator peripheral designed to drive an RF or IR transmitter.  HomeSpan includes an easy-to-use library that interfaces with this peripheral so that with a few additional electronic components you can create a HomeSpan device that controls an RF or IR appliance directly from the Home App on your iPhone, or via Siri.  The library is accessed as follows:
+
+`#include "extras/RFControl.h"`
+
+### *RFControl(int pin)*
+
+Creating an instance of this **class** initializes the RF/IR signal generator and specifies the ESP32 *pin* to output the signal.  You may create more than one instance of this class if driving more than one RF/IR transmitter (each connected to different *pin*).
+
+The following methods are supported:
+
+(to be continued)
+
+
+
+
+
+
+
+
+ 
+---
+
+[↩️](README.md) Back to the Welcome page

docs/HomeKitPrimer.md

@@ -1,3 +1,7 @@
 # HomeKit Primer
 
 *(coming soon)*
+
+---
+
+[↩️](README.md) Back to the Welcome page

docs/README.md

@@ -10,7 +10,7 @@ HomeSpan provides a microcontroller-focused implementation of [Apple's HomeKit A
 * Utilizes a unique *Service-Centric* approach to creating HomeKit devices
 * Takes full advantage of the widely-popular Arduino IDE
 * 100% HAP-R2 compliance
-* 38 integrated [HomeKit Services](ServiceList.md)
+* 38 integrated HomeKit Services
 * Operates in either Accessory or Bridge mode
 
 ### For the HomeSpan Developer
@@ -23,7 +23,7 @@ HomeSpan provides a microcontroller-focused implementation of [Apple's HomeKit A
 * Integrated PWM functionality supporting pulse-wave-modulation on any ESP32 pin
 * Integrated Push Button functionality supporting single, double, and long presses 
 * Integrated access to the ESP32's on-chip Remote Control peripheral for easy generation of IR and RF signals
-* 16 detailed [tutorial-sketches](Tutorials.md) with extensive comments, HomeSpan documentation and tips and tricks
+* 16 detailed tutorial-sketches with extensive comments, HomeSpan documentation and tips and tricks
 
 ### For the HomeSpan End-User
 
@@ -34,7 +34,7 @@ HomeSpan provides a microcontroller-focused implementation of [Apple's HomeKit A
   * Force-unpair the device from HomeKit
   * Perform a Factory Reset
   * Launch the WiFi Access Point
-* A standalone, detailed [End-User Guide](UserGuide.md)
+* A standalone, detailed End-User Guide
 
 # Latest Updates
 
@@ -54,7 +54,8 @@ HomeSpan includes the following documentation:
 * [HomeSpan Accessory Categories](Categories.md) - a list of all HAP Accessory Categories defined by HomeSpan
 * [HomeSpan Command-Line Interface (CLI)](CLI.md) - configure a HomeSpan device's WiFi Credentials, modify its HomeKit Setup Code, monitor and update its status, and access detailed, real-time device diagnostics from the Arduino IDE Serial Monitor
 * [HomeSpan User Guide](UserGuide.md) - turnkey instructions on how to configure an already-programmed HomeSpan device's WiFi Credentials, modify its HomeKit Setup Code, and pair the device to HomeKit.  No computer needed!
-* [HomeSpan API Reference](Reference.md) - a complete guide to the HomeSpan Library API :construction:
+* [HomeSpan API Reference](Reference.md) - a complete guide to the HomeSpan Library API
+* [HomeSpan Extras](Extras.md) - integrated access to the ESP32's on-chip PWM and Remote Control peripherals! :construction:
 
 # External Resources
 

docs/Reference.md

@@ -155,4 +155,6 @@ HomeSpan automatically calls the `button(int pin, int pressType)` method of a Se
   
 HomeSpan will report a warning, but not an error, during initialization if the user had not overridden the virtual button() method for a Service contaning one or more Buttons; triggers of those Buttons will simply ignored.
 
+---
 
+[↩️](README.md) Back to the Welcome page