diff --git a/docs/Logging.md b/docs/Logging.md index ba7c99b..16891b6 100644 --- a/docs/Logging.md +++ b/docs/Logging.md @@ -14,6 +14,8 @@ HomeSpan log messages are typically output directly to the Arduino Serial Monito You can set the *Log Level* in your sketch using the method `homeSpan.setLogLevel(uint8_t level)` as described in the [HomeSpan API Reference](API.md). Level 0 messages are always output; Level 1 messages are only output if the *Log Level* is set to 1 or greater; and Level 2 messages are only output if the *Log Level* is set to to 2. The *Log Level* can also be changed dynamically via the Serial Monitor at any time by typing either the 'L0', 'L1', or 'L2' as described in the [HomeSpan CLI](CLI.md). +You can also completely disable all Serial output messages generated by HomeSpan by setting the *Log Level* to -1, either by typing 'L-1' into the HomeSpan CLI or by calling `homeSpan.setLogLevel(-1)` in your sketch. Disabling all Serial output may be useful in cases where a separate Serial peripheral is being controlled by the ESP32. In such cases you may want to implement a physical switch on your device that automatically sets the Log Level to 0 or -1 so you don't have to recompile your sketch every time you want to enable/disable HomeSpan Log Messages. + ## User-Defined Log Messages You can add your own log messages to any sketch using HomeSpan's **LOG0()**, **LOG1()**, and **LOG2()** macros. Messages created with these macros will be output to the Arduino Serial Monitor according the *Log Level* setting described above. Each **LOGn()** macro (where n=\[0,2\]) is available in two flavors depending on the number of arguments specified: diff --git a/docs/Reference.md b/docs/Reference.md index cbd0677..d4c76e6 100644 --- a/docs/Reference.md +++ b/docs/Reference.md @@ -71,11 +71,12 @@ The following **optional** `homeSpan` methods override various HomeSpan initiali * `void setCommandTimeout(uint16_t nSec)` * sets the duration (in seconds) that the HomeSpan End-User Command Mode, once activated, stays alive before timing out (default=120 seconds) -* `void setLogLevel(uint8_t level)` +* `void setLogLevel(int level)` * sets the logging level for diagnostic messages, where: * 0 = top-level HomeSpan status messages, and any messages output by the user using `Serial.print()` or `Serial.printf()` (default) * 1 = all HomeSpan status messages, and any `LOG1()` messages specified in the sketch by the user * 2 = all HomeSpan status messages plus all HAP communication packets to and from the HomeSpan device, as well as all `LOG1()` and `LOG2()` messages specified in the sketch by the user + * -1 = supresses ALL HomeSpan messages, freeing up the Serial port for other uses * note the log level can also be changed at runtime with the 'L' command via the [HomeSpan CLI](CLI.md) * see [Message Logging](Logging.md) for complete details @@ -204,6 +205,15 @@ The following **optional** `homeSpan` methods enable additional features and pro * example: `homeSpan.processSerialCommand("A");` starts the HomeSpan Setup Access Point * example: `homeSpan.processSerialCommand("Q HUB3");` changes the HomeKit Setup ID for QR Codes to "HUB3" +* `void setSerialInputDisable(boolean val)` + * if *val* is true, disables HomeSpan from reading input from the Serial port + * if *val* is false, re-enables HomeSpan reading input from the Serial port + * useful when the main USB Serial port is needed for reading data from an external Serial peripheral, rather than being used to read input from the Arduino Serial Monitor + + * `boolean getSerialInputDisable()` + * returns *true* if HomeSpan reading from the Serial port is currently disabled + * returns *false* if HomeSpan is operating normally and will read any CLI commands input into the Arduino Serial Monitor + --- The following **optional** `homeSpan` methods provide additional run-time functionality for more advanced use cases: