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. A sample makefile (gnu make) that has been tested on Win32
    with cygwin and MSVC8 is also provided. 
    
    To build from source from within a cygwin environment run
        
        make msvcpath=/cygdrive/c/msvc8/VC/bin

    (you will need to set msvcpath appropriately for your environment)

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 24 error patterns specified in the eCall test plan can be found here.
    There are also 7 additional patterns. The 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 run all test cases from campaign_demo.txt on the 'demo' IVS and PSAP
and save the test results in results.txt. The 'sim' refers to the fact all
modules are compiled into a single EXE for simple testing (using ipc_sim.c).

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'. There are 5 simple functions that 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
