Skip to content

UserGuide.md

Latest commit

 

History

History
233 lines (193 loc) · 15.1 KB

UserGuide.md

File metadata and controls

233 lines (193 loc) · 15.1 KB
Raw

SysRes User Guide

Boys Town National Research Hospital Stephen Neely

Abstract

SysRes is a program designed to measure a system response by performing synchronous averaging of the response to a wideband stimulus. This document is based on version 3.00 of the SysRes program.

(Note: This is an updated Markdown conversion of the original Technical Memorandum 19 from January/March 2002, heavily edited for clarity and modern platform support).

Table of Contents

  1. Introduction
  2. Tutorial
  3. Commands
  4. Command Lists

Introduction

SysRes (System Response) is modeled after the original SysID program. In addition to conducting real-time, simultaneous response measurements, SysRes performs DPOAE (Distortion Product Otoacoustic Emissions) averaging in the style of CUBeDIS. Both SysID and CUBeDIS were originally developed by Jont Allen.

SysRes is highly portable, with native implementations across Windows, macOS, Linux, and legacy DOS environments. The current version of SysRes supports high-quality sound cards on Windows via ASIO/WASAPI, ALSA on Linux, and native CoreAudio aggregate devices on macOS.

SysRes is a highly versatile measurement tool. When properly configured, it can measure the response of virtually any system. It was specifically designed to record inner ear responses using Otoacoustic Emission (OAE) probe microphones, such as the Etymotic ER-10C.

Tutorial

SysRes is controlled via an interactive, command-driven interface. All user input is provided through keyboard commands. This tutorial offers a quick start guide for common commands, while the Commands section details the full application reference.

To launch SysRes on macOS or Linux, run ./sysres from the terminal. On Windows, simply double-click the executable. By default, SysRes starts with a standard set of configuration parameters.

Basic System Response (Loop-back)

The most fundamental application of SysRes is acquiring a basic system response. To understand how this works, we will first look at a loop-back configuration, where the sound card's output is directly connected to its input. In this setup, the measured response will mirror the output stimulus perfectly.

  1. Verify Hardware: Once your loop-back cable is connected, launch SysRes. You should verify that the sound card was correctly detected by typing di (Device Information). SysRes will display the active audio hardware and connection details on the screen.
  2. Compute Frequency Response: Next, type fn to compute a frequency response using a pseudo-random noise stimulus. You should see a perfectly flat, uniform frequency response graph, which confirms that the loop-back circuit is functioning properly.

Figure 1: Uniform Frequency Response

  1. View Time Response: You can also view the response in the time domain. Typing tr (Time Response) switches the graph to a time/magnitude axis. A loop-back response appears as a flat line containing a brief impulse or disturbance. We can zoom in on this disturbance for a closer look.

Figure 2: Time Domain Response

Controlling the View (Zooming)

Use the zoom time commands (zt1 and zt2) to isolate specific sections of the graph:

  1. Set Upper Limit: To view the first 3 milliseconds, set the upper time limit by typing zt2=0.003. The zoom mode (zo) is automatically enabled. Simply type tr again to redraw the zoomed graph.
  2. Set Lower Limit: To zoom in even closer, adjust the lower time limit by typing zt1=0.002 and redraw again.
  3. Reset View: To restore the original full-scale view, disable zoom by typing zo=0, and redraw the graph using tr.

While a loop-back test is useful for calibration and tutorials, the real power of SysRes comes from measuring physical acoustic environments using a microphone and speaker array, or an OAE probe microphone.

Exporting and Printing

To print or export the current graph, use the Printer commands.

  • Export to File: Type PN=output.prn to specify an output file name, which will save a PostScript or PCL image in your working directory.
  • Print Directly: On macOS and Linux, you can route the output directly to a system printer by prefixing the printer name with an exclamation point (e.g., PN=!lp).
  • Format: You can adjust the print orientation using PO=0 (Landscape) or PO=1 (Portrait), and specify the format using PT=0 (PostScript) or PT=1 (PCL).
  • Execute: Once configured, type PS to generate the printout or save the file.

Commands

SysRes relies on a concise, command-driven interface. To assign a new value to a parameter, type the command followed immediately by an equals sign (=) and the new value, without any spaces (e.g., na=100). Typing a command by itself (without an equals sign) will display its current value.

Configuration Commands

