IoTGateway/SDK/NALInterface

From ESS-WIKI
Jump to: navigation, search

Abstract

The main way WSN API SDK can be extended is to add new "NET" modules into its palette. Customer can follow the general C API, structure, command, event and define ( called "NAL" layer Interface ) to add its own "NET" modules (ex: zigbee, bluetooth... ).

Basic Definition

Definition

MAX_SN_INF_NAME       16  // Max size of Interface's Name
MAX_SN_INF_ID         64  // Max size of Interface's Unique ID
MAX_SN_INF_NUM         8  // Max supports interface number
MAX_SN_COM_NAME       32  // Max size of Communication(Net) Type Name
MAX_SN_UID            64  // Max size of SenHub Unique ID
MAX_SN_HOSTNAME       32  // Max size of SenHub Name
MAX_SN_SNO            32  // Max size of SenHub's Serial Number
MAX_SN_PRODUCT_NAME   32  // Max size of SenHub's Product Name

Callback Event ID

typedef enum {
        // Interface: 1000 ~ 1999
        SN_Inf_UpdateInterface_Data      = 1000,  // Update Interface data from Sensor Network Library  
        SN_Inf_SendInfoSpec              = 1001,  // Update Interface InfoSpec (Capability)	 
        // Sensor Node: 2000 ~ 2999
        SN_SenHub_Register               = 2000,  // Sensor Hub Register
        SN_SenHub_SendInfoSpec           = 2001,  // Update Sensor Hub InfoSpec (Capability)
        SN_SenHub_AutoReportData         = 2002,  // Update Sensor Hub data
        SN_SenHub_Disconnect             = 2003,  // Sensor Hub disconnect
        SN_SetResult                     = 3000,	 
 }SN_EVENT_ID;

Control ID

typedef enum {
        SN_Set_ReportSNManagerDataCbf  = 3000,
        // Get / Set
        SN_Inf_Get                     = 6000,
        SN_Inf_Set                     = 6001,
        SN_SenHub_Get                  = 6020,
        SN_SenHub_Set                  = 6021,
 }SN_CTL_ID;

Return Code

typedef enum {
       SN_ER_NOT_IMPLEMENT             =  -13,   /*	Does Not Support this command       (501) */
       SN_ER_TIMEOUT                   =  -12,   /*	Request Timeout	                    (408) */
       SN_ER_SYS_BUSY                  =  -11,   /*	System is busy                      (503) */
       SN_ER_VALUE_OUT_OF_RNAGE        =  -10,   /*	Value is out of range               (416) */
       SN_ER_SYNTAX_ERROR              =   -9,   /*	Format is correct but syntax error  (422) */
       SN_ER_FORMAT_ERROR              =   -8,   /*	Format error                        (415) */
       SN_ER_REQUEST_ERROR             =   -7,   /*	Request error                       (400) */
       SN_ER_RESOURCE_LOSE             =   -6,   /*	SenHub disconnect                   (410) */
       SN_ER_RESOURCE_LOCKED           =   -5,   /* 	Resource is in setting              (426) */
       SN_ER_NOT_FOUND                 =   -4,   /*	Resource Not Found                  (404) */
       SN_ER_WRITE_ONLY                =   -3,   /*	Read Only                           (405) */
       SN_ER_READ_ONLY                 =   -2,   /*	Write Only                          (405) */
       SN_ER_FAILED                    =   -1,   /*	Failed                              (500) */
       SN_OK                           =    0,   /*	Success	                            (200) */
       SN_INITIALIZED                  =    1,   /*	Library had initialized                   */
 }SN_CODE;

Basic In/Out Data Structure

Input Data Base Structure 

typedef struct _InBaseData
{
   char            *psType; // 64 ( reference size )
   int           iSizeType; // Buffer size of psType
   char            *psData; // 2048 ( reference size )
   int           iSizeData; // Buffer size of psData 
   void           *pExtend; // Extend		
 }InBaseData;

Input Data Class Structure 

typedef struct _InDataClass
{
   int                iTypeCount;  // Number of Type
   InBaseData  *pInBaseDataArray;  // Point of first BaseInData Array
   void                *pExtened;  // Extend
 }InDataClass;

