Provided by: owfs-fuse_3.2p4+dfsg1-4.1build1_amd64 
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 fundamental 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 or an USB port accessed as serial port,
e.g. /dev/ttyUSB0
If OWFS was built with libftdi support, you may be able to use the ftdi: prefix in any of
the options as port 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 an adapter of the LINK family 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 a device of the LINK family and DS2880B in the interface/settings directory.
The HA5 speed is set in hardware, so the command line baud rate should match that
rate.
Usually the default settings (9600 for a device of the LINK family 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 number> 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 consistently 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
algorithm).
* 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 benefit 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 in several of
the serial devices options.
Note that this requires that OWFS is built with libftdi support, which might not be the
case in standard repositories.
ftdi:d:<device-node>
path of bus and device-node (e.g. "003/001") within usb device tree (usually at
/proc/bus/usb/ or /dev/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 number>
the device with given vendor id, product id and serial number 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 number>
Identifies a FTDI device by serial number 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.
Permsissions
In order to run owserver (1) without root privileges - as you should, you must have
sufficient permissions to the raw USB node your adapter is connected to e.g. "003/001"
(usually at /proc/bus/usb/ or /dev/bus/usb/).
An easy way to achieve this would be using chown (1):
sudo chown :<your user> /dev/bus/usb/003/001
changes the group of the raw USB node "003/001" from default "root" to "<your
user>"
You can also write a udev (1) rule for your adapter:
SUBSYSTEM=="usb", DRIVER=="usb", ATTR{idVendor}=="0403", ATTR{idProduct}=="6001",
ATTR{serial}=="AK0048A0", GROUP="owsrv"
saved as a file e.g. "10-FTDI-LinkUSB.rules" in "/etc/udev/rules.d/", this rule
will automate the process of changing the group to "owsrv" of the raw USB node the
LinkUSB adapter with S/N:AK0048A0 is connected to.
Serial USB node
Communication in FTDI mode accesses the RAW USB node and NOT the serial USB node your OS
might have created automatically e.g. /dev/ttyUSB0.
As a side effect, if existing, the serial USB node e.g. /dev/ttyUSB0 is removed on
successful starting of owserver (1). After it's termination un- and re-plugging the
adapter, or un- and reloading of the module ftdi_sio will recreate the serial USB node.
Finding FTDI related information on your USB adapter
owusbprobe is THE tool to find the information needed for direct FTDI addressing
However this tool might not yet be packaged in your version. Alternatively you can also
use lsusb to find the usb node your adapter is connected to, and then use lsusb again on
this very node:
sudo lsusb -D /path/to/your/raw/USB/device/node |egrep "idVendor|idProduct|iSerial"
sudo is necessary to get the value of iSerial field, if the permissions are still
unchanged
Examples FTDI addressing
owserver -d ftdi:s:0x0403:0x6001:A800bXHr
starts owserver with a LinkUSB (VID:0x0403,PID:0x6001,S/N:A800bXHr) as bus master
in DS2480B-based emulation mode with direct FTDI access
owserver --link=ftdi:A800bXHr
starts owserver with a LinkUSB (S/N:A800bXHr) as bus master identified by serial
number only in native mode with direct FTDI access
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
SEE ALSO
Programs
owfs (1) owhttpd (1) owftpd (1) owserver (1) owdir (1) owread (1) owwrite (1) owpresent
(1) owtap (1)
Configuration and testing
owfs (5) owtap (1) owmon (1)
Language bindings
owtcl (3) owperl (3) owcapi (3)
Clocks
DS1427 (3) DS1904(3) DS1994 (3) DS2404 (3) DS2404S (3) DS2415 (3) DS2417 (3)
ID
DS2401 (3) DS2411 (3) DS1990A (3)
Memory
DS1982 (3) DS1985 (3) DS1986 (3) DS1991 (3) DS1992 (3) DS1993 (3) DS1995 (3) DS1996 (3)
DS2430A (3) DS2431 (3) DS2433 (3) DS2502 (3) DS2506 (3) DS28E04 (3) DS28EC20 (3)
Switches
DS2405 (3) DS2406 (3) DS2408 (3) DS2409 (3) DS2413 (3) DS28EA00 (3)
Temperature
DS1822 (3) DS1825 (3) DS1820 (3) DS18B20 (3) DS18S20 (3) DS1920 (3) DS1921 (3) DS1821 (3)
DS28EA00 (3) DS28E04 (3)
Humidity
DS1922 (3)
Voltage
DS2450 (3)
Resistance
DS2890 (3)
Multifunction (current, voltage, temperature)
DS2436 (3) DS2437 (3) DS2438 (3) DS2751 (3) DS2755 (3) DS2756 (3) DS2760 (3) DS2770 (3)
DS2780 (3) DS2781 (3) DS2788 (3) DS2784 (3)
Counter
DS2423 (3)
LCD Screen
LCD (3) DS2408 (3)
Crypto
DS1977 (3)
Pressure
DS2406 (3) -- TAI8570
AVAILABILITY
http://www.owfs.org
AUTHOR
Paul Alfille (paul.alfille@gmail.com)