ownetapi(1)

1OWNET(1)                     One-Wire File System                     OWNET(1)
2
3
4

NAME

6       ownet  ,  (libownet) - easy C-language 1-wire interface to the owserver
7       protocol
8

SYNOPSIS

10       libownet library to link with your program
11
12   Handle
13       OWNET_HANDLE
14       Handle to each owserver connection
15
16   Initialization
17       OWNET_HANDLE OWNET_init( const char * owserver_tcp_address_and_port )
18       Associate an owserver (1) tcp/ip address with a handle.
19
20   Directory listing
21       int  OWNET_dirlist(  OWNET_HANDLE  owserver_handle  ,  const   char   *
22       onewire_path , char ** comma_separated_list )
23       Create a comma-separated list of directory elements.
24
25       int  OWNET_dirprocess(  OWNET_HANDLE  owserver_handle  ,  const  char *
26       onewire_path , void (* dirfunc  )  (void  *,  const  char  *),  void  *
27       passed_on_value )
28       void  dirfunc ( void * passed_on_value , const char * directory_element
29       )
30       Apply function dirfunc to each directory element, along with  an  arbi‐
31       trary passed_on_value.
32
33   Get data
34       int   OWNET_read(   OWNET_HANDLE   owserver_handle   ,   const  char  *
35       onewire_path , const char ** return_string )
36       Read a value (of specified size) from a 1-wire device.
37
38       int  OWNET_lread(  OWNET_HANDLE  owserver_handle   ,   const   char   *
39       onewire_path , const char ** return_string , size_t size , off_t offset
40       )
41       Read a value (of specified size and offset) from a 1-wire device.
42
43       int  OWNET_present(  OWNET_HANDLE  owserver_handle  ,  const   char   *
44       onewire_path )
45       Check if a 1-wire device is present.
46
47   Set data
48       int OWNET_put( OWNET_HANDLE owserver_handle , const char * onewire_path
49       , const char * value_string , size_t size )
50       Write a value (of specified size) to a 1-wire device.
51
52       int  OWNET_lwrite(  OWNET_HANDLE  owserver_handle  ,   const   char   *
53       onewire_path , const char * value_string , size_t size , off_t offset )
54       Write a value (of specified size and offset) to a 1-wire device.
55
56   Close
57       void OWNET_close( OWNET_HANDLE owserver_handle )
58       Close the connection to a particular owserver.
59
60       void OWNET_closeall( void )
61       Close all open owserver connections.
62
63       void OWNET_finish( void )
64       Close all open owserver connections and free all memory.
65
66   Temperature scale
67       void OWNET_set_temperature_scale( char temperature_scale )
68       char OWNET_get_temperature_scale( void )
69       Set and retrieve the temperature scale used for all communications.
70
71   Device format
72       void OWNET_set_device_format( const char * device_format )
73       const char * OWNET_get_device_format( void )
74       Set  and  retrieve  the 1-wire device serial number format used for all
75       communications.
76

FUNCTIONS

