Introduction

This example focuses on the basic communication protocol with a DS18S20 temperature probe example.

Hardware

 The one wire bus is actually composed of three wires, +5V, ground and data. It's called 1-wire because there is only a single data pin to communicate both ways. On the MX series you have 4 or 6 1-wire connectors. If you look at the back of the display with the 1-wire connectors to the left, from left to right the three pins will be +5V, data, gnd.

If you need more than 4 or 6 devices just create 'Y' connectors where the the power, ground and data are all split. However beware, long cables and many splits can cause the bus to stop functioning. We have personally tested it with 6 devices attached to the device each with 1 meter (about 3 foot) cables. We have had reports of more/longer cables, but we haven't tested them, nor do we support them.

Each device is programmed with a unique number from the factory reffered to as its address. The number is 8 bytes (64 bits) long. The first 8 bits is reffered to as the family code. The next 48 bits are specific to that device and is gauranteed to be unique from any other device ever produced in the same family. The last 8 bits is a CRC8 of the first 56 bits to allow you to verify that you have received a valid 1-wire address.

Protocol

In 99.9% of circumstances an interaction with the 1-wire bus will be as follows:

#1 Reset the bus

1-wire devices don't listen until you reset the bus. The reset is just a signal for every device on the bus to listen up.

#2 Write out the rom command

Now that you have every device listening, the rom command allows you to select who you want to talk to. For the purposes of this tutorial there are only two. You can either broadcast to every device, or send/receive to/from a single device. The specifics will be discussed later.

#3 Write out commands to probes

This is the actual command telling the device what to do. It is part specific. Consult the datasheet for your device for a complete list.

#4 Read information from the bus

This one is generally optional. Some commands have no return at all. Most of the time the device will also send back a CRC8 of the data at the end. This allows you to verify that the data has been received correctly.

There is also the topic of figuring out what addresses and devices are on the bus. This search algorigh is implemented in the MX.

1-Wire commands (the juicy bits)

Display Return Protocol.

For 1-wire and RPM sensing commands, the display will return information in the Display Return Protocol. Each packet has the form:

1 Byte - #
1 Byte - *
1 Byte - Length/Continued
1 Byte - Type
? Byte(s) - Data

The '#*' is the signature. The third byte serves a dual purpose. It lets you know how long the data will be, but it will also let you know if it will be continued in another packet. The top bit of the byte will signify that there is more data coming in the stream. So if the length is 0x0A, then you have 10 bytes of data and that is it. But if the length is 0x8A then the data is 10 bytes long, but there is more coming in the next packet.

The type will be one of:

'1' - 1-wire return packet
'R' - RPM information

In the case of any 1-wire command, it will be '1'.

Finally the data that the display is returning.

For 1-wire commands the first byte of the data will be a status byte:

00 - success
01 - Unknown 1 wire command
02 - No devices on the bus
03 - Fatal search error

The rest is depends on the command.

Ok back to 1-wire commands. There are two of them, enumeration and transatcion.

Enumeration - FE C8 02

After sending the 1-wire enumeration command hopefully you won't get this:

23 2A - #* Signature
01 - Length 1, not continued
31 - Type: 1-wire packet
02 - Satus: No devices on the bus

What you would really like to see is:

23 2A - #* Signature
0A - Length 10, not continued
31 - Type: 1-wire packet
00 - Satus: Success
[8 bytes]
00 - CRC OK

This will be the result with only one device on the bus. The [8 bytes] contains the address that you can now use to contact that device. It's up to you to figure out what address belongs to which physical device. Remember that the address contains a CRC8. If everything is ok and the data checks out, the last byte will be 00 for success. Any other value denotes a failure. If you have more than one device on the bus you could get something like:

23 2A - #* Signature
8A - Length 10, continued in the next packet
31 - Type: 1-wire packet
00 - Satus: Success
[8 bytes]
00 - CRC OK
23 2A - #* Signature
0A - Length 10, not continued
31 - Type: 1-wire packet
00 - Satus: Success
[8 bytes]
00 - CRC OK

Which denotes two devices.

Transcation - FE C8 01 [Flags] [Write data count] [Read data count] [Data to write]

This is the big one. This command allows you to issue commands on the bus. The command then takes three more bytes:

Byte #1 - Options (bit flags)
Byte #2 - How many bits to write to the 1-wire bus
Byte #3 - How many bits to read from the 1-wire bus

For the Options only currently uses the lower two bits (this WILL change so set all the higher ones to 0)

bit 1 - Calculate and append the CRC8 of the data read from the bus
bit 0 - Reset the bus before the transaction

This is followed by the data to be written to the bus in the order in which you want it written. The data is written first, then the number of requested bits is read. One quirk of the 1-wire bus is that the bus master (the display) has to initiate the reading from the probes. This is why you have to tell the display how many bits to read from the bus.

Be careful when to request the CRC8 and when not to request the CRC8. If the LAST byte you are going to receive is going to be a CRC8 from the device (eg the 9th byte in a 18S20 temperature probe) and you are reading an even number of bytes then ask for the CRC8. If the last byte isn't going to be a CRC8 or you are asking for a non-integer number of bytes then then don't ask for the CRC8 because it will mean nothing.

Just to remind you, generally a 1-wire transaction goes as follows:

#1 Reset the bus
#2 Write out the rom command
#3 Write out commands to probes
#4 Read information from the bus

The rom command is universal between all 1-wire devices. It is used to either single out a single device, or broadcast to all. The two that you will be interested in are:

55 - Match ROM - Single out a single device (the 8 byte address is then transmitted right after)
CC - Skip Rom - Anything after is sent to everyone

After this information can be written to the devices/probes. The commands are device specific and are in the device's datasheet.

Examples

Let's tie all this together with some examples with the DS18S20 temperature sensor.

So when you send the command to tell all probes to get their temperatures ready:

Transmitted to MX: FE C8 01 01 10 00 CC 44

Breakdown:
FE C8 01 - 1-wire command - 1-wire transaction
01 - Options - Reset the bus, no CRC8
10 - transmit 16 bits
00 - read 0 bits
Written to the bus (16 bits):
CC - Skip rom
44 - Convert temperature

Receive from MX: 23 2A 01 31 00

Breakdown:
23 2A - #* signature
01 - Length: 1 bytes
31 - Type: 1-wire packet
00 - Status: success

Now you want to read back the temperature

Transmitted to MX: FE C8 01 03 50 48 55 [8 Byte address] BE

Breakdown:
FE C8 01 - Same as above
03 - Options - Reset the bus, calculate CRC8 of returned information
50 - Send 80 bits of info (8b rom command, 64b address, 8b probe command)
48 - Read back 72 bits of info (SEE NOTE BELOW)
Transmitted onto the bus (80 bits):
55 - Match rom
[8 byte address]
BE - Read scratch pad

Receive from MX: 23 2A 0A 31 00 [9 data bytes] 00

Breakdown:
23 2A - #* signature
0A - Length: 10 Bytes (SEE NOTE BELOW)
31 - Type: 1-wire command
00 - Status: success
[9 data bytes] - see the DS18S20 data sheet for the format
00 - CRC 0K

NOTE:

Even though 72 bits of information were requested, 80 will be returned. This is because the CRC8 was requested which adds 8 bits on to the data.