Package Contents
----------------

Please see LICENSE.TXT for software license.

Executables ('bin' directory):
    fr.exe                  GSM FR codec
    amr_vad1.exe            GSM AMR codec with VAD1 option
    amr_vad2.exe            GSM AMR codec with VAD2 option
    testlab.exe             CONTROL and CHANNEL blocks w/ socket IPC
    testsim_demo.exe        All blocks in 'simulator' ('demo' IVS and PSAP)
    testsim_filio.exe       All blocks in 'simulator' ('fileio' IVS and PSAP)
    modem_demo.exe          'demo' IVS and PSAP
    modem_fileio.exe        'fileio' IVS and PSAP

C source ('c' directory):
    All source code required to build the executables (except the codecs) can
    be found here. Makefiles are provided for NMAKE.

    To build the testlab and 'demo' modems from source with NMAKE (from within
    cmd.exe, which assumes you have run vcvars32.bat or equivalent) run

        nmake

    To build the testlab together with the eCall modem run

        nmake /f makefile_ecall

Matlab source ('ml' directory):
    tchReadFrame.m          Matlab function to read encoded frames
    tchWriteFrame.m         Matlab function to write encoded frames
    tchFrameParam.m         Parameter tables for encoded frames
    tchParam.m              Parameter tables for GSM traffic channels
    tchPatternStats.m       Measure FER/BER on error patterns
    genCampaign.m           Generate 'script' files for the CONTROL block

Error patterns (*.if1 files in the 'bin' directory):
    The final 24 error patterns can be found here (from SA4 June 2008).

    Pattern Name            fer     rber1   rber2   clean
    amr-12_2-ci7.if1        7.68%   3.34%    NaN    0
    amr-4_75-ci1.if1        7.35%   2.08%    NaN    0
    amr-10_2-ci7.if1        6.71%   1.57%    NaN    0
    fr-na-ci7.if1           6.37%   1.46%   8.93%   0
    amr-5_9-ci4.if1         3.99%   1.19%    NaN    0
    amr-5_15-ci4.if1        2.76%   0.80%    NaN    0
    amr-12_2-ci10.if1       1.57%   1.25%    NaN    0
    amr-4_75-ci4.if1        1.53%   0.44%    NaN    0
    fr-na-ci10.if1          1.38%   0.32%   6.05%   0
    amr-7_4-ci7.if1         1.28%   0.36%    NaN    0
    amr-7_95-ci7.if1        1.11%   0.46%    NaN    0
    amr-10_2-ci10.if1       0.56%   0.18%    NaN    0
    amr-6_7-ci7.if1         0.46%   0.29%    NaN    0
    fr-na-rssi100.if1       0.38%   0.10%   4.56%   0
    amr-5_9-ci7.if1         0.23%   0.08%    NaN    0
    amr-5_15-ci7.if1        0.14%   0.05%    NaN    0
    amr-12_2-ci13.if1       0.11%   0.22%    NaN    0
    amr-4_75-ci7.if1        0.07%   0.03%    NaN    0
    fr-na-ci13.if1          0.07%   0.04%   3.11%   0
    amr-7_95-ci10.if1       0.05%   0.04%    NaN    0
    amr-7_4-ci10.if1        0.04%   0.03%    NaN    0
    amr-10_2-ci13.if1       0.03%   0.04%    NaN    0
    fr-na-ci16.if1          0.01%   0.01%   1.48%   0
    amr-4_75-rssi100.if1    0.00%   0.00%    NaN    0

    Error free cases don't require pattern files.


Getting Started
---------------

The best way to learn about how testlab works is to play with the demos and
examine the source code. To aid this, a couple of batch files have been
provided (in the 'bin' directory) that will run the test system right out of
the box.

Try running

    demosim.bat

This will by default run all test cases from campaign_short.txt on the 'demo'
IVS and PSAP and save the test results in results.txt. The 'sim' refers to the
fact that all modules are compiled into a single EXE for simple testing (using
ipc_sim.c). Next try using campaign_demo.txt to run the modems over a channel
in 'bypass' mode.

Then try

    demosock.bat

This will do the same, but instead 5 separate processes will be launched on
your machine and all IPC will be done via sockets (using ipc_sock.c). If you
want to try splitting the blocks across different machines, you can do the
following:

On the first machine (assuming it is named 'test-host') run:

    demosock.bat campaign_demo.txt control test-host

On the second machine run:

    demosock.bat campaign_demo.txt modems test-host

The 'demo' modem does not do any signal processing. It simply sends the MSD
data in the first couple of PCM samples of each frame. For this to work, the
CHANNEL block has to be configured in 'bypass' mode. You can see this in
campaign_demo.txt.

The other campaign files use the various codecs and modes and apply the error
patterns. None of those test cases will pass with the 'demo' modems. You can
see this as the column of 'F' in results.txt after running the tests.

For full details on the campaign file format, see genCampaign.m.


Implementing Candidate IVS and PSAP Modems
------------------------------------------

The only interface that needs to be understood in detail to implement your
candidate modems is found in 'modem.h'. The functions contained therein are
used to hook the IPC framework into your implementation. Examine modem_demo.c
(the source for what is used in the above examples) and modem_fileio.c (not a
modem at all, but simply PCM I/O via files) to see how they are used.


Error Patterns
--------------

The error pattern files are formatted identically to the encoded speech files
with the following considerations:

- Only speech frames are present.
- FQI is saved from the channel decoder:
    FQI = 1 -> good frame
    FQI = 0 -> bad frame
- The d-bits contain the pattern of bit errors after channel decoding:
    0 -> bit is correct
    1 -> bit is flipped
- The CRC is set to zero.

A frame is corrupted using an error pattern as follows:
1. If the frame type is SID or NO_DATA, skip it
2. Copy the FQI bit of the error pattern onto the frame
3. XOR the d-bits of the error pattern onto the d-bits of the frame
