owshell(1)

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

NAME

6       owdir,   owread,  owwrite,  owget,  owexist,  owpresent  -  lightweight
7       owserver access
8

SYNOPSIS

10   Minimal options
11       owdir -s [host:]port [directory]
12       owread -s [host:]port filepath
13       owwrite -s [host:]port filepath value
14       owget -s [host:]port [directory] | filepath
15
16   Server discovery
17       owdir --autoserver [directory]
18       owread --autoserver filepath
19       owwrite --autoserver filepath value
20       owget --autoserver [directory] | filepath
21
22   Full options
23       owdir -q --quiet -f --format f[.]i[[.]c] ] [  --dir  ]  -s  [host:]port
24       [directory] [directory2 ...]
25
26       owread -q --quiet -C --celsius -K --kelvin -F --fahrenheit -R --rankine
27       [ --hex ] [ --start= offset ] [ --size= bytes ] -s [host:]port filepath
28       [filepath2 ...]
29
30       owwrite  -q --quiet -C --celsius -K --kelvin -F --fahrenheit -R --rank‐
31       ine [ --hex ]  [  --start=  offset  ]  -s  [host:]port  filepath  value
32       [filepath2 value2 ...]
33
34       owget  -q  --quiet  -f --format f[.]i[[.]c] -C --celsius -K --kelvin -F
35       --fahrenheit -R --rankine [ --hex ] [ --start= offset ] [ --size= bytes
36       ] [ --dir ] -s [host:]port [directory] | filepath
37
38   Version
39       owdir -V --version
40       owread -V --version
41       owwrite -V --version
42       owget -V --version
43
44   Help
45       owdir -h | --help
46       owread -h | --help
47       owwrite -h | --help
48       owget -h | --help
49

DESCRIPTION

51   1-Wire
52       1-wire is a wiring protocol and series of devices designed and manufac‐
53       tured by Dallas Semiconductor, Inc. The bus is  a  low-power  low-speed
54       low-connector scheme where the data line can also provide power.
55
56       Each  device  is  uniquely and unalterably numbered during manufacture.
57       There are a wide variety of devices, including memory, sensors  (humid‐
58       ity, temperature, voltage, contact, current), switches, timers and data
59       loggers. More complex devices (like thermocouple sensors) can be  built
60       with  these  basic  devices.  There  are  also 1-wire devices that have
61       encryption included.
62
63       The 1-wire scheme uses a single bus master and multiple slaves  on  the
64       same  wire.  The bus master initiates all communication. The slaves can
65       be individually discovered and addressed using their unique ID.
66
67       Bus masters come in a variety of configurations including serial,  par‐
68       allel, i2c, network or USB adapters.
69
70   OWFS design
71       OWFS  is  a  suite of programs that designed to make the 1-wire bus and
72       its devices easily accessible. The underlying principle is to create  a
73       virtual  filesystem,  with  the  unique ID being the directory, and the
74       individual properties of the device are  represented  as  simple  files
75       that can be read and written.
76
77       Details  of  the  individual slave or master design are hidden behind a
78       consistent interface. The goal is to provide an easy set of tools for a
79       software  designer  to create monitoring or control applications. There
80       are some performance enhancements in the implementation, including data
81       caching, parallel access to bus masters, and aggregation of device com‐
82       munication. Still the fundemental goal has been ease of use,  flexibil‐
83       ity and correctness rather than speed.
84
85   OWSHELL programs
86       owdir owread owwrite and owget are collectively called the owshell pro‐
87       grams. They allow lightweight access to an owserver (1) for use in com‐
88       mand line scripts.
89
90       Unlike  owserver  (1)  owhttpd  (1) owftpd (1) owhttpd (1) there is not
91       persistent connection with the 1-wire bus, no  caching  and  no  multi‐
92       threading. Instead, each program connects to a running owserver (1) and
93       performs a quick set of queries.
94
95       owserver (1) performs the actual 1-wire connection (to physical  1-wire
96       busses  or  other  owserver  programs),  performs  concurrency locking,
97       caching, and error collection.
98
99       owshell programs are intended for  use  in  command  line  scripts.  An
100       alternative  approach  is  to  mount an owfs (1) filesystem and perform
101       direct file lists, reads and writes.
102
103   owdir
104       owdir performs a directory listing. With no argument, all  the  devices
105       on  the  main  1-wire  bus  will  be listed. Given the name of a 1-wire
106       device, the available properties will be listed. It is  the  equivalent
107       of
108
109              ls directory
110
111       in the owfs (1) filesystem.
112
113   owread
114       owread   obtains   for   value   of  a  1-wire  device  property.  e.g.
115       28.0080BE21AA00/temperature gives the DS18B20 temperature.  It  is  the
116       equivalent of
117
118              cat filepath
119
120       in the owfs (1) filesystem.
121
122   owwrite
123       owwrite  performs a change of a property, changing a 1-wire device set‐
124       ting or writing to memory. It is the equivalent of
125
126              echo value > filepath
127
128       in the owfs (1) filesystem.
129
130   owget
131       owget (1) is a convenience program, combining the function of owdir (1)
132       and owread (1) by first trying to read the argument as a directory, and
133       if that fails as a 1-wire property.
134

