HOME > > DALLAS 1-WIRE / MICROLAN SECTION INDEX

Reading the documentation for the 1-Wire (aka MicroLan) network

Writing programs for it in Delphi, including setting up TMEX

This page goes into the documentation for the hardware and software of the Dallas Semiconductor 1-Wire system. If you're not yet ready for the detail, but just want to get an idea of why I'm impressed by it, that information is here. An overview of the system implemented is here.

If you were looking for software written by others for the 1-Wire (MicroLan) environment, click here.

Just before I tell you more, I should explain that I have no connection with Dallas Semiconductor, beyond being a happy user of their products for many years. "1-Wire", "MicroLan" and "iButton" are all trademarks of theirs.

I should also remind you that although the following concentrates on using the system with a Windows PC as the master controller, once you are able to do that, optimizing things to use a less expensive controller, or one with a different expensive OS, is not a big step. Dallas has provided drivers for many platforms, and the detail you need to write one for obscure alternatives.

For an example, we're going to look at a very simple thermostat system. Yes- a functionally equivalent system could be built without resorting to a MicroLan!

The system will consist of an DS1820 temperature sensor, a DS2105 to turn the heating on and off, and a PC to be the controller.

What will the end product of your work be? If you had already finished the project, and someone wanted to have their house set up with a duplicate, all they would need to do after installing the hardware would be to...

a) Install on their PC the driver software from Dallas.
b) Run your program.

Looking more closely at the first job:

