Image by upklyak on Freepik

One of the pain points for new Tcl users is the lack of an obvious package repository and management system. Python has pypi and pip. Tcl has Teapot and Teacup, but these were more popular when they were maintained by ActiveState. If you just want to help users (or yourself) install a few Tcl packages hosted on Github, the Tin package manager is worth checking out.

I developed testin as a way to get to know Tin. Once you manually install Tin, installing other packages is as easy as

$ sudo tclsh
% package require tin
% tin add -auto testin https://github.com/johnpeck/testin install.tcl
% tin install testin

...on linux (since the default package directory is owned by root). If you're using Github for development anyway, Tin doesn't make you understand a new package repository.

The Testin repository has detailed instructions for installing Tin, Tcllib, and finally Testin.

A nugget: named arguments for Tcl procs in Testin

Testin has one function: intlist. It simply makes a list of integers, similar to Python's range. But it experiments with named arguments:

% package require testin
1.3
% testin::intlist -length 6
0 1 2 3 4 5

Nifty, right? The intlist function takes two arguments, but cmdline allows omitted arguments to have default values (in this case, the default first integer is 0). And named arguments make procedure calls easier to understand. This idea came from the Tcler's Wiki.

Updates

2024-Jul-04

First post.

Links

• Tin package manager
• Testin respository
• Named arguments for Tcl procs

Image by pch.vector on Freepik

I've been trying to be better about throwing errors in my Tcl code for tcladu. There seem to be at least three ways to do this: error, throw, and return. Is there any difference? Here's what I tried:

# Demonstrate handling errors with Tcl

proc iterint {start points} {
    # Return a list of increasing integers starting with start with
    # length points
    set count 0
    set intlist [list]
    while {$count < $points} {
    lappend intlist [expr $start + $count]
    incr count
    }
    return $intlist
}

proc pdict {dict {pattern *}} {
   set longest 0
   dict for {key -} $dict {
      if {[string match $pattern $key]} {
         set longest [expr {max($longest, [string length $key])}]
      }
   }
   dict for {key value} [dict filter $dict key $pattern] {
      puts [format "%-${longest}s = %s" $key $value]
   }
}

proc throw_error { code } {
    switch $code {
    1 {
        set message "This error was thrown with error"
        set errorcode "FIRST_ERROR_CODE"
        error $message -errorcode $errorcode
    }
    2 {
        set message "This error was thrown with throw"
        set errorcode "SECOND_ERROR_CODE"
        throw $errorcode $message
    }
    3 {
        set message "This error was thrown with return -code error"
        set errorcode "THIRD_ERROR_CODE"
        return -code error -errorcode $errorcode $message
    }
    }
}

foreach code [iterint 1 3] {
    puts "-----------------------------------"
    try {
    throw_error $code
    } trap {FIRST_ERROR_CODE} {message optdict} {
    puts "Error handler for FIRST_ERROR_CODE"
    puts "Message is: $message"
    puts "Context:"
    pdict $optdict
    } trap {SECOND_ERROR_CODE} {message optdict} {
    puts "Error handler for SECOND_ERROR_CODE"
    puts "Message is: $message"
    puts "Context:"
    pdict $optdict  
    } trap {} {message optdict} {
    puts "Catch-all error handler"
    puts "Message is: $message"
    puts "Context:"
    pdict $optdict
    }
}
puts "-----------------------------------"

...and here's the output:

-----------------------------------
Error handler for FIRST_ERROR_CODE
Message is: This error was thrown with error
Context:
-errorinfo  = -errorcode
    (procedure "throw_error" line 1)
    invoked from within
"throw_error $code"
    ("try" body line 2)
-errorcode  = FIRST_ERROR_CODE
-code       = 1
-level      = 0
-errorstack = INNER {invokeStk1 throw_error 1}
-errorline  = 2
-----------------------------------
Error handler for SECOND_ERROR_CODE
Message is: This error was thrown with throw
Context:
-errorcode  = SECOND_ERROR_CODE
-code       = 1
-level      = 0
-errorstack = INNER {returnImm {This error was thrown with throw} {-errorcode SECOND_ERROR_CODE}} CALL {throw_error 2}
-errorinfo  = This error was thrown with throw
    while executing
"throw $errorcode $message"
    (procedure "throw_error" line 11)
    invoked from within
"throw_error $code"
    ("try" body line 2)
