State management

User state commands reduced to Init() and Off() which request (re)initialisation and turning the device off, respectively. All transitions are managed by the device.

RCUSCC/RCUSCC/RCUSCC.py

@@ -25,7 +25,7 @@ import sys
 import opcua
 import numpy
 
-from wrappers import only_when_on, fault_on_error
+from wrappers import only_in_states, only_when_on, fault_on_error
 from opcua_connection import OPCUAConnection
 
 __all__ = ["RCUSCC", "main"]
@@ -42,6 +42,21 @@ class RCUSCC(Device):
             - Type:'DevULong'
         OPC_Time_Out
             - Type:'DevDouble'
+
+    States are as follows:
+        ON = Device is functional and controls the hardware,
+        OFF = Device is turned off, drops connection to the hardware,
+        FAULT = Device detected an unrecoverable error, and is malfunctional,
+        INIT = Device is initialising.
+
+    The following state transitions are implemented:
+        boot -> INIT:  Device will initialise when it is started,
+        INIT -> ON:    Device will report to be functional when initialisation succeeds
+        INIT -> FAULT: Device will degrade to malfunctional if initialisation fails
+        ON -> FAULT:   Device will degrade to malfunctional if an unrecoverable error is encountered
+        * -> OFF:      Device is turned off. Triggered by the Off() command.
+        FAULT -> INIT: Device is reinitialised to recover from an error. Triggered by the Init() command.
+        OFF -> INIT:   Device is turned on again. Triggered by the Init() command.
     """
     client = 0
     name_space_index = 0
@@ -258,11 +273,11 @@ class RCUSCC(Device):
         self.client = opcua.Client("opc.tcp://{}:{}/".format(self.OPC_Server_Name, self.OPC_Server_Port), self.OPC_Time_Out) # timeout in seconds
 
         # Connect to OPC-UA -- will set ON state on success
-        self.opcua_connection = OPCUAConnection(self.client, self.On, self.Fault, self)
+        self.opcua_connection = OPCUAConnection(self.client, self.On, self._Fault, self)
 
         if not self.opcua_connection.connect():
             # hardware or infra is down -- needs fixing first
-            self.Fault()
+            self._Fault()
             return
 
         # Retrieve and map server attributes
@@ -270,21 +285,13 @@ class RCUSCC(Device):
             self._map_attributes()
         except Exception as e:
             self.error_stream("Could not map server interface: %s", e)
-            self.Fault()
+            self._Fault()
             return
 
         # Start keep-alive
         self.opcua_connection.start()
 
         # Everything went ok -- go online
-        self.On()
-
-    @DebugIt()
-    def On(self):
-        """
-
-        :return:None
-        """
         self.set_state(DevState.ON)
 
 
@@ -432,9 +439,11 @@ class RCUSCC(Device):
 
     @command(
     )
+    @only_in_states([DevState.FAULT, DevState.OFF])
     @DebugIt()
     def Init(self):
         """
+        Command to ask for initialisation of this device. Can only be called in FAULT or OFF state.
 
         :return:None
         """
@@ -446,9 +455,14 @@ class RCUSCC(Device):
     @DebugIt()
     def Off(self):
         """
+        Command to ask for shutdown of this device.
 
         :return:None
         """
+        if self.get_state() == DevState.OFF:
+          # Already off. Don't complain.
+          return
+
         # Turn off
         self.set_state(DevState.OFF)
 
@@ -459,14 +473,13 @@ class RCUSCC(Device):
         self.set_state(DevState.OFF)
 
 
-    @command(
-    )
-    @DebugIt()
-    def Fault(self):
+    def _Fault(self):
         """
         FAULT state is used to indicate our connection with the OPC-UA server is down.
 
-        This device will try to reconnect, and transition to the ON state on success.
+        This device will try to reconnect once, and transition to the ON state on success.
+
+        If reconnecting fails, the user needs to call Init() to retry to restart this device.
 
         :return:None
         """