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

FreeBSD Manual Pages

  
 
  

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

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

   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 proper-
       ties.

       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  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
       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  as-
	      sumed.

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

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

       --timeout_serial=5
	      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
       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 net-
	      work 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,  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-
       tries.

* 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 dis-
	      covered 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 sec-
	      ond 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
	      Hexadecimal family codes (the DS18S20, DS2405 and	DS1921 in this
	      example).

       10.12AB23431211
	      A	more complete hexadecimal unique address. Useful when  an  ac-
	      tual 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 dynami-
	      cally for	 each  adapter	under  /bus.x/interface/settings/simu-
	      lated/[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	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-
       lation.

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

       --timeout_w1=10
	      Timeout for w1 netlink communications. This has a	10 second  de-
	      fault 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 deci-
	      mal, 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{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
       addressing
       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-
       Product|iSerial"
	      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
	      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/tempera-
       ture_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/pres-
       sure_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	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.

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

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

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. De-
       fault values are	shown.

   --timeout_volatile=15
       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

   --timeout_stable=300
       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

   --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  "little-
	      host", 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)

OWFS Manpage			     2004			    OWHTTPD(1)

NAME | SYNOPSIS | DESCRIPTION | SPECIFIC OPTIONS | Device Options (1-wire Bus Master) | * Serial devices | * USB devices | * I2C devices | * Network devices | * Simulated devices | * w1 kernel module | FTDI ADDRESSING | TEMPERATURE SCALE OPTIONS | PRESSURE SCALE OPTIONS | FORMAT OPTIONS | JOB CONTROL OPTIONS | CONFIGURATION FILE | HELP OPTIONS | TIME OPTIONS | EXAMPLE | AVAILABILITY | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=owhttpd&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help