Skip to content

GPIO

This class provides high-level access to the instrument's digital pins. The API is defined in pypalmsens.GPIO, and pypalmsens.GPIOAsync for asynchronous workflows.

The intended usage of these classes is via the InstrumentManager.gpio and InstrumentManager.gpio attributes.

Example:

>>> import pypalmsens as ps

>>> with ps.connect() as manager:
...     print("Outputs:", manager.gpio.writable_pins)
...     print("Inputs :", manager.gpio.readable_pins)
...     manager.gpio.write_many([0,1,2], level='high')
Outputs: [0, 1, 2, 3]
Inputs : [0]

For more information how to use these classes, see the documentation here.

Classes:

pypalmsens.GPIO 

GPIO(manager: InstrumentManager)

Digital general-purpose input/output (GPIO) interface.

This class provides high-level access to the instrument's digital pins. Pin numbering is hardware-specific. Consult the instrument manual for the physical mapping.

Note that the internal numbering of the pins exposed by this class may differ from the documented pins numbering, e.g. d0 or d3. The pin numbering is interally consistent.

For MethodSCRIPT devices, the underlying libraries auto-configures read/write direction on read/write instructions.

For explicit control, use the low-level MethodSCRIPT primitives directly:

Methods:

  • read –

    Read the logic level of a single digital input pin.

  • read_many –

    Read the logic levels of multiple digital input pins.

  • toggle –

    Invert the logic level of a single digital output pin.

  • toggle_many –

    Invert the logic level of multiple digital output pins.

  • write –

    Set the logic level of a single digital output pin.

  • write_many –

    Set the logic level of multiple digital output pins.

Attributes:

Source code in src/pypalmsens/_instruments/gpio.py 
107
108
def __init__(self, manager: InstrumentManager):
    self._manager = manager

readable_pins property 

readable_pins: list[int]

Return the pin numbers that support digital input.

Returns:

  • list[int] –

    Sorted list of pin numbers that can be used with read and read_many.

writable_pins property 

writable_pins: list[int]

Return the pin numbers that support digital output.

Returns:

  • list[int] –

    Sorted list of pin numbers that can be used with write, write_many, toggle, and toggle_many.

read 

read(pin: int) -> Literal['low', 'high']

Read the logic level of a single digital input pin.

The pin configuration is automatically switched to input if needed.

Check your device documentation for the available input pins.

Parameters:

  • pin

    (int) –

    Pin number to read.

Returns:

  • level ( {'low', 'high'} ) –

    Current logic level of the requested pin.

Raises:

  • PinNotSupportedError: –

    If pin is not a supported input pin.

Source code in src/pypalmsens/_instruments/gpio.py 
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
def read(self, pin: int) -> Literal['low', 'high']:
    """Read the logic level of a single digital input pin.

    The pin configuration is automatically switched to input if needed.

    Check your device documentation for the available input pins.

    Parameters
    ----------
    pin: integer
        Pin number to read.

    Returns
    -------
    level : {'low', 'high'}
        Current logic level of the requested pin.

    Raises
    ------
    PinNotSupportedError:
        If ``pin`` is not a supported input pin.
    """
    [level] = self.read_many([pin])
    return level

read_many 

read_many(pins: Sequence[int]) -> list[Literal['low', 'high']]

Read the logic levels of multiple digital input pins.

Parameters:

  • pins

    (Sequence[int]) –

    Pin numbers to read. The order is preserved in the returned values.

Returns:

  • levels ( list of {'low', 'high'} ) –

    Logic levels corresponding to the requested pins, in the same order.

Raises:

  • PinNotSupportedError –

    If any pin in pins is not a supported input pin.

