WISE-Agent Sample Handler

In WISE Agent, we implement several Software Modules to access sensor data or control target device, we called Plugins (or Handlers we called before).

Each plugin is designed to handle specific jobs, such as:

• Sensor Plugin: the plugin access sensor data through Sensor driver or 3rd party library, or
• Remote Control Plugin:  the plugin execute remote command on target device.

To support customized plugins, we also defined a set of APIs, called Plugin (Handler) APIs. 

User can implement their own Handler with these Plugin (Handler) APIs to access their sensor data or control their devices and plugged by WISE Agent to communicate with RMM Server.

Architecture

In Plugin (Handler) Architecture, the Plugin (Handler) APIs is the skin of Plugin. Developer need to implement the APIs defined in the Plugin APIs, then the WISE Agent Handler loader will link the pre-defined APIs dynamically.

The Handler Kernel Library is the bone of the Plugin. This library will handle most of the functions in a Plugin, Such as: Gat Capability, Auto Report Start/Stop, Get/Set Sensor Data and basic Threshold Rule support.

The Message Structure is the main structure to describe the sensor data and interact between Handler Kernel and Custom Data Access. In Handler Kernel, the library will generate the handshake message based on the Message Structure.

The Message Generator library provides several APIs to describe the custom sensor data in a Message Structure.

In the Custom Data Access block, user needs to implement the function to access data from 3^rd party library or drivers in platform. And update the sensor data in Message Structure to report those data to the RMM Server through Handler Kernel.

Developer only need to concerned about how to get the sensor data and generate theMessage Structure by Message Generator in Custom Data Access block.

Plugin (Handler) APIs

List

int Handler_Initialize( HANDLER_INFO *handler );

Description

• This function initializes any objects or variables of this handler

Parameters

• handler [POINTER]
  • the structure to exchange the handler information between WISE Agent and Handler.

Return Values

• [-1|0] Error or Success.

---

int Handler_Get_Status( HANDLER_THREAD_STATUS * pOutStatus );

Description

• This function will retrieve Handler Threads Status. Agent will restart current Handler or restart Agent self if busy.

Parameters

• pOutStatus [POINTER]
  • the return status of handerl, the enumerate: 
    • handler_status_no_init = -1,
    • handler_status_init,
    • handler_status_start, 
    • handler_status_stop, 
    • handler_status_busy

Return Values

• [-1|0] Error or Success.

---

void Handler_OnStatusChange( HANDLER_INFO *handler );

Description

• This function will be called while CAgent connection status updated.

Parameters

• handler [POINTER]
  • the pointer of Handler Info structure.

Return Values

• None.

---

int Handler_Start( void );

Description

• Start handler thread.

Parameters

• None.

Return Values

• [-1|0] Error or Success.

---

int Handler_Stop( void );

Description

• Stop handler thread.

Parameters

• None.

Return Values

• [-1|0] Error or Success.

---

void Handler_Recv( char * const topic, void* const data, const size_t datalen, void *pRev1, void* pRev2  );

Description

• Received Packet from Server.

Parameters

• topic[POINTER]
  • MQTT topic string
• data[POINTER]
  • pointer of received payload.
• datalen[NUMBER]
  • received payload size
• pRev1[POINTER]
  • preserved pointer.
• pRev2[POINTER]
  • preserved pointer.

Return Values

• None.

---

int Handler_Get_Capability( char ** pOutReply );

Description

• Get Handler Information specification. 
• Release allocated mamory by calling Handler_MemoryFree.

Parameters

• pOutReply [POINTER]
  • double-pointer of capability string memory.

Return Values

• [-1|0] Error or Success.

---

void Handler_MemoryFree(char *pInData);

Description

• Free the mamory allocated for Handler_Get_Capability

Parameters

• pInData[POINTER]
  • pointer of capability string memory.

Return Values

• None.

---

void Handler_AutoReportStart(char *pInQuery);

Description

• Start Auto Report

Parameters

• pInQuery[POINTER]
  • pointer of  request string.

Return Values

• None.

---

void Handler_AutoReportStop(char *pInQuery);

Description

• Stop Auto Report

Parameters

• pInQuery[POINTER]
  • pointer of  request string.

Return Values

• None.

Handler Info Structure

typedef struct HANDLER_INFO
{
    char Name[MAX_TOPIC_LEN]; // The handler name
    char ServerIP[DEF_MAX_STRING_LENGTH];
    int ServerPort;
    char WorkDir[DEF_MAX_STRING_LENGTH];
    int RequestID;
    int ActionID;

    void* loghandle; // log file handler

    cagent_agent_info_body_t * agentInfo; // Info of the Agent
    HandlerSendCbf sendcbf; // Client Send information (in JSON format) to Cloud Server
    HandlerSendCustCbf sendcustcbf; // Client Send information (in JSON format) to Cloud Server with custom topic
    HandlerSubscribeCustCbf subscribecustcbf; // Client subscribe the custom topic to receive message from Cloud Server
    HandlerSendCapabilityCbf sendcapabilitycbf; // Client Send Spec.Info (in JSON format) to Cloud Server with SpecInfo topic
    HandlerAutoReportCbf sendreportcbf; // Client Send report (in JSON format) to Cloud Server with AutoReport topic
    HandlerSendEventCbf sendeventcbf; // Client Send Event Notify (in JSON format) to Cloud Server with EventNotify topic
}HANDLER_INFO, Handler_info;

Description

• The structure for Handler Information, defined in susiaccess_handler_api.h.

Parameters

• Name[POINTER]
  • handler name
• ServerIP[POINTER]
  • Server URL or IP Address.
• ServerPort[NUMBER]
  • Server (MQTT broker) listen port. 
• WorkDir[POINTER]
  • current executable binary file location.
• RequestID[NUMBER]
  • Unique Handler command resuest ID.
  • Not used in V3.1 or later version, preserved for V3.0
• ActionID[NUMBER]
  • Unique Handler command responseID.
  • Not used in V3.1 or later version, preserved for V3.0
• loghandle[POINTER]
  • the file handle of Log library
• agentInfo[POINTER]
  • the pointer of agent information.
• sendcbf[POINTER]
  • the function pointer to send common message on topic: "/cagent/admin/<ID>/agentactionreq".
• sendcustcbf[POINTER]
  • the function pointer to send custom message on customized topic.
• subscribecustcbf[POINTER]
  • the function pointer to subscribe a callback function to receive message from customized topic.
• sendcapabilitycbf[POINTER]
  • the function pointer to send handler capability on topic: "/cagent/admin/<ID>/agentactionreq".
• sendreportcbf[POINTER]
  • the function pointer to send sensor data report on topic: "/cagent/admin/<ID>/deviceinfo".
• sendeventcbf[POINTER]
  • the function pointer to send event notify on topic: "/cagent/admin/<ID>/eventnotify".

Mesage Generator APIs

List

MSG_CLASSIFY_T* IoT_CreateRoot(char* handlerName);

Description

• Create the Root Node.

Parameters

• handlerName[POINTER]
  • the name root node.

Return Values

• (MSG_CLASSIFY_T*)
  • result pointer

---