oxy_lc.oxy_lc

  1import minimalmodbus
  2from oxy_lc.utilities.modbus_registers import HoldingRegister, InputRegister
  3from oxy_lc.utilities.conversions import twos_compliment
  4from enum import IntEnum
  5from time import sleep
  6
  7# region Errors
  8
  9class ValueRangeError(Exception):
 10    """Exception raised for value range error scenarios.
 11
 12    Attributes:
 13        message -- explanation of the error
 14    """
 15
 16    def __init__(self, message):
 17        self.message = message
 18        super().__init__(self.message)
 19
 20# endregion
 21
 22
 23class OxyLc(minimalmodbus.Instrument):
 24    """
 25    Main object for OxyLC communication
 26
 27    :param minimalmodbus: Child of minimalmodbus to use all included methods as standard
 28    """
 29
 30    def __init__(self, portname: str, slaveaddress: int = 1):
 31        """
 32        Initialiser for OxyLC communication. This should setup the connection to the device at the required protocol.
 33
 34        :param portname: Portname for the connection. Likely "COM*" on windows or "/dev/ttyUSB*" in Linux
 35        :type portname: str
 36        :param slaveaddress: Slave address of the device. Unless changed by the user this defaults to 1 on new products.
 37        :type slaveaddress: int
 38        """
 39        minimalmodbus.Instrument.__init__(self, portname, slaveaddress)
 40        self.serial.baudrate = 9600
 41
 42    # region enums
 43
 44    class StatusValues(IntEnum):
 45        IDLE = 0
 46        START_UP = 1
 47        OPERATING = 2
 48        SHUT_DOWN = 3
 49        STANDBY = 4
 50
 51    class SensorState(IntEnum):
 52        OFF = 0
 53        ON = 1
 54        STANDBY = 2
 55
 56    class HeaterOptions(IntEnum):
 57        HEATER_4V0 = 0
 58        HEATER_4V2 = 1
 59        HEATER_4V35 = 2
 60        HEATER_4V55 = 3
 61
 62    class SaveAndApply(IntEnum):
 63        IDLE = 0
 64        APPLY = 1
 65
 66    class CalibrationStatus(IntEnum):
 67        IDLE = 0
 68        IN_PROGRESS = 1
 69        COMPLETED = 2
 70
 71    class CalibrationControl(IntEnum):
 72        DEFAULT = 0
 73        ACTIVATE = 1
 74        RESET = 2
 75
 76    class BaudRates(IntEnum):
 77        _2400 = 0
 78        _4800 = 1
 79        _9600 = 2
 80        _19200 = 3
 81        _38400 = 4
 82        _57600 = 5
 83        _115200 = 6
 84
 85    class Parity(IntEnum):
 86        NONE = 0
 87        ODD = 1
 88        EVEN = 2
 89
 90    class StopBits(IntEnum):
 91        _1 = 0
 92        _2 = 1
 93
 94    class RS485ApplyChanges(IntEnum):
 95        IDLE = 0
 96        APPLY = 1
 97
 98    # endregion
 99