STANDARD OPTIONS

136   --autoserver
137       Find an owserver using  the  Service  Discovery  protocol.  Essentially
138       Apple's  Bonjour  (aka zeroconf). Only the first owserver will be used,
139       and that choice is probably arbitrary.
140
141   -s [host:]port
142       Connect via tcp (network) to an owserver process that is connected to a
143       physical  1-wire  bus. This allows multiple processes to share the same
144       bus. The owserver process can be local or remote.
145
146       If the server option is not specified, the default is the local machine
147       and  the  IANA allocated default port of 4304. Thus "-s localhost:4304"
148       is the equivalent.
149

DATA OPTIONS

--hex

152       Hexidecimal mode. For reading data, each byte of character will be dis‐
153       played  as  two  characrters  0-9ABCDEF. Most useful for reading memory
154       locations. No spaces between data.
155
156       Writing data in hexidecimal mode just means that  the  data  should  be
157       given as one long hexidecimal string.
158

--start=offset

160       Read  or write memory locations starting at the offset byte rather than
161       the beginning. An offset of 0 means the beginning (and is the default).
162

--size=bytes

164       Read up to the specified number of bytes of a memory location.
165

HELP OPTIONS

167   -h --help
168       Shows (this) basic summary of options.
169
170   -V --version
171       Version of this program.
172

DISPLAY OPTIONS

174   --dir
175       Modify the display of directories to indicate which  entries  are  also
176       directories.  A  directory  member  will have a trailing '/' if it is a
177       directory itself. This aids recursive searches.
178
179   -f --format f[.]i[[.]c]
180       Display format for the  1-wire  devices.  Each  device  has  a  8  byte
181       address, consisting of:
182
183       f      family code, 1 byte
184
185       i      ID number, 6 bytes
186
187       c      CRC checksum, 1 byte
188
189       Possible  formats are f.i (default, 01.A1B2C3D4E5F6), fi fic f.ic f.i.c
190       and fi.c
191
192       All formats are accepted as input, but the output will be in the speci‐
193       fied format.
194

EXAMPLE

196       owdir -s 3000 --format fic
197              Get  the  device  listing (full 16 hex digits, no dots) from the
198              local owserver at port 3000
199
200       owread -F --autoserver 51.125499A32000/typeK/temperature
201              Read temperature from the DS2751-based thermocouple on an  auto-
202              discovered owserver Temperature in fahrenheit.
203
204       owwrite -s 10.0.1.2:3001 32.000800AD23110/pages/page.1 "Passed"
205              Connect  to  a OWFS server process ( owserver ) that was started
206              on another machine at tcp port 3001 and write to the memory of a
207              DS2780
208

AVAILABILITY

265       http://www.owfs.org
266

AUTHOR

268       Paul Alfille (paul.alfille@gmail.com)
269
270
271
272OWSHELL Manpage                      2004                           OWSHELL(1)