From a9dc67609c7b127b92f0c10fc8b1046ffba7bc63 Mon Sep 17 00:00:00 2001 From: Rolf Laich Date: Tue, 15 Sep 2026 17:23:15 +0200 Subject: [PATCH 1/2] Generate STCC4 driver from STCC4 model version 3.5.1 --- README.md | 22 ++----------- ci/checkin_doc.sh | 26 ---------------- ci/set_git_config.sh | 16 ---------- docs/build-documentation.rst | 3 +- docs/conf.py | 3 ++ docs/contributing.rst | 25 +++++++++++++++ docs/dev-setup.rst | 45 +++++++++++++++++++++++++++ docs/development.rst | 4 +++ docs/driver-installation.rst | 37 ++++++++++++++++++++++ docs/execute-measurements.rst | 58 ++++++++++++++++++++--------------- docs/index.rst | 1 + docs/installation.rst | 9 ++---- docs/quickstart.rst | 4 +++ docs/requirements.txt | 1 + docs/run-tests.rst | 5 +-- metadata.yml | 14 ++++----- pyproject.toml | 7 +++-- 17 files changed, 173 insertions(+), 107 deletions(-) delete mode 100644 ci/checkin_doc.sh delete mode 100644 ci/set_git_config.sh create mode 100644 docs/contributing.rst create mode 100644 docs/dev-setup.rst create mode 100644 docs/driver-installation.rst diff --git a/README.md b/README.md index 8ac9384..566e4bf 100644 --- a/README.md +++ b/README.md @@ -15,8 +15,7 @@ The STCC4 is Sensirion's next generation miniature CO2 sensor for indoor air qua The default I²C address of [STCC4](https://sensirion.com/products/catalog/STCC4) is **0x64**. -> [!NOTE] -> The SEK-STCC4 board from Sensirion includes a STCC4 and a SHT4x for temperature and humidity compensation, which is controlled by the STCC4 through the integrated I2C controller interface. The provided examples are designed considering this sensor configuration. + ## Connect the sensor @@ -43,27 +42,12 @@ For special setups you find the sensor pinout in the section below. ## Documentation & Quickstart See the [documentation page](https://sensirion.github.io/python-i2c-stcc4) for an API description and a -[quickstart](https://sensirion.github.io/python-i2c-stcc4/execute-measurements.html) example. +[quickstart](https://sensirion.github.io/python-i2c-stcc4/quickstart.html) example. ## Contributing -### Check coding style - -The coding style can be checked with [`flake8`](http://flake8.pycqa.org/): - -```bash -pip install -e .[test] # Install requirements -flake8 # Run style check -``` - -In addition, we check the formatting of files with -[`editorconfig-checker`](https://editorconfig-checker.github.io/): - -```bash -pip install editorconfig-checker==2.0.3 # Install requirements -editorconfig-checker # Run check -``` +In case you want to contribute to this project, please read the [contribution guidelines]((https://sensirion.github.io/python-i2c-stcc4/contributing.html)). ## License diff --git a/ci/checkin_doc.sh b/ci/checkin_doc.sh deleted file mode 100644 index 1031751..0000000 --- a/ci/checkin_doc.sh +++ /dev/null @@ -1,26 +0,0 @@ -#!/bin/bash - -# set shell settings (see https://sipb.mit.edu/doc/safe-shell/) -set -euv -o pipefail - -# clone the repo into a subfolder html, checkout the gh-pages into this folder and commit the freshly generated html -git clone "git@gitlab:${CI_PROJECT_PATH}.git" html -cd html -git checkout gh-pages -rm -f empty.txt -rm -f *.html -rm -f *.js -rm -rf _* -cd .. -# make sure to copy .nojekyll -cp -rf public/.[!.]* public/* html -cd html -git add . - -if git diff-index --quiet HEAD -- -then - exit 0 -fi - -git commit -m"Automatic doc update: ${CI_COMMIT_SHORT_SHA}" -git push \ No newline at end of file diff --git a/ci/set_git_config.sh b/ci/set_git_config.sh deleted file mode 100644 index 860c6aa..0000000 --- a/ci/set_git_config.sh +++ /dev/null @@ -1,16 +0,0 @@ -#!/bin/bash - -# set shell settings (see https://sipb.mit.edu/doc/safe-shell/) -set -eufv -o pipefail - -# install ssh private key (set as CI variable in GitLab project settings) -mkdir -p ~/.ssh -echo "$SSH_DEPLOY_KEY" > ~/.ssh/id_rsa -chmod 400 ~/.ssh/id_rsa - -# change remote URL to SSH to allow pushing with SSH -git remote set-url --push origin "git@gitlab:${CI_PROJECT_PATH}.git" - -# set git author -git config --global user.name "GitLab-CI" -git config --global user.email "<>" diff --git a/docs/build-documentation.rst b/docs/build-documentation.rst index 6522d99..a188010 100644 --- a/docs/build-documentation.rst +++ b/docs/build-documentation.rst @@ -5,6 +5,5 @@ The documentation is built with `Sphinx `_: .. code-block:: bash - python setup.py install # Install package - pip install -r docs/requirements.txt # Install requirements + python -m pip install .[docs] # Install doc requirements sphinx-build -b html docs docs/_build/html # Build documentation diff --git a/docs/conf.py b/docs/conf.py index f120ec5..f579949 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -10,6 +10,8 @@ from datetime import datetime import importlib.metadata as metadata +import sphinx_tabs.tabs + import sphinx.ext.autodoc import sensirion_i2c_stcc4 @@ -37,6 +39,7 @@ extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.viewcode', + 'sphinx_tabs.tabs', 'sphinx.ext.inheritance_diagram', 'sphinx.ext.githubpages', 'sphinx.ext.intersphinx', diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..45855f0 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,25 @@ +Contributing +------------ + +Contributions are welcome. To keep this driver lean and focused, contributions +should be limited to bug fixes, maintenance, and improvements that make the +driver API more convenient to use. + +The driver is intended to provide a minimal interface to the sensor. Application- +specific functionality and higher-level features should be implemented in an +application layer rather than added to the driver. + +.. note:: + + This driver is generated from a model. Contributions may therefore be + incorporated into the underlying model and regenerated. Changes made only + to the generated code may be overwritten by a future driver generation. + +Before submitting a contribution, make sure that: + +- All CI pipeline checks pass. +- The code passes the `flake8` checks. +- The code complies with the repository's `.editorconfig` configuration. + +Pull requests that introduce new functionality should preserve the scope and +purpose of the driver described above. \ No newline at end of file diff --git a/docs/dev-setup.rst b/docs/dev-setup.rst new file mode 100644 index 0000000..3e2a3e5 --- /dev/null +++ b/docs/dev-setup.rst @@ -0,0 +1,45 @@ +To prepare your development environment, check out the repository, +create a Python virtual environment, and activate it. +Then install the driver in editable mode using `pip`. + +Check out the Git repository to your local machine: + +.. code-block:: console + + git clone + cd + +Create a Python virtual environment: + +.. code-block:: console + + python -m venv .venv + +Activate the virtual environment: + +.. tabs:: + + .. group-tab:: Bash + + .. code-block:: console + + source .venv/bin/activate + + .. group-tab:: PowerShell + + .. code-block:: console + + .venv\Scripts\Activate.ps1 + + .. group-tab:: Command Prompt + + .. code-block:: console + + .venv\Scripts\activate.bat + +Install the driver in editable mode together with the development dependencies: + +.. code-block:: console + + python -m pip install -e . + diff --git a/docs/development.rst b/docs/development.rst index d169708..dddb742 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -1,6 +1,10 @@ Development =========== +For development, you first need to prepare your setup. + +.. include:: dev-setup.rst + .. toctree:: run-tests diff --git a/docs/driver-installation.rst b/docs/driver-installation.rst new file mode 100644 index 0000000..ef91a3c --- /dev/null +++ b/docs/driver-installation.rst @@ -0,0 +1,37 @@ +The driver installation consists of creating a Python virtual environment, +activating it, and installing the driver using `pip`. + +Create a Python virtual environment: + +.. code-block:: console + + python -m venv .venv + +Activate the virtual environment: + +.. tabs:: + + .. group-tab:: Bash + + + .. code-block:: console + + source .venv/bin/activate + + .. group-tab:: PowerShell + + .. code-block:: console + + .venv\Scripts\Activate.ps1 + + .. group-tab:: Command Prompt + + .. code-block:: console + + .venv\Scripts\activate.bat + +Install the driver: + +.. code-block:: console + + python -m pip install sensirion_i2c_stcc4 diff --git a/docs/execute-measurements.rst b/docs/execute-measurements.rst index cedbad2..5459819 100644 --- a/docs/execute-measurements.rst +++ b/docs/execute-measurements.rst @@ -1,27 +1,32 @@ -Execute measurements with SensorBridge -======================================= +Install the STCC4 Driver +------------------------ -The following steps show how to use this driver on a Windows system using the `Sensirion SEK-SensorBridge`_ to -execute a simple measurement. +.. include:: driver-installation.rst -1. Install the STCC4 driver and all required packages as described in :ref:`Installation`. -2. Install the driver for the `Sensirion SEK-SensorBridge`_ - .. sourcecode:: bash +Use the SensorBridge on Windows +------------------------------- - pip install sensirion-shdlc-sensorbridge +1. Install the driver for the `Sensirion SEK-SensorBridge`_: -3. Connect the SEK-SensorBridge to your PC over USB + .. code-block:: console - a. If the SEK-SensorBridge is not detected by your system, follow the `SensorBridge FTDI Driver Installation`_ + python -m pip install sensirion-shdlc-sensorbridge -4. Connect the STCC4 sensor to the SEK-SensorBridge -5. Run the example script from the root of the repository. +2. Connect the SEK-SensorBridge to your PC over USB. - By default the script assumes the SensorBridge is connected to :code:`COM1` serial port. If this is different on your system, - pass the port in use with the :code:`--serial-port` parameter as outlined below. + If the SEK-SensorBridge is not detected by your system, follow the + `SensorBridge FTDI Driver Installation`_. - .. sourcecode:: bash +3. Connect the STCC4 sensor to the SEK-SensorBridge. + +4. Run the example script from the root of the repository. + + By default, the script assumes that the SensorBridge is connected to the + ``COM1`` serial port. If a different port is used, specify it with the + ``--serial-port`` parameter: + + .. code-block:: console python examples/example_usage_sensorbridge_stcc4.py --serial-port @@ -35,20 +40,23 @@ Example script .. literalinclude:: ../examples/example_usage_sensorbridge_stcc4.py :language: python -Execute measurements using internal Linux I²C driver -==================================================== -On Linux systems it is furthermore possible to use the Linux user space I²C driver directly. -How this can be done is shown in the following. +Use the Linux I²C Driver +------------------------ + +On Linux systems, the sensor can alternatively be accessed directly through +the Linux user-space I²C driver. + +1. Connect the STCC4 sensor to an I²C port of your system, for example I²C + port 1 of a Raspberry Pi. -1. Install the STCC4 driver and all required packages as described in :ref:`Installation`. -2. Connect the STCC4 sensor to the I²C port of your system (for example to the I²C port 1 of a Raspberry Pi). -3. Run the example script from the root of the repository. +2. Run the example script from the root of the repository. - By default the script assumes you have the sensor connected to :code:`/dev/i2c-1`. - If this is different on your system, pass the port in use with the :code:`--i2c-port` parameter as outlined below. + By default, the script assumes that the sensor is connected to + ``/dev/i2c-1``. If a different port is used, specify it with the + ``--i2c-port`` parameter: - .. sourcecode:: bash + .. code-block:: console python examples/example_usage_linux_stcc4.py --i2c-port diff --git a/docs/index.rst b/docs/index.rst index 8d9b5f7..1431019 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,4 +12,5 @@ Contents installation quickstart development + contributing api diff --git a/docs/installation.rst b/docs/installation.rst index 6edaa1b..dcec370 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -3,10 +3,7 @@ Installation ============ -The package can be installed with pip: +It is assumed that you have a working Python installation on your system. +If not, please install Python first including `pip `_. -.. sourcecode:: bash - - pip install sensirion_i2c_stcc4 - -Recommended usage is within a virtualenv. +.. include:: driver-installation.rst \ No newline at end of file diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 5dce52d..180ab5d 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -1,6 +1,10 @@ Quick Start =========== +Learn how to quickly get started with the STCC4 and perform your first measurements using +the provided usage examples. + + .. toctree:: execute-measurements diff --git a/docs/requirements.txt b/docs/requirements.txt index 5d15a64..bd93639 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,5 @@ click==8.0.4 jinja2~=3.1.0 sphinx~=7.1.0 +sphinx-tabs~=3.5.0 sphinx_rtd_theme~=1.3.0 diff --git a/docs/run-tests.rst b/docs/run-tests.rst index 55cfeb6..a3f720c 100644 --- a/docs/run-tests.rst +++ b/docs/run-tests.rst @@ -5,7 +5,7 @@ Unit tests can be run with `pytest `_: .. code-block:: bash - pip install -e .[test] # Install requirements + pip install -e .[test] # Install test requirements We provide a mock implementation that allows you to execute the tests for STCC4 without hardware. @@ -26,6 +26,3 @@ attached to COM1 you can start the tests with the following command: .. note:: The SensorBridge must have default settings (baudrate 460800, address 0) - - - diff --git a/metadata.yml b/metadata.yml index 2b29a43..5ebdf16 100644 --- a/metadata.yml +++ b/metadata.yml @@ -1,7 +1,7 @@ -# driver generation metadata -generator_version: 1.6.1 -model_version: 3.5.1 -dg_status: released -is_manually_modified: false -first_generated: '2025-02-24 11:47' -last_generated: '2026-04-30 12:17' +# driver generation metadata +generator_version: 1.9.1 +model_version: 3.5.1 +dg_status: released +is_manually_modified: false +first_generated: '2025-02-24 11:47' +last_generated: '2026-09-15 17:23' diff --git a/pyproject.toml b/pyproject.toml index 991c888..ba4cb2e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -8,7 +8,8 @@ description = "I2C driver for the Sensirion STCC4 sensor family" readme = "README.md" version = "1.1.0" -requires-python = ">=3.8,<4.0" + +requires-python = ">=3.8.4,<4.0" authors = [ { name = "Sensirion", email = "info@sensirion.com" }, @@ -45,8 +46,10 @@ dependencies = [ docs=[ "jinja2~=3.1.6", "sphinx-rtd-theme==3.0.2", - "sphinx==8.2.3", + "sphinx>=7.0,<8.0;python_version < '3.11'", + "sphinx==8.2.3;python_version >= '3.11'", "lazy-object-proxy ~=1.7.1", + "sphinx-tabs~=3.5.0", "sphinx-autoapi~=3.0.0", ] From 22ca7df4417fb13aed73a11e1299576871b8897d Mon Sep 17 00:00:00 2001 From: Rolf Laich Date: Wed, 16 Sep 2026 13:08:52 +0200 Subject: [PATCH 2/2] Add manual modification to Readme --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 566e4bf..7652ad8 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,8 @@ The STCC4 is Sensirion's next generation miniature CO2 sensor for indoor air qua The default I²C address of [STCC4](https://sensirion.com/products/catalog/STCC4) is **0x64**. - +> [!NOTE] +> The SEK-STCC4 board from Sensirion includes a STCC4 and a SHT4x for temperature and humidity compensation, which is controlled by the STCC4 through the integrated I2C controller interface. The provided examples are designed considering this sensor configuration. ## Connect the sensor