advantech icdmanager sdk user’s...

Advantech Automation Corp.

Advantech iCDManager SDK

User’s Manual

For Linux

Version <0.90>

iCDManager SDK Version: <0.90> User’s Manual Date: <08/13/2014>

Confidential ©Advantech Automation Corp., 2014



Table of Contents 1. Welcome to iCDManager SDK 5

1.1 About This Manual 5

1.2 Organization of This Manual 5

2. Advantech iCDManager Overview 7

2.1 Overview 7

2.2 iCDManager Functions 8

2.2.1 Firmware Functions 8

2.2.2 Driver Functions 8

2.2.3 SDK Functions 8

2.3 Environments 8

2.3.1 Hardware 8

2.3.2 Operating Systems 8

2.4 Installation 8

2.4.1 Install iCDManager SDK 8

3. Getting Started with Advantech iCDManager SDK 10

3.1 For GCC 10

3.1.1 Create an Empty GCC Project 10

3.1.2 Writing Codes 11

3.1.3 Compile Your Program 11

3.1.4 Test Your Program 11

4. Programming Guide 12

5. Function Reference 14

5.1 Function Description 14

5.1.1 IcdmLibInitialize 15

5.1.2 IcdmLibUninitialize 15

5.1.3 IcdmGetSerialPortCount 16

5.1.4 IcdmGetSerialInfo 16

5.1.5 IcdmGetSerialCommElapse 17

5.1.6 IcdmGetSerialCommStatus 17

5.1.7 IcdmGetSerialCommExceptionTime 18



5.1.8 IcdmGetSerialCommDataInterval 18

5.1.9 IcdmGetSerialRate 18

5.1.10 IcdmSetSerialRateConfig 19

5.1.11 IcdmGetSerialRateConfig 21

5.1.12 IcdmGetLANPortCount 22

5.1.13 IcdmGetLANInfo 23

5.1.14 IcdmGetLANLinkStatus 23

5.1.15 IcdmGetLANLinkExceptionTime 24

5.1.16 IcdmGetLANCommElapseTime 24

5.1.17 IcdmGetLANRate 25

5.1.18 IcdmSetLANRateConfig 25

5.1.19 IcdmGetLANRateConfig 26

5.1.20 IcdmGetAllRate 27

6. iCDManager SDK Programming Examples 29

6.1 iCDMTest Sub-Functions 29

6.1.1 Show rate 29

6.1.2 Show firmware version 29

6.1.3 Quit program 29

6.2 Example Call Flows 29

6.2.1 Get Serial Port Count 30

6.2.2 Get Serial Port Information 30

6.2.3 Get Serial Port Rate Configuration 30

6.2.4 Set Serial Port Rate Configuration 31

6.2.5 Get LAN Port Count 32

6.2.6 Get LAN Port Rate Configuration 32

6.2.7 Set Serial Port Rate Configuration 32

6.2.8 Get All Ports Rate 33

7. Appendix 34

7.1 Hardware support 34



Advantech iCDManager SDK

1. Welcome to iCDManager SDK

1.1 About This Manual

This manual contains the information you need to get started with the Advantech

iCDManager SDK.

The iCDManager SDK allows you to easily check system communication status, and get

diagnosis information in programs developed with GCC.

This documentation describes Application Programming Interface (API), including calling

procedure of iCDManager SDK.

This manual also contains step-by-step instructions for building applications with the

iCDManager SDK. With the help of Advantech iCDManager SDK, users can develop

applications with tools like GCC in different Linux system platforms.

The Advantech iCDManager SDK provides examples, explaining how to use Advantech

iCDManager SDK with series of real examples and offering reference for users to develop

their own applications. You can modify these sample applications to meet your needs.

This manual does not show you how to solve every possible programming problem. To use

this manual, you should already be familiar with at least one of the supported programming

environments and Linux.

1.2 Organization of This Manual

This user manual is divided into the following sections:

• Advantech iCDManager Overview

• Getting Started with Advantech iCDManager SDK

• Programming Guide

• Function Reference

• iCDManager SDK Programming Examples

Welcome to Advantech iCDManager SDK



Gives the user a basic idea of this manual.

Advantech iCDManager SDK Overview

Gives the user a basic idea of Advantech iCDManager SDK.

Getting Started with iCDManager SDK

Gives the new user a clear idea of the Advantech iCDManager SDK and a walk-through

in creating a simple application. Step-by-step procedures are given for an application

written in GCC development environments.

