| blob | 9784d528094bc10b08a47c5171475e2bed138428 |
1 .\" $OpenBSD: zyd.4,v 1.22 2007/05/24 02:49:57 cnst Exp $
2 .\" $NetBSD: zyd.4,v 1.1 2007/06/09 11:20:55 kiyohara Exp $
3 .\"
4 .\" Copyright (c) 1997, 1998, 1999
5 .\" Bill Paul <wpaul@ctr.columbia.edu>. All rights reserved.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\" 3. All advertising materials mentioning features or use of this software
16 .\" must display the following acknowledgement:
17 .\" This product includes software developed by Bill Paul.
18 .\" 4. Neither the name of the author nor the names of any co-contributors
19 .\" may be used to endorse or promote products derived from this software
20 .\" without specific prior written permission.
21 .\"
22 .\" THIS SOFTWARE IS PROVIDED BY Bill Paul AND CONTRIBUTORS ``AS IS'' AND
23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25 .\" ARE DISCLAIMED. IN NO EVENT SHALL Bill Paul OR THE VOICES IN HIS HEAD
26 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
27 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
28 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
29 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
30 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
31 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
32 .\" THE POSSIBILITY OF SUCH DAMAGE.
33 .\"
34 .Dd May 28, 2007
35 .Dt ZYD 4
36 .Os
37 .Sh NAME
38 .Nm zyd
39 .Nd ZyDAS ZD1211/ZD1211B USB IEEE 802.11b/g wireless network device
40 .Sh SYNOPSIS
41 .Cd "zyd* at uhub? port ?"
42 .Sh DESCRIPTION
43 The
44 .Nm
45 driver provides support for wireless network adapters based around
46 the ZyDAS ZD1211 and ZD1211B USB chips.
47 .Pp
48 These are the modes the
49 .Nm
50 driver can operate in:
51 .Bl -tag -width "IBSS-masterXX"
52 .It BSS mode
53 Also known as
54 .Em infrastructure
55 mode, this is used when associating with an access point, through
56 which all traffic passes.
57 This mode is the default.
58 .It monitor mode
59 In this mode the driver is able to receive packets without
60 associating with an access point.
61 This disables the internal receive filter and enables the card to
62 capture packets from networks which it wouldn't normally have access to,
63 or to scan for access points.
64 .El
65 .Pp
66 .Nm
67 supports software WEP.
68 Wired Equivalent Privacy (WEP) is the de facto encryption standard
69 for wireless networks.
70 It can be typically configured in one of three modes:
71 no encryption; 40-bit encryption; or 104-bit encryption.
72 Unfortunately, due to serious weaknesses in WEP protocol
73 it is strongly recommended that it not be used as the
74 sole mechanism to secure wireless communication.
75 WEP is not enabled by default.
76 .Sh CONFIGURATION
77 The
78 .Nm
79 driver can be configured at runtime with
80 .Xr ifconfig 8
81 or on boot with
82 .Xr ifconfig.if 5
83 using the following parameters:
84 .Bl -tag -width Ds
85 .It Cm bssid Ar bssid
86 Set the desired BSSID.
87 .It Fl bssid
88 Unset the desired BSSID.
89 The interface will automatically select a BSSID in this mode, which is
90 the default.
91 .It Cm chan Ar n
92 Set the channel (radio frequency) to be used by the driver based on
93 the given channel ID
94 .Ar n .
95 .It Fl chan
96 Unset the desired channel to be used by the driver.
97 The driver will automatically select a channel in this mode, which is
98 the default.
99 .It Cm media Ar media
100 The
101 .Nm
102 driver supports the following
103 .Ar media
104 types:
105 .Pp
106 .Bl -tag -width autoselect -compact
107 .It Cm autoselect
108 Enable autoselection of the media type and options.
109 .It Cm DS1
110 Set 802.11b DS 1Mbps operation.
111 .It Cm DS2
112 Set 802.11b DS 2Mbps operation.
113 .It Cm DS5
114 Set 802.11b DS 5.5Mbps operation.
115 .It Cm DS11
116 Set 802.11b DS 11Mbps operation.
117 .El
118 .It Cm mediaopt Ar opts
119 The
120 .Nm
121 driver supports the following media options:
122 .Bl -tag -width ibss
123 .It Cm ibss
124 Select Independent Basic Service Set (IBSS) operation.
125 .El
126 .It Fl mediaopt Ar opts
127 Disable the specified media options on the driver and return it to the
128 default mode of operation (BSS).
129 .It Cm nwid Ar id
130 Set the network ID.
131 The
132 .Ar id
133 can either be any text string up to 32 characters in length,
134 or a series of hexadecimal digits up to 64 digits.
135 An empty
136 .Ar id
137 string allows the interface to connect to any available access points.
138 By default the
139 .Nm
140 driver uses an empty string.
141 Note that network ID is synonymous with Extended Service Set ID (ESSID).
142 .It Fl nwid
143 Set the network ID to the empty string to allow the interface to connect
144 to any available access point.
145 .It Cm nwkey Ar key
146 Enable WEP encryption using the specified
147 .Ar key .
148 The
149 .Ar key
150 can either be a string, a series of hexadecimal digits (preceded by
151 .Sq 0x ) ,
152 or a set of keys of the form
153 .Dq n:k1,k2,k3,k4 ,
154 where
155 .Sq n
156 specifies which of the keys will be used for transmitted packets,
157 and the four keys,
158 .Dq k1
159 through
160 .Dq k4 ,
161 are configured as WEP keys.
162 If a set of keys is specified, a comma
163 .Pq Sq \&,
164 within the key must be escaped with a backslash.
165 Note that if multiple keys are used, their order must be the same within
166 the network.
167 .Nm
168 is capable of using both 40-bit (5 characters or 10 hexadecimal digits)
169 or 104-bit (13 characters or 26 hexadecimal digits) keys.
170 .It Fl nwkey
171 Disable WEP encryption.
172 This is the default mode of operation.
173 .El
174 .Sh HARDWARE
175 The following devices are known to be supported by the
176 .Nm
177 driver:
178 .Pp
179 .Bl -tag -width Ds -offset indent -compact
180 .It 3COM 3CRUSB10075
181 .It Acer WLAN-G-US1
182 .It Airlink+ AWLL3025
183 .It Airlink 101 AWLL3026
184 .It AOpen 802.11g WL54
185 .It Asus A9T integrated wirless
186 .It Asus WL-159g
187 .It Belkin F5D7050 v.4000
188 .It Billion BiPAC 3011G
189 .It Buffalo WLI-U2-KG54L
190 .It CC\*[Am]C WL-2203B
191 .It DrayTek Vigor 550
192 .It Edimax EW-7317UG
193 .It Edimax EW-7317LDG
194 .It Fiberline Networks WL-43OU
195 .It iNexQ UR055g
196 .It Linksys WUSBF54G
197 .It Longshine LCS-8131G3
198 .It MSI US54SE
199 .It Philips SNU5600
200 .It Planet WL-U356
201 .It Planex GW-US54GZ
202 .It Planex GW-US54GZL
203 .It Planex GW-US54Mini
204 .It Safecom SWMULZ-5400
205 .It Sagem XG 760A
206 .It Sagem XG 76NA
207 .It Sandberg Wireless G54 USB
208 .It Sitecom WL-113
209 .It SMC SMCWUSB-G
210 .It Sweex wireless USB 54 Mbps
211 .It Tekram/Siemens USB adapter
212 .It Telegent TG54USB
213 .It Trendnet TEW-424UB
214 .It Trendnet TEW-429UB
215 .It TwinMOS G240
216 .It US Robotics 5423
217 .It X-Micro XWL-11GUZX
218 .It Yakumo QuickWLAN USB
219 .It Zonet ZEW2501
220 .It ZyXEL ZyAIR G-220
221 .El
222 .Sh FILES
223 The adapter needs some firmware files, which are loaded on demand by the
224 driver when a device is attached:
225 .Pp
226 .Bl -tag -width Ds -offset indent -compact
227 .It Pa /libdata/firmware/zyd/zyd-zd1211
228 .It Pa /libdata/firmware/zyd/zyd-zd1211b
229 .El
230 See
231 .Xr firmload 9
232 for how to change this.
233 .Sh EXAMPLES
234 The following
235 .Xr ifconfig.if 5
236 example configures zyd0 to join whatever network is available on boot,
237 using WEP key
238 .Dq 0x1deadbeef1 ,
239 channel 11:
240 .Bd -literal -offset indent
241 inet 192.168.1.1 netmask 255.255.255.0 nwkey 0x1deadbeef1 chan 11
242 .Ed
243 .Pp
244 Configure zyd0 for WEP, using hex key
245 .Dq 0x1deadbeef1 :
246 .Bd -literal -offset indent
247 # ifconfig zyd0 nwkey 0x1deadbeef1
248 .Ed
249 .Pp
250 Return zyd0 to its default settings:
251 .Bd -literal -offset indent
252 # ifconfig zyd0 -bssid -chan media autoselect \e
253 nwid "" -nwkey
254 .Ed
255 .Pp
256 Join an existing BSS network,
257 .Dq my_net :
258 .Bd -literal -offset indent
259 # ifconfig zyd0 192.168.0.2 netmask 0xffffff00 nwid my_net
260 .Ed
261 .Sh DIAGNOSTICS
262 .Bl -diag
263 .It "zyd%d: could not read firmware file %s (error=%d)"
264 For some reason, the driver was unable to read the firmware file from the
265 filesystem.
266 The file might be missing or corrupted.
267 .It "zyd%d: could not load firmware (error=%d)"
268 An error occurred while attempting to upload the firmware to the onboard
269 microcontroller unit.
270 .It "zyd%d: could not send command (error=%s)"
271 An attempt to send a command to the firmware failed.
272 .It "zyd%d: sorry, radio %s is not supported yet"
273 Support for the specified radio chip is not yet implemented in the driver.
274 The device will not attach.
275 .It "zyd%d: device version mismatch: 0x%x (only \*[Gt]= 43.30 supported)"
276 Early revisions of the ZD1211 chipset are not supported by this driver.
277 The device will not attach.
278 .It "zyd%d: device timeout"
279 A frame dispatched to the hardware for transmission did not complete in time.
280 The driver will reset the hardware.
281 This should not happen.
282 .El
283 .Sh SEE ALSO
284 .Xr arp 4 ,
285 .Xr ifmedia 4 ,
286 .Xr intro 4 ,
287 .Xr netintro 4 ,
288 .Xr usb 4 ,
289 .Xr ifconfig.if 5 ,
290 .Xr ifconfig 8 ,
291 .Xr firmload 9
292 .Sh AUTHORS
293 .An -nosplit
294 The
295 .Nm
296 driver was written by
297 .An Florian Stoehr Aq ich@florian-stoehr.de ,
298 .An Damien Bergamini Aq damien@openbsd.org ,
299 and
300 .An Jonathan Gray Aq jsg@openbsd.org .
301 .Sh CAVEATS
302 The
303 .Nm
304 driver does not support a lot of the functionality available in the hardware.
305 More work is required to properly support the IBSS and power management
306 features.