The configuration commands allow the user to configure and set values that affect the stimulus and response.

  • ad – Set analog-to-digital (A/D) mode (input) to a corresponding channel. [0=No input, 1=L 2=R 3=L&R 4=L/R 5=R/L]. Default is the Left channel (1).
  • da – Set digital-to-analog (D/A) mode (output) to a corresponding channel. [0=No output, 1=L 2=R 3=L&R 4=L/R 5=R/L]. Default is the Left channel (1).
  • dc – Control the DC component removal from the response. [0=keep 1=remove]
  • ia – Input attenuation from the microphone or probe (in dB). Default: 0.0 (dB)
  • na – Set the number of averages for the stimulus (range: 1 to 32000). Default is 20.
  • ns – Set the number of samples for the stimulus (range: 64 to 2^20). This must be a power of 2. Default is 1024.
  • oa – Output attenuation to the speaker or probe (in dB). Default is 0.
  • sk – Number of repetitions to skip prior to averaging.
  • sr – Set the sample rate to be used (in kHz). Default is 44 kHz.

Frequency Response Commands

These commands handle initializing stimulus response computation.

  • fc – Measure frequency response using the chirp stimulus.
  • fi – Measure frequency response using the impulse stimulus.
  • ft – Measure frequency response using the tone stimulus.
  • fp – Measure frequency response using the tone-pair stimulus.
  • fn – Measure frequency response using the pseudo-random noise stimulus.
  • fu – Measure frequency response using a user-defined stimulus by setting using an external file (e.g., fu=file.mat).
  • fr – Frequency response using the previously used stimulus. Default is the chirp stimulus.
  • nf – Measure noise floor (normalized to stimulus).
  • no – Normalize to a response that was previously saved in a file (e.g., no=filename).
  • sa – Measure spectral average by repeatedly measuring the system response.

Plot Commands

These commands manage the graphical plotting features.

  • cs – Clear screen; this clears the plotted data.
  • crn – Set the upper right-hand corner text string. "SysRes" is the default. When set to "$fn", the most recently read data file name will be displayed.
  • dr – Dynamic range. Sets the dB range on the graph (e.g., setting to 50 places the limits at 10 dB and -40 dB).
  • dm – Delay axis maximum (ms).
  • dn – Delay axis range (ms).
  • do – Delay offset removed (ms). Allows the user to fine-tune hardware synchronization by accounting for sound card delays.
  • eml – Extra message lines. Condenses the graph to allow more terminal message lines below it.
  • pl – Toggle frequency domain scale between logarithmic and linear.
  • pm – Set the upper bound (maximum) of the phase axis (cycles).
  • pn – Set the range and lower bound of the phase axis (cycles).
  • po – Phase offset removed (cycles).
  • pr – Plot response versus frequency. This will also immediately re-plot the current data against any changed graph settings.
  • ps – Plot stimulus versus frequency. Shows the stimulus behavior relative to the response on the same graph.
  • shd – Show delay mode toggle. Displays the delay graphed data when active.
  • shp – Show phase mode toggle. Displays the phase graphed data when active.
  • tr – Plot response versus time. Maps the frequency response data to time on the x-axis.
  • ts – Plot stimulus versus time.
  • td – Tick direction on the graph (0=inward, 1=outward).
  • te – Plot reverse-time-energy vs time for frequency response data.
  • vr – Voltage reference (dBV). Sets the upper value of the dB axis.
  • SR – SPL reference (dBSPL). Sets the upper value of the dB axis when in SPL mode.
  • zf1 / zf2 – Zoom frequency lower/upper bounds (Hz).
  • zt1 / zt2 – Zoom time lower/upper bounds (seconds).
  • zo – Zoom toggle (0=off, 1=on). Automatically enabled when bounds are set.

File Commands

  • lf – Log messages toggle. When enabled, a sysres.log file captures all terminal output.
  • ra – Read ASCII data file from the working directory (defaults to sysres.txt).
  • rc – Read configuration file (sysres.cfg).
  • rd – Read data file (MATLAB format, defaults to sysres.mat).
  • rl – Read a list of commands from a script file (.lst).
  • rs – Read a stimulus file (MATLAB format).
  • wa – Write ASCII data file (sysres.txt).
  • wc – Write configuration settings to sysres.cfg.
  • wd – Write data file in MATLAB format (sysres.mat).
  • wh – Write help reference to file (help.txt).
  • ws – Write stimulus file in MATLAB format.

Printer Commands

  • PL – Printer label text. Default is "$vn" (version number).
  • PN – Printer destination or file name (e.g., output.prn or !lp).
  • PO – Print orientation (0=Landscape, 1=Portrait).
  • PS – Execute the print screen action.
  • PT – Printer file type (0=PostScript, 1=PCL).

DPOAE Commands

