1OWFS(1)                      One-Wire File System                      OWFS(1)
2
3
4

NAME

6       owfs - 1-wire filesystem
7

SYNOPSIS

9       owfs [ -c config ] -d serialport | -u | -s [host:]port -m mountdir
10

DESCRIPTION

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
17       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
22       encryption included.
23
24       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
28       Bus masters come in a variety of configurations including serial,  par‐
29       allel, i2c, network or USB adapters.
30
31   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
35       individual properties of the device are  represented  as  simple  files
36       that can be read and written.
37
38       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
46   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
52       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
55       actual  files  are exposed, these files are virtual. Not all operations
56       are supported.  Specifically,  file  creation,  deletion,  linking  and
57       renaming  are  not  allowed. (You can link from outside to a owfs file,
58       but not the other way around).
59

Device Options (1-wire Bus Master)

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
67       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
71       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

* Serial devices

76       port specifies a serial port, e.g.  /dev/ttyS0 or an USB port  accessed
77       as serial port, e.g. /dev/ttyUSB0
78
79       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
84       -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
90       --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
94       --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
105       --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
109       --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
115       --ha7e=port (HA7E)
116              Embedded  Data Systems HA7E adapter ( and HA7S ) in native ascii
117              mode.
118
119       --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
125       --checksum | --no_checksum (HA5)
126              Turn  on (default) or off the checksum feature of the HA5 commu‐
127              nication.
128
129       --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
133       --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
138       --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

* USB devices

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
148       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
152       -u | --usb
153              DS2490 based bus master (like the DS9490R).
154
155       -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
160       -uall | --usb=ALL
161              Use all the USB devices.
162
163       --usb_flextime | --usb_regulartime
164              Changes  the  details of 1-wire waveform timing for certain net‐
165              work configurations.
166
167       --altusb
168              Willy Robion's alternative USB timing.
169
170       --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

* I2C devices

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
179       i2c_address
180
181       0,1,2,3
182              0x18,0x19,0x1A,0x1B
183
184       4,5,6,7
185              0x1C,0x1D,0x1E,0x1F (DS2482-800 only)
186
187       port for i2c masters have the form /dev/i2c-0, /dev/i2c-1, ...
188
189       -d port | --device=port
190              This  simple  form  only  permits  a specific port and the first
191              available i2c_address
192
193       --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
197       --i2c | --i2c=: | --i2c=ALL:ALL
198              Search  the available i2c buses for either the first, the first,
199              or every i2c adapter.
200
201       The DS2482-800 masters 8 1-wire buses and so  will  generate  8  /bus.n
202       entries.
203

* Network devices

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
209       E.g. 192.168.0.1:3000 or localhost:3000
210
211       --link=network_address
212              LinkHubE network LINK adapter by iButtonLink
213
214       --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
220       --etherweather=network_address
221              Etherweather adapter
222
223       -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
227       --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

* Simulated devices

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
237       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
241       10,05,21
242              Hexadecimal family codes (the DS18S20, DS2405 and DS1921 in this
243              example).
244
245       10.12AB23431211
246              A more complete  hexadecimal  unique  address.  Useful  when  an
247              actual hardware device should be simulated.
248
249       DS2408,DS2489
250              The  1-wire  device  name.  (Full ID cannot be speciifed in this
251              format).
252
253       --fake=devices
254              Random address and random values for each read. The device ID is
255              also random (unless specified).
256
257       --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
264       --tester=devices
265              Predictable  address  and predictable values for each read. (See
266              the website for the algorhythm).
267

* w1 kernel module

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
273       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
277       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
281       --w1   Use the linux kernel w1 virtual bus master.
282
283       --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

FTDI ADDRESSING

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
294       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
298       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
303       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
307       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
311       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
315       ftdi:s:<vendor>:<product>:<serial number>
316              the device with given vendor id, product id  and  serial  number
317              string
318
319       The above formats are parsed fully by libftdi (minus the ftdi: prefix).
320
321   Simplified device serial-only support
322       An  additional  format  is  supported, for certain bus types. This only
323       specifies the USB serial number.
324
325       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
331   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
337       An easy way to achieve this would be using chown (1):
338
339       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
343       You can also write a udev (1) rule for your adapter:
344
345       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
352   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
360   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
367       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
372   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
378       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

