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 en‐
22 cryption 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 in‐
35 dividual properties of the device are represented as simple files that
36 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 fundamental 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 ac‐
80 cess 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 as‐
95 sumed.
96 --serial_flextime | --serial_regulartime (DS2480B)
98 Changes details of bus timing (see DS2480B datasheet). Some de‐
99 vices, 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 de‐
147 fault. Can be altered dynamically under /settings/timeout/serial
148
150 The only supported true USB bus masters are based on the DS2490 chip.
151 The most common is the DS9490R which has an included 1-wire ID slave
152 with family code 81.
153 There are also bus masters based on the serial chip with a USB to se‐
155 rial conversion built in. These are supported by the serial bus master
156 protocol.
157 -u | --usb
159 DS2490 based bus master (like the DS9490R).
160 -u2 | --usb=2
162 Use the second USB bus master. (The order isn't predicatble,
163 however, since the operating system does not consistently order
164 USB devices).
165 -uall | --usb=ALL
167 Use all the USB devices.
168 --usb_flextime | --usb_regulartime
170 Changes the details of 1-wire waveform timing for certain net‐
171 work configurations.
172 --altusb
174 Willy Robion's alternative USB timing.
175 --timeout_usb=5
177 Timeout for USB communications. This has a 5 second default and
178 can be changed dynamically under /settings/timeout/usb
179
181 I2C is 2 wire protocol used for chip-to-chip communication. The bus
182 masters: DS2482-100, DS2482-101 and DS2482-800 can specify (via pin
183 voltages) a subset of addresses on the i2c bus. Those choices are
184 i2c_address
186 0,1,2,3
188 0x18,0x19,0x1A,0x1B
189 4,5,6,7
191 0x1C,0x1D,0x1E,0x1F (DS2482-800 only)
192 port for i2c masters have the form /dev/i2c-0, /dev/i2c-1, ...
194 -d port | --device=port
196 This simple form only permits a specific port and the first
197 available i2c_address
198 --i2c=port | --i2c=port:i2c_address | --i2c=port:ALL
200 Specific i2c port and the i2c_address is either the first, spe‐
201 cific, or all or them. The i2c_address is 0,1,2,...
202 --i2c | --i2c=: | --i2c=ALL:ALL
204 Search the available i2c buses for either the first, the first,
205 or every i2c adapter.
206 The DS2482-800 masters 8 1-wire buses and so will generate 8 /bus.n en‐
208 tries.
209
211 These bus masters communicate via the tcp/ip network protocol and so
212 can be located anywhere on the network. The network_address is of the
213 form tcp_address:port
214 E.g. 192.168.0.1:3000 or localhost:3000
216 --link=network_address
218 LinkHubE network LINK adapter by iButtonLink
219 --ha7net=network_address | --ha7net
221 HA7Net network 1-wire adapter with specified tcp address or dis‐
222 covered by udp multicast. By Embedded Data Systems
223 --timeout_ha7=60 specific timeout for HA7Net communications (60
224 second default).
225 --etherweather=network_address
227 Etherweather adapter
228 -s network_address | --server=network_address
230 Location of an owserver (1) program that talks to the 1-wire
231 bus. The default port is 4304.
232 --timeout_network=5
234 Timeout for network bus master communications. This has a 1 sec‐
235 ond default and can be changed dynamically under /settings/time‐
236 out/network
237
239 Used for testing and development. No actual hardware is needed. Useful
240 for separating the hardware development from the rest of the software
241 design.
242 devices
244 is a list of comma-separated 1-wire devices in the following
245 formats. Note that a valid CRC8 code is created automatically.
246 10,05,21
248 Hexadecimal family codes (the DS18S20, DS2405 and DS1921 in this
249 example).
250 10.12AB23431211
252 A more complete hexadecimal unique address. Useful when an ac‐
253 tual hardware device should be simulated.
254 DS2408,DS2489
256 The 1-wire device name. (Full ID cannot be speciifed in this
257 format).
258 --fake=devices
260 Random address and random values for each read. The device ID is
261 also random (unless specified).
262 --temperature_low=12 --temperature_high=44
264 Specify the temperature limits for the fake adapter simulation.
265 These should be in the same temperature scale that is specified
266 in the command line. It is possible to change the limits dynami‐
267 cally for each adapter under /bus.x/interface/settings/simu‐
268 lated/[temperature_low|temperature_high]
269 --tester=devices
271 Predictable address and predictable values for each read. (See
272 the website for the algorhythm).
273
275 This a linux-specific option for using the operating system's access to
276 bus masters. Root access is required and the implementation was still
277 in progress as of owfs v2.7p12 and linux 2.6.30.
278 Bus masters are recognized and added dynamically. Details of the physi‐
280 cal bus master are not accessible, bu they include USB, i2c and a num‐
281 ber of GPIO designs on embedded boards.
282 Access is restrict to superuser due to the netlink broadcast protocol
284 employed by w1. Multitasking must be configured (threads) on the compi‐
285 lation.
286 --w1 Use the linux kernel w1 virtual bus master.
288 --timeout_w1=10
290 Timeout for w1 netlink communications. This has a 10 second de‐
291 fault and can be changed dynamically under /settings/timeout/w1
292
294 FTDI is a brand of USB-to-serial chips which are very common. If your
295 serial device is connected via a USB serial dongle based on a FTDI
296 chip, or if your adapter uses a built-in FTDI USB chip (for example,
297 the LinkUSB), you can use this FTDI addressing.
298 The main benefit with this mode of access is that we can decrease the
300 communication delay, yielding twice as fast 1-Wire communication in
301 many cases.
302 The following values for port can be used to identify a specific FTDI
304 port in several of the serial devices options.
305 Note that this requires that OWFS is built with libftdi support, which
306 might not be the case in standard repositories.
307 ftdi:d:<device-node>
309 path of bus and device-node (e.g. "003/001") within usb device
310 tree (usually at /proc/bus/usb/ or /dev/bus/usb/)
311 ftdi:i:<vendor>:<product>
313 first device with given vendor and product id, ids can be deci‐
314 mal, octal (preceded by "0") or hex (preceded by "0x")
315 ftdi:i:<vendor>:<product>:<index>
317 as above with index being the number of the device (starting
318 with 0) if there are more than one
319 ftdi:s:<vendor>:<product>:<serial number>
321 the device with given vendor id, product id and serial number
322 string
323 The above formats are parsed fully by libftdi (minus the ftdi: prefix).
325 Simplified device serial-only support
327 An additional format is supported, for certain bus types. This only
328 specifies the USB serial number.
329 ftdi:<serial number>
331 Identifies a FTDI device by serial number only. Currently, this
332 is only valid for the VID/PID found on the LinkUSB (i.e.
333 --link). Note that those VID/PID's are the default for any
334 FT232R device, and in no way exclusive to LinkUSB.
335 Permsissions
337 In order to run owserver (1) without root privileges - as you should,
338 you must have sufficient permissions to the raw USB node your adapter
339 is connected to e.g. "003/001" (usually at /proc/bus/usb/ or
340 /dev/bus/usb/).
341 An easy way to achieve this would be using chown (1):
343 sudo chown :<your user> /dev/bus/usb/003/001
345 changes the group of the raw USB node "003/001" from default
346 "root" to "<your user>"
347 You can also write a udev (1) rule for your adapter:
349 SUBSYSTEM=="usb", DRIVER=="usb", ATTR{idVendor}=="0403", ATTR{idProd‐
351 uct}=="6001", ATTR{serial}=="AK0048A0", GROUP="owsrv"
352 saved as a file e.g. "10-FTDI-LinkUSB.rules" in
353 "/etc/udev/rules.d/", this rule will automate the process of
354 changing the group to "owsrv" of the raw USB node the LinkUSB
355 adapter with S/N:AK0048A0 is connected to.
356 Serial USB node
358 Communication in FTDI mode accesses the RAW USB node and NOT the serial
359 USB node your OS might have created automatically e.g. /dev/ttyUSB0.
360 As a side effect, if existing, the serial USB node e.g. /dev/ttyUSB0 is
361 removed on successful starting of owserver (1). After it's termination
362 un- and re-plugging the adapter, or un- and reloading of the module
363 ftdi_sio will recreate the serial USB node.
364 Finding FTDI related information on your USB adapter
366 owusbprobe is THE tool to find the information needed for direct FTDI
367 addressing
368 However this tool might not yet be packaged in your version. Alterna‐
369 tively you can also use lsusb to find the usb node your adapter is con‐
370 nected to, and then use lsusb again on this very node:
371 sudo lsusb -D /path/to/your/raw/USB/device/node |egrep "idVendor|id‐
373 Product|iSerial"
374 sudo is necessary to get the value of iSerial field, if the per‐
375 missions are still unchanged
376 Examples FTDI addressing
378 owserver -d ftdi:s:0x0403:0x6001:A800bXHr
379 starts owserver with a LinkUSB
380 (VID:0x0403,PID:0x6001,S/N:A800bXHr) as bus master in DS2480B-
381 based emulation mode with direct FTDI access
382 owserver --link=ftdi:A800bXHr
384 starts owserver with a LinkUSB (S/N:A800bXHr) as bus master
385 identified by serial number only in native mode with direct FTDI
386 access
387
389 -C --Celsius
390 -F --Fahrenheit
391 -K --Kelvin
392 -R --Rankine
393 Temperature scale used for data output. Celsius is the default.
394 Can also be changed within the program at /settings/units/tempera‐
396 ture_scale
397
399 --mbar (default)
400 --atm
401 --mmHg
402 --inHg
403 --psi
404 --Pa
405 Pressure scale used for data output. Millibar is the default.
406 Can also be changed within the program at /settings/units/pres‐
408 sure_scale
409
412 Choose the representation of the 1-wire unique identifiers. OWFS uses
413 these identifiers as unique directory names.
414 Although several display formats are selectable, all must be in family-
416 id-crc8 form, unlike some other programs and the labelling on iButtons,
417 which are crc8-id-family form.
418 -f --format="f[.]i[[.]c]"
420 Display format for the 1-wire devices. Each device has a 8byte address,
421 consisting of:
422 f family code, 1 byte
424 i ID number, 6 bytes
426 c CRC checksum, 1 byte
428 Possible formats are f.i (default, 01.A1B2C3D4E5F6), fi fic f.ic f.i.c
430 and fi.c
431 All formats are accepted as input, but the output will be in the speci‐
433 fied format.
434 The address elements can be retrieved from a device entry in owfs by
436 the family, id and crc8 properties, and as a whole with address. The
437 reversed id and address can be retrieved as r_id and r_address.
438
440 -r --readonly
441 -w --write
442 Do we allow writing to the 1-wire bus (writing memory, setting
443 switches, limits, PIOs)? The write option is available for symmetry,
444 it's the default.
445 -P --pid-file filename
447 Places the PID -- process ID of owfs into the specified filename. Use‐
448 ful for startup scripts control.
449 --background | --foreground
451 Whether the program releases the console and runs in the background af‐
452 ter evaluating command line options. background is the default.
453 --error_print=0|1|2|3
455 =0 default mixed destination: stderr foreground / syslog background
456 =1 syslog only
458 =2 stderr only
460 =3 /dev/null (quiet mode).
462 --error_level=0..9
464 =0 default errors only
465 =1 connections/disconnections
467 =2 all high level calls
469 =3 data summary for each call
471 =4 details level
473 >4 debugging chaff
475 --error_level=9 produces a lot of output
477
479 -c file | --configuration file
480 Name of an owfs (5) configuration file with more command line parame‐
481 ters
482
485 See also this man page and the web site http://www.owfs.org
486 -h --help=[device|cache|program|job|temperature]
488 Shows basic summary of options.
489 device 1-wire bus master options
491 cache cache and communication size and timing
493 program
495 mountpoint or TCP server settings
496 job control and debugging options
498 temperature
500 Unique ID display format and temperature scale
501 -V --version
503 Version of this program and related libraries.
504
506 Timeouts for the bus masters were previously listed in Device options.
507 Timeouts for the cache affect the time that data stays in memory. De‐
508 fault values are shown.
509 --timeout_volatile=15
511 Seconds until a volatile property expires in the cache. Volatile prop‐
512 erties are those (like temperature) that change on their own.
513 Can be changed dynamically at /settings/timeout/volatile
515 --timeout_stable=300
517 Seconds until a stable property expires in the cache. Stable properties
518 are those that shouldn't change unless explicitly changed. Memory con‐
519 tents for example.
520 Can be changed dynamically at /settings/timeout/stable
522 --timeout_directory=60
524 Seconds until a directory listing expires in the cache. Directory lists
525 are the 1-wire devices found on the bus.
526 Can be changed dynamically at /settings/timeout/directory
528 --timeout_presence=120
530 Seconds until the presence and bus location of a 1-wire device expires
531 in the cache.
532 Can be changed dynamically at /settings/timeout/presence
534 There are also timeouts for specific program responses:
536 --timeout_server=5
538 Seconds until the expected response from the owserver (1) is deemed
539 tardy.
540 Can be changed dynamically at /settings/timeout/server
542 --timeout_ftp=900
544 Seconds that an ftp session is kept alive.
545 Can be changed dynamically at /settings/timeout/ftp
547
549 owhttpd -p 3001 -d /dev/ttyS0
550 Web server runs on tcp port 3001, serial adapter at ttyS0
551 owhttpd -p 3001 -s littlehost:4304 --error_level=3
553 Web server on port 3001, from owserver process on host "little‐
554 host", extensive error messages.
555 owhttpd -p 3001 -u -u2 -r
557 Read-only web server on port 3001, using two usb adapters.
558
560 http://www.owfs.org
561
563 Programs
564 owfs (1) owhttpd (1) owftpd (1) owserver (1) owdir (1) owread (1)
565 owwrite (1) owpresent (1) owtap (1)
566 Configuration and testing
568 owfs (5) owtap (1) owmon (1)
569 Language bindings
571 owtcl (3) owperl (3) owcapi (3)
572 Clocks
574 DS1427 (3) DS1904(3) DS1994 (3) DS2404 (3) DS2404S (3) DS2415 (3)
575 DS2417 (3)
576 ID
578 DS2401 (3) DS2411 (3) DS1990A (3)
579 Memory
581 DS1982 (3) DS1985 (3) DS1986 (3) DS1991 (3) DS1992 (3) DS1993 (3)
582 DS1995 (3) DS1996 (3) DS2430A (3) DS2431 (3) DS2433 (3) DS2502 (3)
583 DS2506 (3) DS28E04 (3) DS28EC20 (3)
584 Switches
586 DS2405 (3) DS2406 (3) DS2408 (3) DS2409 (3) DS2413 (3) DS28EA00 (3)
587 Temperature
589 DS1822 (3) DS1825 (3) DS1820 (3) DS18B20 (3) DS18S20 (3) DS1920 (3)
590 DS1921 (3) DS1821 (3) DS28EA00 (3) DS28E04 (3)
591 Humidity
593 DS1922 (3)
594 Voltage
596 DS2450 (3)
597 Resistance
599 DS2890 (3)
600 Multifunction (current, voltage, temperature)
602 DS2436 (3) DS2437 (3) DS2438 (3) DS2751 (3) DS2755 (3) DS2756 (3)
603 DS2760 (3) DS2770 (3) DS2780 (3) DS2781 (3) DS2788 (3) DS2784 (3)
604 Counter
606 DS2423 (3)
607 LCD Screen
609 LCD (3) DS2408 (3)
610 Crypto
612 DS1977 (3)
613 Pressure
615 DS2406 (3) -- TAI8570
616
618 Paul Alfille (paul.alfille@gmail.com)
619OWFS Manpage 2004 OWHTTPD(1)