chore: prepare release 0.1

.copier/answers_pypackage.yaml

@@ -0,0 +1,21 @@
+---
+# Changes here will be overwritten by Copier; NEVER EDIT MANUALLY
+#
+# You can use `pdm run copier update --defaults` to update the template
+# files using the answers stored in this file.
+# (see https://copier.readthedocs.io/en/stable/updating/ for details)
+
+_commit: v0.1.3
+_src_path: https://github.com/feeph/pypackage-template
+author_email: 55798703+feeph@users.noreply.github.com
+author_name: Feeph Aifeimei
+default_branch: master
+is_typed: true
+issuetracker_url: https://github.com/feeph/libads1xxx-python/issues
+max_line_length: 250
+package_description: library for the ADS1xxx family of I²C analog-to-digital converters
+package_name: ads1xxx
+package_namespace: feeph
+python_constraint: '>=3.10,<3.13'
+repository_name: libads1xxx-python
+repository_url: https://github.com/feeph/libads1xxx-python

.github/CODEOWNERS

@@ -6,7 +6,7 @@
 # repository and assigned a permission level first. Otherwise they will
 # be underlined with red squiggly lines when looking at the file in the
 # WebGUI and it won't work.
-#  -> https://github.com/feeph/libads1xxx-python/settings/access
+# (GitHub -> Repository -> Settings -> Collaborators)
 #
 
 # define default ownership

.pre-commit-config.yaml

@@ -3,20 +3,20 @@
 # documentation can be found at https://pre-commit.com/
 #
 # perform once after cloning the repository:
-#  pipx install pre-commit
-#  pre-commit install --allow-missing-config --hook-type pre-commit
-#  pre-commit install --allow-missing-config --hook-type commit-msg
-#  pre-commit install --allow-missing-config --hook-type post-commit
-#  pre-commit install --allow-missing-config --hook-type pre-push
+#  scripts/prepare_repository
 #
 # if you want to trigger pre-commit manually:
 #  pre-commit run
+#  pre-commit run --all-files
 #
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v2.3.0
     hooks:
+      - id: check-merge-conflict
+        args: [--assume-in-merge]
       - id: check-json
+      - id: check-toml
       - id: check-yaml
       - id: end-of-file-fixer
       - id: trailing-whitespace

README.md

@@ -1,5 +1,6 @@
 # libads1xxx-python
 
