1OWFS(1) One-Wire File System OWFS(1)
2
6 owfs - 1-wire filesystem
7
9 owfs [ -c config ] -d serialport | -u | -s [host:]port -m mountdir
10
12 1-Wire
13 1-wire is a wiring protocol and series of devices designed and manufac‐
14 tured by Dallas Semiconductor, Inc. The bus is a low-power low-speed
15 low-connector scheme where the data line can also provide power.
16 Each device is uniquely and unalterably numbered during manufacture.
18 There are a wide variety of devices, including memory, sensors (humid‐
19 ity, temperature, voltage, contact, current), switches, timers and data
20 loggers. More complex devices (like thermocouple sensors) can be built
21 with these basic devices. There are also 1-wire devices that have en‐
22 cryption included.
23 The 1-wire scheme uses a single bus master and multiple slaves on the
25 same wire. The bus master initiates all communication. The slaves can
26 be individually discovered and addressed using their unique ID.
27 Bus masters come in a variety of configurations including serial, par‐
29 allel, i2c, network or USB adapters.
30 OWFS design
32 OWFS is a suite of programs that designed to make the 1-wire bus and
33 its devices easily accessible. The underlying principle is to create a
34 virtual filesystem, with the unique ID being the directory, and the in‐
35 dividual properties of the device are represented as simple files that
36 can be read and written.
37 Details of the individual slave or master design are hidden behind a
39 consistent interface. The goal is to provide an easy set of tools for a
40 software designer to create monitoring or control applications. There
41 are some performance enhancements in the implementation, including data
42 caching, parallel access to bus masters, and aggregation of device com‐
43 munication. Still the fundamental goal has been ease of use, flexibil‐
44 ity and correctness rather than speed.
45 owfs
47 owfs (1) is the filesystem client of the OWFS family of programs. It
48 runs on linux, freebsd and Mac OS X, and requires the fuse kernel mod‐
49 ule and library. (http://fuse.sourceforge.net) which is a user-mode
50 filesystem driver.
51 Essentially, the entire 1-wire bus is mounted to a place in your
53 filesystem. All the 1-wire devices are accessible using standard file
54 operations (read, write, directory listing). The system is safe, no ac‐
55 tual files are exposed, these files are virtual. Not all operations are
56 supported. Specifically, file creation, deletion, linking and renaming
57 are not allowed. (You can link from outside to a owfs file, but not the
58 other way around).
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 ac‐
73 cess 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 as‐
88 sumed.
89 --serial_flextime | --serial_regulartime (DS2480B)
91 Changes details of bus timing (see DS2480B datasheet). Some de‐
92 vices, 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 de‐
140 fault. Can be altered dynamically under /settings/timeout/serial
141
143 The only supported true USB bus masters are based on the DS2490 chip.
144 The most common is the DS9490R which has an included 1-wire ID slave
145 with family code 81.
146 There are also bus masters based on the serial chip with a USB to se‐
148 rial conversion built in. These are supported by the serial bus master
149 protocol.
150 -u | --usb
152 DS2490 based bus master (like the DS9490R).
153 -u2 | --usb=2
155 Use the second USB bus master. (The order isn't predicatble,
156 however, since the operating system does not consistently order
157 USB devices).
158 -uall | --usb=ALL
160 Use all the USB devices.
161 --usb_flextime | --usb_regulartime
163 Changes the details of 1-wire waveform timing for certain net‐
164 work configurations.
165 --altusb
167 Willy Robion's alternative USB timing.
168 --timeout_usb=5
170 Timeout for USB communications. This has a 5 second default and
171 can be changed dynamically under /settings/timeout/usb
172
174 I2C is 2 wire protocol used for chip-to-chip communication. The bus
175 masters: DS2482-100, DS2482-101 and DS2482-800 can specify (via pin
176 voltages) a subset of addresses on the i2c bus. Those choices are
177 i2c_address
179 0,1,2,3
181 0x18,0x19,0x1A,0x1B
182 4,5,6,7
184 0x1C,0x1D,0x1E,0x1F (DS2482-800 only)
185 port for i2c masters have the form /dev/i2c-0, /dev/i2c-1, ...
187 -d port | --device=port
189 This simple form only permits a specific port and the first
190 available i2c_address
191 --i2c=port | --i2c=port:i2c_address | --i2c=port:ALL
193 Specific i2c port and the i2c_address is either the first, spe‐
194 cific, or all or them. The i2c_address is 0,1,2,...
195 --i2c | --i2c=: | --i2c=ALL:ALL
197 Search the available i2c buses for either the first, the first,
198 or every i2c adapter.
199 The DS2482-800 masters 8 1-wire buses and so will generate 8 /bus.n en‐
201 tries.
202
204 These bus masters communicate via the tcp/ip network protocol and so
205 can be located anywhere on the network. The network_address is of the
206 form tcp_address:port
207 E.g. 192.168.0.1:3000 or localhost:3000
209 --link=network_address
211 LinkHubE network LINK adapter by iButtonLink
212 --ha7net=network_address | --ha7net
214 HA7Net network 1-wire adapter with specified tcp address or dis‐
215 covered by udp multicast. By Embedded Data Systems
216 --timeout_ha7=60 specific timeout for HA7Net communications (60
217 second default).
218 --etherweather=network_address
220 Etherweather adapter
221 -s network_address | --server=network_address
223 Location of an owserver (1) program that talks to the 1-wire
224 bus. The default port is 4304.
225 --timeout_network=5
227 Timeout for network bus master communications. This has a 1 sec‐
228 ond default and can be changed dynamically under /settings/time‐
229 out/network
230
232 Used for testing and development. No actual hardware is needed. Useful
233 for separating the hardware development from the rest of the software
234 design.
235 devices
237 is a list of comma-separated 1-wire devices in the following
238 formats. Note that a valid CRC8 code is created automatically.
239 10,05,21
241 Hexadecimal family codes (the DS18S20, DS2405 and DS1921 in this
242 example).
243 10.12AB23431211
245 A more complete hexadecimal unique address. Useful when an ac‐
246 tual hardware device should be simulated.
247 DS2408,DS2489
249 The 1-wire device name. (Full ID cannot be speciifed in this
250 format).
251 --fake=devices
253 Random address and random values for each read. The device ID is
254 also random (unless specified).
255 --temperature_low=12 --temperature_high=44
257 Specify the temperature limits for the fake adapter simulation.
258 These should be in the same temperature scale that is specified
259 in the command line. It is possible to change the limits dynami‐
260 cally for each adapter under /bus.x/interface/settings/simu‐
261 lated/[temperature_low|temperature_high]
262 --tester=devices
264 Predictable address and predictable values for each read. (See
265 the website for the algorhythm).
266
268 This a linux-specific option for using the operating system's access to
269 bus masters. Root access is required and the implementation was still
270 in progress as of owfs v2.7p12 and linux 2.6.30.
271 Bus masters are recognized and added dynamically. Details of the physi‐
273 cal bus master are not accessible, bu they include USB, i2c and a num‐
274 ber of GPIO designs on embedded boards.
275 Access is restrict to superuser due to the netlink broadcast protocol
277 employed by w1. Multitasking must be configured (threads) on the compi‐
278 lation.
279 --w1 Use the linux kernel w1 virtual bus master.
281 --timeout_w1=10
283 Timeout for w1 netlink communications. This has a 10 second de‐
284 fault and can be changed dynamically under /settings/timeout/w1
285
287 FTDI is a brand of USB-to-serial chips which are very common. If your
288 serial device is connected via a USB serial dongle based on a FTDI
289 chip, or if your adapter uses a built-in FTDI USB chip (for example,
290 the LinkUSB), you can use this FTDI addressing.
291 The main benefit with this mode of access is that we can decrease the
293 communication delay, yielding twice as fast 1-Wire communication in
294 many cases.
295 The following values for port can be used to identify a specific FTDI
297 port in several of the serial devices options.
298 Note that this requires that OWFS is built with libftdi support, which
299 might not be the case in standard repositories.
300 ftdi:d:<device-node>
302 path of bus and device-node (e.g. "003/001") within usb device
303 tree (usually at /proc/bus/usb/ or /dev/bus/usb/)
304 ftdi:i:<vendor>:<product>
306 first device with given vendor and product id, ids can be deci‐
307 mal, octal (preceded by "0") or hex (preceded by "0x")
308 ftdi:i:<vendor>:<product>:<index>
310 as above with index being the number of the device (starting
311 with 0) if there are more than one
312 ftdi:s:<vendor>:<product>:<serial number>
314 the device with given vendor id, product id and serial number
315 string
316 The above formats are parsed fully by libftdi (minus the ftdi: prefix).
318 Simplified device serial-only support
320 An additional format is supported, for certain bus types. This only
321 specifies the USB serial number.
322 ftdi:<serial number>
324 Identifies a FTDI device by serial number only. Currently, this
325 is only valid for the VID/PID found on the LinkUSB (i.e.
326 --link). Note that those VID/PID's are the default for any
327 FT232R device, and in no way exclusive to LinkUSB.
328 Permsissions
330 In order to run owserver (1) without root privileges - as you should,
331 you must have sufficient permissions to the raw USB node your adapter
332 is connected to e.g. "003/001" (usually at /proc/bus/usb/ or
333 /dev/bus/usb/).
334 An easy way to achieve this would be using chown (1):
336 sudo chown :<your user> /dev/bus/usb/003/001
338 changes the group of the raw USB node "003/001" from default
339 "root" to "<your user>"
340 You can also write a udev (1) rule for your adapter:
342 SUBSYSTEM=="usb", DRIVER=="usb", ATTR{idVendor}=="0403", ATTR{idProd‐
344 uct}=="6001", ATTR{serial}=="AK0048A0", GROUP="owsrv"
345 saved as a file e.g. "10-FTDI-LinkUSB.rules" in
346 "/etc/udev/rules.d/", this rule will automate the process of
347 changing the group to "owsrv" of the raw USB node the LinkUSB
348 adapter with S/N:AK0048A0 is connected to.
349 Serial USB node
351 Communication in FTDI mode accesses the RAW USB node and NOT the serial
352 USB node your OS might have created automatically e.g. /dev/ttyUSB0.
353 As a side effect, if existing, the serial USB node e.g. /dev/ttyUSB0 is
354 removed on successful starting of owserver (1). After it's termination
355 un- and re-plugging the adapter, or un- and reloading of the module
356 ftdi_sio will recreate the serial USB node.
357 Finding FTDI related information on your USB adapter
359 owusbprobe is THE tool to find the information needed for direct FTDI
360 addressing
361 However this tool might not yet be packaged in your version. Alterna‐
362 tively you can also use lsusb to find the usb node your adapter is con‐
363 nected to, and then use lsusb again on this very node:
364 sudo lsusb -D /path/to/your/raw/USB/device/node |egrep "idVendor|id‐
366 Product|iSerial"
367 sudo is necessary to get the value of iSerial field, if the per‐
368 missions are still unchanged
369 Examples FTDI addressing
371 owserver -d ftdi:s:0x0403:0x6001:A800bXHr
372 starts owserver with a LinkUSB
373 (VID:0x0403,PID:0x6001,S/N:A800bXHr) as bus master in DS2480B-
374 based emulation mode with direct FTDI access
375 owserver --link=ftdi:A800bXHr
377 starts owserver with a LinkUSB (S/N:A800bXHr) as bus master
378 identified by serial number only in native mode with direct FTDI
379 access
380
382 -m --mountpoint=directory_path
383 Path of a directory to mount the 1-wire file system
384 The mountpoint is required. There is no default.
386 --allow_other
388 Shorthand for fuse mount option "-o allow_other" Allows uther users to
389 see the fuse (owfs) mount point and file system. Requires a setting in
390 /etc/fuse.conf as well.
391 --fuse-opt options
393 Sends options to the fuse-mount process. Options should be quoted, e.g.
394 "
395
397 -C --Celsius
398 -F --Fahrenheit
399 -K --Kelvin
400 -R --Rankine
401 Temperature scale used for data output. Celsius is the default.
402 Can also be changed within the program at /settings/units/tempera‐
404 ture_scale
405
407 --mbar (default)
408 --atm
409 --mmHg
410 --inHg
411 --psi
412 --Pa
413 Pressure scale used for data output. Millibar is the default.
414 Can also be changed within the program at /settings/units/pres‐
416 sure_scale
417
420 Choose the representation of the 1-wire unique identifiers. OWFS uses
421 these identifiers as unique directory names.
422 Although several display formats are selectable, all must be in family-
424 id-crc8 form, unlike some other programs and the labelling on iButtons,
425 which are crc8-id-family form.
426 -f --format="f[.]i[[.]c]"
428 Display format for the 1-wire devices. Each device has a 8byte address,
429 consisting of:
430 f family code, 1 byte
432 i ID number, 6 bytes
434 c CRC checksum, 1 byte
436 Possible formats are f.i (default, 01.A1B2C3D4E5F6), fi fic f.ic f.i.c
438 and fi.c
439 All formats are accepted as input, but the output will be in the speci‐
441 fied format.
442 The address elements can be retrieved from a device entry in owfs by
444 the family, id and crc8 properties, and as a whole with address. The
445 reversed id and address can be retrieved as r_id and r_address.
446
448 -r --readonly
449 -w --write
450 Do we allow writing to the 1-wire bus (writing memory, setting
451 switches, limits, PIOs)? The write option is available for symmetry,
452 it's the default.
453 -P --pid-file filename
455 Places the PID -- process ID of owfs into the specified filename. Use‐
456 ful for startup scripts control.
457 --background | --foreground
459 Whether the program releases the console and runs in the background af‐
460 ter evaluating command line options. background is the default.
461 --error_print=0|1|2|3
463 =0 default mixed destination: stderr foreground / syslog background
464 =1 syslog only
466 =2 stderr only
468 =3 /dev/null (quiet mode).
470 --error_level=0..9
472 =0 default errors only
473 =1 connections/disconnections
475 =2 all high level calls
477 =3 data summary for each call
479 =4 details level
481 >4 debugging chaff
483 --error_level=9 produces a lot of output
485
487 -c file | --configuration file
488 Name of an owfs (5) configuration file with more command line parame‐
489 ters
490
493 See also this man page and the web site http://www.owfs.org
494 -h --help=[device|cache|program|job|temperature]
496 Shows basic summary of options.
497 device 1-wire bus master options
499 cache cache and communication size and timing
501 program
503 mountpoint or TCP server settings
504 job control and debugging options
506 temperature
508 Unique ID display format and temperature scale
509 -V --version
511 Version of this program and related libraries.
512
514 Timeouts for the bus masters were previously listed in Device options.
515 Timeouts for the cache affect the time that data stays in memory. De‐
516 fault values are shown.
517 --timeout_volatile=15
519 Seconds until a volatile property expires in the cache. Volatile prop‐
520 erties are those (like temperature) that change on their own.
521 Can be changed dynamically at /settings/timeout/volatile
523 --timeout_stable=300
525 Seconds until a stable property expires in the cache. Stable properties
526 are those that shouldn't change unless explicitly changed. Memory con‐
527 tents for example.
528 Can be changed dynamically at /settings/timeout/stable
530 --timeout_directory=60
532 Seconds until a directory listing expires in the cache. Directory lists
533 are the 1-wire devices found on the bus.
534 Can be changed dynamically at /settings/timeout/directory
536 --timeout_presence=120
538 Seconds until the presence and bus location of a 1-wire device expires
539 in the cache.
540 Can be changed dynamically at /settings/timeout/presence
542 There are also timeouts for specific program responses:
544 --timeout_server=5
546 Seconds until the expected response from the owserver (1) is deemed
547 tardy.
548 Can be changed dynamically at /settings/timeout/server
550 --timeout_ftp=900
552 Seconds that an ftp session is kept alive.
553 Can be changed dynamically at /settings/timeout/ftp
555
557 owfs -d /dev/ttyS0 -m /mnt/1wire
558 Bus master on serial port
559 owfs -F -u -m /mnt/1wire
561 USB adapter, temperatures reported in Fahrenheit
562 owfs -s 10.0.1.2:4304 -m /mnt/1wire
564 Connect to an owserver (1) process that was started on another
565 machine at tcp port 4304
566
568 Programs
569 owfs (1) owhttpd (1) owftpd (1) owserver (1) owdir (1) owread (1)
570 owwrite (1) owpresent (1) owtap (1)
571 Configuration and testing
573 owfs (5) owtap (1) owmon (1)
574 Language bindings
576 owtcl (3) owperl (3) owcapi (3)
577 Clocks
579 DS1427 (3) DS1904(3) DS1994 (3) DS2404 (3) DS2404S (3) DS2415 (3)
580 DS2417 (3)
581 ID
583 DS2401 (3) DS2411 (3) DS1990A (3)
584 Memory
586 DS1982 (3) DS1985 (3) DS1986 (3) DS1991 (3) DS1992 (3) DS1993 (3)
587 DS1995 (3) DS1996 (3) DS2430A (3) DS2431 (3) DS2433 (3) DS2502 (3)
588 DS2506 (3) DS28E04 (3) DS28EC20 (3)
589 Switches
591 DS2405 (3) DS2406 (3) DS2408 (3) DS2409 (3) DS2413 (3) DS28EA00 (3)
592 Temperature
594 DS1822 (3) DS1825 (3) DS1820 (3) DS18B20 (3) DS18S20 (3) DS1920 (3)
595 DS1921 (3) DS1821 (3) DS28EA00 (3) DS28E04 (3)
596 Humidity
598 DS1922 (3)
599 Voltage
601 DS2450 (3)
602 Resistance
604 DS2890 (3)
605 Multifunction (current, voltage, temperature)
607 DS2436 (3) DS2437 (3) DS2438 (3) DS2751 (3) DS2755 (3) DS2756 (3)
608 DS2760 (3) DS2770 (3) DS2780 (3) DS2781 (3) DS2788 (3) DS2784 (3)
609 Counter
611 DS2423 (3)
612 LCD Screen
614 LCD (3) DS2408 (3)
615 Crypto
617 DS1977 (3)
618 Pressure
620 DS2406 (3) -- TAI8570
621
623 http://www.owfs.org
624
626 Paul Alfille (paul.alfille@gmail.com)
627OWFS Manpage 2004 OWFS(1)