1OWHTTPD(1)                   One-Wire File System                   OWHTTPD(1)
2
3
4

NAME

6       owhttpd - Tiny webserver for 1-wire control
7

SYNOPSIS

9       owhttpd [ -c config ] -d serialport | -u | -s [host:]port -p tcp-port
10

DESCRIPTION

12   1-Wire
13       1-wire is a wiring protocol and series of devices designed and manufac‐
14       tured by Dallas Semiconductor, Inc. The bus is  a  low-power  low-speed
15       low-connector scheme where the data line can also provide power.
16
17       Each  device  is  uniquely and unalterably numbered during manufacture.
18       There are a wide variety of devices, including memory, sensors  (humid‐
19       ity, temperature, voltage, contact, current), switches, timers and data
20       loggers. More complex devices (like thermocouple sensors) can be  built
21       with  these  basic  devices.  There  are  also 1-wire devices that have
22       encryption included.
23
24       The 1-wire scheme uses a single bus master and multiple slaves  on  the
25       same  wire.  The bus master initiates all communication. The slaves can
26       be individually discovered and addressed using their unique ID.
27
28       Bus masters come in a variety of configurations including serial,  par‐
29       allel, i2c, network or USB adapters.
30
31   OWFS design
32       OWFS  is  a  suite of programs that designed to make the 1-wire bus and
33       its devices easily accessible. The underlying principle is to create  a
34       virtual  filesystem,  with  the  unique ID being the directory, and the
35       individual properties of the device are  represented  as  simple  files
36       that can be read and written.
37
38       Details  of  the  individual slave or master design are hidden behind a
39       consistent interface. The goal is to provide an easy set of tools for a
40       software  designer  to create monitoring or control applications. There
41       are some performance enhancements in the implementation, including data
42       caching, parallel access to bus masters, and aggregation of device com‐
43       munication. Still the fundamental goal has been ease of use,  flexibil‐
44       ity and correctness rather than speed.
45
46   owhttpd
47       owhttpd (1) is a small webserver that shows the Dallas/Maxim 1-Wire bus
48       attached to a serial port. The main view shows the devices  found,  You
49       can  then  navigate to individual devices, and view/alter their proper‐
50       ties.
51
52       owhttpd (1) uses the same naming convention as owfs (1) , where the URL
53       corresponds to the filename.
54
55       The  web  server  is a modified version of chttpd by Greg Olszewski. It
56       serves no files from the disk, only virtual files from the 1-wire  bus.
57       Security should therefore be good. Only the 1-wire bus is at risk.
58

SPECIFIC OPTIONS

60   -p portnum
61       Sets  the  tcp  port  the  web  server  runs  on.  Access  with the URL
62       http://servernameoripaddress:portnum
63
64       If no port is specified, an ephemeral port is selected by the operating
65       system. Use zeroconf (Bonjour) to discover the assigned port.
66

Device Options (1-wire Bus Master)

68       These  options  specify the device (bus master) connecting the computer
69       to the 1-wire bus. The 1-wire slaves are connected to the  1-wire  bus,
70       and  the bus master connects to a port on the computer and controls the
71       1-wire bus. The bus master is either an  actual  physical  device,  the
72       kernel w1 module, or an owserver (1).
73
74       At  least one device option is required. There is no default. More than
75       one device can be listed, and all will be used. (A logical union unless
76       you explore the /bus.n/ directories.)
77
78       Linux  and BSD enforce a security policy restricting access to hardware
79       ports. You must have sufficient rights to  access  the  given  port  or
80       access will silently fail.
81

* Serial devices

