Oread
Syntax
Oread DQ_Pin, Mode, [ Inputdata ]
Overview
Receive data from a device using the Dallas Semiconductor 1-wire protocol. The 1-wire protocol is a form of asynchronous serial communication developed by Dallas Semiconductor. It requires only one I/O pin which may be shared between multiple 1-wire devices.
Parameters
DQ_Pin is a Port-Bit combination that specifies which I/O pin to use. 1-wire devices require only one I/O pin (normally called DQ) to communicate. This I/O pin will be toggled between output and input mode during the Oread command and will be set to input mode by the end of the Oread command. Mode is a numeric constant (0 - 7) indicating the mode of data transfer. The Mode parameter controls the placement of reset pulses and detection of presence pulses, as well as Byte or Bit input. See notes below. Inputdata is a list of variables or arrays to store the incoming data into.
Example
Device = 24HJ128GP502 ' Select the device to compile for
Declare Xtal = 16
Dim MyResult as Byte
Symbol DQ_Pin = PORTA.0
Oread DQ_Pin, 1, [MyResult]The above example code will transmit a 'reset' pulse to a 1-wire device (connected to bit 0 of PORTA) and will then detect the device's 'presence' pulse and receive one byte and store it in the variable MyResult.
Notes.
The Mode parameter is used to control placement of reset pulses (and detection of presence pulses) and to designate byte or bit input. The table below shows the meaning of each of the 8 possible value combinations for Mode.
Text in this figure or table
Mode Effect Value
| 0 | No Reset, Byte mode |
| 1 | Reset before data, Byte mode |
| 2 | Reset after data, Byte mode |
| 3 | Reset before and after data, Byte mode |
| 4 | No Reset, Bit mode |
| 5 | Reset before data, Bit mode |
| 6 | Reset after data, Bit mode |
| 7 | Reset before and after data, Bit mode |
The correct value for Mode depends on the 1-wire device and the portion of the communication that is being dealt with. Consult the data sheet for the device in question to determine the correct value for Mode. In many cases, however, when using the Oread command, Mode should be set for either No Reset (to receive data from a transaction already started by an Owrite
command) or a Reset after data (to terminate the session after data is received). However, this may vary due to device and application requirements.
When using the Bit (rather than Byte) mode of data transfer, all variables in the InputData argument will only receive one bit. For example, the following code could be used to receive two bits using this mode: -
Dim BitVar1 as Bit
Dim BitVar2 as Bit
Oread PORTA.0, 6, [BitVar1, BitVar2]In the example code shown, a value of 6 was chosen for Mode. This sets Bit transfer and Reset after data mode.
We could also have chosen to make the BitVar1 and BitVar2 variables each a Byte type, however, they would still only have received one bit each in the Oread command, due to the Mode that was chosen.
The compiler also has a modifier for handling a string of data, named Str.
The Str modifier is used for receiving data and placing it directly into a byte array variable.
A string is a set of bytes that are arranged or accessed in a certain order. The values 1, 2, 3 would be stored in a string with the value 1 first, followed by 2 then followed by the value 3. A byte array is a similar concept to a string; it contains data that is arranged in a certain order. Each of the elements in an array is the same size. The string 1 2 3 would be stored in a byte array containing three bytes (elements).
Below is an example that receives ten bytes through a 1-wire interface and stores them in the 10 element byte array, MyArray: -
Dim MyArray[10] as Byte ' Create a 10 element byte array.
Oread DQ_Pin, 1, [Str MyArray]
Print Dec Str MyArray ' Display the values.If the amount of received characters is not enough to fill the entire array, then a formatter may be placed after the array's name, which will only receive characters until the specified length is reached. For example: -
Dim MyArray[10] as Byte ' Create a 10 element byte array.
Oread DQ_Pin, 1, [Str MyArray\5] ' Fill the first 5-bytes of array with data.
Print Str MyArray \5 ' Display the 5-value string.The example above illustrates how to fill only the first n bytes of an array, and then how to display only the first n bytes of the array. n refers to the value placed after the backslash.
Dallas 1-Wire Protocol.
The 1-wire protocol has a well defined standard for transaction sequences. Every transaction sequence consists of four parts: -
Initialisation. ROM Function Command. Memory Function Command. Transaction / Data.
Additionally, the ROM Function Command and Memory Function Command are always 8 bits wide and are sent least-significant-bit first (LSB).
The Initialisation consists of a reset pulse (generated by the master) that is followed by a presence pulse (generated by all slave devices).
The reset pulse is controlled by the lowest two bits of the Mode parameter in the Oread command. It can be made to appear before the ROM Function Command (Mode = 1), after the Transaction / Data portion (Mode = 2), before and after the entire transaction (Mode = 3) or not at all (Mode = 0).
Text in this figure or table
Command Value Action
Reads the 64-bit ID of the 1-wire device. This command can
Read ROM $33
only be used if there is a single 1-wire device on the line. This command, followed by a 64-bit ID, allows the microcon-
Match ROM $55
troller to address a specific 1-wire device. Address a 1-wire device without its 64-bit ID. This command
Skip ROM $CC
can only be used if there is a single 1-wire device on the line. Reads the 64-bit IDs of all the 1-wire devices on the line. A Search
$F0 process of elimination is used to distinguish each unique de-
ROM vice.
Following the Initialisation, comes the ROM Function Command. The ROM Function Command is used to address the desired 1-wire device. The above table shows a few common ROM Function Commands. If only a single 1 wire device is connected, the Match ROM command can be used to address it. If more than one 1-wire device is attached, the microcontroller will ultimately have to address them individually using the Match ROM command.
The third part, the Memory Function Command, allows the microcontroller to address specific memory locations, or features, of the 1-wire device. Refer to the 1-wire device's data sheet for a list of the available Memory Function Commands.
Text in this figure or table
DS1820 +5 Volts 3 VDD 4.7k
| 2 | DS1820 |
| To RA1 | DQ |
1 2 3 1..GND 0v 3..VCC
Finally, the Transaction / Data section is used to read or write
data to the 1-wire device. The Oread command will read data R1
at this point in the transaction. A read is accomplished by generating a brief low-pulse and sampling the line within
| 15us of the falling edge of the pulse. This is called a 'Read | GND | |
| Slot'. | 1 | 2..DQ |
The following program demonstrates interfacing to a Dallas Semiconductor DS1820 1-wire digital thermometer device using the compiler's 1-wire commands, and connections as per the diagram to the right.
The code reads the Counts Remaining and Counts per Degree Centigrade registers within the DS1820 device in order to provide a more accurate temperature (down to 1/10th of a degree).
Device = 24HJ128GP502 ' Select the device to compile for
Declare Xtal = 16
Symbol DQ_Pin = PORTA.1 ' Place the DS1820 on bit-1 of PORTA
Dim wTemperature as Word ' Holds the temperature value
Dim bCounts as Byte ' Holds the counts remaining value
Dim CPerD as Byte ' Holds the Counts per degree C value
Do
Owrite DQ_Pin, 1, [$CC, $44] ' Send the Calculate Temperature command
Repeat
DelayMs 25 ' Wait until conversion is complete
Oread DQ_Pin, 4, [bCounts] ' Keep reading low pulses until
Until bCounts <> 0 ' the DS1820 is finished.
Owrite DQ_Pin, 1, [$CC, $BE] ' Send the Read ScratchPad command
Oread DQ_Pin, 2,[wTemperature.LowByte, wTemperature.HighByte,_
bCounts, bCounts, bCounts, bCounts, bCounts, CPerD]
'
' Calculate the temperature in degrees Centigrade
'
wTemperature=(((wTemperature >> 1)*100) - 25) + (((CPerD - bCounts)*100)/CPerD)
HRsoutLn Dec wTemperature / 100, ".", Dec2 wTemperature, " C"
DelayMs 500
LoopNote. The simple expression used in the code above will not work correctly with negative temperatures. Also note that the 4.7kΩ pull-up resistor (R1) is required for correct operation.
Inline Oread Command.
The standard structure of the Oread command is: -
Oread DQ_Pin, Mode, [ Inputdata ]However, this did not allow it to be used in conditions such as If-Then, While-Wend etc. Therefore, there is now an additional structure to the Oread command: -
MyByte = Oread DQ_Pin, ModeParameters DQ_Pin and Mode have not changed their function, but the result from the 1-wire read is now placed directly into the assignment variable.
See also : Owrite.