SPECIFIC OPTIONS

384   -m --mountpoint=directory_path
385       Path of a directory to mount the 1-wire file system
386
387       The mountpoint is required. There is no default.
388
389   --allow_other
390       Shorthand for fuse mount option "-o allow_other"  Allows uther users to
391       see  the fuse (owfs) mount point and file system. Requires a setting in
392       /etc/fuse.conf as well.
393
394   --fuse-opt options
395       Sends options to the fuse-mount process. Options should be quoted, e.g.
396       "
397

TEMPERATURE SCALE OPTIONS

399   -C --Celsius
400   -F --Fahrenheit
401   -K --Kelvin
402   -R --Rankine
403       Temperature scale used for data output. Celsius is the default.
404
405       Can  also  be  changed  within  the program at /settings/units/tempera‐
406       ture_scale
407

PRESSURE SCALE OPTIONS

409   --mbar (default)
410   --atm
411   --mmHg
412   --inHg
413   --psi
414   --Pa
415       Pressure scale used for data output. Millibar is the default.
416
417       Can  also  be  changed  within  the  program  at  /settings/units/pres‐
418       sure_scale
419
420

FORMAT OPTIONS

422       Choose  the  representation of the 1-wire unique identifiers. OWFS uses
423       these identifiers as unique directory names.
424
425       Although several display formats are selectable, all must be in family-
426       id-crc8 form, unlike some other programs and the labelling on iButtons,
427       which are crc8-id-family form.
428
429   -f --format="f[.]i[[.]c]"
430       Display format for the 1-wire devices. Each device has a 8byte address,
431       consisting of:
432
433       f      family code, 1 byte
434
435       i      ID number, 6 bytes
436
437       c      CRC checksum, 1 byte
438
439       Possible  formats are f.i (default, 01.A1B2C3D4E5F6), fi fic f.ic f.i.c
440       and fi.c
441
442       All formats are accepted as input, but the output will be in the speci‐
443       fied format.
444
445       The  address  elements  can be retrieved from a device entry in owfs by
446       the family, id and crc8 properties, and as a whole with  address.   The
447       reversed id and address can be retrieved as r_id and r_address.
448

JOB CONTROL OPTIONS

450   -r --readonly
451   -w --write
452       Do  we  allow  writing  to  the  1-wire  bus  (writing  memory, setting
453       switches, limits, PIOs)? The write option is  available  for  symmetry,
454       it's the default.
455
456   -P --pid-file filename
457       Places  the PID -- process ID of owfs into the specified filename. Use‐
458       ful for startup scripts control.
459
460   --background | --foreground
461       Whether the program releases the console and  runs  in  the  background
462       after evaluating command line options.  background is the default.
463
464   --error_print=0|1|2|3
465       =0     default mixed destination: stderr foreground / syslog background
466
467       =1     syslog only
468
469       =2     stderr only
470
471       =3     /dev/null (quiet mode).
472
473   --error_level=0..9
474       =0     default errors only
475
476       =1     connections/disconnections
477
478       =2     all high level calls
479
480       =3     data summary for each call
481
482       =4     details level
483
484       >4     debugging chaff
485
486       --error_level=9 produces a lot of output
487

CONFIGURATION FILE

489   -c file | --configuration file
490       Name  of  an owfs (5) configuration file with more command line parame‐
491       ters
492
493

HELP OPTIONS

495       See also this man page and the web site http://www.owfs.org
496
497   -h --help=[device|cache|program|job|temperature]
498       Shows basic summary of options.
499
500       device 1-wire bus master options
501
502       cache  cache and communication size and timing
503
504       program
505              mountpoint or TCP server settings
506
507       job    control and debugging options
508
509       temperature
510              Unique ID display format and temperature scale
511
512   -V --version
513       Version of this program and related libraries.
514

TIME OPTIONS

