Owserver

owserver man page

OWSERVER(1)                                                     One-Wire File System                                                    OWSERVER(1)

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

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

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  (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 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.

   owserver
       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 tunneling 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 connecting. Note: owserver (1) can connect to another owserver (1) process, though the
       utility of this technique is limited (perhaps as a readonly buffer?)

       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
       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/time‐
              out/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/[temper‐
              ature_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 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 com‐
       pilation.

       --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 termina‐
       tion 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  con‐
       nected 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
   -p
       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.

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  iBut‐
       tons, 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

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

PERSISTENT THRESHOLD OPTIONS
       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.

   --timeout_persistent_low=600
       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

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

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

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

DEVELOPER OPTIONS
   --no_dirall
       Reject  DIRALL messages (requests directory as a single message), forcing client to use older DIR method (each element is an individual mes‐
       sage)

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

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

   --pingcrazy
       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.

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

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)

OWSERVER Manpage                                                        2004                                                            OWSERVER(1)