Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
OWNet(3)	      User Contributed Perl Documentation	      OWNet(3)

NAME
       OWNet - Light weight access to owserver

SYNOPSIS
       OWNet is	an easy	way to access owserver and thence the 1-wire bus.

       Dallas Semiconductor's 1-wire system uses simple	wiring and unique
       addresses for its interesting devices. The One Wire File	System (OWFS)
       is a suite of programs that hide	1-wire details behind a	file system
       metaphor. owserver connects to the 1-wire bus and provides network
       access.

       OWNet is	a perl module that connects to owserver	and allows reading,
       writing and listing the 1-wire bus.

       Example perl program that prints	the temperature:

	use OWNet ;
	print OWNet::read( "localhost:4304" , "/10.67C6697351FF/temperature" ) ."\n" ;

       There is	the alternative	object oriented	form:

	use OWNet ;
	my $owserver = OWNet->new( "localhost:4304" ) ;
	print $owserver->read( "/10.67C6697351FF/temperature" )	."\n" ;

SYNTAX
   methods
       new
	    my $owserver = OWNet -> new( address ) ;

       read
	    OWNet::read( address, path [,size [,offset]] )
	    $owserver -> read( path [,size [,offset]] )

       write
	    OWNet::write( address, path, value [,offset] )
	    $owserver -> write(	path, value [,offset] )

       dir
	    OWNet::dir(	address, path )
	    $owserver -> dir( path )

   address
       TCP/IP address of owserver. Valid forms:

       name test.owfs.net:4304
       quad number: 123.231.312.213:4304
       host localhost:4304
       port 4304

   additional arguments
       Additional arguments to add to address

       Temperature scale can also be specified in the address. Same syntax as
       the other OWFS programs:

       -C Celsius (Centigrade)
       -F Fahrenheit
       -K Kelvin
       -R Rankine

       Pressure	scale can also be specified in the address. Same syntax	as the
       other OWFS programs:

       --mbar	  millibar (default)
       --atm	  atmosphere
       --mmHg	  mm Mercury
       --inHg	  inch Mercury
       --psi	  pounds per inch^2
       --Pa	  pascal

       Device display format (1-wire unique address) can also be specified in
       the address, with the general form of -ff[.]i[[.]c] (family id crc):

       -ff.i   /10.67C6697351FF	(default)
       -ffi    /1067C6697351FF
       -ff.i.c /10.67C6697351FF.8D
       -ff.ic  /10.67C6697351FF8D
       -ffi.c  /1067C6697351FF.8D
       -ffic   /1067C6697351FF8D

       Show directories	that are themselves directories	with a '/' suffix (
       e.g. /10.67C6697351FF/ )

       -slash  show directory elements

       Warning messages	will only be displayed if verbose flag is specified in
       address

       -v      verbose

   path
       owfs-type path to an item on the	1-wire bus. Valid forms:

       main directories
	   Used	for the	dir method. E.g. "/" "/uncached"
	   "/1F.321432320000/main"

       device directory
	   Used	for the	dir and	present	method.	E.g. "/10.4300AC220000"
	   "/statistics"

       device properties
	   Used	to read, write.	E.g. "/10.4300AC220000/temperature"

   value
       New value for a device property.	Used by	write.

