1  CircuitPython HC-SR04 Driver
  2  ============================
  3  
  4  |docs| |version| |ci| |license_type|
  5  
  6  .. image:: hcsr04.jpg
  7      :width: 300px
  8  
  9  The HC-SR04 is an inexpensive solution for measuring distances using microcontrollers. This library provides a simple
 10  driver for controlling these sensors from `CircuitPython`_, Adafruit's port of `MicroPython <http://micropython.org/>`_.
 11  
 12  
 13  Installation
 14  ------------
 15  
 16  This driver depends on `CircuitPython <https://github.com/adafruit/circuitpython>`_ and is designed for use with an
 17  HC-SR04 ultrasonic range sensor. You'll also need to ensure all dependencies are available on the CircuitPython
 18  filesystem. This is easily achieved by downloading
 19  `the Adafruit library and driver bundle <https://github.com/adafruit/Adafruit_CircuitPython_Bundle>`_.
 20  
 21  .. warning::
 22  
 23      The HC-SR04 uses 5V logic, so you will have to use a `level shifter
 24      <https://www.adafruit.com/product/2653?q=level%20shifter&>`_ between it
 25      and your CircuitPython board (which uses 3.3V logic).
 26  
 27  .. note::
 28  
 29      If you want to use an HC-SR04 with `MicroPython <http://micropython.org/>`_, I recommend checking out `this library
 30      <https://github.com/andrey-git/micropython-hcsr04>`_.
 31  
 32  
 33  Quick Start
 34  -----------
 35  
 36  You'll need to dedicate two pins to communicating with the HC-SR04. The sensor communicates in a very rudimentary
 37  manner, so it doesn't matter which pins you choose, as long as they're digital IO pins (pins that start with "``D``"
 38  are digital).
 39  
 40  There are two ways of instantiating a :class:`~hcsr04.HCSR04` object: with or without using a context manager.
 41  
 42  .. note::
 43  
 44      It is technically possible to communicate with the HC-SR04 using only one wire since the trigger and echo signals
 45      aren't ever active at the same time. Once I have a chance to determine a safe way to do this, I plan to add this as
 46      a feature to the library.
 47  
 48  .. seealso::
 49  
 50      `Adafruit's guide on Lifetime and ContextManagers <https://circuitpython.readthedocs.io/en/latest/docs/design_guide.html#lifetime-and-contextmanagers>`_
 51          Gives more info on using context managers with CircuitPython drivers.
 52  
 53      :any:`board`
 54          A list of pins available on your device. To view this list, first `get a REPL
 55          <http://circuitpython.readthedocs.io/en/latest/docs/pyboard/tutorial/repl.html>`_ (the guide linked was written
 56          for the pyboard, but it still works), then input the following:
 57  
 58          ::
 59  
 60              import board
 61              dir(board)
 62  
 63  Without a Context Manager
 64  ^^^^^^^^^^^^^^^^^^^^^^^^^
 65  
 66  In the example below, we create the :class:`~hcsr04.HCSR04` object directly, get the distance every 2 seconds, then
 67  de-initialize the device.
 68  
 69  ::
 70  
 71      from hcsr04 import HCSR04
 72      sonar = HCSR04(trig, echo)
 73      try:
 74          while True:
 75              print(sonar.dist_cm())
 76              sleep(2)
 77      except KeyboardInterrupt:
 78          pass
 79      sonar.deinit()
 80  
 81  
 82  With a Context Manager
 83  ^^^^^^^^^^^^^^^^^^^^^^
 84  
 85  In the example below, we use a context manager (the :any:`with <with>` statement) to create the :class:`~hcsr04.HCSR04`
 86  instance, again get the distance every 2 seconds, but then the context manager handles de-initializing the device for
 87  us.
 88  
 89  ::
 90  
 91      from hcsr04 import HCSR04
 92      with HCSR04(trig, echo) as sonar:
 93          try:
 94              while True:
 95                  print(sonar.dist_cm())
 96                  sleep(2)
 97          except KeyboardInterrupt:
 98              pass
 99  
100  
101  API Reference
102  -------------
103  
104  .. toctree::
105     :maxdepth: 2
106  
107     api
108  
109  
110  Contributing
111  ------------
112  
113  Contributions are welcome! Please read our `Code of Conduct
114  <https://github.com/adafruit/Adafruit_CircuitPython_HCSR04/blob/master/CODE_OF_CONDUCT.md>`_
115  before contributing to help this project stay welcoming.
116  
117  
118  License
119  -------
120  
121  This project is licensed under the `MIT License <https://github.com/mmabey/CircuitPython_HCSR04/blob/master/LICENSE>`_.
122  
123  
124  .. |docs| image:: https://readthedocs.org/projects/adafruit-soundboard/badge/
125      :alt: Documentation Status
126      :target: `Read the Docs`_
127  
128  .. |version| image:: https://img.shields.io/github/release/mmabey/CircuitPython_HCSR04/all.svg
129      :alt: Release Version
130      :target: https://github.com/mmabey/CircuitPython_HCSR04
131  
132  .. |ci| image:: https://travis-ci.org/mmabey/CircuitPython_HCSR04.svg
133      :alt: CI Build Status
134      :target: https://travis-ci.org/mmabey/CircuitPython_HCSR04
135  
136  .. |license_type| image:: https://img.shields.io/github/license/mmabey/CircuitPython_HCSR04.svg
137      :alt: License: MIT
138      :target: `GitHub`_
139  
140  .. _GitHub: https://github.com/mmabey/CircuitPython_HCSR04
141  
142  .. _CircuitPython: https://github.com/adafruit/circuitpython
143  
144  .. _Read the Docs: http://circuitpython-hcsr04.readthedocs.io/