Output Data Base Structure 

typedef struct _OutBaseData
{
   char                  *psType;   // 64  ( reference size )
   int                 iSizeType;   // Buffer size of psType
   char                  *psData;   // 2048  ( reference size ) => If the data length is more than buffer size, user can reallocate this buffer point and re-assign the iSizeData.
   int                *iSizeData;   // Buffer size of psData
   void                 *pExtend;   // Extend
}OutBaseData;

typedef struct _OutDataClass
{
   int                 iTypeCount;  // Number of Type
   OutBaseData *pOutBaseDataArray;  // Point of the first BaseOutData Array
   void                 *pExtened;  // Extend		
}OutDataClass;

Structures for Network Interface

Net Interface's Capability 

typedef struct _SNInfInfo
{
   char          sInfName[MAX_SN_INF_NAME];  // Interface Name
   char              sInfID[MAX_SN_INF_ID];  // Unique ID for identify (ex: MAC )
   OutDataClass               outDataClass;  // iTypeCount = 1,   psType: Info, psData:{"n":"SenHubList","sv":"","asm":"r"},{"n":"Topology","sv":"","asm":"r"},{"n":"Health","v":-1,"asm":"r"},
                                                                                       {"n":"Name","sv":"WSN0","asm":"r"}, {"n":"sw","sv":"1.0.0.1","asm":"r"},{"n":"reset","bv":0,"asm":"rw"}
   void                         *pExtened;   // Reserve for use
}SNInfterfaceInfo,SNInfInfo;

Get Multi Net Interfaces' Capability 

typedef struct _SNInfInfos
{
    char          sComType[MAX_SN_COM_NAME];  // Communication Type Name
    int                                iNum;  // Number of Sensor Network Interface
    SNInfInfo        SNInfs[MAX_SN_INF_NUM];  // Detail Information of Sensor Network Interface
}SNInterfaceInfos,SNInfInfos,SNMultiInfInfo;

Auto Update Net Interface InfoSpec 

typedef struct _SNInterfaceSpec
{
 char         sInfName[MAX_SN_INF_NAME];  // Interface Name
 char             sInfID[MAX_SN_INF_ID];  // Unique ID for identify (ex: 0000+MAC: remove '-' and ':' )
 InDataClass                inDataClass;  // iTypeCount = 1,   psType: Info, psData: {"n":"SenNodeList","sv":"","asm":"r"},{"n":"Topology","sv":"","asm":"r"},
                                                                                     {"n":"Health","v":-1,"asm":"r"},{"n":"Name","sv":"WSN0","asm":"r"},
                                                                                     {"n":"sw","sv":"1.0.0.1","asm":"r"},{"n":"reset","bv":0,"asm":"rw"}
 void                         *pExtened;
}SNInterfaceSpec,SNInfSpec;

Auto Update Multi Net Interfaces InfoSpec 

typedef struct _SNMultiInterfaceInfoSpec
{
  char              sComType[MAX_SN_COM_NAME];  // Communication Type Name
  int                                    iNum;  // Number of Sensor Network Interface
  SNInfSpec        aSNInfSpec[MAX_SN_INF_NUM];  // Detail Information of Sensor Network Interface
}SNInterfaceInfoSpec,SNMultiInfInfoSpec;

Auto Updating Sensor Network Interface Data Value 

typedef struct _SNInfData
{
   char            sComType[MAX_SN_COM_NAME];  // WSN
   char                sInfID[MAX_SN_INF_ID];  // Unique ID for identify (ex: MAC )
   InDataClass                   inDataClass;  // psType: Info,psData: {"n":"SenHubList","sv": "000EC6F0F830,000EC6F0F831,000EC6F0F832"},
                                                                       {"n": "Neighbor","sv": "000EC6F0F830,000EC6F0F831"},{"n": "Health","v": 90},
                                                                       {"n":"sw","sv":"1.0.0.1"},{"n":"reset","bv":0}
   void                            *pExtened;
}SNInterfaceData,_SNInfData;