78   OW_init
79       OW_init_string offers the full flexibility of the owfs (1) and  owhttpd
80       [1m(1) command line.
81
82       Arguments
83              Can be as simple as jus the device name, a full parameter speci‐
84              fication.  One or  more  device  names  (includes  tcp,  serial,
85              usb...) and command line switches. See owfs (1) for full syntax.
86
87       Returns
88              0  for  success.  -1  on error and errno will be set.  OW_finish
89              does not need to be called if OW_init fails.
90
91       Sequence
92              One of the init functions must be called  before  accessing  the
93              1-wire bus.  OW_finish is optional.
94
95   OW_init_args
96       OW_init_args  offers  the  full flexibility of the owfs (1) and owhttpd
97       [1m(1) command line.
98
99       Arguments
100              One or more device names (includes tcp, serial, usb...) and com‐
101              mand  line  switches.  See  owfs  (1)  for  full  syntax. Unlike
102              OW_init_string the arguments are in argv/argc format.
103
104       Returns
105              0 for success. -1 on error and errno  will  be  set.   OW_finish
106              does not need to be called if OW_init fails.
107
108       Sequence
109              One  of  the  init functions must be called before accessing the
110              1-wire bus.  OW_finish is optional.
111
112   OW_get
113       OW_get is used to get directory listings and file contents. The results
114       are put in a dynamically allocated buffer.
115
116       Arguments
117              path  is  the path to the directory or file (property).  *buffer
118              returns a pointer to a buffer containing  the  directory  (comma
119              separated)  or  value.   buffer_length returns the length of the
120              value/string in buffer
121
122       Returns
123              number of bytes on success. -1 on error (and errno is set).
124
125       Sequence
126              One of the init functions must be called  before  accessing  the
127              1-wire bus.  OW_finish is optional.
128
129       Important note
130              buffer  is allocated ( with malloc ) by OW_get but must be freed
131              in your program. See malloc (3) and free (3)
132
133   OW_lread
134       OW_lread is used to read 1-wire memory chips. Think of it as a combina‐
135       tion  of lseek and read It allows random-access to the memory, specify‐
136       ing location and length. Unlike OW_get directories cannot  be  obtained
137       and  the buffer must be pre-allocated rather than allocated by the rou‐
138       tine.  buffer must be at least size length.
139
140       Arguments
141              path is the path to the file (property).  buffer is the (pre-al‐
142              located)  memory  area  where the value will be placed.  size is
143              the length of bytes requested.  offset is the position  in  file
144              to start reading.
145
146       Returns
147              number of bytes on success. -1 on error (and errno is set).
148
149       Sequence
150              One  of  the  init functions must be called before accessing the
151              1-wire bus.  OW_finish is optional.
152
153   OW_put
154       OW_put is an easy way to write to 1-wire chips.
155
156       Arguments
157              path is the path to the file (property).  buffer is the value to
158              be  written.   buffer_length  is the length of the value buffer.
159              Returns number of bytes on success. -1 on error  (and  errno  is
160              set).
161
162       Sequence
163              One  of  the  init functions must be called before accessing the
164              1-wire bus.  OW_finish is optional.
165
166   OW_lwrite
167       OW_lwrite is the companion of OW_lread.  It allows writing to arbitrary
168       positions  in 1-wire memory.  Think of it as a combination of lseek and
169       write.  buffer must be at least size length.
170
171       Arguments
172              path is the path to the file (property).  buffer is the data  to
173              be  written.  size is the length of bytes to be written.  offset
174              is the position in file to start writing.
175
176       Returns
177              number of bytes on success. -1 on error (and errno is set).
178
179       Sequence
180              One of the init functions must be called  before  accessing  the
181              1-wire bus.  OW_finish is optional.
182
183   OW_finish
184       OW_finish cleans up the OWFS 1-wire routines, releases devices and mem‐
185       ory.
186
187       Arguments
188              None.
189
190       Returns
191              None
192
193       Sequence
194              OW_finish is optional since  cleanup  is  automatic  on  program
195              exit.
196

DESCRIPTION

198   1-Wire
199       1-wire is a wiring protocol and series of devices designed and manufac‐
200       tured by Dallas Semiconductor, Inc. The bus is  a  low-power  low-speed
201       low-connector scheme where the data line can also provide power.
202
203       Each  device  is  uniquely and unalterably numbered during manufacture.
204       There are a wide variety of devices, including memory, sensors  (humid‐
205       ity, temperature, voltage, contact, current), switches, timers and data
206       loggers. More complex devices (like thermocouple sensors) can be  built
207       with  these  basic devices. There are also 1-wire devices that have en‐
208       cryption included.
209
210       The 1-wire scheme uses a single bus master and multiple slaves  on  the
211       same  wire.  The bus master initiates all communication. The slaves can
212       be individually discovered and addressed using their unique ID.
213
214       Bus masters come in a variety of configurations including serial,  par‐
215       allel, i2c, network or USB adapters.
216
217   OWFS design
218       OWFS  is  a  suite of programs that designed to make the 1-wire bus and
219       its devices easily accessible. The underlying principle is to create  a
220       virtual filesystem, with the unique ID being the directory, and the in‐
221       dividual properties of the device are represented as simple files  that
222       can be read and written.
223
224       Details  of  the  individual slave or master design are hidden behind a
225       consistent interface. The goal is to provide an easy set of tools for a
226       software  designer  to create monitoring or control applications. There
227       are some performance enhancements in the implementation, including data
228       caching, parallel access to bus masters, and aggregation of device com‐
229       munication. Still the fundamental goal has been ease of use,  flexibil‐
230       ity and correctness rather than speed.
231
232   libowcapi
233       libowcapi  (1) is an encapsulation of the full libow library for C pro‐
234       grams.
235
236       libowcapi (1) allows a C program to  use  OWFS  principles  (consistent
237       naming  scheme, multiple adapters, devices, and compatibility) directly
238       from a C program. There are analogous  modules  for  other  programming
239       languages:
240
241       C      libowcapi
242
243       perl   owperl
244
245       php    owphp
246
247       python owpython
248
249       tcl    owtcl
250

EXAMPLE

252       /* Simple directory listing -- no error checking */
253       #include <ownetapi.h>
254       char * buf;
255       size_t s ;
256       OWNET_init("localhost:4304");
257       OWNET_dirlist("/",&buf,&s) ;
258       printf("Directory %s0,buf);
259       free(buf);
260       OWNET_finish() ;
261

AVAILABILITY

318       http://www.owfs.org
319

AUTHOR

321       Paul Alfille (paul.alfille@gmail.com)
322
323
324
325OWFS Manpage                         2008                             OWNET(1)