PSXTCL: an easy TCL interface to Point Six, Inc 1-Wire devices

November 1999

psxtcl is a TCL language extension and library implementing an interface to the Point Six, Inc HA5 ASCII RS232 to 1-Wire host adapter.

The Point Six, Inc 1-Wire products allow easy interfacing from a PC to a wide array of sensors and switches. The HA5 controller can be connected to any standard serial port.

psxtcl allows access to the general HA5 interface and has higher level functions for easy use of the DS1820 temperature probes and T2SS I/O modules

psxtcl was developped as the basis for an elementary temperature control system for my wine cellar. I am reasonably certain that there exist more serious applications for it

psxtcl has been developped and tested under the FreeBSD operating system. It will probably run on almost any recent UNIX system or Linux.

psxtcl is free and covered by the GNU GPL license.


1. Introduction

1.1. psxtcl overview

psxtcl defines an API and a few utility programs and uses a configuration file to describe the hardware that should be used.

The programming interface has two modes of operations:

  • Direct mode: the hardware is accessed from the application processes, which are responsible for providing synchronization if needed.

  • Client/server mode: the hardware is accessed from a single server process, providing service for potentially multiple application processes.

The psxtcl API does not support all of the HA5 interface functions. It should be relatively easy to add the missing functionality by building on the low level procedures which are provided. It should also be relatively easy to adapt the library for the simpler, cheaper HA7E controller, which has a similar command set.


1.2. About this document

This manual describes the psxtcl interface. It does not replace the PointSix manuals in any way, and supposes a general understanding of HA5 and 1_Wire concepts.

You should also have some understanding of the TCL language

Read the HA5 documentation first !

While reading this manual, it may be useful to refer to the sample program climcave.tcl which provides actual examples of use for the different procedures.


2. The configuration file

The configuration file describes how the HA5 adaptor(s) are configured and connected to the system and provides a way to define application nicknames for the 1_Wire devices

The file structure is simple enough, and will be easier defined by an example than by a description.

    # The controller. 
    # You will probably need to change the tty device name to match your
    # configuration.
    # 'a' is the controller address, see PointSix documentation.
    # The address, the line speed, and the cksum on or off (1/0) should of
    # course match the switch settings
    array set psxtcl_adapt_host1 {
        tty /dev/cuaa0
        speed 115200
        addr  a
        cksum 1
    }
    
    # Device definitions. Each definition has 2 entries:
    #  - the name of the host adapter the device is attached to.
    #  - a nickname for the device id.
    # The device arrays can be automatically generated by the
    # "psxdevs.tcl" program, but you will usually want to replace the
    # device names with something more meaningful.
    # (The device name is the part of the array name after
    # 'psxtcl_device_', which would come as dev1, dev2... out of psxdevs) .
    # 
    array set psxtcl_device_tempext {
          hosta host1
          devid "15000000301D8410"
    }
    array set psxtcl_device_ctl1 {
          hosta host1
          devid "160000000E44C512"
    }

Note that the names of controllers and devices are arbitrary, and are the last part of the array name, after psxtcl_adapt_ or psxtcl_device_.

This makes it easy for the extension to find all defined controllers or devices, without explicit lists.

The psxdevs.tcl program will list all 1_Wire devices on a given controller, in the configuration file format. This helps building or updating the configuration file by just replacing the automatically generated device names (dev1, dev2, etc...) with meaningful names.


3. psxtcl procedures

All psxtcl procedures are defined inside the psxtcl namespace. To use them, you will need to import them in your tcl program. For example

    package require psxtcl
    namespace import psxtcl::psxtcl_*

3.1. High level routines

3.1.1. psxtcl_readtemp

psxtcl::psxtcl_readtemp device

This procedure returns the current temperature measured by a DS1820/DS1920 digital thermometer. Internally, the procedure uses the V command and does the computation to obtain high resolution temperature data.

device is the device name as from the configuration file.


3.1.2. psxtcl_readio

psxtcl::psxtcl_readio device resetlatch

This procedures reads the I/O states of a DS2406/2407 device. The resetlatch parameter defaults to 0.

The data is returned as a list of alternate name/value pairs, suitable for an array set statement.

The list is as follows:

    OutputA 0/1 OutputB 0/1 InputA 0/1 InputB 0/1 LatchA 0/1 LatchB 0/1