-errorline  = 2
-----------------------------------
Catch-all error handler
Message is: This error was thrown with return -code error
Context:
-errorcode  = THIRD_ERROR_CODE
-code       = 1
-level      = 0
-errorstack = INNER {invokeStk1 throw_error 3}
-errorinfo  = This error was thrown with return -code error
    while executing
"throw_error $code"
    ("try" body line 2)
-errorline  = 2
-----------------------------------

The differences are in the error options dictionary captured by the try command. The errorstack key has a much larger value with the throw command. The various commands otherwise do the same thing.

Links

• Try command official documentation.
• Error handling question on Stack Overflow.
• Throw command official documentation.
• Pretty printing dictionaries in Tcl.

Update on 2024-Apr-13 -- Removed Gitlab references

Github makes it easier for me to provide binary package releases along with my source code.

Update on 2024-Mar-23 -- Moving to Github

Development has moved to Github.

The first thing I realized when I started to use tcladu was the need for convenience functions. For example, combinations of write_device and read_device should be combined into a query command for convenience. And it would be nice for those kind of commands to be in the same tcladu package. So I started to write some Tcl, and I realized I didn't really know how to manage the package version with this high-level addition.

The tcladu.so binary already provides the tcladu namespace and package version. I set this version in a makefile that also drives testing, so I'd really like the makefile/binary package version to be the source of truth. So I need to extract that package version in the convenience code. It turns out that there's a package command for this. These links are to Tcl 9.0 documentation, but my usage doesn't care.

Adding these lines

load ./tcladu.so
set version [package present tcladu]
package provide tcladu $version

...to the tcladu.tcl source file synchronizes the Tcl and binary source versions. I can then package this up with

pkg_mkIndex -verbose . tcladu.so tcladu.tcl

...using the pkg_mkIndex command. This produces the pkgIndex.tcl script distributed with the package source files:

package ifneeded tcladu 1.1.0 [list load [file join $dir tcladu.so]]\n[list source [file join $dir tcladu.tcl]]

...where you can see the combination of sourcing and loading done to make the package available. These convenience functions are coming in tcladu version 1.1.0.

Image by Freepik

Links

• A nice description of creating a Tcl package
• Turning a SWIG module into a Tcl package

Tcladu is a Tcl package providing an interface to the ADU100 from Ontrak Control Systems.

One of my projects will be powered by a battery, and will sleep for long periods while it waits for user input. My battery life will depend on this sleep current, which might be about 10 µA. My handheld meter will measure this, but it suffers from mediocre common-mode rejection when I use it to measure high-side current. I really wanted to probe my sleep current and send it directly to an oscilloscope. These INA169 breakout boards seem like a convenient way to make this probe, but using them raises calibration, noise, and bandwidth questions. I want to describe how I put down a simple calibration circuit to give myself some confidence in this measurement.

Wiring the sensor

Figure 1 shows the current sensor, which is built around TI’s IN169 current sensor IC. Adafruit sells the breakout board I used, which builds in the IC, the current sensing resistor R_shunt, the current-to-voltage resistor R_load, and a bypass capacitor. It comes configured with a convenient gain of 1 V/A, and sells for about 10 USD. Sparkfun and others make similar breakout boards. These boards can be modified for different “burden voltages” and power configurations.

Xfig's depth settings can create some headaches when you use figure libraries. Library figures can use depths that conflict with your current drawing. Say I have this drawing of the Teensy Audio Board and a red circle,

...and then I move the red circle over the board:

This is clearly not what I want. The circle has a depth of 50, and the board has depths between 10 and 60. The circle ends up on top of some objects and not others. If you were using PowerPoint, you would just select Bring to Front or Send to Back to arrange the objects. But Xfig requires setting the depth of each member object individually, which you should really do with a script like figdepth.

Using figdepth

Figdepth has some options, the most important of which is the minimum depth argument

...which sets the depth of the topmost object in a fig file. The script simply increments all depths by some number to make this minimum depth to be your setting. You will, of course, need to have everything you want to modify in its own fig file. You can then run figdepth like

...to write your new depth-adjusted figure. Use Xfig's merge command to bring the new figure into your old drawing. My new drawing looks like this:

...with all objects in the Teensy Audio Board at a deeper depth than the red circle.

How does it work?

The Fig file format is really simple, which is one reason why I like Xfig so much. You can figure out what kind of object each line describes by looking at the first character. You then figure out which number in the line is the object's depth and increment it. The switch statement below shows how one line is processed.

