Home

Awesome

Python Arduino Command API

The Python Arduino Command API is a light-weight Python library for communicating with Arduino microcontroller boards from a connected computer using standard serial IO, either over a physical wire or wirelessly. It is written using a custom protocol, similar to Firmata.

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.

Method names within the Python Arduino Command API are designed to be as close as possible to their Arduino programming language counterparts

Simple usage example (LED blink)

#!/usr/bin/env python
"""
 Blinks an LED on digital pin 13
 in 1 second intervals
"""

from Arduino import Arduino
import time

board = Arduino('9600') #plugged in via USB, serial com at rate 9600
board.pinMode(13, "OUTPUT")

while True:
    board.digitalWrite(13, "LOW")
    time.sleep(1)
    board.digitalWrite(13, "HIGH")
    time.sleep(1)

Requirements:

Installation:

Either run pip install arduino-python from a command line, or run python setup.py build install from the source directory to install this library.

Setup:

  1. Verify that your Arduino board communicates at the baud rate specified in the setup() function (line 348) in prototype.ino. Change it there if necessary.
  2. Load the prototype.ino sketch onto your Arduino board, using the Arduino IDE.
  3. 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)
  4. Add from Arduino import Arduino into your python script to communicate with your Arduino

For a collection of examples, see examples.py. This file contains methods which replicate the functionality of many Arduino demo sketches.

Testing:

The tests 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 master branch.

After installation, the interactive tests can be run from the source directory:

$ python tests/test_main.py

Automated tests can be run from the source directory with:

$ python tests/test_arduino.py

Classes

board = Arduino("9600") #Example

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:

board = Arduino("9600", port="COM3") #Windows example

board = Arduino("9600", port="/dev/tty.usbmodemfa141") #OSX example

A time-out for reading from the Arduino can also be specified as an optional argument:

board = Arduino("9600", timeout=2) #Serial reading functions will
#wait for no more than 2 seconds

Methods

Digital I/O

#Digital read / write example
board.digitalWrite(13, "HIGH") #Set digital pin 13 voltage
state_1 = board.digitalRead(13) #Will return integer 1
board.digitalWrite(13, "LOW") #Set digital pin 13 voltage
state_2 = board.digitalRead(13) #Will return integer 0

#Digital mode / pulse example
board.pinMode(7, "INPUT") #Set digital pin 7 mode to INPUT
duration = board.pulseIn(7, "HIGH") #Return pulse width measurement on pin 7

Analog I/O

#Analog I/O examples
val=board.analogRead(5) #Read value on analog pin 5 (integer 0 to 1023)
val = val / 4 # scale to 0 - 255
board.analogWrite(11) #Set analog value (PWM) based on analog measurement

Shift Register

bitOrder should be either "MSBFIRST" or "LSBFIRST"

Servo Library Functionality Support is included for up to 8 servos.

#Servo example
board.Servos.attach(9) #declare servo on pin 9
board.Servos.write(9, 0) #move servo on pin 9 to 0 degrees
print board.Servos.read(9) # should be 0
board.Servos.detach(9) #free pin 9

Software Serial Functionality

#Software serial example
board.SoftwareSerial.begin(0, 7, "19200") # Start software serial for transmit only (tx on pin 7)
board.SoftwareSerial.write(" test ") #Send some data
response_char = board.SoftwareSerial.read() #read response character

EEPROM

#EEPROM read and write examples
location = 42
value = 10 # 0-255(byte)

board.EEPROM.write(location, 10) 
print(board.EEPROM.read(location))
print('EEPROM size {size}'.format(size=board.EEPROM.size()))

Misc

To-do list: