29 918
modifications
Modifications
Sauter à la navigation
Sauter à la recherche
FEATHER-M0-MicroPython-bibliotheque (voir la source)
Version du 13 décembre 2017 à 21:02
, 13 décembre 2017 à 21:02Page créée avec « {{FEATHER-M0-EXPRESS-NAV}} {{traduction}} Part of what makes CircuitPython so awesome is its ability to store code separately from the firmware itself. Storing code sepa... »
{{FEATHER-M0-EXPRESS-NAV}}
{{traduction}}
Part of what makes CircuitPython so awesome is its ability to store code separately from the firmware itself. Storing code separately from the firmware makes it easier to update both the code you write and the libraries you depend. So, instead of compiling libraries in, you simply place them into your <code class="prettyprint">lib</code> directory on the <code class="prettyprint">CIRCUITPY</code> drive.
Your board may ship with a <code class="prettyprint">lib</code> folder already, its in the base directory of the drive. If not, simply create the folder yourself.
{{ADFImage|FEATHER-M0-MicroPython-bibliotheque-01.png|640px}}
CircuitPython libraries work in the same was as regular Python modules so the <a href="https://docs.python.org/3/tutorial/modules.html">Python docs</a> are a great reference for how it all should work. In Python terms, we can place our library files in the <code class="prettyprint">lib</code> directory because its part of the Python path by default.
One downside of this approach of separate libraries is that they are not built in. To use them, one needs to copy them to the <code class="prettyprint">CIRCUITPY</code> drive before they can be used. Fortunately, we provide a bundle full of our libraries.
Our bundle and releases also feature optimized versions of the libraries with the <code class="prettyprint">.mpy</code> file extension. These files take less space on the drive and have a smaller memory footprint as they are loaded.
<h2>
<a href="#installing-the-bundle" class="anchor-link"><span class="fa fa-link"></span></a><span id="installing-the-bundle" class="anchor-link-target"></span>Installing the bundle</h2>
We're constantly updating and improving our libraries, so we don't (at this time) ship our CircuitPython boards with the full library bundle. Instead, you may find example code that depends on (<code class="prettyprint">import</code>) libraries. Some of these libraries may be available from us at Adafruit, some may be written by community members!
Either way, once you get past the most basic blink scripts, you'll want to know how to get libraries on board. So, lets take a look at this silly example below which uses a SI7021 I2C temperature sensor.
<pre><code class="prettyprint lang-python">import adafruit_si7021
import busio
import board
i2c = busio.I2C(board.SCL, board.SDA)
sensor = adafruit_si7021.SI7021(i2c)
print("Temperature:", sensor.temperature)
print("Humidity:", sensor.relative_humidity)
</code>
</pre>
After saving that as <code class="prettyprint">code.py</code> on the drive we see the status NeoPixel flashes that an error has occurred. Opening up the serial console we see that an <code class="prettyprint">ImportError</code> has occurred.
{{ADFImage|FEATHER-M0-MicroPython-bibliotheque-02.png|640px}}
It says that no module exists named <code class="prettyprint">adafruit_si7021</code>. Thats the library we need to download! Since we bought the sensor from Adafruit its likely there is a library for in <a href="https://github.com/adafruit/Adafruit_CircuitPython_Bundle/releases/latest">the official Adafruit bundle</a>. If its not an Adafruit part or its missing, we can also check <a href="https://github.com/adafruit/CircuitPython_Community_Bundle/releases/latest">the Community bundle</a> which has libraries contributed by the community.
Visiting the bundle release page will show us information on the latest release including a list of all the versions of the included drivers. Scrolling to the bottom of the page will reveal the downloads. We'll download the first zip file which starts with <code class="prettyprint">adafruit-circuitpython-bundle</code>.
{{ADFImage|FEATHER-M0-MicroPython-bibliotheque-03.png|640px}}
{{ADFImage|FEATHER-M0-MicroPython-bibliotheque-04.png|640px}}
After downloading the zip, extract its contents. This is usually done by double clicking on the zip. On Mac OSX as I'm using, it places the file in the same directory as the zip. I usually sort my Downloads by file data so the <code class="prettyprint">lib</code> directory that was contained in the zip ends up next to the zip file.
{{ADFImage|FEATHER-M0-MicroPython-bibliotheque-05.png|640px}}
== Express Boards ==
If you are using a Feather M0 Express, Metro M0 Express or Circuit Playground Express (e.g. "Express" board) your CircuitPython board comes with 2 MB of Flash storage. This is ''plenty'' of space for all of our library files so we recommend you just install them all! (If you have a Gemma M0 or Trinket M0 or other non-Express board, skip down to the next section)
On Express boards, the <code class="prettyprint">lib</code> directory can be copied directly to the CIRCUITPY drive.
Just drag the entire <code class="prettyprint">lib</code> folder into the CIRCUITPY drive, and 'replace' any old files if your operating system prompts you
You're done! You can go back to coding your project :) The rest of this page is for non-Express boards
== Non-Express Boards ==
If you have a Gemma M0 or Trinket M0, your internal storage is from the chip itself. So, this board doesn't have enough space for all of the libraries. If you try to copy over the entire <code class="prettyprint">lib</code> folder you'll overwhelm your store.
Instead, we'll copy over just what we need as we need it. In the <code class="prettyprint">lib</code> folder there is an <code class="prettyprint">adafruit_si7021.mpy</code> file. That matches the missing module! Python imports modules based on the filename so they will always match up. Lets drag it over. If this works, skip to <a href="https://learn.adafruit.com/adafruit-gemma-m0/installing-libraries#continuing-after-copy">the next section</a>. Keep reading if you have an error.
{{ADFImage|FEATHER-M0-MicroPython-bibliotheque-06.png|640px}}
<h2>
<a href="#non-express-boards-out-of-space" class="anchor-link"><span class="fa fa-link"></span></a><span id="non-express-boards-out-of-space" class="anchor-link-target"></span>Non-Express boards - Out of space?</h2>
The file system on the board is very tiny. (Smaller than an ancient floppy disk.) So, its likely you'll run out of space but don't panic! There are a couple ways to free up space.
The board ships with the Windows 7 serial driver too! Feel free to delete that if you don't need it or have already installed it. Its ~12KiB or so.
<h3>Delete something!</h3>
The simplest way of freeing up space is to delete files from the drive. Perhaps there are libraries in the <code class="prettyprint">lib</code> that you aren't using anymore or test code that isn't in use.
<h3>Use tabs</h3>
One unique feature of Python is that the indentation of code matters. Usually the recommendation is to indent code with four spaces for every indent. In general, we recommend that too. '''However''', one trick to storing more human-readable code is to use a single tab character for indentation. This approach uses 1/4 of the space for indentation and can be significant when we're counting bytes.
<h3>Mac OSX loves to add extra files.</h3>
{{ADFImage|FEATHER-M0-MicroPython-bibliotheque-07.png|640px}}
Luckily you can disable some of the extra hidden files that Mac OSX adds by running a few commands to disable search indexing and create zero byte placeholders. Follow the steps below to maximize the amount of space available on OSX:
<h3>Prevent & Remove Mac OSX Hidden Files</h3>
First find the volume name for your board. With the board plugged in run this command in a terminal to list all the volumes:
<syntaxhighlight lang="python">
ls -l /Volumes</pre>
</syntaxhighlight>
<syntaxhighlight lang="python">
</syntaxhighlight>
Look for a volume with a name like '''CIRCUITPY''' (the default for CircuitPython). The full path to the volume is the '''/Volumes/CIRCUITPY''' path.
Now follow the <a href="http://apple.stackexchange.com/questions/6707/how-to-stop-os-x-from-writing-spotlight-and-trash-files-to-memory-cards-and-usb/7135#7135">steps from this question</a> to run these terminal commands that stop hidden files from being created on the board:
<syntaxhighlight lang="python">
mdutil -i off /Volumes/CIRCUITPY
cd /Volumes/CIRCUITPY
rm -rf .{,_.}{fseventsd,Spotlight-V*,Trashes}
mkdir .fseventsd
touch .fseventsd/no_log .metadata_never_index .Trashes
cd -
</syntaxhighlight>
Replace '''/Volumes/CIRCUITPY''' in the commands above with the full path to your board's volume if it's different. At this point all the hidden files should be cleared from the board and some hidden files will be prevented from being created.
However there are still some cases where hidden files will be created by Mac OSX. In particular if you copy a file that was downloaded from the internet it will have special metadata that Mac OSX stores as a hidden file. Luckily you can run a copy command from the terminal to copy files '''without''' this hidden metadata file. See the steps below:
<h3>Copy Files on Mac OSX Without Creating Hidden Files</h3>
Once you've disabled and removed hidden files with the above commands on Mac OSX you need to be careful to copy files to the board with a special command that prevents future hidden files from being created. Unfortunately you '''cannot''' use drag and drop copy in Finder because it will still create these hidden extended attribute files in some cases (for files downloaded from the internet, like Adafruit's modules).
To copy a file or folder use the '''-X''' option for the '''cp''' command in a terminal. For example to copy a '''foo.mpy''' file to the board use a command like:
<syntaxhighlight lang="python">
cp -X foo.mpy /Volumes/CIRCUITPY</pre>
</syntaxhighlight>
<syntaxhighlight lang="python">
</syntaxhighlight>
Or to copy a folder and all of its child files/folders use a command like:
<syntaxhighlight lang="python">
cp -rX folder_to_copy /Volumes/CIRCUITPY</pre>
</syntaxhighlight>
<syntaxhighlight lang="python">
</syntaxhighlight>
<h3>Other Mac OSX Tips</h3>
If you'd like to see the amount of space used on the drive and manually delete hidden files here's how to do so. First list the amount of space used on the '''CIRCUITPY''' drive with the df command:
{{ADFImage|FEATHER-M0-MicroPython-bibliotheque-08.png|640px}}
Lets remove the <code class="prettyprint">._</code> files first.
{{ADFImage|FEATHER-M0-MicroPython-bibliotheque-09.png|640px}}
Whoa! We have 13Ki more than before! Lets continue!
<h2>
<a href="#continuing-after-copy" class="anchor-link"><span class="fa fa-link"></span></a><span id="continuing-after-copy" class="anchor-link-target"></span>Continuing after copy</h2>
Woohoo! Everything copied over just fine. Lets check the serial terminal to see how things are going.
{{ADFImage|FEATHER-M0-MicroPython-bibliotheque-10.png|640px}}
Oops! Another <code class="prettyprint">ImportError</code>! Libraries can depend on other libraries so copying one file over may not be enough. Looking in the bundle, there is an <code class="prettyprint">adafruit_bus_device</code> directory. In Python terms this is a package. It contains module files. Lets copy the folder over to make sure we get everything.
{{ADFImage|FEATHER-M0-MicroPython-bibliotheque-11.png|640px}}
If that fails due to out of space, <a href="https://learn.adafruit.com/adafruit-gemma-m0/installing-libraries#out-of-space">see above</a>. If not, continue on.
Lets check the serial connection again. Looks like it worked! We don't have any more <code class="prettyprint">ImportError</code>s and we can see the temperature (in Celsius) and the relative humidity.
{{ADFImage|FEATHER-M0-MicroPython-bibliotheque-12.png|640px}}
{{FEATHER-M0-EXPRESS-TRAILER}}
{{traduction}}
Part of what makes CircuitPython so awesome is its ability to store code separately from the firmware itself. Storing code separately from the firmware makes it easier to update both the code you write and the libraries you depend. So, instead of compiling libraries in, you simply place them into your <code class="prettyprint">lib</code> directory on the <code class="prettyprint">CIRCUITPY</code> drive.
Your board may ship with a <code class="prettyprint">lib</code> folder already, its in the base directory of the drive. If not, simply create the folder yourself.
{{ADFImage|FEATHER-M0-MicroPython-bibliotheque-01.png|640px}}
CircuitPython libraries work in the same was as regular Python modules so the <a href="https://docs.python.org/3/tutorial/modules.html">Python docs</a> are a great reference for how it all should work. In Python terms, we can place our library files in the <code class="prettyprint">lib</code> directory because its part of the Python path by default.
One downside of this approach of separate libraries is that they are not built in. To use them, one needs to copy them to the <code class="prettyprint">CIRCUITPY</code> drive before they can be used. Fortunately, we provide a bundle full of our libraries.
Our bundle and releases also feature optimized versions of the libraries with the <code class="prettyprint">.mpy</code> file extension. These files take less space on the drive and have a smaller memory footprint as they are loaded.
<h2>
<a href="#installing-the-bundle" class="anchor-link"><span class="fa fa-link"></span></a><span id="installing-the-bundle" class="anchor-link-target"></span>Installing the bundle</h2>
We're constantly updating and improving our libraries, so we don't (at this time) ship our CircuitPython boards with the full library bundle. Instead, you may find example code that depends on (<code class="prettyprint">import</code>) libraries. Some of these libraries may be available from us at Adafruit, some may be written by community members!
Either way, once you get past the most basic blink scripts, you'll want to know how to get libraries on board. So, lets take a look at this silly example below which uses a SI7021 I2C temperature sensor.
<pre><code class="prettyprint lang-python">import adafruit_si7021
import busio
import board
i2c = busio.I2C(board.SCL, board.SDA)
sensor = adafruit_si7021.SI7021(i2c)
print("Temperature:", sensor.temperature)
print("Humidity:", sensor.relative_humidity)
</code>
</pre>
After saving that as <code class="prettyprint">code.py</code> on the drive we see the status NeoPixel flashes that an error has occurred. Opening up the serial console we see that an <code class="prettyprint">ImportError</code> has occurred.
{{ADFImage|FEATHER-M0-MicroPython-bibliotheque-02.png|640px}}
It says that no module exists named <code class="prettyprint">adafruit_si7021</code>. Thats the library we need to download! Since we bought the sensor from Adafruit its likely there is a library for in <a href="https://github.com/adafruit/Adafruit_CircuitPython_Bundle/releases/latest">the official Adafruit bundle</a>. If its not an Adafruit part or its missing, we can also check <a href="https://github.com/adafruit/CircuitPython_Community_Bundle/releases/latest">the Community bundle</a> which has libraries contributed by the community.
Visiting the bundle release page will show us information on the latest release including a list of all the versions of the included drivers. Scrolling to the bottom of the page will reveal the downloads. We'll download the first zip file which starts with <code class="prettyprint">adafruit-circuitpython-bundle</code>.
{{ADFImage|FEATHER-M0-MicroPython-bibliotheque-03.png|640px}}
{{ADFImage|FEATHER-M0-MicroPython-bibliotheque-04.png|640px}}
After downloading the zip, extract its contents. This is usually done by double clicking on the zip. On Mac OSX as I'm using, it places the file in the same directory as the zip. I usually sort my Downloads by file data so the <code class="prettyprint">lib</code> directory that was contained in the zip ends up next to the zip file.
{{ADFImage|FEATHER-M0-MicroPython-bibliotheque-05.png|640px}}
== Express Boards ==
If you are using a Feather M0 Express, Metro M0 Express or Circuit Playground Express (e.g. "Express" board) your CircuitPython board comes with 2 MB of Flash storage. This is ''plenty'' of space for all of our library files so we recommend you just install them all! (If you have a Gemma M0 or Trinket M0 or other non-Express board, skip down to the next section)
On Express boards, the <code class="prettyprint">lib</code> directory can be copied directly to the CIRCUITPY drive.
Just drag the entire <code class="prettyprint">lib</code> folder into the CIRCUITPY drive, and 'replace' any old files if your operating system prompts you
You're done! You can go back to coding your project :) The rest of this page is for non-Express boards
== Non-Express Boards ==
If you have a Gemma M0 or Trinket M0, your internal storage is from the chip itself. So, this board doesn't have enough space for all of the libraries. If you try to copy over the entire <code class="prettyprint">lib</code> folder you'll overwhelm your store.
Instead, we'll copy over just what we need as we need it. In the <code class="prettyprint">lib</code> folder there is an <code class="prettyprint">adafruit_si7021.mpy</code> file. That matches the missing module! Python imports modules based on the filename so they will always match up. Lets drag it over. If this works, skip to <a href="https://learn.adafruit.com/adafruit-gemma-m0/installing-libraries#continuing-after-copy">the next section</a>. Keep reading if you have an error.
{{ADFImage|FEATHER-M0-MicroPython-bibliotheque-06.png|640px}}
<h2>
<a href="#non-express-boards-out-of-space" class="anchor-link"><span class="fa fa-link"></span></a><span id="non-express-boards-out-of-space" class="anchor-link-target"></span>Non-Express boards - Out of space?</h2>
The file system on the board is very tiny. (Smaller than an ancient floppy disk.) So, its likely you'll run out of space but don't panic! There are a couple ways to free up space.
The board ships with the Windows 7 serial driver too! Feel free to delete that if you don't need it or have already installed it. Its ~12KiB or so.
<h3>Delete something!</h3>
The simplest way of freeing up space is to delete files from the drive. Perhaps there are libraries in the <code class="prettyprint">lib</code> that you aren't using anymore or test code that isn't in use.
<h3>Use tabs</h3>
One unique feature of Python is that the indentation of code matters. Usually the recommendation is to indent code with four spaces for every indent. In general, we recommend that too. '''However''', one trick to storing more human-readable code is to use a single tab character for indentation. This approach uses 1/4 of the space for indentation and can be significant when we're counting bytes.
<h3>Mac OSX loves to add extra files.</h3>
{{ADFImage|FEATHER-M0-MicroPython-bibliotheque-07.png|640px}}
Luckily you can disable some of the extra hidden files that Mac OSX adds by running a few commands to disable search indexing and create zero byte placeholders. Follow the steps below to maximize the amount of space available on OSX:
<h3>Prevent & Remove Mac OSX Hidden Files</h3>
First find the volume name for your board. With the board plugged in run this command in a terminal to list all the volumes:
<syntaxhighlight lang="python">
ls -l /Volumes</pre>
</syntaxhighlight>
<syntaxhighlight lang="python">
</syntaxhighlight>
Look for a volume with a name like '''CIRCUITPY''' (the default for CircuitPython). The full path to the volume is the '''/Volumes/CIRCUITPY''' path.
Now follow the <a href="http://apple.stackexchange.com/questions/6707/how-to-stop-os-x-from-writing-spotlight-and-trash-files-to-memory-cards-and-usb/7135#7135">steps from this question</a> to run these terminal commands that stop hidden files from being created on the board:
<syntaxhighlight lang="python">
mdutil -i off /Volumes/CIRCUITPY
cd /Volumes/CIRCUITPY
rm -rf .{,_.}{fseventsd,Spotlight-V*,Trashes}
mkdir .fseventsd
touch .fseventsd/no_log .metadata_never_index .Trashes
cd -
</syntaxhighlight>
Replace '''/Volumes/CIRCUITPY''' in the commands above with the full path to your board's volume if it's different. At this point all the hidden files should be cleared from the board and some hidden files will be prevented from being created.
However there are still some cases where hidden files will be created by Mac OSX. In particular if you copy a file that was downloaded from the internet it will have special metadata that Mac OSX stores as a hidden file. Luckily you can run a copy command from the terminal to copy files '''without''' this hidden metadata file. See the steps below:
<h3>Copy Files on Mac OSX Without Creating Hidden Files</h3>
Once you've disabled and removed hidden files with the above commands on Mac OSX you need to be careful to copy files to the board with a special command that prevents future hidden files from being created. Unfortunately you '''cannot''' use drag and drop copy in Finder because it will still create these hidden extended attribute files in some cases (for files downloaded from the internet, like Adafruit's modules).
To copy a file or folder use the '''-X''' option for the '''cp''' command in a terminal. For example to copy a '''foo.mpy''' file to the board use a command like:
<syntaxhighlight lang="python">
cp -X foo.mpy /Volumes/CIRCUITPY</pre>
</syntaxhighlight>
<syntaxhighlight lang="python">
</syntaxhighlight>
Or to copy a folder and all of its child files/folders use a command like:
<syntaxhighlight lang="python">
cp -rX folder_to_copy /Volumes/CIRCUITPY</pre>
</syntaxhighlight>
<syntaxhighlight lang="python">
</syntaxhighlight>
<h3>Other Mac OSX Tips</h3>
If you'd like to see the amount of space used on the drive and manually delete hidden files here's how to do so. First list the amount of space used on the '''CIRCUITPY''' drive with the df command:
{{ADFImage|FEATHER-M0-MicroPython-bibliotheque-08.png|640px}}
Lets remove the <code class="prettyprint">._</code> files first.
{{ADFImage|FEATHER-M0-MicroPython-bibliotheque-09.png|640px}}
Whoa! We have 13Ki more than before! Lets continue!
<h2>
<a href="#continuing-after-copy" class="anchor-link"><span class="fa fa-link"></span></a><span id="continuing-after-copy" class="anchor-link-target"></span>Continuing after copy</h2>
Woohoo! Everything copied over just fine. Lets check the serial terminal to see how things are going.
{{ADFImage|FEATHER-M0-MicroPython-bibliotheque-10.png|640px}}
Oops! Another <code class="prettyprint">ImportError</code>! Libraries can depend on other libraries so copying one file over may not be enough. Looking in the bundle, there is an <code class="prettyprint">adafruit_bus_device</code> directory. In Python terms this is a package. It contains module files. Lets copy the folder over to make sure we get everything.
{{ADFImage|FEATHER-M0-MicroPython-bibliotheque-11.png|640px}}
If that fails due to out of space, <a href="https://learn.adafruit.com/adafruit-gemma-m0/installing-libraries#out-of-space">see above</a>. If not, continue on.
Lets check the serial connection again. Looks like it worked! We don't have any more <code class="prettyprint">ImportError</code>s and we can see the temperature (in Celsius) and the relative humidity.
{{ADFImage|FEATHER-M0-MicroPython-bibliotheque-12.png|640px}}
{{FEATHER-M0-EXPRESS-TRAILER}}