These commands describe and control a DPOAE experiment.

  • avm – average weighting mode (0=uniform, 1=RMS, 2=MS)
  • ca – calibrate (specify buffer size)
  • cach – DP calibration channel (0 or 1)
  • ct – calibration tones (specify frequency in Hz)
  • cn – specify calibrate buffer size (samples)
  • dp – display distortion product (2*F1-F2) vs time
  • dpbw – DP envelope bandwidth (Hz)
  • dpch – DP analysis channel (0 or 1)
  • dpdp – display 3F1-2F2 component also (0=NO, 1=YES)
  • dpef – DP exponential fit type (0, 1 or 2)
  • dpen – DP envelope size (power of 2, 0=STFT)
  • dpfc – DP fit complex (0=NO, 1=YES)
  • dpft – DP filter type (0=24dB, 1=Blackman, 2=Gaussian)
  • dpno – set DP noise display (0=off, 1=on)
  • dpon – set DP order number [-1=2*F1-F2]
  • dpsb – DP noise sidebands (% of DP frequency)
  • dpst – Copy the DP stimulus to the response buffer, as if it were measured.
  • dptl – DP initial time-constant (sec) [0.1]
  • om – offset for DP envelope analysis (msec)
  • os – offset for DP envelope analysis (samples)
  • rjm – reject mode (0=none, 1=DPN)
  • rjn – maximum number of rejects
  • rjt – reject threshold (dB SPL)

Stimulus Commands

  • a1 / a2 / a3 – Attenuation of tone 1, 2, or 3 (dB).
  • bd – Beginning duration (msec). Specifies silence before stimulus onset.
  • dbms1 / dbms2 / dbms3 – Growth rate of tone 1, 2, or 3 (dB per msec) for stimulus with exponential ramps.
  • ed – End duration (msec). Specifies silence after stimulus termination.
  • f1 / f2 / f3 – Frequency of the first, second, or third tone (kHz).
  • od – Ramp onset duration (msec). Sets the duration of the amplitude envelope ramp.
  • rt – Ramp type (0=None, 1=Linear, 2=Cosine, 3=Blackman). Determines the windowing function applied to the stimulus.
  • st – Stimulus type: [0=chirp, 1=impulse, 2=zero, 3=tone, 4=tone pair 5=noise, 6=user defined, 7=masking]
  • vo – Volts (stimulus amplitude). Default is 1.

Masking Commands

These parameters describe the stimulus for a forward masking experiment.

  • ma1 – masker attenuation (dB)
  • ma2 – probe attenuation (dB)
  • mf1 – masker frequency (Hz)
  • mf2 – probe frequency (Hz)
  • mmd – masker duration (msec)
  • mmr – masker ramp time (msec)
  • mms – masker start time (msec)
  • mpd – probe duration (msec)
  • mpg – probe gap time (msec)
  • ms – initialize forward masking stimulus
  • mtd – timing pulse duration (msec)
  • mtv – timing pulse amplitude (volts)

Other Commands

  • be – Beep, plays a system sound.
  • bp – Band-pass filter (from F1 to F2)
  • cd – Get or set the current directory.
  • co – Comment. Inserts a line of text on the graph.
  • dbg – Debug mode. Displays automated commands as if they were typed.
  • di – Device information. Displays the current sound card hardware information and allows hardware toggling.
  • et – Elapsed time since program start (sec).
  • ga – Gap between stimulus repetitions (sec)
  • go – Average and show time-domain response
  • ls – List files in the current working directory.
  • sm – Sensitivity of microphone (V/Pa)
  • ow – Overwrite existing data files without prompting (0=no, 1=yes).
  • pa – Pause (e.g., pa=message).
  • pg – Pregap before I/O (sec)
  • q – Quit the application.
  • sl – Sleep for N seconds.
  • to – Time-out pause after N seconds.
  • vn – Display the version number.

Command Lists

SysRes supports a powerful scripting capability using "command list" files, which automate repetitive configurations, calculations, and frequency responses.

A command list file is a standard plain text file containing a .lst extension. Each command must reside on its own line. Comments can be inserted by starting a line with a semi-colon (;).

You can execute a command list immediately upon launching SysRes by providing the filename as an argument. For example, running ./sysres test.lst will bypass the interactive prompt and immediately execute the commands in test.lst. You can also execute a list during an active session by typing rl=test.lst.

Interactive Pauses

It is highly recommended to insert pause (pa) commands within your scripts. This temporarily halts execution, giving you time to analyze a plotted graph or save data before continuing. You can also display a custom message during the pause. For example, inserting pa=Record external data now into your script will halt the program and display that message until you resume.