Programming Guide

Shows Call Flows for using iCDManager SDK.

Functions Reference

• Function Description

Gives a thorough description of all the functions supported in Advantech iCDManager

SDK.

Device Driver Programming Examples

This chapter gives an overview of the examples we provide.



2. Advantech iCDManager Overview The Advantech iCDManager SDK provides functions to check system communication status,

and get diagnosis information when connectivity exception occurs. It is freely bundled with

Advantech ECU platform products which with iCDManager design.

With iCDManager SDK, it gives you a powerful programming API for use with a variety of

programming environments.

2.1 Overview

Advantech's iCDManager SDK contains a set of functions and associated structures that can

be used in various application programs. The APIs support GCC development environment.

Users can directly write applications with API. Examples are supplied in the package,

providing a reference for users to develop applications. When developing work is completed,

users can use test tools to verify if functions of the application are correct.

Figure 1 illustrates the iCDManager's system structure and component.



2.2 iCDManager Functions

2.2.1 Firmware Functions

The firmware module is used to monitor the communication status TX and RX, firmware will

calculate by the communication quality rating algorithm, it can detect the communication

signal (RX ,TX ) status and transfer these data to the driver layer.

The Advantech iCDManager firmware supports the following functions:

2.2.2 Driver Functions

The driver module will collect the firmware data and provide the communication status for

the above application software to get the communication interface status.

2.2.3 SDK Functions

The SDK module will provide the Programming API for the customer application.

2.3 Environments

2.3.1 Hardware This Software API and utility support only Advantech ECU platform products which with

iCDManager design.

2.3.2 Operating Systems � Linux with Kernel 2.6.18

2.4 Installation

2.4.1 Install iCDManager SDK

Installation is required. If there is no existing installation of Advantech iCDManager SDK on

your computer, take the following steps to install Advantech iCDManager SDK.



How to install Advantech iCDManager SDK

1) Verify that your computer meets the hardware and software requirements to run

Advantech iCDManager SDK.

2) If you do not already have a copy of the installer Advantech iCDManager driver,

download the installer.

3) Uncompress the tar.gz file

4) Run ./install.sh script to install the iCDManager SDK.

Below is an example of Advantech iCDManager SDK Setup.

Step 1: uncompress the tar.gz file.

#tar –zxvf advagent-1.0.1.tar.gz

Setp 2:run the install.sh script to install SDK

#cd advantech-1.0.0

#./install.sh

This will install SDK to /home/root/Advagent



3. Getting Started with Advantech iCDManager SDK

This chapter provides a step-by-step example to demonstrate how to build an application

using iCDManager SDK from scratch in GCC.

Following is the list of the necessary files for programming:

File Name Description File Location

• iCDManagerSDK.h: Function declaration, constant definition for GCC. Your installation

/home/root/Advagent/include

• libicdm.so: Library files for C/ C++.

Your installation /usr/lib/

3.1 For GCC

3.1.1 Create an Empty GCC Project

To use the SDK functions, you must use the so routines. Follow this procedure:

1. Create your source files as you would for Linux programs written in C++ by calling so

functions as typical function calls.

2. Include the header file, as shown in the following example:

#include "iCDManagerSDK.h"

(Installation /home/root/Advagent/Include/ iCDManagerSDK.h)

3. Import library: "libicdm.so" to the project module.

(Installation /usr/lib/libicdm.so)

For a general outline of creating a c programs, complete the following procedure:

1. Create a c source code file as:

#vim icdmtest.c



3.1.2 Writing Codes

#include <stdio.h>

#include "iCDManagerSDK.h"

int main()

{

IcdmLibInitialize();

int serialPortCount = IcdmGetSerialPortCount();

int LANPortCount = IcdmGetLANPortCount();

printf(“Serial count:%d, LAN count:%d\n”,);

IcdmLibUninitialize();

return 0;

}

3.1.3 Compile Your Program

User could use the following command to compile the program:

# gcc icdmtest.c –o icdmtest -licdm

3.1.4 Test Your Program

User could use the following command to execute the program:

#./icdmtest



4. Programming Guide

Device Function Group

The following figure describes the common call flow of the iCDManager which is necessary

for all iCDManager operations:

IcdmLibInitialize

End

IcdmLibUninitialize

Serial port / LAN port functions

Start

• IcdmLibInitialize and IcdmLibInitialize Functions

IcdmLibInitialize initializes the device. This function must be called before any other

