# OWIN

OWIN / OWOUT Example

Syntax: OWIN Pin, Mode, [InputData]

## Function

Receive data from a device using the Maxim/Dallas Semiconductor 1-Wire®protocol.

- Pin is a variable/constant/expression (0 - 15) that specifies which I/O pin to use. 1-Wire devices require only one I/O pin (called DQ) to communicate. This I/O pin will be toggled between output and input mode during the OWIN command and will be set to input mode by the end of the OWIN command.
- Mode is a variable/constant/expression (0 - 15) indicating the mode of data transfer. The Mode argument controls placement of reset pulses (and detection of presence pulses) as well as byte vs. bit input and normal vs. high speed. See explanation below.
- InputData is a list of variables and modifiers that tells OWIN what to do with incoming data. OWIN can store data in a variable or array, interpret numeric text (decimal, binary, or hex) and store the corresponding value in a variable, wait for a fixed or variable sequence of bytes, or ignore a specified number of bytes. These actions can be combined in any order in the InputData list.

## Quick Facts

| BS2p, BS2pe, and BS2px
Receive Rate | Approximately 20 kBits/sec (low speed, not including reset pulse)
Special Notes | The DQ pin (specified by Pin) must have a 4.7 kΩ pull-up resist0r.
Related Commands | OWOUT

## Explanation

The 1-Wire protocol is a form of asynchronous serial communication developed by Maxim/Dallas Semiconductor. It only requires one I/O pin and that pin can be shared between multiple 1-Wire devices. The OWIN command allows the BASIC Stamp to receive data from a 1-Wire device.

The following is an example of the OWIN command:

    result  VAR     Byte

    Main:
      OWIN 0, 1, [result]
      STOP

This code will transmit a "reset" pulse to a 1-Wire device (connected to I/O pin 0) and then will detect the device's "presence" pulse and then receive one byte and store it in the variable result.

The Mode argument is used to control placement of reset pulses (and detection of presence pulses) and to designate byte vs. bit input and normal vs. high speed†. The tables below show the meaning of each of the four bits of Mode and some of the 16 possible values and their effect.

### Mode Format bits

Bit | Function
0 | Front-End Reset • 0 = No reset • 1 = Generate reset before data
1 | Back-End Reset • 0 = No reset • 1 = Generate reset after data
2 | Bit / Byte Transfer • 0 = Byte • 1 = Bit
3 | Low / High Speed† • 0 = Low • 1 = High

Mode | Effect
0 | No Reset, Byte mode, Low speed
1 | Reset before data, Byte mode, Low speed
2 | Reset after data, Byte mode, Low speed
3 | Reset before and after data, Byte mode, Low speed
4 | No Reset, Bit mode, Low speed
5 | Reset before data, Bit mode, Low speed
6 | Reset after data, Bit mode, Low speed
7 | Reset before and after data, Bit mode, Low speed
8 | No Reset, Byte mode, High speed†
9 | Reset before data, Byte mode, High speed†

† The BS2pe is not capable of High-Speed transfers.

The proper value for Mode depends on the 1-Wire device and the portion of the communication you're working on. Please consult the data sheet for the device in question to determine the correct value for Mode. In many cases, however, when using the OWIN command, Mode should be set for either No Reset (to receive data from a transaction already started by a OWOUTcommand) or a Back-End Reset (to terminate the session after data is received). This may vary due to device and application requirements, however.

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:

    bitOne  VAR     Bit
    bitTwo  VAR     Bit

    Main:
      OWIN 0, 6, [bitOne, bitTwo]
      STOP

In the code above, we chose the value "6" for Mode. This sets Bit transfer and Back-End Reset modes. Also, we could have chosen to make the bitOne and bitTwo variables each a byte in size, but they still would only have received one bit each in the OWIN command (due to the Mode selected).

The OWIN command's InputData argument is similar to the SERINcommand's InputData argument. This means data can be received as ASCII character values, decimal, hexadecimal and binary translations and string data as in the examples below. (Assume a 1-Wire device is used and that it transmits the string, "Value: 3A:101" every time it receives a Front-End Reset pulse).

    value   VAR     Byte(13)

    Main:
      OWIN 0, 1, [value]                    ' receive ASCII code for "V"
      OWIN 0, 1, [DEC value]                ' receive the number 3
      OWIN 0, 1, [HEX value]                ' receive the number $3A
      OWIN 0, 1, [BIN value]                ' receive the number %101
      OWIN 0, 1, [STR value\13]             ' receive the string "Value: 3A:101"
      STOP

The tables below list all the available special formatters and conversion formatters available to the OWIN command. See the SERIN command for additional information and examples of their use.

Special Formatter | Action
STR ByteArray \L {\E} | Input a character string of length L into an array. If specified, an end character E causes the string input to end before reaching length L. Remaining bytes are filled with 0s (zeros).
WAITSTR ByteArray {\L} | Wait for a sequence of bytes matching a string stored in an array variable, optionally limited to L characters. If the optional L argument is left off, the end of the array-string must be marked by a byte containing a zero (0).
SKIP Length | Ignore Length bytes of characters.
SPSTR Length | Buffer Length bytes (up to 126) of serial characters to Scratchpad RAM, starting at location 0. Use GET to retrieve the characters.

