1-Wire Application Interface
This section provides a brief description of the API functions contained in
the 'general' and 'userial' 1-Wire libraries.
Link-Level 1-Wire Net functions:
--------------------------------
owTouchReset - Reset all devices on the 1-Wire Net. Result of function
indicates if any devices were detected
owTouchBit - Send and receive 1 bit from the 1-Wire Net
owTouchByte - Send and receive 8 bits from the 1-Wire Net
owWriteByte - Send 8 bits to the 1-Wire Net and verify the echo received
matches. (constructed from owTouchByte)
owReadByte - Receive 8 bits from the 1-Wire Net by sending all 1's (0xFF)
and letting the slave change the echo.(constructed from owTouchByte)
owSpeed - Set the communication speed of the 1-Wire Net to Normal (16K bits)
or Overdrive (142K bits). All 1-Wire devices at least support the
Normal communication rate.
owLevel - Set the 1-Wire Net line level to Normal (5V weak pull-up), Power
Delivery (5V strong pull-up), or Program Level (12V EPROM programming
level). Power delivery only required by some 1-Wire devices.
Programming level only required to write EPROM based memory 1-Wire
devices.
owProgramPulse - Timed programming pulse for EPROM 1-Wire device writing.
Can be constructed from owLevel. Only required to write EPROM based
memory 1-Wire devices.
owWriteBytePower - Send 8 bits of communication to the 1-Wire Net and
verify that the 8 bits read from the 1-Wire Net is the same (write
operation). The parameter 'sendbyte' least significant 8 bits are used.
After the 8 bits are sent change the level of the 1-Wire net.
owReadBytePower - Reads 8 bits of communication to the 1-Wire Net and after
the 8 bits are read the level of the 1-Wire changes.
owReadBitPower - After 1 bit is read and matches the
applyPowerResponse the power level changes for power delivery.
owHasPowerDelivery - This function indicates whether the adapter can deliver
power. It is just set to be true but may need to be changed for
different adapters.
owHasOverDrive - This function indicates whether the adapter has overdrive
capability. It has been set and may need to be changed for different
adapters.
owHasProgramPulse - This function indicates whether or not voltage is
available.
Network-level 1-Wire Net functions:
-----------------------------------
owFirst - Search to find the 'first' 1-Wire device on the 1-Wire Net.
All 1-Wire Net devices have a unique 64-bit serial number.
The order the devices are found is serial number dependent.
The serial number found can be retrieved after this function using
owSerialNum.
owNext - Search to find the 'next' 1-Wire device on the 1-Wire Net based
on the last search done. The serial number found can be retrieved after
this function using owSerialNum. If owNext returns FALSE then the end
of the search has been found. Calling owNext again will reset the search
and find the 'first' device again.
owSerialNum - Retrieve or set the currently selected device serial number.
owFamilySearchSetup - Setup the following search (owNext) to find a
specific family type. The first 8 bits of the unique serial number
indicate the 'family' that the device belongs to. The 'family' lets the
application know what type of commands the device requires. The
owSerialNum function must be called after the search has been performed
to verify the correct family type was found. If it is not the correct
family type then there are no devices of that type on the 1-Wire Net.
owSkipFamily - Skip all of the family type that was found in the last
search. The next search (owNext) will find a new type or come to the end
of the search.
owAccess - Select the current device by Serial Number. The selection is
done by resetting the 1-Wire Net, sending the 'MATCH ROM' command
followed by the current serial number. At the end of this operation
only the current device is listening on the 1-Wire Net for a device
specific command.
owVerify - Selects and verifies that the current device by Serial Number
is on the 1-Wire Net. This function uses the 'search' command to select
and verify the device is in contact with the Net.
owOverdriveAccess - Select the current device by Serial Number and place it
and the 1-Wire Net into Overdrive communication speed.
Transport-level 1-Wire Net functions:
-------------------------------------
owBlock - Send and receive blocks of data to the 1-Wire Net. A reset is
optionally done on the 1-Wire before the data is sent. This API is more
efficient than sending data with multiple 'owTouchByte' calls.
owRead - Generic read of memory from the device with no CRC checking or
added information passed.
owWrite - Generic write to memory with no CRC writing.
owReadPage - Reads a page in memory with no CRC checking.
owReadPageExtra - Reads a page in memory with extra information and no CRC
checking.
owReadPageExtraCRC - Reads a complete memory page with CRC verification
provided by the device with extra information.
owReadPageCRC - Reads a complete memory page with CRC verification
provided by the device.
owReadPagePacket - Reads a Universal Data Packet from memory.
owReadPagePacketExtra - Reads a Universal Data Packet from memory with
extra information.
owWritePagePacket - Writes a Universal Data Packet to memory.
owGetNumberBanks - Gets the number of banks for a certain iButton
given it's family code.
owGetNumberPages - Gets the number of pages in the given memory bank
for a certain part.
owGetSize - Gets the size of a memory bank in bytes.
owGetPageLength - Gets the raw page length in bytes for a given
memory bank.
owGetStartingAddress - Gets the physical starting address of the
given memory bank.
owGetBankDescription - Gets a string description of the memory
bank.
owGetName - Retrieves the Dallas Semiconductor/Maxim part number
of the 1-Wire device as a string.
owGetAlternateName - Retrieves the alternate Dallas Semiconductor/
Maxim part numbers or names.
owGetDescription - Retrieves a short description of the function
of the 1-Wire device type.
owIsGeneralPurposeMemory - Checks to see if the memory bank is
general purpose user memory.
owIsReadWrite - Checks to see if this memory bank is read/write.
owIsWriteOnce - Checks to see if this memory bank is write once
such as with EPROM technology.
owIsReadOnly - Query to see if current memory bank is read only.
owIsNonvolatile - Query to see if current memory bank non-volatile.
Memory is non-volatile if it retains its contents even when
removed from the 1-Wire network.
owNeedsProgramPulse - Checks to see if this memory bank requires a
'ProgramPulse' in order to write.
owNeedsPowerDelivery - Checks to see if this memory bank requires
'PowerDelivery' in order to write.
owHasExtraInfo - Checks to see if this memory bank's pages deliver
extra information outside of the normal data space, when read.
owGetExtraInfoLength - Gets the length in bytes of extra information
that is read when reading a page in this memory bank.
owGetExtraInfoDesc - Gets a string description of what is contained
in the extra information returned when reading pages in the
given memory bank.
owGetMaxPacketDataLength - Gets maximum data page length in bytes
for a packet read or written in the given memory bank.
owHasPageAutoCRC - Checks to see if the given memory bank's pages
can be read with the contents being verified by a device
generated CRC.
owRedirectPage - Checks to see if the given memory bank has pages
that can be redirected to a new page. This is used in
Write-Once memory to provide a means to update.
owCanLockPage - Checks to see if the given memory bank has pages
that can be locked. A locked page would prevent any changes
to it's contents.
owCanLockRedirectPage - Checks to see if the given memory bank
has pages that can be locked from being redirected. This
would prevent a Write-Once memory from being updated.
owProgramByte - Program a byte to an EPROM based 1-Wire device memory.
(function options may change on future versions of this code)
File-level 1-Wire Net functions:
--------------------------------
owFormat - Formats a touch memory device.
owCreateFile - Creating a file given that it doesn't already exist and
assigns a handle for access.
owCloseFile - Close a file and free up the handle.
owWriteFile - Writes data to a file that is all ready been created.
owCreateDir - Creates a directory or subdirectory in the 1-Wire file
structure.
owRemoveDir - Removes a directory from the 1-Wire file structure.
owDeleteFile - Removes a file from the 1-Wire file structure.
owAttribute - Changes the attributes of a file.
owReNameFile - Changes the name of a given file.
owReadFile - Read the data of a file.
owOpenFile - Finds and returns a handle for accessing a file.
owFirstFile - Finds the first file in the 1-Wire file structure.
owNextFile - Finds the next file in the 1-Wire file structure.
owGetCurrentDir - Gets the current directory that the application is in.
owChangeDirectory - Changes from the current directory to the one specified
as long as it exists.
Note: Not all 1-Wire devices are supported with the above functions. See
'Dallas Semiconductor Application Note 114' for a description of
the 1-Wire file structure. (function options may change on future
versions of this code)
Session-Level 1-Wire Net functions:
-----------------------------------
owAcquire - Attempts to acquire a 1-Wire net
owAcquireEx - Attempts to acquire a 1-Wire net while return port number.
owRelease - Releases the previously acquired a 1-Wire net
General API Code
----------------
The 'general' code set sends commands that rely on the following 1-Wire Net
link-level functions.
The following is a description of the API needed to port this code set to any
platform. See the 'TODO.C' and 'TODOSES.C' files in the directory
'\lib\general'. Required API that must be implemented for the
'general' code set to function:
owTouchReset - Reset all devices on the 1-Wire Net. Result of function
indicates if any devices were detected.
owTouchBit - Send and receive 1 bit from the 1-Wire Net
API that can be generated from the required API:
------------------------------------------------
owTouchByte - Send and receive 8 bits from the 1-Wire Net. This can be
constructed from 8 calls to owTouchBit but it may be for efficient to
create this API.
owWriteByte - Send 8 bits to the 1-Wire Net and verify the echo received
matches.(constructed from owTouchByte)
owReadByte - Receive 8 bits from the 1-Wire Net by sending all 1's (0xFF)
and letting the slave change the echo. (constructed from owTouchByte)
Optional API that may be needed for the platform or for a specific application:
-------------------------------------------------------------------------------
owSpeed - Set the communication speed for the 1-Wire Net to Normal
(16K bits) or Overdrive (142K bits). All 1-Wire devices at least support
the Normal communication rate. This API need only be implemented if
Overdrive communication rate is desired.
owLevel - Set the 1-Wire Net line level to Normal (5V weak pull-up),
Power Delivery (5V strong pull-up), or Program Level (12V EPROM
programming level). Power delivery only required by some 1-Wire devices
such as the DS1820, DS2450, and DS1954. Programming level only required
to write EPROM based memory 1-Wire devices.
owProgramPulse - Timed programming pulse for EPROM 1-Wire device writing.
Can be constructed from owLevel. Only required to write EPROM based
memory 1-Wire devices.
msGettick - Return an increment millisecond counter. This is used in
several of the sample applications.
msDelay - Delay at least the specified number of milliseconds. This is
used in several of the sample applications.
owAcquire - Attempts to acquire a 1-Wire net
owRelease - Releases the previously acquired a 1-Wire net
owWriteBytePower - Send 8 bits of communication to the 1-Wire Net and
verify that the 8 bits read from the 1-Wire Net is the same (write
operation). The parameter 'sendbyte' least significant 8 bits are used.
After the 8 bits are sent change the level of the 1-Wire net.
owHasPowerDelivery - This function indicates whether the adapter can deliver
power. It is just set to be true but may need to be changed for
different adapters.
owHasOverDrive - This function indicates whether the adapter has overdrive
capability. It has been set and may need to be changed for different
adapters.
owHasProgramPulse - This function indicates whether or not voltage is
available.
