Improve specification of interior lights

Signed-off-by: Erik Jaegervall <[email protected]>

spec/Body/Body.vspec

@@ -1,4 +1,5 @@
 #
+# (C) 2023 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
 # (C) 2018 Volvo Cars
 # (C) 2016 Jaguar Land Rover
 #
@@ -58,6 +59,12 @@ Trunk.IsLocked:
   type: actuator
   description: Is trunk locked or unlocked. True = Locked. False = Unlocked.
 
+Trunk.IsLightOn:
+  datatype: boolean
+  type: actuator
+  description: Is trunk light on
+  comment: V4.0 Moved from Vehicle.Cabin.Lights.IsTrunkOn because Trunk is not defined as part of the Cabin.
+
 
 #
 # Horn description

spec/Cabin/Cabin.vspec

@@ -87,12 +87,12 @@ RearviewMirror.DimmingLevel:
 ##
 # Interior lights signals and sensors
 ##
-Lights:
+Light:
   type: branch
-  description: Interior lights signals and sensors.
+  description: Light that is part of the Cabin.
+  comment: V4.0 branch renamed from "Lights" to "Light" to comply with singular naming of entities. Use SingleConfigurableLight.vspec to describe interior lights that can be configured.
+#include InteriorLights.vspec Light
 
-# Include the lights specification and attach it under the Lights branch.x
-#include InteriorLights.vspec Lights
 
 ##
 # Door signals and attributes

spec/Cabin/InteriorLights.vspec

@@ -11,59 +11,55 @@
 # All interior lights and sensors
 #
 
+#
+# Non-configurable lights
+#
 IsGloveBoxOn:
   datatype: boolean
   type: actuator
   description: Is glove box light on
 
-IsTrunkOn:
-  datatype: boolean
-  type: actuator
-  description: Is trunk light light on
-
 IsDomeOn:
   datatype: boolean
   type: actuator
   description: Is central dome light light on
 
-AmbientLight:
+PerceivedAmbientLight:
   datatype: uint8
   type: sensor
   unit: percent
   min: 0
   max: 100
-  description: How much ambient light is detected in cabin. 0 = No ambient light. 100 = Full brightness
-
-LightIntensity:
-  datatype: uint8
-  type: sensor
-  unit: percent
-  min: 0
-  max: 100
-  description: Intensity of the interior lights. 0 = Off. 100 = Full brightness.
+  description: The percentage of ambient light that is measured (e.g., by a sensor) inside the cabin. 0 = No ambient light. 100 = Full brightness.
+  comment: V4.0 named changed from "AmbientLight" to "PerceivedAmbientLight". This is a read-only property that refers to the pre-existing light (e.g., natural light). If you are looking for the in-cabin decorative lights that sometimes are also called "AmbientLights", please refer to the branch Vehicle.Cabin.Light.AmbientLight.
 
 #
-# First / front row lights
+# Configurable lights
 #
 Spotlight:
   type: branch
-  instances: 
+  instances:
     - Row[1,4]
     - ["DriverSide","PassengerSide"]
   description: Spotlight for a specific area in the vehicle.
+#include SingleConfigurableLight.vspec Spotlight
 
-Spotlight.IsSharedOn:
-  datatype: boolean
-  type: sensor
-  description: Is a shared light across a specific row on
 
-Spotlight.IsLeftOn:
-  datatype: boolean
-  type: actuator
-  description: Is light on the left side switched on
+AmbientLight:
+  type: branch
+  instances:
+    - Row[1,2]
+    - ["DriverSide","PassengerSide"]
+  description: Decorative coloured light inside the cabin, usually mounted on the door, cealing, etc.
+#include SingleConfigurableLight.vspec AmbientLight
 
+InteractiveLightBar:
+  type: branch
+  description: Decorative coloured light bar that supports effects. It is usually mounted on the dashboard (e.g., BMW i7 Interactive bar).
+#include SingleConfigurableLight.vspec InteractiveLightBar
 
-Spotlight.IsRightOn:
-  datatype: boolean
+InteractiveLightBar.Effect:
   type: actuator
-  description: Is light on the right side switched on
+  datatype: string
+  description: Light effect selection from a predefined set of allowed values.
+  comment: Default and allowed values are OEM-specific and should be defined accordingly (e.g., with the use of overlays).

spec/Cabin/SingleConfigurableLight.vspec

@@ -0,0 +1,30 @@
+#
+# (C) 2023 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+#
+# All files and artifacts in this repository are licensed under the
+# provisions of the license provided by the LICENSE file in this repository.
+#
+
+#
+# Generic specification for a light whose color and brightness can be configured.
+#
+
+IsLightOn:
+  type: actuator
+  datatype: boolean
+  description: Indicates whether the light is turned on. True = On, False = Off.
+
+Intensity:
+  type: actuator
+  datatype: uint8
+  unit: percent
+  min: 1
+  max: 100
+  description: How much of the maximum possible brightness of the light is used. 1 = Maximum attenuation, 100 = no attenuation (i.e., full brightness).
+  comment: Minimum value cannot be zero as on/off is controlled by the actuator IsLightOn. V4.0 moved from Cabin.Lights.AmbientLight.Intensity to enable individual control of lights via the SingleConfigurableLight.vspec.
+
+Color:
+  type: actuator
+  datatype: string
+  description: Hexadecimal color code represented as a 3-byte RGB (i.e., Red, Green, and Blue) value preceded by a hash symbol "#". Allowed range "#000000" to "#FFFFFF".
+  comment: For example; "#C0C0C0" = Silver, "#FFD700" = Gold, "#000000" = Black, "#FFFFFF" = White, etc.