83       port  specifies a serial port, e.g.  /dev/ttyS0 or an USB port accessed
84       as serial port, e.g. /dev/ttyUSB0
85
86       If OWFS was built with libftdi support, you may  be  able  to  use  the
87       ftdi:  prefix in any of the options as port to address a FTDI-based USB
88       device.
89       For details, see the FTDI ADDRESSING section.
90
91       -d port | --device=port (DS2480B)
92              DS2480B-based bus master (like the DS9097U or an adapter of  the
93              LINK  family in emulation mode). If the adapter doesn't respond,
94              a passive type  (DS9907E  or  diode/resistor)  circuit  will  be
95              assumed.
96
97       --serial_flextime | --serial_regulartime (DS2480B)
98              Changes  details  of  bus  timing  (see DS2480B datasheet). Some
99              devices, like the Swart LCD cannot work with flextime.
100
101       --baud=1200|9600|19200|38400|57600|115200 (DS2480B,LINK,HA5)
102              Sets the initial serial port communication  speed  for  all  bus
103              masters.  Not  all  serial  devices  support all speeds. You can
104              change the individual bus master speed for a device of the  LINK
105              family  and DS2880B in the interface/settings directory. The HA5
106              speed is set in hardware, so the command line baud  rate  should
107              match that rate.
108              Usually the default settings (9600 for a device of the LINK fam‐
109              ily and DS2480B ) and 115200 for the HA5 are sane and  shouldn't
110              be changed.
111
112       --straight_polarity  | --reverse_polarity (DS2480B)
113              Reverse  polarity  of the DS2480B output transistors? Not needed
114              for the DS9097U, but required for some other designs.
115
116       --link=port (LINK)
117              iButtonLink LINK adapter (all versions) in  non-emulation  mode.
118              Uses an ascii protocol over serial.
119              This  supports  the  simplified  ftdi:<serial number> addressing
120              scheme.
121
122       --ha7e=port (HA7E)
123              Embedded Data Systems HA7E adapter ( and HA7S ) in native  ascii
124              mode.
125
126       --ha5=port | --ha5=port:a | --ha5=port:acg (HA5)
127              Embedded Data Systems HA5 mutidrop adapter in native ascii mode.
128              Up to 26 adapters can share the same port, each with an assigned
129              letter.  If  no  letter specified, the program will scan for the
130              first response (which may be slow).
131
132       --checksum | --no_checksum (HA5)
133              Turn on (default) or off the checksum feature of the HA5  commu‐
134              nication.
135
136       --passive=port | --ha2=port | --ha3=port | --ha4b=port (Passive)
137              Passive  1-wire  adapters. Powered off the serial port and using
138              passive electrical components (resitors and diodes).
139
140       --8bit | --6bit (Passive)
141              Synthesize the 1-wire waveforme using a 6-bit  (default)  serial
142              word,  or  8-bit word. Not all UART devices support 6 bit opera‐
143              tion.
144
145       --timeout_serial=5
146              Timeout (in seconds) for all  serial  communications.  5  second
147              default.   Can  be  altered  dynamically  under  /settings/time‐
148              out/serial
149

* USB devices

151       The only supported true USB bus masters are based on the  DS2490  chip.
152       The  most  common  is the DS9490R which has an included 1-wire ID slave
153       with family code 81.
154
155       There are also bus masters based on the  serial  chip  with  a  USB  to
156       serial  conversion built in. These are supported by the serial bus mas‐
157       ter protocol.
158
159       -u | --usb
160              DS2490 based bus master (like the DS9490R).
161
162       -u2 | --usb=2
163              Use the second USB bus master.  (The  order  isn't  predicatble,
164              however,  since the operating system does not consistently order
165              USB devices).
166
167       -uall | --usb=ALL
168              Use all the USB devices.
169
170       --usb_flextime | --usb_regulartime
171              Changes the details of 1-wire waveform timing for  certain  net‐
172              work configurations.
173
174       --altusb
175              Willy Robion's alternative USB timing.
176
177       --timeout_usb=5
178              Timeout  for USB communications. This has a 5 second default and
179              can be changed dynamically under /settings/timeout/usb
180

* I2C devices