METHODS
       new Object-oriented (only):

	   OWNet::new( address )

	   Create a new	OWNet object --	corresponds to an owserver.

	   Error (and undef return value) if:

	   1 Badly formed tcp/ip address
	   2 No	owserver at address

       read
	   Non object-oriented:
	       OWNet::read( address , path [ , size [ ,	offset ] ] )

	   Object-oriented:
	       $ownet->read( path [ , size [ , offset ]	] )

	   Read	the value of a 1-wire device property. Returns the (scalar
	   string) value of the	property.

	   size	(number	of bytes to read) is optional

	   offset (number of bytes from	start of field to start	write) is
	   optional

	   Error (and undef return value) if:

	   1 (Non object) No owserver at address
	   2 (Object form) Not called with a valid OWNet object
	   3 Bad path
	   4 path not a	readable device	property

       write
	   Non object-oriented:
	       OWNet::write( address , path , value [ ,	offset ] )

	   Object-oriented:
	       $ownet->write( path , value [ , offset ]	)

	   Set the value of a 1-wire device property. Returns "1" on success.

	   offset (number of bytes from	start of field to start	write) is
	   optional

	   Error (and undef return value) if:

	   1 (Non object) No owserver at address
	   2 (Object form) Not called with a valid OWNet object
	   3 Bad path
	   4 path not a	writable device	property
	   5 value incorrect size or format

       dir
	   Non object-oriented:
	       OWNet::dir( address , path )

	   Object-oriented:
	       $ownet->dir( path )

	   Return a comma-separated list of the	entries	in path. Entries are
	   equivalent to "fully	qualified names" -- full path names.

	   Error (and undef return value) if:

	   1 (Non object) No owserver at address
	   2 (Object form) Not called with a valid OWNet object
	   3 Bad path
	   4 path not a	directory

       present (deprecated)
	   Non object-oriented:
	       OWNet::present( address , path )

	   Object-oriented:
	       $ownet->present(	path )

	   Test	if a 1-wire device exists.

	   Error (and undef return value) if:

	   1 (Non object) No owserver at address
	   2 (Object form) Not called with a valid OWNet object
	   3 Bad path
	   4 path not a	device

DESCRIPTION
   OWFS
       OWFS is a suite of programs that	allows easy access to Dallas
       Semiconductor's 1-wire bus and devices.	OWFS provides a	consistent
       naming scheme, safe multplexing of 1-wire traffice, multiple methods of
       access and display, and network access.	The basic OWFS metaphor	is a
       file-system, with the bus beinng	the root directory, each device	a
       subdirectory, and the the device	properties (e.g. voltage, temperature,
       memory) a file.

   1-Wire
       1-wire is a protocol allowing simple connection of inexpensive devices.
       Each device has a unique	ID number (used	in its OWFS address) and is
       individually addressable.  The bus itself is extremely simple --	a data
       line and	a ground. The data line	also provides power.  1-wire devices
       come in a variety of packages --	chips, commercial boxes, and iButtons
       (stainless steel	cans).	1-wire devices have a variety of capabilities,
       from simple ID to complex voltage, temperature, current measurements,
       memory, and switch control.

   Programs
       Connection to the 1-wire	bus is either done by bit-banging a digital
       pin on the processor, or	by using a bus master -- USB, serial, i2c,
       parallel.  The heavy-weight OWFS	programs: owserver owfs	owhttpd	owftpd
       and the heavy-weight perl module	OW all link in the full	OWFS library
       and can connect directly	to the bus master(s) and/or to owserver.

       OWNet is	a light-weight module. It connects only	to an owserver,	does
       not link	in the OWFS library, and should	be more	portable..

   Object-oriented
       OWNet can be used in either a classical (non-object-oriented) manner,
       or with objects.	 The object stored the ip address of the owserver and
       a network socket	to communicate.	 OWNet will use	persistent tcp
       connections for the object form -- potentially a	performance boost over
       a slow network.

EXAMPLES
   owserver
       owserver	is a separate process that must	be accessible on the network.
       It allows multiple clients, and can connect to many physical 1-wire
       adapters	and 1-wire devices. It's address must be discoverable --
       either set on the command line, or at it's default location, or by
       using Bonjour (zeroconf)	service	discovery.

       An example owserver invocation for a serial adapter and explicitly
       chooses the default port:

	owserver -d /dev/ttyS0 -p 4304

   OWNet
	use OWNet ;

	# Create owserver object
	my $owserver = OWNet->new('localhost:4304 -v -F') ; #default location, verbose errors, Fahrenheit degrees
	# my $owserver = OWNet->new() ;	#simpler, again	default	location, no error messages, default Celsius

	#print directory
	print $owserver->dir('/') ;

	#print temperature from	known device (DS18S20,	ID: 10.13224366A280)
	print "Temperature: ".$owserver->read('/uncached/10.13224366A280/temperature') ;

	# Now for some fun -- a	tree of	everything:
	sub Tree($$) {
	  my $ow = shift ;
	  my $path = shift ;

	  print	"$path\t" ;

	  # first try to read
	  my $value = $ow->read($path) ;
	  if ( defined($value) ) {
	    print "$value\n";
	    return ;
	  }

	  # not	readable, try as directory
	  my $dirstring	= $ow->dir($path) ;
	  if ( defined($dirstring) ) {
	    print "<directory>\n" ;
	    my @dir = split /,/	,  $ow->dir($path) ;
	    foreach (@dir) {
	       Tree($ow,$_) ;
	    }
	    return ;
	  }

	  # can't read,	not directory
	  print	"<write-only>\n" ;
	  return ;
	}

	Tree( $owserver, '/' ) ;

