Basic features

.github/workflows/test.yml

@@ -34,7 +34,7 @@ jobs:
             - name: Verify style with flake8
               run: poetry run flake8
             - name: Run tests
-              run: poetry run pytest
+              run: poetry run pytest -m "not needs_hardware"
             - name: Publish Test Report
               uses: mikepenz/action-junit-report@v4
               if: success() || failure() # always run even if the previous step fails

README.md

@@ -1,2 +1,90 @@
 # python-uart-scc1
-Python driver for Sensirion SCC1-USB Cable
+This repository provides a Python driver for [Sensirion SCC1-USB Cable](https://www.sensirion.com/products/catalog/SCC1-USB/).
+The detailed technical description of the SCC1-USB cable is provided in the [datasheet](https://www.sensirion.com/media/documents/EE77392F/65290BF6/LQ_DS_SCC1-RS485-USB_Datasheet.pdf).
+
+## Feature overview
+
+On one hand the SCC1-USB exposes an API to efficiently use the supported sensors. So far support is only added for the [SLF3x-Sensor family](https://sensirion.com/products/catalog/SLF3C-1300F).
+
+On the other hand the cable can be used as USB to I2c bridge for any Sensirion I2c sensor that can be plugged to the cable.
+
+For both scenarios an example is available in the example subfolder of this repository.
+
+**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
+
+## Getting started
+
+### Installation
+
+It is recommended to use a virtual environment. In any case you can install the package via pip by typing:
+
+```bash
+pip install sensirion-uart-scc1
+```
+
+If you have cloned the repository you can install the package and all it dependencies using [poetry](https://python-poetry.org/).
+
+```bash
+poetry install
+```
+
+### Running the examples
+
+We provide two examples to show two basic usage scenarios of the driver
+
+- **SLF3x Usage**
+  This example does not require any additional dependency. Once the package `sensirion-uart-scc1` is installed the example is run by typing:
+
+  ```bash
+    python ./examples/scc1_slf3x_example/slf3x_usage.py --serial-port <your-com-port>
+  ```
+
+- **USB-I2c-Bridge**
+  This example shows how a public python driver can be used with the SCC1-USB cable. The example uses the public driver `sensirion_i2c_sf06_lf`. Before you run the example you need to install this driver.
+
+  ```bash
+    pip install sensirion_i2c_sf06_lf
+  ```
+
+  After having installed the driver the example is run by typing:
+
+  ```bash
+    python ./examples/scc1_usb_to_i2c/scc1_usb_2_i2c_usage.py --serial-port <your-com-port>
+  ```
+
+## Contributing
+
+You are very welcome to open issues and to create pull requests.
+
+Nevertheless you need to understand that we cannot consider pull request that do not pass the CI-pipeline.
+
+This section explains in short how you can make sure that your contribution passes all the checks of the CI pipeline.
+
+The repository uses poetry for dependency management. It is used in the CI pipeline as well.
+The easiest way to be conformant to our coding style will be to use poetry for your contributions as well. This will allow to test and check your contributions locally before creating pull requests.
+
+### Installing and running tests
+
+For testing some extra dependencies are required that need to be installed.
+
+```bash
+poetry install --with test
+```
+
+The tests (including those that are marked) can be executed by tying:
+
+```bash
+poetry run pytest
+```
+
+**Note**: On github no tests that require hardware can be run. Test cases that rely on attached hardware need to be decorated with `@pytest.mark.needs_hardware`
+
+### Checking code-formatting
+
+Make sure that you code is properly formatted. The CI pipeline will check and fail if this is not the case. To check the code-formatting before pushing to the repository type:
+
+```bash
+poetry run flake8
+```

docs/api.rst

@@ -1,19 +1,31 @@
 API Documentation
 =================
 
-This is an example for auto-documenting code of the module
-<sensirion_package_name>.<my_module>. If you are viewing this in the browser
-click on **View page source** in the upper right corner to see the markup from
-which this page has been generated.
+Protocols:
+----------
 
-Just replace <sensirion_package_name>.<my_module> below with the actual values
-in your project and remove the two dots in the beginning of the same line.
+.. automodule:: sensirion_uart_scc1.protocols
+   :members:
+   :undoc-members:
+   :exclude-members: __init__
+
+Exceptions:
+-----------
+.. automodule:: sensirion_uart_scc1.scc1_exceptions
+   :members:
+   :undoc-members:
 
-You can also auto-document classes, methods and many more. You can find
-additional information on auto-documenation on
-https://www.sphinx-doc.org/en/master/usage/quickstart.html#autodoc
 
+Scc1ShdlcDevice:
+----------------
+.. automodule:: sensirion_uart_scc1.scc1_shdlc_device
+   :members:
+   :undoc-members:
 
-.. .. automodule:: sensirion_uart_scc1.device
+Drivers:
+--------
+.. automodule:: sensirion_uart_scc1.drivers
    :members:
    :undoc-members:
+   :exclude-members: __init__
+

docs/index.rst

@@ -1,12 +1,9 @@
 Welcome to sensirion_uart_scc1's documentation!
 ====================================================
 
-This is the documentation template for sensirion_uart_scc1. If you are
-viewing this in the browser click on **View page source** in the upper right
-corner to see the markup from which this page has been generated.
+This package contains the driver for the
+[Sensirion SCC1-USB cable](https://www.sensirion.com/products/catalog/SCC1-USB/).
 
-Read more on how to document your code (even automatically) on
-https://www.sphinx-doc.org/en/master/usage/quickstart.html#defining-document-structure
 
 .. toctree::
    :maxdepth: 2

examples/scc1_slf3x_example/sfl3x_usage.py

@@ -0,0 +1,29 @@
+import argparse
+
+from sensirion_shdlc_driver import ShdlcSerialPort, ShdlcConnection
+
+from sensirion_uart_scc1.drivers.scc1_slf3x import Scc1Slf3x
+from sensirion_uart_scc1.drivers.slf_common import get_flow_unit_label
+from sensirion_uart_scc1.scc1_shdlc_device import Scc1ShdlcDevice
+
+parser = argparse.ArgumentParser()
+parser.add_argument('--serial-port', '-p', default='COM5')
+args = parser.parse_args()
+
+with ShdlcSerialPort(port=args.serial_port, baudrate=115200) as port:
+    device = Scc1ShdlcDevice(ShdlcConnection(port), slave_address=0)
+    sensor = Scc1Slf3x(device)
+    print("serial_number:", sensor.serial_number)
+    print("product id:", sensor.product_id)
+    print("Flow;\tTemperature;\t Flag")
+    flow_scale, unit = sensor.get_flow_unit_and_scale()
+    sensor.start_continuous_measurement(interval_ms=2)
+    try:
+        for _ in range(1000):
+            remaining, lost, data = sensor.read_extended_buffer()
+            print(f"Remaining bytes {remaining} and {lost}-sample lost")
+            print()
+            for flow, temperature, flag in data:
+                print(f'{flow / flow_scale} {get_flow_unit_label(unit)};\t{temperature / 200} C;\t {flag}')
+    finally:
+        sensor.stop_continuous_measurement()

examples/scc1_usb_to_i2c/scc1_usb_2_i2c_usage.py

@@ -0,0 +1,38 @@
+# -*- coding: utf-8 -*-
+
+import time
+
+from sensirion_driver_adapters.i2c_adapter.i2c_channel import I2cChannel
+from sensirion_i2c_driver import CrcCalculator
+from sensirion_i2c_sf06_lf.commands import InvFlowScaleFactors
+from sensirion_i2c_sf06_lf.device import Sf06LfDevice
+from sensirion_shdlc_driver import ShdlcSerialPort, ShdlcConnection
+
+from sensirion_uart_scc1.scc1_shdlc_device import Scc1ShdlcDevice
+
+with ShdlcSerialPort(port='COM5', baudrate=115200) as port:
+    bridge = Scc1ShdlcDevice(ShdlcConnection(port), slave_address=0)
+
+    channel = I2cChannel(bridge.get_i2c_transceiver(),
+                         slave_address=0x08,
+                         crc=CrcCalculator(8, 0x31, 0xff, 0x0))
+
+    sensor = Sf06LfDevice(channel)
+    try:
+        sensor.stop_continuous_measurement()
+        time.sleep(0.1)
+    except BaseException:
+        ...
+    (product_identifier, serial_number
+     ) = sensor.read_product_identifier()
+    print(f"product_identifier: {product_identifier}; " f"serial_number: {serial_number}; ")
+    sensor.start_h2o_continuous_measurement()
+    for i in range(500):
+        try:
+            time.sleep(0.02)
+            (a_flow, a_temperature, a_signaling_flags
+             ) = sensor.read_measurement_data(InvFlowScaleFactors.SLF3C_1300F)
+            print(f"a_flow: {a_flow}; " f"a_temperature: {a_temperature}; " f"a_signaling_flags: {a_signaling_flags}; ")
+        except BaseException:
+            continue
+    sensor.stop_continuous_measurement()