
Readme.txt

Package:  eCall ANSI-C fixed-point reference source code
Version:  15.0.0 (Rel-15)
Date:     2017-03-14


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

folder 'ecall':
    Contains the complete eCall reference source code.

    modem_ivs.c     : top-level modem implementation for IVS
    modem_psap.c    : top-level modem implementation for PSAP

    modemx.h        : header file for both modem_ivs.c and modem_psap.c

    ecall_defines.h : compile time options and preprocessor constants

    ecall_control.h : header file control message handling
    ecall_fec.h     : header file FEC encoder and decoder
    ecall_modem.h   : header file modulator and demodulator
    ecall_sync.h    : header file synchronization
    ecall_rom.h     : header file ROM data

    ecall_control.c : control message handling
    ecall_fec.c     : FEC encoder and decoder
    ecall_modem.c   : modulator and demodulator
    ecall_sync.c    : synchronization
    ecall_rom.c     : ROM data


folder 'test_setup':
    Contains the eCall software simulation framework, to be compiled and run
    on MS Windows systems.

folder 'test_vec':
    Contains binary PCM data (104 files) and receiver/transmitter port logs
    in ASCII format (104 files) to test the eCall IVS and PSAP modems.

    The PCM format is 16 bit signed, little endian, at 8 kHz sampling rate.
    The data files reflect 26 test cases and were generated from the eCall
    software simulation framework.

    campaign_short.txt    : configuration file for the 26 test cases

    pcmdlout<index>.pcm   : output PCM data of DL vocoder = input to IVS
    pcmulout<index>.pcm   : output PCM data of UL vocoder = input to PSAP

    pcmdlin<index>.pcm    : test vectors for PSAP modem output
    pcmulin<index>.pcm    : test vectors for IVS modem output

    portivsrx<index>.txt  : test vectors for IVS port logs (receiver)
    portivstx<index>.txt  : test vectors for IVS port logs (transmitter)

    portpsaprx<index>.txt : test vectors for PSAP port logs (receiver)
    portpsaptx<index>.txt : test vectors for PSAP port logs (transmitter)


standalone.c
    main() wrapper to run the IVS or PSAP modem on prestored PCM files or
    receiver/transmitter port logs. To get a list of command-line options,
    invoke the corresponding executable with option '-h' (help).

standalone.h
    header file for standalone.c


Makefile.win
    NMAKE Makefile for Microsoft Visual Studio 2005 and above:
    Builds 'standalone.exe' from standalone.c and the eCall sources,
    build options are RELEASE and DEBUG.

Makefile.glx
    GNU Linux Makefile using gcc:
    Builds 'standalone' from standalone.c and the eCall sources,
    build options are RELEASE and DEBUG.

verify.bat
    Windows batch file:
    Runs 'standalone.exe' in six different modem modes on the 26 test cases
    contained in folder 'test_vec' and performs a test vector comparison to
    the respective output PCM and port log data.

verify.sh
    Linux shell script:
    Same functionality as 'verify.bat', but for usage under Linux.


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

3GPP TS 26.268 provides the eCall modem source code, a software simulation
framework, and a standalone wrapper that allows to run the IVS or PSAP modem
on prestored reference data.

The following functions represent the eCall modem interface and invoke the
respective receiver and transmitter implementation of each modem:

    * void IvsReset(const Ord8 *msd, int length);
    * void IvsProcess(Int16 *pcm);
    * void IvsSendStart(void);

    * void PsapReset(void);
    * void PsapProcess(Int16 *pcm);
    * void PsapSendStart(void);
    * void PsapSendHlack(const Ord8 data);

The external application must in addition implement the callback functions:

    * void IvsCatchEvent(IvsEvent ie);
    * void IvsReceiveAck(void);
    * void IvsReceiveHlack(const Ord8 data);

    * void PsapCatchEvent(PsapEvent pe);
    * void PsapReceiveMsd(const Ord8 *msd, int length);

    * void Abort(const char *format, ...);
    * void LogInfo(const char *format, ...);

IvsCatchEvent and PsapCatchEvent inform about relevant modem events and can
be used to perform actions such as muting or unmuting of the voice channel.
The other callback functions indicate...

    * IvsReceiveAck   : reception of the lower-layer ACK,
    * IvsReceiveHlack : reception of the HLACK message,
    * PsapReceiveMsd  : successful MSD reception.

Abort and LogInfo should implement a variadic error and printlog handler,
respectively. See standalone.c for sample implementations of all callback
functions.

For a real-time simulation over 3GPP FR and AMR vocoders and to log PCM data
as input to the standalone wrapper, the eCall sources have to be integrated
into a simulation framework; folder 'test_setup' contains the one as used in
the 3GPP selection tests.

In order to compile and run the eCall modem code, follow the instructions
given below. For code testing, two batch files have been provided:

    * verify.bat : MS Windows systems
    * verify.sh  : Linux systems

For each of the 26 test cases of campaign_short.txt in folder 'test_vec',
they run the standalone wrapper in six different modem modes (three IVS and
three PSAP modes). The resulting PCM and port log files in folder 'out' are
finally compared to the test vectors in folder 'test_vec'.

In modes 'psap' and 'psaprx', you should see an MSD success message at the
end of each test case.


Code Compilation
----------------

MS Windows systems
    Compilation assumes an installation of MS Visual Studio 2005 or above.
    To set the environment variables for building, run 'vcvars32.bat' which
    should be contained in the 'bin' subfolder of your VC installation.

    To build standalone.exe from standalone.c and the eCall sources (or to
    perform cleanup), run

    nmake /f Makefile.win
    nmake /f Makefile.win clean

    The source code should compile without any errors or warnings.
    Run 'verify.bat' to verify the executable against the test vectors.


GNU Linux systems
    Compilation under Linux has been tested with

    * GNU Make version 3.81
    * gcc version 4.1.3 and 4.2.4

    Build the executable 'standalone' and perform cleanup with

    make -f Makefile.glx
    make -f Makefile.glx clean

    On the platforms tested, the code compiled without errors or warnings.
    Run 'verify.sh' to verify the executable against the test vectors.


Simulation Framework
--------------------

The eCall software simulation framework is provided in folder 'test_setup'.

Important remarks:

    * See LICENSE.TXT and README.TXT for terms of usage!

    * The G.711 software is part of ITU-T Rec. G.191, (C) ITU 2000.
      Distributed with the authorization of ITU as part of the test setup
      software for 3GPP TS 26.268.

    * The framework must be compiled and run on MS Windows systems, as the
      FR and AMR vocoders are attached to it in form of Windows executables
      and via Windows specific API functions.


To build (or clean) the framework together with the eCall IVS and PSAP,
change to subfolder 'c' of 'test_setup' and run (remember 'vcvars32.bat')

    nmake /f makefile_ecall
    nmake /f makefile_ecall clean

The framework has the five callback functions of above already implemented.
By default, the binaries (*.exe *.lib) are generated in the 'bin' subfolder.
You can use the following two batch files to run the executables:

    demosim.bat  : runs testsim_demo.exe
    demosock.bat : runs testlab.exe and modem_demo.exe in socket mode
