mirror of
https://github.com/thearn/Python-Arduino-Command-API.git
synced 2026-01-11 15:38:11 -05:00
261 lines
16 KiB
HTML
261 lines
16 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
|
|
<head>
|
|
<meta charset='utf-8' />
|
|
<meta http-equiv="X-UA-Compatible" content="chrome=1" />
|
|
<meta name="description" content="Python-arduino-command-api : A Python library for communicating with Arduino microcontroller boards" />
|
|
|
|
<link rel="stylesheet" type="text/css" media="screen" href="stylesheets/stylesheet.css">
|
|
|
|
<title>Python-arduino-command-api</title>
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<!-- HEADER -->
|
|
<div id="header_wrap" class="outer">
|
|
<header class="inner">
|
|
<a id="forkme_banner" href="https://github.com/thearn/Python-Arduino-Command-API">View on GitHub</a>
|
|
|
|
<h1 id="project_title">Python-arduino-command-api</h1>
|
|
<h2 id="project_tagline">A Python library for communicating with Arduino microcontroller boards</h2>
|
|
|
|
<section id="downloads">
|
|
<a class="zip_download_link" href="https://github.com/thearn/Python-Arduino-Command-API/zipball/master">Download this project as a .zip file</a>
|
|
<a class="tar_download_link" href="https://github.com/thearn/Python-Arduino-Command-API/tarball/master">Download this project as a tar.gz file</a>
|
|
</section>
|
|
</header>
|
|
</div>
|
|
|
|
<!-- MAIN CONTENT -->
|
|
<div id="main_content_wrap" class="outer">
|
|
<section id="main_content" class="inner">
|
|
<h1>
|
|
<a name="python-arduino-command-api" class="anchor" href="#python-arduino-command-api"><span class="octicon octicon-link"></span></a>Python Arduino Command API</h1>
|
|
|
|
<p>The Python Arduino Command API is a light-weight Python library for
|
|
communicating with <a href="http://www.arduino.cc/">Arduino microcontroller boards</a> from a connected computer using
|
|
standard serial IO, either physically
|
|
or wirelessly. It is written using a custom protocol, similar to <a href="http://firmata.org/wiki/Main_Page">Firmata</a>. </p>
|
|
|
|
<p>This allows a user to quickly protoype programs for Arduino using Python code, or to
|
|
simply read/control/troubleshoot/experiment
|
|
with harware connected to an Arduino board without ever having to recompile and reload sketches to the board itself.</p>
|
|
|
|
<p>Method names within the Python Arduino Command API are designed to be as close
|
|
as possible to their Arduino programming language counterparts</p>
|
|
|
|
<h2>
|
|
<a name="simple-usage-example-led-blink" class="anchor" href="#simple-usage-example-led-blink"><span class="octicon octicon-link"></span></a>Simple usage example (LED blink)</h2>
|
|
|
|
<div class="highlight highlight-python"><pre><span class="c">#!/usr/bin/env python</span>
|
|
<span class="sd">"""</span>
|
|
<span class="sd"> Blinks an LED on digital pin 13</span>
|
|
<span class="sd"> in 1 second intervals</span>
|
|
<span class="sd">"""</span>
|
|
|
|
<span class="kn">from</span> <span class="nn">Arduino</span> <span class="kn">import</span> <span class="n">Arduino</span>
|
|
<span class="kn">import</span> <span class="nn">time</span>
|
|
|
|
<span class="n">board</span> <span class="o">=</span> <span class="n">Arduino</span><span class="p">(</span><span class="s">'9600'</span><span class="p">)</span> <span class="c">#plugged in via USB, serial com at rate 9600</span>
|
|
|
|
<span class="k">while</span> <span class="bp">True</span><span class="p">:</span>
|
|
<span class="n">board</span><span class="o">.</span><span class="n">digitalWrite</span><span class="p">(</span><span class="mi">13</span><span class="p">,</span> <span class="s">"LOW"</span><span class="p">)</span>
|
|
<span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
|
|
<span class="n">board</span><span class="o">.</span><span class="n">digitalWrite</span><span class="p">(</span><span class="mi">13</span><span class="p">,</span> <span class="s">"HIGH"</span><span class="p">)</span>
|
|
<span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
|
|
</pre></div>
|
|
|
|
<h2>
|
|
<a name="requirements" class="anchor" href="#requirements"><span class="octicon octicon-link"></span></a>Requirements:</h2>
|
|
|
|
<ul>
|
|
<li>
|
|
<a href="http://python.org/">Python</a> 2.3 or higher (Python 3.x not yet tested, but would probably work)</li>
|
|
<li>
|
|
<a href="http://pyserial.sourceforge.net/">pyserial</a> 2.6 or higher</li>
|
|
<li>Any <a href="https://www.sparkfun.com/categories/242">Arduino compatible microcontroller</a> with at least 14KB of flash memory </li>
|
|
</ul><h2>
|
|
<a name="setup" class="anchor" href="#setup"><span class="octicon octicon-link"></span></a>Setup:</h2>
|
|
|
|
<ol>
|
|
<li>Run <code>setup.py build install</code> to install the library</li>
|
|
<li>Verify that your Arduino board communicates at the baud rate specified in the
|
|
<code>setup()</code> function (line 348) in <code>prototype.ino</code>. Change it there if necessary.</li>
|
|
<li>Load the <code>prototype.ino</code> sketch onto your Arduino board, using the Arduino IDE.</li>
|
|
<li>Set up some kind of serial I/O communication between the Arduino board and your computer (via physical USB cable,
|
|
bluetooth, xbee, etc + associated drivers)</li>
|
|
<li>Add <code>from Arduino import Arduino</code> into your python script to communicate with your Arduino</li>
|
|
</ol><p>For a collection of examples, see <code>examples.py</code>. This file contains methods which replicate
|
|
the functionality of many Arduino demo sketches. </p>
|
|
|
|
<h2>
|
|
<a name="testing" class="anchor" href="#testing"><span class="octicon octicon-link"></span></a>Testing:</h2>
|
|
|
|
<p>The <code>tests</code> directory contains some basic tests for the library. Extensive code coverage is a bit difficult to expect for every release, since a positive test involves actually
|
|
connecting and issuing commands to a live Arduino, hosting any hardware
|
|
required to test a particular function. But a core of basic communication tests
|
|
should at least be maintained here and used before merging into the <code>master</code> branch.</p>
|
|
|
|
<p>After installation, the interactive tests can be run from the source directory:</p>
|
|
|
|
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>python tests/test_main.py
|
|
</pre></div>
|
|
|
|
<p>Automated tests can be run from the source directory with:</p>
|
|
|
|
<div class="highlight highlight-bash"><pre><span class="nv">$ </span>python tests/test_arduino.py
|
|
</pre></div>
|
|
|
|
<h2>
|
|
<a name="classes" class="anchor" href="#classes"><span class="octicon octicon-link"></span></a>Classes</h2>
|
|
|
|
<ul>
|
|
<li>
|
|
<code>Arduino(baud)</code> - Set up communication with currently connected and powered
|
|
Arduino. </li>
|
|
</ul><div class="highlight highlight-python"><pre><span class="n">board</span> <span class="o">=</span> <span class="n">Arduino</span><span class="p">(</span><span class="s">"9600"</span><span class="p">)</span> <span class="c">#Example</span>
|
|
</pre></div>
|
|
|
|
<p>The device name / COM port of the connected Arduino will be auto-detected.
|
|
If there are more than one Arduino boards connected,
|
|
the desired COM port can be also be passed as an optional argument:</p>
|
|
|
|
<div class="highlight highlight-python"><pre><span class="n">board</span> <span class="o">=</span> <span class="n">Arduino</span><span class="p">(</span><span class="s">"9600"</span><span class="p">,</span> <span class="n">port</span> <span class="o">=</span> <span class="s">"COM3"</span><span class="p">)</span> <span class="c">#Windows example</span>
|
|
</pre></div>
|
|
|
|
<div class="highlight highlight-python"><pre><span class="n">board</span> <span class="o">=</span> <span class="n">Arduino</span><span class="p">(</span><span class="s">"9600"</span><span class="p">,</span> <span class="n">port</span> <span class="o">=</span> <span class="s">"/dev/tty.usbmodemfa141"</span><span class="p">)</span> <span class="c">#OSX example</span>
|
|
</pre></div>
|
|
|
|
<p>A time-out for reading from the Arduino can also be specified as an optional
|
|
argument:</p>
|
|
|
|
<div class="highlight highlight-python"><pre><span class="n">board</span> <span class="o">=</span> <span class="n">Arduino</span><span class="p">(</span><span class="s">"9600"</span><span class="p">,</span> <span class="n">timeout</span> <span class="o">=</span> <span class="mi">2</span><span class="p">)</span> <span class="c">#Serial reading functions will </span>
|
|
<span class="c">#wait for no more than 2 seconds</span>
|
|
</pre></div>
|
|
|
|
<h2>
|
|
<a name="methods" class="anchor" href="#methods"><span class="octicon octicon-link"></span></a>Methods</h2>
|
|
|
|
<p><strong>Digital I/O</strong></p>
|
|
|
|
<ul>
|
|
<li>
|
|
<code>Arduino.digitalWrite(pin_number, state)</code> turn digital pin on/off</li>
|
|
<li>
|
|
<code>Arduino.digitalRead(pin_number)</code> read state of a digital pin</li>
|
|
</ul><div class="highlight highlight-python"><pre><span class="c">#Digital read / write example</span>
|
|
<span class="n">board</span><span class="o">.</span><span class="n">digitalWrite</span><span class="p">(</span><span class="mi">13</span><span class="p">,</span> <span class="s">"HIGH"</span><span class="p">)</span> <span class="c">#Set digital pin 13 voltage</span>
|
|
<span class="n">state_1</span> <span class="o">=</span> <span class="n">board</span><span class="o">.</span><span class="n">digitalRead</span><span class="p">(</span><span class="mi">13</span><span class="p">)</span> <span class="c">#Will return integer 1</span>
|
|
<span class="n">board</span><span class="o">.</span><span class="n">digitalWrite</span><span class="p">(</span><span class="mi">13</span><span class="p">,</span> <span class="s">"LOW"</span><span class="p">)</span> <span class="c">#Set digital pin 13 voltage</span>
|
|
<span class="n">state_2</span> <span class="o">=</span> <span class="n">board</span><span class="o">.</span><span class="n">digitalRead</span><span class="p">(</span><span class="mi">13</span><span class="p">)</span> <span class="c">#Will return integer 0</span>
|
|
</pre></div>
|
|
|
|
<ul>
|
|
<li>
|
|
<code>Arduino.pinMode(pin_number, io_mode)</code> set pin I/O mode</li>
|
|
<li>
|
|
<code>Arduino.pulseIn(pin_number, state)</code> measures a pulse<br>
|
|
</li>
|
|
<li>
|
|
<code>Arduino.pulseIn_set(pin_number, state)</code> measures a pulse, with preconditioning</li>
|
|
</ul><div class="highlight highlight-python"><pre><span class="c">#Digital mode / pulse example</span>
|
|
<span class="n">board</span><span class="o">.</span><span class="n">pinMode</span><span class="p">(</span><span class="mi">7</span><span class="p">,</span> <span class="s">"INPUT"</span><span class="p">)</span> <span class="c">#Set digital pin 7 mode to INPUT</span>
|
|
<span class="n">duration</span> <span class="o">=</span> <span class="n">board</span><span class="o">.</span><span class="n">pulseIn</span><span class="p">(</span><span class="mi">7</span><span class="p">,</span> <span class="s">"HIGH"</span><span class="p">)</span> <span class="c">#Return pulse width measurement on pin 7</span>
|
|
</pre></div>
|
|
|
|
<p><strong>Analog I/O</strong></p>
|
|
|
|
<ul>
|
|
<li>
|
|
<code>Arduino.analogRead(pin_number)</code> returns the analog value</li>
|
|
<li>
|
|
<code>Arduino.analogWrite(pin_number, value)</code> sets the analog value</li>
|
|
</ul><div class="highlight highlight-python"><pre><span class="c">#Analog I/O examples</span>
|
|
<span class="n">val</span><span class="o">=</span><span class="n">board</span><span class="o">.</span><span class="n">analogRead</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span> <span class="c">#Read value on analog pin 5 (integer 0 to 1023)</span>
|
|
<span class="n">val</span> <span class="o">=</span> <span class="n">val</span> <span class="o">/</span> <span class="mi">4</span> <span class="c"># scale to 0 - 255</span>
|
|
<span class="n">board</span><span class="o">.</span><span class="n">analogWrite</span><span class="p">(</span><span class="mi">11</span><span class="p">)</span> <span class="c">#Set analog value (PWM) based on analog measurement</span>
|
|
</pre></div>
|
|
|
|
<p><strong>Shift Register</strong></p>
|
|
|
|
<ul>
|
|
<li>
|
|
<code>Arduino.shiftIn(dataPin, clockPin, bitOrder)</code> shift a byte in and returns it</li>
|
|
<li>
|
|
<code>Arduino.shiftOut(dataPin, clockPin, bitOrder, value)</code> shift the given byte out</li>
|
|
</ul><p><code>bitOrder</code> should be either <code>"MSBFIRST"</code> or <code>"LSBFIRST"</code></p>
|
|
|
|
<p><strong>Servo Library Functionality</strong>
|
|
Support is included for up to 8 servos. </p>
|
|
|
|
<ul>
|
|
<li>
|
|
<code>Arduino.Servos.attach(pin, min = 544, max = 2400)</code> Create servo instance. Only 8 servos can be used at one time. </li>
|
|
<li>
|
|
<code>Arduino.Servos.read(pin)</code> Returns the angle of the servo attached to the specified pin</li>
|
|
<li>
|
|
<code>Arduino.Servos.write(pin, angle)</code> Move an attached servo on a pin to a specified angle</li>
|
|
<li>
|
|
<code>Arduino.Servos.writeMicroseconds(pin, uS)</code> Write a value in microseconds to the servo on a specified pin</li>
|
|
<li>
|
|
<code>Arduino.Servos.detach(pin)</code> Detaches the servo on the specified pin</li>
|
|
</ul><div class="highlight highlight-python"><pre><span class="c">#Servo example</span>
|
|
<span class="n">board</span><span class="o">.</span><span class="n">Servos</span><span class="o">.</span><span class="n">attach</span><span class="p">(</span><span class="mi">9</span><span class="p">)</span> <span class="c">#declare servo on pin 9</span>
|
|
<span class="n">board</span><span class="o">.</span><span class="n">Servos</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="mi">9</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="c">#move servo on pin 9 to 0 degrees</span>
|
|
<span class="k">print</span> <span class="n">board</span><span class="o">.</span><span class="n">Servos</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="mi">9</span><span class="p">)</span> <span class="c"># should be 0</span>
|
|
<span class="n">board</span><span class="o">.</span><span class="n">Servos</span><span class="o">.</span><span class="n">detach</span><span class="p">(</span><span class="mi">9</span><span class="p">)</span> <span class="c">#free pin 9</span>
|
|
</pre></div>
|
|
|
|
<p><strong>Software Serial Functionality</strong></p>
|
|
|
|
<ul>
|
|
<li>
|
|
<code>Arduino.SoftwareSerial.begin(ss_rxPin,ss_txPin,ss_device_baud)</code> initialize software serial device on
|
|
specified pins.
|
|
Only one sofware serial device can be used at a time. Existing software serial instance will
|
|
be be overwritten by calling this method, both in Python and on the arduino board.</li>
|
|
<li>
|
|
<code>Arduino.SoftwareSerial.write(data)</code> send data using the arduino 'write' function to the existing software
|
|
serial connection.</li>
|
|
<li>
|
|
<code>Arduino.SoftwareSerial.read()</code> returns one byte from the existing software serial connection</li>
|
|
</ul><div class="highlight highlight-python"><pre><span class="c">#Software serial example</span>
|
|
<span class="n">board</span><span class="o">.</span><span class="n">SoftwareSerial</span><span class="o">.</span><span class="n">begin</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">7</span><span class="p">,</span><span class="s">"19200"</span><span class="p">)</span> <span class="c"># Start software serial for transmit only (tx on pin 7)</span>
|
|
<span class="n">board</span><span class="o">.</span><span class="n">SoftwareSerial</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">" test "</span><span class="p">)</span> <span class="c">#Send some data </span>
|
|
<span class="n">response_char</span> <span class="o">=</span> <span class="n">board</span><span class="o">.</span><span class="n">SoftwareSerial</span><span class="o">.</span><span class="n">read</span><span class="p">()</span> <span class="c">#read response character</span>
|
|
</pre></div>
|
|
|
|
<p><strong>Misc</strong></p>
|
|
|
|
<ul>
|
|
<li>
|
|
<code>Arduino.close()</code> closes serial connection to the Arduino.</li>
|
|
</ul><h2>
|
|
<a name="to-do-list" class="anchor" href="#to-do-list"><span class="octicon octicon-link"></span></a>To-do list:</h2>
|
|
|
|
<ul>
|
|
<li>Expand software serial functionality (<code>print()</code> and <code>println()</code>)</li>
|
|
<li>Add simple reset functionality that zeros out all pin values</li>
|
|
<li>Add I2C / TWI function support (Arduino <code>Wire.h</code> commands)</li>
|
|
<li>Include a wizard which generates 'prototype.ino' with selected serial baud rate and Arduino function support
|
|
(to help reduce memory requirements).</li>
|
|
<li>Multi-serial support for Arduino mega (<code>Serial1.read()</code>, etc)</li>
|
|
</ul>
|
|
</section>
|
|
</div>
|
|
|
|
<!-- FOOTER -->
|
|
<div id="footer_wrap" class="outer">
|
|
<footer class="inner">
|
|
<p class="copyright">Python-arduino-command-api maintained by <a href="https://github.com/thearn">thearn</a></p>
|
|
<p>Published with <a href="http://pages.github.com">GitHub Pages</a></p>
|
|
</footer>
|
|
</div>
|
|
|
|
|
|
|
|
</body>
|
|
</html>
|