Added comments for state and state transitions

RCUSCC/RCUSCC/RCUSCC.py

@@ -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,7 +285,7 @@ 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
@@ -428,6 +443,7 @@ class RCUSCC(Device):
     @DebugIt()
     def Init(self):
         """
+        Command to ask for initialisation of this device. Can only be called in FAULT or OFF state.
 
         :return:None
         """
@@ -436,13 +452,17 @@ class RCUSCC(Device):
 
     @command(
     )
-    @only_in_states([DevState.INIT, DevState.ON, DevState.FAULT])
     @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)
 
@@ -453,11 +473,13 @@ class RCUSCC(Device):
         self.set_state(DevState.OFF)
 
 
-    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
         """