Skip to content

Commit 353ceeb

Browse files
mmabeymmabey
committed
First full release
Verified everything works using the Metro M0 Express in CircuitPython 1.0.0.
1 parent 4db7709 commit 353ceeb

File tree

14 files changed

+613
-0
lines changed

14 files changed

+613
-0
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,3 +99,4 @@ ENV/
9999

100100
# mypy
101101
.mypy_cache/
102+
.idea

‎.travis.yml

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Travis CI configuration for automated .mpy file generation.
2+
# Author: Tony DiCola
3+
# License: Public Domain
4+
# This configuration will work with Travis CI (travis-ci.org) to automacially
5+
# build .mpy files for CircuitPython when a new tagged release is created. This
6+
# file is relatively generic and can be shared across multiple repositories by
7+
# following these steps:
8+
# 1. Copy this file into a .travis.yml file in the root of the repository.
9+
# 2. Change the deploy > file section below to list each of the .mpy files
10+
# that should be generated. The config will automatically look for
11+
# .py files with the same name as the source for generating the .mpy files.
12+
# Note that the .mpy extension should be lower case!
13+
# 3. Commit the .travis.yml file and push it to GitHub.
14+
# 4. Go to travis-ci.org and find the repository (it needs to be setup to access
15+
# your github account, and your github account needs access to write to the
16+
# repo). Flip the 'ON' switch on for Travis and the repo, see the Travis
17+
# docs for more details: https://docs.travis-ci.com/user/getting-started/
18+
# 5. Get a GitHub 'personal access token' which has at least 'public_repo' or
19+
# 'repo' scope: https://help.github.com/articles/creating-an-access-token-for-command-line-use/
20+
# Keep this token safe and secure! Anyone with the token will be able to
21+
# access and write to your GitHub repositories. Travis will use the token
22+
# to attach the .mpy files to the release.
23+
# 6. In the Travis CI settings for the repository that was enabled find the
24+
# environment variable editing page: https://docs.travis-ci.com/user/environment-variables/#Defining-Variables-in-Repository-Settings
25+
# Add an environment variable named GITHUB_TOKEN and set it to the value
26+
# of the GitHub personal access token above. Keep 'Display value in build
27+
# log' flipped off.
28+
# 7. That's it! Tag a release and Travis should go to work to add .mpy files
29+
# to the release. It takes about a 2-3 minutes for a worker to spin up,
30+
# build mpy-cross, and add the binaries to the release.
31+
language: generic
32+
33+
sudo: true
34+
35+
deploy:
36+
provider: releases
37+
api_key: $GITHUB_TOKEN
38+
file:
39+
- "hcsr04.mpy"
40+
skip_cleanup: true
41+
on:
42+
tags: true
43+
44+
before_install:
45+
- sudo apt-get -yqq update
46+
- sudo apt-get install -y build-essential git python python-pip
47+
- git clone https://github.com/adafruit/circuitpython.git
48+
- make -C circuitpython/mpy-cross
49+
- export PATH=$PATH:$PWD/circuitpython/mpy-cross/
50+
- sudo pip install shyaml
51+
52+
before_deploy:
53+
- shyaml get-values deploy.file < .travis.yml | sed 's/.mpy/.py/' | xargs -L1 mpy-cross

‎CODE_OF_CONDUCT.md

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
In the interest of fostering an open and welcoming environment, we as
6+
contributors and maintainers pledge to making participation in our project and
7+
our community a harassment-free experience for everyone, regardless of age, body
8+
size, disability, ethnicity, gender identity and expression, level of experience,
9+
nationality, personal appearance, race, religion, or sexual identity and
10+
orientation.
11+
12+
## Our Standards
13+
14+
Examples of behavior that contributes to creating a positive environment
15+
include:
16+
17+
* Using welcoming and inclusive language
18+
* Being respectful of differing viewpoints and experiences
19+
* Gracefully accepting constructive criticism
20+
* Focusing on what is best for the community
21+
* Showing empathy towards other community members
22+
23+
Examples of unacceptable behavior by participants include:
24+
25+
* The use of sexualized language or imagery and unwelcome sexual attention or
26+
advances
27+
* Trolling, insulting/derogatory comments, and personal or political attacks
28+
* Public or private harassment
29+
* Publishing others' private information, such as a physical or electronic
30+
address, without explicit permission
31+
* Other conduct which could reasonably be considered inappropriate in a
32+
professional setting
33+
34+
## Our Responsibilities
35+
36+
Project maintainers are responsible for clarifying the standards of acceptable
37+
behavior and are expected to take appropriate and fair corrective action in
38+
response to any instances of unacceptable behavior.
39+
40+
Project maintainers have the right and responsibility to remove, edit, or
41+
reject comments, commits, code, wiki edits, issues, and other contributions
42+
that are not aligned to this Code of Conduct, or to ban temporarily or
43+
permanently any contributor for other behaviors that they deem inappropriate,
44+
threatening, offensive, or harmful.
45+
46+
## Scope
47+
48+
This Code of Conduct applies both within project spaces and in public spaces
49+
when an individual is representing the project or its community. Examples of
50+
representing a project or community include using an official project e-mail
51+
address, posting via an official social media account, or acting as an appointed
52+
representative at an online or offline event. Representation of a project may be
53+
further defined and clarified by project maintainers.
54+
55+
## Enforcement
56+
57+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
58+
reported by contacting the project team at [email protected]. All
59+
complaints will be reviewed and investigated and will result in a response that
60+
is deemed necessary and appropriate to the circumstances. The project team is
61+
obligated to maintain confidentiality with regard to the reporter of an incident.
62+
Further details of specific enforcement policies may be posted separately.
63+
64+
Project maintainers who do not follow or enforce the Code of Conduct in good
65+
faith may face temporary or permanent repercussions as determined by other
66+
members of the project's leadership.
67+
68+
## Attribution
69+
70+
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
71+
available at [http://contributor-covenant.org/version/1/4][version]
72+
73+
[homepage]: http://contributor-covenant.org
74+
[version]: http://contributor-covenant.org/version/1/4/

‎Pipfile

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
[[source]]
2+
url = "https://pypi.python.org/simple"
3+
verify_ssl = true
4+
5+
[dev-packages]
6+
sphinx = "*"
7+
sphinx-rtd-theme = "*"

‎README.rst

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
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/

‎VERSION

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
0.1

‎docs/Makefile

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = python -msphinx
7+
SPHINXPROJ = CircuitPythonHCSR04Library
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/api.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
``hcsr04``
2+
==========
3+
4+
.. automodule:: hcsr04
5+
:members:

0 commit comments

Comments
 (0)