owcapi(1)

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

NAME

6       owcapi - easy C-language 1-wire interface
7

SYNOPSIS

9       libowcapi library to link with your program
10
11   Initialization
12       ssize_t OW_init( device name or full parameter string )
13       ssize_t OW_init_args( int argc, char ** args )
14
15       The  full  set  of initialization options is extensive. They correspond
16       roughly to the command line options of owfs (1) owhttpd (1) and  owftpd
17       [1m(1)
18
19   Get data
20       int OW_present( const char * path )
21       int OW_get( const char * path, char ** buffer, size_t * buffer_length )
22       ssize_t  OW_lread(  const  char  *  path, unsigned char * buffer, const
23       size_t size, const off_t offset )
24
25   Set data
26       ssize_t OW_put( const char * path, const char * buffer, size_t  *  buf‐
27       fer_length )
28       ssize_t  OW_lwrite(  const  char  * path, const unsigned char * buffer,
29       const size_t size, const off_t offset )
30
31   Debug
32       void OW_set_error_level( const char *param )
33       void OW_set_error_print( const char *param )
34
35   Close
36       void OW_finish( void )
37

FUNCTIONS

39   OW_init
40       OW_init_string offers the full flexibility of the owfs (1) and  owhttpd
41       [1m(1) command line.
42
43       Arguments
44              Can be as simple as jus the device name, a full parameter speci‐
45              fication.  One or  more  device  names  (includes  tcp,  serial,
46              usb...) and command line switches. See owfs (1) for full syntax.
47
48       Returns
49              0  for  success.  -1  on error and errno will be set.  OW_finish
50              does not need to be called if OW_init fails.
51
52       Sequence
53              One of the init functions must be called  before  accessing  the
54              1-wire bus.  OW_finish is optional.
55
56   OW_init_args
57       OW_init_args  offers  the  full flexibility of the owfs (1) and owhttpd
58       [1m(1) command line.
59
60       Arguments
61              One or more device names (includes tcp, serial, usb...) and com‐
62              mand  line  switches.  See  owfs  (1)  for  full  syntax. Unlike
63              OW_init_string the arguments are in argv/argc format.
64
65       Returns
66              0 for success. -1 on error and errno  will  be  set.   OW_finish
67              does not need to be called if OW_init fails.
68
69       Sequence
70              One  of  the  init functions must be called before accessing the
71              1-wire bus.  OW_finish is optional.
72
73   OW_present
74       OW_present is used to check presence of a 1-wire device.
75
76       Arguments
77              path is the path to the directory or file (property).
78
79       Returns
80              0 on success. -1 on error (and errno is set).
81
82       Sequence
83              One of the init functions must be called  before  accessing  the
84              1-wire bus.  OW_finish is optional.
85
86   OW_get
87       OW_get is used to get directory listings and file contents. The results
88       are put in a dynamically allocated buffer.
89
90       Arguments
91              path is the path to the directory or file  (property).   *buffer
92              returns  a  pointer  to a buffer containing the directory (comma
93              separated) or value.  buffer_length returns the  length  of  the
94              value/string in buffer
95
96       Returns
97              number of bytes on success. -1 on error (and errno is set).
98
99       Sequence
100              One  of  the  init functions must be called before accessing the
101              1-wire bus.  OW_finish is optional.
102
103       Important note
104              buffer is allocated ( with malloc ) by OW_get but must be  freed
105              in your program. See malloc (3) and free (3)
106
107   OW_lread
108       OW_lread is used to read 1-wire memory chips. Think of it as a combina‐
109       tion of lseek and read It allows random-access to the memory,  specify‐
110       ing  location  and length. Unlike OW_get directories cannot be obtained
111       and the buffer must be pre-allocated rather than allocated by the  rou‐
112       tine.  buffer must be at least size length.
113
114       Arguments
115              path  is  the  path to the file (property).  buffer is the (pre-
116              allocated) memory area where the value will be placed.  size  is
117              the  length  of bytes requested.  offset is the position in file
118              to start reading.
119
120       Returns
121              number of bytes on success. -1 on error (and errno is set).
122
123       Sequence
124              One of the init functions must be called  before  accessing  the
125              1-wire bus.  OW_finish is optional.
126
127   OW_put
128       OW_put is an easy way to write to 1-wire chips.
129
130       Arguments
131              path is the path to the file (property).  buffer is the value to
132              be written.  buffer_length is the length of  the  value  buffer.
133              Returns  number  of  bytes on success. -1 on error (and errno is
134              set).
135
136       Sequence
137              One of the init functions must be called  before  accessing  the
138              1-wire bus.  OW_finish is optional.
139
140   OW_lwrite
141       OW_lwrite is the companion of OW_lread.  It allows writing to arbitrary
142       positions in 1-wire memory.  Think of it as a combination of lseek  and
143       write.  buffer must be at least size length.
144
145       Arguments
146              path  is the path to the file (property).  buffer is the data to
147              be written.  size is the length of bytes to be written.   offset
148              is the position in file to start writing.
149
150       Returns
151              number of bytes on success. -1 on error (and errno is set).
152
153       Sequence
154              One  of  the  init functions must be called before accessing the
155              1-wire bus.  OW_finish is optional.
156
157   OW_set_error_level
158       OW_set_error_level sets the debug output  to  a  certain  level.  0  is
159       default, and higher value gives more output.
160       (0=default,   1=err_connect,   2=err_call,   3=err_data,  4=err_detail,
161       5=err_debug, 6=err_beyond)
162
163       Arguments
164              params is the level. Should be an integer.
165
166       Returns
167              None
168
169       Sequence
170              One of the init functions must  be  called  before  setting  the
171              level, since init defaults to level 0.
172
173   OW_set_error_print
174       OW_set_error_print  sets  where  the  debug  output should be directed.
175       0=mixed output, 1=syslog, 2=console.
176
177       Arguments
178              params is the level. Should be an integer between 0 and 2.
179
180       Returns
181              None
182
183       Sequence
184              One of the init functions must  be  called  before  setting  the
185              level, since init defaults to 0 (mixed output).
186
187   OW_finish
188       OW_finish cleans up the OWFS 1-wire routines, releases devices and mem‐
189       ory.
190
191       Arguments
192              None.
193
194       Returns
195              None
196
197       Sequence
198              OW_finish is optional since  cleanup  is  automatic  on  program
199              exit.
200

DESCRIPTION

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

EXAMPLE

256       /* Simple directory listing -- no error checking */
257       #include <owcapi.h>
258       unsigned char * buf;
259       size_t s ;
260       OW_init("/dev/ttyS0");
261       OW_set_error_print("2");
262       OW_set_error_level("6");
263       OW_get("/",&buf,&s) ;
264       printf("Directory %s0,buf);
265       free(buf);
266       OW_finish() ;
267

AVAILABILITY

324       http://www.owfs.org
325

AUTHOR

327       Paul Alfille (paul.alfille@gmail.com)
328
329
330
331OWFS Manpage                         2004                            OWCAPI(1)