NAME

    Device::Tektronix - Command interface for Tektronix THS Handheld
    Oscilloscopes

SYNOPSIS

     my $tek = new Device::Tektronix(debug => 1,
                                  port  => 'com1',
                                  baud  => 38400
                                 ) or die;

     $tek->connect or die $tek->error;

     $oldsource = $tek->waveform->source;
     $tek->waveform->encoding('ulsb');   # signed, MSB first
     $tek->waveform->source("ch2");
     $tek->waveform->start(1);
     $tek->waveform->stop(2049);
     $tek->waveform->width(8);

     $tek->trigger->auto_set;

     $tek->channel->bandwidth($channel,'full');

     $scale = $tek->time->scale;  

     $data = $tek->waveform->get;

    See tek-fft included with the distribution of this Perl Module for a
    full and complete example of the API.

DESCRIPTION

    THS.pm is an object-oriented interface to the Tektronix THS700 series
    handheld oscilloscopes. It uses either Win32::SerialPort or
    Device::SerialPort for communications under Unix and Windows.

    Advanced features include waveform datalogging, and extended DMM
    logging.

    The full command set is not implemented yet, but should be done by
    version 0.2.

    This project lives at http://warped.org/tek.

AUTHOR

    Max Baker

Methods

  Constructor and Fundamental Methods

    new([args])
        New will accept a few arguments :

            debug     - Print Copious debug info to stdout
            port      - Specify the com port (com1,com2)
            baud      - BAUD rate to use for scope (default is 9600)
                        Make sure your scope matches, and speed it up to 38,400!
            flaghard  - RTS/CTS  or Hardware Flow Control (0 or 1), default on
            flagsoft  - Xon/Xoff or Software Flow Control (0 or 1)
            parity    - Parity Bit for RS232  (0,1)
            stopbits  - Stop Bits for RS232  (1)
            retries   - Number of times to retry a command before failing. (10)
            timeout   - Timeout in Seconds for each retry on serial port  (10)
            serialize - Boolean.  Use to turn off BUSY? checking.  Use with caution.

        Don't forget to $tek->connect()!

        This module is designed to work in silent mode, so that you can
        build an application around it. Any command will return undef if
        there is an error or failure. Check the error() method of your
        object if you get an undef, or turn on debug.

    $tek->connect()
        Connects your object to the scope through the serial port. Note,
        changes some settings.

    $tek->error()
        Any command that fails returns undef. Hit this method to see what
        the last error was.

         my $error = $tek->error();

    $tek->serialize([1|0])
        Turns off command serialization. Internally will do a 'BUSY?' check
        before sending each command. See the Programming Manual for more
        details.

         # speed up things that we know won't collide
         $tek->serialize(0);
         $tek->command...;
         $tek->command...;
         $tek->serialize(1);

  Internally Used Methods

        You probably don't want to bother to mess with these, but just in
        case...

    $tek->query(cmd,[argument,argument])
        Internally used command that allows you to send command language
        directly to the scope. Use this command to talk to the scope
        yerself. Will return the results of the given commands. Use set()
        for commands that don't give results.

        Note: The [] in the prototype means 'optional', not 'array
        reference'.

    $tek->busywait()
        Internal use only. Does a 'BUSY?' check and waits for the '0' or
        '1'. Internally has timeouts.

    $tek->set('cmd',argument,[argument])
        Internal use only. Command to set something on the scope. Returns
        undef if error, or non-zero if it worked. Does not return anything
        from the scope, use query instead.

    serial_check()
        Internal use only. Checks to make sure the port is not CTS blocking
        or there was a disconnect, etc.

    $tek->receive()
        Internal use only. Waits for a line from the serial port, terminated
        in a linefeed. Used by query()

    $tek->send(msg)
        Internal use only. Sends a line to the serial port.

  Helper Methods

        These are for getting around some of the command lanaguage
        weirdness.

    $tek->to_num
        Converts the given string to float. Used to convert sci. notation
        values from scope to perl usable values.

    $tek->NR3(number)
        Formats a number in socalled 'NR3' format as per the programming
        manual : Floating Point Value with an Exponent.

        No Plus Sign and E is capital, unlike Perl.

