github/Python-Arduino-Command-API
1
1
Fork 0
mirror of https://github.com/thearn/Python-Arduino-Command-API.git synced 2026-01-11 07:28:02 -05:00
Code Issues Packages Projects Releases Wiki Activity

added instructions for pip

Browse Source
This commit is contained in:
Tristan
2013-10-10 16:39:55 -04:00
parent d4a5aa5b9b
commit 4cc3d0de57
1 changed files with 30 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

57
README.md
View File

@@ -1,15 +1,15 @@
# Python Arduino Command API
The Python Arduino Command API is a light-weight Python library for
communicating with [Arduino microcontroller boards](http://www.arduino.cc/) from a connected computer using
standard serial IO, either physically
or wirelessly. It is written using a custom protocol, similar to [Firmata](http://firmata.org/wiki/Main_Page).
The Python Arduino Command API is a light-weight Python library for
communicating with [Arduino microcontroller boards](http://www.arduino.cc/) from a connected computer using
standard serial IO, either physically
or wirelessly. It is written using a custom protocol, similar to [Firmata](http://firmata.org/wiki/Main_Page).
This allows a user to quickly protoype programs for Arduino using Python code, or to
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
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)
@@ -35,19 +35,22 @@ while True:
## Requirements:
- [Python](http://python.org/) 2.3 or higher (Python 3.x not yet tested, but would probably work)
- [pyserial](http://pyserial.sourceforge.net/) 2.6 or higher
- Any [Arduino compatible microcontroller](https://www.sparkfun.com/categories/242) with at least 14KB of flash memory
- Any [Arduino compatible microcontroller](https://www.sparkfun.com/categories/242) with at least 14KB of flash memory
## Installation:
Either run `pip install Arduino` from a command line, or run `python setup.py
build install` from the source directory to install this library.
## Setup:
1. Run `setup.py build install` to install the library
2. Verify that your Arduino board communicates at the baud rate specified in the
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.
3. Load the `prototype.ino` sketch onto your Arduino board, using the Arduino IDE.
4. Set up some kind of serial I/O communication between the Arduino board and your computer (via physical USB cable,
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)
5. Add `from Arduino import Arduino` into your python script to communicate with your Arduino
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.
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
@@ -66,14 +69,14 @@ $ python tests/test_arduino.py
```
## Classes
- `Arduino(baud)` - Set up communication with currently connected and powered
Arduino.
- `Arduino(baud)` - Set up communication with currently connected and powered
Arduino.
```python
board = Arduino("9600") #Example
```
The device name / COM port of the connected Arduino will be auto-detected.
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:
@@ -84,11 +87,11 @@ 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
A time-out for reading from the Arduino can also be specified as an optional
argument:
```python
board = Arduino("9600", timeout = 2) #Serial reading functions will
board = Arduino("9600", timeout = 2) #Serial reading functions will
#wait for no more than 2 seconds
```
@@ -108,7 +111,7 @@ state_2 = board.digitalRead(13) #Will return integer 0
```
- `Arduino.pinMode(pin_number, io_mode)` set pin I/O mode
- `Arduino.pulseIn(pin_number, state)` measures a pulse
- `Arduino.pulseIn(pin_number, state)` measures a pulse
- `Arduino.pulseIn_set(pin_number, state)` measures a pulse, with preconditioning
```python
@@ -137,9 +140,9 @@ board.analogWrite(11) #Set analog value (PWM) based on analog measurement
`bitOrder` should be either `"MSBFIRST"` or `"LSBFIRST"`
**Servo Library Functionality**
Support is included for up to 8 servos.
Support is included for up to 8 servos.
- `Arduino.Servos.attach(pin, min = 544, max = 2400)` Create servo instance. Only 8 servos can be used at one time.
- `Arduino.Servos.attach(pin, min = 544, max = 2400)` Create servo instance. Only 8 servos can be used at one time.
- `Arduino.Servos.read(pin)` Returns the angle of the servo attached to the specified pin
- `Arduino.Servos.write(pin, angle)` Move an attached servo on a pin to a specified angle
- `Arduino.Servos.writeMicroseconds(pin, uS)` Write a value in microseconds to the servo on a specified pin
@@ -155,18 +158,18 @@ board.Servos.detach(9) #free pin 9
**Software Serial Functionality**
- `Arduino.SoftwareSerial.begin(ss_rxPin,ss_txPin,ss_device_baud)` initialize software serial device on
specified pins.
Only one sofware serial device can be used at a time. Existing software serial instance will
- `Arduino.SoftwareSerial.begin(ss_rxPin,ss_txPin,ss_device_baud)` 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.
- `Arduino.SoftwareSerial.write(data)` send data using the arduino 'write' function to the existing software
- `Arduino.SoftwareSerial.write(data)` send data using the arduino 'write' function to the existing software
serial connection.
- `Arduino.SoftwareSerial.read()` returns one byte from the existing software serial connection
```python
#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
board.SoftwareSerial.write(" test ") #Send some data
response_char = board.SoftwareSerial.read() #read response character
```
@@ -178,7 +181,7 @@ response_char = board.SoftwareSerial.read() #read response character
- Expand software serial functionality (`print()` and `println()`)
- Add simple reset functionality that zeros out all pin values
- Add I2C / TWI function support (Arduino `Wire.h` commands)
- Include a wizard which generates 'prototype.ino' with selected serial baud rate and Arduino function support
- Include a wizard which generates 'prototype.ino' with selected serial baud rate and Arduino function support
(to help reduce memory requirements).
- Multi-serial support for Arduino mega (`Serial1.read()`, etc)