Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 252 lines (178 sloc) 9.587 kb
64192f4 @bobbrez Updating the README and reorganizing the directory structure to be a bit...
bobbrez authored
1 # SparkFun WiFly Shield Library : alpha 2 release
764d073 Import source from alpha 1 release (http://sparkfun.com/Code/wifly/WiFly...
follower authored
2
64192f4 @bobbrez Updating the README and reorganizing the directory structure to be a bit...
bobbrez authored
3 This is a library for the Arduino-compatible [WiFly Shield](http://sparkfun.com/products/9954) available from SparkFun Electronics. The library also provides a high-level interface for the [SC16IS750 I2C/SPI-to-UART IC](http://www.sparkfun.com/products/9981) used in the WiFly shield but also available on a separate breakout board.
764d073 Import source from alpha 1 release (http://sparkfun.com/Code/wifly/WiFly...
follower authored
4
64192f4 @bobbrez Updating the README and reorganizing the directory structure to be a bit...
bobbrez authored
5 The goal with this library is to make it--as much as possible--a "drop in" replacement for the official [Arduino Ethernet library](http://www.arduino.cc/en/Reference/Ethernet). Once a wireless network is joined the library should respond in the same way as the Ethernet library. This means you should be able to take existing Ethernet examples and make them work wirelessly without too many changes.
764d073 Import source from alpha 1 release (http://sparkfun.com/Code/wifly/WiFly...
follower authored
6
64192f4 @bobbrez Updating the README and reorganizing the directory structure to be a bit...
bobbrez authored
7 # Installation
8 A good resource to start is the [Arduino Hacking Libraries](http://www.arduino.cc/en/Hacking/Libraries) article which goes in depth about how to install libraries. There are two ways to install this library, it can either be directly downloaded and unzipped or it can be cloned using Git.
764d073 Import source from alpha 1 release (http://sparkfun.com/Code/wifly/WiFly...
follower authored
9
070e51f @bobbrez Minor changes in formatting
bobbrez authored
10 ## Step 1: Check the libraries directory
64192f4 @bobbrez Updating the README and reorganizing the directory structure to be a bit...
bobbrez authored
11 For both methods, you'll need to check that you have a shared library
12 directory. It should be under the Arduino home (e.g. in OSX, it will probably be `~/Documents/Arduino/libraries`).
13 If the `libraries` directory doesn't already exist, you'll need to create it.
764d073 Import source from alpha 1 release (http://sparkfun.com/Code/wifly/WiFly...
follower authored
14
070e51f @bobbrez Minor changes in formatting
bobbrez authored
15 ## Step 2a: Add the library via Git
64192f4 @bobbrez Updating the README and reorganizing the directory structure to be a bit...
bobbrez authored
16 Use Git to clone this project into the `libraries` directory. If you've
17 never used Git before, check out the [Git Community Book](http://book.git-scm.com/).
764d073 Import source from alpha 1 release (http://sparkfun.com/Code/wifly/WiFly...
follower authored
18
070e51f @bobbrez Minor changes in formatting
bobbrez authored
19 ## Step 2b: Add the library via Archived File
64192f4 @bobbrez Updating the README and reorganizing the directory structure to be a bit...
bobbrez authored
20 Download and unzip the zip file from this GitHub project and put the
21 contents in the `libraries` directory.
764d073 Import source from alpha 1 release (http://sparkfun.com/Code/wifly/WiFly...
follower authored
22
64192f4 @bobbrez Updating the README and reorganizing the directory structure to be a bit...
bobbrez authored
23 At the end of Step 2, you should have a copy of this project at
24 `~/Documents/Arduino/libraries/WiFly`
25
070e51f @bobbrez Minor changes in formatting
bobbrez authored
26 ##Step 3: Include the library in your project
64192f4 @bobbrez Updating the README and reorganizing the directory structure to be a bit...
bobbrez authored
27 Restart the Arduino IDE if you're using it. Under the `Sketch` menu, you
28 should see a `WiFly` item in the `Import Library ...` option. If you
29 don't, recheck that the library is in the right location and that you've
e507760 @bobbrez Updating readme to show the new import scheme
bobbrez authored
30 restarted the Arduino IDE. Right now it adds a lot more then needed.
64192f4 @bobbrez Updating the README and reorganizing the directory structure to be a bit...
bobbrez authored
31
32 You can also manually add the library by adding the following to the top
33 of your sketch.
34
202c471 @bobbrez Minor changes in formatting
bobbrez authored
35 ```c
e507760 @bobbrez Updating readme to show the new import scheme
bobbrez authored
36 #include <SPI.h>
64192f4 @bobbrez Updating the README and reorganizing the directory structure to be a bit...
bobbrez authored
37 #include <WiFly.h>
38 ```
39
40 # Usage
764d073 Import source from alpha 1 release (http://sparkfun.com/Code/wifly/WiFly...
follower authored
41
121045b Updated documentation to describe how to connect to open (i.e. no passph...
follower authored
42 This is how you connect to a WPA wireless network with a passphrase
43 and use DHCP to obtain an IP address and DNS configuration:
764d073 Import source from alpha 1 release (http://sparkfun.com/Code/wifly/WiFly...
follower authored
44
202c471 @bobbrez Minor changes in formatting
bobbrez authored
45 ```c
e507760 @bobbrez Updating readme to show the new import scheme
bobbrez authored
46 #include <SPI.h>
202c471 @bobbrez Minor changes in formatting
bobbrez authored
47 #include <WiFly.h>
764d073 Import source from alpha 1 release (http://sparkfun.com/Code/wifly/WiFly...
follower authored
48
49 void setup() {
50
51 WiFly.begin();
52
53 if (!WiFly.join("ssid", "passphrase")) {
54 // Handle the failure
55 }
56
57 // Rejoice in your connection
58 }
202c471 @bobbrez Minor changes in formatting
bobbrez authored
59 ```
764d073 Import source from alpha 1 release (http://sparkfun.com/Code/wifly/WiFly...
follower authored
60
121045b Updated documentation to describe how to connect to open (i.e. no passph...
follower authored
61 If the network you want to connect to has no passphrase you can use this form:
62
92963fa @bobbrez Minor changes in formatting
bobbrez authored
63 ```c
64 if (!WiFly.join("ssid")) {
65 // Handle the failure
66 }
67 ```
121045b Updated documentation to describe how to connect to open (i.e. no passph...
follower authored
68
311eb84 Update documentation to describe WEP support.
follower authored
69 If the network you want to connect to is using WEP use this form:
70
92963fa @bobbrez Minor changes in formatting
bobbrez authored
71 ```c
72 if (!WiFly.join("NETWORK", "00112233445566778899AABBCC", WEP_MODE)) {
73 // Handle the failure
74 }
75 ```
311eb84 Update documentation to describe WEP support.
follower authored
76
77 Note the description of the WEP key from the WiFly user guide:
78
79 * Key must be EXACTLY 26 ASCII characters representing 13 bytes.
80 * In HEX format, hex digits > 9 can be either upper or lower case.
81 * "The Wifly GSX only supports “open” key mode, 128 bit keys for WEP."
82
83 Whatever connection method you use, once you have joined you can use
84 the Client and Server classes (re-implemented for the WiFly) mostly as
85 normal.
764d073 Import source from alpha 1 release (http://sparkfun.com/Code/wifly/WiFly...
follower authored
86
87 You can supply a domain name rather than an IP address for client
88 connections:
89
92963fa @bobbrez Minor changes in formatting
bobbrez authored
90 ```c
91 Client client("google.com", 80);
92 ```
764d073 Import source from alpha 1 release (http://sparkfun.com/Code/wifly/WiFly...
follower authored
93
94 You can also retrieve the current IP address with:
95
92963fa @bobbrez Minor changes in formatting
bobbrez authored
96 ```c
97 Serial.println(WiFly.ip());
98 ```
764d073 Import source from alpha 1 release (http://sparkfun.com/Code/wifly/WiFly...
follower authored
99
100 This release of the library comes with three examples:
101
102 * WiFly_Autoconnect_Terminal: reimplementation from tutorial
103 * WiFly_WebClient: Ethernet WebClient demo with small WiFly changes
104 * WiFly_WebServer: Ethernet WebServer demo with small WiFly changes
105
106 For each example you will need to modify the file "Credentials.h" to
107 supply your network's name (SSID) and passphrase.
108
3eb0462 Note addition of hardware factory reset tool in documentation.
follower authored
109 There are also some troubleshooting tools:
fb2dd46 Add reference to troubleshooting tool in documentation.
follower authored
110
111 * SpiUartTerminal: enter command mode and send commands manually
3eb0462 Note addition of hardware factory reset tool in documentation.
follower authored
112 * HardwareFactoryReset: hardware factory reset a WiFly module
764d073 Import source from alpha 1 release (http://sparkfun.com/Code/wifly/WiFly...
follower authored
113
a8243f2 Add documentation to README about requirement for library configuration.
follower authored
114
92963fa @bobbrez Minor changes in formatting
bobbrez authored
115 # Configuration
a8243f2 Add documentation to README about requirement for library configuration.
follower authored
116
117 Different revisions of the WiFly shield support different features. If
118 you are using an older revision of the shield you will need to modify
119 the value of 'SHIELD_REVISION' in the file 'Configuration.h' to
120 indicate which revision of the WiFly shield you are using. See the
121 documentation in the file for further detail.
122
123 The value defaults to the most recent revision sold at the time of
124 code release.
125
126
92963fa @bobbrez Minor changes in formatting
bobbrez authored
127 # Arduino Mega support
a4fe33d Add documentation on support for the Arduino Mega.
follower authored
128
129 This library supports using the WiFly Shield with the Arduino Mega if
130 four jumper wires are added. The following connections are required:
131
132 * Mega pin 53 to shield pin 10
133 * Mega pin 51 to shield pin 11
134 * Mega pin 50 to shield pin 12
135 * Mega pin 52 to shield pin 13
136
137 In addition, code on the Mega must not use pins 10, 11, 12, or 13.
138
139
92963fa @bobbrez Minor changes in formatting
bobbrez authored
140 # Known Issues
764d073 Import source from alpha 1 release (http://sparkfun.com/Code/wifly/WiFly...
follower authored
141
142 This is an alpha release--this means it's non-feature complete and may
143 not be entirely reliable. It has been tested with the shipped examples and
144 works in most cases.
145
146 There are some known issues:
147
311eb84 Update documentation to describe WEP support.
follower authored
148 * Connections to WEP networks have not really been tested--please try
149 it out and provide feedback. At the moment adhoc networks of any
150 type are not supported--the module supports them, the library just
151 hasn't been modified to recognise the different way the module
152 responds when connecting.
764d073 Import source from alpha 1 release (http://sparkfun.com/Code/wifly/WiFly...
follower authored
153 * Incomplete documentation.
154 * Only tested with WiFly firmware version 2.18--earlier or later
155 versions may or may not have issues. 2.20 has also been tested.
156 * Only DHCP is supported--you can't specify an IP address and DNS
157 configuration directly.
158 * There are some situations (exact cause unknown but often it seems
159 to be after initial programming) where the WiFly will fail to
160 respond to requests. You may need to power-cycle the Arduino or try
161 refreshing the page in your browser if it's acting as a server.
162 * There's a limit to how quickly you can refresh a page when acting
163 as a server--this is because the library doesn't handle dropped
164 connections well at present. You can generally tell from the lights
165 on the unit if it's busy. (This is particularly obvious when a
166 using a web browser (rather than something like 'wget') because
167 after the page is loaded the browser makes an immediate request for
168 the favicon. Once every five seconds or so should be fine depending
169 on how big the page is.
170 * None of the non-ethernet capabilities of the WiFly are yet exposed
171 e.g. network scans, signal strength information etc.
172 * The code isn't very robust for error states--in general it will
173 hang rather than return useful information.
174 * We only have a 9600 baud connection between the Arduino and WiFly
175 it should in theory be possible to be much faster.
176 * Passphrases or SSIDs that contain spaces or dollar signs ($) will
177 probably not work.
178
174e326 @bobbrez More updates to readme
bobbrez authored
179 # License
764d073 Import source from alpha 1 release (http://sparkfun.com/Code/wifly/WiFly...
follower authored
180
174e326 @bobbrez More updates to readme
bobbrez authored
181 The SparkFun WiFly Shield library is Copyright (c) 2010 by SparkFun
182 Electronics and is licensed under the LGPL.
764d073 Import source from alpha 1 release (http://sparkfun.com/Code/wifly/WiFly...
follower authored
183
174e326 @bobbrez More updates to readme
bobbrez authored
184 Examples based on the original examples from the official Arduino
185 Ethernet library are licensed under the same terms as the originals.
764d073 Import source from alpha 1 release (http://sparkfun.com/Code/wifly/WiFly...
follower authored
186
174e326 @bobbrez More updates to readme
bobbrez authored
187 'ParsedStream.h' contains a ringbuffer implementation based on one
188 originally found in the Arduino 'HardwareSerial' implementation.
764d073 Import source from alpha 1 release (http://sparkfun.com/Code/wifly/WiFly...
follower authored
189
174e326 @bobbrez More updates to readme
bobbrez authored
190 # Authors
191
192 * Chris Taylor (Original autoconnect sketch and tutorial)
193 * Philip J. Lindsay (Conversion to library)
194 * John Crouchley (1.0 updates -- see https://github.com/jcrouchley/WiFly-Shield)
195 * Bob Breznak (see https://github.com/bobbrez/WiFly-Shield for updates)
764d073 Import source from alpha 1 release (http://sparkfun.com/Code/wifly/WiFly...
follower authored
196
92963fa @bobbrez Minor changes in formatting
bobbrez authored
197 # Changelog
764d073 Import source from alpha 1 release (http://sparkfun.com/Code/wifly/WiFly...
follower authored
198
03d3f35 Add release date for alpha 2.
follower authored
199 + alpha 2 -- 17 December 2010 -- "Azalea Galaxy"
fb2dd46 Add reference to troubleshooting tool in documentation.
follower authored
200
074c6e2 Add additional features to release notes.
follower authored
201 * NOTE: New configuration location! You now need to modify the value
202 of 'SHIELD_REVISION' in the file 'Configuration.h' to
203 indicate what revision of the WiFly shield you are
204 using. See the documentation in the file for further
205 detail. The value defaults to the most recent revision sold
206 at the time of the code release.
207
c3bcd41 Reorder release notes by slightly better priority.
follower authored
208 * Added support for joining Open networks (i.e. without a passphrase or key).
094a4bf Updated release notes in README.
follower authored
209
c3bcd41 Reorder release notes by slightly better priority.
follower authored
210 * Added (untested) WEP network support.
094a4bf Updated release notes in README.
follower authored
211
212 * Modified software reboot to hopefully work more reliably.
213
074c6e2 Add additional features to release notes.
follower authored
214 * Added support for hardware reset which should be more reliable than
215 software reboot on board revisions that support it (currently only the
216 most recent revision).
217
c3bcd41 Reorder release notes by slightly better priority.
follower authored
218 * Modified command mode entry method to hopefully work more
219 reliably. Includes use of guard time as originally inspired by
220 World Mood Light.
074c6e2 Add additional features to release notes.
follower authored
221
c3bcd41 Reorder release notes by slightly better priority.
follower authored
222 * Added 'SpiUartTerminal' troubleshooting tool.
074c6e2 Add additional features to release notes.
follower authored
223
3510fbb Add hardware factory reset tool to release notes.
follower authored
224 * Added 'HardwareFactoryReset' tool to help with troubleshooting.
225
c3bcd41 Reorder release notes by slightly better priority.
follower authored
226 * Added support for further board revision feature support configuration.
227
228 * Added some debugging support.
e69abf2 Add WEP support to release notes.
follower authored
229
3510fbb Add hardware factory reset tool to release notes.
follower authored
230
764d073 Import source from alpha 1 release (http://sparkfun.com/Code/wifly/WiFly...
follower authored
231 + alpha 1 -- 31 August 2010 -- "August Gratitude"
232
233 * Change default crystal speed to match new 14MHz crystal used.
234 NOTE: People using the older 12MHz crystal will need to change
235 "USE_14_MHZ_CRYSTAL" in SpiUart.cpp to 'false'.
236
237 * Added ability to set baud rate at runtime in SpiUart class.
238 (Note: This ability to change the baudrate has not yet been propagated
239 to the WiFly class.)
240
241 * Renamed Spi.h to _Spi.h in order to avoid clashes with the other
242 library by the same name as the IDE might (and has) mistakenly
243 included ours instead of the the other one which results in
244 confusing error messages.
245
246 * Changed the case of the 'examples' directory so it gets displayed
247 in the IDE correctly.
248
249
250 + alpha 0 -- 19 May 2010 -- "Awfully Gorgeous"
251 * Initial release
Something went wrong with that request. Please try again.