Skip to content

docs: Add was_touched & touch_calibrate for pins 0, 1, 2 & pin_logo. #802

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: v2-docs
Choose a base branch
from
Open

docs: Add was_touched & touch_calibrate for pins 0, 1, 2 & pin_logo. #802

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ae76850
docs: Move resistive/capacitive description to set_touch_mode().
microbit-carlos Mar 4, 2024
67fd7c7
docs: Add was_touched() & get_touches() for pins 0, 1, 2, pin_logo.
microbit-carlos Mar 19, 2024
b2a0dc9
docs: Add touch_calibrate() for pins 0,1,2, logo.
microbit-carlos Sep 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 20 additions & 4 deletions docs/microbit_micropython_api.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -149,18 +149,34 @@ Each of these pins are instances of the ``MicroBitPin`` class, which offers the
# Only available for touch pins 0, 1, and 2. Returns boolean if the pin
# is touched
pin.is_touched()
# Only available for touch pins 0, 1, 2 and on micro:bit V2 also the logo.
# Sets the touch mode. Value can be either RESISTIVE or CAPACITIVE
# Only available for touch pins 0, 1, and 2. Returns boolean if the pin
# has been touched since the last time this method was called
pin.was_touched()
# Only available for touch pins 0, 1, and 2. Returns the running total of
# pin touches, and resets this counter to zero
pin.get_touches()
# Only available for touch pins 0, 1, and 2. Sets the touch mode.
# Value can be either RESISTIVE or CAPACITIVE
pin.set_touch_mode(value)
# Only available for touch pins 0, 1, and 2. Re-calibrates the touch pin
# detection.
pin.touch_calibrate()

Except in the case of the pins marked **V2**, which offers the following API:

pin_logo::

# returns boolean for logo touch pin
# returns a boolean for logo touch pin
pin_logo.is_touched()
# returns a boolean if the logo was pressed since the last time
# this method was called
pin_logo.was_touched()
# returns the running total of touches, and resets this counter to zero
pin_logo.get_touches()
# Sets the touch mode. Value can be either RESISTIVE or CAPACITIVE
pin.set_touch_mode(value)
pin_logo.set_touch_mode(value)
# Re-calibrates the touch pin detection.
pin.touch_calibrate()

pin_speaker, as the above ``MicroBitPin`` class, but does not include
``pin.is_touched()``.
Expand Down
32 changes: 22 additions & 10 deletions docs/pin.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -197,15 +197,36 @@ its own to that.

.. py:class:: MicroBitTouchPin

.. py:method:: touch_calibrate()

Re-calibrates the touch pin detection.
This is useful when a conductive object is connected to the pin to
be used as a touch sensor.

.. py:method:: is_touched()

Return ``True`` if the pin is being touched with a finger, otherwise
return ``False``.

.. py:method:: was_touched()

Returns ``True`` or ``False`` to indicate if the pin was touched
since the device started or since the last time this method was called.

.. py:method:: get_touches()

Returns the number of times the pin was touched
since the device started or since the last time this method was called.

.. py:method:: set_touch_mode(value)

.. note::
The default touch mode for the pins on the edge connector is
The default touch mode for the pins on the edge connector is
`resistive`. The default for the logo pin **V2** is `capacitive`.

Set the touch mode for the given pin. Value can be either ``CAPACITIVE``
or ``RESISTIVE``. For example, ``pin0.set_touch_mode(pin0.CAPACITIVE)``.

**Resistive touch**
This test is done by measuring how much resistance there is between the
pin and ground. A low resistance gives a reading of ``True``. To get
Expand All @@ -218,15 +239,6 @@ its own to that.
<https://www.allaboutcircuits.com/technical-articles/introduction-to-capacitive-touch-sensing>`_
does not require you to make a ground connection as part of a circuit.

.. py:method:: set_touch_mode(value)

.. note::
The default touch mode for the pins on the edge connector is
`resistive`. The default for the logo pin **V2** is `capacitive`.

Set the touch mode for the given pin. Value can be either ``CAPACITIVE``
or ``RESISTIVE``. For example, ``pin0.set_touch_mode(pin0.CAPACITIVE)``.

The pull mode for a pin is automatically configured when the pin changes to an
input mode. Input modes are when you call ``read_analog`` / ``read_digital`` /
``is_touched``. The default pull mode for these is, respectively, ``NO_PULL``,
Expand Down