Novra Devices Communication Library

Version. 5.2A

User Guide

1. Introduction

The communication library provides communication services that can be used to communicate with any supported Novra device. The purpose is to enable clients to control and monitor the devices using their own software tools. This guide should provide the programmers, who are using this library, with the necessary information to use it. The following terms are used in this guide…

Device: Refers to any of Novra products (S75, C75 or A75).

Host: Refers to the Host/PC that runs the final application.

Library: Refers to the communication library provided by Novra.

Application: Refers to the Applications written by Novra clients, using this library to communicate with the device.

Programmer: Refers to the person using this library to produce an application.

User: Refers to the person using the application to interact with the device.

Status Port: Refers to the UDP port that the device sends status to (destination UDP port for status packets)


Novra Devices Communication Library

2. Supported devices

This release supports the following releases of the S75: 2.X, 3.X, PESMAKER, A75 (1.x).


Novra Devices Communication Library

3. Auto Discovery Framework

To automatically recognize the devices the library listens on a select group of 10 UDP ports. This group was chosen to cover a fairly wide spectrum of ports; therefore it is very unlikely that the 10 ports will be blocked on a single system. The device should always be configured such that the status packets are broadcast on these ports. The function GetAvailablePort() –as described later- provides a way of getting a port that is available on the host. If the programmer attempts to set the status port to a value that is not in the auto detect group an error will result. In the unlikely case that a unit can’t be discovered, for example if the host won’t allow listening on the status port that the device uses, programmers should allow for manual device addition.


Novra Devices Communication Library

4. How to use the Library

All the functions that set or retrieve the device parameters require a handle to the device and the proper structure. It is strictly the responsibility of the programmer to pass the proper structure –the structure that matches the device type- to the API call.

4.1. Getting a device handle

The recommended method to obtain a device handle is to use openDevice() and pass it a device entry structure obtained from discoverDevices(). However we also recommend that the application will have a method for manual addition of the device, in this case the user will have to enter the device details –all the values required for the device entry structure- and the application will call the openDevice() API passing it this structure.

OpenDevice() will attempt to listen to status messages from the device. If for any reason –the host might have applications with exclusive access to some UDP ports- the openDevice() function fails to get status messages, the forceDevice() API should be used to reset the network configuration of the device, and reconfigure the status port that the device is using. Anytime the programmer attempts to configure the status port, GetAvailablePort() should be used to obtain a usable value for this parameter.

When the application no longer needs the handle, the closeS75() function should be called. This function will delete the handle, after this call any copies of the handle are invalid and unsafe to use.

The b_openS75(), s_openS75(), b_forceS75(), s_forceS75() are not recommended in new designs. They were ported from an earlier version, refer to the API reference for their use.

4.2. Setting and getting device parameters

The following operations can be performed using this version of the communication library…

- Configure the device network parameters.

- Configure the device RF parameters.

- Get the list of PIDs that the device is configured to process.

- Set the List of PIDs that the device should process.

- Get the device status.

- Get the device Type.

- Reset the Device.

- Set the DVB MAC address (version 3.X devices).

For most of these functions the programmer needs to pass a structure containing the necessary information, or a structure to be populated by the required information. It is strictly the responsibility of the programmer to use the structure that corresponds to the device type.


Novra Devices Communication Library

5. API reference

int discoverDevices( Novra_DeviceList *devices );

int closeS75( S75_Handle S75Unit );

int configureNetwork( S75_Handle S75Unit, LPBYTE networkSettings );

int configureRF( S75_Handle S75Unit, LPBYTE RFSettings );

int setPIDList( S75_Handle S75Unit, const S75D_PIDList *PIDs );

int getPIDList( S75_Handle S75Unit, S75D_PIDList *PIDs );

int getStatus( S75_Handle S75Unit, BYTE *status );

int resetS75( S75_Handle S75Unit );

int GetAvailablePort( WORD &Port);

S75_Handle open Device( Novra_DeviceEntry * pDev, const int timeout, int& ErrorCode);

S75_Handle forceDevice( const Novra_DeviceEntry * pDev,WORD Port, const int timeout, int& ErrorCode);

int GetDeviceType(S75_Handle S75Unit, WORD &DevType);

int SetDVBMACAddress(S75_Handle S75Unit, LPBYTE DVBMAC);

S75_Handle s_openS75( .... );

S75_Handle b_openS75( .... );

S75_Handle b_forceS75( ... );

S75_Handle s_forceS75( ... );


int discoverDevices

int discoverDevices( Novra_DeviceList *devices );

Input

none

Output

devices (A structure to hold the list of devices discovered)

Return

1 = Success, 0 = failed

