PIKA Digital Logger Application Sample

1. PIKA Technologies Inc.Digital Logger Application Sample April 2010

2. What is it? Sample Application developed in C++ and C# Can be used to passively record calls from Digital T1/E1 spans Works on HMP 2.8+ platforms (Windows, Linux) with PIKA Digital PCIe Boards Files can be saved in .wav or raw formats

3. Overall Architecture Description At start-up the main thread will create all the required instances. It will therefore create the digital board instance and its associated members. Each instance will communicate with the PIKA Driver (PKH_XXX) to configure and start it’s associated objects. The main thread will then spawn the event thread. The event thread is used to handle asynchronous events from the PIKA driver. For debugging purposes an event message logger (not to be confused with the digital logger) has been included to show events on the console and can also be injected to the PIKA Driver logs. The DigitalBoard instance contains 4 span instances and up to 2*30 calls. A particular call is associated to 1 channel for each of 2 spans. We should note that signalling channels are created but are not actually started. Each Span instance contains 1 hdlc and up to 30 channels.

4. Getting Started • Install the PIKA Low Level HMP API on a PC ( 2.8.x or newer ) as described in the Getting Started Guide • Remove the line jumpers on the PIKA HMP PCIe digital board. • Install the board in the PC • Cabling - requires some specific wiring • Download, Compile, and run the Digital Logger application

5. Sample Code - Overall Architecture • At start-up, the sample application will statically create all of the resources needed to Passively Record on all channels and spans • The event thread handles asynchronous events from the PIKA driver. • For debugging purposes an event message logger (not to be confused with the digital logger) has been included to show events on the console and can also be injected to the PIKA Driver logs. There are multiple debug levels that can be controlled via a compile flag. • A 4 span board can log 2 T1 or E1 connections • Each Span uses an HDLC to capture ISDN messages and via the PIKA Low Level API, these messages get sent to the application for processing.

6. Overall Architecture Description • The Hdlc instance is used to handle incoming ISDN Q.921/Q.931 messages. When a valid Q.931 message is decoded (cisdntranscoder.cpp), the channel detected shall setup a call. • The call will then start listening to the conference between the 2 previously associated channels and output the conversation to a file. The filename will have the following format: • Board_#_Call_#_$date$.extension • When a ISDN Disconnect or Release message is detected, the audio file will be saved and closed. • It is also possible to copy the audio buffers to the application. This can then be used to listen to the conversation in a live session.

7. Application thread Diagram DL_Initialize Digital Logger API Main Application DL_SetCallAudioBufferCB PKH_BOARD_XXX PIKA Driver DL_SetCallAudioBufferCB PKH_SPAN_XXX DL_Start PKH_CHANNEL_XXX DL_Stop DL_Cleanup Audio function CB Spawn Thread Spawn Thread Application Event Thread Digital Logger Event Thread DL_WaitOnEvent PKH_ Wait On Event DL_WaitOnEventSerialized

8. Using the Digital Logger API There are different APIs available (for windows) • Compile all source into an application • DL_XXX : include digitallogger.h • Compile application with DLL • PKDL_XXX : include DigitalLoggingDll.h • Compile application in C# • Use namespace DigitalLogger in DigitalLogger.cs

9. API call scenario • Main Application thread • DL_Initialize(tApplicationConfiguration config) // Initialize system • DL_SetCallAudioBufferCB(Pf_callAudioBufferCB func) // Set callback if you want to listen to live audio • Create an event thread and call DL_WaitOnEvent(PK_UINT timeout, tApplicationEvent *event) • DL_Start() // Start the system • A Call is triggered from the CO • Application Event Thread • DL_WaitOnEvent returns EVENT_CALLSETUP, SpanId1 specifies the span origin • DL_WaitOnEvent returns EVENT_CALLCONNECT • Digital Application Wrapper • The call will be recorded in an audio file • The Audio Buffer Call Back will the called with the audio buffer • The Call is hung up • Application Event Thread • DL_WaitOnEvent returns EVENT_CALLRELEASE • Digital Application Wrapper • The recorded file is closed • Main Application thread • DL_Stop() // Stop the system • Stop Application thread • DL_Cleanup // Cleanup the system

10. Class Hierarchy and containment Logger (singleton) LogClient BaseEntity System 1 DigitalBoard n 1 4 Span 1 Hdlc 1 Channel 30 Call 2*30

11. Passive Logging Passive Logging – Application Call Logs Process ISDN Messages PKH_SPAN_HDLC_X Audio Record AudioFiles CO RX TX RX- Tip/Ring 0 HDLC Jumpers MediaProcessing T1/E1 Span 1 HDLC RX- Tip/Ring 2 HDLC 3 HDLC HMP Digital Board - PCIe PBX TX RX

12. Passive Logging Architecture PBX CO TX RX RX TX Tip / Ring Tip / Ring RX RX HDLC Audio Audio HDLC M M ISDN Events ISDN Events Conf M Record File

13. Passive Logging – Cabling Telco PBX RX Tip TX Tip RX Ring TX Ring RX Tip TX Tip RX Ring TX Ring Do No Connection Do No Connection RX TIP RX RING TX TIP TX RING RX TIP RX RING TX TIP TX RING Span 0 Span 1 PIKA Digital T1/E1 HMP Board - PCIe

14. Call/Span/Channel allocation Span 1 0 1 2 3 28 29 30 31 Span 2 0 1 2 3 28 29 30 31 0 1 3 2 31 28 29 30 Call Ids 32 33 35 34 63 60 61 62 Span 3 0 1 2 3 28 29 30 31 Span 4 0 1 2 3 28 29 30 31

15. Where can I find it? • The Source code is located under: • http://svn.pikatech.com/customercare/trunk/samples/DigitalLogger/ • Some additional info: • http://forum.pikatechnologies.com/showthread.php?t=170 • ./docs/README.rtf