When creating a module for CircuitPython you typically want to include information like documentation, continuous integration build scripts, etc. which can be a lot of boilerplate code to create and copy. Luckily there's a handy tool called cookiecutter that uses a template to bootstrap the creation of a driver. Follow these steps to install and use cookiecutter to start creating a VL6180X driver.
cookiecutter Install
First you'll need to make sure you have Python and cookiecutter installed. Download and install Python from python.org (be sure you select to have the pip package manager installed too and Python added to your system path if installing on Windows). Then in a command prompt use pip (either pip if using Python 2.7.x or pip3 if using Python 3.x) to install cookiecutter:
pip install cookiecutter
Note on some systems like mac OSX or Debian/Ubuntu Linux you might need to run the command above as root with sudo. If you run into trouble installing cookiecutter be sure to read its documentation.
CircuitPython Template
Once cookiecutter is installed you can use it to bootstrap the creation of a driver and its boilerplate code. You'll use this special cookiecutter template that's made for creating CircuitPython drivers. From a terminal run:
cookiecutter gh:adafruit/cookiecutter-adafruit-circuitpython
You should see cookiecutter run and prompt you for information about the driver you're creating. For the VC6180X you can use information like:
library_name: VL6180x depends_on_bus_device []: True depends_on_register []: author: ladyada github_user [adafruit]: library_prefix []: adafruit company []: Adafruit Industries
Notice we specified True for the depends_on_bus_device question. This means cookiecutter will do extra work to include the dependency on the bus device module automatically. Since we saw in the previous page that bus device simplifies access to the I2C device we'll be sure to include it here.
The depends_on_register question we left blank to specify false, or no dependency, on the register module. The register module provides some handy abstractions for accessing 8-bit device registers but we aren't using it here because the VL6180X uses 16-bit register addresses and isn't complex enough to need the extra dependency. You might examine the register module and consider using it when writing your own drivers for other devices!
After the cookiecutter template finishes running you should see a vl6180x directory created, and inside will be files like:
cookiecutter created these files and populated them with information to boostrap the driver creation process. Here's what you'll find in the files:
- .travis.yml - This is a configuration for the Travis-CI build system to automatically generate .mpy files for code stored on Adafruit's GitHub account. Open this file and carefully read the comments to see how to setup Travis CI (specifically setup steps you need to follow on Travis' website to enter your Github access token). Setting up Travis-CI is optional and this file can be ignored if you don't want automatic .mpy generation for Github releases.
- adafruit_vl6180x.py - This is the main source file for your driver code. The cookiecutter template will create this by taking the name of your library and appending adafruit_ to it so it matches the convention for other Adafruit libraries. When users import your library they'll do so using the exact name of this file.
- api.rst - This is the API documentation that will automatically be generated by Read The Docs / sphinx tools. You don't typically need to add or change anything here--the comments and docstrings from your source file will be parsed and turned into documentation automatically.
- CODE_OF_CONDUCT.md - This is populated with a good code of conduct for potential contributors to your library.
- conf.py - This is a configuration for the sphinx documentation engine used by Read The Docs. You don't need to change anything here.
- LICENSE - By default this is populated with the MIT license.
- README.rst - A small readme is automatically generated to match the format of other drivers. You should fill in the introduction and usage section TODOs before publishing the code.
- readthedocs.yml - This is a configuration file that Read The Docs uses to check that a repository has documentation it should process. You don't need to change this file.
- requirements.txt - This is a Python package configuration file that lists the dependencies of the driver. Although CircuitPython / MicroPython don't use this file, tools like Read The Docs will use it to determine what packages need to be installed to build documentation. You don't need to change this file.
In the next section we'll start filling in the code for adafruit_vl6180x.py by converting from Arduino to Python & CircuitPython code.
Text editor powered by tinymce.
