1OWHTTPD(1) One-Wire File System OWHTTPD(1)
2
6 owhttpd - Tiny webserver for 1-wire control
7
9 owhttpd [ -c config ] -d serialport | -u | -s [host:]port -p tcp-port
10
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 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 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 Bus masters come in a variety of configurations including serial, par‐
29 allel, i2c, network or USB adapters.
30 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 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 fundemental goal has been ease of use, flexibil‐
44 ity and correctness rather than speed.
45 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 owhttpd (1) uses the same naming convention as owfs (1) , where the URL
53 corresponds to the filename.
54 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
60 -p portnum
61 Sets the tcp port the web server runs on. Access with the URL
62 http://servernameoripaddress:portnum
63 If no port is specified, an ephemeral port is selected by the operating
65 system. Use zeroconf (Bonjour) to discover the assigned port.
66
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 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 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
83 port specifies a serial port, e.g. /dev/ttyS0 or an USB port accessed
84 as serial port, e.g. /dev/ttyUSB0
85 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 -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 --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 --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 --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 --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 --ha7e=port (HA7E)
123 Embedded Data Systems HA7E adapter ( and HA7S ) in native ascii
124 mode.
125 --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 --checksum | --no_checksum (HA5)
133 Turn on (default) or off the checksum feature of the HA5 commu‐
134 nication.
135 --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 --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 --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
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 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 -u | --usb
160 DS2490 based bus master (like the DS9490R).
161 -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 -uall | --usb=ALL
168 Use all the USB devices.
169 --usb_flextime | --usb_regulartime
171 Changes the details of 1-wire waveform timing for certain net‐
172 work configurations.
173 --altusb
175 Willy Robion's alternative USB timing.
176 --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
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 i2c_address
187 0,1,2,3
189 0x18,0x19,0x1A,0x1B
190 4,5,6,7
192 0x1C,0x1D,0x1E,0x1F (DS2482-800 only)
193 port for i2c masters have the form /dev/i2c-0, /dev/i2c-1, ...
195 -d port | --device=port
197 This simple form only permits a specific port and the first
198 available i2c_address
199 --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 --i2c | --i2c=: | --i2c=ALL:ALL
205 Search the available i2c buses for either the first, the first,
206 or every i2c adapter.
207 The DS2482-800 masters 8 1-wire buses and so will generate 8 /bus.n
209 entries.
210
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 E.g. 192.168.0.1:3000 or localhost:3000
217 --link=network_address
219 LinkHubE network LINK adapter by iButtonLink
220 --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 --etherweather=network_address
228 Etherweather adapter
229 -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 --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
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 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 10,05,21
249 Hexidecimal family codes (the DS18S20, DS2405 and DS1921 in this
250 example).
251 10.12AB23431211
253 A more complete hexidecimal unique address. Useful when an
254 actual hardware device should be simulated.
255 DS2408,DS2489
257 The 1-wire device name. (Full ID cannot be speciifed in this
258 format).
259 --fake=devices
261 Random address and random values for each read. The device ID is
262 also random (unless specified).
263 --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 --tester=devices
272 Predictable address and predictable values for each read. (See
273 the website for the algorhythm).
274
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 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 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 --w1 Use the linux kernel w1 virtual bus master.
289 --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
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 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 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 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 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 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 ftdi:s:<vendor>:<product>:<serial number>
323 the device with given vendor id, product id and serial number
324 string
325 The above formats are parsed fully by libftdi (minus the ftdi: prefix).
327 Simplified device serial-only support
329 An additional format is supported, for certain bus types. This only
330 specifies the USB serial number.
331 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 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 An easy way to achieve this would be using chown (1):
345 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 You can also write a udev (1) rule for your adapter:
351 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 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 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 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 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 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
391 -C --Celsius
392 -F --Fahrenheit
393 -K --Kelvin
394 -R --Rankine
395 Temperature scale used for data output. Celsius is the default.
396 Can also be changed within the program at /settings/units/tempera‐
398 ture_scale
399
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 Can also be changed within the program at /settings/units/pres‐
410 sure_scale
411
414 Choose the representation of the 1-wire unique identifiers. OWFS uses
415 these identifiers as unique directory names.
416 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 -f --format="f[.]i[[.]c]"
422 Display format for the 1-wire devices. Each device has a 8byte address,
423 consisting of:
424 f family code, 1 byte
426 i ID number, 6 bytes
428 c CRC checksum, 1 byte
430 Possible formats are f.i (default, 01.A1B2C3D4E5F6), fi fic f.ic f.i.c
432 and fi.c
433 All formats are accepted as input, but the output will be in the speci‐
435 fied format.
436 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
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 -P --pid-file filename
449 Places the PID -- process ID of owfs into the specified filename. Use‐
450 ful for startup scripts control.
451 --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 --error_print=0|1|2|3
457 =0 default mixed destination: stderr foreground / syslog background
458 =1 syslog only
460 =2 stderr only
462 =3 /dev/null (quiet mode).
464 --error_level=0..9
466 =0 default errors only
467 =1 connections/disconnections
469 =2 all high level calls
471 =3 data summary for each call
473 =4 details level
475 >4 debugging chaff
477 --error_level=9 produces a lot of output
479
481 -c file | --configuration file
482 Name of an owfs (5) configuration file with more command line parame‐
483 ters
484
487 See also this man page and the web site http://www.owfs.org
488 -h --help=[device|cache|program|job|temperature]
490 Shows basic summary of options.
491 device 1-wire bus master options
493 cache cache and communication size and timing
495 program
497 mountpoint or TCP server settings
498 job control and debugging options
500 temperature
502 Unique ID display format and temperature scale
503 -V --version
505 Version of this program and related libraries.
506
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 --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 Can be changed dynamically at /settings/timeout/volatile
517 --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 Can be changed dynamically at /settings/timeout/stable
524 --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 Can be changed dynamically at /settings/timeout/directory
530 --timeout_presence=120
532 Seconds until the presence and bus location of a 1-wire device expires
533 in the cache.
534 Can be changed dynamically at /settings/timeout/presence
536 There are also timeouts for specific program responses:
538 --timeout_server=5
540 Seconds until the expected response from the owserver (1) is deemed
541 tardy.
542 Can be changed dynamically at /settings/timeout/server
544 --timeout_ftp=900
546 Seconds that an ftp session is kept alive.
547 Can be changed dynamically at /settings/timeout/ftp
549
551 owhttpd -p 3001 -d /dev/ttyS0
552 Web server runs on tcp port 3001, serial adapter at ttyS0
553 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 owhttpd -p 3001 -u -u2 -r
559 Read-only web server on port 3001, using two usb adapters.
560
562 http://www.owfs.org
563
565 Programs
566 owfs (1) owhttpd (1) owftpd (1) owserver (1) owdir (1) owread (1)
567 owwrite (1) owpresent (1) owtap (1)
568 Configuration and testing
570 owfs (5) owtap (1) owmon (1)
571 Language bindings
573 owtcl (3) owperl (3) owcapi (3)
574 Clocks
576 DS1427 (3) DS1904(3) DS1994 (3) DS2404 (3) DS2404S (3) DS2415 (3)
577 DS2417 (3)
578 ID
580 DS2401 (3) DS2411 (3) DS1990A (3)
581 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 Switches
588 DS2405 (3) DS2406 (3) DS2408 (3) DS2409 (3) DS2413 (3) DS28EA00 (3)
589 Temperature
591 DS1822 (3) DS1825 (3) DS1820 (3) DS18B20 (3) DS18S20 (3) DS1920 (3)
592 DS1921 (3) DS1821 (3) DS28EA00 (3) DS28E04 (3)
593 Humidity
595 DS1922 (3)
596 Voltage
598 DS2450 (3)
599 Resistance
601 DS2890 (3)
602 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 Counter
608 DS2423 (3)
609 LCD Screen
611 LCD (3) DS2408 (3)
612 Crypto
614 DS1977 (3)
615 Pressure
617 DS2406 (3) -- TAI8570
618
620 Paul Alfille (paul.alfille@gmail.com)
621OWFS Manpage 2004 OWHTTPD(1)