+[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-purple.json)](https://github.com/copier-org/copier)
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
 [![pdm-managed](https://img.shields.io/endpoint?url=https%3A%2F%2Fcdn.jsdelivr.net%2Fgh%2Fpdm-project%2F.github%2Fbadge.json)](https://pdm-project.org)
 [![tox](https://img.shields.io/badge/tox-ab79d2)](https://tox.wiki/)
@@ -12,7 +13,7 @@ library for the ADS1xxx family of I²C analog-to-digital converters
 
 ## Bugs & Features
 
-Please submit bugs and request features on the [issue tracker]( https://github.com/feeph/libads1xxx-python/issues).
+Please submit bugs and request features on the [issue tracker](https://github.com/feeph/libads1xxx-python/issues).
 
 Contributions are always welcome.
 

docs/CONTRIBUTING.md

@@ -52,6 +52,6 @@ tox
 ### use the demo script
 
 ```SHELL
-pdm run scripts/demonstrator.py
-pdm run scripts/demonstrator.py -v -i 2
+pdm run examples/demonstrator.py
+pdm run examples/demonstrator.py -v -i 2
 ```

feeph/ads1xxx/__init__.py

@@ -1,8 +1,8 @@
 #!/usr/bin/env python3
 """
+ADS1xxx family of I²C analog-to-digital converters
 """
 
 # the following imports are provided for user convenience
 # flake8: noqa: F401
-from feeph.ads1xxx.component import Component
-from feeph.ads1xxx.functions import function1
+from feeph.ads1xxx.ads1115 import Ads1115, Ads1115Config

feeph/ads1xxx/ads1115.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""
+ADS111x - Ultra-Small, Low-Power, I2C-Compatible, 860-SPS, 16-Bit ADCs
+          With Internal Reference, Oscillator, and Programmable Comparator
+
+datasheet: https://www.ti.com/lit/ds/symlink/ads1115.pdf
+"""
+
+import logging
+
+# module busio provides no type hints
+import busio  # type: ignore
+from attrs import define
+from feeph.i2c import BurstHandler
+
+from feeph.ads1xxx.ads111x import Ads111x
+
+LH = logging.getLogger('feeph.ads1xxx')
+
+
+@define
+class Ads1115Config:
+    """
+    The 16-bit Config register is used to control the operating mode, input
+    selection, data rate, full-scale range, and comparator modes.
+    """
+    # fmt: off
+    OSSA:     int  # 0b#..._...._...._.... status or single shot start
+    IMUX:     int  # 0b.###_...._...._.... input multiplexer configuration
+    PGA:      int  # 0b...._###._...._.... programmable gain amplifier
+    MODE:     int  # 0b...._...#_...._.... operating mode
+    DR:       int  # 0b...._...._###._.... data rate
+    COMP_MOD: int  # 0b...._...._...#_.... comparator mode
+    COMP_POL: int  # 0b...._...._...._#... comparator polarity
+    COMP_LAT: int  # 0b...._...._...._.#.. latching comparator
+    COMP_QUE: int  # 0b...._...._...._..## comparator queue & disable
+    # fmt: on
+
+
+DEFAULTS = {
+    0x01: 0x8583,
+    0x02: 0x8000,
+    0x03: 0x7FFF,
+}
+
+
+class Ads1115(Ads111x):
+    # 0x00 - conversion register (2 bytes, ro, default: 0x0000)
+    # 0x01 - config register     (2 bytes, rw, default: 0x8583)
+    # 0x10 - lo_thresh register  (2 bytes, rw, default: 0x0080)
+    # 0x11 - hi_thresh register  (2 bytes, rw, default: 0xFF7F)
+
+    def __init__(self, i2c_bus: busio.I2C):
+        self._i2c_bus = i2c_bus
+        self._i2c_adr = 0x48  # the I²C bus address is hardcoded
+
+    def get_config(self) -> Ads1115Config:
+        with BurstHandler(i2c_bus=self._i2c_bus, i2c_adr=self._i2c_adr) as bh:
+            value = bh.read_register(0x01, byte_count=2)
+        params = {
+            "OSSA":     value & 0b1000_0000_0000_0000,
+            "IMUX":     value & 0b0111_0000_0000_0000,
+            "PGA":      value & 0b0000_1110_0000_0000,
+            "MODE":     value & 0b0000_0001_0000_0000,
+            "DR":       value & 0b0000_0000_1110_0000,
+            "COMP_MOD": value & 0b0000_0000_0001_0000,
+            "COMP_POL": value & 0b0000_0000_0000_1000,
+            "COMP_LAT": value & 0b0000_0000_0000_0100,
+            "COMP_QUE": value & 0b0000_0000_0000_0011,
+        }
+        return Ads1115Config(**params)
+
+    def set_config(self, config: Ads1115Config):
+        value = 0b0000_0000_0000_0000
+        value &= config.OSSA
+        value &= config.IMUX
+        value &= config.PGA
+        value &= config.MODE
+        value &= config.DR
+        value &= config.COMP_MOD
+        value &= config.COMP_POL
+        value &= config.COMP_LAT
+        value &= config.COMP_QUE
+        with BurstHandler(i2c_bus=self._i2c_bus, i2c_adr=self._i2c_adr) as bh:
+            bh.write_register(0x01, value, byte_count=2)
+
+    def reset_device_registers(self):
+        with BurstHandler(i2c_bus=self._i2c_bus, i2c_adr=self._i2c_adr) as bh:
+            for register, value in DEFAULTS.items():
+                bh.write_register(register, value, byte_count=2)
+
+    # ---------------------------------------------------------------------
+
+    def get_measurement(self) -> int:
+        return 0
+
+    # ---------------------------------------------------------------------

feeph/ads1xxx/ads111x.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+"""
+abstract base class for ADS1113, ADS1114 and ADS1115
+"""
+
+import logging
+from abc import ABC, abstractmethod
+
+LH = logging.getLogger('feeph.ads1xxx')
+
+
+class Ads111x(ABC):
+    """
+
+    """
+
+    @abstractmethod
+    def get_measurement(self) -> int:
+        ...
+
+    @abstractmethod
+    def reset_device_registers(self):
+        ...