182       I2C is  2 wire protocol used for chip-to-chip  communication.  The  bus
183       masters:  DS2482-100,  DS2482-101  and  DS2482-800 can specify (via pin
184       voltages) a subset of addresses on the i2c bus. Those choices are
185
186       i2c_address
187
188       0,1,2,3
189              0x18,0x19,0x1A,0x1B
190
191       4,5,6,7
192              0x1C,0x1D,0x1E,0x1F (DS2482-800 only)
193
194       port for i2c masters have the form /dev/i2c-0, /dev/i2c-1, ...
195
196       -d port | --device=port
197              This simple form only permits a  specific  port  and  the  first
198              available i2c_address
199
200       --i2c=port | --i2c=port:i2c_address | --i2c=port:ALL
201              Specific  i2c port and the i2c_address is either the first, spe‐
202              cific, or all or them. The i2c_address is 0,1,2,...
203
204       --i2c | --i2c=: | --i2c=ALL:ALL
205              Search the available i2c buses for either the first, the  first,
206              or every i2c adapter.
207
208       The  DS2482-800  masters  8  1-wire buses and so will generate 8 /bus.n
209       entries.
210

* Network devices

212       These bus masters communicate via the tcp/ip network  protocol  and  so
213       can  be located anywhere on the network.  The network_address is of the
214       form tcp_address:port
215
216       E.g. 192.168.0.1:3000 or localhost:3000
217
218       --link=network_address
219              LinkHubE network LINK adapter by iButtonLink
220
221       --ha7net=network_address | --ha7net
222              HA7Net network 1-wire adapter with specified tcp address or dis‐
223              covered by udp multicast. By Embedded Data Systems
224              --timeout_ha7=60  specific timeout for HA7Net communications (60
225              second default).
226
227       --etherweather=network_address
228              Etherweather adapter
229
230       -s network_address | --server=network_address
231              Location of an owserver (1) program that  talks  to  the  1-wire
232              bus. The default port is 4304.
233
234       --timeout_network=5
235              Timeout for network bus master communications. This has a 1 sec‐
236              ond default and can be changed dynamically under /settings/time‐
237              out/network
238

* Simulated devices

240       Used  for testing and development. No actual hardware is needed. Useful
241       for separating the hardware development from the rest of  the  software
242       design.
243
244       devices
245              is  a  list  of  comma-separated 1-wire devices in the following
246              formats. Note that a valid CRC8 code is created automatically.
247
248       10,05,21
249              Hexadecimal family codes (the DS18S20, DS2405 and DS1921 in this
250              example).
251
252       10.12AB23431211
253              A  more  complete  hexadecimal  unique  address.  Useful when an
254              actual hardware device should be simulated.
255
256       DS2408,DS2489
257              The 1-wire device name. (Full ID cannot  be  speciifed  in  this
258              format).
259
260       --fake=devices
261              Random address and random values for each read. The device ID is
262              also random (unless specified).
263
264       --temperature_low=12 --temperature_high=44
265              Specify the temperature limits for the fake adapter  simulation.
266              These  should be in the same temperature scale that is specified
267              in the command line. It is possible to change the limits dynami‐
268              cally  for  each  adapter  under /bus.x/interface/settings/simu‐
269              lated/[temperature_low|temperature_high]
270
271       --tester=devices
272              Predictable address and predictable values for each  read.  (See
273              the website for the algorhythm).
274

* w1 kernel module

276       This a linux-specific option for using the operating system's access to
277       bus masters. Root access is required and the implementation  was  still
278       in progress as of owfs v2.7p12 and linux 2.6.30.
279
280       Bus masters are recognized and added dynamically. Details of the physi‐
281       cal bus master are not accessible, bu they include USB, i2c and a  num‐
282       ber of GPIO designs on embedded boards.
283
284       Access  is  restrict to superuser due to the netlink broadcast protocol
285       employed by w1. Multitasking must be configured (threads) on the compi‐
286       lation.
287
288       --w1   Use the linux kernel w1 virtual bus master.
289
290       --timeout_w1=10
291              Timeout  for  w1  netlink  communications.  This has a 10 second
292              default and can be  changed  dynamically  under  /settings/time‐
293              out/w1
294

FTDI ADDRESSING

296       FTDI  is  a brand of USB-to-serial chips which are very common. If your
297       serial device is connected via a USB serial  dongle  based  on  a  FTDI
298       chip,  or  if  your adapter uses a built-in FTDI USB chip (for example,
299       the LinkUSB), you can use this FTDI addressing.
300
301       The main benefit with this mode of access is that we can  decrease  the
302       communication  delay,  yielding  twice  as fast 1-Wire communication in
303       many cases.
304
305       The following values for port can be used to identify a  specific  FTDI
306       port in several of the serial devices options.
307       Note  that this requires that OWFS is built with libftdi support, which
308       might not be the case in standard repositories.
309
310       ftdi:d:<device-node>
311              path of bus and device-node (e.g. "003/001") within  usb  device
312              tree (usually at /proc/bus/usb/ or /dev/bus/usb/)
313
314       ftdi:i:<vendor>:<product>
315              first  device with given vendor and product id, ids can be deci‐
316              mal, octal (preceded by "0") or hex (preceded by "0x")
317
318       ftdi:i:<vendor>:<product>:<index>
319              as above with index being the number  of  the  device  (starting
320              with 0) if there are more than one
321
322       ftdi:s:<vendor>:<product>:<serial number>
323              the  device  with  given vendor id, product id and serial number
324              string
325
326       The above formats are parsed fully by libftdi (minus the ftdi: prefix).
327
328   Simplified device serial-only support
329       An additional format is supported, for certain  bus  types.  This  only
330       specifies the USB serial number.
331
332       ftdi:<serial number>
333              Identifies a FTDI device by serial number only.  Currently, this
334              is only valid  for  the  VID/PID  found  on  the  LinkUSB  (i.e.
335              --link).   Note  that  those  VID/PID's  are the default for any
336              FT232R device, and in no way exclusive to LinkUSB.
337
338   Permsissions
339       In order to run owserver (1) without root privileges - as  you  should,
340       you  must  have sufficient permissions to the raw USB node your adapter
341       is  connected  to  e.g.  "003/001"  (usually   at   /proc/bus/usb/   or
342       /dev/bus/usb/).
343
344       An easy way to achieve this would be using chown (1):
345
346       sudo chown :<your user> /dev/bus/usb/003/001
347              changes  the  group  of  the raw USB node "003/001" from default
348              "root" to "<your user>"
349
350       You can also write a udev (1) rule for your adapter:
351
352       SUBSYSTEM=="usb", DRIVER=="usb",  ATTR{idVendor}=="0403",  ATTR{idProd‐
353       uct}=="6001", ATTR{serial}=="AK0048A0", GROUP="owsrv"
354              saved    as    a    file    e.g.    "10-FTDI-LinkUSB.rules"   in
355              "/etc/udev/rules.d/", this rule will  automate  the  process  of
356              changing  the  group  to "owsrv" of the raw USB node the LinkUSB
357              adapter with S/N:AK0048A0 is connected to.
358
359   Serial USB node
360       Communication in FTDI mode accesses the RAW USB node and NOT the serial
361       USB node your OS might have created automatically e.g. /dev/ttyUSB0.
362       As a side effect, if existing, the serial USB node e.g. /dev/ttyUSB0 is
363       removed on successful starting of owserver (1). After it's  termination
364       un-  and  re-plugging  the  adapter, or un- and reloading of the module
365       ftdi_sio will recreate the serial USB node.
366
367   Finding FTDI related information on your USB adapter
368       owusbprobe is THE tool to find the information needed for  direct  FTDI
369       addressing
370       However  this  tool might not yet be packaged in your version. Alterna‐
371       tively you can also use lsusb to find the usb node your adapter is con‐
372       nected to, and then use lsusb again on this very node:
373
374       sudo   lsusb   -D   /path/to/your/raw/USB/device/node   |egrep  "idVen‐
375       dor|idProduct|iSerial"
376              sudo is necessary to get the value of iSerial field, if the per‐
377              missions are still unchanged
378
379   Examples FTDI addressing
380       owserver -d ftdi:s:0x0403:0x6001:A800bXHr
381              starts          owserver          with         a         LinkUSB
382              (VID:0x0403,PID:0x6001,S/N:A800bXHr) as bus master  in  DS2480B-
383              based emulation mode with direct FTDI access
384
385       owserver --link=ftdi:A800bXHr
386              starts  owserver  with  a  LinkUSB  (S/N:A800bXHr) as bus master
387              identified by serial number only in native mode with direct FTDI
388              access
389