method that performs iCDManager operations. IcdmLibUninitialize() is the counterpart

function of the IcdmLibInitialize function to close the device.

• Serial Device Functions

IcdmGetSerialPortCount/ IcdmGetSerialInfo/ IcdmSetSerialRateConfig/ IcdmGetSerialRateConfig/ IcdmGetSerialRate

These functions configure the Serial device.

• LAN Device Functions

IcdmGetLANPortCount / IcdmGetLANInfo / IcdmGetLANLinkStatus /



IcdmSetLANRateConfig / IcdmGetLANRateConfig / IcdmGetLANRate

These functions configure the LAN port rate.

IcdmGetAllRates

This function get all rates about serial port and LAN port.



5. Function Reference

Advantech's iCDManager contains a set of functions and associated structures that can be

used in various applications. The APIs support many development environments and

programming languages, including C++. This documentation describes iCDManager

application programming interface (API).

5.1 Function Description

User should manipulate Watchdog through the functions from libicdm.so, thus makes user

can use the iCDManager SDK through their existing application and examples without any

change.

The following tables describe all the user interfaces the iCDManager SDK should support.

Item Name Note

1 IcdmLibInitialize iCDManager SDK library initialize. 2 IcdmLibUninitialize

iCDManager SDK library uninitialize.

3 IcdmGetSerialPortCount

Get serial port count in device.

4 IcdmGetSerialInfo

Get serial port send/receive data elapse and response time.

5 IcdmGetSerialCommElapse Get serial port send/receive data elapse.

6 IcdmGetSerialCommStatus

Get serial port send/receive data status.

7 IcdmGetSerialCommExceptionTime

Get the time for serial port communication in exception status (in second).

8 IcdmGetSerialCommDataInterval

Get Serial port communication data interval (in microsecond).

9 IcdmGetSerialRate Get serial port communication status rate.

10 IcdmSetSerialRateConfig Get serial rate configuration.

11 IcdmGetSerialRateConfig Get serial rate configuration.

12 IcdmGetLANPortCount Get LAN port count in the device.

13 IcdmGetLANInfo

Get the Watchdog current reboot status.

14 IcdmGetLANLinkStatus Get LAN port link status.



15 IcdmGetLANLinkExceptionTime Get the time for LAN port link in exception status.

16 IcdmGetLANCommElapseTime

Get the latest communication elapse time for LAN port.

17 IcdmGetLANRate Get LAN port communication status rate.

18 IcdmSetLANRateConfig Set LAN rate configuration.

19 IcdmGetLANRateConfig Get LAN rate configuration.

20 IcdmGetAllRate

Get all serial port and LAN communication status rate.

5.1.1 IcdmLibInitialize

bool ret = IcdmLibInitialize ();

Purpose

iCDManager SDK library initialize.

Parameters

Return

1. true if initialize successful.

2. false if initialize failed.

5.1.2 IcdmLibUninitialize

bool ret = IcdmLibUninitialize ();

Purpose

iCDManager SDK library uninitialize.

Parameters

Name Direction Type Range Description

Return



1. true if uninitialize successful.

2. false if uninitialize failed.

5.1.3 IcdmGetSerialPortCount

uint32 serialPortCount = IcdmGetSerialPortCount();

Purpose

Get serial port count in device.

Parameters

Return Value

1. Serial port count in device if success.

2. 0 if failed.

5.1.4 IcdmGetSerialInfo

bool ret = IcdmGetSerialInfo (uint32 portNumber, uint32& RxElapsed, uint32& TxElapsed, uint32& ResponseTime);

Purpose

Get serial port send/receive data elapse and response time.

Parameters


portNumber Input Uint32 default Serial port number. (1 refers to COM1).

RxElapsed Output Uint32 default Data receive elapse.

TxElapsed Output Uint32 default Data transmit communication elapse.

ResponseTime Output Uint32 default data communication interval

Return Value

1. true if successful.

2. false if failed.



5.1.5 IcdmGetSerialCommElapse

uint32 elapse = IcdmGetSerialCommElapse ( uint32 portNumber, uint32 commDataType );

Purpose

Get serial port send/receive data elapse.

Parameters


portNumber Input uint32 default Serial port number. (1 refers to COM1).

commDataType Input uint32 0/1 0 for send data status, and 1 for receive data status.

Return Value

1. Serial port send/receive data elapse.

5.1.6 IcdmGetSerialCommStatus

bool ret = IcdmGetSerialCommStatus ( uint32 portNumber, uint32 commDataType );

