diff --git a/examples/Intermediate/6-DimmableLED/6-DimmableLED.ino b/examples/Intermediate/6-DimmableLED/6-DimmableLED.ino new file mode 100644 index 0000000..fdfb7d0 --- /dev/null +++ b/examples/Intermediate/6-DimmableLED/6-DimmableLED.ino @@ -0,0 +1,76 @@ + +//////////////////////////////////////////////////////////// +// // +// HomeSpan: A HomeKit implementation for the ESP32 // +// ------------------------------------------------ // +// // +// Example 6: One working on/off LEDs and one working // +// dimmable LED, both based on the LightBulb // +// Service // +// // +//////////////////////////////////////////////////////////// + + +#include "HomeSpan.h" +#include "DEV_LED.h" + +void setup() { + + // Example 6 changes Example 5 so that LED #2 is now dimmable, instead of just on/off. This requires us to create a new + // derived Service we will name "DEV_DimmableLED" Instead of creating a new file to store this definition, we will simply + // tack it on to the end of the DEV_LED.h file that includes the code we created in Example 5 to control an on/off LED. + // Grouping similar-style Services in one ".h" file makes it easier to organize your custom devices. + + // As usual, all previous comments have been deleted and only new changes from the previous example are shown. + + // NOTE: The Arduino/ESP32 code base does not include the function analogWrite() which is typically used to create a PWM + // output to drive the brightness of an LED. The ESP32 code base itself includes a set of functions to create PWM output + // and the ESP32 chip has built-in PWM functionality specifically for this purpose. There are numerous libraries + // you can download that mimics or reproduces analogWrite() in some form or another. HomeSpan conveniently comes with + // it own version of a wrapper around the ESP32 PWM classes that make it very easy to define PWM "channel," attach a pin, + // and set the PWM level (or duty cycle) from 0-100%. These functions are encapsualted in the PwmPin class, as defined in + // PwmPin.h. We will include this file in our updated DEV_LED.h for use with DEV_DimmableLED. + + Serial.begin(115200); + + homeSpan.begin(Category::Lighting,"HomeSpan LEDs"); + + new SpanAccessory(); + + new Service::AccessoryInformation(); + new Characteristic::Name("LED #1"); + new Characteristic::Manufacturer("HomeSpan"); + new Characteristic::SerialNumber("123-ABC"); + new Characteristic::Model("20mA LED"); + new Characteristic::FirmwareRevision("0.9"); + new Characteristic::Identify(); + + new Service::HAPProtocolInformation(); + new Characteristic::Version("1.1.0"); + + new DEV_LED(16); // create an on/off LED attached to pin 16 (same as in Example 5) + + new SpanAccessory(); + + new Service::AccessoryInformation(); + new Characteristic::Name("LED #2"); + new Characteristic::Manufacturer("HomeSpan"); + new Characteristic::SerialNumber("123-ABC"); + new Characteristic::Model("20mA LED"); + new Characteristic::FirmwareRevision("0.9"); + new Characteristic::Identify(); + + new Service::HAPProtocolInformation(); + new Characteristic::Version("1.1.0"); + + new DEV_DimmableLED(0,17); // NEW! create a dimmable LED attached to pin 17 using PWM channel 0. See new code at end of DEV_LED.h + +} // end of setup() + +////////////////////////////////////// + +void loop(){ + + homeSpan.poll(); + +} // end of loop() diff --git a/examples/Intermediate/6-DimmableLED/DEV_LED.h b/examples/Intermediate/6-DimmableLED/DEV_LED.h new file mode 100644 index 0000000..0b2ce94 --- /dev/null +++ b/examples/Intermediate/6-DimmableLED/DEV_LED.h @@ -0,0 +1,70 @@ + +//////////////////////////////////// +// DEVICE-SPECIFIC LED SERVICES // +//////////////////////////////////// + +#include "PwmPin.h" // NEW! Include this HomeSpan "extra" to create LED-compatible PWM signals on one or more pins + +struct DEV_LED : Service::LightBulb { // ON/OFF LED + + int ledPin; // pin number defined for this LED + SpanCharacteristic *power; // reference to the On Characteristic + + DEV_LED(int ledPin) : Service::LightBulb(){ // constructor() method + + power=new Characteristic::On(); + this->ledPin=ledPin; + pinMode(ledPin,OUTPUT); + + } // end constructor + + StatusCode update(){ // update() method + + digitalWrite(ledPin,power->newValue.BOOL); + + return(StatusCode::OK); // return OK status code + + } // update +}; + +////////////////////////////////// + +// Here's the new code defining DEV_DimmableLED - changes from above are noted in the comments + +struct DEV_DimmableLED : Service::LightBulb { // Dimmable LED + + PwmPin *pwmPin; // NEW! Create reference to PWM Pin instantiated below + int channel; // NEW! Store the PWM channel used for this LED (should be unique for each LED) + SpanCharacteristic *power; // reference to the On Characteristic + SpanCharacteristic *level; // NEW! Create a reference to the Brightness Characteristic instantiated below + + DEV_DimmableLED(int channel, int ledPin) : Service::LightBulb(){ // constructor() method + + power=new Characteristic::On(); + + level=new Characteristic::Brightness(50); // NEW! Instantiate the Brightness Characteristic with an initial value of 50% (same as we did in Example 4) + new SpanRange(5,100,1); // NEW! This sets the range of the Brightness to be from a min of 5%, to a max of 100%, in steps of 1% (different from Example 4 values) + + this->channel=channel; // NEW! Save the channel number (from 0-15) + this->pwmPin=new PwmPin(channel, ledPin); // NEW! Configures the PWM channel and attach the specified ledPin. pinMode() does NOT need to be called. + + } // end constructor + + StatusCode update(){ // update() method + + // Here we set the duty cycle (brightness) of the LED by callng pwmPin with the appropriate channel. + // The second argument should be a number from 0-100 (representing %brightness). HomeKit sets the on/off + // status of the LED ("power") separately from the brightness of the LED ("level"). This means HomeKit can + // request the LED be turned off, but retain the brightness level so that it does not need to be resent if + // the LED is turned back on. Multiplying the newValue of the power Characteristic (as a boolean) with the + // newValue of the Brightness Characteristic (as an int) is a short-hand way of creating the logic to + // determing the PWM level when the LED is off (always zero) or on (whatever the brightness level is). + + pwmPin->set(channel,power->newValue.BOOL*level->newValue.INT); + + return(StatusCode::OK); // return OK status code + + } // update +}; + +////////////////////////////////// diff --git a/src/PwmPin.cpp b/src/PwmPin.cpp new file mode 100644 index 0000000..b32bd89 --- /dev/null +++ b/src/PwmPin.cpp @@ -0,0 +1,32 @@ + +#include "PwmPin.h" +#include + +PwmPin::PwmPin(uint8_t channel, uint8_t pin){ + this->channel=channel & 0x0F; + this->pin=pin; + + ledc_timer_config_t ledTimer; + ledTimer.timer_num=LEDC_TIMER_0; + ledTimer.speed_mode=(this->channel)<8?LEDC_HIGH_SPEED_MODE:LEDC_LOW_SPEED_MODE; + ledTimer.duty_resolution=LEDC_TIMER_10_BIT; + ledTimer.freq_hz=5000; + ledc_timer_config(&ledTimer); + + ledChannel.gpio_num=pin; + ledChannel.speed_mode=(this->channel)<8?LEDC_HIGH_SPEED_MODE:LEDC_LOW_SPEED_MODE; + ledChannel.channel=(ledc_channel_t)(this->channel&0x07); + ledChannel.intr_type=LEDC_INTR_DISABLE; + ledChannel.timer_sel=LEDC_TIMER_0; + ledChannel.duty=0; + ledChannel.hpoint=0; + +} + +void PwmPin::set(uint8_t channel, uint8_t level){ + ledChannel.duty=level*1023; + ledChannel.duty/=100; + ledChannel.duty&=0x03FF; + ledc_channel_config(&ledChannel); + +} diff --git a/src/PwmPin.h b/src/PwmPin.h new file mode 100644 index 0000000..79d26f2 --- /dev/null +++ b/src/PwmPin.h @@ -0,0 +1,21 @@ + +///////////////////////////////////// +// PWM Pin Control // +///////////////////////////////////// + +// A wrapper around the ESP-IDF ledc library to easily set the brightness of an LED from 0-100%. +// Can be used for any device requiring a PWM output (not just an LED). Frequency of PWM +// is hardcoded to 5000 Hz and either High-Speed Timer-0 (for channels 0-7) or Low-Speed Timer-0 +// for channels (8-15) is configured and selected automatically. + +#include + +class PwmPin { + uint8_t channel; + uint8_t pin; + ledc_channel_config_t ledChannel; + + public: + PwmPin(uint8_t channel, uint8_t pin); // assigns pin to be output of one of 16 PWM channels (0-15) + void set(uint8_t channel, uint8_t level); // sets the PWM duty of channel to level (0-100) +};