Structures for SenHub

typedef struct _InSenData
{
   char                sUID[MAX_SN_UID];   // ( ex: MAC )
   InDataClass              inDataClass;   // psType: SenData, psData: {"n": "room temp","v": 26},{"n": "mcu temp","v": 42}			
                                           // psType: Net, psData: {"n":"Health","v":80,"asm":"r"}
   void                       *pExtened; 	
}InSenData;

typedef struct _OutSenData
{
   char                  sUID[MAX_SN_UID]; // ( ex: MAC )
   OutDataClass              outDataClass; // psType: SenData, psData: {"n": "room temp","v": 26},{"n": "mcu temp","v": 42}						
   void                         *pExtened;		 	
}OutSenData;

NHL APIs

Common APIs

Syntax

SN_CODE SN_Initialize( void *pInUserData );


Description

This function initializes the NAL module Library. To initial "NAL" module resources and variables in this function. 

Note: You need save address point of the input parameter pInUserData. Please pass the address to WSN Core when calling the event callback function. 
      WSN Core uses the address point to confirm which NAL module callback data.


Parameters

void *pInUserData

[in]the address point for tagging which NAL module.


Return Values

SNM__OK: Successfully to initial the NAL module.

SNM_FAILED: Failed to initial.


Syntax

SN_CODE SN_Uninitialize( void *pInParam);


Description

This function uninitialized the "NAL" Module. You must call this function before closing this module to release resources


Parameters

void *pInParam

[in] Reserve to use.


Return Values

SNM__OK: Successfully to uninitialized the NAL module.

SNM_FAILED: Failed to uninitialized .

Syntax

SN_CODE SN_Manager_GetVersion( char *psVersion, int BufLen );


Description

To get version of the "NAL" module.


Parameters

char *psVersion

[out]the buffer pointer to save the version of "NHL" module in string.
[in]the buffer size of psVersion


Return Values

SNM__OK: Successfully to get version of the "NHL" module.

SNM_FAILED: Failed to get.

Callback Function

Syntax

typedef SN_CODE SN_SetUpdateDataCbf( UpdateSNDataCbf pUpdateSNDataCbf);


Description

This function is used to set callback function point (UpdateSNDataCbf)


Parameters pUpdateSNDataCbf

[in]set the address of function point to receive the event callback from "NAL" module


Return Values

SNM__OK: Successfully to set the event callback function point.

SNM_FAILED: Failed to set.


Syntax

typedef SN_CODE UpdateSNDataCbf( const int CmdID, const void *pInData, const int InDatalen, void *pUserData, void *pOutParam, void *pRev1, void *pRev2 );


Description

This function is used to receive events that trigger by NAL module. (ex: A New SenHub Connected/Disconnected/Auto Report Sensor Data/Auto Report Interface Data)


Parameters

CmdID [in] event id. Refer to SN_EVENT_ID

  • pInData [in] address point of data structure. HAL returns data type structure depend on event id ( SN_EVENT_ID ).

InDatalen [in] length of the pInData

  • pUserData [in] HAL module needs return the user data point that passed in SN_Initialize


Return Values

SNM__OK: Successfully to process the callback event.

SNM_FAILED: Failed to process the callback event.


Examples for "NAL" Auto Updating to WSN Core SDK by Event Callback

Update IoTGW Interface InfoSpec

Description: "NAL" changes its own capability by updating Interface's InfoSpec. 

CmdID   : SN_Inf_SendInfoSpec (1001)
pInData : SNMultiInfInfoSpec
SNMultiInfInfoSpec:
sComType = WSN
iNum = 1
aSNInfSpec[0].sInfName = WSN0
aSNInfSpec[0].sInfID   = 852CF4B7B0E8
aSNInfSpec[0].inDataClass.iTypeCount  = 1
aSNInfSpec[0].inDataClass.pInBaseDataArray[0]->psType = Info
asSNInfSpec[0].inDataClass.pInBaseDataArray[0]->psData = {"n":"SenHubList","sv":"","asm":"r"},{"n":"Neighbor","sv":"","asm":"r"},{"n":"Health","v":-1,"asm":"r"},																													
                                                         {"n":"Name","sv":"WSN0","asm":"r"},{"n":"sw","sv":"1.0.0.1","asm":"r"},{"n":"reset","bv":0,"asm":"rw"}


Update IoTGW interface's data

Description: "NAL" auto updates these values of interface. 

CmdID   : UpdateInterface_data (1000)
pInData : SNInterfaceData
SNInterfaceData:
sComType = WSN
iNum = 1
aSNInfSpec[0].sInfName = WSN0
aSNInfSpec[0].sInfID   = 852CF4B7B0E8
aSNInfSpec[0].inDataClass.iTypeCount  = 1
aSNInfSpec[0].inDataClass.pInBaseDataArray[0]->psType = Info
asSNInfSpec[0].inDataClass.pInBaseDataArray[0]->psData = {"n":"SenHubList","sv": "000EC6F0F830,000EC6F0F831,000EC6F0F832"},{"n":"Neighbor","sv": "000EC6F0F830,000EC6F0F831"},
                                                         {"n":"Health","v": 90},{"n":"sw","sv":"1.0.0.1"},{"n":"reset","bv":0}


Info a new SenHub connecting with "NAL module

Description:To info the WSN Core SDK that a new SenHub connecting with "NAL" interface. 

CmdID   : SN_SenHub_Register (2000)
pInData : SenHubInfo
SenHubInfo:
sUID     (sv): 0000+MAC
sHostName(sv): WISE1020-MAC(4)
sSN      (sv): MAC
sProduct (sv): WISE1020


Info a new SenHub connecting with "NAL module

Description:To info the WSN Core SDK that a new SenHub connecting with "NAL" interface. 

CmdID   : SN_SenHub_Disconnect (2003)
pInData : InSenData
InSenData:
sUID = 000EC6F0F830
inDataClass.iTypeCount = 0
pExtened = NULL


Update capability (InfoSpec) of a SenHub

Description: Update capability of a SenHub 

CmdID   : SN_SenHub_SendInfoSpec (2001)
pInData : InSenData
InSenData:
sUID = 000EC6F0F830
inDataClass.iTypeCount = 4
inDataClass.pBaseDataArray[0]->psType = SenData
inDataClass.pBaseDataArray[0]->psData = {"n": "room temp","u": "Cel","v": 0,"min": 0,"max": 100,"asm": "r","type": "d","rt": "ucum.Cel","st": "ipso","exten": ""},
                                        {"n": "mcu temp","u": "Cel","v": 0,"min": 0,"max": 100,"asm": "r","type": "d","rt": "ucum.Cel","st": "ipso","exten": ""}
inDataClass.pBaseDataArray[1]->psType = Info
inDataClass.pBaseDataArray[1]->psData = {"n": "Name","sv": "WISE1020-MAC(4)","asm": "rw"},{"n":"sw","sv":"1.0.0.2","asm":"r"},{"n":"reset","bv":0,"asm":"rw"}
inDataClass.pBaseDataArray[2]->psType = Net
inDataClass.pBaseDataArray[2]->psData = {"n":"Health","v":80,"asm":"r"},{"n":"Neighbor","sv":"","asm":"r"},{"n":"sw","sv":"1.0.0.1","asm":"r"}
inDataClass.pBaseDataArray[3]->psType = Action
inDataClass.pBaseDataArray[3]->psData = {"n":"AutoReport", "bv":0, "asm":"rw"}


Update values of a SenHub

Description: Update values of a SenHub 

CmdID   : SenHub_AutoReportData (2002)
pInData : InSenData
InSenData:
sUID = 000EC6F0F830
inDataClass.iTypeCount = 2
inDataClass.pBaseDataArray[0]->psType = SenData
inDataClass.pBaseDataArray[0]->psData = {"n": "room temp","v": 26},{"n": "mcu temp","v": 42},{"n": "parking din","bv": 0}
inDataClass.pBaseDataArray[1]->psType = Net
inDataClass.pBaseDataArray[1]->psData = {"n":"Health","v":88},{"n":"Neighbor","sv":"852CF4B7B0E8,000EC6F0F831"}

Network Interface APIs

Syntax

SN_CODE SN_GetCapability( SNMultiInfInfo *pOutSNMultiInfInfo );


Description

"WSN" SDK Core calls the SN_GetCapability to get NAL's capability.


Parameters

pOutSNMultiInfInfo

[out] the SNMultiInfInfo point to save the NAL's capability


[Example] 

pOutSNMultiInfInfo->sComType = WSN
pOutSNMultiInfInfo->iNum = 1
pOutSNMultiInfInfo->SNInfs[0].sInfName = WSN0
pOutSNMultiInfInfo->SNInfs[0].sInfID   = 852CF4B7B0E8
pOutSNMultiInfInfo->SNInfs[0].outDataClass.iTypeCount  = 1
pOutSNMultiInfInfo->SNInfs[0].outDataClass.pOutBaseDataArray[0]->psType = Info
pOutSNMultiInfInfo->SNInfs[0].outDataClass.pOutBaseDataArray[0]->psData = {"n":"SenHubList","sv":"","asm":"r"},{"n":"Neighbor","sv":"","asm":"r"},
                                                                          {"n":"Health","v":-1,"asm":"r"},{"n":"Name","sv":"WSN0","asm":"r"},																										                            
                                                                          {"n":"sw","sv":"1.0.0.1","asm":"r"},{"n":"reset","bv":0,"asm":"rw"}

Return Values

SNM__OK: Successfully to get capability of the "NAL" module.

SNM_FAILED: Failed to get capability of the "NAL" module.


Syntax

SN_CODE SN_GetData( SN_CTL_ID CmdID, InSenData *pInSenData, OutSenData *pOutSenData );


Description

This function is used to get values of resource of "NAL" module.


Parameters

CmdID

[in] control id. Refer to SN_CTL_ID

pInSenData

[in] get which "NAL" resource value

pOutSenData

[out] return the value of "NAL" resoure


Return Values

SNM__OK: Successfully to get.

SNM_FAILED: Failed to get.


[Example]

To get value of the SenHub (000EC6F0F830)'s "room temp" sensor. 

CmdID = SN_SenHub_Get ( 6020 ) => Get Sensor Hub value
pInSenData:
sUID  = 000EC6F0F830
inDataClass.iTypeCount = 1
inDataClass.pBaseDataArray[0]->psType = SenData
inDataClass.pBaseDataArray[0]->psData = {"n": "room temp"}

pOutSenData:
SN_CODE     = SN_OK
sUID = 000EC6F0F830	  
outDataClass.iTypeCount = 1
outDataClass.pBaseOutDataArray[0].psType = SenData
outDataClass.pBaseOutDataArray[0].psData = {"n": "room temp","v":27}


Syntax

SN_CODE SN_SetData( SN_CTL_ID CmdID, InSenData *pInSenData, OutSenData *pOutSenData );


Description

This function is used to set value to "NAL" module.


Parameters

CmdID

[in] control id. Refer to SN_CTL_ID

pInSenData

[in] set value of the "NAL" resource

pOutSenData

[out] return the value of "NAL" resoure


Return Values

SNM__OK: Successfully to set.

SNM_FAILED: Failed to set.


[Example]

To set value of the SenHub (000EC6F0F830)'s "Name". 

CmdID = SN_SenHub_Set ( 6021 ) => Set Sensor Hub value
pInSenData:
sUID  = 000EC6F0F830
inDataClass.iTypeCount = 1
inDataClass.pBaseDataArray[0]->psType = Info
inDataClass.pBaseDataArray[0]->psData = {"n": "Name", "sv":"Demo"}

SN_CODE     = SN_OK
pOutSenData:
sUID = 000EC6F0F830	  
outDataClass.iTypeCount = 1
outDataClass.pBaseOutDataArray[0].psType = Info
outDataClass.pBaseOutDataArray[0].psData = {"n": "Name", "sv":"Demo"}
Retrieved from "https://ess-wiki.advantech.com.tw/wiki/index.php?title=IoTGateway/SDK/NALInterface&oldid=953"