516       Timeouts for the bus masters were previously listed in Device  options.
517       Timeouts  for  the  cache  affect  the  time that data stays in memory.
518       Default values are shown.
519
520   --timeout_volatile=15
521       Seconds until a volatile property expires in the cache. Volatile  prop‐
522       erties are those (like temperature) that change on their own.
523
524       Can be changed dynamically at /settings/timeout/volatile
525
526   --timeout_stable=300
527       Seconds until a stable property expires in the cache. Stable properties
528       are those that shouldn't change unless explicitly changed. Memory  con‐
529       tents for example.
530
531       Can be changed dynamically at /settings/timeout/stable
532
533   --timeout_directory=60
534       Seconds until a directory listing expires in the cache. Directory lists
535       are the 1-wire devices found on the bus.
536
537       Can be changed dynamically at /settings/timeout/directory
538
539   --timeout_presence=120
540       Seconds until the presence and bus location of a 1-wire device  expires
541       in the cache.
542
543       Can be changed dynamically at /settings/timeout/presence
544
545       There are also timeouts for specific program responses:
546
547   --timeout_server=5
548       Seconds  until  the  expected  response from the owserver (1) is deemed
549       tardy.
550
551       Can be changed dynamically at /settings/timeout/server
552
553   --timeout_ftp=900
554       Seconds that an ftp session is kept alive.
555
556       Can be changed dynamically at /settings/timeout/ftp
557

EXAMPLE

559       owfs -d /dev/ttyS0 -m /mnt/1wire
560              Bus master on serial port
561
562       owfs -F -u -m /mnt/1wire
563              USB adapter, temperatures reported in Fahrenheit
564
565       owfs -s 10.0.1.2:4304 -m /mnt/1wire
566              Connect to an owserver (1) process that was started  on  another
567              machine at tcp port 4304
568

SEE ALSO

570   Programs
571       owfs  (1)  owhttpd  (1)  owftpd  (1)  owserver (1) owdir (1) owread (1)
572       owwrite (1) owpresent (1) owtap (1)
573
574   Configuration and testing
575       owfs (5) owtap (1) owmon (1)
576
577   Language bindings
578       owtcl (3) owperl (3) owcapi (3)
579
580   Clocks
581       DS1427 (3) DS1904(3) DS1994 (3)  DS2404  (3)  DS2404S  (3)  DS2415  (3)
582       DS2417 (3)
583
584   ID
585       DS2401 (3) DS2411 (3) DS1990A (3)
586
587   Memory
588       DS1982  (3)  DS1985  (3)  DS1986  (3)  DS1991 (3) DS1992 (3) DS1993 (3)
589       DS1995 (3) DS1996 (3) DS2430A (3) DS2431  (3)  DS2433  (3)  DS2502  (3)
590       DS2506 (3) DS28E04 (3) DS28EC20 (3)
591
592   Switches
593       DS2405 (3) DS2406 (3) DS2408 (3) DS2409 (3) DS2413 (3) DS28EA00 (3)
594
595   Temperature
596       DS1822  (3)  DS1825  (3)  DS1820 (3) DS18B20 (3) DS18S20 (3) DS1920 (3)
597       DS1921 (3) DS1821 (3) DS28EA00 (3) DS28E04 (3)
598
599   Humidity
600       DS1922 (3)
601
602   Voltage
603       DS2450 (3)
604
605   Resistance
606       DS2890 (3)
607
608   Multifunction (current, voltage, temperature)
609       DS2436 (3) DS2437 (3) DS2438 (3)  DS2751  (3)  DS2755  (3)  DS2756  (3)
610       DS2760 (3) DS2770 (3) DS2780 (3) DS2781 (3) DS2788 (3) DS2784 (3)
611
612   Counter
613       DS2423 (3)
614
615   LCD Screen
616       LCD (3) DS2408 (3)
617
618   Crypto
619       DS1977 (3)
620
621   Pressure
622       DS2406 (3) -- TAI8570
623

AVAILABILITY

625       http://www.owfs.org
626

AUTHOR

628       Paul Alfille (paul.alfille@gmail.com)
629
630
631
632OWFS Manpage                         2004                              OWFS(1)
Impressum