Advent Instruments AI-7280 Manual

Central Office
Line Simulator
AI-7280
Programmers Guide
Direct Control
Advent Instruments Inc.
Release 2.0a

Copyright 2012 - Advent Instruments Inc. All rights reserved.
Printed in Canada
Advent Instruments Inc.
111 - 1515 Broadway Street
Port Coquitlam, BC, V3C6M2
Canada
Internet: [email protected]
[email protected]
Web Site: http://www.adventinstruments.com
Telephone: [phone]
Fax: [phone]

Advent Instruments Inc.
Contents
1. Getting Started 1
1.1 Introduction 1
1.2 Firmware Overview 2
1.3 Communication Basics 4
1.3.1 Serial RS-232 Port 5
1.3.2 USB Port 5
2. Command Reference 7
2.1 Overview 7
2.2 Get & Set Commands 7
2.3 Program Control Commands 10
Clear Program Memory: PC 10
Load Program: PL"(program text)" 10
Start Program from RAM: PS(n)M 11
Start Program from Flash: PS(n)F(file#) 11
Halt Program Execution: PH(n) 11
Resume Program Execution: PR(n) 11
Stop Program Execution: PX(n) 11
Single Step: PT(n) 12
Set Program Load Address: PA(offset) 12
3. HAL Properties 13
3.1 Overview 13
3.2 ACCAP Properties 14
3.3 BULK Properties 17
3.4 COMM Properties 19
3.5 DATA Properties 21
3.6 DCCAP Properties 25
3.7 DCPROFILE Properties 27
3.8 DIO Properties 29
3.9 DTMF Properties 30
3.10 DTMFCAP Properties 32
3.11 ECHO Properties 34
3.12 FILE Properties 35
3.13 FILTER Properties 37
3.14 FSK Properties 39
3.15 FSKDROP Properties 41
3.16 MEASURE Properties 42
3.17 METERPULSE Properties 44
3.18 MFGEN Properties 46
3.19 NOISE Properties 49
3.20 RING Properties 50
3.21 SCHEDULER Properties 52
3.22 SIGNALIO Properties 54
3.23 SOURCE Properties 54
3.24 STATUS Properties 56
AI-7280 Programmers Guide - Direct Control i

Advent Instruments Inc.
3.25 SYSTEM Properties 57
3.26 TELINT Properties 61
3.27 TIMER Properties 64
3.28 TONE Properties 66
3.29 TONEA Properties 67
3.30 TONEB Properties 71
3.31 TONEC Properties 72
3.32 TONED Properties 73
3.33 USB Properties 74
4. Programming 77
4.1 Overview 77
Capabilities 77
Program Development 78
4.2 Programming Example 78
What is TRsSim 79
Creating a Device Script Project 79
Direct Program Loading 84
4.3 Script Language Basics 85
Process Blocks 85
Function & Subroutine Blocks 86
Variables & Constants 87
Statements 89
Built in Routines and Properties 92
Appendix A: Firmware Revisions 97
Appendix B: Property Listing by Index 99
Appendix C: Error Codes 104
Appendix D: Support 107
Glossary of Terms 109
ii AI-7280 Programmers Guide - Direct Control

Advent Instruments Inc. 1. Getting Started
1. Getting Started
1.1 Introduction
The AI-7280 can be controlled from any device that provides a RS-232 serial port. By
sending simple ASCII character commands, all of the low level functionality of the AI-
7280 is accessible. While using this method of control provides the most flexibility, it is
generally more complex than using the provided Win32 DLL or .NET Assembly. Both
provide a layer of abstraction that simplifies many tasks. However for applications where
the DLL or .NET assembly cannot be used (non-Windows PC), or where the DLL or
.NET assembly cannot perform the specific task, this form of communication and control
may be the best option.
It is possible to use the AI-7280's USB port for direct control; however, the correct USB
drivers are required for this functionality. Currently drivers are available for Windows,
Linux, and Apple OS-X operating systems. Please contact technical support for more
information on USB driver availability if you wish to use the USB port.
This document provides technical information on how the AI-7280 is controlled directly
from the RS-232 serial port or USB port. It divided into the following sections, each
describing a specific aspect of controlling the AI-7280.
• Section 1. Getting Started
Provides a general overview of the AI-7280's firmware structure and
communication basics.
• Section 2. Command Reference
Describes the structure and function of the basic AI-7280 commands.
• Section 3. HAL Properties
Provides reference information on the operation and function of all the hardware
abstraction layer properties.
• Section
AI-7280 Programmers Guide - Direct Control 1

1. Getting Started Advent Instruments Inc.
4. Programming
Provides an overview and example of how programs are developed, along with
basic information on the scripting language constructs.
1.2 Firmware Overview
At its most basic level, the AI-7280 firmware can be broken down into three logical
elements. They are the command processor, program execution units, and the hardware
abstraction layer. While overly simplistic, the following figure shows the structure of
those logical elements.
Command Processor
Hardware Abstraction Layer
Program
Execution
Units
Starting from the bottom of the figure is the Hardware Abstraction Layer (HAL). This is
simply a layer of software that controls all hardware related aspects of the AI-7280. The
AI-7280 functionality is represented by over 200 properties. These properties are
organized into groups of similar function. The groups control various settings, such as
the ringing generator, tone generators, level meters, FSK modulator, FSK generator,
DTMF detector, and others.
From a programming point of view, each property can be viewed as a variable or register.
For example, to change the frequency of the ringing generator, a command is sent to
write a value into the "Ring.Freq" property. By writing a value into a property register,
the underlying hardware is immediately changed. The syntax used to define the various
properties is as follows:
(group name) . (property name)
Some examples include:
Ring.Freq (controls ring generator frequency)
TelInt.Voltage (telephone interface line voltage)
ToneA.Level (output level of tone generator A)
Measure.Level (returns output of RMS level meter)
While most of the properties can be both written to and read from, some may be read-
only, or write-only. For example, the Measure.Level property is a read-only property
that cannot be written to.
2 AI-7280 Programmers Guide - Direct Control

Advent Instruments Inc. 1. Getting Started
The vast majority of the properties are of a numeric data type. This means that only
numbers can be written, or read from that property. However, some of the properties are
string types. This means that ASCII character strings may be written, or read from them.
Since all aspects of the AI-7280 are determined by the HAL property values, controlling
the AI-7280 is reduced to simply reading and writing to the various properties.
There are two ways in which the property values can be manipulated. They are:
• Commands received from the RS-232 serial port, or USB port, or
• Statements executed by the program execution units.
The Command Processor block, shown in the previous figure, is responsible for
interpreting characters received from either the RS-232 or USB ports. It simply waits for
complete command strings to arrive from the controlling device, and then processes the
command. It will either execute the desired command, or if a syntax error is detected,
return an error message. The command processor operates in a strict master slave
relationship with the controlling device. It acts as the slave and returns data only in
response to a command.
The two commands used to access the HAL properties are set and get commands. The
set command writes a value into any HAL property, while the get command returns the
value stored in the HAL property.
In addition to set and get are other commands used to control the program execution
units. The AI-7280 contains a number of virtual processors that can be programmed for a
wide variety of tasks. These are the program execution units shown in the previous
figure. The program execution units allow the AI-7280 to operate in a semi-autonomous
manner. Programs running on the AI-7280 can perform various low-level timing critical
tasks, while the PC (or other controlling device) performs the supervisory tasks. These
programs may be stored in the AI-7280's non-volatile flash memory, or downloaded into
the volatile RAM.
To aid in writing AI-7280 programs, the TRsSim software provides a simplified high-
level language compiler. This software converts high-level language statements into
object code executed by the AI-7280. An example of such a program is as follows:
Loop
If TelInt.HookDetect = 1 Then
Exit Loop
End If
End Loop
Let ToneA.Freq = 440
Let ToneB.Freq = 350
Let ToneA.Level = 0.500
Let ToneB.Level = 0.500
Let ToneA.Enable = 1
Let ToneA.Enable = 1
The above program waits until a connected telephone device goes off-hook. Once this
occurs, it enables tone generators A and B to produce the standard North American dial
tone (440 & 350 Hz) at a level of 0.5 Vrms (open circuit).
This program can be compiled by the TRsSim software and stored in the AI-7280's flash
memory. When needed, the PC (or other controlling device), can simply execute this
program with one of the AI-7280's program execution units.
AI-7280 Programmers Guide - Direct Control 3

1. Getting Started Advent Instruments Inc.
1.3 Communication Basics
All commands sent to and received from the AI-7280 use ASCII characters. A command
is simply a series of ASCII characters followed by the <CR> character (ASCII 13). The
<CR> character marks the end of the command. The AI-7280 only processes the
command once the <CR> character is received. Optionally, a <LF> character (ASCII 10)
may follow the <CR> character; however it is ignored and has no effect on the command.
For every command sent, the AI-7280 responds with either an acknowledgement, error
code, or the requested data. Because ASCII characters are used for the commands, any
terminal program (for example. Windows HyperTerminal) may be used to send
commands. The AI-7280 does not echo any sent characters so a local echo must be
enabled to see the commands in a terminal program's window. In addition, all responses
sent by the AI-7280 are terminated with only a <CR> character. Not a <CR> <LF>
combination.
Some command examples that can be sent from a terminal program are shown below.
Note, commands are represented by bold face text and must be followed by the <CR>
character. The expected response is shown in the line underneath the command.
Terminal program settings should be 9600 baud, 8 data bits, 1 stop bit, with no flow
control.
1. Get the software version string:
?HS2
"AI-7280 Software Version [2.12](1)"
2. Enable the ringing generator:
>HN111=1
OK
3. Turn off the ringing generator:
>HN111=0
OK
4. Measure and return the DC voltage on the telephone line:
?HN71
-4.81737e1
More detailed information on the command syntax is provided in section 2. Command
Reference.
Note: It is important to limit the length of any commands to less than 128 characters.
This is because the AI-7280 must buffer all of the command characters prior to the <CR>
character. The size of the buffer is fixed and this requires that all commands are less than
128 characters in length (including the <CR> character).
Note: AI-7280 commands are case sensitive. All commands use upper case characters
exclusively.
4 AI-7280 Programmers Guide - Direct Control

Advent Instruments Inc. 1. Getting Started
1.3.1 Serial RS-232 Port
The AI-7280 serial port operates at one of the following baud rates: 9600, 19200, 38400,
57600, and 115200. The serial format is fixed at 8 data bits, 1 stop bit, and no parity.
Flow control is not used (either hardware or software).
Upon a power up or reset, the baud rate is set to 9600 bps. It may be changed to one of
the other supported baud rates by writing to the HAL property (Comm.Baud).
If the AI-7280 detects a line break (at least 11 consecutive space bits), it resets the baud
rate back to the default value of 9600 bps and flushes any unprocessed commands from
its internal buffer. When attempting to communicate with the AI-7280 for the first time,
it is good practice to first send a line break, which ensures the baud rate is set to 9600
baud. Once communication is established, the baud rate may be set higher in order to
improve throughput.
The rear panel 9 pin RS-232 connector is configured as a DCE (Data Communications
Equipment) port. As such, no cross over cable is required when making a connection to a
standard PC serial port. A minimum of three wires are required to make a serial
connection. They are TX Data (pin 2), RX Data (pin 3), and Ground (pin 5). The AI-
7280 can monitor the PC's RTS (pin 7) signal and control the state of the CTS (pin 8)
signal, but does not use them to communicate. The DSR (pin 6) and DTR (pin 4)
connections are internally tied together. Pins (1 and 9) have no internal connection.
Upon power up or a hardware reset, the AI-7280 outputs the following characters from
the RS-232 serial port at 9600 baud.
ABL1<CR>
GO<CR>
They are generated by an internal boot loader program which loads the main firmware
program of the AI-7280. Following these characters, the AI-7280 is ready to accept
commands.
1.3.2 USB Port
The USB port may be used to communicate with the AI-7280 in the same manner as the
RS-232 port. The command structure and syntax is identical. However in order to use
the USB port, a suitable driver must be installed on the host PC. A Windows XP, Vista,
7 USB driver installation package is available at:
http://www.adventinstruments.com/Products/AI-7280/Downloads
Note: The USB drivers are automatically installed if the TRsSim software has been
installed on the PC (version 3.0 and higher).
To determine if drivers are available for other operating systems, please contact technical
support.
AI-7280 Programmers Guide - Direct Control 5

Advent Instruments Inc. 2. Command Reference
2. Command Reference
2.1 Overview
The AI-7280 supports two main classes of commands. They are:
• Get & Set Data
• Program Management
The get and set commands are used to write to or read from any of the Hardware
Abstraction Layer (HAL) properties. They are the most important commands in
controlling the AI-7280 settings and reading its measurements. In addition to accessing
the HAL properties, the commands can access the variable memory space used by the
program execution units, or registers internal to the execution units. For details on the
use of these commands see the following section: 2.2 Get & Set Commands.
The second class of commands deals with program management and control the program
execution units. Programs can be stored and executed from the non-volatile flash
memory, or downloaded into RAM and executed. Commands are provided to start, halt,
resume, and stop the program execution units. See section: 2.3 Program Control
Commands for more detailed information.
It is important to note that the same command structure is used for both the RS-232 port
and the USB port. There is no difference in syntax when using either communication
method.
2.2 Get & Set Commands
From a programming point of view, the AI-7280 can be represented as a large collection
of registers. Some of these registers control various hardware settings (like the HAL
properties), while others access variable memory used by executing programs or registers
controlling the state of program execution. In order to control the AI-7280, the set and
get commands are used to write to and read from many different registers.
The syntax of the get and set commands are:
?(reg) Get register contents
>(reg)=(data) Set register contents
Where "(reg)" represents the register to access, and "(data)" represents the value to set the
register to.
Registers contain data of either a numeric or character string type. In addition, registers
are grouped into three different classes. They are HAL properties, program variable
AI-7280 Programmers Guide - Direct Control 7

2. Command Reference Advent Instruments Inc.
memory, and program execution control & status. As such, registers are defined by their
class, data type, and an ID number.
(reg) <class> <data type> <ID number>
Where:
<class> 'H' for HAL properties
'G' for program variable registers
'V' for program control & status registers
<data type> 'N' for numeric values
'S' for strings
<ID number> Integer value representing specific register
Some examples of registers are:
HN112 Numeric HAL property representing the frequency of the
ringing generator.
HS2 String HAL property representing the software version string
of the AI-7280 firmware.
VN103 Numeric status register for the first program execution unit.
In order to read these registers, get command '?' precedes the register. For example,
sending the following commands reads the registers listed above.
?HN112
2.2e1
?HS2
"AI-7280 Software Version [2.12](1)"
?VN103
0
Note that each command must be terminated with a <CR> character (0Dh) before it is
processed by the AI-7280. In addition, the data returned by the AI-7280 is always
terminated with only a <CR> character.
In each of the get commands used above, the AI-7280 reads the contents of the register
and returns its value. Reading "HN112" returns the frequency of the ringing generator,
which by default is 22 Hz. Register "HS2" returns a string representing the firmware
version, and "VN103" returns a value representing the program execution status
(0=stopped, 1=running, 2=halted).
If the data type of the register being read is numeric, then the value is returned in
scientific notation. Lower case 'e' delimits the mantissa portion from the exponent. In
addition, the period '.' character is always used as the decimal symbol.
For string data types, the returned characters are enclosed in double quotation marks.
Multiple commands can be combined on the same command line. For example, the
following command reads the registers for ringing frequency, level, and DC offset
voltage simultaneously.
8 AI-7280 Programmers Guide - Direct Control

Advent Instruments Inc. 2. Command Reference
?HN112:?HN113:?HN116
2.2e1:6e1:4.8e1
Multiple commands are delimited by using the colon ':' character. In the response, the
value of each register is also delimited by the colon character. In the example above, the
ringing frequency is currently set at 22 Hz, ringing AC level at 60 Vrms, and ringing DC
offset level at 48 Volts.
Writing data to registers requires using the set command. For example, to set the ringing
frequency to 68.5 Hz, send the following command:
>HN112=68.5
OK
The AI-7280 responds with 'OK' to each valid set command. If multiple set commands
are chained together, each one returns an 'OK' response. For example,
>HN112=22:>HN113=40
OK:OK
It is important to observe the following rules when using the set command:
• No space characters can be inserted between the register 'HN112', the equal sign
'=', or the value passed '22', otherwise an error message will be returned.
• If setting a numeric value, the format for the data must be as follows:
[-]n[.n] Where 'n' is one or more digits 0 to 9
Examples of valid numeric values are:
1
3.1415926
-314.159
0.000833
Examples of invalid numeric values are:
3,1415926
-3.14159e2
.000833
• If setting a character string value, it must be enclosed in double quotation marks.
To include quotation marks within the string, send two quotation marks.
For example, to set the variable register 'GS1' to:
He said "never", and left the room.
Send the following command:
>GS1="He said ""never"", and left the room."
If the AI-7280 cannot correctly interpret a command, its response is in the format of:
'ERR=x', where 'x' is an integer value representing the error condition. For a listing of all
command error codes, see: Appendix C: Error Codes
AI-7280 Programmers Guide - Direct Control 9

2. Command Reference Advent Instruments Inc.
In order to properly use the get and set data commands, it is important to understand the
purpose of each of the AI-7280's registers. A summary of all HAL properties is listed in
Appendix B: Property Listing by Index, while section 3. HAL Properties provides
detailed information for each property.
2.3 Program Control Commands
An important feature of the AI-7280 is its ability to execute simple programs. These
programs can be used to off load low level tasks from the PC or other controlling device.
Up to six independent program execution units (PEU) can be operating at any one time.
Each PEU can run a separate program, or a program can be constructed from multiple
processes, which each PEU running a process.
The following commands are used to control the PEUs. If the AI-7280 correctly
interprets the command, it returns the characters 'OK' in response. However, if an error is
detected it returns the character string 'ERR=x', where 'x' represents an error code. See
Appendix C: Error Codes for a listing of the possible error codes and their meaning.
Clear Program Memory: PC
This command clears the RAM program memory. Programs may be stored and executed
out of the internal non-volatile flash memory, or the RAM. If using the RAM to load and
execute programs, send the 'PC' command before loading a program with the 'PL'
command.
Example:
PC
OK
Load Program: PL"(program text)"
Loads a program into the AI-7280's RAM. All programs generated by the TRsSim
compiler are composed of printable ASCII characters, which must be enclosed in
quotation marks when using this command. As the maximum length of any command
must not exceed 128 characters, programs exceeding 123 characters should be broken up
into multiple text strings. Each text string can be loaded in succession by using the 'PL'
command. The maximum program size that can be loaded into the RAM is 16384
characters.
Example: this program enables the ringing generator for 2 seconds.
PL"TIN1HN111WIN2000TIN0HN111"
OK
Note: If the program text contains quotation marks, they must be duplicated before using
the PL command.
Example: load the program: TIS"hello"GS1
10 AI-7280 Programmers Guide - Direct Control

Advent Instruments Inc. 2. Command Reference
PL"TIS""hello""GS1"
OK
Start Program from RAM: PS(n)M
Starts executing the program loaded into RAM. The value (n) must be between 1 and 6
and specifies which program execution unit (PEU) is used to execute the program. The
AI-7280 can run up to 6 programs or processes at the same time.
Example: Start PEU #1 running a program loaded into RAM
PS1M
OK
Start Program from Flash: PS(n)F(file#)
Starts program execution from a file stored in the flash memory. The file to execute is
identified by the integer (file#) parameter. As with the run from memory command, the
value (n) specifies which PEU is used (valid range is from 1 to 6). Program files are
loaded into the flash memory by using the TRsSim software.
Example: Run program #2 stored in the flash memory on PEU #1
PS1F2
OK
Halt Program Execution: PH(n)
This command halts program execution for the specified PEU. The value (n) specifies
which the PEU to halt. If the value zero is passed for (n), then all PEUs are halted. To
resume execution, use the program resume 'PR' command.
Example: Halt PEU #4
PH4
OK
Resume Program Execution: PR(n)
Resumes program execution. The value (n) specifies the PEU to resume. If the value
zero is passed for (n), then all halted PEUs resume program execution.
Example: Resume PEU #4
PR4
OK
Stop Program Execution: PX(n)
Stops program execution. The value (n) specifies the PEU to stop. If the value zero is
passed for (n), then all PEUs are stopped. Once a program is stopped, it cannot be
resumed. Rather is must be started from the beginning again using the 'PS' command.
Example: Stop all programs
AI-7280 Programmers Guide - Direct Control 11

2. Command Reference Advent Instruments Inc.
PX0
OK
Single Step: PT(n)
Single step program execution. The value (n) specifies the PEU to execute a single
instruction. If the value zero is passed for (n), then all PEUs are single stepped. Only
PEUs that have been halted can be single stepped. PEUs that are running or stopped will
ignore this command.
Example: Execute a single instruction for PEU #1
PT1
OK
Set Program Load Address: PA(offset)
This command specifies a memory offset when loading programs into RAM with the 'PL'
command. In situations where more than one program is to be loaded into the RAM, this
command sets where additional programs are stored. The (offset) value must range from
0 to 4095 and specifies the number of 32 bit words used to offset the program memory.
Example: Load and run two programs in memory. The first program has a length of just
under 200 characters.
PC
OK
PL"(program #1 text - first 100 characters)"
OK
PL"(program #1 text - next 100 characters)"
OK
PS1M
OK
PA50
OK
PL"(program #2 text - max. 123 characters at a time)"
OK
PS2M
OK
Use caution with the 'PA' command, since if used improperly it can cause programs to be
overwritten in memory.
Note: While not shown in the examples above, every command sent to the AI-7280 must
be terminated with the <CR> character (0Dh), and optionally may be followed by the
<LF> character (0Ah). The <CR> character (0Dh) terminates every response returned by
the AI-7280.
12 AI-7280 Programmers Guide - Direct Control

Advent Instruments Inc. 3. HAL Properties
3. HAL Properties
3.1 Overview
The Hardware Abstraction Layer (HAL) properties represent a collection of registers that
control all of the signal processing and hardware aspects of the AI-7280. By writing to or
reading from various properties, the AI-7280 can be configured to perform a wide variety
of tasks.
Each property is identified by a unique ID number and name. The ID number is required
when accessing a property with the set '>' or get '?' command, while the name is used
when accessing a property from within the TRsSim programming environment.
The HAL properties are organized in groups based on their function. The following table
lists all of the groups with a brief description of their purpose. More detailed information
on each of the properties is provided in the following sections.
Tone & Signal Generation Groups:
TONEA Controls the generation of either a single frequency tone, FSK modulated
signal, or AM modulated signal.
TONEB Controls the generation of a single frequency tone, or can supply the
modulation source if ToneA is set to AM mode.
TONEC Controls the generation of a single frequency tone.
TONED Controls the generation of a single frequency tone.
MFGEN Simplifies generating DTMF or MF tones by providing access to a
programmable tone table that specifies frequencies, levels, and timing for
up to 20 different tones.
NOISE Controls a broadband white noise generator.
DATA Collection of properties used in defining a bit stream used by the FSK
modulator.
FSKDROP Controls the signal level during FSK modulation.
Telephone Line Interface Groups:
TELINT Sets the telephone interface settings such a line voltage and loop current
among others.
RING Controls the ringing generator frequency, level, DC offset, and wave
shape.
METERPULSE Controls the metering pulse tone generator.
ECHO Determines the level and delay of any simulated echoes for signals sent to
the telephone interface.
DCPROFILE Generates a user defined DC line voltage profile.
Signal Analysis & Measurement:
MEASURE Collection of properties that return various measurements such as signal
level, frequency, DC line voltage, and DC loop current.
FILTER Controls the settings of optional filters applied before level and frequency
measurements.
DTMF Controls a DTMF level meter and frequency counter.
DTMFCAP Collection of properties used to detect and capture DTMF digits.
AI-7280 Programmers Guide - Direct Control 13

3. HAL Properties Advent Instruments Inc.
FSK Controls the FSK demodulator, which decodes a FSK signal into a stream
of byte values.
SOURCE Determines the signal source for measurement meters, DTMF detector,
FSK decoder, and BNC output connector.
Waveform Capture & Playback & Transfer:
ACCAP Controls the capture and playback of AC signals.
DCCAP Controls the capture of DC line voltage and loop current measurements.
BULK Collection of properties that simplify the transfer of AC or DC waveform
data to and from the PC.
System Related Functions:
SYSTEM Collection of properties controlling system related functions.
COMM Controls the RS-232 serial port settings.
USB Controls the USB port settings.
DIO Determines the function of the rear panel digital Input/Output connector.
FILE Collection of properties used to access files stored in the flash memory.
TIMER Collection of properties that represent various timers used in the system.
SIGNALIO Sets the gain of any signals routed to the BNC output connector.
STATUS Properties returning status information on various AI-7280 activities.
SCHEDULER Method to perform various operations at a predetermined future time.
Each property is of either a numeric or string data type. If a numeric property then its
value can represent any single precision floating point value. Otherwise as a string
property, its value is represented by a string of characters. For the string data types, the
maximum length supported is 64 characters. The null character (0h) is used internally to
mark the end of a string. As such, null (0h) cannot be used within a character string.
All of the properties in the following sections are listed in alphabetical order. For a listed
by ID number, see: Appendix B: Property Listing by Index
Note: The property descriptions that follow assume an AI-7280 firmware version of at
least 4.14. If an earlier version is used, some of the following properties may not be
available. It is recommended that the AI-7280 be upgraded to the latest firmware
version. A software package to update the firmware is available on the
www.adventinsturments.com web site.
3.2 ACCAP Properties
These properties are used to capture AC signals and optionally play them back. Up to
229376 samples can be collected at either the full sample rate (39062.5 samples/s) or at
the half sample rate (19531.25 samples/s) depending on the MODE property value. In
either case, the samples are stored as 16 bits values representing a maximum range of +/-
10V. The samples are stored in an internal memory buffer with the INDEX property
pointing to where in the buffer the next sample is to be stored. The signal source for the
capture is determined by the SOURCE.ANALYZER property.
Samples stored in the buffer may be played back by using the PLAYINDEX and
PLAYCOUNT properties. The MODE property affects the playback sample rate as well
as the capture rate. If half rate playback is selected, then cubic interpolation is performed
in order to up sample to the full system sample rate. The playback samples are summed
14 AI-7280 Programmers Guide - Direct Control

Advent Instruments Inc. 3. HAL Properties
in with the current tone and noise generators. By using the SAMPLE property, the
captured samples may be read from the buffer or written into the buffer.
Note that a two sample delay is incurred for playback. For example, if playing 10
samples, the first two (at full rate) will be zero, followed by 8 samples stored in the
capture buffer. When the playback stops, the last two samples are still stored in an
internal buffer and not sent to the DAC. If playback is started with another 10 samples,
the two remaining samples stored in the buffer are cleared.
Name:
ACCAP.COUNT
ID:
185
Type:
Numeric
Description:
Sets the number of samples to capture. For example, setting this property to 10 captures
10 samples. As the samples are collected this property counts down to zero. Once at
zero it stops the sampling process. As each sample is recorded the INDEX property
increments. To stop a capture in progress, write the value 0 to this property. If the value
-1 is written, the capture continues indefinitely.
Name:
ACCAP.INDEX
ID:
184
Type:
Numeric
Description:
Sets the position in the capture buffer where the next recorded sample is to be stored. As
samples are collected, this property automatically increments by 1 for each sample. It
also automatically rolls over to zero once the RECLOOPEND property value is
exceeded. The maximum index value is 229375.
Name:
ACCAP.MODE
ID:
183
Type:
Numeric
Description:
Determines the capture and playback mode:
0 = capture and playback at full rate (39062.5 sampler/s) at 16 bits/sample
1 = capture and playback at half rate (19531.25 samples/s) at 16 bits/sample
Name:
ACCAP.PLAYCOUNT
ID:
189
Type:
Numeric
Description:
Sets the number of samples to playback. Writing a value greater than zero starts
playback of the specified number of samples. The first sample is taken from the position
in the buffer determined by PLAYINDEX. As each sample is output, this property
decrements by one until it reaches zero. Once it reaches zero, playback stops. To stop a
playback in progress, write the value 0. If a value if -1 is written, then playback
continues indefinitely.
Note that a two sample delay is incurred when playback is started.
AI-7280 Programmers Guide - Direct Control 15

3. HAL Properties Advent Instruments Inc.
Name:
ACCAP.PLAYGAIN
ID:
214
Type:
Numeric
Description:
Sets the gain applied to the waveform playback. The default value is 1.0. Using negative
values result in a polarity inversion.
Name:
ACCAP.PLAYINDEX
ID:
188
Type:
Numeric
Description:
Sets or returns the position within the capture buffer where the next playback sample is
read from. As samples are played back, this value automatically increments by 1. When
it becomes greater than PLAYLOOPEND this property is reset to the value stored in
PLAYLOOPSTART.
Name:
ACCAP.PLAYLOOPEND
ID:
213
Type:
Numeric
Description:
Sets the end position of a range of samples for playback. Once PLAYINDEX is greater
than this value, PLAYINDEX is set to the PLAYLOOPSTART value. By default,
PLAYLOOPEND is set to the maximum number of samples allowed in the buffer
(229375).
Name:
ACCAP.PLAYLOOPSTART
ID:
212
Type:
Numeric
Description:
Sets the start position of a range of samples for playback. When PLAYINDEX becomes
greater than PLAYLOOPEND, then PLAYINDEX is set to this value. By default,
PLAYLOOPSTART is set to zero.
Name:
ACCAP.RECLOOPEND
ID:
213
Type:
Numeric
Description:
Sets the end position for a range of captured samples. When recording, if INDEX
exceeds RECLOOPEND, then INDEX is set to 0. The default value is 229375.
Name:
ACCAP.SAMPLE
ID:
187
Type:
Numeric
Description:
Reading this property returns the sample value pointed to by the SAMPLEINDEX
property. Writing to this property sets the value pointed to by the SAMPLEINDEX
property. Either reading or writing to this property causes the SAMPLEINDEX property
to increment by 1.
16 AI-7280 Programmers Guide - Direct Control