1OWFTPD(1) One-Wire File System OWFTPD(1)
2
6 owftpd - Anoymous FTP server for 1-wire access
7
9 owftpd [ -c config ] -d serialport | -u | -s [host:]port [ -p host:tcp-
10 port ]
11
13 1-Wire
14 1-wire is a wiring protocol and series of devices designed and manufac‐
15 tured by Dallas Semiconductor, Inc. The bus is a low-power low-speed
16 low-connector scheme where the data line can also provide power.
17 Each device is uniquely and unalterably numbered during manufacture.
19 There are a wide variety of devices, including memory, sensors (humid‐
20 ity, temperature, voltage, contact, current), switches, timers and data
21 loggers. More complex devices (like thermocouple sensors) can be built
22 with these basic devices. There are also 1-wire devices that have
23 encryption included.
24 The 1-wire scheme uses a single bus master and multiple slaves on the
26 same wire. The bus master initiates all communication. The slaves can
27 be individually discovered and addressed using their unique ID.
28 Bus masters come in a variety of configurations including serial, par‐
30 allel, i2c, network or USB adapters.
31 OWFS design
33 OWFS is a suite of programs that designed to make the 1-wire bus and
34 its devices easily accessible. The underlying principle is to create a
35 virtual filesystem, with the unique ID being the directory, and the
36 individual properties of the device are represented as simple files
37 that can be read and written.
38 Details of the individual slave or master design are hidden behind a
40 consistent interface. The goal is to provide an easy set of tools for a
41 software designer to create monitoring or control applications. There
42 are some performance enhancements in the implementation, including data
43 caching, parallel access to bus masters, and aggregation of device com‐
44 munication. Still the fundemental goal has been ease of use, flexibil‐
45 ity and correctness rather than speed.
46 owftpd
48 owhttpd (1) is an anonymous ftp (file-transfer-protocol) server that
49 shows the Dallas/Maxim 1-Wire bus attached to a computer. The main
50 directory shows the devices found, You can then navigate to individual
51 devices, view and set their properties.
52 owftpd (1) uses the same naming convention as owfs (1) and owhppt (1) ,
54 where the URL corresponds to the filename.
55 The ftp server is a modified version of oftpd by Shane Kerr. It serves
57 no files from the disk, only virtual files from the 1-wire bus. Secu‐
58 rity should therefore be good. Only the 1-wire bus is at risk.
59
61 These options specify the device (bus master) connecting the computer
62 to the 1-wire bus. The 1-wire slaves are connected to the 1-wire bus,
63 and the bus master connects to a port on the computer and controls the
64 1-wire bus. The bus master is either an actual physical device, the
65 kernel w1 module, or an owserver (1).
66 At least one device option is required. There is no default. More than
68 one device can be listed, and all will be used. (A logical union unless
69 you explore the /bus.n/ directories.)
70 Linux and BSD enforce a security policy restricting access to hardware
72 ports. You must have sufficient rights to access the given port or
73 access will silently fail.
74
76 port specifies a serial port, e.g. /dev/ttyS0 or an USB port accessed
77 as serial port, e.g. /dev/ttyUSB0
78 If OWFS was built with libftdi support, you may be able to use the
80 ftdi: prefix in any of the options as port to address a FTDI-based USB
81 device.
82 For details, see the FTDI ADDRESSING section.
83 -d port | --device=port (DS2480B)
85 DS2480B-based bus master (like the DS9097U or an adapter of the
86 LINK family in emulation mode). If the adapter doesn't respond,
87 a passive type (DS9907E or diode/resistor) circuit will be
88 assumed.
89 --serial_flextime | --serial_regulartime (DS2480B)
91 Changes details of bus timing (see DS2480B datasheet). Some
92 devices, like the Swart LCD cannot work with flextime.
93 --baud=1200|9600|19200|38400|57600|115200 (DS2480B,LINK,HA5)
95 Sets the initial serial port communication speed for all bus
96 masters. Not all serial devices support all speeds. You can
97 change the individual bus master speed for a device of the LINK
98 family and DS2880B in the interface/settings directory. The HA5
99 speed is set in hardware, so the command line baud rate should
100 match that rate.
101 Usually the default settings (9600 for a device of the LINK fam‐
102 ily and DS2480B ) and 115200 for the HA5 are sane and shouldn't
103 be changed.
104 --straight_polarity | --reverse_polarity (DS2480B)
106 Reverse polarity of the DS2480B output transistors? Not needed
107 for the DS9097U, but required for some other designs.
108 --link=port (LINK)
110 iButtonLink LINK adapter (all versions) in non-emulation mode.
111 Uses an ascii protocol over serial.
112 This supports the simplified ftdi:<serial number> addressing
113 scheme.
114 --ha7e=port (HA7E)
116 Embedded Data Systems HA7E adapter ( and HA7S ) in native ascii
117 mode.
118 --ha5=port | --ha5=port:a | --ha5=port:acg (HA5)
120 Embedded Data Systems HA5 mutidrop adapter in native ascii mode.
121 Up to 26 adapters can share the same port, each with an assigned
122 letter. If no letter specified, the program will scan for the
123 first response (which may be slow).
124 --checksum | --no_checksum (HA5)
126 Turn on (default) or off the checksum feature of the HA5 commu‐
127 nication.
128 --passive=port | --ha2=port | --ha3=port | --ha4b=port (Passive)
130 Passive 1-wire adapters. Powered off the serial port and using
131 passive electrical components (resitors and diodes).
132 --8bit | --6bit (Passive)
134 Synthesize the 1-wire waveforme using a 6-bit (default) serial
135 word, or 8-bit word. Not all UART devices support 6 bit opera‐
136 tion.
137 --timeout_serial=5
139 Timeout (in seconds) for all serial communications. 5 second
140 default. Can be altered dynamically under /settings/time‐
141 out/serial
142
144 The only supported true USB bus masters are based on the DS2490 chip.
145 The most common is the DS9490R which has an included 1-wire ID slave
146 with family code 81.
147 There are also bus masters based on the serial chip with a USB to
149 serial conversion built in. These are supported by the serial bus mas‐
150 ter protocol.
151 -u | --usb
153 DS2490 based bus master (like the DS9490R).
154 -u2 | --usb=2
156 Use the second USB bus master. (The order isn't predicatble,
157 however, since the operating system does not consistently order
158 USB devices).
159 -uall | --usb=ALL
161 Use all the USB devices.
162 --usb_flextime | --usb_regulartime
164 Changes the details of 1-wire waveform timing for certain net‐
165 work configurations.
166 --altusb
168 Willy Robion's alternative USB timing.
169 --timeout_usb=5
171 Timeout for USB communications. This has a 5 second default and
172 can be changed dynamically under /settings/timeout/usb
173
175 I2C is 2 wire protocol used for chip-to-chip communication. The bus
176 masters: DS2482-100, DS2482-101 and DS2482-800 can specify (via pin
177 voltages) a subset of addresses on the i2c bus. Those choices are
178 i2c_address
180 0,1,2,3
182 0x18,0x19,0x1A,0x1B
183 4,5,6,7
185 0x1C,0x1D,0x1E,0x1F (DS2482-800 only)
186 port for i2c masters have the form /dev/i2c-0, /dev/i2c-1, ...
188 -d port | --device=port
190 This simple form only permits a specific port and the first
191 available i2c_address
192 --i2c=port | --i2c=port:i2c_address | --i2c=port:ALL
194 Specific i2c port and the i2c_address is either the first, spe‐
195 cific, or all or them. The i2c_address is 0,1,2,...
196 --i2c | --i2c=: | --i2c=ALL:ALL
198 Search the available i2c buses for either the first, the first,
199 or every i2c adapter.
200 The DS2482-800 masters 8 1-wire buses and so will generate 8 /bus.n
202 entries.
203
205 These bus masters communicate via the tcp/ip network protocol and so
206 can be located anywhere on the network. The network_address is of the
207 form tcp_address:port
208 E.g. 192.168.0.1:3000 or localhost:3000
210 --link=network_address
212 LinkHubE network LINK adapter by iButtonLink
213 --ha7net=network_address | --ha7net
215 HA7Net network 1-wire adapter with specified tcp address or dis‐
216 covered by udp multicast. By Embedded Data Systems
217 --timeout_ha7=60 specific timeout for HA7Net communications (60
218 second default).
219 --etherweather=network_address
221 Etherweather adapter
222 -s network_address | --server=network_address
224 Location of an owserver (1) program that talks to the 1-wire
225 bus. The default port is 4304.
226 --timeout_network=5
228 Timeout for network bus master communications. This has a 1 sec‐
229 ond default and can be changed dynamically under /settings/time‐
230 out/network
231
233 Used for testing and development. No actual hardware is needed. Useful
234 for separating the hardware development from the rest of the software
235 design.
236 devices
238 is a list of comma-separated 1-wire devices in the following
239 formats. Note that a valid CRC8 code is created automatically.
240 10,05,21
242 Hexidecimal family codes (the DS18S20, DS2405 and DS1921 in this
243 example).
244 10.12AB23431211
246 A more complete hexidecimal unique address. Useful when an
247 actual hardware device should be simulated.
248 DS2408,DS2489
250 The 1-wire device name. (Full ID cannot be speciifed in this
251 format).
252 --fake=devices
254 Random address and random values for each read. The device ID is
255 also random (unless specified).
256 --temperature_low=12 --temperature_high=44
258 Specify the temperature limits for the fake adapter simulation.
259 These should be in the same temperature scale that is specified
260 in the command line. It is possible to change the limits dynami‐
261 cally for each adapter under /bus.x/interface/settings/simu‐
262 lated/[temperature_low|temperature_high]
263 --tester=devices
265 Predictable address and predictable values for each read. (See
266 the website for the algorhythm).
267
269 This a linux-specific option for using the operating system's access to
270 bus masters. Root access is required and the implementation was still
271 in progress as of owfs v2.7p12 and linux 2.6.30.
272 Bus masters are recognized and added dynamically. Details of the physi‐
274 cal bus master are not accessible, bu they include USB, i2c and a num‐
275 ber of GPIO designs on embedded boards.
276 Access is restrict to superuser due to the netlink broadcast protocol
278 employed by w1. Multitasking must be configured (threads) on the compi‐
279 lation.
280 --w1 Use the linux kernel w1 virtual bus master.
282 --timeout_w1=10
284 Timeout for w1 netlink communications. This has a 10 second
285 default and can be changed dynamically under /settings/time‐
286 out/w1
287
289 FTDI is a brand of USB-to-serial chips which are very common. If your
290 serial device is connected via a USB serial dongle based on a FTDI
291 chip, or if your adapter uses a built-in FTDI USB chip (for example,
292 the LinkUSB), you can use this FTDI addressing.
293 The main benefit with this mode of access is that we can decrease the
295 communication delay, yielding twice as fast 1-Wire communication in
296 many cases.
297 The following values for port can be used to identify a specific FTDI
299 port in several of the serial devices options.
300 Note that this requires that OWFS is built with libftdi support, which
301 might not be the case in standard repositories.
302 ftdi:d:<device-node>
304 path of bus and device-node (e.g. "003/001") within usb device
305 tree (usually at /proc/bus/usb/ or /dev/bus/usb/)
306 ftdi:i:<vendor>:<product>
308 first device with given vendor and product id, ids can be deci‐
309 mal, octal (preceded by "0") or hex (preceded by "0x")
310 ftdi:i:<vendor>:<product>:<index>
312 as above with index being the number of the device (starting
313 with 0) if there are more than one
314 ftdi:s:<vendor>:<product>:<serial number>
316 the device with given vendor id, product id and serial number
317 string
318 The above formats are parsed fully by libftdi (minus the ftdi: prefix).
320 Simplified device serial-only support
322 An additional format is supported, for certain bus types. This only
323 specifies the USB serial number.
324 ftdi:<serial number>
326 Identifies a FTDI device by serial number only. Currently, this
327 is only valid for the VID/PID found on the LinkUSB (i.e.
328 --link). Note that those VID/PID's are the default for any
329 FT232R device, and in no way exclusive to LinkUSB.
330 Permsissions
332 In order to run owserver (1) without root privileges - as you should,
333 you must have sufficient permissions to the raw USB node your adapter
334 is connected to e.g. "003/001" (usually at /proc/bus/usb/ or
335 /dev/bus/usb/).
336 An easy way to achieve this would be using chown (1):
338 sudo chown :<your user> /dev/bus/usb/003/001
340 changes the group of the raw USB node "003/001" from default
341 "root" to "<your user>"
342 You can also write a udev (1) rule for your adapter:
344 SUBSYSTEM=="usb", DRIVER=="usb", ATTR{idVendor}=="0403", ATTR{idProd‐
346 uct}=="6001", ATTR{serial}=="AK0048A0", GROUP="owsrv"
347 saved as a file e.g. "10-FTDI-LinkUSB.rules" in
348 "/etc/udev/rules.d/", this rule will automate the process of
349 changing the group to "owsrv" of the raw USB node the LinkUSB
350 adapter with S/N:AK0048A0 is connected to.
351 Serial USB node
353 Communication in FTDI mode accesses the RAW USB node and NOT the serial
354 USB node your OS might have created automatically e.g. /dev/ttyUSB0.
355 As a side effect, if existing, the serial USB node e.g. /dev/ttyUSB0 is
356 removed on successful starting of owserver (1). After it's termination
357 un- and re-plugging the adapter, or un- and reloading of the module
358 ftdi_sio will recreate the serial USB node.
359 Finding FTDI related information on your USB adapter
361 owusbprobe is THE tool to find the information needed for direct FTDI
362 addressing
363 However this tool might not yet be packaged in your version. Alterna‐
364 tively you can also use lsusb to find the usb node your adapter is con‐
365 nected to, and then use lsusb again on this very node:
366 sudo lsusb -D /path/to/your/raw/USB/device/node |egrep "idVen‐
368 dor|idProduct|iSerial"
369 sudo is necessary to get the value of iSerial field, if the per‐
370 missions are still unchanged
371 Examples FTDI addressing
373 owserver -d ftdi:s:0x0403:0x6001:A800bXHr
374 starts owserver with a LinkUSB
375 (VID:0x0403,PID:0x6001,S/N:A800bXHr) as bus master in DS2480B-
376 based emulation mode with direct FTDI access
377 owserver --link=ftdi:A800bXHr
379 starts owserver with a LinkUSB (S/N:A800bXHr) as bus master
380 identified by serial number only in native mode with direct FTDI
381 access
382
384 -p host:portnum
385 (Optional) Sets the tcp port the ftp server runs on. Access with the
386 URL ftp://anonymous@servernameoripaddress:portnum
387 The well known ftp port, 21, will be used by default. Since this port
389 number is in the restricted range, special permission is usually
390 required.
391
393 -C --Celsius
394 -F --Fahrenheit
395 -K --Kelvin
396 -R --Rankine
397 Temperature scale used for data output. Celsius is the default.
398 Can also be changed within the program at /settings/units/tempera‐
400 ture_scale
401
403 --mbar (default)
404 --atm
405 --mmHg
406 --inHg
407 --psi
408 --Pa
409 Pressure scale used for data output. Millibar is the default.
410 Can also be changed within the program at /settings/units/pres‐
412 sure_scale
413
416 Choose the representation of the 1-wire unique identifiers. OWFS uses
417 these identifiers as unique directory names.
418 Although several display formats are selectable, all must be in family-
420 id-crc8 form, unlike some other programs and the labelling on iButtons,
421 which are crc8-id-family form.
422 -f --format="f[.]i[[.]c]"
424 Display format for the 1-wire devices. Each device has a 8byte address,
425 consisting of:
426 f family code, 1 byte
428 i ID number, 6 bytes
430 c CRC checksum, 1 byte
432 Possible formats are f.i (default, 01.A1B2C3D4E5F6), fi fic f.ic f.i.c
434 and fi.c
435 All formats are accepted as input, but the output will be in the speci‐
437 fied format.
438 The address elements can be retrieved from a device entry in owfs by
440 the family, id and crc8 properties, and as a whole with address. The
441 reversed id and address can be retrieved as r_id and r_address.
442
444 -r --readonly
445 -w --write
446 Do we allow writing to the 1-wire bus (writing memory, setting
447 switches, limits, PIOs)? The write option is available for symmetry,
448 it's the default.
449 -P --pid-file filename
451 Places the PID -- process ID of owfs into the specified filename. Use‐
452 ful for startup scripts control.
453 --background | --foreground
455 Whether the program releases the console and runs in the background
456 after evaluating command line options. background is the default.
457 --error_print=0|1|2|3
459 =0 default mixed destination: stderr foreground / syslog background
460 =1 syslog only
462 =2 stderr only
464 =3 /dev/null (quiet mode).
466 --error_level=0..9
468 =0 default errors only
469 =1 connections/disconnections
471 =2 all high level calls
473 =3 data summary for each call
475 =4 details level
477 >4 debugging chaff
479 --error_level=9 produces a lot of output
481
483 -c file | --configuration file
484 Name of an owfs (5) configuration file with more command line parame‐
485 ters
486
489 See also this man page and the web site http://www.owfs.org
490 -h --help=[device|cache|program|job|temperature]
492 Shows basic summary of options.
493 device 1-wire bus master options
495 cache cache and communication size and timing
497 program
499 mountpoint or TCP server settings
500 job control and debugging options
502 temperature
504 Unique ID display format and temperature scale
505 -V --version
507 Version of this program and related libraries.
508
510 Timeouts for the bus masters were previously listed in Device options.
511 Timeouts for the cache affect the time that data stays in memory.
512 Default values are shown.
513 --timeout_volatile=15
515 Seconds until a volatile property expires in the cache. Volatile prop‐
516 erties are those (like temperature) that change on their own.
517 Can be changed dynamically at /settings/timeout/volatile
519 --timeout_stable=300
521 Seconds until a stable property expires in the cache. Stable properties
522 are those that shouldn't change unless explicitly changed. Memory con‐
523 tents for example.
524 Can be changed dynamically at /settings/timeout/stable
526 --timeout_directory=60
528 Seconds until a directory listing expires in the cache. Directory lists
529 are the 1-wire devices found on the bus.
530 Can be changed dynamically at /settings/timeout/directory
532 --timeout_presence=120
534 Seconds until the presence and bus location of a 1-wire device expires
535 in the cache.
536 Can be changed dynamically at /settings/timeout/presence
538 There are also timeouts for specific program responses:
540 --timeout_server=5
542 Seconds until the expected response from the owserver (1) is deemed
543 tardy.
544 Can be changed dynamically at /settings/timeout/server
546 --timeout_ftp=900
548 Seconds that an ftp session is kept alive.
549 Can be changed dynamically at /settings/timeout/ftp
551
553 owftpd -d /dev/ttyS0
554 Ftp server runs on default tcp port 21, serial adapter at ttyS0
555 owftpd -s littlehost:4304 --error_level=3
557 Ftp server on default port 21, from owserver (1) process on host
558 "littlehost", extensive error messages.
559
561 http://www.owfs.org
562
564 Programs
565 owfs (1) owhttpd (1) owftpd (1) owserver (1) owdir (1) owread (1)
566 owwrite (1) owpresent (1) owtap (1)
567 Configuration and testing
569 owfs (5) owtap (1) owmon (1)
570 Language bindings
572 owtcl (3) owperl (3) owcapi (3)
573 Clocks
575 DS1427 (3) DS1904(3) DS1994 (3) DS2404 (3) DS2404S (3) DS2415 (3)
576 DS2417 (3)
577 ID
579 DS2401 (3) DS2411 (3) DS1990A (3)
580 Memory
582 DS1982 (3) DS1985 (3) DS1986 (3) DS1991 (3) DS1992 (3) DS1993 (3)
583 DS1995 (3) DS1996 (3) DS2430A (3) DS2431 (3) DS2433 (3) DS2502 (3)
584 DS2506 (3) DS28E04 (3) DS28EC20 (3)
585 Switches
587 DS2405 (3) DS2406 (3) DS2408 (3) DS2409 (3) DS2413 (3) DS28EA00 (3)
588 Temperature
590 DS1822 (3) DS1825 (3) DS1820 (3) DS18B20 (3) DS18S20 (3) DS1920 (3)
591 DS1921 (3) DS1821 (3) DS28EA00 (3) DS28E04 (3)
592 Humidity
594 DS1922 (3)
595 Voltage
597 DS2450 (3)
598 Resistance
600 DS2890 (3)
601 Multifunction (current, voltage, temperature)
603 DS2436 (3) DS2437 (3) DS2438 (3) DS2751 (3) DS2755 (3) DS2756 (3)
604 DS2760 (3) DS2770 (3) DS2780 (3) DS2781 (3) DS2788 (3) DS2784 (3)
605 Counter
607 DS2423 (3)
608 LCD Screen
610 LCD (3) DS2408 (3)
611 Crypto
613 DS1977 (3)
614 Pressure
616 DS2406 (3) -- TAI8570
617
620 Paul Alfille (paul.alfille@gmail.com)
621OWFS Manpage 2004 OWFTPD(1)