Skip to content

Commit d8da0fc

Browse files
sdmeijersdmeijer
committed
Added ToDo
1 parent 7930226 commit d8da0fc

1 file changed

Lines changed: 162 additions & 161 deletions

File tree

‎README.md‎

Lines changed: 162 additions & 161 deletions
Original file line numberDiff line numberDiff line change
@@ -1,161 +1,162 @@
1-
# Python Arduino Command API
2-
3-
The Python Arduino Command API is a light-weight Python library for
4-
communicating with [Arduino microcontroller boards](http://www.arduino.cc/) from a connected computer using
5-
standard serial IO, either physically
6-
or wirelessly. It is written using a custom protocol, similar to [Firmata](http://firmata.org/wiki/Main_Page).
7-
8-
This allows a user to quickly protoype programs for Arduino using Python code, or to
9-
simply read/control/troubleshoot/experiment
10-
with harware connected to an Arduino board without ever having to recompile and reload sketches to the board itself.
11-
12-
Method names within the Python Arduino Command API are designed to be as close
13-
as possible to their Arduino programming language counterparts.
14-
15-
## Simple usage example (LED blink)
16-
```python
17-
#!/usr/bin/env python
18-
"""
19-
Blinks an LED on digital pin 13
20-
in 1 second intervals
21-
"""
22-
23-
from Arduino import Arduino
24-
import time
25-
26-
board = Arduino('9600') #plugged in via USB, serial com at rate 9600
27-
28-
while True:
29-
board.digitalWrite(13, "LOW")
30-
time.sleep(1)
31-
board.digitalWrite(13, "HIGH")
32-
time.sleep(1)
33-
```
34-
35-
## Requirements:
36-
- [Python](http://python.org/) 2.3 or higher (Python 3.x not yet tested, but would probably work)
37-
- [pyserial](http://pyserial.sourceforge.net/) 2.6 or higher
38-
- Any [Arduino compatible microcontroller](https://www.sparkfun.com/) with at least 14KB of flash memory
39-
40-
## Setup:
41-
1. Run `setup.py build install` to install the library
42-
2. Verify that your Arduino board communicates at the baud rate specified in the
43-
`setup()` function (line 243) in `prototype.ino`. Change it there if necessary.
44-
3. Load the `prototype.ino` sketch onto your Arduino board, using the Arduino IDE.
45-
4. Set up some kind of serial I/O communication between the Arduino board and your computer (via physical USB cable,
46-
bluetooth, xbee, etc + associated drivers)
47-
5. Add `from Arduino import Arduino` into your python script to communicate with your Arduino
48-
49-
For a collection of examples, see `examples.py`. This file contains methods which replicate
50-
the functionality of many Arduino demo sketches.
51-
52-
## Classes
53-
- `Arduino(baud)` - Set up communication with currently connected and powered
54-
Arduino.
55-
56-
```python
57-
board = Arduino("9600") #Example
58-
```
59-
60-
The device name / COM port of the connected Arduino will be auto-detected.
61-
If there are more than one Arduino boards connected,
62-
the desired COM port can be also be passed as an optional argument:
63-
64-
```python
65-
board = Arduino("9600", port = "COM3") #Windows example
66-
```
67-
```python
68-
board = Arduino("9600", port = "/dev/tty.usbmodemfa141") #OSX example
69-
```
70-
71-
A time-out for reading from the Arduino can also be specified as an optional
72-
argument:
73-
74-
```python
75-
board = Arduino("9600", timeout = 2) #Serial reading functions will
76-
#wait for no more than 2 seconds
77-
```
78-
79-
## Methods
80-
81-
**Digital I/O**
82-
83-
- `Arduino.digitalWrite(pin_number, state)` turn digital pin on/off
84-
- `Arduino.digitalRead(pin_number)` read state of a digital pin
85-
86-
```python
87-
#Digital read / write example
88-
board.digitalWrite(13, "HIGH") #Set digital pin 13 voltage
89-
state_1 = board.digitalRead(13) #Will return integer 1
90-
board.digitalWrite(13, "LOW") #Set digital pin 13 voltage
91-
state_2 = board.digitalRead(13) #Will return integer 0
92-
```
93-
94-
- `Arduino.pinMode(pin_number, io_mode)` set pin I/O mode
95-
- `Arduino.pulseIn(pin_number, state)` measures a pulse
96-
- `Arduino.pulseIn_set(pin_number, state)` measures a pulse, with preconditioning
97-
98-
```python
99-
#Digital mode / pulse example
100-
board.pinMode(7, "INPUT") #Set digital pin 7 mode to INPUT
101-
duration = board.pulseIn(7, "HIGH") #Return pulse width measurement on pin 7
102-
```
103-
104-
**Analog I/O**
105-
106-
- `Arduino.analogRead(pin_number)` returns the analog value
107-
- `Arduino.analogWrite(pin_number, value)` sets the analog value
108-
109-
```python
110-
#Analog I/O examples
111-
val=board.analogRead(5) #Read value on analog pin 5 (integer 0 to 1023)
112-
val = val / 4 # scale to 0 - 255
113-
board.analogWrite(11) #Set analog value (PWM) based on analog measurement
114-
```
115-
116-
**Servo Library Functionality**
117-
Support is included for up to 8 servos.
118-
119-
- `Arduino.Servo.attach(pin, min = 544, max = 2400)` Create servo instance. Only 8 servos can be used at one time.
120-
- `Arduino.Servo.read(pin)` Returns the angle of the servo attached to the specified pin
121-
- `Arduino.Servo.write(pin, angle)` Move an attached servo on a pin to a specified angle
122-
- `Arduino.Servo.writeMicroseconds(pin, uS)` Write a value in microseconds to the servo on a specified pin
123-
- `Arduino.Servo.detach(pin)` Detaches the servo on the specified pin
124-
125-
```python
126-
#Servo example
127-
board.Servo.attach(9) #declare servo on pin 9
128-
board.Servo.write(9, 0) #move servo on pin 9 to 0 degrees
129-
print board.Servo.read(9) # should be 0
130-
board.Servo.detach(9) #free pin 9
131-
```
132-
133-
**Software Serial Functionality**
134-
135-
- `Arduino.SoftwareSerial.begin(ss_rxPin,ss_txPin,ss_device_baud)` initialize software serial device on
136-
specified pins.
137-
Only one sofware serial device can be used at a time. Existing software serial instance will
138-
be be overwritten by calling this method, both in Python and on the arduino board.
139-
- `Arduino.SoftwareSerial.write(data)` send data using the arduino 'write' function to the existing software
140-
serial connection.
141-
- `Arduino.SoftwareSerial.read()` returns one byte from the existing software serial connection
142-
143-
```python
144-
#Software serial example
145-
board.SoftwareSerial.begin(0,7,"19200") # Start software serial for transmit only (tx on pin 7)
146-
board.SoftwareSerial.write(" test ") #Send some data
147-
response_char = board.SoftwareSerial.read() #read response character
148-
```
149-
150-
**Misc**
151-
152-
- `Arduino.close()` closes serial connection to the Arduino.
153-
154-
## To-do list:
155-
- Expand software serial functionality (`print()` and `println()`)
156-
- Add simple reset functionality that zeros out all pin values
157-
- Add I2C / TWI function support (Arduino `Wire.h` commands)
158-
- <del> Add `tone()` / `noTone()` squarewave generator support for piezo type speakers</del> currently testing code for this (thanks to Sjoerd Dirk Meijer.)
159-
- Include a wizard which generates 'prototype.ino' with selected serial baud rate and Arduino function support
160-
(to help reduce memory requirements).
161-
- Multi-serial support for Arduino mega (`Serial1.read()`, etc)
1+
# Python Arduino Command API
2+
3+
The Python Arduino Command API is a light-weight Python library for
4+
communicating with [Arduino microcontroller boards](http://www.arduino.cc/) from a connected computer using
5+
standard serial IO, either physically
6+
or wirelessly. It is written using a custom protocol, similar to [Firmata](http://firmata.org/wiki/Main_Page).
7+
8+
This allows a user to quickly protoype programs for Arduino using Python code, or to
9+
simply read/control/troubleshoot/experiment
10+
with harware connected to an Arduino board without ever having to recompile and reload sketches to the board itself.
11+
12+
Method names within the Python Arduino Command API are designed to be as close
13+
as possible to their Arduino programming language counterparts.
14+
15+
## Simple usage example (LED blink)
16+
```python
17+
#!/usr/bin/env python
18+
"""
19+
Blinks an LED on digital pin 13
20+
in 1 second intervals
21+
"""
22+
23+
from Arduino import Arduino
24+
import time
25+
26+
board = Arduino('9600') #plugged in via USB, serial com at rate 9600
27+
28+
while True:
29+
board.digitalWrite(13, "LOW")
30+
time.sleep(1)
31+
board.digitalWrite(13, "HIGH")
32+
time.sleep(1)
33+
```
34+
35+
## Requirements:
36+
- [Python](http://python.org/) 2.3 or higher (Python 3.x not yet tested, but would probably work)
37+
- [pyserial](http://pyserial.sourceforge.net/) 2.6 or higher
38+
- Any [Arduino compatible microcontroller](https://www.sparkfun.com/) with at least 14KB of flash memory
39+
40+
## Setup:
41+
1. Run `setup.py build install` to install the library
42+
2. Verify that your Arduino board communicates at the baud rate specified in the
43+
`setup()` function (line 243) in `prototype.ino`. Change it there if necessary.
44+
3. Load the `prototype.ino` sketch onto your Arduino board, using the Arduino IDE.
45+
4. Set up some kind of serial I/O communication between the Arduino board and your computer (via physical USB cable,
46+
bluetooth, xbee, etc + associated drivers)
47+
5. Add `from Arduino import Arduino` into your python script to communicate with your Arduino
48+
49+
For a collection of examples, see `examples.py`. This file contains methods which replicate
50+
the functionality of many Arduino demo sketches.
51+
52+
## Classes
53+
- `Arduino(baud)` - Set up communication with currently connected and powered
54+
Arduino.
55+
56+
```python
57+
board = Arduino("9600") #Example
58+
```
59+
60+
The device name / COM port of the connected Arduino will be auto-detected.
61+
If there are more than one Arduino boards connected,
62+
the desired COM port can be also be passed as an optional argument:
63+
64+
```python
65+
board = Arduino("9600", port = "COM3") #Windows example
66+
```
67+
```python
68+
board = Arduino("9600", port = "/dev/tty.usbmodemfa141") #OSX example
69+
```
70+
71+
A time-out for reading from the Arduino can also be specified as an optional
72+
argument:
73+
74+
```python
75+
board = Arduino("9600", timeout = 2) #Serial reading functions will
76+
#wait for no more than 2 seconds
77+
```
78+
79+
## Methods
80+
81+
**Digital I/O**
82+
83+
- `Arduino.digitalWrite(pin_number, state)` turn digital pin on/off
84+
- `Arduino.digitalRead(pin_number)` read state of a digital pin
85+
86+
```python
87+
#Digital read / write example
88+
board.digitalWrite(13, "HIGH") #Set digital pin 13 voltage
89+
state_1 = board.digitalRead(13) #Will return integer 1
90+
board.digitalWrite(13, "LOW") #Set digital pin 13 voltage
91+
state_2 = board.digitalRead(13) #Will return integer 0
92+
```
93+
94+
- `Arduino.pinMode(pin_number, io_mode)` set pin I/O mode
95+
- `Arduino.pulseIn(pin_number, state)` measures a pulse
96+
- `Arduino.pulseIn_set(pin_number, state)` measures a pulse, with preconditioning
97+
98+
```python
99+
#Digital mode / pulse example
100+
board.pinMode(7, "INPUT") #Set digital pin 7 mode to INPUT
101+
duration = board.pulseIn(7, "HIGH") #Return pulse width measurement on pin 7
102+
```
103+
104+
**Analog I/O**
105+
106+
- `Arduino.analogRead(pin_number)` returns the analog value
107+
- `Arduino.analogWrite(pin_number, value)` sets the analog value
108+
109+
```python
110+
#Analog I/O examples
111+
val=board.analogRead(5) #Read value on analog pin 5 (integer 0 to 1023)
112+
val = val / 4 # scale to 0 - 255
113+
board.analogWrite(11) #Set analog value (PWM) based on analog measurement
114+
```
115+
116+
**Servo Library Functionality**
117+
Support is included for up to 8 servos.
118+
119+
- `Arduino.Servo.attach(pin, min = 544, max = 2400)` Create servo instance. Only 8 servos can be used at one time.
120+
- `Arduino.Servo.read(pin)` Returns the angle of the servo attached to the specified pin
121+
- `Arduino.Servo.write(pin, angle)` Move an attached servo on a pin to a specified angle
122+
- `Arduino.Servo.writeMicroseconds(pin, uS)` Write a value in microseconds to the servo on a specified pin
123+
- `Arduino.Servo.detach(pin)` Detaches the servo on the specified pin
124+
125+
```python
126+
#Servo example
127+
board.Servo.attach(9) #declare servo on pin 9
128+
board.Servo.write(9, 0) #move servo on pin 9 to 0 degrees
129+
print board.Servo.read(9) # should be 0
130+
board.Servo.detach(9) #free pin 9
131+
```
132+
133+
**Software Serial Functionality**
134+
135+
- `Arduino.SoftwareSerial.begin(ss_rxPin,ss_txPin,ss_device_baud)` initialize software serial device on
136+
specified pins.
137+
Only one sofware serial device can be used at a time. Existing software serial instance will
138+
be be overwritten by calling this method, both in Python and on the arduino board.
139+
- `Arduino.SoftwareSerial.write(data)` send data using the arduino 'write' function to the existing software
140+
serial connection.
141+
- `Arduino.SoftwareSerial.read()` returns one byte from the existing software serial connection
142+
143+
```python
144+
#Software serial example
145+
board.SoftwareSerial.begin(0,7,"19200") # Start software serial for transmit only (tx on pin 7)
146+
board.SoftwareSerial.write(" test ") #Send some data
147+
response_char = board.SoftwareSerial.read() #read response character
148+
```
149+
150+
**Misc**
151+
152+
- `Arduino.close()` closes serial connection to the Arduino.
153+
154+
## To-do list:
155+
- Expand software serial functionality (`print()` and `println()`)
156+
- Add simple reset functionality that zeros out all pin values
157+
- Add I2C / TWI function support (Arduino `Wire.h` commands)
158+
- <del> Add `tone()` / `noTone()` squarewave generator support for piezo type speakers</del> currently testing code for this (thanks to Sjoerd Dirk Meijer.)
159+
- Include a wizard which generates 'prototype.ino' with selected serial baud rate and Arduino function support
160+
(to help reduce memory requirements).
161+
- Multi-serial support for Arduino mega (`Serial1.read()`, etc)
162+
- (sdmeijer) Add capacitive sensors (http://playground.arduino.cc/Code/CapacitiveSensor)

0 commit comments

Comments
 (0)