state machine docs somewhat OK

Author: VigneshVSV

docs/beginners-guide/articles/state-machine.md

@@ -1,8 +1,7 @@
 [API Reference](../../api-reference/thing/state-machine.md)
 
 Often, certain operations are not allowed during certain conditions, for example,
-one cannot turn ON a motor twice in a row, or one does not wish to change the
-exposure of a camera during video capture (say).
+one cannot turn ON a motor twice in a row, or a measurement device cannot modify a setting change if a measurement is ongoing.
 
 To implement these contraints, a state machine may be used to prevent property writes or
 action invokations in certain states (events are not supported). A `StateMachine` is a class-level
@@ -11,20 +10,20 @@ in these states:
 
 ```py title="Definition" linenums="1"
 --8<-- "docs/beginners-guide/code/fsm/def.py:1:1"
---8<-- "docs/beginners-guide/code/fsm/def.py:12:15"
---8<-- "docs/beginners-guide/code/fsm/def.py:34:36"
---8<-- "docs/beginners-guide/code/fsm/def.py:40:41"
+--8<-- "docs/beginners-guide/code/fsm/def.py:14:15"
+--8<-- "docs/beginners-guide/code/fsm/def.py:30:33"
+--8<-- "docs/beginners-guide/code/fsm/def.py:37:38"
 ```
 
 Specify the machine conditions as keyword arguments to the `state_machine` with properties and actions
 in a list:
 
 ```py title="Specify Properties and Actions" linenums="1"
 --8<-- "docs/beginners-guide/code/fsm/def.py:1:2"
---8<-- "docs/beginners-guide/code/fsm/def.py:12:41"
+--8<-- "docs/beginners-guide/code/fsm/def.py:12:38"
 ```
 
-As expected, one needs to set the `StateMachine` state to indicate state changes:
+One needs to set the `StateMachine` state to indicate state changes:
 
 ```py title="set_state()" linenums="1"
 --8<-- "docs/beginners-guide/code/fsm/def.py:13:15"
@@ -34,22 +33,43 @@ As expected, one needs to set the `StateMachine` state to indicate state changes
 One can also sepcify the allowed state of a property or action directly
 on the corresponding objects:
 
-```py title="Specify State Alternate" linenums="1"
+```py title="Specify State Directly on Object" linenums="1"
 --8<-- "docs/beginners-guide/code/fsm/def.py:13:15"
---8<-- "docs/beginners-guide/code/fsm/def.py:64:"
+--8<-- "docs/beginners-guide/code/fsm/def.py:64:74"
 ```
 
+## State Change Events
+
 State machines also push state change event when the state changes:
 
-```py title="Definition" linenums="1"
+```py title="Definition" linenums="1" hl_lines="7"
+--8<-- "docs/beginners-guide/code/fsm/def.py:13:16"
+--8<-- "docs/beginners-guide/code/fsm/def.py:41:48"
+```
 
+One can suppress state change events by setting:
+
+```python title="suppress state change event"
+self.state_machine.set_state('STATE', push_event=False)
 ```
 
-One can suppress state change events by setting `push_state_change_event=False`.
+```python title="subscription" linenums="1"
+def state_change_cb(event):
+    print(f"State changed to {event.data}")
 
-Lastly, one can also supply callbacks which are executed when entering and exiting certain states,
-irrespective of where or when the state change occured:
+client.observe_property(name="state", callbacks=state_change_cb)
+```
 
-```py title="Definition" linenums="1"
+> One can supply multiple callbacks which may called in series or concurrently (see [Events](events.md#subscription)).
+
+## State Change Callbacks
+
+One can also supply callbacks which are executed when entering and exiting certain states,
+irrespective of where or when the state change occured:
 
+```py title="enter and exit callbacks" linenums="1" hl_lines="21"
+--8<-- "docs/beginners-guide/code/fsm/def.py:13:15"
+--8<-- "docs/beginners-guide/code/fsm/def.py:75:"
 ```
+
+These callbacks are executed after the state change is effected, and are mostly useful when there are state changes at multiple places in the code which need to trigger the same side-effects.

docs/beginners-guide/code/fsm/client.py

@@ -1,7 +1,8 @@
-from hololinked.server import Thing, StateMachine, action, Property
-from hololinked.server.properties import String
+from hololinked.core import Thing, StateMachine, action, Property
+from hololinked.core.properties import String
 from enum import StrEnum
 
+
 class states(StrEnum):
     DISCONNECTED = "DISCONNECTED"
     ON = "ON"
@@ -12,28 +13,24 @@ class states(StrEnum):
 
 class Picoscope(Thing):
     """A PC Oscilloscope from Picotech"""
-    
+
     @action()
-    def connect(self):
-        ...
+    def connect(self): ...
 
     @action()
-    def disconnect(self):
-        ...
+    def disconnect(self): ...
 
     @action()
-    def start_acquisition(self):
-        ... 
+    def start_acquisition(self): ...
 
     @action()
-    def stop_acquisition(self):
-        ...
+    def stop_acquisition(self): ...
 
     serial_number = String()
 
     state_machine = StateMachine(
-        states=['DISCONNECTED', 'ON', 'FAULT', 'ALARM', 'MEASURING'],
-        initial_state='DISCONNECTED',
+        states=["DISCONNECTED", "ON", "FAULT", "ALARM", "MEASURING"],
+        initial_state="DISCONNECTED",
         DISCONNECTED=[connect, serial_number],
         ON=[start_acquisition, disconnect],
         MEASURING=[stop_acquisition],
@@ -47,28 +44,51 @@ def stop_acquisition(self):
         push_state_change_event=True,
         DISCONNECTED=[connect, serial_number],
         ON=[start_acquisition, disconnect],
-        MEASURING=[stop_acquisition]
+        MEASURING=[stop_acquisition],
     )
     # v2
 
     def connect(self):
-        # add connect logic here
-        self.state_machine.set_state('ON')
+        """add connect logic here"""
+        self.state_machine.set_state("ON")
 
     def disconnect(self):
-        # add disconnect logic here
-        self.state_machine.current_state = 'DISCONNECTED'
-        # same as self.state_machine.set_state('DISCONNECTED', 
-        #               push_event=True, skip_callbacks=False)
+        """add disconnect logic here"""
+        self.state_machine.current_state = "DISCONNECTED"
+        # self.state_machine.set_state('DISCONNECTED', push_event=True, skip_callbacks=False)
 
     @action(state=[states.ON])
     def start_acquisition(self):
-        # add start measurement logic
+        """add start measurement logic here"""
         self.state_machine.set_state(states.MEASURING)
 
     @action(state=[states.MEASURING, states.FAULT, states.ALARM])
     def stop_acquisition(self):
-        # add stop measurement logic
+        """add stop measurement logic here"""
         if self.state_machine.state == states.MEASURING:
             self.state_machine.set_state(states.ON)
-        # else allow FAULT or ALARM state to persist 
+        # else allow FAULT or ALARM state to persist to inform the user that something is wrong
+
+    serial_number = String(
+        state=[states.DISCONNECTED], doc="serial number of the device"
+    )  # type: str
+
+    def cancel_polling(self):
+        """add cancel polling logic here"""
+        self._cancel_polling = True
+
+    def polling_loop(self):
+        """add polling logic here"""
+        self._cancel_polling = False
+        while not self._cancel_polling:
+            ...
+
+    state_machine = StateMachine(
+        states=states,
+        initial_state=states.DISCONNECTED,
+        push_state_change_event=True,
+        DISCONNECTED=[connect, serial_number],
+        ON=[start_acquisition, disconnect],
+        MEASURING=[stop_acquisition],
+        on_enter=dict(DISCONNECTED=[cancel_polling]),
+    )

docs/beginners-guide/code/fsm/def.py

@@ -5,26 +5,26 @@
 
 
 class Rect(BaseModel):
-    x : Annotated[int, Field(default=0, ge=0)]
-    y : Annotated[int, Field(default=0, ge=0)]
-    width : Annotated[int, Field(default=0, gt=0)]
+    x: Annotated[int, Field(default=0, ge=0)]
+    y: Annotated[int, Field(default=0, ge=0)]
+    width: Annotated[int, Field(default=0, gt=0)]
     height: Annotated[int, Field(default=0, gt=0)]
 
 
 class UEyeCamera(Thing):
-
     def get_aoi(self) -> Rect:
         """Get current AOI from camera as Rect object (with x, y, width, height)"""
         rect_aoi = ueye.IS_RECT()
-        ret = ueye.is_AOI(self.handle, ueye.IS_AOI_IMAGE_GET_AOI,
-                        rect_aoi, ueye.sizeof(rect_aoi))
+        ret = ueye.is_AOI(
+            self.handle, ueye.IS_AOI_IMAGE_GET_AOI, rect_aoi, ueye.sizeof(rect_aoi)
+        )
         assert return_code_OK(self.handle, ret)
         return Rect(
-                x=rect_aoi.s32X.value,
-                y=rect_aoi.s32Y.value,
-                width=rect_aoi.s32Width.value,
-                height=rect_aoi.s32Height.value
-            )
+            x=rect_aoi.s32X.value,
+            y=rect_aoi.s32Y.value,
+            width=rect_aoi.s32Width.value,
+            height=rect_aoi.s32Height.value,
+        )
 
     def set_aoi(self, value: Rect) -> None:
         """Set camera AOI. Specify as x,y,width,height or a tuple
@@ -35,69 +35,73 @@ def set_aoi(self, value: Rect) -> None:
         rect_aoi.s32Width = ueye.int(value.width)
         rect_aoi.s32Height = ueye.int(value.height)
 
-        ret = ueye.is_AOI(self.handle, ueye.IS_AOI_IMAGE_SET_AOI,
-                             rect_aoi, ueye.sizeof(rect_aoi))
+        ret = ueye.is_AOI(
+            self.handle, ueye.IS_AOI_IMAGE_SET_AOI, rect_aoi, ueye.sizeof(rect_aoi)
+        )
         assert return_code_OK(self.handle, ret)
 
-    AOI = Property(fget=get_aoi, fset=set_aoi, model=Rect,
-                doc="Area of interest within the image",) # type: Rect
+    AOI = Property(
+        fget=get_aoi,
+        fset=set_aoi,
+        model=Rect,
+        doc="Area of interest within the image",
+    )  # type: Rect
 
 
 import ctypes
 from picosdk.ps6000 import ps6000 as ps
 from picosdk.functions import assert_pico_ok
 
 trigger_schema = {
-    'type': 'object',
-    'properties' : {
-        'enabled' : { 'type': 'boolean' },
-        'channel' : { 
-            'type': 'string', 
-            'enum': ['A', 'B', 'C', 'D', 'EXTERNAL', 'AUX'] 
+    "type": "object",
+    "properties": {
+        "enabled": {"type": "boolean"},
+        "channel": {
+            "type": "string",
+            "enum": ["A", "B", "C", "D", "EXTERNAL", "AUX"],
             # include both external and aux for 5000 & 6000 series
             # let the device driver will check if the channel is valid for the series
         },
-        'threshold' : { 'type': 'number' },
-        'adc' : { 'type': 'boolean' },
-        'direction' : { 
-            'type': 'string', 
-            'enum': ['above', 'below', 'rising', 'falling', 'rising_or_falling'] 
+        "threshold": {"type": "number"},
+        "adc": {"type": "boolean"},
+        "direction": {
+            "type": "string",
+            "enum": ["above", "below", "rising", "falling", "rising_or_falling"],
         },
-        'delay' : { 'type': 'integer' },
-        'auto_trigger' : { 
-            'type': 'integer', 
-            'minimum': 0 
-        }
+        "delay": {"type": "integer"},
+        "auto_trigger": {"type": "integer", "minimum": 0},
     },
-    "description" : "Trigger settings for a single channel of the picoscope",
+    "description": "Trigger settings for a single channel of the picoscope",
 }
 
+
 class Picoscope(Thing):
+    trigger = Property(doc="Trigger settings", model=trigger_schema)  # type: dict
 
-    trigger = Property(doc="Trigger settings",
-                    model=trigger_schema) # type: dict
-    
     @trigger.setter
-    def set_trigger(self, value : dict) -> None:
+    def set_trigger(self, value: dict) -> None:
         channel = value["channel"].upper()
         direction = value["direction"].upper()
         enabled = ctypes.c_int16(int(value["enabled"]))
         delay = ctypes.c_int32(value["delay"])
-        direction = ps.PS6000_THRESHOLD_DIRECTION[f'PS6000_{direction}']
-        if channel in ['A', 'B', 'C', 'D']:
-            channel = ps.PS6000_CHANNEL['PS6000_CHANNEL_{}'.format(
-                                        channel)]
+        direction = ps.PS6000_THRESHOLD_DIRECTION[f"PS6000_{direction}"]
+        if channel in ["A", "B", "C", "D"]:
+            channel = ps.PS6000_CHANNEL["PS6000_CHANNEL_{}".format(channel)]
         else:
-            channel = ps.PS6000_CHANNEL['PS6000_TRIGGER_AUX']
+            channel = ps.PS6000_CHANNEL["PS6000_TRIGGER_AUX"]
         if not value["adc"]:
-            if channel in ['A', 'B', 'C', 'D']:
-                threshold = int(threshold * self.max_adc * 1e3
-                            / self.ranges[self.channel_settings[channel]['v_range']])
+            if channel in ["A", "B", "C", "D"]:
+                threshold = int(
+                    threshold
+                    * self.max_adc
+                    * 1e3
+                    / self.ranges[self.channel_settings[channel]["v_range"]]
+                )
             else:
-                threshold = int(self.max_adc/5)
+                threshold = int(self.max_adc / 5)
         threshold = ctypes.c_int16(threshold)
         auto_trigger = ctypes.c_int16(int(auto_trigger))
-        self._status['trigger'] = ps.ps6000SetSimpleTrigger(self._ct_handle,
-                                    enabled, channel, threshold, direction, 
-                                    delay, auto_trigger)
-        assert_pico_ok(self._status['trigger'])
+        self._status["trigger"] = ps.ps6000SetSimpleTrigger(
+            self._ct_handle, enabled, channel, threshold, direction, delay, auto_trigger
+        )
+        assert_pico_ok(self._status["trigger"])