DS1991(3)

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

NAME

6       DS1991 - 1152bit MultiKey iButton
7

SYNOPSIS

9       Non-volatile memory with password protection.
10
11       02  [.]XXXXXXXXXXXX[XX][/[  subkey0/reset.  hex_pwd | subkey0/password.
12       hex_pwd | subkey0/secure_data.  hex_pwd | subkey0/id.  hex_pwd
13
14       02 [.]XXXXXXXXXXXX[XX][/[ subkey1/reset.  hex_pwd  |  subkey1/password.
15       hex_pwd | subkey1/secure_data.  hex_pwd | subkey1/id.  hex_pwd
16
17       02  [.]XXXXXXXXXXXX[XX][/[  subkey0/reset.  hex_pwd | subkey2/password.
18       hex_pwd | subkey2/secure_data.  hex_pwd | subkey2/id.  hex_pwd  address
19       | crc8 | id | locator | r_address | r_id | r_locator | type ]]
20

FAMILY CODE

22       02
23

SPECIAL PROPERTIES

25   subkey[0|1|2]/reset.hex_pwd
26       write-only, yes-no
27       Initialize one of the three secure data areas and set a new password.
28
29       The extension (hex_pwd) is the new 8-byte password in hexadecimal (e.g.
30       password.000204006080A0C0E for bytes 0,2,4,6,8,10,12,14)
31
32       The data must be "1" or "yes" to actually reset the subkey.
33
34       Note: writing a password will clear any existing data and ID.
35
36   subkey[0|1|2]/password.hex_pwd
37       write-only, binary
38       Change the password of one of the secure subkey  areas  without  losing
39       data.
40
41       The  extension (hex_pwd) is the existing 8-byte password in hexadecimal
42       (e.g. password.00020406080A0C0E for bytes 0,2,4,6,8,10,12,14)
43
44       The data portion is 8 bytes that will be used as a new password.
45
46   subkey[0|1|2]/secure_data.hex_pwd
47       read-write, binary
48       Read or write data in one of the three sucure data areas.
49
50       The extension (hex_pwd) is the existing 8-byte password in  hexadecimal
51       (e.g. password.00020406080A0C0E for bytes 0,2,4,6,8,10,12,14)
52
53       The  data  portion  binary  data.  Up  to 48 bytes in each subkey area,
54       starting at location 0. If the wrong  password  is  specified,  "random
55       data" is returned on read and data is silently ignored on write.
56
57   subkey[0|1|2]/id.hex_pwd
58       read-write, binary
59       Read or write the subkey id.
60
61       The  extension (hex_pwd) is the existing 8-byte password in hexadecimal
62       (e.g. password.00020406080A0C0E for bytes 0,2,4,6,8,10,12,14)
63
64       The data portion 8 binary bytes. This is the subkey  id.   The  correct
65       password must be used to write a new id but not to read it.
66

STANDARD PROPERTIES

68   address
69   r_address
70       read-only, ascii
71       The  entire  64-bit  unique  ID. Given as upper case hexidecimal digits
72       (0-9A-F).
73       address starts with the family code
74       r address is the address in reverse order, which is often used in other
75       applications and labeling.
76
77   crc8
78       read-only, ascii
79       The  8-bit error correction portion. Uses cyclic redundancy check. Com‐
80       puted from the preceding 56 bits of the  unique  ID  number.  Given  as
81       upper case hexadecimal digits (0-9A-F).
82
83   family
84       read-only, ascii
85       The  8-bit  family  code. Unique to each type of device. Given as upper
86       case hexadecimal digits (0-9A-F).
87
88   id
89   r_id
90       read-only, ascii
91       The 48-bit middle portion of the unique ID number. Does not include the
92       family code or CRC. Given as upper case hexadecimal digits (0-9A-F).
93       r  id is the id in reverse order, which is often used in other applica‐
94       tions and labeling.
95
96   locator
97   r_locator
98       read-only, ascii
99       Uses an extension of the 1-wire design from  iButtonLink  company  that
100       associated  1-wire  physical  connections with a unique 1-wire code. If
101       the connection is behind a Link Locator the locator will show a  unique
102       8-byte number (16 character hexadecimal) starting with family code FE.
103       If  no  Link  Locator is between the device and the master, the locator
104       field will be all FF.
105       r locator is the locator in reverse order.
106
107   present (DEPRECATED)
108       read-only, yes-no
109       Is the device currently present on the 1-wire bus?
110
111   type
112       read-only, ascii
113       Part name assigned by Dallas Semi. E.g.  DS2401  Alternative  packaging
114       (iButton vs chip) will not be distiguished.
115

ALARMS

117       None.
118

DESCRIPTION

120   1-Wire
121       1-wire is a wiring protocol and series of devices designed and manufac‐
122       tured by Dallas Semiconductor, Inc. The bus is  a  low-power  low-speed
123       low-connector scheme where the data line can also provide power.
124
125       Each  device  is  uniquely and unalterably numbered during manufacture.
126       There are a wide variety of devices, including memory, sensors  (humid‐
127       ity, temperature, voltage, contact, current), switches, timers and data
128       loggers. More complex devices (like thermocouple sensors) can be  built
129       with  these  basic  devices.  There  are  also 1-wire devices that have
130       encryption included.
131
132       The 1-wire scheme uses a single bus master and multiple slaves  on  the
133       same  wire.  The bus master initiates all communication. The slaves can
134       be individually discovered and addressed using their unique ID.
135
136       Bus masters come in a variety of configurations including serial,  par‐
137       allel, i2c, network or USB adapters.
138
139   OWFS design
140       OWFS  is  a  suite of programs that designed to make the 1-wire bus and
141       its devices easily accessible. The underlying principle is to create  a
142       virtual  filesystem,  with  the  unique ID being the directory, and the
143       individual properties of the device are  represented  as  simple  files
144       that can be read and written.
145
146       Details  of  the  individual slave or master design are hidden behind a
147       consistent interface. The goal is to provide an easy set of tools for a
148       software  designer  to create monitoring or control applications. There
149       are some performance enhancements in the implementation, including data
150       caching, parallel access to bus masters, and aggregation of device com‐
151       munication. Still the fundamental goal has been ease of use,  flexibil‐
152       ity and correctness rather than speed.
153
154   DS1991
155       The  DS1991 (3) is an iButton with password protected non-volatile mem‐
156       ory. Data is read/written  with  error  checking  (transparent  to  the
157       user).  The  memory  is  divided into 3 different pages with 3 separate
158       passwords.
159
160       In theory, choosing an incorrect password is hard  to  discern  because
161       the  chip  responds  normally  but with incorrect data. There is a pub‐
162       lished analysis suggesting that the "random data" follows a pattern and
163       so a concerted attack might be successful.
164
165       The   password   (in   hexadecimal)   is  used  a  the  file  extension
166       02.1234123414/subkey0/id.  password allowing a password to be passed to
167       the program within the filesystem paradigm.
168

ADDRESSING

170       All  1-wire  devices are factory assigned a unique 64-bit address. This
171       address is of the form:
172
173       Family Code
174              8 bits
175
176       Address
177              48 bits
178
179       CRC    8 bits
180
181       Addressing under OWFS is in hexadecimal, of form:
182
183              01.123456789ABC
184
185       where 01 is an example 8-bit family code, and 12345678ABC is an example
186       48 bit address.
187
188       The  dot  is  optional,  and the CRC code can included. If included, it
189       must be correct.
190

DATASHEET

192       http://pdfserv.maxim-ic.com/en/ds/DS1991.pdf
193

AVAILABILITY

255       http://www.owfs.org
256

AUTHOR

258       Christian Magnusson (mag@mag.cx) and Paul Alfille
259
260
261
262OWFS Manpage                         2003                            DS1991(3)