From 0cdcd488aa0f6603e7ec17be0a3d79b89bedec12 Mon Sep 17 00:00:00 2001 From: Gregg Date: Sun, 19 Jul 2020 07:46:28 -0500 Subject: [PATCH] Completed Example 4 Also added in Fan RotationSpeed and Fan RotationDirection Characteristics. --- .../4-AdvancedCeilingFan.ino | 29 ++++++++++++++++--- src/Services.h | 26 ++++++++++------- 2 files changed, 40 insertions(+), 15 deletions(-) diff --git a/examples/4-AdvancedCeilingFan/4-AdvancedCeilingFan.ino b/examples/4-AdvancedCeilingFan/4-AdvancedCeilingFan.ino index fd12aa5..14fc59a 100644 --- a/examples/4-AdvancedCeilingFan/4-AdvancedCeilingFan.ino +++ b/examples/4-AdvancedCeilingFan/4-AdvancedCeilingFan.ino @@ -14,8 +14,8 @@ void setup() { - // Example 4 expands on Example 3 by adding Characteristics to set fan speed, fan direction, and light brightness. - // For ease of reading, all prior comments have been removed and new comments added to show explicit changes from previous example. + // Example 4 expands on Example 3 by adding Characteristics to set FAN SPEED, FAN DIRECTION, and LIGHT BRIGHTNESS. + // For ease of reading, all prior comments have been removed and new comments added to show explicit changes from the previous example. Serial.begin(115200); @@ -35,11 +35,32 @@ void setup() { new Characteristic::Version("1.1.0"); new Service::LightBulb(); - new Characteristic::On(); - new SpanRange(20,100,5); + new Characteristic::On(true); // NEW: Providing an argument sets its initial value. In this case it means the LightBulb will be turned on at start-up + new Characteristic::Brightness(50); // NEW: This allows control of the Brightness of the LightBulb, with an initial value of 50% upon start-up (Note 1) + new SpanRange(20,100,5); // NEW: This sets the range of the Brightness to be from a min of 20%, to a max of 100%, in steps of 5% (Note 2) new Service::Fan(); new Characteristic::Active(); + new Characteristic::RotationDirection(); // NEW: This allows control of the Rotation Direction of the Fan + new Characteristic::RotationSpeed(25); // NEW: This allows control of the Rotation Speed of the Fan, with an initial value of 25% upon start-up (Note 1) + new SpanRange(25,100,25); // NEW: This sets the range of the Rotation Speed to be from a min of 25%, to a max of 100%, in steps of 25% (Note 2) + + + // NOTE 1: Setting the initial value of the Brightness Characteristic to 50% does not by itself cause HomeKit to turn the light on to 50% upon start-up. + // Rather, this is governed by the initial value of the On Characteristic, which in this case happens to be set to true. If it were set to false, + // or left unspecified (default is false) then the LightBulb will be off at start-up. However, it will jump to 50% brightness as soon as turned on + // for the first time. This same logic applies to the Active and RotationSpeed Characteristics for a Fan. + + // NOTE 2: The default range for Characteristics that support a range of values is specified in the HAP Section 9. For Brightness, the range defaults + // to min=0%, max=100%, step=1%. SpanRange(min,max,step) can be used to over-ride this default. SpanRange is generic and can be used wih other Characteristics + // that support a range of values, such as RotationSpeed. Whenever a new SpanRange is defined it is applied to the most recently defined Characteristic. + // It only has an effect if that Characteristic utilizes ranges. + + // RECOMMENDATION: Using SpanRange to change the minimum Brightness from 0% (the default) to 20% (or any non-zero value) provides for a better + // HomeKit experience. This is because the LightBulb power is controlled by the On Characteristic, and allowing Brightness to be as low as 0% + // sometimes results in HomeKit turning on the LightBulb but with Brightness=0%, which is not very intuitive. This can occur when asking Siri + // to lower the Brightness all the way, and turnign on the LightBulb. By setting a minumum value of 20%, HomeKit always ensures that there is + // some Brightness value whenever the LightBulb is turned on. The same logic applies to other range-enabled Characteristics (such as RotationSpeed). } // end of setup() diff --git a/src/Services.h b/src/Services.h index 6117a5e..6b0a954 100644 --- a/src/Services.h +++ b/src/Services.h @@ -77,31 +77,35 @@ namespace Service { namespace Characteristic { + struct Active : SpanCharacteristic { Active(uint8_t value=0) : SpanCharacteristic{"B0",PR+PW+EV,(uint8_t)value}{} }; + + struct Brightness : SpanCharacteristic { Brightness(int value=0) : SpanCharacteristic{"8",PR+PW+EV,(int)value}{} }; + + struct ColorTemperature : SpanCharacteristic { ColorTemperature(uint32_t value=50) : SpanCharacteristic{"CE",PR+PW+EV,(uint32_t)value}{} }; + struct FirmwareRevision : SpanCharacteristic { FirmwareRevision(char *value) : SpanCharacteristic{"52",PR,(char *)value}{} }; - + + struct Hue : SpanCharacteristic { Hue(double value=0) : SpanCharacteristic{"13",PR+PW+EV,(double)value}{} }; + struct Identify : SpanCharacteristic { Identify() : SpanCharacteristic{"14",PW,(boolean)false}{} }; - + struct Manufacturer : SpanCharacteristic { Manufacturer(char *value) : SpanCharacteristic{"20",PR,(char *)value}{} }; struct Model : SpanCharacteristic { Model(char *value) : SpanCharacteristic{"21",PR,(char *)value}{} }; struct Name : SpanCharacteristic { Name(char *value) : SpanCharacteristic{"23",PR,(char *)value}{} }; - struct SerialNumber : SpanCharacteristic { SerialNumber(char *value) : SpanCharacteristic{"30",PR,(char *)value}{} }; - struct On : SpanCharacteristic { On(boolean value=false) : SpanCharacteristic{"25",PR+PW+EV,(boolean)value}{} }; + + struct OutletInUse : SpanCharacteristic { OutletInUse(boolean value=false) : SpanCharacteristic{"26",PR+EV,(boolean)value}{} }; - struct Active : SpanCharacteristic { Active(uint8_t value=0) : SpanCharacteristic{"B0",PR+PW+EV,(uint8_t)value}{} }; + struct RotationDirection : SpanCharacteristic { RotationDirection(int value=0) : SpanCharacteristic{"28",PR+PW+EV,(int)value}{} }; - struct Brightness : SpanCharacteristic { Brightness(int value=0) : SpanCharacteristic{"8",PR+PW+EV,(int)value}{} }; - - struct Hue : SpanCharacteristic { Hue(double value=0) : SpanCharacteristic{"13",PR+PW+EV,(double)value}{} }; + struct RotationSpeed : SpanCharacteristic { RotationSpeed(double value=0) : SpanCharacteristic{"29",PR+PW+EV,(double)value}{} }; struct Saturation : SpanCharacteristic { Saturation(double value=0) : SpanCharacteristic{"2F",PR+PW+EV,(double)value}{} }; - struct ColorTemperature : SpanCharacteristic { ColorTemperature(uint32_t value=50) : SpanCharacteristic{"CE",PR+PW+EV,(uint32_t)value}{} }; - - struct OutletInUse : SpanCharacteristic { OutletInUse(boolean value=false) : SpanCharacteristic{"26",PR+EV,(boolean)value}{} }; + struct SerialNumber : SpanCharacteristic { SerialNumber(char *value) : SpanCharacteristic{"30",PR,(char *)value}{} }; struct Version : SpanCharacteristic { Version(char *value) : SpanCharacteristic{"37",PR,(char *)value}{} };