proc increase_object_depth { xfig_line depth_increase} {
    # Return a new xfig line with the depth increased
    #
    # Arguments:
    #   xfig_line -- Single line from an xfig file
    #   depth_increase -- Amount to increase the depth
    set entry_list [split $xfig_line]
    set first_character [lindex $entry_list 0]
    switch $first_character {
    "0" {
        # Color object -- nothing to do
        return $xfig_line
    }
    "1" {
        # Ellipse
        set depth_index 6
        set old_depth [get_object_depth $xfig_line]
        set new_depth [expr $old_depth + $depth_increase]
        set new_entry_list [lset entry_list $depth_index $new_depth]
        set new_line [join $new_entry_list]
        return $new_line
    }
    "2" {
        # Polyline (also imported picture bounding boxes)
        set depth_index 6
        set old_depth [get_object_depth $xfig_line]
        set new_depth [expr $old_depth + $depth_increase]
        set new_entry_list [lset entry_list $depth_index $new_depth]
        set new_line [join $new_entry_list]
        return $new_line
    }
    "3" {
        # Spline
        set depth_index 6
        set old_depth [get_object_depth $xfig_line]
        set new_depth [expr $old_depth + $depth_increase]
        set new_entry_list [lset entry_list $depth_index $new_depth]
        set new_line [join $new_entry_list]
        return $new_line
    }
    "4" {
        # Text
        set depth_index 3
        set old_depth [get_object_depth $xfig_line]
        set new_depth [expr $old_depth + $depth_increase]
        set new_entry_list [lset entry_list $depth_index $new_depth]
        set new_line [join $new_entry_list]
        return $new_line
    }
    "5" {
        # Arc
        set depth_index 6
        set old_depth [get_object_depth $xfig_line]
        set new_depth [expr $old_depth + $depth_increase]
        set new_entry_list [lset entry_list $depth_index $new_depth]
        set new_line [join $new_entry_list]
        return $new_line
    }
    "6" {
        # Compound -- nothing to do
        return $xfig_line
    }
    default {
        # Some non-object -- nothing to do
        return $xfig_line
    }
  }
}

Having trouble with cmdline?

Figdepth uses the cmdline package from tcllib to handle command line arguments. I usually run scripts out of Eshell in Emacs, so I have this in my .emacs:

...to set the TCLLIBPATH environment variable. This tells Tcl where to find Tcllib's packages.

Where is the figdepth script?

Figdepth is part of my xfigart repository.

I still love Xfig when I need to make a sketch of something with roughly-correct diminsions. I've been neglecting my Xfigart repository, but I'm going to try to be better. I'll start with this drawing of the CES-571423-28PM speaker from CUI.

The siunitx package for LaTeX makes it easy to handle units in both normal and math modes. I end up needing units like V_rms when talking about electronics, so I add this in my preamble:

\usepackage{siunitx}

\DeclareSIUnit \vrms {\ensuremath{\mathrm{V_{rms}}}}
\DeclareSIUnit \vpp {\ensuremath{\mathrm{V_{pp}}}}

...to define these units to siunitx. I can then invoke the units with something like

free air.  I drove them to about \SI{9}{\vpp}.

where I know siunitx will then make the proper space between the number and the unit. This all renders like this:

...in the PDF output.

I've been wanting to experiment with audio signal processing on the Teensy, so I bought a Teensy 4.0 and an Audio Adaptor Board. I had to do a bit of research to find the right headers to plug one board into the other. I ended up with the headers listed below.

I used these headers in the photo shown below.

I've been interested in fieldbusses lately, and MODBUS in particular is used by some pretty cheap hardware modules. It also offers "driverless" communication — you don't need a .dll or .so file to talk to your hardware. The hardware I've been experiementing with is shown below:

...and can be bought from eBay for around 50 USD. I found some very useful code on the Tcl wiki and was able to write and read from registers with a USB/RS-485 adaptor. The RTU-307C user's manual implies that you can change the RS-485 baud from 9600, but I wasn't able to figure out how that works.

After some more help from The Tcler's Wiki, I put together a GUI to demonstrate MODBUS communication with the RTU-307C module. The animation below shows the GUI next to an oscilloscope (yelloscope) display. The wiki helped me get the mouse wheel to move those sliders.

Links

Source: Repository on Gitlab