1OWNet(3) User Contributed Perl Documentation OWNet(3)
2
6 OWNet - Light weight access to owserver
7
9 OWNet is an easy way to access owserver and thence the 1-wire bus.
10 Dallas Semiconductor's 1-wire system uses simple wiring and unique
12 addresses for its interesting devices. The One Wire File System (OWFS)
13 is a suite of programs that hide 1-wire details behind a file system
14 metaphor. owserver connects to the 1-wire bus and provides network
15 access.
16 OWNet is a perl module that connects to owserver and allows reading,
18 writing and listing the 1-wire bus.
19 Example perl program that prints the temperature:
21 use OWNet ;
23 print OWNet::read( "localhost:4304" , "/10.67C6697351FF/temperature" ) ."\n" ;
24 There is the alternative object oriented form:
26 use OWNet ;
28 my $owserver = OWNet->new( "localhost:4304" ) ;
29 print $owserver->read( "/10.67C6697351FF/temperature" ) ."\n" ;
30
32 methods
33 new
34 my $owserver = OWNet -> new( address ) ;
35 read
37 OWNet::read( address, path [,size [,offset]] )
38 $owserver -> read( path [,size [,offset]] )
39 write
41 OWNet::write( address, path, value [,offset] )
42 $owserver -> write( path, value [,offset] )
43 dir
45 OWNet::dir( address, path )
46 $owserver -> dir( path )
47 address
49 TCP/IP address of owserver. Valid forms:
50 name test.owfs.net:4304
52 quad number: 123.231.312.213:4304
53 host localhost:4304
54 port 4304
55 additional arguments
57 Additional arguments to add to address
58 Temperature scale can also be specified in the address. Same syntax as
60 the other OWFS programs:
61 -C Celsius (Centigrade)
63 -F Fahrenheit
64 -K Kelvin
65 -R Rankine
66 Pressure scale can also be specified in the address. Same syntax as the
68 other OWFS programs:
69 --mbar millibar (default)
71 --atm atmosphere
72 --mmHg mm Mercury
73 --inHg inch Mercury
74 --psi pounds per inch^2
75 --Pa pascal
76 Device display format (1-wire unique address) can also be specified in
78 the address, with the general form of -ff[.]i[[.]c] (family id crc):
79 -ff.i /10.67C6697351FF (default)
81 -ffi /1067C6697351FF
82 -ff.i.c /10.67C6697351FF.8D
83 -ff.ic /10.67C6697351FF8D
84 -ffi.c /1067C6697351FF.8D
85 -ffic /1067C6697351FF8D
86 Show directories that are themselves directories with a '/' suffix (
88 e.g. /10.67C6697351FF/ )
89 -slash show directory elements
91 Warning messages will only be displayed if verbose flag is specified in
93 address
94 -v verbose
96 path
98 owfs-type path to an item on the 1-wire bus. Valid forms:
99 main directories
101 Used for the dir method. E.g. "/" "/uncached"
102 "/1F.321432320000/main"
103 device directory
105 Used for the dir and present method. E.g. "/10.4300AC220000"
106 "/statistics"
107 device properties
109 Used to read, write. E.g. "/10.4300AC220000/temperature"
110 value
112 New value for a device property. Used by write.
113
115 new Object-oriented (only):
116 OWNet::new( address )
118 Create a new OWNet object -- corresponds to an owserver.
120 Error (and undef return value) if:
122 1 Badly formed tcp/ip address
124 2 No owserver at address
125 read
127 Non object-oriented:
128 OWNet::read( address , path [ , size [ , offset ] ] )
129 Object-oriented:
131 $ownet->read( path [ , size [ , offset ] ] )
132 Read the value of a 1-wire device property. Returns the (scalar
134 string) value of the property.
135 size (number of bytes to read) is optional
137 offset (number of bytes from start of field to start write) is
139 optional
140 Error (and undef return value) if:
142 1 (Non object) No owserver at address
144 2 (Object form) Not called with a valid OWNet object
145 3 Bad path
146 4 path not a readable device property
147 write
149 Non object-oriented:
150 OWNet::write( address , path , value [ , offset ] )
151 Object-oriented:
153 $ownet->write( path , value [ , offset ] )
154 Set the value of a 1-wire device property. Returns "1" on success.
156 offset (number of bytes from start of field to start write) is
158 optional
159 Error (and undef return value) if:
161 1 (Non object) No owserver at address
163 2 (Object form) Not called with a valid OWNet object
164 3 Bad path
165 4 path not a writable device property
166 5 value incorrect size or format
167 dir
169 Non object-oriented:
170 OWNet::dir( address , path )
171 Object-oriented:
173 $ownet->dir( path )
174 Return a comma-separated list of the entries in path. Entries are
176 equivalent to "fully qualified names" -- full path names.
177 Error (and undef return value) if:
179 1 (Non object) No owserver at address
181 2 (Object form) Not called with a valid OWNet object
182 3 Bad path
183 4 path not a directory
184 present (deprecated)
186 Non object-oriented:
187 OWNet::present( address , path )
188 Object-oriented:
190 $ownet->present( path )
191 Test if a 1-wire device exists.
193 Error (and undef return value) if:
195 1 (Non object) No owserver at address
197 2 (Object form) Not called with a valid OWNet object
198 3 Bad path
199 4 path not a device
200
203 OWFS
204 OWFS is a suite of programs that allows easy access to Dallas
205 Semiconductor's 1-wire bus and devices. OWFS provides a consistent
206 naming scheme, safe multplexing of 1-wire traffice, multiple methods of
207 access and display, and network access. The basic OWFS metaphor is a
208 file-system, with the bus beinng the root directory, each device a
209 subdirectory, and the the device properties (e.g. voltage, temperature,
210 memory) a file.
211 1-Wire
213 1-wire is a protocol allowing simple connection of inexpensive devices.
214 Each device has a unique ID number (used in its OWFS address) and is
215 individually addressable. The bus itself is extremely simple -- a data
216 line and a ground. The data line also provides power. 1-wire devices
217 come in a variety of packages -- chips, commercial boxes, and iButtons
218 (stainless steel cans). 1-wire devices have a variety of capabilities,
219 from simple ID to complex voltage, temperature, current measurements,
220 memory, and switch control.
221 Programs
223 Connection to the 1-wire bus is either done by bit-banging a digital
224 pin on the processor, or by using a bus master -- USB, serial, i2c,
225 parallel. The heavy-weight OWFS programs: owserver owfs owhttpd owftpd
226 and the heavy-weight perl module OW all link in the full OWFS library
227 and can connect directly to the bus master(s) and/or to owserver.
228 OWNet is a light-weight module. It connects only to an owserver, does
230 not link in the OWFS library, and should be more portable..
231 Object-oriented
233 OWNet can be used in either a classical (non-object-oriented) manner,
234 or with objects. The object stored the ip address of the owserver and
235 a network socket to communicate. OWNet will use persistent tcp
236 connections for the object form -- potentially a performance boost over
237 a slow network.
238
240 owserver
241 owserver is a separate process that must be accessible on the network.
242 It allows multiple clients, and can connect to many physical 1-wire
243 adapters and 1-wire devices. It's address must be discoverable --
244 either set on the command line, or at it's default location, or by
245 using Bonjour (zeroconf) service discovery.
246 An example owserver invocation for a serial adapter and explicitly
248 chooses the default port:
249 owserver -d /dev/ttyS0 -p 4304
251 OWNet
253 use OWNet ;
254 # Create owserver object
256 my $owserver = OWNet->new('localhost:4304 -v -F') ; #default location, verbose errors, Fahrenheit degrees
257 # my $owserver = OWNet->new() ; #simpler, again default location, no error messages, default Celsius
258 #print directory
260 print $owserver->dir('/') ;
261 #print temperature from known device (DS18S20, ID: 10.13224366A280)
263 print "Temperature: ".$owserver->read('/uncached/10.13224366A280/temperature') ;
264 # Now for some fun -- a tree of everything:
266 sub Tree($$) {
267 my $ow = shift ;
268 my $path = shift ;
269 print "$path\t" ;
271 # first try to read
273 my $value = $ow->read($path) ;
274 if ( defined($value) ) {
275 print "$value\n";
276 return ;
277 }
278 # not readable, try as directory
280 my $dirstring = $ow->dir($path) ;
281 if ( defined($dirstring) ) {
282 print "<directory>\n" ;
283 my @dir = split /,/ , $ow->dir($path) ;
284 foreach (@dir) {
285 Tree($ow,$_) ;
286 }
287 return ;
288 }
289 # can't read, not directory
291 print "<write-only>\n" ;
292 return ;
293 }
294 Tree( $owserver, '/' ) ;
296
298 Object properties (All private)
299 ADDR
300 literal sting for the IP address, in dotted-quad or host format.
301 This property is also used to indicate a substantiated object.
302 PORT
304 string for the port number (or service name). Service name must be
305 specified as :owserver or the like.
306 SG Flag sent to server, and returned, that encodes temperature scale
308 and display format. Persistence is also encoded in this word in the
309 actual tcp message, but kept separately in the object.
310 VERBOSE
312 Print error messages? Set by "-v" in object invocation.
313 SLASH
315 Add "/" to the end of directory entries. Set by "-slash" in object
316 invocation.
317 SOCK
319 Socket address (object) for communication. Stays defined for
320 persistent connections, else deleted between calls.
321 PERSIST
323 State of socket connection (persistent means the same socket is
324 used which speeds network communication).
325 VER owprotocol version number (currently 0)
327 Private methods
329 _self
330 Takes either the implicit object reference (if called on an object)
331 or the ip address in non-object format. In either case a socket is
332 created, the persistence bit is properly set, and the address
333 parsed. Returns the object reference, or undef on error. Called
334 by each external method (read,write,dir) on the first parameter.
335 _new
337 Takes command line invocation parameters (for an object or not) and
338 properly parses and sets up the properties in a hash array.
339 _Sock
341 Socket processing, including tests for persistence and opening. If
342 no host is specified, localhost (127.0.0.1) is used. If no port is
343 specified, uses the IANA allocated well known port (4304) for
344 owserver. First looks in /etc/services, then just tries 4304.
345 _ToServer
347 Sends a message to owserver. Formats in owserver protocol. If a
348 persistent socket fails, retries after new socket created.
349 _FromServerBinaryParse
351 Reads a specified length from server
352 _FromServer
354 Reads whole packet from server, using _FromServerBinaryParse (first
355 for header, then payload). Discards ping packets silently.
356 _BonjourLookup
358 Uses the mDNS service discovery protocol to find an available
359 owserver. Employs NET::Rendezvous (an earlier name or Apple's
360 Bonjour) This module is loaded only if available. (Uses the method
361 of http://sial.org/blog/2006/12/optional_perl_module_loading.html)
362
364 Paul H Alfille paul.alfille@gmail.com
365
367 Support for proper timeout using the "select" function seems broken in
368 perl. This might leave the routines vulnerable to network timing
369 errors.
370
372 http://www.owfs.org
373 Documentation for the full owfs program suite, including man pages
374 for each of the supported 1-wire devices, and more extensive
375 explanatation of owfs components.
376 http://owfs.sourceforge.net/projects/owfs
378 Location where source code is hosted.
379
381 Copyright (c) 2007 Paul H Alfille. All rights reserved.
382 This program is free software; you can redistribute it and/or
383 modify it under the same terms as Perl itself.
384perl v5.10.0 2010-06-15 OWNet(3)