INTERNALS
   Object properties (All private)
       ADDR
	   literal sting for the IP address, in	dotted-quad or host format.
	   This	property is also used to indicate a substantiated object.

       PORT
	   string for the port number (or service name). Service name must be
	   specified as	:owserver or the like.

       SG  Flag	sent to	server,	and returned, that encodes temperature scale
	   and display format. Persistence is also encoded in this word	in the
	   actual tcp message, but kept	separately in the object.

       VERBOSE
	   Print error messages? Set by	"-v" in	object invocation.

       SLASH
	   Add "/" to the end of directory entries. Set	by "-slash" in object
	   invocation.

       SOCK
	   Socket address (object) for communication. Stays defined for
	   persistent connections, else	deleted	between	calls.

       PERSIST
	   State of socket connection (persistent means	the same socket	is
	   used	which speeds network communication).

       VER owprotocol version number (currently	0)

   Private methods
       _self
	   Takes either	the implicit object reference (if called on an object)
	   or the ip address in	non-object format.  In either case a socket is
	   created, the	persistence bit	is properly set, and the address
	   parsed.  Returns the	object reference, or undef on error.  Called
	   by each external method (read,write,dir) on the first parameter.

       _new
	   Takes command line invocation parameters (for an object or not) and
	   properly parses and sets up the properties in a hash	array.

       _Sock
	   Socket processing, including	tests for persistence and opening.  If
	   no host is specified, localhost (127.0.0.1) is used.	 If no port is
	   specified, uses the IANA allocated well known port (4304) for
	   owserver. First looks in /etc/services, then	just tries 4304.

       _ToServer
	   Sends a message to owserver.	Formats	in owserver protocol. If a
	   persistent socket fails, retries after new socket created.

       _FromServerBinaryParse
	   Reads a specified length from server

       _FromServer
	   Reads whole packet from server, using _FromServerBinaryParse	(first
	   for header, then payload). Discards ping packets silently.

       _BonjourLookup
	   Uses	the mDNS service discovery protocol to find an available
	   owserver.  Employs NET::Rendezvous (an earlier name or Apple's
	   Bonjour) This module	is loaded only if available. (Uses the method
	   of http://sial.org/blog/2006/12/optional_perl_module_loading.html)

AUTHOR
       Paul H Alfille paul.alfille@gmail.com

BUGS
       Support for proper timeout using	the "select" function seems broken in
       perl. This might	leave the routines vulnerable to network timing
       errors.

SEE ALSO
       http://www.owfs.org
	   Documentation for the full owfs program suite, including man	pages
	   for each of the supported 1-wire devices, and more extensive
	   explanatation of owfs components.

       http://owfs.sourceforge.net/projects/owfs
	   Location where source code is hosted.

COPYRIGHT
       Copyright (c) 2007 Paul H Alfille. All rights reserved.
	This program is	free software; you can redistribute it and/or
	modify it under	the same terms as Perl itself.

perl v5.10.0			  2010-06-15			      OWNet(3)

NAME | SYNOPSIS | SYNTAX | METHODS | DESCRIPTION | EXAMPLES | INTERNALS | AUTHOR | BUGS | SEE ALSO | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=OWNet&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help