Conversion Formatter | Type of Number | Numeric Characters Accepted | Notes
DEC{1..5} | Decimal, optionally limited to 1 - 5 digits | 0 through 9 | 1
SDEC{1..5} | Signed decimal, optionally limited to 1 - 5 digits | -, 0 through 9 | 1,2
HEX{1..4} | Hexadecimal, optionally limited to 1 - 4 digits | 0 through 9, A through F | 1,3
SHEX{1..4} | Signed hexadecimal, optionally limited to 1 - 4 digits | -, 0 through 9, A through F | 1,2,3
IHEX{1..4} | Indicated hexadecimal, optionally limited to 1 - 4 digits | $, 0 through 9, A through F | 1,3,4
ISHEX{1..4} | Signed, indicated hexadecimal, optionally limited to 1 - 4 digits | -, $, 0 through 9, A through F | 1,2,3,4
BIN{1..16} | Binary, optionally limited to 1 - 16 digits | 0, 1 | 1
SBIN{1..16} | Signed binary, optionally limited to 1 - 16 digits | -, 0, 1 | 1,2
IBIN{1..16} | Indicated binary, optionally limited to 1 - 16 digits | %, 0, 1 | 1,4
ISBIN{1..16} | Signed, indicated binary, optionally limited to 1 - 16 digits | -, %, 0, 1 | 1,2,4
NUM | Generic numeric input; hex or binary number must be indicated | $, %, 0 through 9, A through F | 1,3,4
SNUM | Similar to NUM with value treated as signed with range -32768 to +32767 | -, $, %, 0 through 9, A through F | 1,2,3,4

1. All numeric conversions will continue to accept new data until receiving either the specified number of digits (ex: three digits for DEC3) or a non-numeric character.
2. To be recognized as part of a number, the minus sign (-) must immediately precede a numeric character. The minus sign character occurring in non-numeric text is ignored and any character (including a space) between a minus and a number causes the minus to be ignored.
3. The hexadecimal formatters are not case-sensitive; "a" through "f" means the same as "A" through "F".
4. Indicated hexadecimal and binary formatters ignore all characters, even valid numerics, until they receive the appropriate prefix ($ for hexadecimal, % for binary). The indicated formatters can differentiate between text and hexadecimal (ex: ABC would be interpreted by HEX as a number but IHEX would ignore it unless expressed as $ABC). Likewise, the binary version can distinguish the decimal number 10 from the binary number %10. A prefix occurring in non-numeric text is ignored, and any character (including a space) between a prefix and a number causes the prefix to be ignored. Indicated, signed formatters require that the minus sign come before the prefix, as in -$1B45.

### The 1-Wire Protocol Format

The 1-Wire protocol has a well-defined standard for transaction sequences. Every transaction sequence consists of four parts: 1) Initialization, 2) ROM Function Command, 3) Memory Function Command, and 4) Transaction/Data. Additionally, the ROM Function Command and Memory Function Command are always 8 bits wide (1 byte in size) and is sent least-significant-bit (LSB) first.

The Initialization part consists of a reset pulse (generated by the master) and will be followed by a presence pulse (generated by all slave devices). The figure below details the reset pulse generated by the BASIC Stamp and a typical presence pulse generated by a 1-Wire slave, in response.

This reset pulse is controlled by the lowest two bits of the Mode argument in the OWIN command. It can be made to appear before the ROM Function Command (ex: Mode = 1), after the Transaction/Data portion (ex: Mode = 2), before and after the entire transaction (ex: Mode = 3) or not at all (ex: Mode = 0). See the section on Mode, above, for more information.

Following the Initialization part is the ROM Function Command. The ROM Function Command is used to address the desired 1-Wire device. The table below shows common ROM Function Commands. If only a single 1-Wire device is connected, the Skip ROM command can be used to address it. If more than one 1-Wire device is attached, the BASIC Stamp will ultimately have to address them individually using the Match ROM command.

Command | Value (HEX) | Action
Read ROM | $33 | Reads the 64-bit ID of the 1-Wire device. This command can only be used if there is a single 1-Wire device on the line.
Match ROM | $55 | This command, followed by a 64-bit ID, allows the BASIC Stamp to address a specific 1-Wire device.
Skip ROM | $CC | Address a 1-Wire device without its 64-bit ID. This command can only be used if there is a single 1-Wire device on the line.
Search ROM | $F0 | Reads the 64-bit IDs of all the 1-Wire devices on the line. A process of elimination is used to distinguish each unique device.

The third part, the Memory Function Command, allows the BASIC Stamp 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.

Finally, the Transaction/Data section is used to read or write data to the 1-Wire device. The OWIN command will read data at this point in the transaction. A read is accomplished by generating a brief low-pulse and sampling the line within 15 ms of the falling edge of the pulse. This is called a "Read Slot." The figure below shows typical Read Slots performed by the BASIC Stamp. See the OWOUT command for information on Write Slots.

Go to Welcome page

BASIC Stamp Help Version 2.5.4

Copyright © Parallax Inc.

8/8/2012