Source code in src/pypalmsens/_instruments/gpio.py 
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
def read_many(self, pins: Sequence[int]) -> list[Literal['low', 'high']]:
    """Read the logic levels of multiple digital input pins.

    Parameters
    ----------
    pins : Sequence[int]
        Pin numbers to read. The order is preserved in the
        returned values.

    Returns
    -------
    levels : list of {'low', 'high'}
        Logic levels corresponding to the requested ``pins``,
        in the same order.

    Raises
    ------
    PinNotSupportedError
        If any pin in ``pins`` is not a supported input pin.
    """
    raise_if_pins_not_supported(
        self._manager._comm.ClientConnection, pins=pins, mode='read'
    )

    mask = pins_to_bitmask(pins)

    with self._manager._lock():
        level_mask = self._manager._comm.ClientConnection.ReadDigitalLine(mask)

    levels = []
    for pin in pins:
        pin_mask = 1 << pin
        levels.append(pin_mask & level_mask == pin_mask)

    return [('low', 'high')[level] for level in levels]

toggle 

toggle(pin: int)

Invert the logic level of a single digital output pin.

A high state becomes low and vice-versa.

Parameters:

  • pin

    (int) –

    Pin number to toggle.

Returns:

  • None –

Raises:

  • PinNotSupportedError –

    If pin is not a supported output pin.

Source code in src/pypalmsens/_instruments/gpio.py 
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
def toggle(self, pin: int):
    """Invert the logic level of a single digital output pin.

    A ``high`` state becomes ``low`` and vice-versa.

    Parameters
    ----------
    pin : int
        Pin number to toggle.

    Returns
    -------
    None

    Raises
    ------
    PinNotSupportedError
        If ``pin`` is not a supported output pin.
    """
    return self.toggle_many([pin])

toggle_many 

toggle_many(pins: Sequence[int])

Invert the logic level of multiple digital output pins.

Each pin is toggled independently: high becomes low and low becomes high.

Parameters:

Raises:

  • PinNotSupportedError –

    If any pin in pins is not a supported output pin.

Source code in src/pypalmsens/_instruments/gpio.py 
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
def toggle_many(self, pins: Sequence[int]):
    """Invert the logic level of multiple digital output pins.

    Each pin is toggled independently: ``high`` becomes ``low``
    and ``low`` becomes ``high``.

    Parameters
    ----------
    pins : Sequence[int]
        Pin numbers to toggle.

    Raises
    ------
    PinNotSupportedError
        If any pin in ``pins`` is not a supported output pin.
    """

    def func(current: int, mask: int) -> int:
        return current ^ mask  # toggle

    return self._write_many(pins, func)

write 

write(pin: int, level: Literal['low', 'high'] = 'high')

Set the logic level of a single digital output pin.

Parameters:

  • pin

    (int) –

    Pin number to write.

  • level

    (('low', 'high'), default: 'low' ) –

    Logic level to set. Default is 'high'.

Raises:

  • PinNotSupportedError: –

    If pin is not a supported input pin.

Source code in src/pypalmsens/_instruments/gpio.py 
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
def write(self, pin: int, level: Literal['low', 'high'] = 'high'):
    """Set the logic level of a single digital output pin.

    Parameters
    ----------
    pin : int
        Pin number to write.
    level : {'low', 'high'}, optional
        Logic level to set.  Default is ``'high'``.

    Raises
    ------
    PinNotSupportedError:
        If ``pin`` is not a supported input pin.
    """
    self.write_many([pin], level=level)

write_many 

write_many(pins: Sequence[int], level: Literal['low', 'high'] = 'high')

Set the logic level of multiple digital output pins.

Parameters:

  • pins

    (Sequence[int]) –

    Pin numbers to write.

  • level

    (('low', 'high'), default: 'low' ) –

    Logic level to set on all specified pins. Default is 'high'.

Raises:

  • PinNotSupportedError –

    If any pin in pins is not a supported output pin.

Source code in src/pypalmsens/_instruments/gpio.py 
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
def write_many(self, pins: Sequence[int], level: Literal['low', 'high'] = 'high'):
    """Set the logic level of multiple digital output pins.

    Parameters
    ----------
    pins : Sequence[int]
        Pin numbers to write.
    level : {'low', 'high'}, optional
        Logic level to set on all specified pins.  Default is
        ``'high'``.

    Raises
    ------
    PinNotSupportedError
        If any pin in ``pins`` is not a supported output pin.
    """
    if level == 'high':

        def func(current: int, mask: int) -> int:
            return current | mask  # high

    elif level == 'low':

        def func(current: int, mask: int) -> int:
            return current & ~mask  # low

    else:
        raise ValueError("`level` must be one of 'low' or 'high'")

    return self._write_many(pins, func)

pypalmsens.GPIOAsync 

GPIOAsync(manager: InstrumentManagerAsync)

Digital general-purpose input/output (GPIO) interface.

This class provides high-level access to the instrument's digital pins. Pin numbering is hardware-specific. Consult the instrument manual for the physical mapping.

Note that the pins are typically referred to as d0 or d3. These correspond to pins 0 and 3 in this interface, respectively.

For MethodSCRIPT devices, the underlying libraries auto-configures read/write direction on read/write instructions.

For explicit control, use the low-level MethodSCRIPT primitives directly:

Methods:

  • read_async –

    Read the logic level of a single digital input pin.

  • read_many_async –

    Read the logic levels of multiple digital input pins.

  • toggle_async –

    Invert the logic level of a single digital output pin.

  • toggle_many_async –

    Invert the logic level of multiple digital output pins.

  • write_async –

    Set the logic level of a single digital output pin.

  • write_many_async –

    Set the logic level of multiple digital output pins.

Attributes:

Source code in src/pypalmsens/_instruments/gpio_async.py 
33
34
def __init__(self, manager: InstrumentManagerAsync):
    self._manager = manager

readable_pins property 

readable_pins: list[int]

Return the pin numbers that support digital input.

Returns:

  • list[int] –

    Sorted list of pin numbers that can be used with read and read_many.

writable_pins property 

writable_pins: list[int]

Return the pin numbers that support digital output.

Returns:

  • list[int] –

    Sorted list of pin numbers that can be used with write, write_many, toggle, and toggle_many.

read_async async 

read_async(pin: int) -> Literal['low', 'high']

Read the logic level of a single digital input pin.

The pin configuration is automatically switched to input if needed.

Check your device documentation for the available input pins.

Parameters:

  • pin

    (int) –

    Pin number to read.

Returns:

  • level ( {'low', 'high'} ) –

    Current logic level of the requested pin.

Raises:

  • PinNotSupportedError: –

    If pin is not a supported input pin.

Source code in src/pypalmsens/_instruments/gpio_async.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
async def read_async(self, pin: int) -> Literal['low', 'high']:
    """Read the logic level of a single digital input pin.

    The pin configuration is automatically switched to input if needed.

    Check your device documentation for the available input pins.

    Parameters
    ----------
    pin: integer
        Pin number to read.

    Returns
    -------
    level : {'low', 'high'}
        Current logic level of the requested pin.

    Raises
    ------
    PinNotSupportedError:
        If ``pin`` is not a supported input pin.
    """
    [level] = await self.read_many_async([pin])
    return level

read_many_async async 

read_many_async(pins: Sequence[int]) -> list[Literal['low', 'high']]

Read the logic levels of multiple digital input pins.

Parameters:

  • pins

    (Sequence[int]) –

    Pin numbers to read. The order is preserved in the returned values.

Returns:

  • levels ( list of {'low', 'high'} ) –

    Logic levels corresponding to the requested pins, in the same order.

Raises:

  • PinNotSupportedError –

    If any pin in pins is not a supported input pin.

Source code in src/pypalmsens/_instruments/gpio_async.py 
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
async def read_many_async(self, pins: Sequence[int]) -> list[Literal['low', 'high']]:
    """Read the logic levels of multiple digital input pins.

    Parameters
    ----------
    pins : Sequence[int]
        Pin numbers to read. The order is preserved in the
        returned values.

    Returns
    -------
    levels : list of {'low', 'high'}
        Logic levels corresponding to the requested ``pins``,
        in the same order.

    Raises
    ------
    PinNotSupportedError
        If any pin in ``pins`` is not a supported input pin.
    """
    raise_if_pins_not_supported(
        self._manager._comm.ClientConnection, pins=pins, mode='read'
    )

    mask = pins_to_bitmask(pins)

    async with self._manager._lock():
        level_mask: int = await create_future(
            self._manager._comm.ClientConnection.ReadDigitalLineAsync(mask)
        )

    levels = []
    for pin in pins:
        pin_mask = 1 << pin
        levels.append(pin_mask & level_mask == pin_mask)

    return [('low', 'high')[level] for level in levels]