This function discovers all Novra devices that are sending status reports
on one of the 10 auto detect status ports listed below...

0x1974 | 0x2075 | 0x2175 | 0x2275 | 0x2375
0x2475 | 0x3475 | 0x4475 | 0x4575 | 0x4675

The output of the function is a Novra_DeviceList structure, defined as...

typedef struct Novra_DeviceList {
                            WORD num_devices;
                Novra_DeviceEntry Device[MAX_DEVICES];

                                } Novra_DeviceList;

and the device entry is defined as..

typedef struct Novra_DeviceEntry {
        BYTE DeviceIP[4];
        BYTE DeviceMAC[6];

        WORD StatusPort;

        WORD DeviceType;

        } Novra_DeviceEntry;

BACK


int closeS75

int closeS75( S75_Handle S75Unit );

Input

S75Unit ( Handle to the S75 Unit to be closed )

Output

none

Return

S75_OK or S75_FAILED

This function closes the handle S75Unit by deleting the dynamic object associated with this handle.

BACK


int configureNetwork

int configureNetwork( S75_Handle S75Unit, LPBYTE networkSettings );

Input

S75Unit (handle to the device to be configured), networkSettings (Pointer to a structure that has the new configuration)

Output

none

Return

S75_OK or Error Code

The function will attempt to configure and verify the Device S75Unit, using the Settings in the structure Network Settings. Care must be taken that the network setting structure is the appropriate type for the device.

Two network settings structures are defined. The network settings for the S75 version 2.X devices is...

typedef struct S75D_NetSetting {

BYTE DestinationIP[4];
BYTE SubnetMask[4];
BYTE DefaultGatewayIP[4];
WORD DestinationUDP;
BYTE ReceiverIP[4];
WORD StatusPort;

} S75D_NetSetting;

The network settings structure for version 3.X devices is

typedef struct S75D_NetSetting_V3 {
BYTE UniCastStatusDestIP[4];
BYTE SubnetMask[4];
BYTE DefaultGatewayIP[4];
WORD UniCastStatusDestUDP;
BYTE ReceiverIP[4];
WORD BCastStatusPort;
BYTE IGMP_Enable; 	// Enable IGMP operation.
} S75D_NetSetting_V3;


int configureRF

int configureRF( S75_Handle S75Unit, LPBYTE RFSettings );

Input

S75Unit (handle to the device to be configured), RFSettings (Pointer to a structure that has the new configuration)

Output

None

Return

S75_OK or Error Code (see header file)

The function configures the RF settings of the device whose handle is S75Unit. The RFSettings structure is the same for 2.X devices and 3.X devices.

The structure is defined as follows...

typedef struct S75D_RFSetting {

float
        frequency;

        // MHz
float symbolRate;
                 // Msps
int powerOn;

        // 0 = power to LNB is off, 1 = power to LNB is on
int band;

        // 0 = low, 1 = high
int polarity;

        // 0 = vertical or right, 1 = horizontal or left

} S75D_RFSetting;

In addition to that structure Newer devices support higher voltage for LNB control

For the S75 V 3.x and the PesMaker you have use the following structure to configure the RF

typedef struct S75D_RFSetting_V3 {

float frequency; // MHz

float symbolRate; // Msps

int powerOn; // 0 = power to LNB is off, 1 = power to LNB is on

int band; // 0 = low, 1 = high

int polarity; // 0 = vertical or right, 1 = horizontal or left

BYTE HighVoltage; // Increased Voltage for 20 volt..

BYTE LongLineCompensation ; // Long Line Compensation on / off, add an extra 1 vold

}S75D_RFSetting_V3 ;

The supported LNB voltages are:

Vertical/Horizontal = 13/18 volts (default setting)

Vertical/Horizontal = 14/19 volts (Long Line compensation)

Vertical/Horizontal = 12/20 volts (High voltage Option)

Vertical/Horizontal = 13/21 volts (Long Line compensation and High voltage)


int setPIDList

int setPIDList( S75_Handle S75Unit, const S75D_PIDList *PIDs );

Input

S75Unit (handle to the device to be configured), PIDList (Pointer to a structure that has the new configuration)

Output

None

Return

S75_OK or Error Code (see header file)

This function sets the filter table inside the device to process the DVB packets with the PIDs included in the structure PIDList.

This structure is defined as follows...

typedef struct S75D_PIDList{

WORD Entry[SIZE_PID_LIST];
        // PID values
BYTE Control[SIZE_PID_LIST];
        // 0 = pass raw, 1 = MPE PROCESSING
int	 NumberofPIDs;
        // Number of entries in the List..

} S75D_PIDList;


int getPIDList

