Provided by: owhttpd_3.2p3+dfsg1-2_amd64 bug

NAME

       owhttpd - Tiny webserver for 1-wire control

SYNOPSIS

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

   owhttpd
       owhttpd (1) is a small webserver that shows the Dallas/Maxim  1-Wire  bus  attached  to  a
       serial  port.  The  main view shows the devices found, You can then navigate to individual
       devices, and view/alter their properties.

       owhttpd (1) uses the same naming convention as owfs (1) , where the URL corresponds to the
       filename.

       The  web server is a modified version of chttpd by Greg Olszewski. It serves no files from
       the disk, only virtual files from the 1-wire bus. Security should therefore be good.  Only
       the 1-wire bus is at risk.

SPECIFIC OPTIONS

   -p portnum
       Sets    the    tcp    port    the    web   server   runs   on.   Access   with   the   URL
       http://servernameoripaddress:portnum

       If no port is specified, an ephemeral port  is  selected  by  the  operating  system.  Use
       zeroconf (Bonjour) to discover the assigned port.

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

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

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

       owhttpd -p 3001 -d /dev/ttyS0
              Web server runs on tcp port 3001, serial adapter at ttyS0

       owhttpd -p 3001 -s littlehost:4304 --error_level=3
              Web  server  on  port  3001,  from owserver process on host "littlehost", extensive
              error messages.

       owhttpd -p 3001 -u -u2 -r
              Read-only web server on port 3001, using two usb adapters.

AVAILABILITY

       http://www.owfs.org

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

AUTHOR

       Paul Alfille (paul.alfille@gmail.com)