toggle_async async 

toggle_async(pin: int)

Invert the logic level of a single digital output pin.

A high state becomes low and vice-versa.

Parameters:

  • pin

    (int) –

    Pin number to toggle.

Returns:

  • None –

Raises:

  • PinNotSupportedError –

    If pin is not a supported output pin.

Source code in src/pypalmsens/_instruments/gpio_async.py 
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
async def toggle_async(self, pin: int):
    """Invert the logic level of a single digital output pin.

    A ``high`` state becomes ``low`` and vice-versa.

    Parameters
    ----------
    pin : int
        Pin number to toggle.

    Returns
    -------
    None

    Raises
    ------
    PinNotSupportedError
        If ``pin`` is not a supported output pin.
    """
    return await self.toggle_many_async([pin])

toggle_many_async async 

toggle_many_async(pins: Sequence[int])

Invert the logic level of multiple digital output pins.

Each pin is toggled independently: high becomes low and low becomes high.

Parameters:

Raises:

  • PinNotSupportedError –

    If any pin in pins is not a supported output pin.

Source code in src/pypalmsens/_instruments/gpio_async.py 
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
async def toggle_many_async(self, pins: Sequence[int]):
    """Invert the logic level of multiple digital output pins.

    Each pin is toggled independently: ``high`` becomes ``low``
    and ``low`` becomes ``high``.

    Parameters
    ----------
    pins : Sequence[int]
        Pin numbers to toggle.

    Raises
    ------
    PinNotSupportedError
        If any pin in ``pins`` is not a supported output pin.
    """

    def func(current: int, mask: int) -> int:
        return current ^ mask  # toggle

    return await self._write_many_async(pins, func)

write_async async 

write_async(pin: int, level: Literal['low', 'high'] = 'high')

Set the logic level of a single digital output pin.

Parameters:

  • pin

    (int) –

    Pin number to write.

  • level

    (('low', 'high'), default: 'low' ) –

    Logic level to set. Default is 'high'.

Raises:

  • PinNotSupportedError: –

    If pin is not a supported input pin.

Source code in src/pypalmsens/_instruments/gpio_async.py 
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
async def write_async(self, pin: int, level: Literal['low', 'high'] = 'high'):
    """Set the logic level of a single digital output pin.

    Parameters
    ----------
    pin : int
        Pin number to write.
    level : {'low', 'high'}, optional
        Logic level to set.  Default is ``'high'``.

    Raises
    ------
    PinNotSupportedError:
        If ``pin`` is not a supported input pin.
    """
    _ = await self.write_many_async([pin], level=level)

write_many_async async 

write_many_async(pins: Sequence[int], level: Literal['low', 'high'] = 'high')

Set the logic level of multiple digital output pins.

Parameters:

  • pins

    (Sequence[int]) –

    Pin numbers to write.

  • level

    (('low', 'high'), default: 'low' ) –

    Logic level to set on all specified pins. Default is 'high'.

Raises:

  • PinNotSupportedError –

    If any pin in pins is not a supported output pin.

Source code in src/pypalmsens/_instruments/gpio_async.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
async def write_many_async(
    self, pins: Sequence[int], level: Literal['low', 'high'] = 'high'
):
    """Set the logic level of multiple digital output pins.

    Parameters
    ----------
    pins : Sequence[int]
        Pin numbers to write.
    level : {'low', 'high'}, optional
        Logic level to set on all specified pins.  Default is
        ``'high'``.

    Raises
    ------
    PinNotSupportedError
        If any pin in ``pins`` is not a supported output pin.
    """
    if level == 'high':

        def func(current: int, mask: int) -> int:
            return current | mask  # high

    elif level == 'low':

        def func(current: int, mask: int) -> int:
            return current & ~mask  # low

    else:
        raise ValueError("`level` must be one of 'low' or 'high'")

    return await self._write_many_async(pins, func)