a) "install the driver software": I'm 90% sure that what you need is called the "RTE" (Run Time Environment). I must admit, I didn't do this as a separate install, nor by hand. (I set up both the RTE and the SDK (explained soon) by inserting the...
... CD called "Dallas 2000 Data Book" and

clicking on...
iButton-TMEX RunTime Environment Rev.3.11 and...

.... which appears under "Software Installs" on the secondary page which you reach after clicking on the "1-Wire® Chips" link which is on the front page that comes up if you let the CD autostart. (The "1-Wire® Chips" link is under the "Automatic Information" heading.) I believe the same software is available from the Dallas site, or the iButton site. There is certainly a wealth of software there for you!

If you don't like opaque installs, you can use Windows to access the CD. What you want is in \AutoInfo\RTE... from which you select a folder for the system you are doing the install on: DOS, Win16, or Win32.

Using the RTE is a little bit like using Windows API calls. If that makes no sense to you, just ignore it!

Your program is not sufficient on it's own. When you created it (more on this in a moment), it assumed that it could call some routines... routines to be found in the RTE. Don't worry if this idea isn't familiar to you.. it is a common way of doing things, for very good reasons. One of them gives rise to the following: If you wrote the program on a Windows 95 machine, using that to test it (in which case, that machine had the Win32 RTE installed), you will find that the same program, without modification, will run on a Windows 3.1 machine, or a DOS machine... as long as they have the Win16 RTE or the DOS RTE, respectively. Of course, that statement ("it will run...") only relates to the 1-Wire aspects of the problem. Your DOS machine will not suddenly sprout windows! RTEs (in general) provide a "translator" between what you do (the program) and a specific environment (DOS, Windows, Solaris, etc). From the program's side of the bridge, each RTE looks the same. But as things cross the bridge (either way) they are translated into what the specific environment needs.

The RTE is free. You can pass on copies to customers so that they can buy chips from Dallas and buy your program from you.

So! Enough diversion. Back to work. How do you create the program?

After installing the RTE on the machine you want to work on, install the Software Developer's Kit (SDK). It was the next item ("iButton-TMEX Software Developer's Kit 3.10") on the CD mentioned above, and is also available (free) over the internet. Once you have done that, you will have a whole bunch of useful help files, examples (in several languages), etc, on your disc. You will also have some near-essential files that simplify writing programs for the MicroLan.

These "near-essential files" are, in Pascal and Delphi terms "units". I don't know other languages as well, but I think VB and C call them "Libraries", and they are the sort of thing you tell your compiler about with the verb "include".

Visit my Delphi 1-Wire programming tutorials for further details, and some Delphi source code (Look in particular at the first two tutorials in Level 5.) This page is about more general issues.

You need to grasp the layers the problem has been arranged in.

We'll start at the level of the chip itself, looking at the DS2405 for our example. You need to look at the datasheet for that chip, which is available over the internet, and it is also on the CD. This may be a good place to remind you that an iButton is nothing more than a 1-Wire (aka MicroLan) chip in a robust package. (They look like 15mm diameter, 6mm thick watch batteries.)

Go make a cup of coffee. Here beginneth some hard stuff. Hard to explain, hard to grasp... wonderfully simple, in essence, though. Getting through this next bit will be a bit like learning to ride a bike.

Cast your mind back to the explanation of the way that one wire can carry data to and from many slaves, and power as well. Now look at the datasheet, and find the flowchart. ("ROM functions flow chart, fig.4", on pg.9 in mine, which has "102299" in the lower right of each page, perhaps a version ID.)

(First of all: beware that word "ROM"... I kept misunderstanding things because I thought I knew what it meant, how it was being used. Gloss over it!)

The flowchart is not a description (in any narrow way) of a program. Rather, it describes the operation of a DS2405 in a MicroLan.

Start with the first box: "Master Tx Reset Pulse." The correct extended interpretation of this is: As soon as the DS2405 is powered up, it will sit and wait until the master (i.e. the PC or other in charge of the MicroLan) transmits (Tx) the special code (pulse) which causes all attached slaves to reset themselves. Remember: anything anyone (master or slave) transmits on the LAN is "seen" by everyone... it is how (whether) things respond that is important!

Only when the master transmits the reset pulse do we move on to the next box. As soon as it has seen the reset pulse, the DS2405 (the slave) will transmit a code saying, "Yes, a chip is here". This message is anonymous, and all other 1-Wire on the LAN will also be sending them. the presence pulse is not much use, apart from being a preliminary check that the LAN works in at least a limited way.

Now, the flowchart tells us, the DS2405 waits for the master to send a "ROM function command". All the other slaves are also waiting for this. They all respond... internally... to a number of commands. When I said respond internally I was trying to make clear that they will not necessarily "say" anything on the LAN as part of their response.

The really cool Rom function command is "Match Rom", code 55h. (the hex number 55, i.e. binary 0101 0101) The master issues this command prior to sending 64 bits onto the LAN. The 64 bits are what it takes to "say" one of the possible chip ID numbers.

The master, by means of the Match command can "turn off" every slave on the LAN, apart from the one with the number it sends out after "saying" "55h". The flow chart tells us this:

After the master transmits the 55h, the flow chart directs us to check: Was it a 33h? No, so: Was it a 55h? Yes! So: "Master Tx bit 0", i.e. Wait for the master to transmit bit 0 of the id of the chip that it wants NOT shut down. (Remember that all of the slaves are doing the same thing up to now.) When it has transmitted that first bit, as "Bit 0 match?", I.e.: Is bit 0 of MY ID the same as the bit the master transmitted? If NOT, I follow the arrow to "Master Tx Reset", i.e. WAIT until the master transmits the nest reset pulse.... in other words, I'm essentially switched off. On the other hand, if bit 0 of my ID was the same as the bit transmitted by the master, I now await the next bit.... and so on.

Once all 64 bits (the last being bit NUMBER 63, because the first was bit number 0) have been sent by the master, all but one of the slaves is "asleep", awaiting the next reset.

What we have seen so far is typical of any 1-Wire chip's response to a Match Rom command. What happens next? In the case of the DS2405, it toggles the state of its PIO (programmable input/output) external, physical, in- addition- to- the two- 1- Wire- pins pin. (Toggle: makes it 0 if it was one, and vice versa.)

A digression: The PIO pin of the DS2405 can be an input or an output. I'm not quite sure how this can be, but I do know that it works! In all of the systems I've used in the past, there's been a mandatory way to say ahead of time which way you want to use PIO pins. There is no such step in the DS2405's operation. End of digression.

Lastly, the flow chart tells us that the DS2405 will transmit 0s or 1s until the master issues a reset pulse. (What state will the PIO be in before the first Match ROM and concomitant (in the case of the DS2405) toggle PIO? I don't know!)

Some Good News: If all goes well, you may not have to look at a device flowchart in detail again! The SDK takes care of MANY messy details for you. You may want to look at one in case of difficulties, though, so I thought you needed to know how to read one. Go re-heat your coffee... you've earned it.

Before we can create a program, we need to look at another layer, and at some hardware. This essay assumes the simple case: that you are using a Dallas interface, e.g. a DS9097, or an iButtonLink interface (confusingly NOT a Dallas product... but largely equivalent to the 9097), plugged into your computer's parallel or serial port. (There are alternatives, e.g. a HA7E or a WeatherDuck. They slightly change how you work, though, so leave them for another day.) Into the 9097, you plug the two wires of your MicroLan.

Any MicroLan program consist of at least....

"Get the adapter (e.g. 9097) running"
"Do things"
"Shut down the adapter"

Getting the adapter running and shutting it down have several aspects, not least setting up within the software a convenient channel of communication between the program and the adapter.

Before I can go on, a (computer) language independent word about "calling functions", the verb "returns" and "parameters". In Pascal I might write Ans:=DoIt(1,2,3) if I meant "do the thing called DoIt. Send the parameters 1, 2 and 3 to DoIt. Put whatever answer comes back in the variable called Ans." In this essay, I will speak of such things as follows: "Call DoIt. Pass the parameters 1,2, and 3." If I say "DoIt returns zero if there was no problem", then that means that, in my Pascal example, Ans would have zero in it after the line of code had executed.

Sometimes, in place of 1, 2 and 3, you must insert a variable. After the function has been processed, the contents of that variable may have changed.

Working with the SDK gives you access to a bunch of functions with names beginning "TM". (From "Touch Memory", the name of an iButton precursor, I think). To "get the adapter running" (and the system ready for further operations), you call the TMExtendedStartSession function. You pass three parameters to it. The first tells the system what port the adapter is plugged into. The second tells it what type of adapter you are using. The last should have a null. (Don't worry about that. See program examples for what works.). TMExtendedStartSession returns a number greater than zero if al is well. That number (the value of which does not concern you... just put it in a variable, and use that when you need the number) is called the "Session Handle". It is, if you like, a quick way to say "that adapter". For this essay, I'm going to assume that the number was put in a variable called SessHndl

Once you've done TMExtendedSessionStart, you need to do TMSetUp, which has SessHndl as it's parameter.

In a simple world, you only need to do TMExtendedSessionStart/TMSetUp once, prior to any use of the MicroLan. Once, at the end of everything, you should do TMEndSession, which also takes SessHndl as it's parameter.

I tend to be more conservative. I call TMExtendedSessionStart/TMSetUp just before using the MicroLan within the broader context of my program, and call TMEndSession each time I'm through with the MicroLan for the moment. There's even a TMValidSession that I could use to see if a session I set up earlier is still okay... but I haven't been doing things that way!

A couple of odds and ends:

a) Don't confuse what we've been talking about in setting up the adapter with the RESET pulse that we will eventually be sending over the MicroLan.
b) There is a TMSessionStart... but I think that is obsolete, TMExtendedSessionStart being a later and better replacement.

So! Where did I find this Good Stuff?

It is in the "iButton-TMEX Software Development Kit Reference Manual", which you can find on the CD or on the internet. On the CD it is in the User's Guides section of the "iButtons and 1-Wire section." (Be careful you don't click on the "Software Install" link, if all you want is to consult the .pdf!) The same information is available in the help file "TMEXAPI.HLP" which installs with the SDK. After the install on my system, it was in \Dallas\Doc\TMEX_SDK.

We are nearly there. How's your headache?
Remember all that business about using the Match Rom function command to turn off all the slaves but one on the MicroLan, and, in the case of a DS2405, toggle the PIO?

TMEX takes care of most of the hassle for you. Once the adapter is running (see above), you only have to make two function calls:

First TMRom. (Remember I said not to think too closely about why "rom" appears in the name.) It takes 3 parameters. The first is the session handle, created by TMExtendedSessionStart/ SetUp, as explained above. The second parameter is a way for the program to access some memory. (See program examples, or SDK documentation for details). The last parameter holds the ID of the chip you want to access.

Once you've called TMRom, you call TMAccess. It needs two parameters, the ones that were the first two passed to TMRom. TMAccess is pretty clever: It causes the master to issue a reset pulse to the MicroLan (by calling TMTouchReset), it then goes through all of the stuff described above when I talked about a system going through the execution of the Match Rom function command.

Guess what? For a simple program to toggle the PIO of a 2405, you now know almost everything you need!

What DON'T you know?

Try to think of it yourself?

(Have another coffee?)

umm...

well...

v

v

v

v

v

v

v

v

v

v

v

Did I create enough white space to save you seeing the answer before you wanted it?

Remember how often I've said things like "...the ID number of the chip in question..."? How do you know the number of an individual chip? How do you know what chips are on the MicroLan? TMEX to the rescue!