100    # region Properties
101
102    @property
103    def o2_average(self) -> float:
104        """
105        Get live sensor reading - O2 Average
106
107        :return: Current averaged O2 reading from the sensor (%)
108        :rtype: float
109        """
110        o2_reading = self.read_register(InputRegister.O2_AVERAGE, functioncode=4)
111        return o2_reading / 100
112
113    @property
114    def o2_raw(self) -> float:
115        """
116        Get live sensor reading - O2 raw
117
118        :return: Current raw O2 reading from the sensor (%)
119        :rtype: float
120        """
121        o2_reading = self.read_register(InputRegister.O2_RAW, functioncode=4)
122        return o2_reading / 100
123
124    @property
125    def asymmetry(self) -> float:
126        """
127        Get live sensor reading - O2 asymmetry
128
129        :return: Current asymmetry of the sensor
130        :rtype: float
131        """
132        asymmetry_reading = self.read_register(InputRegister.ASYMMETRY, functioncode=4)
133        return asymmetry_reading / 1000
134
135    @property
136    def status(self) -> StatusValues:
137        """
138        Get live sensor reading - current device status
139        Returned as Enum from StatusValues
140
141        :return: Current status of the device
142        :rtype: StatusValues
143        """
144        status = self.read_register(InputRegister.SYSTEM_STATUS, functioncode=4)
145        return self.StatusValues(status)
146
147    @property
148    def sensor_state(self) -> SensorState:
149        """
150        Get live sensor reading - Sensor State
151
152        :return: Current state of the sensor
153        :rtype: SensorState
154        """
155        _sensor_state = self.read_register(HoldingRegister.SENSOR_STATE, functioncode=3)
156        return self.SensorState(_sensor_state)
157
158    @sensor_state.setter
159    def sensor_state(self, state: SensorState) -> None:
160        """
161        Set the current state of the sensor
162
163        :param state: State option from Enum SensorState
164        :type state: SensorState
165        """
166        self.write_register(HoldingRegister.SENSOR_STATE, state)
167
168    @property
169    def heater_voltage(self) -> float:
170        """
171        Get sensor setting - heater voltage
172
173        :return: Current set heater voltage of the sensor (Volts)
174        :rtype: float
175        """
176        _heater_Voltage = self.read_register(
177            InputRegister.HEATER_VOLTAGE, functioncode=4
178        )
179        return _heater_Voltage / 100
180
181    @heater_voltage.setter
182    def heater_voltage(self, set_voltage: HeaterOptions) -> None:
183        """
184        Set the current heater voltage for the sensor
185
186        :param state: State option from Enum HeaterOptions
187        :type state: HeaterOptions
188        """
189        self.write_register(HoldingRegister.HEATER_VOLTAGE, set_voltage)
190
191    @property
192    def warnings(self) -> str:
193        """
194        Getting current warnings as a string of bits as received by the sensor
195
196        :return: Warning states as bit string
197        :rtype: str
198        """
199
200        warnings_hex = self.read_register(InputRegister.WARNINGS, functioncode=4)
201        
202        decode_to_bits = f"{warnings_hex:08b}"
203
204        return decode_to_bits
205
206    @property
207    def td_average(self) -> float:
208        """
209        Get live sensor TD average
210
211        :return: TD Average (ms)
212        :rtype: float
213        """
214        td_average = self.read_register(InputRegister.TD_AVERAGE, functioncode=4)
215        return td_average / 10
216
217    @property
218    def td_raw(self) -> float:
219        """
220        Get live sensor TD raw
221
222        :return: TD raw (ms)
223        :rtype: float
224        """
225        td_raw = self.read_register(InputRegister.TD_RAW, functioncode=4)
226        return td_raw / 10
227
228    @property
229    def tp(self) -> float:
230        """
231        Get live sensor TP
232
233        :return: TP (ms)
234        :rtype: float
235        """
236        tp = self.read_register(InputRegister.TP, functioncode=4)
237        return tp / 10
238
239    @property
240    def t1(self) -> float:
241        """
242        Get live sensor T1
243
244        :return: T1 (ms)
245        :rtype: float
246        """
247        t1 = self.read_register(InputRegister.T1, functioncode=4)
248        return t1 / 10
249
250    @property
251    def t2(self) -> float:
252        """
253        Get live sensor T2
254
255        :return: T2 (ms)
256        :rtype: float
257        """
258        t2 = self.read_register(InputRegister.T2, functioncode=4)
259        return t2 / 10
260
261    @property
262    def t4(self) -> float:
263        """
264        Get live sensor T4
265
266        :return: T4 (ms)
267        :rtype: float
268        """
269        t4 = self.read_register(InputRegister.T4, functioncode=4)
270        return t4 / 10
271
272    @property
273    def t5(self) -> float:
274        """
275        Get live sensor T5
276
277        :return: T5 (ms)
278        :rtype: float
279        """
280        t5 = self.read_register(InputRegister.T5, functioncode=4)
281        return t5 / 10
282
283    @property
284    def pp_o2_real(self) -> float:
285        """
286        Get live ppO2 Real
287
288        :return: ppO2 Real
289        :rtype: float
290        """
291        pp_o2 = self.read_register(InputRegister.PPO2_REAL, functioncode=4)
292        return pp_o2 / 10
293
294    @property
295    def pp_o2_raw(self) -> float:
296        """
297        Get live ppO2 raw
298
299        :return: ppO2 raw
300        :rtype: float
301        """
302        pp_o2 = self.read_register(InputRegister.PPO2_RAW, functioncode=4)
303        return pp_o2 / 10
304
305    @property
306    def pressure(self) -> float:
307        """
308        Get live pressure
309
310        :return: pressure (mbar)
311        :rtype: float
312        """
313        _pressure = self.read_register(InputRegister.PRESSURE, functioncode=4)
314        return _pressure
315
316    @property
317    def pressure_sens_temperature(self) -> float:
318        """
319        Get live temperature of the pressure sensor
320
321        :return: temperature (°C)
322        :rtype: float
323        """
324        temp_decimal = self.read_register(
325            InputRegister.PRESSURE_SENS_TEMP, functioncode=4
326        )
327
328        converted_temperature = twos_compliment(temp_decimal, 16)
329
330        return converted_temperature
331
332    @property
333    def calibration_status(self) -> CalibrationStatus:
334        """
335        Get current calibration status of the sensor
336
337        :return: calibration status
338        :rtype: CalibrationStatus
339        """
340        _cal_status = self.read_register(
341            InputRegister.CALIBRATION_STATUS, functioncode=4
342        )
343        return self.CalibrationStatus(_cal_status)
344
345    @property
346    def year_of_manufacture(self) -> int:
347        """
348        Get Year of Manufacture
349
350        :return: Year of Manufacture (YYYY)
351        :rtype: int
352        """
353        _year_of_manufacture = self.read_register(InputRegister.YOM, functioncode=4)
354        return _year_of_manufacture
355
356    @property
357    def day_of_manufacture(self) -> int:
358        """
359        Get Day of Manufacture
360
361        :return: Day of Manufacture (DDD)
362        :rtype: int
363        """
364        _day_of_manufacture = self.read_register(InputRegister.DOM, functioncode=4)
365        return _day_of_manufacture
366
367    @property
368    def serial_number(self) -> int:
369        """
370        Get Serial Number
371
372        :return: Serial Number (XXXXX)
373        :rtype: int
374        """
375        _serial_number = self.read_register(InputRegister.SERIAL_NO, functioncode=4)
376        return _serial_number
377
378    @property
379    def software_revision(self) -> int:
380        """
381        Get Software Revision
382
383        :return: Software Revision (RRR)
384        :rtype: int
385        """
386        _software_revision = self.read_register(
387            InputRegister.SOFTWARE_REV, functioncode=4
388        )
389        return _software_revision
390
391    @property
392    def calibration_value(self) -> float:
393        """
394        Return current calibration value
395        calibration_value defaults to 20.7 on new interface boards.
396
397        :return: calibration (%)
398        :rtype: float
399        """
400        _calibration_value = self.read_register(HoldingRegister.CALIBRATION_PERCENT)
401        return _calibration_value / 100
402
403    @calibration_value.setter
404    def calibration_value(self, value: float) -> None:
405        """
406        Set the calibration value for the sensor.
407        Value is then stored in memory even after power cycle
408
409        :param value: Calibration value between 0% and 100%
410        :type value: float
411        :raises self.ValueRangeError: Value out of range
412        """
413        if (value < 0) or (value > 100):
414            raise ValueRangeError(
415                f"Calibration value {value} out of range. Value Must be between 0 and 100"
416            )
417
418        self.write_register(HoldingRegister.CALIBRATION_PERCENT, int(value * 100))
419
420    @property
421    def calibration_control(self) -> CalibrationControl:
422        """
423        Current Calibration control setting
424
425        :return: calibration control
426        :rtype: CalibrationControl
427        """
428        _calibration_control = self.read_register(HoldingRegister.CALIBRATION_CONTROL)
429        return self.CalibrationControl(_calibration_control)
430
431    @calibration_control.setter
432    def calibration_control(self, control_setting: CalibrationControl) -> None:
433        """
434        Set calibration control
435
436        :param control_setting: Control setting
437        :type control_setting: CalibrationControl
438        """
439        self.write_register(HoldingRegister.CALIBRATION_CONTROL, control_setting)
440
441    @property
442    def device_address(self) -> int:
443        """
444        Get device address
445
446        :return: Address (1-247)
447        :rtype: int
448        """
449        _address = self.read_register(HoldingRegister.ADDRESS)
450        return _address
451
452    @device_address.setter
453    def device_address(self, new_address: int) -> None:
454        """
455        Set new device Address
456
457        :param new_address: between 1 & 247
458        :type new_address: int
459        :raises ValueRangeError: Address out of range
460        """
461        if (new_address < 1) or (new_address > 247):
462            raise ValueRangeError("Address must be between 1 and 247")
463
464        self.write_register(HoldingRegister.ADDRESS, new_address)
465
466    @property
467    def parity(self) -> Parity:
468        """
469        Get device parity
470
471        :return: parity
472        :rtype: Parity
473        """
474        _parity = self.read_register(HoldingRegister.PARITY)
475        return self.Parity(_parity)
476
477    @parity.setter
478    def parity(self, new_parity: Parity) -> None:
479        """
480        Set new device parity
481
482        :param new_parity: new parity from enum
483        :type new_parity: Parity
484        """
485        self.write_register(HoldingRegister.PARITY, new_parity)
486
487    # endregion
488
489    # region Methods
490
491    def turn_on(self):
492        """
493        Turn the sensor On
494        """
495        self.sensor_state = self.SensorState.ON
496
497    def turn_off(self):
498        """
499        Turn the sensor Off
500        """
501        self.sensor_state = self.SensorState.OFF
502
503    def calibrate(self, calibration_value: float | None = None) -> bool:
504        """
505        Calibrate the sensor to the given percent value
506
507        :param calibration_precent: O2 percent for calibration, If None is passed it will use the stored calibration_value.
508                                    calibration_value defaults to 20.7 on new interface boards.
509        :type calibration_precent: float, optional
510        :return: boolean indication of success
511        :rtype: bool
512        """
513        if self.status != self.StatusValues.OPERATING:
514            print("Sensor must be in operation to calibrate")
515            return False
516
517        if calibration_value:
518            try:
519                self.calibration_value = calibration_value
520            except ValueRangeError as e:
521                print(e)
522                return False
523
524        self.calibration_control = self.CalibrationControl.ACTIVATE
525
526        count = 0
527        timeout = 5
528        while (self.calibration_status != self.CalibrationStatus.COMPLETED) and (
529            count != timeout
530        ):
531            sleep(1)
532            count += 1
533
534        self.write_register(
535            HoldingRegister.CALIBRATION_CONTROL, self.CalibrationControl.RESET
536        )
537
538        if count == timeout:
539            print("calibration timeout")
540            return False
541        else:
542            return True
543
544    def clear_error_flags(self) -> None:
545        """
546        Clears error flags on the device
547        """
548        self.write_register(HoldingRegister.CLEAR_FLAGS, 1)
549
550    def set_and_apply_heater_voltage(self, set_voltage: HeaterOptions | None) -> None:
551        """
552        Set the current heater voltage for the sensor
553
554        :param state: State option from Enum HeaterOptions
555        :type state: HeaterOptions
556        """
557        if set_voltage:
558            self.heater_voltage = set_voltage
559
560        # MinimalModbus will throw a NoResonseError when this register is written.
561        # It must be passed or it will crash the program
562        try:
563            self.write_register(
564                HoldingRegister.HEATER_VOLTAGE_SAVE, self.SaveAndApply.APPLY
565            )
566        except minimalmodbus.NoResponseError:
567            sleep(2)
568
569        self.sensor_state = self.SensorState.ON
570
571
572    def display_warnings(self) -> dict[str:bool]:
573        """
574        Reads and decodes the warnings and returns a dictionary with each warning/error with a corresponding boolean showing error state
575
576        :return: Warning states for each of the representative bits (True is error)
577        :rtype: dict[str: bool]
578        """
579        warning_states = {
580            "Pump Error": False,
581            "Heater Voltage Error": False,
582            "Asymmetry Warning": False,
583            "O2 Low Warning": False,
584            "Pressure Sensor Warning": False,
585            "Pressure Sensor Error": False,
586        }
587        warnings_bits = self.warnings
588
589        for count, state in enumerate(warning_states):
590            if warnings_bits[::-1][count] == '1':
591                warning_states[state] = True
592
593        return warning_states
594
595    # endregion