1线主设备配置-1-Wire Master Device C

abstract: the 'family-code' embedded in the lasered rom number of each 1-wire device signifies a specific device type. since each device type has different features and commands, it is imperative the 1-wire master knows how to translate this 'family-code' into the correct commands. this document presents a method to dynamically configure the 1-wire master to correctly communicate with a previously unknown 1-wire device type by providing the 1-wire master with an xml configuration file. this document was originally created to support the ieee 1451.4 a smart transducer interface for sensors and actuators—mixed-mode communication protocols and transducer electronic data sheet (teds) formats standards committee.
introductionthe 'family-code' embedded in the lasered rom number of each 1-wire device signifies a specific device type. since each device type has different features and commands, it is imperative the 1-wire® master knows how to translate this 'family-code' into the correct commands. unfortunately, since the 'family-code' is only an 8-bit value it is impossible to encode all of the features and commands in it. instead the 1-wire master must make this association by different means. one method is to hardcode this association in the source code of the 1-wire master. it can then be updated by rewriting the source code to accommodate new devices. this method is expensive and in some cases impossible thus relegating some 1-wire masters to only deal with legacy devices.
this document presents a method to dynamically configure the 1-wire master to correctly communicate with a previously unknown 1-wire device type by providing the 1-wire master with a configuration file. the 1-wire master could be updated with the latest 1-wire devices by providing a new configuration file. this document describes the format of one such configuration file utilizing xml. this document was originally created to support the ieee 1451.4 a smart transducer interface for sensors and actuators - mixed-mode communication protocols and transducer electronic data sheet (teds) formats standards committee.
the appendix proposes a method where a generic family code (for example fd hex) could be differentiated by means of a read-only configuration memory page on the device. no devices currently implement this method.
command notationit is assumed that each 1-wire master must come with the ability to search for 1-wire devices and read the unique rom number associated with each device. from the rom number the 8-bit 'family-code' can be extracted. the 1-wire master will then perform 1-wire operations as defined by this configuration file based on the 'family-code'. by examining all 1-wire device operations, a minimum set of commands was derived. the commands are described in table 1 along with a suggested notation. table 2 describes additional commands that add verification to the command sequences.
table 1. core 1-wire commands notation command description
xx send the following hex byte value to the 1-wire bus. if this hex byte is within a crc block then calculate the crc on the result of the 1-wire operation (see verification commands).
{l, delay} delay for 'l' milliseconds
{m} select the device with a 1-wire reset, match rom command, and device rom
{p} prime 1-wire power delievery (strong pull-up) or to occur after the next 1-wire byte
{n} restore normal pull-up
{u} issued a 12-volt pulse (used in eprom programming)
{ax} supply a memory address where 'x' is a number 0,1,...representing the lsbyte to msbyte. for example '{a0}{a1}' would specify a 16-bit address with the least significant byte first followed by the most significant byte.
{dx} data to write to a memory device where the 'x' is a number 0,1,...representing the lsbyte to msbyte of the data. for example '{d0} {d1} {d2}' is three bytes of data to write. note the master processing these commands would place the actual data into the command flow.
{r} read memory bytes to end of memory. all values read are valid data however now verification is performed.
table 2. verification commands notation command description
{dx} data to read. this data can be for verification of data written to a memory 1-wire device or result data such as a temperature conversion. note it is in same format as the {dx} command where 'x' is a number indicating the byte number with {d0} being the lsbyte.
{t} success is reading toggling bits such as 0xaa or 0x55.
{00} success is reading all 0's such as 0x00
{ff} success is reading all 1's such as 0xff
{crc16,start,seed} start crc16 calculation by first setting the crc16 to the provided 'seed' represented in hex notation. all following command bytes will be included in the calculation until the 'check' command is found.
{crc16,check,value} check the crc16 calculated value to make sure it equals the provided hex 'value'. if it is not then this is a failure. the crc16 calculation can be stopped after the check.
{crc8,start,seed} start crc8 calculation by first setting the crc8 to the provided 'seed' represented in hex notation. all following command bytes will be included in the calculation until the 'check' command is found.
{crc16,check,value} check the crc8 calculated value to make sure it equals the provided hex 'value'. if it is not then this is a failure. the crc8 calculation can be stopped after the check.
see figure 1 to see an example command sequence to read the scratchpad of the ds18b20.
figure 1. ds18b20 read temperature command sequence and 1-wire master translation.
device typesthe general types of 1-wire devices covered by this document are memory, switch, and temperature.
the memory device has some kind of data storage memory area. it may be write-once but must support multiple reads. it is often arranged in pages and is usually written a page at a time. a memory device may have multiple banks of memory with different attributes.
the switch device can control a latch. the latch may connect the output to ground (lowside) or to the communication channel (highside). some switch devices can also sense voltage. a switch device can have multiple channels.
the temperature device returns a temperature value in celsius. the result is a signed value representing temperature units. the unit conversion to celsius is provided.
each device type contains one or more standard operations. for example each temperature device has a 'read' operation. table 3 shows the standard operations and attributes of each device type.
table 3. device operations and attributes by type device type operations attributes
memory read
write read/write/readonly/writeonce
starting physical address
number of pages
page length in bytes
switch read latch
enable latch
disable latch
read level (optional) highside/lowside
temperature read min temperature
max temperature
step (unit of celsius returned from read)
the 'setup' operation is also included in any of the device type descriptions. a 'setup' is a command sequence that readies the device for operation. for any of the 'read' operation there are also two attributes 'andmask' and 'polarity'. the 'andmask' is a hex value that is bitwise anded with the result data described in the command sequence with {d0}. the 'polarity' indicates that the operation is 'true' if it matches the resulting value from the 'andmask'. for example when reading the latch state (read latch) of a ds2406 channel a, the andmask=0x01 and polarity=0x00. so the value read from the command sequence is bitwise anded with 0x01 and if the result is 0, the latch is on.
configuration formatthe xml syntax was selected for the example configuration file format. since xml is so 'extensible' it was easy to incorporate the device types, operations, attributes and the actual command sequences into a human readable format. the overall 'tag' for grouping these descriptions was . within this group are individual device descriptions with a specified family code attribute, for example: . each device group can contain , , or groups that correspond to the device types already described. note that some devices may have more then one channel and group. for example the ds2406 has both memory and switch groups since it incorporates both of these features. see the figure 2 in the appendix for an example xml file describing six different 1-wire devices. two of these devices are memory, two are switches, and two are temperature devices.
examples ds2433, 4kbit eeprom main memory 0x0000 16 32 {m} {crc16,start,0} 0f {a0} {a1} {d0} {d1} {d2} {d3} {d4} {d5} {d6} {d7} {d8} {d9} {d10} {d11} {d12} {d13} {d14} {d15} {d16} {d17} {d18} {d19} {d20} {d21} {d22} {d23} {d24} {d25} {d26} {d27} {d28} {d29} {d30} {d31} ff ff {crc16,check,0xb001} {m} 55 {a0} {a1} {p} 1f {l,10} {n} {t} {m} f0 {a0} {a1} {r} ds2430a, 32-byte eeprom with locking register main memory 0x0000 1 32 {m} 0f {a0} {d0} {d1} {d2} {d3} {d4} {d5} {d6} {d7} {d8} {d9} {d10} {d11} {d12} {d13} {d14} {d15} {d16} {d17} {d18} {d19} {d20} {d21} {d22} {d23} {d24} {d25} {d26} {d27} {d28} {d29} {d30} {d31} {m} aa {a0} {d0} {d1} {d2} {d3} {d4} {d5} {d6} {d7} {d8} {d9} {d10} {d11} {d12} {d13} {d14} {d15} {d16} {d17} {d18} {d19} {d20} {d21} {d22} {d23} {d24} {d25} {d26} {d27} {d28} {d29} {d30} {d31} {m} 55 {p} a5 {l,20} {n} {m} f0 {a0} {r} application register 0x0000 1 8 {m} 99 {a0} {d0} {d1} {d2} {d3} {d4} {d5} {d6} {d7} {m} c3 {a0} {d0} {d1} {d2} {d3} {d4} {d5} {d6} {d7} {m} 5a {p} a5 {l,20} {n} {m} c3 {a0} {r} ds2406, dual channel switch with 1kbit eprom main memory 0x0000 4 32 {m} {crc16,start,0} 0f {a0} {a1} {d0} ff ff {crc16,check,0xb001} {u} {d0} {m} f0 {a0} {a1} {r} pio-a {m} {crc16,start,0} f5 55 ff {d0} ff ff {crc16,check,0xb001} {m} {crc16,start,0} f5 55 ff {d0} ff ff {crc16,check,0xb001} {m} {crc16,start,0} f5 05 ff 00 ff ff {crc16,check,0xb001} {m} {crc16,start,0} f5 05 ff ff ff ff {crc16,check,0xb001} pio-b {m} {crc16,start,0} f5 55 ff {d0} ff ff {crc16,check,0xb001} {m} {crc16,start,0} f5 55 ff {d0} ff ff {crc16,check,0xb001} {m} {crc16,start,0} f5 09 ff 00 ff ff {crc16,check,0xb001} {m} {crc16,start,0} f5 09 ff ff ff ff {crc16,check,0xb001} ds2409, 1-wire coupler main {m} 5a 18 {d0} {m} 5a 18 {d0} {m} 5a 18 {d0} {m} a5 ff {m} 66 ff auxilary {m} 5a 18 {d0} {m} 5a 18 {d0} {m} 33 ff ff ff {m} 66 ff ds18s20/ds1920, fixed resolution temperature {m} b8 {m} {p} 44 {l,750} {n} {ff} {m} be {crc8,start,0} {d0} {d1} ff ff ff ff ff ff ff {crc8,check,0x00} ds18b20, high-resolution temperature {m} 00 00 7f {m} {p} 48 {l,10} {n} {m} b8 {m} {p} 44 {l,750} {n} {ff} {m} be {crc8,start,0} {d0} {d1} ff ff ff ff ff ff ff {crc8,check,0x00} figure 2. example xml configuration file for six 1-wire devices
xml device description schema
the device description schema provides a template to add support for new devices to their systems. the schema defines devices that support memory, switching, and temperature reading.
figure 2. xml device description schema.
appendix memory configuration pagethe following general memory description describes an idealized memory device with a configuration page that provides all of the necessary information to utilize the remaining memory space. the configuration page could provide the device type differentiation that is currently implemented with the rom family code but with more information conveyed. a common generic family code (for example fd hex) could be used for all devices with this configuration page.
all 1-wire memory devices support the read memory command (f0 hex), and with the exception of the ds2430a, it requires 2 address bytes. for this example the read memory command will be used to retrieve the configuration page information at a fixed address of ff7f hex. the memory location will have a length byte, 26 bytes of data followed by an inverted crc16 for validation. table a1 provides the bit-level details of the configuration page format.
table a1. configuration page format byte offset name content
0 length length of data in the configuration page (fixed at 26) 1 general_flags bit 0 memory type (1 eeprom, 0 eeprom)
bit 1 scratchpad erased on read-memory (1 yes, 0 no)
bit 2 device has read page with crc16 (1 yes, 0 no)
bit 3 device has write-once mode like pseudo eprom (1 yes, 0 no) (eeprom only)
bit 4 device has map of used pages (1 yes, 0 no)
bit 5 not used 0
bit 6 not used 0
bit 7 not used 0
2 writeprot_flags bit 0 individual page write-protect (1 yes, 0 no)
bit 1 global device write-protect (1 yes, 0 no)
bit 2 write protect register is organized with one page per bit (1 yes, 0 no). if not then one page per byte
bit 3 not used 0
bit 4 not used 0
bit 5 not used 0
bit 6 not used 0
bit 7 not used 0
3 crc_flags bit 0 write scratchpad has crc16 (1 yes, 0 no)
bit 1 read scratchpad has crc16 (1 yes, 0 no)
bit 2 read special memory command has crc16 (1 yes, 0 no)
bit 3 not used 0
bit 4 not used 0
bit 5 not used 0
bit 6 not used 0
bit 7 not used 0
4 scratchpad_length length of scratchpad in bytes (eeprom only)
5 page_length length of normal memory page in bytes
6 pages number of pages (2 bytes)
8 special_pages number of special function pages
9 special_page_length length of special memory page in bytes
10 readscratch_cmd read scratchpaf command
11 write_cmd write command (scratchpad for eeprom)
12 copyscratch_cmd copy scratchpad command
13 readpagecrc_cmc read page of memory with crc16 command
14 readspecial_cmd read special memory page command
15 write_special_cmd write special memory command
16 writeprot_addr address of write-protect registers in special memory. (2 bytes)
18 writeprotdev_addr address of write-protect entire device register in special memory. (2 bytes)
20 writeonce_addr address to write-once mode (pseudo eprom) flag in special memory. (2 bytes)
22 usedpgs_addr address in special memory for map of used pages. (2 bytes)
24 usedpgs_offset bit offset of the map of used pages
25 writeprot_value value written to special memory register to write-protect a page.
26 writeonce_value value written to special memory register to make a page write-once like pseudo eprom.
27 crc16 bitwise inverted crc16 of bytes 0 to 24, lsbyte first. (2 bytes)
the following table lists the operations that will be described by the configuration page.
table a2. operations operation eeprom eprom description
read memory x x read memory with device generated crc
read page with crc x x read a page of memory with device generated crc
write scratchpad x write the scratchpad in preparation of writing ot memory
read scratchpad x read the scratchpad to verify the write was correct
copy scratchpad x copy the scratchpad to the final memory location
write memory x write a byte to memory
read speical page with crc x read a page of special memory with device generated crc
write special byte x write a byte to the special memory
write protect page x x write protect a page
set page for write-once x set an eeprom page to be write-once like (pseudo eprom)
calculate free pages x calculate the number of free pages in an eprom device by looking at the map of used pages.
x supported by all devices of this type
x supported by some devices of this type
generally not supported by devices of this type
operations detailthe operations detail listed in table a2 can be implemented with the details provided by the configuration page. this section provides the sequence and data fields to use to implement the operations.
read memory
- 1-wire reset and presence
- rom level command sequence (read/search/match/overdrive match/overdrive skip)
- write readmemory command (f0 hex)
- write first address byte ta1, lsbyte
- write second address byte ta2, msbyte
- read data
read page with crc
- if general_flags.bit2 = 1 - 1-wire reset and presence
- rom level command sequence (read/search/match/overdrive match/overdrive skip)
- write readpagecrc_cmd - write first address byte ta1, lsbyte
- write second address byte ta2, msbyte
- read page_length bytes (unless address is not at page beginning)
- read bitwise inverted crc16
write scratchpad
- if general_flags.bit0 = 1 - 1-wire reset and presence
- rom level command sequence (read/search/match/overdrive match/overdrive skip)
- write write_cmd - write first address byte ta1, lsbyte
- write second address byte ta2, msbyte
- write data bytes
- if crcflags.bit0 = 1 and at end of page
- read bitwise inverted crc16
read scratchpad
- if general_flags.bit0 = 1 - 1-wire reset and presence
- rom level command sequence (read/search/match/overdrive match/overdrive skip)
- write readscratch_cmd - read first address byte ta1, lsbyte
- read second address byte ta2, msbyte
- read offest and status flags es
- read data bytes
- if crcflags.bit1 = 1 and at end of page
- read bitwise inverted crc16
copy scratchpad
- if general_flags.bit0 = 1 - 1-wire reset and presence
- rom level command sequence (read/search/match/overdrive match/overdrive skip)
- write copyscratch_cmd
- write first address byte ta1, lsbyte
- write second address byte ta2, msbyte
- write offset and status flags es
- strong pullup applied to 1-wire for a minimum of 10ms
- read confirmation byte (should be aa or 55)
write memory
- if general_flags.bit0 = 0 - 1-wire reset and presence
- rom level command sequence (read/search/match/overdrive match/overdrive skip)
- write write_cmd - write first address byte ta1, lsbyte
- write second address byte ta2, msbyte
- write data byte to write
- read bitwise inverted crc16 of command, address, and data (first pass) or address and data (second pass)
- apply 480 µs 12v programming pulse on the 1-wire
- read confirmation data byte (should or of old data and current data bytes)
- if next address to write is sequential then can send the next data byte...
read special page with crc
- if general_flags.bit2 = 1 - 1-wire reset and presence
- rom level command sequence (read/search/match/overdrive match/overdrive skip)
- write readspecial_cmd - read first address byte ta1, lsbyte
- read second address byte ta2, msbyte
- read special_page_length bytes (unless address is not at page beginning)
- read bitwise inverted crc16
write special byte
- if general_flags.bit0 = 0 - 1-wire reset and presence
- rom level command sequence (read/search/match/overdrive match/overdrive skip)
- write write_special_cmd - write first address byte ta1, lsbyte
- write second address byte ta2, msbyte
- write data byte to write
- read bitwise inverted crc16 of command, address, and data (first pass) or address and data (second pass).
apply 480 µs 12v programming pulse on the 1-wire
- read confirmation data byte (should or of old data and current data bytes)
- if next address to write is sequential then can send the next data byte...
write protect page
- if writeprot_flags.bit0 = 1 - if writeprot_flags.bit2 = 1
- address = writeprot_addr + page / 8
- data = writeprot_value rotate left remainder (page / 8) - else
- address = writeprot_addr + page
- data = writeprot_value
- write special byte with address and data.
set page for write-once
- if general_flags.bit3 = 1 - address = writeonce_addr
- data = writeonce_value
- write special byte with address and data
mark page used
- if general_flags.bit4 = 1 - address = usedpgs_addr + (page + usedpgs_offset) / 8
- data = bitinverse (1 rotate left remainder ((page + usedpgs_offest) / 8)
- write special byte at address and data
calculate free pages
- if general_flags.bit4 = 1 - address = usedpgs_addr
- read special page with crc starting at address until (special_pages / 8) number of bytes read
- count the number of 1's in the bytes read, this is the number of free pages
table a3 provides example configuration pages using existing devices as a template. note however, these devices do not currently contain the configuration page.
table a3. example configuration pages
the ds2409 and ds2430a are no longer recommended for new designs.