TEMPERATURE SCALE OPTIONS

391   -C --Celsius
392   -F --Fahrenheit
393   -K --Kelvin
394   -R --Rankine
395       Temperature scale used for data output. Celsius is the default.
396
397       Can  also  be  changed  within  the program at /settings/units/tempera‐
398       ture_scale
399

PRESSURE SCALE OPTIONS

401   --mbar (default)
402   --atm
403   --mmHg
404   --inHg
405   --psi
406   --Pa
407       Pressure scale used for data output. Millibar is the default.
408
409       Can  also  be  changed  within  the  program  at  /settings/units/pres‐
410       sure_scale
411
412

FORMAT OPTIONS

414       Choose  the  representation of the 1-wire unique identifiers. OWFS uses
415       these identifiers as unique directory names.
416
417       Although several display formats are selectable, all must be in family-
418       id-crc8 form, unlike some other programs and the labelling on iButtons,
419       which are crc8-id-family form.
420
421   -f --format="f[.]i[[.]c]"
422       Display format for the 1-wire devices. Each device has a 8byte address,
423       consisting of:
424
425       f      family code, 1 byte
426
427       i      ID number, 6 bytes
428
429       c      CRC checksum, 1 byte
430
431       Possible  formats are f.i (default, 01.A1B2C3D4E5F6), fi fic f.ic f.i.c
432       and fi.c
433
434       All formats are accepted as input, but the output will be in the speci‐
435       fied format.
436
437       The  address  elements  can be retrieved from a device entry in owfs by
438       the family, id and crc8 properties, and as a whole with  address.   The
439       reversed id and address can be retrieved as r_id and r_address.
440

JOB CONTROL OPTIONS

442   -r --readonly
443   -w --write
444       Do  we  allow  writing  to  the  1-wire  bus  (writing  memory, setting
445       switches, limits, PIOs)? The write option is  available  for  symmetry,
446       it's the default.
447
448   -P --pid-file filename
449       Places  the PID -- process ID of owfs into the specified filename. Use‐
450       ful for startup scripts control.
451
452   --background | --foreground
453       Whether the program releases the console and  runs  in  the  background
454       after evaluating command line options.  background is the default.
455
456   --error_print=0|1|2|3
457       =0     default mixed destination: stderr foreground / syslog background
458
459       =1     syslog only
460
461       =2     stderr only
462
463       =3     /dev/null (quiet mode).
464
465   --error_level=0..9
466       =0     default errors only
467
468       =1     connections/disconnections
469
470       =2     all high level calls
471
472       =3     data summary for each call
473
474       =4     details level
475
476       >4     debugging chaff
477
478       --error_level=9 produces a lot of output
479

CONFIGURATION FILE

481   -c file | --configuration file
482       Name  of  an owfs (5) configuration file with more command line parame‐
483       ters
484
485

HELP OPTIONS

487       See also this man page and the web site http://www.owfs.org
488
489   -h --help=[device|cache|program|job|temperature]
490       Shows basic summary of options.
491
492       device 1-wire bus master options
493
494       cache  cache and communication size and timing
495
496       program
497              mountpoint or TCP server settings
498
499       job    control and debugging options
500
501       temperature
502              Unique ID display format and temperature scale
503
504   -V --version
505       Version of this program and related libraries.
506

TIME OPTIONS

