diff --git a/README.md b/README.md index ca7b695..1cd6f21 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ For both scenarios an example is available in the example subfolder of this repo **Note**: Using the cable as USB to I2c bridge will not allow to achieve the same throughput as with the embedded API. -The API of the driver is described on the [documentation page](https://potential-bassoon-5myg4n3.pages.github.io/) of this repository +The API of the driver is described on the [documentation page](https://sensirion.github.io/python-uart-scc1) of this repository ## Getting started diff --git a/docs/api.rst b/docs/api.rst index f6e3528..962cf25 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -4,10 +4,14 @@ API Documentation Protocols: ---------- -.. automodule:: sensirion_uart_scc1.protocols +.. automodule:: sensirion_uart_scc1.protocols.i2c_transceiver :members: :undoc-members: - :exclude-members: __init__ + +.. automodule:: sensirion_uart_scc1.protocols.shdlc_transceiver + :members: + :undoc-members: + Exceptions: ----------- @@ -24,8 +28,7 @@ Scc1ShdlcDevice: Drivers: -------- -.. automodule:: sensirion_uart_scc1.drivers +.. automodule:: sensirion_uart_scc1.drivers.scc1_slf3x :members: :undoc-members: - :exclude-members: __init__ diff --git a/docs/index.rst b/docs/index.rst index 5b9652e..44193cf 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,8 +1,8 @@ Welcome to sensirion_uart_scc1's documentation! -==================================================== +=============================================== This package contains the driver for the -[Sensirion SCC1-USB cable](https://www.sensirion.com/products/catalog/SCC1-USB/). +`Sensirion SCC1-USB cable `_. .. toctree:: diff --git a/sensirion_uart_scc1/drivers/scc1_slf3x.py b/sensirion_uart_scc1/drivers/scc1_slf3x.py index a9a7247..96309d5 100644 --- a/sensirion_uart_scc1/drivers/scc1_slf3x.py +++ b/sensirion_uart_scc1/drivers/scc1_slf3x.py @@ -17,10 +17,16 @@ class Scc1Slf3x: The Scc1 provides features to support the Slf3x liquid flow sensors. This driver accesses the sensor through the API specified by scc1. """ - SENSOR_TYPE = 3 #: Slf3x + SENSOR_TYPE = 3 #: Sensor type for Slf3x START_MEASUREMENT_DELAY_S = 0.015 def __init__(self, device: Scc1ShdlcDevice, liquid_mode: SlfMode = SlfMode.LIQUI_1) -> None: + """ + Initialize object instance. + + :param device: The Scc1 device that provides the access to the sensor. + :param liquid_mode: The liquid that is measured. + """ self._scc1 = device self._liquid_config = SLF_PRODUCT_LIQUI_MAP[SlfProduct.SLF3x] self._serial_number, self._product_id = self._get_serial_number_and_product_id() @@ -32,6 +38,8 @@ def __init__(self, device: Scc1ShdlcDevice, liquid_mode: SlfMode = SlfMode.LIQUI @property def serial_number(self) -> int: """ + Get the serial number + :return: The serial number as integer """ return self._serial_number @@ -39,6 +47,8 @@ def serial_number(self) -> int: @property def product_id(self) -> int: """ + Get the product Id + :return: The product identifier as integer """ return self._product_id @@ -53,7 +63,8 @@ def liquid_mode(self) -> SlfMode: @liquid_mode.setter def liquid_mode(self, mode: SlfMode) -> None: """ - Set liquid measurement mode + Set liquid measurement mode. + :param mode: One of the liquid measurement modes """ if not isinstance(mode, SlfMode): @@ -68,12 +79,16 @@ def liquid_mode(self, mode: SlfMode) -> None: @property def liquid_mode_name(self) -> str: """ + Get the name of the liquid. + :return: Name of current liquid measurement mode """ return self.get_liquid_mode_name(self._liquid_mode) def get_liquid_mode_name(self, mode: SlfMode) -> str: """ + Get the name of the liquid + :param mode: A liquid mode :return: Get name of a specific liquid measurement mode """ @@ -83,6 +98,7 @@ def get_liquid_mode_name(self, mode: SlfMode) -> str: def sampling_interval_ms(self) -> int: """ Sampling interval for synchronous measurement + :return: Current internal sampling interval """ return self._sampling_interval_ms @@ -92,12 +108,15 @@ def sampling_interval_ms(self, interval_ms: int): """ Set sampling interval for continuous measurement This will not be applied while measurement is running + :param interval_ms: The requested measurement interval in milliseconds """ self._sampling_interval_ms = interval_ms def get_serial_number(self) -> int: """ + Get the serial number of the device. + :return: The sensor serial number """ return self._serial_number @@ -106,6 +125,7 @@ def get_flow_unit_and_scale(self, command: Optional[int] = None) -> Optional[Tup """ Get the scale factor, unit and sensor sanity check result of the sensor for the given argument. (only available on some SLF3x sensor products) + :param command: The 16-bit command to read flow unit and scale factor for. If no value is supplied the actual measurement command is used :return: A tuple with (scale_factor, flow_unit), None if command is not supported @@ -123,6 +143,8 @@ def get_last_measurement(self) -> Optional[Tuple[int, int, int]]: """ Read current measurement and starts internal continuous measurement with configured interval, if not already started. + + :return: A tuple with flow, temperature and flag """ data = self._scc1.transceive(0x35, [self.SENSOR_TYPE], 0.01) if not data: @@ -133,6 +155,7 @@ def get_last_measurement(self) -> Optional[Tuple[int, int, int]]: def start_continuous_measurement(self, interval_ms=0) -> None: """ Start a continuous measurement with a give interval. + :param interval_ms: Measurement interval in milliseconds. """ if self._is_measuring: @@ -154,7 +177,8 @@ def stop_continuous_measurement(self) -> None: def read_extended_buffer(self) -> Tuple[int, int, List[Tuple[Any, ...]]]: """ Read out measurement buffer - :return: A tuple with (bytes_remaining, bytes_los, data) + + :return: A tuple with (bytes_remaining, bytes_lost, data) """ data = self._scc1.transceive(0x36, [self.SENSOR_TYPE], 0.01) bytes_lost = int(struct.unpack('>I', data[:4])[0]) diff --git a/sensirion_uart_scc1/protocols/i2c_transceiver.py b/sensirion_uart_scc1/protocols/i2c_transceiver.py index 217dd1f..bfa268e 100644 --- a/sensirion_uart_scc1/protocols/i2c_transceiver.py +++ b/sensirion_uart_scc1/protocols/i2c_transceiver.py @@ -10,19 +10,28 @@ class RxTx(Protocol): @property def tx_data(self) -> Optional[bytes]: - """The byte array with the data to be sent""" + """ + The byte array with the data to be sent + """ @property def rx_length(self) -> Optional[int]: - """ Number of bytes to read + """ + Number of bytes to read """ @property def read_delay(self) -> float: - """Time between writing and reading an i2c command.""" + """ + Time between writing and reading an i2c command. + """ def interpret_response(self, data: Optional[bytes]) -> Optional[Tuple[Any, ...]]: - """Split the byte array from the response into the fields of the command.""" + """Split the byte array from the response into the fields of the command. + + :param data: The byte array that needs to be interpreted. + :return: A tuple with the interpreted data. + """ @runtime_checkable @@ -30,7 +39,8 @@ class I2cTransceiver(Protocol): def execute(self, slave_addr: int, rx_tx: RxTx) -> Tuple[Any, ...]: """ - Compatibility method for driver adapters + Compatibility method for driver adapters. + :param slave_addr: i2c slave address :param rx_tx: Object containing the information to execute the communication with the device :return: interpreted results diff --git a/sensirion_uart_scc1/protocols/shdlc_transceiver.py b/sensirion_uart_scc1/protocols/shdlc_transceiver.py index bca54ab..73f7572 100644 --- a/sensirion_uart_scc1/protocols/shdlc_transceiver.py +++ b/sensirion_uart_scc1/protocols/shdlc_transceiver.py @@ -7,7 +7,8 @@ class ShdlcTransceiver(Protocol): def transceive(self, command: int, data: Union[bytes, Iterable], timeout: float = -1.0) -> Optional[bytes]: - """Wrapper method for legacy shdlc-driver compatibility + """Wrapper method for legacy shdlc-driver compatibility. + :param command: The command to send (one byte) :param data: byte array of the data to send as arguments to the command :param timeout: response timeout in seconds (-1 for using default value) diff --git a/sensirion_uart_scc1/scc1_shdlc_device.py b/sensirion_uart_scc1/scc1_shdlc_device.py index 29bc292..cfe4647 100644 --- a/sensirion_uart_scc1/scc1_shdlc_device.py +++ b/sensirion_uart_scc1/scc1_shdlc_device.py @@ -18,7 +18,12 @@ class Scc1ShdlcDevice(ShdlcDevice): The Scc1 Shdlc device is used to communicate with various sensor using the Sensirion SCC1 sensor cable. """ - def __init__(self, connection: ShdlcConnection, slave_address: int) -> None: + def __init__(self, connection: ShdlcConnection, slave_address: int = 0) -> None: + """Initialize object instance. + + :param connection: The used ShdlcConnection + :param slave_address: The SHDLC slave address that is used by this device. + """ super().__init__(connection, slave_address) self._version = self.get_version() self._serial_number = self.get_serial_number() @@ -48,10 +53,11 @@ def sensor_reset(self) -> None: def transceive(self, command: int, data: Union[bytes, Iterable], timeout: float = -1.0) -> Optional[bytes]: """ Provides a generic way to send shdlc commands. - :param command: The command to send (one byte) - :param data: byte array of the data to send as arguments to the command - :param timeout: response timeout in seconds (-1 for using default value) - :return: The returned data as bytes + + :param command: The command to send (one byte). + :param data: Byte array of the data to send as arguments to the command. + :param timeout: Response timeout in seconds (-1 for using default value). + :return: The returned data as bytes. """ if timeout <= 0.0: timeout = 3.0