Command Sub Modules

    All the device commands are put into sub catagories to make it all more
    readable, and so I don't have to type as much.

  Aquire Commands

    $tek->aquire->aquire()
        Query: Gives summary of aquire settings.

    $tek->aquire->mode([mode])
        Query: Shows current Aquire Mode.

        Set: Change Aquisition mode to :

                sample
                peak detect
                average
                envelope

        You can truncate these to three letters if you want.
        (sam/peak/ave/env)

        The settings inside the mode is not changed with this command.

    $tek->aquire->samples()
        Query : Returns the number of acquisitions performed by scope in
        current aquire mode.

    $tek->aquire->averages([number of averages])
        Query : Returns the number of Averages used for average mode

        Set : Turns on Average Aquire Mode and sets the number of averages.

        Number must be any number between 2 and 256.

    $tek->aquire->envelope([Number of Envelopes])
        Query : Number of Envelopes in use for Envelope Mode

        Set : Turns on Envelope mode and sets the number of envelopes used.
        Number of Envelopes can be any number between 2 and 256.

        Set to 0 or 'infinity' for Infinite (free-run) envelope mode.

    $tek->aquire->state([state])
        Query : What aquire state the scope is in

        Set : Start or Stop data aquisition.

            off/stop    - Like the "hold" Button
            run/start   - Resets the acuisition counter to 0 and starts aquisition.

    $tek->aquire->run()
        Start / Restart aquisition.

    $tek->aquire->stop()
        Stop Aquisition

    $tek->aquire->stopafter([command])
        Query : See what Stopafter mode the scope is in

        Set : Have the scope in free-run aquisition mode, or have it stop
        after it has filled its buffers.

            run  - Default behavior
            done - Stop aquisition after "single sequence" of aquisitions.

  Alias Commands

    This sub-module includes the Alias Commands section of the Programming
    Manual.

    Aliases are macro buffers that you can setup and store complex
    measurements into.

    $tek->alias->alias()
        Query : See if Aliases are on

        Set : Turn Aliases off and on.

    $tek->alias->list()
        Query : Lists different names set

  Diagnostic Commands

    This sub-module includes the following sections from the Programming
    Manual:

    Status and Error
    Misc
    Calibration
    Diagnostics

    $tek->diag->header([on|off])
        Query : See if Header is on (any query will tell you this)

        Set : Turn Header on or off. Takes on/off/0/1 as arg.

        Headers are turned off by connect()

        Turning headers on might break some internal functions. Maybe.

    $tek->diag->id()
        Query : ID String

    $tek->diag->lock([all|none])
        Query : See if front panel is locked

        Set : Turn lock on or off. Takes all/none as argument.

        The On button is never locked.

  

  

  

  

  

  Time Settings (Horizontal Commands)

    scale
        Query : Timebase returned as number (not string)

        Set : Number from 5ns to 5s with 1-2-5 granularity.

  Channel Commands (Vertical Commands)

    $tek->channel->status( channel_no )
        Query : Get Channel info for channel_no

    $tek->channel->probe( channel_no )
        Query : Get Probe info for channel_no

    $tek->channel->bandwidth( channel_no [20/full] )
        Query : Get Bandwidth setting for channel

        Set : Set Bandwidth

    $tek->channel->coupling( channel_no [ac|dc|gnd] )
        Query : Get coupling setting for channel

        Set : Set coupling

    $tek->channel->invert( channel_no [on|off])
        Query : Get invert setting for channel

        Set : Set invert

            on
            off

    $tek->channel->position( channel_no [delta_divs])
        Query : Get position setting for channel

        Set : Move position by given number of divisions

        Value can be +- 10 divs according to my scope, but +- 5 according to
        the programming menu.

    $tek->channel->units( channel_no [volts|amps])
        Query : Get units setting for channel

        Set : Set the probe type to voltage or current probe

            volts
            amps

    $tek->channel->probescale( channel_no [1|10|50|100|500|1000])
        Query : Get Voltage Probe Attenuation Factor setting for channel

        Set : Set the probe type

            1  - 1X
            10 - 10X
            ...

    $tek->channel->scale( channel_no [0.005 - 50000])
        Query : Get Vertical Gain of Channel. Same as VOLTS/DIV Button.

        Set : Set the Volts per division

        Depending on the Probe multiplier in Use, only certain settings
        work.

         1x Probe  - [ .005 .01 .02 .05 .1  .2  .5  1  2  5  10  20  50  ] 
         10x Probe - [ 0.05 0.1 0.2 0.5 1   2   5   10 20 50 100 200 500 ]
         1000x     - [ 5    10  20  50  100 200 500 1k 2k 5k 10k 20k 50k ]

        You can figure out the rest. You might just want to make sure /
        input what type of probe is on there from the user before setting
        the scale. It's safe to assume 10x, unless using a THS720P.

  

  

  Trigger Commands

    $tek->trigger->trigger([go])
        Query : Get current Trigger settings

        Set : Give any argument to force a trigger event

    $tek->trigger->auto_set()
        Set : This one does the same as hitting the "Set Level to 50%"
        Button.

    $tek->trigger->main()
        Query : Gives info about the main trigger.

    $tek->trigger->slope([falling|rising])
        Query : Duh

        Set : Duh

    $tek->trigger->source([ch1|ch2|dmm])
        Query : Source of trigger

        Set : Source of trigger

            ch1
            ch2
            dmm (external)

    $tek->trigger->couple([])
        Query : Get current mode for trigger coupling

        Set :

            dc    - DC Coupling
            hf    - High Freq Rejection on DC Signal
            lf    - Low Freq Rejection  on AC Signal
            noise - DC Low sensitivity.  Requires more amplitude...

    level([some voltage|ttl|ecl])
        Query : Returns the trigger level setting

        Set : Set the trigger level

            ECL - Scope preset of -1.3V
            TTL - Scope preset of 1.4V
            some voltage - Whatever you want.

        Note: In DMM triggering mode, you have only two choices, either 0.2
        or 2.0

  Waveforms Menus

        Includes Data, Curve and Waveform commands

        $tek->waveform->data([init|snap)
            Query : Lists the waveform data parameters

            Set : Sets the waveform parameters

                init - Factory defaults
                snap - USe vertical bars for start and stop

        $tek->waveform->dest([refa|refb|sto1|...|sto10])
            Query : Lists the waveform destination register

            Set : Sets the destination register

                refa - Reference Waveform A
                refb - Reference Waveform B
                sto1 - Storage 1 (not usable from scope interface)
                ...
                sto10- Storage 10

        $tek->waveform->encoding([])
            Query : Lists the waveform encoding

            Set : Sets the waveform encoding

                ascii - plain text, signed integer
                smsb  - signed, MSB     (-128...127) or (-32768...32767)
                umsb  - unsigned, MSB   (0...255)    or (0     ...65535)
                slsb  - signed, LSB
                ulsb  - unsigned MSB

        $tek->waveform->source([init|snap])
            Query : Lists the waveform source

            Set : Sets the waveform Source Channel

                ch1
                ch2
                math
                refa
                refb
                sto0
                ...
                sto10

            You can specify multiple sources. Data always comes back in
            order above. Multiple source data from curve() is separated by a
            comma.

        $tek->waveform->start([1...2500])
            Query : Lists the waveform starting point

            Set : Sets the waveform starting point

                1 - 2500  for scope mode
                1 - 480   for DMM mode

        $tek->waveform->stop([1...2500])
            Query : Lists the waveform stopping point

            Set : Sets the waveform stopping point

                1 - 2500  for scope mode
                1 - 480   for DMM mode

        $tek->waveform->width([8|16])
            Query : Lists the bytes per sample (1 or 2)

            Set : Sets the waveform widthping point

                8  - 8it (1 byte)
                16 - 16bit (2 bytes)

            Note that the scope samples at 8-bit. 16bit is good for Averaged
            waveforms. The MSB is simply 0 for the rest.

        $tek->waveform->get()
            Query : Get waveform data from scope.

  

COPYRIGHT AND LICENSE

            Copyright (C) 2003 by Max Baker

            This library is free software; you can redistribute it and/or
            modify it under the same terms as Perl itself, either Perl
            version 5.8.1 or, at your option, any later version of Perl 5
            you may have available.