If you execute TMFirst, it will give you the ID number of one of the slaves. For example, one of my DS2405s is number (in binary)...

1010 0010 0000 0000 0000 0000 0000 0000 0000 1101 1111 1110 0101 0100 0000 0101

(I think they're serious about not wanting to run out of numbers!)
The first 8 bits are a checksum. The last 8 bits are always 0000 0101 for a DS2405. That leaves 48 bits in the middle for different 2405s. Would anyone like to illustrate that number for me? Perhaps it is something like every person on the planet could be given as many 2405s as there are people in the USA before Dallas would run out of numbers. Alternatively, if they used all of the device codes, and all of the numbers for each, and each chip weighed 2 grams, what percent of the earth's mass would have to be converted to chips to manufacture them all?

Anyway... Once you have called TMFirst once, you then call TMNext. (Pretty snappy, these names!). It will return the ID of another slave on the net, or 0 if all slaves have already been found by previous TMFirsts or TMNexts.

Well.. I'm exhausted. What about you? I hope you are now launched into the fabulous world of 1-Wire and TMEX? Obviously there are other things to learn about. I'll try to write some of them up eventually.

Just before I go, three things....

You'll see talk of "Strong Pull Up". The adapter between the PC and the MicroLan may or may not be able to, may or may not be setting the data/ power line in a "Strong Pull Up" state. I've used DS1820s without a Strong Pull Up state, and they worked, even though I think the data sheets say they shouldn't. It is something to get to grips with, but not to worry about too much in the early days.

In documentation about TMRom, TM Access, and others, you may (if you're like me!) be confused by references like "The internal 8 byte buffer can be read (or written) by..." I'm 90% certain that this "internal buffer" is somewhere in the bowels of the RTE software. It seems that you use TMRom to move a chip's ID into or out of the buffer in the RTE (which sits in a corner of the PCs RAM). That buffer is consulted or filled by various TMxx functions that need or read the IDs of slaves on the MicroLan. Sorry... maybe I didn't explain that still... but at least you are alerted to a possible source of confusion!

Third: Beware of the various near relatives for temperature measurement. Work with the data sheet of the chip you are using. Slight differences in accessing the registers and data formats mean that what works for one won't work properly for a near relation!

PLEASE send me a nice email to reassure me that someone read this, and that my work was of some use to you? Your general geographic location (I don't need address) would add to my enjoyment of the information. My Delphi tutorials have been used from the Ukraine to India to Alaska to many corners of the lower 48 US states.

Above all? ENJOY!!

Looking for email, domain registration, or web site hosting? If you visit 1&1's site from here, it helps me. They host my website, and I wouldn't put this link up for them if I wasn't happy with their service. They offer things for the beginner and the corporation.

Ad from page's editor: Yes.. I do enjoy compiling these things for you. I hope they are helpful. However... this doesn't pay my bills!!! Sheepdog Software (tm) is supposed to help do that, so if you found this stuff useful, (and you run a Windows or MS-DOS PC) please visit my freeware and shareware page, download something, and circulate it for me? Links on your page to this page would also be appreciated!
Click here to visit editor's freeware, shareware page.
How to email or write this page's editor, Tom Boyd

Why does this page cause a script to run? Because of the Google panels, and the code for the search button. Also, I have my web-traffic monitored for me by eXTReMe tracker. They offer a free tracker. If you want to try one, check out their site. Why do I mention the script? Be sure you know all you need to about spyware.

....... P a g e . . . E n d s .....