Ultracomm

ultracomm is a command line utility for configuring Ultrasonix Tablet systems and acquiring ultrasound data.

In the Phonology Lab we typically don't run ultracomm directly and instead run the ultrasession.py Python script, which handles a lot of bookkeeping details relevant to a data acquisition session automatically, and which calls ultracomm for you.

The ultracomm code and releases are available at [github]. See the 'Releases' section for the latest released version.

Usage

ultracomm accepts a number of parameters that are used to connect to and configure the Ultrasonix system. These parameters can be included on the command line or aggregated in a parameter file that is included with the --params option.

 ultracomm --params /path/to/params.cfg

The --address and --output parameters are required unless an information-only option was invoked (e.g. --help or --version). --address specifies the IP address of the Ultrasonix system, and --output names an output file containing a series of ultrasound images.

For a listing of available parameters, see [params.cfg] in the ultracomm repository.

For all available options, use:

 ultracomm --help

A typical acquistion

A typical acquisition with ultracomm proceeds by first initializing the ultrasound system and then acquiring data. The first call to ultracomm is non-interactive. It sets the ultrasound system to use the specified imaging parameters, then freezes the system to the non-imaging mode:

 ultracomm --params /path/to/params.cfg --init-only

The second call to ultracomm starts acquiring data and saves to the output file specified by --output.

 ultracomm --params /path/to/params.cfg --output /path/to/output.bpr

This command is interactive and prompts the user to press Enter to terminate the acquisition. ultracomm will confirm that the imaging parameters are correct before performing the acquisition.

The acquisition command can be repeated as many times as desired without re-executing the --init-only command. The imaging parameters will not change unless there is additional user interaction with the ultrasound system.

Troubleshooting

There is an issue with ultracomm occasionally terminating with an access violation error. This error occurs at program end, after acquisition has completed and data files are closed. It is believed to be the result of a bug in the Ulterius library supplied by Ultrasonix and used by ultracomm. Since the error occurs at program end it doesn't seem to result in bad or missed data, but it can result in a Windows error dialog box popping up, which can interfere with the flow of a series of acquisitions in an Opensesame or other experiment. The --av-hack option is used to ignore access violation errors so that they do not result in popup messages.