Purpose

Get serial port send/receive data status.

Parameters




Return Value

1. If there is data communication in specified time interval(60s), then return true; else return false.



5.1.7 IcdmGetSerialCommExceptionTime

uint32 exceptionTime = IcdmGetSerialCommExceptionTime ( uint32 portNumber, uint32 commDataType );

Purpose

Get the time for serial port communication in exception status (in second).

Parameters




Return Value

1. The time for serial port communication in exception status (in second). If the communication is still on, then return 0.

5.1.8 IcdmGetSerialCommDataInterval

uint32 interval = IcdmGetSerialCommDataInterval( uint32 portNumber );

Purpose

Get Serial port communication data interval (in microsecond).

Parameters



Return Value

1. Serial port communication data interval (in microsecond).

5.1.9 IcdmGetSerialRate

double rate = IcdmGetSerialRate ( uint32 portNumber );



Purpose

Get serial port communication status rate.

Parameters


portNumber Input uint32 default Serial port number.

Return Value

1. Serial port communication status rate.

5.1.10 IcdmSetSerialRateConfig

bool ret = IcdmSetSerialRateConfig( uint32 portNumber, uint32 mode, uint32 AStandard, uint32 BStandard, uint32 AMax, uint32 BMax, uint32 Enable );

Purpose

Set serial rate configuration.

Parameters



mode Input uint32 1-4

Rating mode.

1: Fully TX/RX

2: Half TX/RX

3: TX Only

4: TX Only

AStandard Input uint32 default

A parameter standard value. In different mode, the meaning is different.

1: RX Time Span(Normal)

2: TX Time Span



3: TX Time Span(Normal)


BStandard Input uint32 default

B parameter standard value. In different mode, the meaning is different.


2: RX Time Span

3: NA

4: NA

AMax Input uint32 default

A parameter max value. In different mode, the meaning is different.

1: RX Time Span(Max)

2: TX Time Span(Max)



BMax Input uint32 default

B parameter max value. In different mode, the meaning is different.



3: NA

4: NA

Enable Input uint32 0/1

Flag for checking rate result or not.

0: not check

1: check

Return Value




2. false if failed.

5.1.11 IcdmGetSerialRateConfig

bool ret = IcdmGetSerialRateConfig( uint32 portNumber, uint32& mode, uint32& AStandard, uint32& BStandard, uint32& AMax, uint32& BMax, uint32& Enable );

Purpose

Get serial rate configuration.

Parameters



mode Output uint32 1-4

Rating mode.

1: Fully TX/RX

2: Half TX/RX

3: TX Only

4: TX Only

AStandard Output uint32 default

A parameter standard value. In different mode, the meaning is different.


2: TX Time Span



BStandard Output uint32 default

B parameter standard value. In different mode, the meaning is different.


2: RX Time Span

3: NA

4: NA



AMax Output uint32 default

A parameter max value. In different mode, the meaning is different.





BMax Output uint32 default

B parameter max value. In different mode, the meaning is different.



3: NA

4: NA

Enable Output uint32 0/1


0: not check

1: check

Return Value


2. false if failed.

5.1.12 IcdmGetLANPortCount

uint32 LANPortCount = IcdmGetLANPortCount();

Purpose

Get LAN port count in the device.

Parameters

Return Value

1. LAN count if success.



2. 0 if failed.

5.1.13 IcdmGetLANInfo

bool ret = IcdmGetLANInfo(uint32 portNumber, uint32 &ElapsedOfLastActive,uint8 &LinkSpeed, uint8 &PhyiscLinkStatus);

Purpose

Get LAN port communication information.

Parameters


portNumber Input uint32 default LAN port number (1 refers to LAN1).

ElapsedOfLastActive Output uint32 default Latest active status elapse time.

LinkSpeed Output uint8 default

LAN port link speed.

0xa0:100M;

0xa1:1k;

0xa3:10M

PhyiscLinkStatus Output uint8 default 1:link;

0:not link.

Return Value


2. false if failed.

5.1.14 IcdmGetLANLinkStatus

bool status = IcdmGetLANLinkStatus( uint32 portNumber );

Purpose

Get LAN port link status.

Parameters





Return Value

1. If there is physical link for the LAN port, return true; else return false.

5.1.15 IcdmGetLANLinkExceptionTime

uint32 exceptionTime = IcdmGetLANLinkExceptionTime( uint32 portNumber );

Purpose

Get the time for LAN port link in exception status.

Parameters



Return Value

1. the time for LAN port link in exception status (in second).

5.1.16 IcdmGetLANCommElapseTime

uint32 elapse = IcdmGetLANCommElapseTime( uint32 portNumber );

Purpose

Get the latest communication elapse time for LAN port.

Parameters



Return Value



1. the latest communication elapse time for LAN port..

5.1.17 IcdmGetLANRate

double rate = IcdmGetLANRate( uint32 portNumber );

Purpose

Get LAN port communication status rate.

Parameters



Return Value

1. LAN port communication status rate.

5.1.18 IcdmSetLANRateConfig

bool ret = IcdmSetLANRateConfig( uint32 portNumber, uint32 AStandard, uint32 AMax, uint32 Enable );

Purpose

Set LAN rate configuration.

Parameters




Rating mode.

1: Client/Server Polling

2: Heartbeat Monitoring




4: Event Data Stream

AStandard Input uint32 default A parameter standard value. It means Active Time Span (Normal).

AMax Input uint32 default A parameter max value. It means Active Time span (Max).



0: not check

1: check

Return Value


2. false if failed.

5.1.19 IcdmGetLANRateConfig

bool ret = IcdmGetLANRateConfig( uint32 portNumber, uint32& AStandard, uint32& AMax, uint32& Enable );

Purpose

Get LAN rate configuration.

Parameters


portNumber Input uint32 default LAN port number.


Rating mode.

1: Client / Server Polling





4: Event Data Stream

AStandard Input uint32 default A parameter standard value. It means Active Time Span (Normal).

AMax Input uint32 default A parameter max value. It means Active Time span (Max).



0: not check

1: check

Return


2. false if failed.

5.1.20 IcdmGetAllRate

bool ret = IcdmGetAllRate(unsigned char *pSerialRate, uint32 serialCount, unsigned char *pLanRate, uint32 lanCount);

Purpose

Get all Serial port and LAN communication rate.

Parameters


pSerialRate Output unsigned char pointer

default Rate array for all Serial port, array length should equal to serial port count.

serialCount Input uint32 default Serial port count.

pLanRate Output unsigned char pointer

default Rate array for all LAN port, array length should equal to LAN port count.

lanCount Input uint32 default LAN port count.



Return


2. false if failed.



6. iCDManager SDK Programming Examples

This chapter gives an overview of the examples we provide.

Please install the example package provided by Advantech firstly.

We offer iCDMTest program for user, which can be used for the reference of software

development.

6.1 iCDMTest Sub-Functions

The test example is console program. This program should supply thirteen operations,

below is the command line of the test program:

6.1.1 Show rate

- This command shows rates about serial port and LAN port.

Command line: t

6.1.2 Show firmware version

- This command shows firmware version.

Command line: v

6.1.3 Quit program

- This command force example program quit.

Command line: q

6.2 Example Call Flows



6.2.1 Get Serial Port Count

IcdmLibUninitialize()

IcdmGetSerialPortCount()

IcdmLibInitialize()

6.2.2 Get Serial Port Information

IcdmGetSerialInfo(portNumber, RxElapsed, TxElapsed,

ResponseTime)

IcdmLibInitialize()


6.2.3 Get Serial Port Rate Configuration




IcdmGetSerialRateConfig(portNumber, mode,

AStandard, BStandard,

AMax, BMax,

Enable );

IcdmLibInitialize()

6.2.4 Set Serial Port Rate Configuration


IcdmSetSerialRateConfig(portNumber, mode, AStandard, BStandard, AMax, BMax, Enable );

IcdmLibInitialize()



6.2.5 Get LAN Port Count


IcdmGetLANPortCount()

IcdmLibInitialize()

6.2.6 Get LAN Port Rate Configuration

IcdmGetLANRateConfig(portNumber, mode,

AStandard, AMax,

Enable );


IcdmLibInitialize()

6.2.7 Set Serial Port Rate Configuration




IcdmSetLANRateConfig(portNumber, mode, AStandard, AMax, Enable );

IcdmLibInitialize()

6.2.8 Get All Ports Rate

IcdmLibInitialize()

IcdmGetSerialPortCount()


IcdmGetLANPortCount()

IcdmGetAllRate(*pSerialRate,serialCount,

*pLanRate,lanCount);



7. Appendix

7.1 Hardware support

Hardware support list:

Item Product Type Product

ECU

1) ECU-4674

advantech icdmanager sdk user’s...

Documents