Ubuntu Manpage: owfs - 1-wire filesystem

NAME

       owfs - 1-wire filesystem

SYNOPSIS

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

DESCRIPTION

1-Wire
1-wire is a wiring protocol and series of devices designed and manufactured by Dallas
Semiconductor, Inc. The bus is a low-power low-speed low-connector scheme where the data
line can also provide power.

Each device is uniquely and unalterably numbered during manufacture. There are a wide
variety of devices, including memory, sensors (humidity, temperature, voltage, contact,
current), switches, timers and data loggers. More complex devices (like thermocouple
sensors) can be built with these basic devices. There are also 1-wire devices that have
encryption included.

The 1-wire scheme uses a single bus master and multiple slaves on the same wire. The bus
master initiates all communication. The slaves can be individually discovered and
addressed using their unique ID.

Bus masters come in a variety of configurations including serial, parallel, i2c, network
or USB adapters.

OWFS design
OWFS is a suite of programs that designed to make the 1-wire bus and its devices easily
accessible. The underlying principle is to create a virtual filesystem, with the unique ID
being the directory, and the individual properties of the device are represented as simple
files that can be read and written.

Details of the individual slave or master design are hidden behind a consistent interface.
The goal is to provide an easy set of tools for a software designer to create monitoring
or control applications. There are some performance enhancements in the implementation,
including data caching, parallel access to bus masters, and aggregation of device
communication. Still the fundemental goal has been ease of use, flexibility and
correctness rather than speed.

owfs
owfs (1) is the filesystem client of the OWFS family of programs. It runs on linux,
freebsd and Mac OS X, and requires the fuse kernel module and library.
(http://fuse.sourceforge.net) which is a user-mode filesystem driver.

Essentially, the entire 1-wire bus is mounted to a place in your filesystem. All the
1-wire devices are accessible using standard file operations (read, write, directory
listing). The system is safe, no actual files are exposed, these files are virtual. Not
all operations are supported. Specifically, file creation, deletion, linking and renaming
are not allowed. (You can link from outside to a owfs file, but not the other way around).

Device Options (1-wire Bus Master)

       These options specify the device (bus master) connecting the computer to the  1-wire  bus.
       The  1-wire  slaves are connected to the 1-wire bus, and the bus master connects to a port
       on the computer and controls the 1-wire bus. The bus master is either an  actual  physical
       device, the kernel w1 module, or an owserver (1).

       At  least  one device option is required. There is no default. More than one device can be
       listed,  and  all  will  be  used.  (A  logical  union  unless  you  explore  the  /bus.n/
       directories.)

       Linux  and  BSD  enforce  a security policy restricting access to hardware ports. You must
       have sufficient rights to access the given port or access will silently fail.

* Serial devices

       port specifies a serial port, e.g.  /dev/ttyS0

       If OWFS was built with libftdi support, you may be able to use the ftdi: prefix to address
       a FTDI-based USB device.
       For details, see the FTDI ADDRESSING section.

       -d port | --device=port (DS2480B)
              DS2480B-based  bus  master (like the DS9097U or the LINK in emulation mode). If the
              adapter doesn't respond, a passive type (DS9907E or diode/resistor) circuit will be
              assumed.

       --serial_flextime | --serial_regulartime (DS2480B)
              Changes details of bus timing (see DS2480B datasheet). Some devices, like the Swart
              LCD cannot work with flextime.

       --baud=1200|9600|19200|38400|57600|115200 (DS2480B,LINK,HA5)
              Sets the initial serial port communication speed  for  all  bus  masters.  Not  all
              serial  devices  support all speeds. You can change the individual bus master speed
              for the LINK and DS2880B in the interface/settings directory. The HA5 speed is  set
              in hardware, so the command line buad rate should match that rate.
              Usually  the  default  settings (9600 for LINK and DS2480B ) and 115200 for the HA5
              are sane and shouldn't be changed.

       --straight_polarity  | --reverse_polarity (DS2480B)
              Reverse polarity of the DS2480B output transistors? Not needed for the DS9097U, but
              required for some other designs.

       --link=port (LINK)
              iButtonLink  LINK  adapter  (all  versions)  in  non-emulation  mode. Uses an ascii
              protocol over serial.
              This supports the simplified ftdi:<serial> addressing scheme.

       --ha7e=port (HA7E)
              Embedded Data Systems HA7E adapter ( and HA7S ) in native ascii mode.

       --ha5=port | --ha5=port:a | --ha5=port:acg (HA5)
              Embedded Data Systems HA5 mutidrop adapter in native ascii mode. Up to 26  adapters
              can  share the same port, each with an assigned letter. If no letter specified, the
              program will scan for the first response (which may be slow).

       --checksum | --no_checksum (HA5)
              Turn on (default) or off the checksum feature of the HA5 communication.

       --passive=port | --ha2=port | --ha3=port | --ha4b=port (Passive)
              Passive 1-wire adapters. Powered off the serial port and using  passive  electrical
              components (resitors and diodes).

       --8bit | --6bit (Passive)
              Synthesize the 1-wire waveforme using a 6-bit (default) serial word, or 8-bit word.
              Not all UART devices support 6 bit operation.

       --timeout_serial=5
              Timeout (in seconds) for all  serial  communications.  5  second  default.  Can  be
              altered dynamically under /settings/timeout/serial

* USB devices

       The  only  supported true USB bus masters are based on the DS2490 chip. The most common is
       the DS9490R which has an included 1-wire ID slave with family code 81.

       There are also bus masters based on the serial chip with a USB to serial conversion  built
       in. These are supported by the serial bus master protocol.

       -u | --usb
              DS2490 based bus master (like the DS9490R).

       -u2 | --usb=2
              Use  the  second  USB  bus master. (The order isn't predicatble, however, since the
              operating system does not conssitently order USB devices).

       -uall | --usb=ALL
              Use all the USB devices.

       --usb_flextime | --usb_regulartime
              Changes the details of 1-wire waveform timing for certain network configurations.

       --altusb
              Willy Robion's alternative USB timing.

       --timeout_usb=5
              Timeout for USB communications. This has a 5 second  default  and  can  be  changed
              dynamically under /settings/timeout/usb

* I2C devices

       I2C  is  2 wire protocol used for chip-to-chip communication. The bus masters: DS2482-100,
       DS2482-101 and DS2482-800 can specify (via pin voltages) a subset of addresses on the  i2c
       bus. Those choices are

       i2c_address

       0,1,2,3
              0x18,0x19,0x1A,0x1B

       4,5,6,7
              0x1C,0x1D,0x1E,0x1F (DS2482-800 only)

       port for i2c masters have the form /dev/i2c-0, /dev/i2c-1, ...

       -d port | --device=port
              This simple form only permits a specific port and the first available i2c_address

       --i2c=port | --i2c=port:i2c_address | --i2c=port:ALL
              Specific  i2c  port  and  the  i2c_address is either the first, specific, or all or
              them. The i2c_address is 0,1,2,...

       --i2c | --i2c=: | --i2c=ALL:ALL
              Search the available i2c buses for either  the  first,  the  first,  or  every  i2c
              adapter.

       The DS2482-800 masters 8 1-wire buses and so will generate 8 /bus.n entries.

* Network devices

       These  bus  masters  communicate  via  the  tcp/ip  network protocol and so can be located
       anywhere on the network.  The network_address is of the form tcp_address:port

       E.g. 192.168.0.1:3000 or localhost:3000

       --link=network_address
              LinkHubE network LINK adapter by iButtonLink

       --ha7net=network_address | --ha7net
              HA7Net network 1-wire adapter with specified  tcp  address  or  discovered  by  udp
              multicast. By Embedded Data Systems
              --timeout_ha7=60 specific timeout for HA7Net communications (60 second default).

       --etherweather=network_address
              Etherweather adapter

       -s network_address | --server=network_address
              Location  of an owserver (1) program that talks to the 1-wire bus. The default port
              is 4304.

       --timeout_network=5
              Timeout for network bus master communications. This has a 1 second default and  can
              be changed dynamically under /settings/timeout/network

* Simulated devices

       Used  for testing and development. No actual hardware is needed. Useful for separating the
       hardware development from the rest of the software design.

       devices
              is a list of comma-separated 1-wire devices in the following formats. Note  that  a
              valid CRC8 code is created automatically.

       10,05,21
              Hexadecimal family codes (the DS18S20, DS2405 and DS1921 in this example).

       10.12AB23431211
              A  more  complete hexadecimal unique address. Useful when an actual hardware device
              should be simulated.

       DS2408,DS2489
              The 1-wire device name. (Full ID cannot be speciifed in this format).

       --fake=devices
              Random address and random values for each  read.  The  device  ID  is  also  random
              (unless specified).

       --temperature_low=12 --temperature_high=44
              Specify  the temperature limits for the fake adapter simulation. These should be in
              the same temperature scale that is specified in the command line. It is possible to
              change      the      limits      dynamically     for     each     adapter     under
              /bus.x/interface/settings/simulated/[temperature_low|temperature_high]

       --tester=devices
              Predictable address and predictable values for each read. (See the website for  the
              algorhythm).

* w1 kernel module

       This  a linux-specific option for using the operating system's access to bus masters. Root
       access is required and the implementation was still in progress as  of  owfs  v2.7p12  and
       linux 2.6.30.

       Bus  masters  are recognized and added dynamically. Details of the physical bus master are
       not accessible, bu they include USB, i2c and a number of GPIO designs on embedded boards.

       Access is restrict to superuser due to the netlink  broadcast  protocol  employed  by  w1.
       Multitasking must be configured (threads) on the compilation.

       --w1   Use the linux kernel w1 virtual bus master.

       --timeout_w1=10
              Timeout  for  w1  netlink  communications.  This has a 10 second default and can be
              changed dynamically under /settings/timeout/w1

FTDI ADDRESSING

       FTDI is a brand of USB-to-serial chips which are very common. If  your  serial  device  is
       connected via a USB serial dongle based on a FTDI chip, or if your adapter uses a built-in
       FTDI USB chip (for example, the LinkUSB), you can use this FTDI addressing.

       The main benifit with this mode of access is that we can decrease the communication delay,
       yielding twice as fast 1-Wire communication in many cases.

       The following values for port can be used to identify a specific FTDI port. Note that this
       requires that OWFS is built with libftdi support.

       ftdi:d:<devicenode>
              path of bus and device-node (e.g. "003/001") within usb  device  tree  (usually  at
              /proc/bus/usb/)

       ftdi:i:<vendor>:<product>
              first  device with given vendor and product id, ids can be decimal, octal (preceded
              by "0") or hex (preceded by "0x")

       ftdi:i:<vendor>:<product>:<index>
              as above with index being the number of the device (starting with 0) if  there  are
              more than one

       ftdi:s:<vendor>:<product>:<serial>
              first device with given vendor id, product id and serial string

       The above formats are parsed fully by libftdi (minus the ftdi: prefix).

   Simplified device serial-only support
       An  additional  format  is  supported,  for certain bus types. This only specifies the USB
       serial number.

       ftdi:<serial>
              Identifies a FTDI device by serial only.  Currently, this is  only  valid  for  the
              VID/PID  found  on  the  LinkUSB  (i.e. --link).  Note that those VID/PID's are the
              default for any FT232R device, and in no way exclusive to LinkUSB.

SPECIFIC OPTIONS

   -m --mountpoint=directory_path
       Path of a directory to mount the 1-wire file system

       The mountpoint is required. There is no default.

   --allow_other
       Shorthand for fuse mount option "-o allow_other"  Allows  uther  users  to  see  the  fuse
       (owfs) mount point and file system. Requires a setting in /etc/fuse.conf as well.

   --fuse-opt options
       Sends options to the fuse-mount process. Options should be quoted, e.g. "

TEMPERATURE SCALE OPTIONS

   -C --Celsius
   -F --Fahrenheit
   -K --Kelvin
   -R --Rankine
       Temperature scale used for data output. Celsius is the default.

       Can also be changed within the program at /settings/units/temperature_scale

PRESSURE SCALE OPTIONS

   --mbar (default)
   --atm
   --mmHg
   --inHg
   --psi
   --Pa
       Pressure scale used for data output. Millibar is the default.

       Can also be changed within the program at /settings/units/pressure_scale

FORMAT OPTIONS

       Choose the representation of the 1-wire unique identifiers. OWFS uses these identifiers as
       unique directory names.

       Although several display formats are selectable,  all  must  be  in  family-id-crc8  form,
       unlike some other programs and the labelling on iButtons, which are crc8-id-family form.

   -f --format="f[.]i[[.]c]"
       Display format for the 1-wire devices. Each device has a 8byte address, consisting of:

       f      family code, 1 byte

       i      ID number, 6 bytes

       c      CRC checksum, 1 byte

       Possible formats are f.i (default, 01.A1B2C3D4E5F6), fi fic f.ic f.i.c and fi.c

       All formats are accepted as input, but the output will be in the specified format.

       The  address  elements  can be retrieved from a device entry in owfs by the family, id and
       crc8 properties, and as a whole  with  address.   The  reversed  id  and  address  can  be
       retrieved as r_id and r_address.

JOB CONTROL OPTIONS

   -r --readonly
   -w --write
       Do  we  allow  writing to the 1-wire bus (writing memory, setting switches, limits, PIOs)?
       The write option is available for symmetry, it's the default.

   -P --pid-file filename
       Places the PID -- process ID of owfs into  the  specified  filename.  Useful  for  startup
       scripts control.

   --background | --foreground
       Whether  the  program  releases  the  console  and runs in the background after evaluating
       command line options.  background is the default.

   --error_print=0|1|2|3
       =0     default mixed destination: stderr foreground / syslog background

       =1     syslog only

       =2     stderr only

       =3     /dev/null (quiet mode).

   --error_level=0..9
       =0     default errors only

       =1     connections/disconnections

       =2     all high level calls

       =3     data summary for each call

       =4     details level

       >4     debugging chaff

       --error_level=9 produces a lot of output

CONFIGURATION FILE

   -c file | --configuration file
       Name of an owfs (5) configuration file with more command line parameters

       +.PP +On Debian, +.B owfs (1) +always reads +.I /etc/owfs.conf

HELP OPTIONS

       See also this man page and the web site http://www.owfs.org

   -h --help=[device|cache|program|job|temperature]
       Shows basic summary of options.

       device 1-wire bus master options

       cache  cache and communication size and timing

       program
              mountpoint or TCP server settings

       job    control and debugging options

       temperature
              Unique ID display format and temperature scale

   -V --version
       Version of this program and related libraries.

TIME OPTIONS

       Timeouts for the bus masters were previously listed in Device options.  Timeouts  for  the
       cache affect the time that data stays in memory. Default values are shown.

   --timeout_volatile=15
       Seconds  until  a  volatile  property  expires in the cache. Volatile properties are those
       (like temperature) that change on their own.

       Can be changed dynamically at /settings/timeout/volatile

   --timeout_stable=300
       Seconds until a stable property expires in the cache. Stable  properties  are  those  that
       shouldn't change unless explicitly changed. Memory contents for example.

       Can be changed dynamically at /settings/timeout/stable

   --timeout_directory=60
       Seconds  until  a  directory  listing expires in the cache. Directory lists are the 1-wire
       devices found on the bus.

       Can be changed dynamically at /settings/timeout/directory

   --timeout_presence=120
       Seconds until the presence and bus location of a 1-wire device expires in the cache.

       Can be changed dynamically at /settings/timeout/presence

       There are also timeouts for specific program responses:

   --timeout_server=5
       Seconds until the expected response from the owserver (1) is deemed tardy.

       Can be changed dynamically at /settings/timeout/server

   --timeout_ftp=900
       Seconds that an ftp session is kept alive.

       Can be changed dynamically at /settings/timeout/ftp

EXAMPLE

       owfs -d /dev/ttyS0 -m /mnt/1wire
              Bus master on serial port

       owfs -F -u -m /mnt/1wire
              USB adapter, temperatures reported in Fahrenheit

       owfs -s 10.0.1.2:4304 -m /mnt/1wire
              Connect to an owserver (1) process that was started on another machine at tcp  port
              4304

AVAILABILITY

       http://www.owfs.org

AUTHOR

       Paul Alfille (paul.alfille@gmail.com)