Soldered-SliderPotentiometer-MicroPython-Library/SliderPotentiometer.py at main · SolderedElectronics/Soldered-SliderPotentiometer-MicroPython-Library · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
# FILE: SliderPotentiometer.py
# AUTHOR: Fran Fodor @ Soldered
# BRIEF: MicroPython library for the Slider Potentiometer with Qwiic.
# LAST UPDATED: 2026-04-30

from machine import ADC, Pin, I2C
from os import uname
import struct


class SliderPotentiometer:
    """
    Base class for slider potentiometer implementations.
    Provides a common interface for analog and Qwiic variants.
    """

    def get_value(self):
        """
        Read the raw value of the potentiometer.

        :return: Raw potentiometer reading
        """
        raise NotImplementedError

    def min_value(self):
        """
        Get the minimum possible potentiometer reading.

        :return: Minimum value (always 0)
        """
        return 0

    def max_value(self):
        """
        Get the maximum possible potentiometer reading.

        :return: Maximum value
        """
        raise NotImplementedError

    def get_percentage(self):
        """
        Get the current potentiometer position as a percentage.

        :return: Position as integer percentage (0-100)
        """
        return int(100 * (self.get_value() / self.max_value()))


class AnalogSliderPotentiometer(SliderPotentiometer):
    """
    Slider potentiometer read via onboard ADC pin.
    """

    def __init__(self, pin):
        """
        Initialize the analog slider potentiometer.

        :param pin: GPIO pin number connected to the potentiometer wiper
        :param calibrated_min: Raw ADC value at physical minimum (default 0)
        :param calibrated_max: Raw ADC value at physical maximum (default 65535);
                               tune this down if the slider saturates before full travel
        """
        self._adc = ADC(Pin(pin))

    def get_value(self):
        """
        Read the raw 16-bit ADC value.

        :return: Raw ADC reading (0-65535)
        """
        return self._adc.read_u16()

    def max_value(self):
        """
        Get the calibrated maximum value.

        :return: Calibrated maximum ADC reading
        """
        return 65536

    def get_percentage(self):
        """
        Get the current potentiometer position as a percentage, clamped to calibrated range.

        :return: Position as integer percentage (0-100)
        """
        raw = self.get_value()
        clamped = max(self.min_value, min(self.max_value, raw))
        return int(100 * (clamped - self.min_value) / self.max_value)


class QwiicSliderPotentiometer(SliderPotentiometer):
    """
    Slider potentiometer read via Qwiic (I2C) interface.
    Compatible with the Soldered easyC slider potentiometer breakout.

    Default I2C address: 0x30
    """

    _ANALOG_READ_REG = 0x00
    _DEFAULT_ADDRESS = 0x30

    def __init__(self, i2c=None, address=_DEFAULT_ADDRESS):
        """
        Initialize the Qwiic slider potentiometer.

         :param i2c: Initialized I2C object (optional, auto-detected on known boards)
        :param address: I2C address of the device (default 0x30)
        """
        if i2c is not None:
            self.i2c = i2c
        else:
            if uname().sysname in ("esp32", "esp8266", "Soldered Dasduino CONNECTPLUS"):
                self.i2c = I2C(0, scl=Pin(22), sda=Pin(21))
            else:
                raise Exception("Board not recognized, enter I2C pins manually")

        self.address = address

    def get_value(self):
        """
        Read the raw potentiometer value over Qwiic.

        :return: Raw potentiometer reading (0-1024)
        """
        self.i2c.writeto(self.address, bytes([self._ANALOG_READ_REG]))
        raw = self.i2c.readfrom(self.address, 2)
        return struct.unpack_from('<H', raw)[0]

    def max_value(self):
        """
        Get the maximum possible potentiometer reading.

        :return: Maximum value (1024)
        """
        return 1024