PSOSPA LED updated (#70)

* Added features:
 - Get channel number for psospa class
 - Added str Literals for colours (hue)
 - Added set all functions for colour and states

* Updated documentation to match changes

* Upversioned 1.2.2 (docs 0.3.1)

Author: JamesPicoTech

README.md

@@ -45,6 +45,6 @@ Current PicoScope support:
 - [pypi-nightly (dev repo)](https://pypi.org/project/pypicosdk-nightly/)
 
 ## Version Control
-pyPicoSDK: 1.2.1
+pyPicoSDK: 1.2.2
 
-Docs: 0.3.0
+Docs: 0.3.1

docs/docs/ref/psospa/led.md

@@ -2,7 +2,7 @@
 
 The LED's on the 3000E are controllable via hue, saturation and brightness. To control them these rules need to be met:
 
-- To control each LED `set_led_states([led], 'on')` must be called first per LED. It is automatically called in `set_led_colours()`.
+- To control each LED `set_led_states([led], 'on')` must be called first per LED. 
 <!-- - For both `set_led_brightness()` and `set_led_colours()`, on of the following commands needs to be ran to apply the settings:
     - `run_block_capture()`
     - `run_streaming()`
@@ -12,12 +12,21 @@ The LED's on the 3000E are controllable via hue, saturation and brightness. To c
 Here is an example of changing Channel A and Channel B to red and green, respectively:
 ```
 import pypicosdk as psdk
+import time
 
 scope = psdk.psospa()
 scope.open_unit()
 
+scope.set_led_states('A', 'on')
 scope.set_led_colours('A', 0, 100)
-scope.set_led_colours('B', 100, 100)
+time.sleep(2)
+# OR 
+scope.set_led_states(['A', 'B', 'C'], ['on', 'on', 'on'])
+scope.set_led_colours(['A', 'B', 'C'], ['red', 'green', 'blue'], [100, 100, 100])
+time.sleep(2)
+# or 
+scope.set_all_led_states('on')
+scope.set_all_led_colours('pink')
 
 input('Waiting for user... ')
 ```
@@ -29,6 +38,7 @@ The LEDs are controlled via the functions below:
         filters:
         - "!.*"
         - "set_led"
+        - "set_all_led"
         - "!_to_"
         - "!^_"
         show_root_toc_entry: false

pypicosdk/constants.py

@@ -948,7 +948,7 @@ class PICO_LED_COLOUR_PROPERTIES(ctypes.Structure):
 class PICO_LED_STATE_PROPERTIES(ctypes.Structure):
     """This structure is used with set_led_states() to define the 
     state for one LED."""
-    _pack_ = 1
+    # _pack_ = 8
     _fields_ = [
         ("led_", ctypes.c_uint32),
         ("state_", ctypes.c_int8),
@@ -957,6 +957,9 @@ class PICO_LED_STATE_PROPERTIES(ctypes.Structure):
 led_state_l = Literal['auto', 'off', 'on']
 led_state_m = {'auto': -1, 'off': 0, 'on': 1}
 
+led_colours_l = Literal['red', 'green', 'blue', 'yellow', 'pink']
+led_colours_m = {'red': 0, 'green': 100, 'blue': 244, 'yellow': 61, 'pink':306}
+
 # Public names exported by :mod:`pypicosdk.constants` for ``import *`` support.
 # This explicit list helps static analyzers like Pylance discover available
 # attributes when the parent package re-exports ``pypicosdk.constants`` using
@@ -1023,6 +1026,8 @@ class PICO_LED_STATE_PROPERTIES(ctypes.Structure):
     'led_channel_m',
     'led_state_l',
     'led_state_m',
+    'led_colours_l',
+    'led_colours_m',
     'range_literal',
     'range_map',
     'resolution_literal',

pypicosdk/psospa.py

@@ -49,6 +49,7 @@ def open_unit(self, serial_number:str=None, resolution:RESOLUTION | resolution_l
         self.resolution = resolution
         self.set_all_channels_off()
         self.min_adc_value, self.max_adc_value =super().get_adc_limits()
+        self.n_channels = self.get_variant_details()['NumberOfAnalogueChannels']
 
         return usb_power_struct
 
@@ -214,7 +215,27 @@ def set_led_brightness(self, brightness:int) -> None:
             brightness,
         )
 
-    def set_led_colours(self, led:led_channel_l, hue:int, saturation:int) -> None:
+    def set_all_led_colours(self, hue:int|led_colours_l, saturation:int=100) -> None:
+        """
+        Sets all LED's on the PicoScope to a single colour
+
+        Args:
+            hue (int | str): Colour as a hue in [0-359] or a 
+                basic colour from the following:
+                ['red', 'green', 'blue', 'yellow', 'pink']
+
+            saturation (int, optional): Saturation of the colour [0-100]. Defaults to 100.
+        """
+        led_list = list(led_channel_m.keys())
+        led_list = led_list[:self.n_channels] + led_list[-2:]
+        self.set_led_colours(led_list, [hue] * len(led_list), [saturation] * len(led_list))
+
+    def set_led_colours(
+            self, 
+            led:led_channel_l | list[led_channel_l], 
+            hue:int | led_colours_l | list[int] | list[led_colours_l], 
+            saturation:int | list[int]
+        ) -> None:
         """Sets the colour of the selected LED using HUE and Saturation
 
         It will not take affect until one of the following 
@@ -225,22 +246,53 @@ def set_led_colours(self, led:led_channel_l, hue:int, saturation:int) -> None:
          - siggen_apply()
 
         Args:
-            led (str): The selected LED. Must be one of these values:
+            led (str|list[str]): The selected LED. Must be one or a list of these values:
                 `'A'`, `'B'`, `'C'`, `'D'`, `'E'`, `'F'`, `'G'`, `'H'`, `'AWG'`, `'AUX'`.
-            hue (int): Hue of the LED, [0-359].
-            saturation (int): Saturation of the LED, [0-100].
+            hue (int|list[int]): Colour as a hue in [0-359] or a 
+                basic colour from the following:
+                ['red', 'green', 'blue', 'yellow', 'pink']
+            saturation (int|list[int]): Saturation of the LED, [0-100].
         """
-        self.set_led_states(led, "on")
-        led = led_channel_m[led]
-        led_struct = PICO_LED_COLOUR_PROPERTIES(led, hue, saturation)
+        # if isinstance(hue, str):
+        #     hue = led_colours_m[hue]
+
+        if not isinstance(led, list):
+            led = [led]
+            hue = [hue]
+            saturation = [saturation]
+        
+        if isinstance(hue[0], str):
+            hue = [led_colours_m[i] for i in hue]
+
+        array_len = len(led)
+        array_struct = (PICO_LED_COLOUR_PROPERTIES * array_len)()
+
+        for i in range(array_len):
+            array_struct[i] = PICO_LED_COLOUR_PROPERTIES(
+                led_channel_m[led[i]],
+                hue[i],
+                saturation[i]
+            )
+
         self._call_attr_function(
             "SetLedColours",
             self.handle,
-            led_struct,
-            1,
+            ctypes.byref(array_struct),
+            array_len,
         )
+    
+    def set_all_led_states(self,state:str|led_state_l):
+        """
+        Sets the state of all LED's on the PicoScope.
 
-    def set_led_states(self, led:str|led_channel_l, state:str|led_state_l):
+        Args:
+            state (str): ['auto', 'on', 'off']
+        """
+        led_list = list(led_channel_m.keys())
+        led_list = led_list[:self.n_channels] + led_list[-2:]
+        self.set_led_states(led_list, [state] * len(led_list))
+
+    def set_led_states(self, led:str|led_channel_l|list[led_channel_l], state:str|led_state_l|list[led_state_l]):
         """
         Sets the state for a selected LED. Between default behaviour (auto),
         on or off.
@@ -250,12 +302,22 @@ def set_led_states(self, led:str|led_channel_l, state:str|led_state_l):
                 `'A'`, `'B'`, `'C'`, `'D'`, `'E'`, `'F'`, `'G'`, `'H'`, `'AWG'`, `'AUX'`.
             state (str): State of selected LED: `'auto'`, `'off'`, `'on'`.
         """
-        led = led_channel_m[led]
-        state = led_state_m[state]
-        struct = PICO_LED_STATE_PROPERTIES(led, state)
+        if not isinstance(led, list):
+            led = [led]
+            state = [state]
+
+        array_len = len(led)
+        array_struct = (PICO_LED_STATE_PROPERTIES * array_len)()
+
+        for i in range(array_len):
+            array_struct[i] = PICO_LED_STATE_PROPERTIES(
+                led_channel_m[led[i]],
+                led_state_m[state[i]]
+            )
+
         self._call_attr_function(
             'SetLedStates',
             self.handle,
-            struct, 
-            1
-        )
+            ctypes.byref(array_struct), 
+            ctypes.c_uint32(array_len)
+        )

pypicosdk/version.py

@@ -1,2 +1,2 @@
 
-VERSION = "1.2.1"
+VERSION = "1.2.2"

version.py

@@ -1,4 +1,4 @@
 # Master version file for all scripts.
 # Update these variables and run a build-tool (which will run version_updater.py)
-docs_version = "0.3.0"
-package_version = "1.2.1"
+docs_version = "0.3.1"
+package_version = "1.2.2"