IoTGateway/SDK/NALInterface
From ESS-WIKI
Contents
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_Manager_GetVersion( char *psVersion, int BufLen );
Description
To return the version of your "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 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
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.