int getPIDList( S75_Handle S75Unit, const S75D_PIDList *PIDs );

Input

S75Unit (handle to the device to be configured), PIDList (Pointer to a structure that will hold the list)

Output

PIDList ( the structure that holds the list)

Return

S75_OK or Error Code (see header file)

This function gets the list of PIDs that is received and processed by the device.

This structure is defined as follows...

typedef struct S75D_PIDList{

WORD Entry[SIZE_PID_LIST];
        // PID values
BYTE Control[SIZE_PID_LIST];
        // 0 = pass raw, 1 = MPE PROCESSING
int NumberofPIDs;
        // Number of entries in the List..

} S75D_PIDList;


int getStatus

int getStatus( S75_Handle S75Unit, BYTE *status );

Input

S75Unit (Handle to the device), status (pointer to the structure that will hold the information)

Output

status

Return

Returns

The status structure has to be of the proper type, for V2.X devices use S75D_Status,and use S75D_Status_V3 for Version 3.X devices

The status Structures are defined in the header file S75.h

BACK


int resetS75

int resetS75( S75_Handle S75Unit );

Input

S75Unit (handle to the device)

Output

None

Return

S75_OK or S75_FAILED

This function will send a reset command to the S75Unit

BACK


int GetAvailablePort

int GetAvailablePort( WORD &Port);

Input

Reference to a variable to hold the new port

Output

Port

Return

Error Code

The functions scans the auto detection ports and returns the first available port that can be used on this machine. i.e. no applications is listening on that port

BACK


openDevice

S75_Handle openDevice( Novra_DeviceEntry * pDev, const int timeout, int& ErrorCode);

Input

Device Entry as returned by the Discover Devices, timeout (in ms), reference to error code variable

Output

Error Code

Return

Valid handle or NULL pointer

This function creates a handle to the device pointed to by pDev. this handle is used to access the device through other functions in the library.

BACK


forceDevice

S75_Handle forceDevice( const Novra_DeviceEntry * pDev,WORD Port, const int timeout, int& ErrorCode);

Input

Device pointer, statusPort, timeout (in ms), and reference to error code

Output

Error Code

Return

Valid handle or NULL pointer

The function resets the network configuration of the prescribed device (pDev), and forces it to send status on the given Port (Port), Then it attempts to open the device and creates a handle for it that can be used to access the device later.

This function should be used whenever a device is sending status on a port that is not accessible to the application on the host. The value used for status port should be returned by GetAvailablePort().

BACK


int GetDeviceType

int GetDeviceType(S75_Handle S75Unit, WORD &DevType);

Input

Device Handle, reference to DevType

Output

DevType holds the device type information

Return

Error Code

This function Returns the device type, the following device types are defined in the header file S75.h

typedef enum NOVRA_DEVICES {
 S75_ANY, 		// for the auto discovery class
S75_UNKNOWN, 		// A device that reports firmware that is not recognised or bad status packet.
S75_V_1, 		// For version 1 if we ever decide to support it.
S75D_V21, 		// For version 2.X
S75D_V3 			 // For version 3.X
};


int SetDVBMACAddress

int SetDVBMACAddress(S75_Handle S75Unit, LPBYTE DVBMAC);

Input

Device Handle, DVB MAC (an array of 6 bytes to be used as DVB MAC address)

Output

None

Return

Error Code

The functions sets the DVB MAC address for version 3.X units

BACK


s_openS75

S75_Handle s_openS75( const char *S75IPAddress,

                      const char *S75MACAddress,

                      const int *statusPort,

                      const int *timeout        );

Input   : S75IPAddress, S75MACAddress, statusPort, timeout (in ms)

Output  : none

Returns : valid handle or NULL pointer


b_openS75

S75_Handle b_openS75( const BYTE S75IPAddress[4],

                      const BYTE S75MACAddress[6],

                      const int *statusPort,

                      const int *timeout          );

Input   : S75IPAddress, S75MACAddress, statusPort, timeout (in ms)

Output  : none

Returns : valid handle or NULL pointer


b_forceS75

S75_Handle b_forceS75( const BYTE S75MACAddress[6],

                       const BYTE S75IPAddress[4],

                       const int *statusPort,

                       const int *timeout          );

Input   : S75IPAddress, S75MACAddress, statusPort, timeout (in ms)

Output  : none

Returns : valid handle or NULL pointer


s_forceS75

S75_Handle s_forceS75( const char *S75MACAddress,

                       const char *S75IPAddress,

                       const int *statusPort,

                       const int *timeout        );

Input   : S75IPAddress, S75MACAddress, statusPort, timeout (in ms)

Output  : none

Returns : valid handle or NULL pointer