Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
OWSERVER(1)		     One-Wire File System		   OWSERVER(1)

       owserver	- Backend server (daemon) for 1-wire control

       owserver	[ -c config ] -d serialport | -u | -s [host:]port -p tcp-port

       1-wire is a wiring protocol and series of devices designed and manufac-
       tured 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  (humid-
       ity, 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 en-
       cryption	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,  par-
       allel, 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 in-
       dividual	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 com-
       munication. Still the fundamental goal has been ease of use,  flexibil-
       ity and correctness rather than speed.

       owserver	 (1)  is  the backend component	of the OWFS 1-wire bus control
       system.	owserver (1) arbitrates	access to the bus from multiple	client
       processes.  The	physical  bus  is usually connected to a serial	or USB
       port, and other processes connect to owserver (1) over network  sockets
       (tcp  port).  Communication can be local	or over	a network. Secure tun-
       neling can be implemented using standard	techniques.

       Frontend	clients	include	a filesystem representation: owfs (1) ,	and  a
       webserver:  owhttpd  (1).  Direct language bindings are also available,
       e.g: owperl (3).	 Several instances of each client can be initiated.

       Each client can also connect directly to	 the  physical	bus,  skipping
       owserver	 (1)  but  only	 one  client  can  connect to the physical bus
       safely. Simultaneous access is prevented	by the	operating  system  for
       USB  ports,  but	 unfortunately not serial ports. The safe way to share
       access to the 1-wire bus	is via owserver	(1) with the clients  connect-
       ing.  Note:  owserver  (1) can connect to another owserver (1) process,
       though the utility of this technique is limited (perhaps	as a  readonly

       owserver	 (1)  is by default multithreaded. Optional data caching is in
       the server, not clients,	so all the clients gain	efficiency.

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 ac-
       cess 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
       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 as-

       --serial_flextime | --serial_regulartime	(DS2480B)
	      Changes details of bus timing (see DS2480B datasheet). Some  de-
	      vices, 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 fam-
	      ily  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

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

       --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	commu-

       --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	opera-

	      Timeout (in seconds) for all serial communications. 5 second de-
	      fault. 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  se-
       rial  conversion	built in. These	are supported by the serial bus	master

       -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  net-
	      work configurations.

	      Willy Robion's alternative USB timing.

	      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



	      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, spe-
	      cific, 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 en-

* 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. or	localhost:3000

	      LinkHubE network LINK adapter by iButtonLink

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

	      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 for network bus master communications. This has a	1 sec-
	      ond default and can be changed dynamically under /settings/time-

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

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

	      Hexadecimal family codes (the DS18S20, DS2405 and	DS1921 in this

	      A	 more  complete	hexadecimal unique address. Useful when	an ac-
	      tual hardware device should be simulated.

	      The 1-wire device	name. (Full ID cannot  be  speciifed  in  this

	      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 dynami-
	      cally  for  each	adapter	 under /bus.x/interface/settings/simu-

	      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	physi-
       cal bus master are not accessible, bu they include USB, i2c and a  num-
       ber 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	compi-

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

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

       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.

	      path  of	bus and	device-node (e.g. "003/001") within usb	device
	      tree (usually at /proc/bus/usb/ or /dev/bus/usb/)

	      first device with	given vendor and product id, ids can be	 deci-
	      mal, octal (preceded by "0") or hex (preceded by "0x")

	      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

       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.

       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

       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{idProd-
       uct}=="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
       However this tool might not yet be packaged in your  version.  Alterna-
       tively you can also use lsusb to	find the usb node your adapter is con-
       nected to, and then use lsusb again on this very	node:

       sudo lsusb -D /path/to/your/raw/USB/device/node	 |egrep	 "idVendor|id-
	      sudo is necessary	to get the value of iSerial field, if the per-
	      missions 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

       TCP port	or IPaddress:port for owserver

       Other OWFS programs will	access owserver	via this address.  (e.g.  owfs
       -s IP:port /1wire)

       If  no port is specified, the default well-known	port (4304 -- assigned
       by the IANA) will be used.

   -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/tempera-

   --mbar (default)
       Pressure	scale used for data output. Millibar is	the default.

       Can  also  be  changed  within  the  program  at	 /settings/units/pres-

       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	speci-
       fied 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.

   -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.  Use-
       ful for startup scripts control.

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

       =0     default mixed destination: stderr	foreground / syslog background

       =1     syslog only

       =2     stderr only

       =3     /dev/null	(quiet mode).

       =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

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

       See also	this man page and the web site

   -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

	      mountpoint or TCP	server settings

       job    control and debugging options

	      Unique ID	display	format and temperature scale

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

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

       Seconds	until a	volatile property expires in the cache.	Volatile prop-
       erties are those	(like temperature) that	change on their	own.

       Can be changed dynamically at /settings/timeout/volatile

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

       Can be changed dynamically at /settings/timeout/stable

       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

       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:

       Seconds until the expected response from	the  owserver  (1)  is	deemed

       Can be changed dynamically at /settings/timeout/server

       Seconds that an ftp session is kept alive.

       Can be changed dynamically at /settings/timeout/ftp

       These  settings	control	 the  behavior of owserver (1) in granting and
       dropping	persistent tcp connections. The	default	settings are shown.

       In general no changes should be needed. In general the  purpose	is  to
       limit total resource usage from an errant or rogue client.

       Minimum	seconds	 that  a  persistent tcp connection to owserver	(1) is
       kept open. This is the limit used when the  number  of  connections  is
       above --clients_persistent_low

       Maximum	seconds	 that  a  persistent tcp connection to owserver	(1) is
       kept open. This is the limit used when the number of connections	is be-
       low --clients_persistent_low

       Maximum	number	of  persistent	tcp connections	to owserver (1)	before
       connections start getting the more stringent  time  limitation  --time-

       Maximum	number of persistent tcp connections to	before no more are al-
       lowed (only non-persistent at this point).  owserver (1)	before no more
       are allowed (only non-persistent	at this	point).

       Reject  DIRALL messages (requests directory as a	single message), forc-
       ing client to use older DIR method (each	element	is an individual  mes-

       Reject  GET  messages (lets owserver determine if READ or DIRALL	is ap-
       propriate). Client will fall back to older methods.

       Reject persistence in requests. All transactions	will have  to  be  new

       Interject  many	"keep-alive"  (PING) responses.	Usually	PING responses
       are only	sent when processing is	taking a long time  to	inform	client
       that owserver is	still there.

       owserver	 -p 3001 -d /dev/ttyS0 runs owserver on	tcp port 3001 and con-
       nects to	a physical 1-wire bus on a serial port.

       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)

       DS1427  (3)  DS1904(3)  DS1994  (3)  DS2404  (3)	DS2404S	(3) DS2415 (3)
       DS2417 (3)

       DS2401 (3) DS2411 (3) DS1990A (3)

       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)

       DS2405 (3) DS2406 (3) DS2408 (3)	DS2409 (3) DS2413 (3) DS28EA00 (3)

       DS1822 (3) DS1825 (3) DS1820 (3)	DS18B20	(3)  DS18S20  (3)  DS1920  (3)
       DS1921 (3) DS1821 (3) DS28EA00 (3) DS28E04 (3)

       DS1922 (3)

       DS2450 (3)

       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)

       DS2423 (3)

   LCD Screen
       LCD (3) DS2408 (3)

       DS1977 (3)

       DS2406 (3) -- TAI8570


       Paul Alfille (

OWSERVER Manpage		     2004			   OWSERVER(1)


Want to link to this manual page? Use this URL:

home | help