From 91f6ecb95882f8413a315e3d8a317882b75f5982 Mon Sep 17 00:00:00 2001 From: Gregg Date: Sun, 3 Apr 2022 07:21:43 -0500 Subject: [PATCH] Updated Message Logging Example 9 Added LOG0() and variadic LOG1() messages. Also needed to rename Accessory from "On/Off" to "On-Off" since HomeKit no longer allows "/" characters! --- .../09-MessageLogging/09-MessageLogging.ino | 29 +++++--- examples/09-MessageLogging/DEV_LED.h | 68 ++++++++----------- 2 files changed, 47 insertions(+), 50 deletions(-) diff --git a/examples/09-MessageLogging/09-MessageLogging.ino b/examples/09-MessageLogging/09-MessageLogging.ino index 26f5081..eefb533 100644 --- a/examples/09-MessageLogging/09-MessageLogging.ino +++ b/examples/09-MessageLogging/09-MessageLogging.ino @@ -42,27 +42,36 @@ void setup() { // HomeSpan sends a variety of messages to the Serial Monitor of the Arduino IDE whenever the device is connected - // to a computer. Message output is performed either by the usual Serial.print() function, or by one of two macros, - // LOG1() and LOG2(). These two macros call Serial.print() depending on HomeSpan's Log Level setting. A setting - // of 0 means that LOG1() and LOG2() messages are ignored. A setting of 1 causes HomeSpan to print LOG1() messages - // to the Serial Monitor, but ignores LOG2() message. And a setting of 2 causes HomeSpan to print both LOG1() and - // LOG2() messages. + // to a computer. Message output can be performed either by the usual Serial.print() or Serial.printf() functions, + // or by one of three user macros: LOG0(), LOG1() and LOG2(). These three macros output messages to the Serial Monitor + // depending on HomeSpan's Log Level setting: + + // at a setting of 0, only LOG0() message are output; LOG1() and LOG2() messages are ignored + // at a setting of 1, both LOG0() and LOG1() messages are output; LOG2() messages are ignored + // at a setting of 2, all LOG0(), LOG1(), and LOG2() messages are output // Example 9 illustrates how to add such log messages. The code is identical to Example 8 (without comments), except - // that Serial.print() and LOG1() messages have been added to DEV_LED.h. The Serial.print() messages will always be + // that LOG0() and LOG1() messages have been added to DEV_LED.h. The LOG0() messages will always be // output to the Arduino Serial Monitor. The LOG1() messages will only be output if the Log Level is set to 1 or 2. - // The setLogLevel() method of homeSpan is used to change the log level as follows: + // The setLogLevel() method of homeSpan can used to change the log level as follows: // homeSpan.setLogLevel(0) - sets Log Level to 0 // homeSpan.setLogLevel(1) - sets Log Level to 1 // homeSpan.setLogLevel(2) - sets Log Level to 2 - // The method should be called BEFORE homeSpan.begin() - see below for proper use. + // The method should be called BEFORE homeSpan.begin() - see below for proper use. Note that the Log Level + // can also be changed dynamically during runtime via the HomeSpan CLI by typing 'L0', 'L1', or 'L2' into the Serial Monitor + + // There are two forms of the LOG0(), LOG1(), and LOG2() macros. The first form takes only a single argument and outputs + // messsges using the Serial.print(var) function. This allows you to output any single variable or text message, but does not allow you + // to control the format, or to output more than one variable at a time. The second form take multiple arguments, where the first + // is a standard C++ formatting string, and any remaining arguments are consumed according to the format string. This form + // utilizes the variadic Serial.printf(char *fmt [,var1, var2...]) function. // RECOMMENDATION: Since a HomeSpan ESP32 is meant to be physically connected to real-world devices, you may find // yourself with numerous ESP32s each configured with a different set of Accessories. To aid in identification - // you may want to add Serial.print() statements containing some sort of initialization message to the constructors for + // you may want to add LOG0() statements containing some sort of initialization message to the constructors for // each derived Service, such as DEV_LED. Doing so allows HomeSpan to "report" on its configuration upon start-up. See // DEV_LED for examples. @@ -82,7 +91,7 @@ void setup() { // Defines an ON/OFF LED Accessory attached to pin 16 new SpanAccessory(); - new DEV_Identify("On/Off LED","HomeSpan","123-ABC","20mA LED","0.9",0); + new DEV_Identify("On-Off LED","HomeSpan","123-ABC","20mA LED","0.9",0); new DEV_LED(16); // Defines a Dimmable (PWM-driven) LED Accessory attached to pin 17 diff --git a/examples/09-MessageLogging/DEV_LED.h b/examples/09-MessageLogging/DEV_LED.h index 50ad054..94726e8 100644 --- a/examples/09-MessageLogging/DEV_LED.h +++ b/examples/09-MessageLogging/DEV_LED.h @@ -17,22 +17,23 @@ struct DEV_LED : Service::LightBulb { // ON/OFF LED pinMode(ledPin,OUTPUT); // Here we output log messages when the constructor is initially called. - // We use Serial.print() since to ensure the message is always output - // regardless of the VERBOSITY setting. + // We use LOG0() to ensure the message is always output regardless of the + // LOG Level setting. Note this uses the single-argument form of LOG(), so + // multiple calls are needed to create a complete message - Serial.print("Configuring On/Off LED: Pin="); // initialization message - Serial.print(ledPin); - Serial.print("\n"); + LOG0("Configuring On/Off LED: Pin="); // initialization message + LOG0(ledPin); + LOG0("\n"); } // end constructor boolean update(){ // update() method - // Here we output log messages whenever update() is called, - // which is helpful for debugging purposes if your physical device - // is not functioning as expected. Since it's just for debugging, - // we use LOG1() instead of Serial.print(). Note we can output - // both the current as well as the new power settings. + // Here we output log messages whenever update() is called, which is helpful + // for debugging purposes if your physical device is not functioning as expected. + // Since it's just for debugging, we use LOG1() instead of LOG0(). Note we can + // output both the current as well as the new power settings. We've again + // used the single-argument form of LOG() to create this message LOG1("Updating On/Off LED on pin="); LOG1(ledPin); @@ -64,33 +65,18 @@ struct DEV_DimmableLED : Service::LightBulb { // Dimmable LED level=new Characteristic::Brightness(50); // Brightness Characteristic with an initial value of 50% level->setRange(5,100,1); // sets the range of the Brightness to be from a min of 5%, to a max of 100%, in steps of 1% + // Here we once again output log messages when the constructor is initially called. + // However, this time we use the multi-argument form of LOG() that resembles a + // standard printf() function, which makes for more compact code. + + LOG0("Configuring Dimmable LED: Pin=%d\n",pin); // initialization message + this->ledPin=new LedPin(pin); // configures a PWM LED for output to the specified pin - - // Here we output log messages when the constructor is initially called. - // We use Serial.print() since to ensure the message is always output - // regardless of the VERBOSITY setting. Note that ledPin has a method getPin() - // that retrieves the pin number so you don't need to store it separately. - - Serial.print("Configuring Dimmable LED: Pin="); // initialization message - Serial.print(ledPin->getPin()); - Serial.print("\n"); } // end constructor boolean update(){ // update() method - // Here we output log messages whenever update() is called, - // which is helpful for debugging purposes if your physical device - // is not functioning as expected. Since it's just for debugging, - // we use LOG1() instead of Serial.print(). - - LOG1("Updating Dimmable LED on pin="); - LOG1(ledPin->getPin()); - LOG1(": Current Power="); - LOG1(power->getVal()?"true":"false"); - LOG1(" Current Brightness="); - LOG1(level->getVal()); - // Note that since Dimmable_LED has two updateable Characteristics, // HomeKit may be requesting either or both to be updated. We can // use the "isUpdated" flag of each Characteristic to output a message @@ -98,16 +84,18 @@ struct DEV_DimmableLED : Service::LightBulb { // Dimmable LED // Since update() is called whenever there is an update to at least // one of the Characteristics in a Service, either power, level, or both // will have its "isUpdated" flag set. - - if(power->updated()){ - LOG1(" New Power="); - LOG1(power->getNewVal()?"true":"false"); - } - if(level->updated()){ - LOG1(" New Brightness="); - LOG1(level->getNewVal()); - } + // As above, we use the multi-argument form of LOG() to create the messages + // Note that for DimmableLED, ledPin has a method getPin() that retrieves the + // pin number so you don't need to store it separately. + + LOG1("Updating Dimmable LED on pin=%dL Current Power=%s Current Brightness=%d",ledPin->getPin(),power->getVal()?"true":"false",level->getVal()); + + if(power->updated()) + LOG1(" New Power=%s",power->getNewVal()?"true":"false"); + + if(level->updated()) + LOG1(" New Brightness=%d",level->getNewVal()); LOG1("\n");