Learn more about Communications Toolbox

Attaching a System to the Error Rate Test Console and Running Simulations

On this page…
Attaching a System to the Error Rate Test Console Defining Simulation Conditions Registering a Test Point Getting Test Information Running a simulation Getting Results and Plotting Data

Running simulations with the Error Rate Test Console involves the following tasks:

• Attaching a system

• Defining simulation conditions

  • Specifying stop criterion

  • Specifying iteration mode

  • Specifying reset mode

  • Specifying sweep values

• Registering test points

• Running simulations

• Getting results and plotting

Attaching a System to the Error Rate Test Console

You attach a system to the Error Rate Test Console to run simulations and obtain error rate data. There are two ways to attach a system to the Error Rate Test Console.

• To attach a system to the Error Rate Test Console, type the following at the MATLAB command line:

  attachSystem(testConsole, mySystem)

• To attach a system at construction time of an Error Rate Test Console, use the following:

  testconsole = commtest.ErrorRate(mySystem)

• mySystem is the name of the system under test

If system under test A is currently attached to the Error Rate Test Console H1, and you call attachSystem(H2,A), then A detaches from H1 and attaches to Error Rate Test Console H2. This throws a warning stating that the system has detached from H1 to be attached to H2.

Back to Top

Defining Simulation Conditions

Stop Criterion

The Error Rate Test Console controls the simulation stop criterion using the SimulationLimitOption property. You define the criterion to stop a simulation when reaching either a specific number of transmissions or a specific number of errors.

• Setting SimulationLimitOption property to 'Number of transmissions' stops the simulation for each sweep parameter point when the Error Rate Test Console counts the number of transmissions specified in MaxNumTransmissions

• Setting SimulationLimitOption property to 'Number of errors' stops the simulation for a sweep parameter point when the Error Rate Test Consols counts the number of errors specified in MinNumErrors. The ErrorCountTestPoint property should be set to the name of the registered test point containing the error count being compared to the MinNumErrors property to control the simulation length.

• Setting SimulationLimitOption property to 'Number of errors or transmissions' stops the simulation for each sweep parameter point when the Error Rate Test Console completes the number of transmissions specified in MaxNumTransmissions or when obtaining the number of errors specified in MinNumErrors, whichever happens first.

Iteration Mode

The iteration mode defines the way that the Error Rate Test Console combines test parameter sweep values to perform simulations. The IterationMode property of the test console controls this behavior.

• Setting IterationMode to 'Combinatorial' performs simulations for all possible combinations of registered test parameter sweep values.

• Setting IterationMode to 'Indexed' performs simulations for all indexed sweep value sets. The i^th sweep value set consists of the i^th element from every sweep value vector for each registered test parameter. All sweep value vectors must be of equal length, with the exception of those that are unit length.

Specifying and Obtaining Sweep Values

The Error Rate Test Console performs simulations for a set of sweep points, which consist of combinations of sweep values specified for each registered test parameter. The was the test console forms sweep points depends on the IterationMode settings. The iteration mode defines the way in which sweep values for different test parameters combine to produce simulation results.

Using the setTestParameterSweepValues method, you specify sweep values for each test parameter that the system under test registers to the Error Rate Test Console.

setTestParameterSweepValues(obj,name,value)

where

• obj represents handle to the Error Rate Test Console.

• name represents the name of the registered test parameter (this name must correspond to a test parameter registered by the system under test or an error occurs)

• value represents the sweep values you specify for the test parameter named ‘name'. Depending on the application, sweep values may be a vector with numeric values or a cell array of characters. The test console issues an error if you attempt to set sweep values that are out of the specified valid range for a test parameter (valid ranges are defined by the system when attaching to a test console).

You obtain the list of test parameters registered by the system under test using the info method of the Error Rate Test Console.

You obtain the sweep values for a specific registered test parameter using the getTestParameterSweepValues method of the Error Rate Test Console. You obtain the valid ranges of a specific registered test parameter using the getTestParameterValidRanges method of the Error Rate Test Console.

If you do not specify sweep values for a particular test parameter, the Error Rate Test Console. always uses the parameter's default value to run simulations. (Default values for test parameters are defined by the system when attaching to a test console at registration time.)

Reset Mode

You control the reset criteria for the system under test using the SystemResetMode property of the Error Rate Test Console.

• Setting SystemResetMode to 'Reset at new simulation point' resets the system under test resets at the beginning of iterations for a new simulation sweep point.

• Setting SystemResetMode to 'Reset at every iteration' resets the system under test at every simulation.

Back to Top

Registering a Test Point

You obtain error rate results at different points in the system under test, by defining unique test points. Each test point groups a pair of probes that the system under test uses to log data and the Error Rate Test Console uses to obtain data. In order to create a test point for a pair of probes, the probes must be registered to the Error Rate Test Console.

The Error Rate Test Console calculates error rates by comparing the data available in a pair of probes.

Test points hold error and transmission counts for each sweep point simulation.

The info method displays which test points are registered to the test console.

registerTestPoint(h, name , actprobe,expprobe) registers a new test point with name, name, to the error rate test console, h.

The test point must contain a pair of registered test probes actprobe and expprobe whose data will be compared to obtain error rate values. actprobe contains actual data, and ,expprobe contains expected data. Error rates will be calculated using a default error rate calculator function that simply performs one-to-one comparisons of the data vectors available in the probes.

registerTestPoint(h, name, actprobe,expprobe, handle) adds a handle, handle, that points to a user-defined error calculator function that will be used in stead of the default function to compare the data in probes actprobe and exprobe, to obtain error rate results.

Writing a user-defined error calculator function

A user-defined error calculator function must comply with the following syntax:

[ecnt tcnt] = functionName(act, exp, udata) where ecnt output corresponds to the error count, and TCNT output is the number of transmissions used to obtain the error count. Inputs act, and exp correspond to actual and expected data. The error rate test console will set these inputs to the data available in the pair of test point probes actprobe and expprobe previously mentioned. udata is a user data input that the system under test may pass to the test console at run time using the setUserData method. udata may contain data necessary to compute errors such as delays, data buffers, and so on. The error rate test console will pass the same user data logged by the system under test to the error calculator functions of all the registered test points.

You call the info method to see the names of the registered test points and the error rate calculator functions associated with them, and to see the names of the registered test probes.

Back to Top

Getting Test Information

Returns a report of the current test console settings.

info(h) displays:

• Test console name

• System under test name

• Available test inputs

• Registered test inputs

• Registered test parameters

• Registered test probes

• Registered test points

• Metric calculator functions

• Test metrics

Back to Top

Running a simulation

You run simulations by calling the run method of the Error Rate Test Console.

run(testConsole) runs a specified number of iterations of an attached system under test for a specified set of parameter values. If a Parallel Computing Toolbox license is available and a matlabpool is open, then the iterations will be distributed among the available number of workers.

Back to Top

Getting Results and Plotting Data

Call the getResults method of the error rate test console to obtain test results.

r = getResults(testConsole) returns the simulation results, r, for the test console, h. r is an object of type testconsole.Results and contains all the simulation data for all the registered test points.

You call the getData method of results.object r to get simulation results data. You call the plot and semilogy method of the results object r to plot results data. See testconsole.Results for more information.

Back to Top

Debug Mode

BERTool: A Bit Error Rate Analysis GUI

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS