EIS Service SDK

From ESS-WIKI
Jump to: navigation, search

Introduction

  This is a SDK for receiving and sending control command to EdgeSense system. Application can use the SDK to communication with EdgeSense southbound devices.

Device Service SDK

 Device service SDK supports cross-platform / OS and multiple language as below. User can ealy to get/set southbound services by it. 

OS: Windows, Linux

CPU: x86/x64 and ARM / RISC

Language: C/C++, Node.JS

How To

Soure Code

C/C++

git@advgitlab.eastasia.cloudapp.azure.com:EdgeSense/Service-SDK.git

Node.JS

git@advgitlab.eastasia.cloudapp.azure.com:EdgeSense-Open/device-service-sdk-node.js.git


Definition

Service Return Code

typedef enum {                                                        
    SV_ER_NOT_IMPLEMENT                = -13,   /*        Does Not Support this command        (501)        */
    SV_ER_TIMEOUT                      = -12,   /*        Request Timeout                      (408)        */
    SV_ER_SYS_BUSY                     = -11,   /*        System is busy                       (503)        */
    SV_ER_VALUE_OUT_OF_RNAGE           = -10,   /*        Value is out of range                (416)        */
    SV_ER_SYNTAX_ERROR                 =  -9,   /*        Format is correct but syntax error   (422)        */
    SV_ER_FORMAT_ERROR                 =  -8,   /*        Format error                         (415)        */
    SV_ER_REQUEST_ERROR                =  -7,   /*        Request error                        (400)        */
    SV_ER_RESOURCE_LOSE                =  -6,   /*        SenHub disconnect                    (410)        */
    SV_ER_RESOURCE_LOCKED              =  -5,   /*        Resource is in setting               (426)        */
    SV_ER_NOT_FOUND                    =  -4,   /*        Resource Not Found                   (404)        */
    SV_ER_WRITE_ONLY                   =  -3,   /*        Read Only                            (405)        */
    SV_ER_READ_ONLY                    =  -2,   /*        Write Only                           (405)        */
    SV_ER_FAILED                       =  -1,   /*        Failed                               (500)        */
    SV_OK                              =   0,   /*        Success                              (200)        */
    SV_INITILIZED                      =   1,   /*        Library had initilized                            */
} SV_CODE;

Service Status

typedef enum
{
    SV_UNINIT = 0,
    SV_INIT   = 1,
    SV_JOINED = 2,
    SV_LEAVED = 3,
}SV_STATUS;

Service Event

Callback Function

typedef SV_CODE (SVCALL *Service_Cb) ( SV_EVENT e, char *ServiceName, void *inData, int dataLen, void *pUserData )

Service Event Type

typedef enum
{
    SV_E_JoinServiceSystem       = 0, // Connected to the Service System
    SV_E_LeaveServiceSystem      = 1, // Disconnected from the Service System
    SV_E_RegisterService         = 2, // Registed a new Service ( ex: HDD_PMQ Plugin )
    SV_E_DeregisterService       = 3, // Deregisted a Service
    SV_E_UpdateServiceCapability = 4, // Update Service's Capability
    SV_E_UpdateData              = 5, // Update Service's data value
    SV_E_ActionResult            = 6, // Reply Message of Get / Set
    SV_E_EventNotify             = 7, // EventNotify
}SV_EVENT;

Example

e ServiceName inData dataLen pUserData
SV_E_JoinServiceSystem
 ServiceSystem
 "" 0 point of user data
SV_E_LeaveServiceSystem
 ServiceSystem
 "" 0 point of user data
SV_E_RegisterService
 HDD_PMQ
 InfoSpec of Service refer to SenHub
 Length of data
 point of user data
SV_E_DeregisterService
 HDD_PMQ
 "" 0 point of user data
SV_E_UpdateServiceCapability
 HDD_PMQ
 InfoSpec of Service refer to SenHub
 Length of data
 point of user data
SV_E_UpdateData
 HDD_PMQ
 data value of Service refer to SenHub
 Length of data
 point of user data
SV_E_ActionResult
 HDD_PMQ
 result of action
 Length of data
 point of user data
SV_E_EventNotify
 HDD_PMQ
 event notify refer to EventNotify
 Length of data
 point of user data

 

Functions

Item Function Name Description
1 SV_Initialize Initialize the Service SDK
2 SV_Uninitialize
 UnInitialize the Service SDK
3 SV_GetVersion
 Get version of Service SDK
4 SV_GetServiceStatus
 Get status of Service System
5 SV_Query_Service
 Query All of Service Name
6 SV_GetCapability
 Get Service's Capability
7 SV_AutoReportStart
 Start Auto Report
8 SV_AutoReportStop
 Stop Auto Report
9 SV_Action
 Function for Get / Set Command


Initial & Uninitial 

SV_CODE SV_Initialize( Service_Cb fn, void *pInUserData )

  • Description:Initialize the Service SDK
  • Parameter:

           Service_Cb     fn: point of callback function

            void* pInUserData: user data will pass when callback

  • Return value:

           SV_CODE  - SV_OK                : Successful
                                SV_ER_FAILED  : Failed to call

  • History:   06/26/2017 Modified


SV_CODE SV_Uninitialize( );

  • Description: UnInitialize the Service SDK
  • Parameter: NONE
  • Return value:

           SV_CODE  - SV_OK                : Successful
                                SV_ER_FAILED  : Failed to call

  • History:   06/26/2017 Modified

Information

SV_CODE SV_GetVersion(char *outVersion, int bufSize ); 

  • Description: Get version of Service SDK
  • Parameter:

      - char * outVersion (out): point of result buffer size ( recomd: 128 bytes ) =>v1.0.1
      - int    bufsize     (in): max size of buffer

  • Return value:

        SV_CODE  - SV_OK               : Successful
                           - SV_ER_FAILED: Failed to call

  • History:   06/26/2017 Modified
  • Example: 

                 outVersion: "v1.0.1"



SV_STATUS SV_GetServiceStatus( );

  • Description: Get status of Service System
  • Parameter:

             NONE

  • Return value:

                  SERVICE_STATUS - SV_UNINIT: SDK NOT Initilize
                                                  - SV_INIT     : Init Status
                                                  - SV_JOINED: Joined to Service System
                                                  - SV_LEAVED: Leaved from Service System

  • History:   06/26/2017 Modified



SV_CODE SV_Query_Service( char *outBuf, int bufSize );

  • Description: Query All of Service Name
  • Parameter:

            - char * outBuf  (out):  point of result buffer size ( recomd: 1024 bytes ) => { "Service":{"e":[{"n":"HDD_PMQ},{"n":"Modebus"}] }

            - int     bufsize      (in):  max size of buffer

  • Return value:

           SV_CODE  - SV_OK               : Successful
                               - SV_ER_FAILED: Failed to call

  • History:   06/26/2017 Modified
  • Example:

              outBuf=> {"Service":{"e":[ ] }} or {"Service":{"e":[{"n":"HDD_PMQ},{"n":"Modebus"}]}}

Function for Service

SV_CODE SV_GetCapability( const char *ServiceName, char *outBuffer,  int bufSize )

  • Description: Get Service's Capability
  • Parameter:

           - const char * ServiceName (in):    Service Name => HDD_PMQ

           - char *            outBuffer     (out):     buffer point for Service's Info Spec ( Recommend:4096 characters )

           - int                  bufSize            (in):     Max buffer size ( Recommend: 4096 ) 

  • Return value:

           SV_CODE  - SV_OK               : Successful
                               - SV_ER_FAILED: Failed to call

  • History:   06/26/2017 Modified
  • Example:

            ServiceName : HDD_PMQ

             outBuffer : Capability of Serice refer to SenHub



SV_CODE SV_AutoReportStart( const char *ServiceName , char *inData, int inDataLen  );

  • Description: Start Auto Report
  • Parameter:

           - const char * ServiceName (in):    Service Name => HDD_PMQ

           - char *                      inData (in):     Start JSON Data

           - int                      inDataLen (in):     Data Length

  • Return value:

           SV_CODE  - SV_OK               : Successful
                               - SV_ER_FAILED: Failed to call

  • History:   06/26/2017 Modified
{
    "susiCommData":{
        "requestID":1001,
        "catalogID": 4,
        "commCmd": 2053, //general_start_auto_upload_req
        “handlerName”:”general”,
        "requestItems":{"All":{}}        
        "autoUploadIntervalSec": 30
    }
}



SV_CODE  SV_AutoReportStop( const char *ServiceName, char *inData, int inDataLen );

  • Description: Stop Auto Report
  • Parameter:

           - const char * ServiceName (in):    Service Name => HDD_PMQ

           - char *                      inData (in):     Start JSON Data

           - int                      inDataLen (in):     Data Length

  • Return value:

           SV_CODE  - SV_OK               : Successful
                               - SV_ER_FAILED: Failed to call

  • History:   06/26/2017 Modified
  • Example:

            ServiceName : HDD_PMQ

             inData : 

 {
    "susiCommData": {
        "requestID":1001,
        "catalogID": 4,        
        "commCmd": 2056, //general_stop_auto_upload_req
        “handlerName”:”general”
        "requestItems":{"All":{}}
    }
}



               Reply:

                 Topic: /cagent/admin/<devID>/agentcallbackreq 

{
    "susiCommData":{
        "requestID":1001,
        "catalogID": 4,
        "commCmd": 2054, //general_start_auto_upload_rep
        “handlerName”:”general”,
        “result”:”SUCCESS”
    }
}

SV_CODE SV_Action( const char *ServiceName , char *szAction,  void *pUserData );

  • Description: Action function for Get / Set Command
  • Parameter:

           - const char * ServiceName (in) :    Service Name => HDD_PMQ

            - char *                     szAction (in) :    Action Command with JSON

            - void *                 pUserData ( in):    User data will return when result is callbacked

  • Return value:

           SV_CODE  - SV_OK               : Successful
                               - SV_ER_FAILED: Failed to call

  • History:   06/26/2017 Modified
  • Example:

            ServiceName : HDD_PMQ

             szAction: 

{  
  "susiCommData":{  
     "sessionID":"2746E3B65BAB115338B9668CDC5C35C4",
     "sensorIDList":{  
        "e":[  
           {  
              "n":"SenHub/Info/sw"
           }
        ]
     },
     "commCmd":523,
     "requestID":0,
     "agentID":"",
     "handlerName":"SenHub",
     "sendTS":1466057267
  }
}

             Reply: 

                 Topic: /cagent/admin/<devID>/agentactionreq 

{  
  "susiCommData":{  
     "commCmd":524,
     "handlerName":"SenHub",
     "sessionID":"2746E3B65BAB115338B9668CDC5C35C4",
     "sensorInfoList":{  
        "e":[  
           {  
              "n":"/Info/sw",
              "sv":"1.0.00",
              "StatusCode":200
           }
        ]
     }
  }
}

Release & Sample Code

Item Package Name Date Note Download ( Windows )
1 ServiceSDK_v1.0.1beta_20170704.zip
 2017/07/04 initial beta release v1.0.1_beta
2 EISServiceSDKSetup_1.0.3.zip
 2017/12/28
v1.0.3
Retrieved from "https://ess-wiki.advantech.com.tw/wiki/index.php?title=EIS_Service_SDK&oldid=17214"