1OWSERVER(1) One-Wire File System OWSERVER(1)
2
6 owserver - Backend server (daemon) for 1-wire control
7
9 owserver [ -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 owserver
47 owserver (1) is the backend component of the OWFS 1-wire bus control
48 system. owserver (1) arbitrates access to the bus from multiple client
49 processes. The physical bus is usually connected to a serial or USB
50 port, and other processes connect to owserver (1) over network sockets
51 (tcp port). Communication can be local or over a network. Secure tun‐
52 neling can be implemented using standard techniques.
53 Frontend clients include a filesystem representation: owfs (1) , and a
55 webserver: owhttpd (1). Direct language bindings are also available,
56 e.g: owperl (3). Several instances of each client can be initiated.
57 Each client can also connect directly to the physical bus, skipping
59 owserver (1) but only one client can connect to the physical bus
60 safely. Simultaneous access is prevented by the operating system for
61 USB ports, but unfortunately not serial ports. The safe way to share
62 access to the 1-wire bus is via owserver (1) with the clients connect‐
63 ing. Note: owserver (1) can connect to another owserver (1) process,
64 though the utility of this technique is limited (perhaps as a readonly
65 buffer?)
66 owserver (1) is by default multithreaded. Optional data caching is in
68 the server, not clients, so all the clients gain efficiency.
69
71 These options specify the device (bus master) connecting the computer
72 to the 1-wire bus. The 1-wire slaves are connected to the 1-wire bus,
73 and the bus master connects to a port on the computer and controls the
74 1-wire bus. The bus master is either an actual physical device, the
75 kernel w1 module, or an owserver (1).
76 At least one device option is required. There is no default. More than
78 one device can be listed, and all will be used. (A logical union unless
79 you explore the /bus.n/ directories.)
80 Linux and BSD enforce a security policy restricting access to hardware
82 ports. You must have sufficient rights to access the given port or ac‐
83 cess will silently fail.
84
86 port specifies a serial port, e.g. /dev/ttyS0 or an USB port accessed
87 as serial port, e.g. /dev/ttyUSB0
88 If OWFS was built with libftdi support, you may be able to use the
90 ftdi: prefix in any of the options as port to address a FTDI-based USB
91 device.
92 For details, see the FTDI ADDRESSING section.
93 -d port | --device=port (DS2480B)
95 DS2480B-based bus master (like the DS9097U or an adapter of the
96 LINK family in emulation mode). If the adapter doesn't respond,
97 a passive type (DS9907E or diode/resistor) circuit will be as‐
98 sumed.
99 --serial_flextime | --serial_regulartime (DS2480B)
101 Changes details of bus timing (see DS2480B datasheet). Some de‐
102 vices, like the Swart LCD cannot work with flextime.
103 --baud=1200|9600|19200|38400|57600|115200 (DS2480B,LINK,HA5)
105 Sets the initial serial port communication speed for all bus
106 masters. Not all serial devices support all speeds. You can
107 change the individual bus master speed for a device of the LINK
108 family and DS2880B in the interface/settings directory. The HA5
109 speed is set in hardware, so the command line baud rate should
110 match that rate.
111 Usually the default settings (9600 for a device of the LINK fam‐
112 ily and DS2480B ) and 115200 for the HA5 are sane and shouldn't
113 be changed.
114 --straight_polarity | --reverse_polarity (DS2480B)
116 Reverse polarity of the DS2480B output transistors? Not needed
117 for the DS9097U, but required for some other designs.
118 --link=port (LINK)
120 iButtonLink LINK adapter (all versions) in non-emulation mode.
121 Uses an ascii protocol over serial.
122 This supports the simplified ftdi:<serial number> addressing
123 scheme.
124 --ha7e=port (HA7E)
126 Embedded Data Systems HA7E adapter ( and HA7S ) in native ascii
127 mode.
128 --ha5=port | --ha5=port:a | --ha5=port:acg (HA5)
130 Embedded Data Systems HA5 mutidrop adapter in native ascii mode.
131 Up to 26 adapters can share the same port, each with an assigned
132 letter. If no letter specified, the program will scan for the
133 first response (which may be slow).
134 --checksum | --no_checksum (HA5)
136 Turn on (default) or off the checksum feature of the HA5 commu‐
137 nication.
138 --passive=port | --ha2=port | --ha3=port | --ha4b=port (Passive)
140 Passive 1-wire adapters. Powered off the serial port and using
141 passive electrical components (resitors and diodes).
142 --8bit | --6bit (Passive)
144 Synthesize the 1-wire waveforme using a 6-bit (default) serial
145 word, or 8-bit word. Not all UART devices support 6 bit opera‐
146 tion.
147 --timeout_serial=5
149 Timeout (in seconds) for all serial communications. 5 second de‐
150 fault. Can be altered dynamically under /settings/timeout/serial
151
153 The only supported true USB bus masters are based on the DS2490 chip.
154 The most common is the DS9490R which has an included 1-wire ID slave
155 with family code 81.
156 There are also bus masters based on the serial chip with a USB to se‐
158 rial conversion built in. These are supported by the serial bus master
159 protocol.
160 -u | --usb
162 DS2490 based bus master (like the DS9490R).
163 -u2 | --usb=2
165 Use the second USB bus master. (The order isn't predicatble,
166 however, since the operating system does not consistently order
167 USB devices).
168 -uall | --usb=ALL
170 Use all the USB devices.
171 --usb_flextime | --usb_regulartime
173 Changes the details of 1-wire waveform timing for certain net‐
174 work configurations.
175 --altusb
177 Willy Robion's alternative USB timing.
178 --timeout_usb=5
180 Timeout for USB communications. This has a 5 second default and
181 can be changed dynamically under /settings/timeout/usb
182
184 I2C is 2 wire protocol used for chip-to-chip communication. The bus
185 masters: DS2482-100, DS2482-101 and DS2482-800 can specify (via pin
186 voltages) a subset of addresses on the i2c bus. Those choices are
187 i2c_address
189 0,1,2,3
191 0x18,0x19,0x1A,0x1B
192 4,5,6,7
194 0x1C,0x1D,0x1E,0x1F (DS2482-800 only)
195 port for i2c masters have the form /dev/i2c-0, /dev/i2c-1, ...
197 -d port | --device=port
199 This simple form only permits a specific port and the first
200 available i2c_address
201 --i2c=port | --i2c=port:i2c_address | --i2c=port:ALL
203 Specific i2c port and the i2c_address is either the first, spe‐
204 cific, or all or them. The i2c_address is 0,1,2,...
205 --i2c | --i2c=: | --i2c=ALL:ALL
207 Search the available i2c buses for either the first, the first,
208 or every i2c adapter.
209 The DS2482-800 masters 8 1-wire buses and so will generate 8 /bus.n en‐
211 tries.
212
214 These bus masters communicate via the tcp/ip network protocol and so
215 can be located anywhere on the network. The network_address is of the
216 form tcp_address:port
217 E.g. 192.168.0.1:3000 or localhost:3000
219 --link=network_address
221 LinkHubE network LINK adapter by iButtonLink
222 --ha7net=network_address | --ha7net
224 HA7Net network 1-wire adapter with specified tcp address or dis‐
225 covered by udp multicast. By Embedded Data Systems
226 --timeout_ha7=60 specific timeout for HA7Net communications (60
227 second default).
228 --etherweather=network_address
230 Etherweather adapter
231 -s network_address | --server=network_address
233 Location of an owserver (1) program that talks to the 1-wire
234 bus. The default port is 4304.
235 --timeout_network=5
237 Timeout for network bus master communications. This has a 1 sec‐
238 ond default and can be changed dynamically under /settings/time‐
239 out/network
240
242 Used for testing and development. No actual hardware is needed. Useful
243 for separating the hardware development from the rest of the software
244 design.
245 devices
247 is a list of comma-separated 1-wire devices in the following
248 formats. Note that a valid CRC8 code is created automatically.
249 10,05,21
251 Hexadecimal family codes (the DS18S20, DS2405 and DS1921 in this
252 example).
253 10.12AB23431211
255 A more complete hexadecimal unique address. Useful when an ac‐
256 tual hardware device should be simulated.
257 DS2408,DS2489
259 The 1-wire device name. (Full ID cannot be speciifed in this
260 format).
261 --fake=devices
263 Random address and random values for each read. The device ID is
264 also random (unless specified).
265 --temperature_low=12 --temperature_high=44
267 Specify the temperature limits for the fake adapter simulation.
268 These should be in the same temperature scale that is specified
269 in the command line. It is possible to change the limits dynami‐
270 cally for each adapter under /bus.x/interface/settings/simu‐
271 lated/[temperature_low|temperature_high]
272 --tester=devices
274 Predictable address and predictable values for each read. (See
275 the website for the algorhythm).
276
278 This a linux-specific option for using the operating system's access to
279 bus masters. Root access is required and the implementation was still
280 in progress as of owfs v2.7p12 and linux 2.6.30.
281 Bus masters are recognized and added dynamically. Details of the physi‐
283 cal bus master are not accessible, bu they include USB, i2c and a num‐
284 ber of GPIO designs on embedded boards.
285 Access is restrict to superuser due to the netlink broadcast protocol
287 employed by w1. Multitasking must be configured (threads) on the compi‐
288 lation.
289 --w1 Use the linux kernel w1 virtual bus master.
291 --timeout_w1=10
293 Timeout for w1 netlink communications. This has a 10 second de‐
294 fault and can be changed dynamically under /settings/timeout/w1
295
297 FTDI is a brand of USB-to-serial chips which are very common. If your
298 serial device is connected via a USB serial dongle based on a FTDI
299 chip, or if your adapter uses a built-in FTDI USB chip (for example,
300 the LinkUSB), you can use this FTDI addressing.
301 The main benefit with this mode of access is that we can decrease the
303 communication delay, yielding twice as fast 1-Wire communication in
304 many cases.
305 The following values for port can be used to identify a specific FTDI
307 port in several of the serial devices options.
308 Note that this requires that OWFS is built with libftdi support, which
309 might not be the case in standard repositories.
310 ftdi:d:<device-node>
312 path of bus and device-node (e.g. "003/001") within usb device
313 tree (usually at /proc/bus/usb/ or /dev/bus/usb/)
314 ftdi:i:<vendor>:<product>
316 first device with given vendor and product id, ids can be deci‐
317 mal, octal (preceded by "0") or hex (preceded by "0x")
318 ftdi:i:<vendor>:<product>:<index>
320 as above with index being the number of the device (starting
321 with 0) if there are more than one
322 ftdi:s:<vendor>:<product>:<serial number>
324 the device with given vendor id, product id and serial number
325 string
326 The above formats are parsed fully by libftdi (minus the ftdi: prefix).
328 Simplified device serial-only support
330 An additional format is supported, for certain bus types. This only
331 specifies the USB serial number.
332 ftdi:<serial number>
334 Identifies a FTDI device by serial number only. Currently, this
335 is only valid for the VID/PID found on the LinkUSB (i.e.
336 --link). Note that those VID/PID's are the default for any
337 FT232R device, and in no way exclusive to LinkUSB.
338 Permsissions
340 In order to run owserver (1) without root privileges - as you should,
341 you must have sufficient permissions to the raw USB node your adapter
342 is connected to e.g. "003/001" (usually at /proc/bus/usb/ or
343 /dev/bus/usb/).
344 An easy way to achieve this would be using chown (1):
346 sudo chown :<your user> /dev/bus/usb/003/001
348 changes the group of the raw USB node "003/001" from default
349 "root" to "<your user>"
350 You can also write a udev (1) rule for your adapter:
352 SUBSYSTEM=="usb", DRIVER=="usb", ATTR{idVendor}=="0403", ATTR{idProd‐
354 uct}=="6001", ATTR{serial}=="AK0048A0", GROUP="owsrv"
355 saved as a file e.g. "10-FTDI-LinkUSB.rules" in
356 "/etc/udev/rules.d/", this rule will automate the process of
357 changing the group to "owsrv" of the raw USB node the LinkUSB
358 adapter with S/N:AK0048A0 is connected to.
359 Serial USB node
361 Communication in FTDI mode accesses the RAW USB node and NOT the serial
362 USB node your OS might have created automatically e.g. /dev/ttyUSB0.
363 As a side effect, if existing, the serial USB node e.g. /dev/ttyUSB0 is
364 removed on successful starting of owserver (1). After it's termination
365 un- and re-plugging the adapter, or un- and reloading of the module
366 ftdi_sio will recreate the serial USB node.
367 Finding FTDI related information on your USB adapter
369 owusbprobe is THE tool to find the information needed for direct FTDI
370 addressing
371 However this tool might not yet be packaged in your version. Alterna‐
372 tively you can also use lsusb to find the usb node your adapter is con‐
373 nected to, and then use lsusb again on this very node:
374 sudo lsusb -D /path/to/your/raw/USB/device/node |egrep "idVendor|id‐
376 Product|iSerial"
377 sudo is necessary to get the value of iSerial field, if the per‐
378 missions are still unchanged
379 Examples FTDI addressing
381 owserver -d ftdi:s:0x0403:0x6001:A800bXHr
382 starts owserver with a LinkUSB
383 (VID:0x0403,PID:0x6001,S/N:A800bXHr) as bus master in DS2480B-
384 based emulation mode with direct FTDI access
385 owserver --link=ftdi:A800bXHr
387 starts owserver with a LinkUSB (S/N:A800bXHr) as bus master
388 identified by serial number only in native mode with direct FTDI
389 access
390
392 -p
393 TCP port or IPaddress:port for owserver
394 Other OWFS programs will access owserver via this address. (e.g. owfs
396 -s IP:port /1wire)
397 If no port is specified, the default well-known port (4304 -- assigned
399 by the IANA) will be used.
400
402 -C --Celsius
403 -F --Fahrenheit
404 -K --Kelvin
405 -R --Rankine
406 Temperature scale used for data output. Celsius is the default.
407 Can also be changed within the program at /settings/units/tempera‐
409 ture_scale
410
412 --mbar (default)
413 --atm
414 --mmHg
415 --inHg
416 --psi
417 --Pa
418 Pressure scale used for data output. Millibar is the default.
419 Can also be changed within the program at /settings/units/pres‐
421 sure_scale
422
425 Choose the representation of the 1-wire unique identifiers. OWFS uses
426 these identifiers as unique directory names.
427 Although several display formats are selectable, all must be in family-
429 id-crc8 form, unlike some other programs and the labelling on iButtons,
430 which are crc8-id-family form.
431 -f --format="f[.]i[[.]c]"
433 Display format for the 1-wire devices. Each device has a 8byte address,
434 consisting of:
435 f family code, 1 byte
437 i ID number, 6 bytes
439 c CRC checksum, 1 byte
441 Possible formats are f.i (default, 01.A1B2C3D4E5F6), fi fic f.ic f.i.c
443 and fi.c
444 All formats are accepted as input, but the output will be in the speci‐
446 fied format.
447 The address elements can be retrieved from a device entry in owfs by
449 the family, id and crc8 properties, and as a whole with address. The
450 reversed id and address can be retrieved as r_id and r_address.
451
453 -r --readonly
454 -w --write
455 Do we allow writing to the 1-wire bus (writing memory, setting
456 switches, limits, PIOs)? The write option is available for symmetry,
457 it's the default.
458 -P --pid-file filename
460 Places the PID -- process ID of owfs into the specified filename. Use‐
461 ful for startup scripts control.
462 --background | --foreground
464 Whether the program releases the console and runs in the background af‐
465 ter evaluating command line options. background is the default.
466 --error_print=0|1|2|3
468 =0 default mixed destination: stderr foreground / syslog background
469 =1 syslog only
471 =2 stderr only
473 =3 /dev/null (quiet mode).
475 --error_level=0..9
477 =0 default errors only
478 =1 connections/disconnections
480 =2 all high level calls
482 =3 data summary for each call
484 =4 details level
486 >4 debugging chaff
488 --error_level=9 produces a lot of output
490
492 -c file | --configuration file
493 Name of an owfs (5) configuration file with more command line parame‐
494 ters
495
498 See also this man page and the web site http://www.owfs.org
499 -h --help=[device|cache|program|job|temperature]
501 Shows basic summary of options.
502 device 1-wire bus master options
504 cache cache and communication size and timing
506 program
508 mountpoint or TCP server settings
509 job control and debugging options
511 temperature
513 Unique ID display format and temperature scale
514 -V --version
516 Version of this program and related libraries.
517
519 Timeouts for the bus masters were previously listed in Device options.
520 Timeouts for the cache affect the time that data stays in memory. De‐
521 fault values are shown.
522 --timeout_volatile=15
524 Seconds until a volatile property expires in the cache. Volatile prop‐
525 erties are those (like temperature) that change on their own.
526 Can be changed dynamically at /settings/timeout/volatile
528 --timeout_stable=300
530 Seconds until a stable property expires in the cache. Stable properties
531 are those that shouldn't change unless explicitly changed. Memory con‐
532 tents for example.
533 Can be changed dynamically at /settings/timeout/stable
535 --timeout_directory=60
537 Seconds until a directory listing expires in the cache. Directory lists
538 are the 1-wire devices found on the bus.
539 Can be changed dynamically at /settings/timeout/directory
541 --timeout_presence=120
543 Seconds until the presence and bus location of a 1-wire device expires
544 in the cache.
545 Can be changed dynamically at /settings/timeout/presence
547 There are also timeouts for specific program responses:
549 --timeout_server=5
551 Seconds until the expected response from the owserver (1) is deemed
552 tardy.
553 Can be changed dynamically at /settings/timeout/server
555 --timeout_ftp=900
557 Seconds that an ftp session is kept alive.
558 Can be changed dynamically at /settings/timeout/ftp
560
562 These settings control the behavior of owserver (1) in granting and
563 dropping persistent tcp connections. The default settings are shown.
564 In general no changes should be needed. In general the purpose is to
566 limit total resource usage from an errant or rogue client.
567 --timeout_persistent_low=600
569 Minimum seconds that a persistent tcp connection to owserver (1) is
570 kept open. This is the limit used when the number of connections is
571 above --clients_persistent_low
572 --timeout_persistent_high=3600
574 Maximum seconds that a persistent tcp connection to owserver (1) is
575 kept open. This is the limit used when the number of connections is be‐
576 low --clients_persistent_low
577 --clients_persistent_low=10
579 Maximum number of persistent tcp connections to owserver (1) before
580 connections start getting the more stringent time limitation --time‐
581 out_persistent_low
582 --clients_persistent_high=20
584 Maximum number of persistent tcp connections to before no more are al‐
585 lowed (only non-persistent at this point). owserver (1) before no more
586 are allowed (only non-persistent at this point).
587
589 --no_dirall
590 Reject DIRALL messages (requests directory as a single message), forc‐
591 ing client to use older DIR method (each element is an individual mes‐
592 sage)
593 --no_get
595 Reject GET messages (lets owserver determine if READ or DIRALL is ap‐
596 propriate). Client will fall back to older methods.
597 --no_persistence
599 Reject persistence in requests. All transactions will have to be new
600 connections.
601 --pingcrazy
603 Interject many "keep-alive" (PING) responses. Usually PING responses
604 are only sent when processing is taking a long time to inform client
605 that owserver is still there.
606
609 owserver -p 3001 -d /dev/ttyS0 runs owserver on tcp port 3001 and con‐
610 nects to a physical 1-wire bus on a serial port.
611
613 Programs
614 owfs (1) owhttpd (1) owftpd (1) owserver (1) owdir (1) owread (1)
615 owwrite (1) owpresent (1) owtap (1)
616 Configuration and testing
618 owfs (5) owtap (1) owmon (1)
619 Language bindings
621 owtcl (3) owperl (3) owcapi (3)
622 Clocks
624 DS1427 (3) DS1904(3) DS1994 (3) DS2404 (3) DS2404S (3) DS2415 (3)
625 DS2417 (3)
626 ID
628 DS2401 (3) DS2411 (3) DS1990A (3)
629 Memory
631 DS1982 (3) DS1985 (3) DS1986 (3) DS1991 (3) DS1992 (3) DS1993 (3)
632 DS1995 (3) DS1996 (3) DS2430A (3) DS2431 (3) DS2433 (3) DS2502 (3)
633 DS2506 (3) DS28E04 (3) DS28EC20 (3)
634 Switches
636 DS2405 (3) DS2406 (3) DS2408 (3) DS2409 (3) DS2413 (3) DS28EA00 (3)
637 Temperature
639 DS1822 (3) DS1825 (3) DS1820 (3) DS18B20 (3) DS18S20 (3) DS1920 (3)
640 DS1921 (3) DS1821 (3) DS28EA00 (3) DS28E04 (3)
641 Humidity
643 DS1922 (3)
644 Voltage
646 DS2450 (3)
647 Resistance
649 DS2890 (3)
650 Multifunction (current, voltage, temperature)
652 DS2436 (3) DS2437 (3) DS2438 (3) DS2751 (3) DS2755 (3) DS2756 (3)
653 DS2760 (3) DS2770 (3) DS2780 (3) DS2781 (3) DS2788 (3) DS2784 (3)
654 Counter
656 DS2423 (3)
657 LCD Screen
659 LCD (3) DS2408 (3)
660 Crypto
662 DS1977 (3)
663 Pressure
665 DS2406 (3) -- TAI8570
666
668 http://www.owfs.org
669
671 Paul Alfille (paul.alfille@gmail.com)
672OWSERVER Manpage 2004 OWSERVER(1)