Bugfix/lighting-output-internal-process-api (#1086)

* Fixed Lighting_Command to ignore write priority and use its own. 

* Fixed BACnetLightingOperation reserved range.

* Refactor overridden into the lighting command module. Added Overridden status flags API.  Added Lighting Output API to implement a momentary override to the output that is cleared at the next lighting command.  Integrated lighting command overridden behavior into the lighting output object.

* Added Trim_Fade_Time, High_End_Trim, Low_End_Trim, Last_On_Value and Default_On_Value properties to lighting output.
Added TRIM_ACTIVE flag to lighting command. Added Last_On_Value and Default_On_Value to lighting command for restore and toggle.

src/bacnet/basic/object/lo.h

@@ -45,13 +45,47 @@ bool Lighting_Output_Present_Value_Set(
 BACNET_STACK_EXPORT
 bool Lighting_Output_Present_Value_Relinquish(
     uint32_t object_instance, unsigned priority);
-
+BACNET_STACK_EXPORT
+bool Lighting_Output_Present_Value_Relinquish_All(uint32_t object_instance);
 BACNET_STACK_EXPORT
 float Lighting_Output_Relinquish_Default(uint32_t object_instance);
 BACNET_STACK_EXPORT
 bool Lighting_Output_Relinquish_Default_Set(
     uint32_t object_instance, float value);
 
+BACNET_STACK_EXPORT
+float Lighting_Output_Last_On_Value(uint32_t object_instance);
+BACNET_STACK_EXPORT
+bool Lighting_Output_Last_On_Value_Set(uint32_t object_instance, float value);
+BACNET_STACK_EXPORT
+float Lighting_Output_Default_On_Value(uint32_t object_instance);
+BACNET_STACK_EXPORT
+bool Lighting_Output_Default_On_Value_Set(
+    uint32_t object_instance, float value);
+BACNET_STACK_EXPORT
+float Lighting_Output_High_End_Trim(uint32_t object_instance);
+BACNET_STACK_EXPORT
+bool Lighting_Output_High_End_Trim_Set(uint32_t object_instance, float value);
+BACNET_STACK_EXPORT
+float Lighting_Output_Low_End_Trim(uint32_t object_instance);
+BACNET_STACK_EXPORT
+bool Lighting_Output_Low_End_Trim_Set(uint32_t object_instance, float value);
+BACNET_STACK_EXPORT
+uint32_t Lighting_Output_Trim_Fade_Time(uint32_t object_instance);
+BACNET_STACK_EXPORT
+bool Lighting_Output_Trim_Fade_Time_Set(
+    uint32_t object_instance, uint32_t value);
+
+BACNET_STACK_EXPORT
+bool Lighting_Output_Overridden_Set(uint32_t object_instance, float value);
+BACNET_STACK_EXPORT
+bool Lighting_Output_Overridden_Clear(uint32_t object_instance);
+BACNET_STACK_EXPORT
+bool Lighting_Output_Overridden_Status(uint32_t object_instance);
+BACNET_STACK_EXPORT
+bool Lighting_Output_Overridden_Momentary(
+    uint32_t object_instance, float value);
+
 BACNET_STACK_EXPORT
 bool Lighting_Output_Change_Of_Value(uint32_t instance);
 BACNET_STACK_EXPORT

src/bacnet/basic/sys/lighting_command.c

@@ -17,11 +17,11 @@
 
 /**
  * @brief call the lighting command tracking value callbacks
- * @param data - dimmer data
+ * @param data - dimmer data structure
  * @param old_value - value prior to write
  * @param value - value of the write
  */
-static void lighting_command_tracking_value_handler(
+static void lighting_command_tracking_value_notify(
     struct bacnet_lighting_command_data *data, float old_value, float value)
 {
     struct lighting_command_notification *head;
@@ -37,6 +37,7 @@ static void lighting_command_tracking_value_handler(
 
 /**
  * @brief Add a Lighting Command notification callback
+ * @param data - dimmer data structure
  * @param cb - notification callback to be added
  */
 void lighting_command_notification_add(
@@ -59,26 +60,188 @@ void lighting_command_notification_add(
     } while (head);
 }
 
+/**
+ * @brief call the lighting command tracking value callbacks
+ * @param data - dimmer data structure
+ * @param old_value - value prior to write
+ * @param value - value of the write
+ */
+static void lighting_command_timer_notify(
+    struct bacnet_lighting_command_data *data, uint16_t milliseconds)
+{
+    struct lighting_command_timer_notification *head;
+
+    head = &data->Timer_Notification_Head;
+    do {
+        if (head->callback) {
+            head->callback(data, milliseconds);
+        }
+        head = head->next;
+    } while (head);
+}
+
+/**
+ * @brief Add a Lighting Command notification callback
+ * @param data - dimmer data structure
+ * @param cb - notification callback to be added
+ */
+void lighting_command_timer_notfication_add(
+    struct bacnet_lighting_command_data *data,
+    struct lighting_command_timer_notification *notification)
+{
+    struct lighting_command_timer_notification *head;
+
+    head = &data->Timer_Notification_Head;
+    do {
+        if (head->next == notification) {
+            /* already here! */
+            break;
+        } else if (!head->next) {
+            /* first available free node */
+            head->next = notification;
+            break;
+        }
+        head = head->next;
+    } while (head);
+}
+
+/**
+ * @brief Clamps the step increment value
+ * @param step_increment [in] step increment value
+ * @return clamped step increment value
+ */
+float lighting_command_step_increment_clamp(float step_increment)
+{
+    if (isless(step_increment, 0.1f)) {
+        step_increment = 0.1f;
+    }
+    if (isgreater(step_increment, 100.0f)) {
+        step_increment = 100.0f;
+    }
+
+    return step_increment;
+}
+
+/**
+ * @brief Clamp the value within the operating range between low and high
+ *  end trim values.
+ * @details The Operating Range is a subset of the Normalized Range,
+ *  that represents the range of acceptable values for control of the object.
+ *  The Operating Range is defined by the High_End_Trim and Low_End_Trim
+ *  property values. When values are written outside of the Operating Range,
+ *  the Tracking_Value will reflect the actual, clamped normalized light
+ *  output while the Present_Value will reflect the original target value.
+ * @param data - dimmer data structure
+ * @param value the value that will be subject to clamping
+ */
+float lighting_command_operating_range_clamp(
+    struct bacnet_lighting_command_data *data, float value)
+{
+    /* clamp value within trim values, if non-zero */
+    if (isless(value, 1.0f)) {
+        /* jump target to OFF if below normalized min */
+        value = 0.0f;
+    } else if (isgreater(value, data->High_Trim_Value)) {
+        value = data->High_Trim_Value;
+        data->In_Progress = BACNET_LIGHTING_TRIM_ACTIVE;
+    } else if (isless(value, data->Low_Trim_Value)) {
+        value = data->Low_Trim_Value;
+        data->In_Progress = BACNET_LIGHTING_TRIM_ACTIVE;
+    }
+
+    return value;
+}
+
+/**
+ * @brief Clamp the value within the normalized ON range 1% to 100%.
+ * @details The physical output level, or non-normalized range,
+ *  is specified as the linearized percentage (0..100%)
+ *  of the possible light output range with 0.0% being off,
+ *  1.0% being dimmest, and 100.0% being brightest.
+ *  The actual range represents the subset of physical output levels
+ *  defined by Min_Actual_Value and Max_Actual_Value
+ *  (or 1.0 to 100.0% if these properties are not present).
+ *  The normalized range is always 0.0 to 100.0% where
+ *  1.0% = bottom of the actual range and 100.0% = top of the actual range.
+ * @param data - dimmer data structure
+ * @param value [in] value to normalize
+ * @return normalized value within the range defined by Min_Actual_Value
+ *  and Max_Actual_Value
+ */
+float lighting_command_normalized_on_range_clamp(
+    struct bacnet_lighting_command_data *data, float value)
+{
+    /* clamp value within trim values, if non-zero */
+    if (isgreater(value, data->Max_Actual_Value)) {
+        value = data->Max_Actual_Value;
+    } else if (isless(value, data->Min_Actual_Value)) {
+        value = data->Min_Actual_Value;
+    }
+
+    return value;
+}
+
+/**
+ * @brief Normalize the value to the min/max range
+ * @details The physical output level, or non-normalized range,
+ *  is specified as the linearized percentage (0..100%)
+ *  of the possible light output range with 0.0% being off,
+ *  1.0% being dimmest, and 100.0% being brightest.
+ *  The actual range represents the subset of physical output levels
+ *  defined by Min_Actual_Value and Max_Actual_Value
+ *  (or 1.0 to 100.0% if these properties are not present).
+ *  The normalized range is always 0.0 to 100.0% where
+ *  1.0% = bottom of the actual range and 100.0% = top of the actual range.
+ * @param data - dimmer data structure
+ * @param value [in] value to normalize
+ * @return normalized value within the range defined by
+ *  0.0%, Min_Actual_Value, and Max_Actual_Value
+ */
+float lighting_command_normalized_range_clamp(
+    struct bacnet_lighting_command_data *data, float value)
+{
+    float normalized_value;
+
+    /* clamp value within normalized values, if non-zero */
+    if (isless(value, 1.0f)) {
+        /* jump target to OFF if below normalized min */
+        normalized_value = 0.0f;
+    } else if (isgreater(value, data->Max_Actual_Value)) {
+        normalized_value = data->Max_Actual_Value;
+    } else if (isless(value, data->Min_Actual_Value)) {
+        normalized_value = data->Min_Actual_Value;
+    } else {
+        normalized_value = value;
+    }
+
+    return normalized_value;
+}
+
 /**
  * @brief Callback for tracking value updates
- * @param  data - dimmer data
+ * @param data - dimmer data structure
  * @param  old_value - value prior to write
  * @param  value - value of the write
  */
-static void lighting_command_tracking_value_notify(
+static void lighting_command_tracking_value_event(
     struct bacnet_lighting_command_data *data, float old_value, float value)
 {
-    if (!data->Out_Of_Service) {
-        /* clamp value within trim values, if non-zero */
-        if (isless(value, 1.0f)) {
-            /* jump target to OFF if below normalized min */
-            value = 0.0f;
-        } else if (isgreater(value, data->High_Trim_Value)) {
-            value = data->High_Trim_Value;
-        } else if (isless(value, data->Low_Trim_Value)) {
-            value = data->Low_Trim_Value;
+    if (data->Overridden) {
+        value = lighting_command_operating_range_clamp(data, value);
+        if (isgreaterequal(value, 1.0)) {
+            data->Last_On_Value = value;
         }
-        lighting_command_tracking_value_handler(data, old_value, value);
+        lighting_command_tracking_value_notify(data, old_value, value);
+        if (data->Overridden_Momentary) {
+            data->Overridden = false;
+        }
+    } else if (!data->Out_Of_Service) {
+        data->Overridden_Momentary = false;
+        value = lighting_command_operating_range_clamp(data, value);
+        if (isgreaterequal(value, 1.0)) {
+            data->Last_On_Value = value;
+        }
+        lighting_command_tracking_value_notify(data, old_value, value);
     } else {
         debug_printf(
             "Lighting-Command[%lu]-Out-of-Service\n", (unsigned long)data->Key);
@@ -88,7 +251,7 @@ static void lighting_command_tracking_value_notify(
 /**
  * Handles the timing for a single Lighting Output object Fade
  *
- * @param data [in] dimmer data
+ * @param data - dimmer data structure
  * @param milliseconds - number of milliseconds elapsed since previously
  * called.  Works best when called about every 10 milliseconds.
  */
@@ -97,19 +260,11 @@ static void lighting_command_fade_handler(
 {
     float old_value;
     float x1, x2, x3, y1, y3;
-    float target_value, min_value, max_value;
+    float target_value;
 
     old_value = data->Tracking_Value;
-    min_value = data->Min_Actual_Value;
-    max_value = data->Max_Actual_Value;
-    target_value = data->Target_Level;
-    /* clamp target within min/max */
-    if (isgreater(target_value, max_value)) {
-        target_value = max_value;
-    }
-    if (isless(target_value, min_value)) {
-        target_value = min_value;
-    }
+    target_value =
+        lighting_command_normalized_on_range_clamp(data, data->Target_Level);
     if ((milliseconds >= data->Fade_Time) ||
         (!islessgreater(data->Tracking_Value, target_value))) {
         /* stop fading */
@@ -127,8 +282,8 @@ static void lighting_command_fade_handler(
         x1 = 0.0f;
         x2 = (float)milliseconds;
         x3 = (float)data->Fade_Time;
-        if (isless(old_value, min_value)) {
-            y1 = min_value;
+        if (isless(old_value, data->Min_Actual_Value)) {
+            y1 = data->Min_Actual_Value;
         } else {
             y1 = old_value;
         }
@@ -137,7 +292,7 @@ static void lighting_command_fade_handler(
         data->Fade_Time -= milliseconds;
         data->In_Progress = BACNET_LIGHTING_FADE_ACTIVE;
     }
-    lighting_command_tracking_value_notify(
+    lighting_command_tracking_value_event(
         data, old_value, data->Tracking_Value);
 }
 
@@ -153,25 +308,17 @@ static void lighting_command_fade_handler(
  * progress of the ramp. <target-level> shall be clamped to
  * Min_Actual_Value and Max_Actual_Value.
  *
- * @param data [in] dimmer data
+ * @param data - dimmer data structure
  * @param milliseconds - number of milliseconds elapsed
  */
 static void lighting_command_ramp_handler(
     struct bacnet_lighting_command_data *data, uint16_t milliseconds)
 {
-    float old_value, target_value, min_value, max_value, step_value, steps;
+    float old_value, target_value, step_value, steps;
 
     old_value = data->Tracking_Value;
-    min_value = data->Min_Actual_Value;
-    max_value = data->Max_Actual_Value;
-    target_value = data->Target_Level;
-    /* clamp target within min/max, if needed */
-    if (isgreater(target_value, max_value)) {
-        target_value = max_value;
-    }
-    if (isless(target_value, min_value)) {
-        target_value = min_value;
-    }
+    target_value =
+        lighting_command_normalized_on_range_clamp(data, data->Target_Level);
     /* determine the number of steps */
     if (milliseconds <= 1000) {
         /* percent per second */
@@ -213,12 +360,8 @@ static void lighting_command_ramp_handler(
             data->Lighting_Operation = BACNET_LIGHTS_STOP;
         }
         /* clamp target within min/max, if needed */
-        if (isgreater(step_value, max_value)) {
-            step_value = max_value;
-        }
-        if (isless(step_value, min_value)) {
-            step_value = min_value;
-        }
+        step_value =
+            lighting_command_normalized_on_range_clamp(data, step_value);
         if (data->Lighting_Operation == BACNET_LIGHTS_STOP) {
             if (isless(data->Target_Level, 1.0f)) {
                 /* jump target to OFF if below normalized min */
@@ -232,28 +375,10 @@ static void lighting_command_ramp_handler(
             data->In_Progress = BACNET_LIGHTING_RAMP_ACTIVE;
         }
     }
-    lighting_command_tracking_value_notify(
+    lighting_command_tracking_value_event(
         data, old_value, data->Tracking_Value);
 }
 
-/**
- * Clamps the step increment value
- *
- * @param step_increment [in] step increment value
- * @return clamped step increment value
- */
-static float lighting_command_step_increment_clamp(float step_increment)
-{
-    if (isless(step_increment, 0.1f)) {
-        step_increment = 0.1f;
-    }
-    if (isgreater(step_increment, 100.0f)) {
-        step_increment = 100.0f;
-    }
-
-    return step_increment;
-}
-
 /**
  * Updates the object tracking value while stepping
  *
@@ -266,58 +391,22 @@ static float lighting_command_step_increment_clamp(float step_increment)
 static void
 lighting_command_step_up_handler(struct bacnet_lighting_command_data *data)
 {
-    float old_value, target_value, min_value, max_value, step_value;
+    float old_value, target_value, step_value;
 
     old_value = data->Tracking_Value;
-    min_value = data->Min_Actual_Value;
-    max_value = data->Max_Actual_Value;
     step_value = lighting_command_step_increment_clamp(data->Step_Increment);
     /* inhibit ON if the value is already OFF */
-    if (isgreaterequal(old_value, min_value)) {
+    if (isgreaterequal(old_value, data->Min_Actual_Value)) {
         target_value = old_value + step_value;
-        /* clamp target within min/max, if needed */
-        if (isgreater(target_value, max_value)) {
-            target_value = max_value;
-        }
-        if (isless(target_value, min_value)) {
-            target_value = min_value;
-        }
-        data->Tracking_Value = target_value;
+        data->Tracking_Value =
+            lighting_command_normalized_on_range_clamp(data, target_value);
         data->In_Progress = BACNET_LIGHTING_IDLE;
         data->Lighting_Operation = BACNET_LIGHTS_STOP;
-        lighting_command_tracking_value_notify(
+        lighting_command_tracking_value_event(
             data, old_value, data->Tracking_Value);
     }
 }
 
-/**
- * Normalize the value to the min/max range
- * @param value [in] value to normalize
- * @param min_value [in] minimum value
- * @param max_value [in] maximum value
- * @return normalized value
- */
-static float
-lighting_command_normalize_value(float value, float min_value, float max_value)
-{
-    float normalized_value;
-    /* clamp target within min/max, if needed */
-    if (isgreater(value, max_value)) {
-        /* clamp target within max */
-        normalized_value = max_value;
-    } else if (isless(value, 1.0f)) {
-        /* jump target to OFF if below normalized min */
-        normalized_value = 0.0f;
-    } else if (isless(value, min_value)) {
-        /* clamp target within min */
-        normalized_value = min_value;
-    } else {
-        normalized_value = value;
-    }
-
-    return normalized_value;
-}
-
 /**
  * Updates the object tracking value while stepping
  *
@@ -330,30 +419,20 @@ lighting_command_normalize_value(float value, float min_value, float max_value)
 static void
 lighting_command_step_down_handler(struct bacnet_lighting_command_data *data)
 {
-    float old_value, target_value, min_value, max_value, step_value;
+    float old_value, target_value, step_value;
 
     old_value = target_value = data->Tracking_Value;
-    min_value = data->Min_Actual_Value;
-    max_value = data->Max_Actual_Value;
     step_value = lighting_command_step_increment_clamp(data->Step_Increment);
     if (isgreaterequal(target_value, step_value)) {
         target_value -= step_value;
     } else {
-        target_value = 0.0f;
+        target_value = data->Min_Actual_Value;
     }
-    /* clamp target within min/max, if needed */
-    if (isgreater(target_value, max_value)) {
-        /* clamp target within max */
-        target_value = max_value;
-    }
-    if (isless(target_value, min_value)) {
-        /* clamp target within min */
-        target_value = min_value;
-    }
-    data->Tracking_Value = target_value;
+    data->Tracking_Value =
+        lighting_command_normalized_on_range_clamp(data, target_value);
     data->In_Progress = BACNET_LIGHTING_IDLE;
     data->Lighting_Operation = BACNET_LIGHTS_STOP;
-    lighting_command_tracking_value_notify(
+    lighting_command_tracking_value_event(
         data, old_value, data->Tracking_Value);
 }
 
@@ -369,18 +448,16 @@ lighting_command_step_down_handler(struct bacnet_lighting_command_data *data)
 static void
 lighting_command_step_on_handler(struct bacnet_lighting_command_data *data)
 {
-    float old_value, target_value, min_value, max_value, step_value;
+    float old_value, target_value, step_value;
 
     old_value = target_value = data->Tracking_Value;
-    min_value = data->Min_Actual_Value;
-    max_value = data->Max_Actual_Value;
     step_value = lighting_command_step_increment_clamp(data->Step_Increment);
     target_value += step_value;
     data->Tracking_Value =
-        lighting_command_normalize_value(target_value, min_value, max_value);
+        lighting_command_normalized_range_clamp(data, target_value);
     data->In_Progress = BACNET_LIGHTING_IDLE;
     data->Lighting_Operation = BACNET_LIGHTS_STOP;
-    lighting_command_tracking_value_notify(
+    lighting_command_tracking_value_event(
         data, old_value, data->Tracking_Value);
 }
 
@@ -396,11 +473,9 @@ lighting_command_step_on_handler(struct bacnet_lighting_command_data *data)
 static void
 lighting_command_step_off_handler(struct bacnet_lighting_command_data *data)
 {
-    float old_value, target_value, min_value, max_value, step_value;
+    float old_value, target_value, step_value;
 
     old_value = target_value = data->Tracking_Value;
-    min_value = data->Min_Actual_Value;
-    max_value = data->Max_Actual_Value;
     step_value = lighting_command_step_increment_clamp(data->Step_Increment);
     if (isgreaterequal(target_value, step_value)) {
         target_value -= step_value;
@@ -408,10 +483,10 @@ lighting_command_step_off_handler(struct bacnet_lighting_command_data *data)
         target_value = 0.0f;
     }
     data->Tracking_Value =
-        lighting_command_normalize_value(target_value, min_value, max_value);
+        lighting_command_normalized_range_clamp(data, target_value);
     data->In_Progress = BACNET_LIGHTING_IDLE;
     data->Lighting_Operation = BACNET_LIGHTS_STOP;
-    lighting_command_tracking_value_notify(
+    lighting_command_tracking_value_event(
         data, old_value, data->Tracking_Value);
 }
 
@@ -424,18 +499,17 @@ lighting_command_step_off_handler(struct bacnet_lighting_command_data *data)
  * @note The WARN, WARN_RELINQUISH, and WARN_OFF lighting
  * commands, as well as writing one of the special values to the
  * Present_Value property, cause a blink-warn notification
- * to occur at the specified priority. A blink-warn
- * notification is used to warn the occupants that the lights
- * are about to turn off, giving the occupants the opportunity
- * to exit the space or to override the lights for a period of time.
+ * to occur. A blink-warn notification is used to warn the
+ * occupants that the lights are about to turn off, giving
+ * the occupants the opportunity to exit the space or to
+ * override the lights for a period of time.
  *
  * The actual blink-warn notification mechanism shall be a local matter.
  * The physical lights may blink once, multiple times, or
  * repeatedly. They may also go bright, go dim, or signal a notification
  * through some other means. In some circumstances, no blink-warn
  * notification will occur at all. The blink-warn notification
- * shall not be reflected in the priority array or the tracking
- * value.
+ * shall not be reflected in the tracking value.
  *
  * @param data [in] dimmer data
  * @param milliseconds - number of milliseconds elapsed
@@ -443,11 +517,9 @@ lighting_command_step_off_handler(struct bacnet_lighting_command_data *data)
 static void lighting_command_blink_handler(
     struct bacnet_lighting_command_data *data, uint16_t milliseconds)
 {
-    float old_value, target_value, min_value, max_value;
+    float old_value, target_value;
 
     old_value = data->Tracking_Value;
-    min_value = data->Min_Actual_Value;
-    max_value = data->Max_Actual_Value;
     /* detect 'end' operation */
     if (data->Blink.Duration > milliseconds) {
         data->Blink.Duration -= milliseconds;
@@ -494,14 +566,30 @@ static void lighting_command_blink_handler(
             }
         }
     }
-    target_value =
-        lighting_command_normalize_value(target_value, min_value, max_value);
+    target_value = lighting_command_normalized_range_clamp(data, target_value);
     /* note: The blink-warn notifications shall not be reflected
        in the tracking value. */
     if (data->In_Progress == BACNET_LIGHTING_IDLE) {
         data->Tracking_Value = target_value;
     }
-    lighting_command_tracking_value_notify(data, old_value, target_value);
+    lighting_command_tracking_value_event(data, old_value, target_value);
+}
+
+/**
+ * @brief Overrides the current lighting command if overridden is true
+ * @param data [in] dimmer data
+ */
+void lighting_command_override(
+    struct bacnet_lighting_command_data *data, float value)
+{
+    float old_value;
+
+    if (!data) {
+        return;
+    }
+    old_value = data->Tracking_Value;
+    data->Tracking_Value = value;
+    lighting_command_tracking_value_event(data, old_value, value);
 }
 
 /**
@@ -516,6 +604,9 @@ void lighting_command_timer(
     if (!data) {
         return;
     }
+    if (data->Overridden) {
+        data->Lighting_Operation = BACNET_LIGHTS_NONE;
+    }
     switch (data->Lighting_Operation) {
         case BACNET_LIGHTS_NONE:
             data->In_Progress = BACNET_LIGHTING_IDLE;
@@ -546,13 +637,20 @@ void lighting_command_timer(
         case BACNET_LIGHTS_STOP:
             data->In_Progress = BACNET_LIGHTING_IDLE;
             break;
+        case BACNET_LIGHTS_RESTORE_ON:
+        case BACNET_LIGHTS_DEFAULT_ON:
+        case BACNET_LIGHTS_TOGGLE_RESTORE:
+        case BACNET_LIGHTS_TOGGLE_DEFAULT:
+            lighting_command_fade_handler(data, milliseconds);
+            break;
         default:
             break;
     }
+    lighting_command_timer_notify(data, milliseconds);
 }
 
 /**
- * @brief Set the lighting command if the priority is active
+ * @brief Set the lighting command to perform a fade to value operation
  * @param data [in] dimmer data
  * @param value [in] BACnet lighting value
  * @param fade_time [in] BACnet lighting fade time
@@ -586,7 +684,7 @@ void lighting_command_ramp_to(
 }
 
 /**
- * @brief Set the lighting command if the priority is active
+ * @brief Set the lighting command to perform a step increment operation
  * @param data [in] dimmer object instance
  * @param operation [in] BACnet lighting operation
  * @param step_increment [in] BACnet lighting step increment value
@@ -606,7 +704,7 @@ void lighting_command_step(
 }
 
 /**
- * @brief Set the lighting command to blink mode
+ * @brief Set the lighting command to perform a blink operation
  * @param data [in] dimmer object instance
  * @param operation [in] BACnet lighting operation for blink warn
  * @param blink [in] BACnet blink data
@@ -634,7 +732,7 @@ void lighting_command_blink_warn(
 }
 
 /**
- * @brief Set the lighting command if the priority is active
+ * @brief Set the lighting command to perform a stop operation
  * @param object [in] BACnet object instance
  * @param priority [in] BACnet priority array value 1..16
  */
@@ -647,7 +745,7 @@ void lighting_command_stop(struct bacnet_lighting_command_data *data)
 }
 
 /**
- * @brief Set the lighting command if the priority is active
+ * @brief Set the lighting command to perform no operations
  * @param object [in] BACnet object instance
  * @param priority [in] BACnet priority array value 1..16
  */
@@ -659,6 +757,82 @@ void lighting_command_none(struct bacnet_lighting_command_data *data)
     data->Lighting_Operation = BACNET_LIGHTS_NONE;
 }
 
+/**
+ * @brief Set the lighting command to perform a restore-on operation
+ * @param data [in] dimmer data
+ * @param fade_time [in] BACnet lighting fade time
+ */
+void lighting_command_restore_on(
+    struct bacnet_lighting_command_data *data, uint32_t fade_time)
+{
+    if (!data) {
+        return;
+    }
+    data->Fade_Time = fade_time;
+    data->Lighting_Operation = BACNET_LIGHTS_RESTORE_ON;
+    data->Target_Level = data->Last_On_Value;
+}
+
+/**
+ * @brief Set the lighting command to perform a default-on operation
+ * @param data [in] dimmer data
+ * @param fade_time [in] BACnet lighting fade time
+ */
+void lighting_command_default_on(
+    struct bacnet_lighting_command_data *data, uint32_t fade_time)
+{
+    if (!data) {
+        return;
+    }
+    data->Fade_Time = fade_time;
+    data->Lighting_Operation = BACNET_LIGHTS_DEFAULT_ON;
+    data->Target_Level = data->Default_On_Value;
+}
+
+/**
+ * @brief Set the lighting command to perform a toggle restore operation
+ * @param data [in] dimmer data
+ * @param fade_time [in] BACnet lighting fade time
+ */
+void lighting_command_toggle_restore(
+    struct bacnet_lighting_command_data *data, uint32_t fade_time)
+{
+    if (!data) {
+        return;
+    }
+    data->Fade_Time = fade_time;
+    data->Lighting_Operation = BACNET_LIGHTS_TOGGLE_RESTORE;
+    if (isless(data->Tracking_Value, 1.0f)) {
+        /* OFF: write the Last_On_Value */
+        data->Target_Level = data->Last_On_Value;
+    } else {
+        /* not OFF, write 0.0% */
+        data->Target_Level = 0.0f;
+    }
+}
+
+/**
+ * @brief Set the lighting command to perform a toggle default operation
+ * @param data [in] dimmer data
+ * @param fade_time [in] BACnet lighting fade time
+ */
+void lighting_command_toggle_default(
+    struct bacnet_lighting_command_data *data, uint32_t fade_time)
+{
+    if (!data) {
+        return;
+    }
+    data->Fade_Time = fade_time;
+    data->Lighting_Operation = BACNET_LIGHTS_TOGGLE_DEFAULT;
+    if (isless(data->Tracking_Value, 1.0f)) {
+        /* OFF: write the Default_On_Value */
+        data->Target_Level = data->Default_On_Value;
+    } else {
+        /* not OFF, write 0.0% */
+        data->Target_Level = 0.0f;
+    }
+}
+
 void lighting_command_init(struct bacnet_lighting_command_data *data)
 {
     if (!data) {
@@ -666,12 +840,15 @@ void lighting_command_init(struct bacnet_lighting_command_data *data)
     }
     data->Tracking_Value = 0.0f;
     data->Lighting_Operation = BACNET_LIGHTS_NONE;
-    data->In_Progress = BACNET_LIGHTING_IDLE;
+    data->In_Progress = BACNET_LIGHTING_NOT_CONTROLLED;
     data->Out_Of_Service = false;
     data->Min_Actual_Value = 1.0f;
     data->Max_Actual_Value = 100.0f;
     data->Low_Trim_Value = 1.0f;
     data->High_Trim_Value = 100.0f;
+    data->Last_On_Value = 100.0f;
+    data->Default_On_Value = 100.0f;
+    data->Overridden = false;
     data->Blink.On_Value = 100.0f;
     data->Blink.Off_Value = 0.0f;
     data->Blink.End_Value = 0.0f;

src/bacnet/basic/sys/lighting_command.h

@@ -14,6 +14,7 @@
 
 /**
  * @brief Callback for tracking value updates
+ * @param  key - key used to link to specific light
  * @param  old_value - value prior to write
  * @param  value - value of the write
  */
@@ -25,6 +26,21 @@ struct lighting_command_notification {
     lighting_command_tracking_value_callback callback;
 };
 
+/* forward prototype of the structure defined later */
+struct bacnet_lighting_command_data;
+
+/**
+ * @brief Callback for non-standard Lighting_Operation timer values
+ * @param  data - Lighting Command data structure
+ * @param  milliseconds - elapsed time in milliseconds
+ */
+typedef void (*lighting_command_timer_callback)(
+    struct bacnet_lighting_command_data *data, uint16_t milliseconds);
+struct lighting_command_timer_notification {
+    struct lighting_command_timer_notification *next;
+    lighting_command_timer_callback callback;
+};
+
 typedef struct bacnet_lighting_command_warn_data {
     /* warn */
     float On_Value;
@@ -51,12 +67,17 @@ typedef struct bacnet_lighting_command_data {
     float Max_Actual_Value;
     float High_Trim_Value;
     float Low_Trim_Value;
+    float Default_On_Value;
+    float Last_On_Value;
     BACNET_LIGHTING_COMMAND_WARN_DATA Blink;
     /* bits - in common area of structure */
     bool Out_Of_Service : 1;
+    bool Overridden : 1;
+    bool Overridden_Momentary : 1;
     /* key used with callback */
     uint32_t Key;
     struct lighting_command_notification Notification_Head;
+    struct lighting_command_timer_notification Timer_Notification_Head;
 } BACNET_LIGHTING_COMMAND_DATA;
 
 #ifdef __cplusplus
@@ -86,12 +107,45 @@ BACNET_STACK_EXPORT
 void lighting_command_stop(struct bacnet_lighting_command_data *data);
 BACNET_STACK_EXPORT
 void lighting_command_none(struct bacnet_lighting_command_data *data);
+BACNET_STACK_EXPORT
+void lighting_command_restore_on(
+    struct bacnet_lighting_command_data *data, uint32_t fade_time);
+BACNET_STACK_EXPORT
+void lighting_command_default_on(
+    struct bacnet_lighting_command_data *data, uint32_t fade_time);
+BACNET_STACK_EXPORT
+void lighting_command_toggle_restore(
+    struct bacnet_lighting_command_data *data, uint32_t fade_time);
+BACNET_STACK_EXPORT
+void lighting_command_toggle_default(
+    struct bacnet_lighting_command_data *data, uint32_t fade_time);
+
+BACNET_STACK_EXPORT
+void lighting_command_override(
+    struct bacnet_lighting_command_data *data, float value);
+
+BACNET_STACK_EXPORT
+float lighting_command_step_increment_clamp(float step_increment);
+BACNET_STACK_EXPORT
+float lighting_command_operating_range_clamp(
+    struct bacnet_lighting_command_data *data, float value);
+BACNET_STACK_EXPORT
+float lighting_command_normalized_range_clamp(
+    struct bacnet_lighting_command_data *data, float value);
+BACNET_STACK_EXPORT
+float lighting_command_normalized_on_range_clamp(
+    struct bacnet_lighting_command_data *data, float value);
+
 BACNET_STACK_EXPORT
 void lighting_command_init(struct bacnet_lighting_command_data *data);
 BACNET_STACK_EXPORT
 void lighting_command_notification_add(
     struct bacnet_lighting_command_data *data,
     struct lighting_command_notification *notification);
+BACNET_STACK_EXPORT
+void lighting_command_timer_notfication_add(
+    struct bacnet_lighting_command_data *data,
+    struct lighting_command_timer_notification *notification);
 
 #ifdef __cplusplus
 }