The parameter values are natural, a 1 means active.


3.1.3. psxtcl_setoutputs

psxtcl::psxtcl_setoutputs device Aon Bon

This procedure sets the output states for a DS2406/2407 device.

Aon and Bon should be set to 1 or 0 to enable or disable an output


3.2. host adapter oriented routines

3.2.1. psxtcl_reset

psxtcl::psxtcl_reset adapt

This procedures generates a 1_Wire reset and returns the adapter's answer


3.2.2. psxtcl_searchrom

psxtcl::psxtcl_searchrom hosta knownalso

This procedure returns a list of rom codes found on the 1_Wire bus.

The value for knownalso determines if all devices are listed, or only those which are not currently listed in the configuration file (the default)

This procedure is the core of the psxdevs.tcl program which lists the devices in a format suitable for inclusion in the configuration file.


3.3. Low level routines

The following procedures implement the individual operations on an HA5 adaptor: select a device, send a command, read the resulting output.


3.3.1. psxtcl_writecmd

psxtcl::psxtcl_writecmd device cmd

This selects the device designated by the device name device and writes the command cmd to the adaptor.

The adaptor address and checksum must not be included in cmd as they are computed from the configuration file information.


3.3.2. psxtcl_readline

psxtcl::psxtcl_readline device

This reads data from the adaptor and should be used after a psxtcl_writecmd call.


3.3.3. psxtcl_select

psxtcl::psxtcl_select hosta devid

This selects the device designated by rom code devid. This is invoked inside the psxtcl_writecmd procedure, and has probably little other use.


3.4. Miscellaneous procedures

3.4.1. psxtcl_family

psxtcl::psxtcl_family devid

This returns the family code out of rom code devid.


4. psxtcl utility programs

4.1. The psxd.tcl daemon

psxd.tcl implements a server which executes actions on behalf of application clients.

The protocol is trivial: the client sends a fragment of tcl code (usually a call to one of the psxtcl procedures), the server executes the code fragment and returns the result.

Important: The protocol has no security provisions whatsoever. The daemon will happily execute whatever TCL code anybody will send at him. Don't run this (especially as root) on a machine which is accessible from a network

The connection is open and closed for each call. This means that only high level psxtcl procedures (like psxtcl_readtemp) can be safely used because they perform a complete action on the adaptor. Low level procedures would need several connections to perform a complete action, with a risk of confusion if several clients interact with the server at the same time.

All in all, this should be completely rewritten, but it's a thirty lines piece of code, and still useful to me.

The following procedure, or an equivalent, can be used on the client side to send commands and retrieve results. You can see that it is quite easy to switch between the local and remote modes of operation. This is used in climcave.tcl

    set local 0
    # Either do a psx operation locally or ask the server to do it
    proc sendcommand {args} {
        global psxport local
        if {$local} {
            return [uplevel "eval $args"]
        } else {
            set cmd [uplevel "subst \[concat $args\]"]
            set s [socket localhost $psxport]
            puts $s $cmd;flush $s
            gets $s res
            close $s
            if {[string match "ERROR:*" $res]} {
                return -code error $res
            } else {
                return $res
            }
        }
    }
         

4.2. The psxdevs.tcl utility

psxdevs.tcl [-a] adapname

The psxdevs.tcl command will list the devices on a 1_Wire bus, in a format appropriate for inclusion in the configuration file

By default, only new devices (not already in the configuration) will be listed. The -a option can be used to list all devices

psxdevs.tcl will try to connect to the psxd.tcl server, and will work locally if the connection fails.


5. Installation

Untar the package. Example:

    tar xvzf psxtcl-1.1.1.tar.gz

This will create the psxtcl-x.y.z directoy (psxtcl-1.1.1).

Then run:

    cd psxtcl-1.1.1
    configure
    make
    make install

This should do the trick.

Depending on your system, and how TCL was built, you may have trouble loading the psxtclc.so shared object. This will usually manifest itself at make install time, or with package not found errors.

In this case, if you do not want to get your hands into dirty ld options, you can use make install-static and execute the scripts with the psxtcl TCL shell, which has the extension statically linked in.


6. Useful references

www.scriptics.com, the place TCL calls home

www.pointsix.com, Point Six, Inc home page

www.dalsemi.com, Dallas Semiconductors home page

And feel free to contact me: