Merge pull request #1 from hostcc/initial-revision

Initial revision

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @hostcc

.github/workflows/main.yml

@@ -0,0 +1,107 @@
+---
+name: main
+
+on:
+  pull_request:
+  release:
+    types: [published]
+  push:
+    branches:
+      - main
+      - master
+
+jobs:
+  tests:
+    name: Tests
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            python: 3.6
+            toxenv: py
+          - os: ubuntu-latest
+            python: 3.7
+            toxenv: py
+          - os: ubuntu-latest
+            python: 3.8
+            toxenv: py
+          - os: ubuntu-latest
+            python: 3.9
+            toxenv: py
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout the code
+        uses: actions/checkout@v2
+        with:
+          # Disable shallow clone for Sonar scanner, as it needs access to the
+          # history
+          fetch-depth: 0
+      - name: Set Python up
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install testing tools
+        run: >-
+          python -m pip install --upgrade setuptools pip tox virtualenv coverage
+      - name: Run the tests
+        run: tox -e ${{ matrix.toxenv }}
+      - name: Generage Coverage combined XML report
+        run: coverage xml
+      - name: Determine package version
+        id: package-version
+        run: |
+          package_version=`cat version.txt`
+          echo "::set-output name=VALUE::$package_version"
+      - name: SonarCloud scanning
+        uses: sonarsource/sonarcloud-github-action@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+        with:
+          # yamllint disable rule:line-length
+          args: >-
+            -Dsonar.projectKey=${{ github.repository_owner }}_${{ github.event.repository.name }}
+            -Dsonar.organization=${{ github.repository_owner }}
+            -Dsonar.projectVersion=${{ steps.package-version.outputs.VALUE }}
+          # yamllint enable rule:line-length
+
+  pypi-publish:
+    name: Publish to PyPi
+    runs-on: ubuntu-latest
+    # PyPi disallows to publish packages with direct dependencies (GitHub
+    # sourced dependency in this case), so disable publishing for now
+    if: false
+    needs: [tests]
+    steps:
+      - name: Checkout the code
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 0  # `setuptools_scm` needs tags
+      - name: Set Python up
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.9
+      - name: Install the PEP517 package builder
+        run: python -m pip install --upgrade build
+      - name: Build the package
+        run: python -m build
+      - name: Publish the package to Test PyPi
+        # Skip publishing to test PyPI if we're performing release, there might
+        # be already the version of the package from the merge to master branch
+        if: github.event_name != 'release'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.TEST_PYPI_TOKEN }}
+          repository_url: https://test.pypi.org/legacy/
+      - name: Publish the release to PyPi
+        # Publish to production PyPi only happens when a release published out
+        # of the main branch
+        if: >-
+          github.event_name == 'release'
+          && github.event.action == 'published'
+          && (github.event.release.target_commitish == 'main'
+             || github.event.release.target_commitish == 'master')
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_TOKEN }}

.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.egg-info/
+.tox/
+dist/
+.coverage

.readthedocs.yaml

@@ -0,0 +1,16 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.9"
+
+sphinx:
+   configuration: docs/conf.py
+
+python:
+   install:
+   - requirements: docs/requirements.txt

README.rst

@@ -0,0 +1,130 @@
+.. image::  https://github.com/hostcc/energomera-hass-mqtt/actions/workflows/main.yml/badge.svg?branch=master
+   :target: https://github.com/hostcc/energomera-hass-mqtt/tree/master
+   :alt: Github workflow status
+.. image:: https://readthedocs.org/projects/energomera-hass-mqtt/badge/?version=stable
+   :target: https://energomera-hass-mqtt.readthedocs.io/en/stable
+   :alt: ReadTheDocs status
+.. image:: https://img.shields.io/github/v/release/hostcc/energomera-hass-mqtt
+   :target: https://github.com/hostcc/energomera-hass-mqtt/releases/latest
+   :alt: Latest GitHub release
+.. image:: https://img.shields.io/pypi/v/energomera-hass-mqtt
+   :target: https://pypi.org/project/energomera-hass-mqtt/
+   :alt: Latest PyPI version
+
+Description
+===========
+
+Python package to read data from `Energomera energy meter
+<https://energomera-by.translate.goog/products/?_x_tr_sl=ru&_x_tr_tl=en&_x_tr_hl=en-US&_x_tr_pto=wapp&_x_tr_sch=http>`_
+(possibly supporting `others similar
+<http://www.energomera.ru/en/products/meters>`_) and send over to HomeAssistant
+using MQTT.
+
+The package has been developed with CE301BY three-phase meter.
+
+Dependencies
+============
+
+* Pending PR to ``iec62056_21`` for transport improvements:
+  https://github.com/pwitab/iec62056-21/pull/29
+
+Quick start
+===========
+
+Since there are direct dependencies no package is published on PyPI and you'll
+need to install it directly from Github:
+
+.. code:: shell
+
+     pip install git+https://github.com/hostcc/energomera-hass-mqtt@main
+
+Usage
+=====
+
+.. code::
+
+   usage: energomera-hass-mqtt [-h] [-c CONFIG_FILE]
+
+   optional arguments:
+    -h, --help            show this help message and exit
+    -c CONFIG_FILE, --config-file CONFIG_FILE
+       Path to configuration file (default: '/etc/energomera/config.yaml')
+
+Configuration file format
+=========================
+
+Configuration file is in YAML format and supports following elements:
+
+.. code:: yaml
+
+        # (optional) General parameters
+        general:
+            # (bool) default ``false``: perform single processing cycle and
+            #  exit
+            oneshot:
+            # (number) default ``30``: delay in seconds between processing
+            #  cycles
+            intercycle_delay:
+            # (string) default ``error``: logging level, one of ``critical``,
+            #  ``error``, ``warning``, ``info`` or ``debug``
+            logging_level:
+
+        # Energy meter parameters
+        meter:
+            # (string) Serial port (e.g. /dev/ttyUSB0)
+            port:
+            # (string) Password to meter for administrative session, manufacturer's
+            #  default is '777777'
+            password:
+        # MQTT parameters
+        mqtt:
+            # (string) Hostname or IP address of MQTT broker
+            host:
+            # (string) optional: MQTT user name
+            user:
+            # (string) optional: MQTT user password
+            password:
+            # (string) default ``homeassistant``: Preffix to MQTT topic names,
+            #  should correspond to one set in HomeAssistant for auto-discovery
+            hass_discovery_prefix:
+        # (list of mappings) - optional: Energy meter parameters to process and
+        #  properties of corresponding HASS sensor
+        parameters:
+            - # (string) IEC address (e.g. ``POWEP``)
+              address:
+              # (string or list) HASS Sensor name for the entry. If IEC address
+              #  provides multi-value reponse, this could be a list with the
+              #  number of entries equals to number of values in response
+              name:
+              # (string) Device class of the HASS sensor
+              device_class:
+              # (string) State class of the HASS sensor
+              state_class:
+              # (string) Unit of measurement for the HASS sensor
+              unit:
+              # (string) - optional: Additional data to read the parameter with
+              #  (argument to parameter's address)
+              additional_data:
+              # (string) - optional: Entity name for the HASS sensor, will be
+              #  used to generate its unique ID. If omitted the ``address`` is
+              #  used instead. Use of this option might be needed if your
+              #  configuration contains several entries of meter's parameters
+              #  of same address, but with different ``additional_data``
+              entity_name:
+              # (number) - optional: Zero-based index to pick an entry from
+              #  multi-value response to meter's parameter
+              response_idx:
+
+
+``parameters`` section supports following expressions:
+
+        - ``{{ energomera_prev_month }}``: Previous month in meter's format
+        - ``{{ energomera_prev_day }}``: Previous day in meter's format
+
+
+``systemd`` support
+===================
+
+Sample service definition for ``systemd`` is provided under
+`<https://github.com/hostcc/energomera-hass-mqtt/tree/main/systemd>`_
+directory.

docs/api-docs.rst

@@ -0,0 +1,8 @@
+API documentation
+=================
+
+.. autosummary::
+   :toctree: _generated
+   :recursive:
+
+   energomera_hass_mqtt

docs/conf.py

@@ -0,0 +1,54 @@
+"""
+Configuration file for the Sphinx documentation builder.
+
+This file only contains a selection of the most common options. For a full
+list see the documentation:
+https://www.sphinx-doc.org/en/master/usage/configuration.html
+"""
+
+# -- Path setup --------------------------------------------------------------
+import sys
+from sphinx.util.inspect import getdoc
+from sphinx.util.docstrings import separate_metadata
+sys.path.extend(['../src'])
+
+# -- Project information -----------------------------------------------------
+
+project = 'energomera-hass-mqtt'
+copyright = '2022, Ilia Sotnikov'
+author = 'Ilia Sotnikov'
+
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.autosectionlabel',
+]
+
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+autodoc_default_options = {
+    'members': True,
+    'inherited-members': True,
+    'show-inheritance': True,
+    'member-order': 'bysource',
+    'class-doc-from': 'both',
+}
+
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+}

docs/index.rst

@@ -0,0 +1,18 @@
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   Introduction <self>
+   api-docs
+
+.. contents::
+
+.. include:: ../README.rst
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/requirements.txt

@@ -0,0 +1,6 @@
+sphinx-rtd-theme
+git+https://github.com/hostcc/iec62056-21.git@feature/transport-improvements
+asyncio-mqtt
+pyyaml
+schema
+addict

pyproject.toml

@@ -0,0 +1,14 @@
+[build-system]
+requires = ["setuptools>=43.0.0", "wheel", "setuptools_scm>=6.2"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools_scm]
+local_scheme = "no-local-version"
+write_to = "version.txt"
+
+[tool.pytest.ini_options]
+pythonpath = [
+	"src"
+]
+log_cli = 1
+log_cli_level = "error"