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 priciple 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
- -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.
- --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
- Hexidecimal family codes (the DS18S20, DS2405 and
DS1921 in this example).
- 10.12AB23431211
- A more complete hexidecimal 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
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
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.
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
On Debian,
owfs (1) always reads
/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)
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)