508       Timeouts for the bus masters were previously listed in Device  options.
509       Timeouts  for  the  cache  affect  the  time that data stays in memory.
510       Default values are shown.
511
512   --timeout_volatile=15
513       Seconds until a volatile property expires in the cache. Volatile  prop‐
514       erties are those (like temperature) that change on their own.
515
516       Can be changed dynamically at /settings/timeout/volatile
517
518   --timeout_stable=300
519       Seconds until a stable property expires in the cache. Stable properties
520       are those that shouldn't change unless explicitly changed. Memory  con‐
521       tents for example.
522
523       Can be changed dynamically at /settings/timeout/stable
524
525   --timeout_directory=60
526       Seconds until a directory listing expires in the cache. Directory lists
527       are the 1-wire devices found on the bus.
528
529       Can be changed dynamically at /settings/timeout/directory
530
531   --timeout_presence=120
532       Seconds until the presence and bus location of a 1-wire device  expires
533       in the cache.
534
535       Can be changed dynamically at /settings/timeout/presence
536
537       There are also timeouts for specific program responses:
538
539   --timeout_server=5
540       Seconds  until  the  expected  response from the owserver (1) is deemed
541       tardy.
542
543       Can be changed dynamically at /settings/timeout/server
544
545   --timeout_ftp=900
546       Seconds that an ftp session is kept alive.
547
548       Can be changed dynamically at /settings/timeout/ftp
549

EXAMPLE

551       owhttpd -p 3001 -d /dev/ttyS0
552              Web server runs on tcp port 3001, serial adapter at ttyS0
553
554       owhttpd -p 3001 -s littlehost:4304 --error_level=3
555              Web server on port 3001, from owserver process on host  "little‐
556              host", extensive error messages.
557
558       owhttpd -p 3001 -u -u2 -r
559              Read-only web server on port 3001, using two usb adapters.
560

AVAILABILITY

562       http://www.owfs.org
563

SEE ALSO

565   Programs
566       owfs  (1)  owhttpd  (1)  owftpd  (1)  owserver (1) owdir (1) owread (1)
567       owwrite (1) owpresent (1) owtap (1)
568
569   Configuration and testing
570       owfs (5) owtap (1) owmon (1)
571
572   Language bindings
573       owtcl (3) owperl (3) owcapi (3)
574
575   Clocks
576       DS1427 (3) DS1904(3) DS1994 (3)  DS2404  (3)  DS2404S  (3)  DS2415  (3)
577       DS2417 (3)
578
579   ID
580       DS2401 (3) DS2411 (3) DS1990A (3)
581
582   Memory
583       DS1982  (3)  DS1985  (3)  DS1986  (3)  DS1991 (3) DS1992 (3) DS1993 (3)
584       DS1995 (3) DS1996 (3) DS2430A (3) DS2431  (3)  DS2433  (3)  DS2502  (3)
585       DS2506 (3) DS28E04 (3) DS28EC20 (3)
586
587   Switches
588       DS2405 (3) DS2406 (3) DS2408 (3) DS2409 (3) DS2413 (3) DS28EA00 (3)
589
590   Temperature
591       DS1822  (3)  DS1825  (3)  DS1820 (3) DS18B20 (3) DS18S20 (3) DS1920 (3)
592       DS1921 (3) DS1821 (3) DS28EA00 (3) DS28E04 (3)
593
594   Humidity
595       DS1922 (3)
596
597   Voltage
598       DS2450 (3)
599
600   Resistance
601       DS2890 (3)
602
603   Multifunction (current, voltage, temperature)
604       DS2436 (3) DS2437 (3) DS2438 (3)  DS2751  (3)  DS2755  (3)  DS2756  (3)
605       DS2760 (3) DS2770 (3) DS2780 (3) DS2781 (3) DS2788 (3) DS2784 (3)
606
607   Counter
608       DS2423 (3)
609
610   LCD Screen
611       LCD (3) DS2408 (3)
612
613   Crypto
614       DS1977 (3)
615
616   Pressure
617       DS2406 (3) -- TAI8570
618

AUTHOR

620       Paul Alfille (paul.alfille@gmail.com)
621
622
623
624OWFS Manpage                         2004                           OWHTTPD(1)
Impressum