White Paper 5: Using 1-Wire AP
abstract: all 1-wire® device data sheets describe two sets of commands. the first set referred to as rom function commands are used for device identification and selection. the second set is often called memory function commands but may contain other non-memory operations. a rom function command must be completed each time a device is selected to get it ready for a memory function command. the 1-wire apis created by dallas semiconductor utilize these commands to do operations with 1-wire devices. sometimes it is not always obvious what commands are being called. this document will map the commands presented in the data sheets to the api functions. where specific api functions are not available, a technique will be presented to translate the commands using the generic communications api functions.
introduction all 1-wire device data sheets describe two sets of commands. the first set referred to as rom function commands are used for device identification and selection. the second set is often called memory function commands but may contain other non-memory operations. a rom function command must be completed each time a device is selected to get it ready for a memory function command. the 1-wire apis created by dallas semiconductor utilize these commands to do operations with 1-wire devices. sometimes it is not always obvious what commands are being called. this document will map the commands presented in the data sheets to the api functions. where specific api functions are not available, a technique will be presented to translate the commands using the generic communications api functions.
see application note 155 for a detailed description of the various apis including the abbreviations discussed in this document (pd, tmex, owapi, owcom). (special terms, commands, or codes are shown in italics for clarity.) rom function commands the rom function commands are used to either discover the rom id or use the rom id to select a device in various modes. the rom id is a unique 64-bit number that contains a family code, serialization field, and a cyclic redundancy check (crc). the 1-wire master transmits one of these functions after it has issued a 1-wire reset and received a presence.
the read rom command reads the rom id directly. it can only be used on a 1-wire network where there is only one device attached. with networks of more than one device, the rom id must be discovered with the search rom command. this search algorithm is discussed in detail in application note 187. the conditional search rom command works the same as search rom except only 1-wire devices that are in some kind of alarm state will respond. this is used to discover only devices that need attention.
the skip rom command is used to select all devices regardless of its rom id. this could be used to gang program memory devices provided there is sufficient energy. the overdrive skip command is similar but it not only selects all devices it also puts those devices at the overdrive communication rate. this is most often used to move all capable 1-wire devices to overdrive speed. after the devices are communicating in overdrive, the rom ids can be discovered using the conventional search rom sequence.
the match rom command selects a specific device by broadcasting a selected rom id. the overdrive match is similar but it also switches the device to the overdrive communication speed. the resume command is used to reselect the last device that was selected. this is a shortcut command when repeatedly accessing the same device.
table 1 maps the apis to a particular rom function command. note that since the various 1-wire apis are designed with the idea of multiple 1-wire devices on a network, the commands that require or are most useful in a single device network are not supported directly. however any command can be constructed using the basic communication functions as will be discussed later in custom commands.
table 1. rom function commands command pd tmex
read rom no predefined api, see custom commands. no predefined api, see custom commands.
match rom owaccess tmaccess
search rom owfirst, ownext tomfirst, tmnext
conditional search rom owfirst, ownext tmfirstalarm, tmnextalarm
skip rom no predefined api, see custom commands. no predefined api, see custom commands.
overdrive skip* no predefined api, see custom commands. no predefined api, see custom commands.
overdrive match owoverdriveaccess tmoveraccess
resume command** no predefined api, see custom commands. no predefined api, see custom commands.
command owapi owcom
read rom no predefined api, see custom commands. no predefined api, see custom commands.
match rom (package com.dalsemi.onewire.adapter)
dsportadapter.select dsportadapter.select
search rom (package com.dalsemi.onewire.adapter)
dsportadapter.getfirstdevicecontainer,
dsportadapter.getnextdevicecontainer dsportadapter.getfirstdevicecontainer,
dsportadapter.getnextdevicecontainer
conditional search rom (package com.dalsemi.onewire.adapter)
dsportadapter.setsearchonlyalarmingdevices
(then same as search rom) dsportadapter.setsearchonlyalarmingdevices
(then same as search rom)
skip rom no predefined api, see custom commands. no predefined api, see custom commands.
overdrive skip* no predefined api, see custom commands. no predefined api, see custom commands.
overdrive match* (package com.dalsemi.onewire.container)
onewirecontainer.setspeed
onewirecontainer.dospeed onewirecontainer.setspeed
onewirecontainer.dospeed
resume command** no predefined api, see custom commands. no predefined api, see custom commands.
*note: only applies to 1-wire devices that support overdrive communication speed.
**note: only applies to 1-wire devices that support the resume command. memory function commands the memory function commands vary slightly from one device type to another. however their primary objective is the same, which is to read and write the memory areas of the device. to deal with these diverse command structures, the 1-wire apis were constructed to abstract out these differences. for example, a generic write memory api may use a write scratchpad, read scratchpad, and copy scatchpad sequence or it may use an eprom write memory sequence. to the api user, it looks the same.
there are three levels of memory commands in most of the apis. the first allows reading and writing to the memory without any structure (raw). the second uses a packet structure called the universal data packet (udp). the third type combines multiple udp structures into a file structure. see application note 114 for a description of the udp and file structure. table 2 maps the apis to the three types of memory operations.
table 2. abstract memory functions command pd tmex
write raw owwrite tmprogramblock (eprom only) (see custom commands)
read raw owread tmprogramblock (eprom only) (see custom commands)
write udp owwritepagepacket tmwritepacket
read udp owreadpagepacket tmreadpacket
write file owcreatefile
owwritefile tmcreatefile
tmwritefile
read file owopenfile
owreadfile tmopenfile
tmreadfile
command owapi owcom
write raw (package com.dalsemi.onewire.container)
memorybank.write memorybank.write
read raw memorybank.read memorybank.read
write udp (package com.dalsemi.onewire.container)
pagedmemorybank.writepagepacket pagedmemorybank.writepagepacket
read udp (package com.dalsemi.onewire.container)
pagedmemorybank.readpagepacket pagedmemorybank.readpagepacket
write file (package com.dalsemi.onewire.application.file)
owfileoutputstream.write owfileoutputstream.write
read file (package com.dalsemi.onewire.application.file)
owfileinputstream.read owfileinputstream.read
some of the commands that are included under memory function commands in data sheets are actually custom device commands. see the following section for a guide on how to deal with these commands. custom commands almost all of the custom commands can be derived by first selecting the device with a match rom equivalent api and then send a bidirectional block of data to the 1-wire network. the block is constructed by putting in the write commands that are required into the block and putting in ff (hex) bytes into the block that are reads from the 1-wire device. for example, the ds1994 has a memory-mapped real-time clock (rtc) register that can be accessed with the read memory command. figure 1 below is taken from the ds1994's data sheet.
the ds1994 is no longer recommended for new designs.
figure 1. ds1994 read memory flow (data sheet).
as the ds1994 data sheet specifies, the rtc register is five bytes long starting at address 0202(hex). the memory command flow as seen in figure 1 starts after the device has been selected with a rom function command like match rom.
table 3 below lists the eight bytes that make up a block of bidirectional data to be sent to the 1-wire bus based on the flow chart. while this data could be sent a byte at a time, it is often more efficient to create a block and sent it all at once.
table 3. read rtc block block offset byte value (hex) description
0 f0 master tx read memory command
1 02 master tx ta1 (address, least significant byte, t7:t0)
2 02 master tx ta2 (address, most significant byte, t15:t8)
3 ff master rx byte 0 of rtc (address 0202h)
4 ff master rx byte 1 of rtc (address 0203h)
5 ff master rx byte 2 of rtc (address 0204h)
6 ff master rx byte 3 of rtc (address 0205h)
7 ff master rx byte 4 of rtc (address 0206h)
figure 2 is a 'c' example written for the 1-wire public domain (pd) api that uses the block outlined in table 3 to read the rtc of the ds1994.
figure 2. pd example reading rtc unsigned char datablock[] = { 0xf0,0x02,0x02,0xff,0xff,0xff,0xff,0xff }; int portnum=0; // select the current device (match rom) if (owaccess(portnum)) { // send the read memory command and address, receive the rtc value if (owblock(portnum, 1, datablock, 8)) { // rtc is now in bytes 3-7 of datablock ... } } table 4 shows the bidirectional block commands for each of the apis. for completeness, the single byte and bit commands are also included.
table 4. generic 1-wire io functions command pd tmex
block (bidirectional) owblock tmblockstream
byte (bidirectional) owtouchbyte tmtouchbyte
bit (bidirectional) owtouchbit tmtouchbit
read byte owreadbyte tmtouchbyte(data = ff hex)
write byte owwritebyte tmtouchbyte(data to write)
reset owtouchreset tmtouchreset
command owapi owcom
block (bidirectional) (package com.dalsemi.onewire.adapter)
dsportadapter.datablock dsportadapter.datablock
byte (bidirectional) (package com.dalsemi.onewire.adapter)
dsportadapter.datablock
(single byte block) dsportadapter.databock
(single byte block)
bit (bidirectional) not available not available
read byte (package com.dalsemi.onewire.adapter)
dsportadapter.getbyte dsportadapter.getbyte
write byte (package com.dalsemi.onewire.adapter)
dsportadapter.putbyte dsportadapter.putbyte
1-wire reset + presence detect (package com.dalsemi.onewire.adapter)
dsportadapter.reset dsportadapter.reset
by looking at the data sheet for each 1-wire device type, it is possible to do any of the functions by constructing the appropriate block and using the generic 1-wire io functions. some of the 1-wire devices require special power delivery constraints or program pulses that are addressed by the special api functions in table 5.
table 5. special 1-wire power functions command pd tmex
eprom programming pulse owprogrampulse tmprogrampulse
power delivery
(strong pullup) after bit owreadbitpower (read bit only) tmonewirelevel (prime for next bit)
tmtouchbit
power delivery
(strong pullup) after byte owwritebytepower (write byte only) tmonewirelevel (prime for next byte)
tmtouchbyte
command owapi owcom
eprom programming pulse (package com.dalsemi.onewire.adapter)
dsportadapter.startprogrampulse dsportadapter.startprogrampulse
power delivery
(strong pullup) after bit (package com.dalsemi.onewire.adapter)
dsportadapter.startpowerdelivery
(prime for next bit)
dsportadapter.putbit /
dsportadapter.getbit dsportadapter.startpowerdelivery
(prime for next bit)
dsportadapter.putbit /
dsportadapter.getbit
power delivery
(strong pullup) after byte (package com.dalsemi.onewire.adapter)
dsportadapter.startpowerdelivery
(prime for next byte)
dsportadapter.putbyte /
dsportadapter.getbyte dsportadapter.startpowerdelivery
(prime for next byte)
dsportadapter.putbyte /
dsportadapter.getbyte
1-wire is a registered trademark of maxim integrated products, inc.
关于嵌入式技术的一些基础知识
出门问问TicWatchS2怎么样 更可以成为户外运动爱好者的选择
1安等于多少毫安 锂电池如何检测容量是否达标
倍加福推出带IO-Link接口的双张超声波传感器
iPhone8什么时候发布？iPhone8杀死Home键，iPhone8钢化膜不再有圆孔了！
White Paper 5: Using 1-Wire AP
受新品影响多款锐龙Threadripper2900系列处理器价格大幅降价
第二期物联网产融精准对接交流会，在腾讯会议直播平台上召开
苹果欲将iPad生产择址印度
华为荣耀准备在2019年第四季度推出5G手机
连涨三周！年轻人为何爱选海尔智家Leader冰箱？
家电智能化的背后暗藏隐私泄露危机
3D渲染技术如何加速智能驾驶舱创新，促进智能趋势的发展
炎武科技,FMK24-L,24GHz无人机准毫米波雷达高度计,24GHz无人机准毫米波避障雷达,飞控雷达,无人机安全测距和防碰撞,飞行器水面定高
BeingLab举办智联跨界先行者论坛 聚焦AI
安全威胁或将是5G未来发展的最大新挑战
在PAD中添加表面型测试点
基于STR710处理器实现嵌入式以太网接口的应用方案
AOS | 超低反向工作电压 TVS二极管
浙江省计划2022年突破氢能产业总产值规模百亿元大关
introduction all 1-wire device data sheets describe two sets of commands. the first set referred to as rom function commands are used for device identification and selection. the second set is often called memory function commands but may contain other non-memory operations. a rom function command must be completed each time a device is selected to get it ready for a memory function command. the 1-wire apis created by dallas semiconductor utilize these commands to do operations with 1-wire devices. sometimes it is not always obvious what commands are being called. this document will map the commands presented in the data sheets to the api functions. where specific api functions are not available, a technique will be presented to translate the commands using the generic communications api functions.
see application note 155 for a detailed description of the various apis including the abbreviations discussed in this document (pd, tmex, owapi, owcom). (special terms, commands, or codes are shown in italics for clarity.) rom function commands the rom function commands are used to either discover the rom id or use the rom id to select a device in various modes. the rom id is a unique 64-bit number that contains a family code, serialization field, and a cyclic redundancy check (crc). the 1-wire master transmits one of these functions after it has issued a 1-wire reset and received a presence.
the read rom command reads the rom id directly. it can only be used on a 1-wire network where there is only one device attached. with networks of more than one device, the rom id must be discovered with the search rom command. this search algorithm is discussed in detail in application note 187. the conditional search rom command works the same as search rom except only 1-wire devices that are in some kind of alarm state will respond. this is used to discover only devices that need attention.
the skip rom command is used to select all devices regardless of its rom id. this could be used to gang program memory devices provided there is sufficient energy. the overdrive skip command is similar but it not only selects all devices it also puts those devices at the overdrive communication rate. this is most often used to move all capable 1-wire devices to overdrive speed. after the devices are communicating in overdrive, the rom ids can be discovered using the conventional search rom sequence.
the match rom command selects a specific device by broadcasting a selected rom id. the overdrive match is similar but it also switches the device to the overdrive communication speed. the resume command is used to reselect the last device that was selected. this is a shortcut command when repeatedly accessing the same device.
table 1 maps the apis to a particular rom function command. note that since the various 1-wire apis are designed with the idea of multiple 1-wire devices on a network, the commands that require or are most useful in a single device network are not supported directly. however any command can be constructed using the basic communication functions as will be discussed later in custom commands.
table 1. rom function commands command pd tmex
read rom no predefined api, see custom commands. no predefined api, see custom commands.
match rom owaccess tmaccess
search rom owfirst, ownext tomfirst, tmnext
conditional search rom owfirst, ownext tmfirstalarm, tmnextalarm
skip rom no predefined api, see custom commands. no predefined api, see custom commands.
overdrive skip* no predefined api, see custom commands. no predefined api, see custom commands.
overdrive match owoverdriveaccess tmoveraccess
resume command** no predefined api, see custom commands. no predefined api, see custom commands.
command owapi owcom
read rom no predefined api, see custom commands. no predefined api, see custom commands.
match rom (package com.dalsemi.onewire.adapter)
dsportadapter.select dsportadapter.select
search rom (package com.dalsemi.onewire.adapter)
dsportadapter.getfirstdevicecontainer,
dsportadapter.getnextdevicecontainer dsportadapter.getfirstdevicecontainer,
dsportadapter.getnextdevicecontainer
conditional search rom (package com.dalsemi.onewire.adapter)
dsportadapter.setsearchonlyalarmingdevices
(then same as search rom) dsportadapter.setsearchonlyalarmingdevices
(then same as search rom)
skip rom no predefined api, see custom commands. no predefined api, see custom commands.
overdrive skip* no predefined api, see custom commands. no predefined api, see custom commands.
overdrive match* (package com.dalsemi.onewire.container)
onewirecontainer.setspeed
onewirecontainer.dospeed onewirecontainer.setspeed
onewirecontainer.dospeed
resume command** no predefined api, see custom commands. no predefined api, see custom commands.
*note: only applies to 1-wire devices that support overdrive communication speed.
**note: only applies to 1-wire devices that support the resume command. memory function commands the memory function commands vary slightly from one device type to another. however their primary objective is the same, which is to read and write the memory areas of the device. to deal with these diverse command structures, the 1-wire apis were constructed to abstract out these differences. for example, a generic write memory api may use a write scratchpad, read scratchpad, and copy scatchpad sequence or it may use an eprom write memory sequence. to the api user, it looks the same.
there are three levels of memory commands in most of the apis. the first allows reading and writing to the memory without any structure (raw). the second uses a packet structure called the universal data packet (udp). the third type combines multiple udp structures into a file structure. see application note 114 for a description of the udp and file structure. table 2 maps the apis to the three types of memory operations.
table 2. abstract memory functions command pd tmex
write raw owwrite tmprogramblock (eprom only) (see custom commands)
read raw owread tmprogramblock (eprom only) (see custom commands)
write udp owwritepagepacket tmwritepacket
read udp owreadpagepacket tmreadpacket
write file owcreatefile
owwritefile tmcreatefile
tmwritefile
read file owopenfile
owreadfile tmopenfile
tmreadfile
command owapi owcom
write raw (package com.dalsemi.onewire.container)
memorybank.write memorybank.write
read raw memorybank.read memorybank.read
write udp (package com.dalsemi.onewire.container)
pagedmemorybank.writepagepacket pagedmemorybank.writepagepacket
read udp (package com.dalsemi.onewire.container)
pagedmemorybank.readpagepacket pagedmemorybank.readpagepacket
write file (package com.dalsemi.onewire.application.file)
owfileoutputstream.write owfileoutputstream.write
read file (package com.dalsemi.onewire.application.file)
owfileinputstream.read owfileinputstream.read
some of the commands that are included under memory function commands in data sheets are actually custom device commands. see the following section for a guide on how to deal with these commands. custom commands almost all of the custom commands can be derived by first selecting the device with a match rom equivalent api and then send a bidirectional block of data to the 1-wire network. the block is constructed by putting in the write commands that are required into the block and putting in ff (hex) bytes into the block that are reads from the 1-wire device. for example, the ds1994 has a memory-mapped real-time clock (rtc) register that can be accessed with the read memory command. figure 1 below is taken from the ds1994's data sheet.
the ds1994 is no longer recommended for new designs.
figure 1. ds1994 read memory flow (data sheet).
as the ds1994 data sheet specifies, the rtc register is five bytes long starting at address 0202(hex). the memory command flow as seen in figure 1 starts after the device has been selected with a rom function command like match rom.
table 3 below lists the eight bytes that make up a block of bidirectional data to be sent to the 1-wire bus based on the flow chart. while this data could be sent a byte at a time, it is often more efficient to create a block and sent it all at once.
table 3. read rtc block block offset byte value (hex) description
0 f0 master tx read memory command
1 02 master tx ta1 (address, least significant byte, t7:t0)
2 02 master tx ta2 (address, most significant byte, t15:t8)
3 ff master rx byte 0 of rtc (address 0202h)
4 ff master rx byte 1 of rtc (address 0203h)
5 ff master rx byte 2 of rtc (address 0204h)
6 ff master rx byte 3 of rtc (address 0205h)
7 ff master rx byte 4 of rtc (address 0206h)
figure 2 is a 'c' example written for the 1-wire public domain (pd) api that uses the block outlined in table 3 to read the rtc of the ds1994.
figure 2. pd example reading rtc unsigned char datablock[] = { 0xf0,0x02,0x02,0xff,0xff,0xff,0xff,0xff }; int portnum=0; // select the current device (match rom) if (owaccess(portnum)) { // send the read memory command and address, receive the rtc value if (owblock(portnum, 1, datablock, 8)) { // rtc is now in bytes 3-7 of datablock ... } } table 4 shows the bidirectional block commands for each of the apis. for completeness, the single byte and bit commands are also included.
table 4. generic 1-wire io functions command pd tmex
block (bidirectional) owblock tmblockstream
byte (bidirectional) owtouchbyte tmtouchbyte
bit (bidirectional) owtouchbit tmtouchbit
read byte owreadbyte tmtouchbyte(data = ff hex)
write byte owwritebyte tmtouchbyte(data to write)
reset owtouchreset tmtouchreset
command owapi owcom
block (bidirectional) (package com.dalsemi.onewire.adapter)
dsportadapter.datablock dsportadapter.datablock
byte (bidirectional) (package com.dalsemi.onewire.adapter)
dsportadapter.datablock
(single byte block) dsportadapter.databock
(single byte block)
bit (bidirectional) not available not available
read byte (package com.dalsemi.onewire.adapter)
dsportadapter.getbyte dsportadapter.getbyte
write byte (package com.dalsemi.onewire.adapter)
dsportadapter.putbyte dsportadapter.putbyte
1-wire reset + presence detect (package com.dalsemi.onewire.adapter)
dsportadapter.reset dsportadapter.reset
by looking at the data sheet for each 1-wire device type, it is possible to do any of the functions by constructing the appropriate block and using the generic 1-wire io functions. some of the 1-wire devices require special power delivery constraints or program pulses that are addressed by the special api functions in table 5.
table 5. special 1-wire power functions command pd tmex
eprom programming pulse owprogrampulse tmprogrampulse
power delivery
(strong pullup) after bit owreadbitpower (read bit only) tmonewirelevel (prime for next bit)
tmtouchbit
power delivery
(strong pullup) after byte owwritebytepower (write byte only) tmonewirelevel (prime for next byte)
tmtouchbyte
command owapi owcom
eprom programming pulse (package com.dalsemi.onewire.adapter)
dsportadapter.startprogrampulse dsportadapter.startprogrampulse
power delivery
(strong pullup) after bit (package com.dalsemi.onewire.adapter)
dsportadapter.startpowerdelivery
(prime for next bit)
dsportadapter.putbit /
dsportadapter.getbit dsportadapter.startpowerdelivery
(prime for next bit)
dsportadapter.putbit /
dsportadapter.getbit
power delivery
(strong pullup) after byte (package com.dalsemi.onewire.adapter)
dsportadapter.startpowerdelivery
(prime for next byte)
dsportadapter.putbyte /
dsportadapter.getbyte dsportadapter.startpowerdelivery
(prime for next byte)
dsportadapter.putbyte /
dsportadapter.getbyte
1-wire is a registered trademark of maxim integrated products, inc.
关于嵌入式技术的一些基础知识
出门问问TicWatchS2怎么样 更可以成为户外运动爱好者的选择
1安等于多少毫安 锂电池如何检测容量是否达标
倍加福推出带IO-Link接口的双张超声波传感器
iPhone8什么时候发布？iPhone8杀死Home键，iPhone8钢化膜不再有圆孔了！
White Paper 5: Using 1-Wire AP
受新品影响多款锐龙Threadripper2900系列处理器价格大幅降价
第二期物联网产融精准对接交流会，在腾讯会议直播平台上召开
苹果欲将iPad生产择址印度
华为荣耀准备在2019年第四季度推出5G手机
连涨三周！年轻人为何爱选海尔智家Leader冰箱？
家电智能化的背后暗藏隐私泄露危机
3D渲染技术如何加速智能驾驶舱创新，促进智能趋势的发展
炎武科技,FMK24-L,24GHz无人机准毫米波雷达高度计,24GHz无人机准毫米波避障雷达,飞控雷达,无人机安全测距和防碰撞,飞行器水面定高
BeingLab举办智联跨界先行者论坛 聚焦AI
安全威胁或将是5G未来发展的最大新挑战
在PAD中添加表面型测试点
基于STR710处理器实现嵌入式以太网接口的应用方案
AOS | 超低反向工作电压 TVS二极管
浙江省计划2022年突破氢能产业总产值规模百亿元大关