Preliminary

The CHAILink client API has three types of functions.

Main functions : these few functions are related with CHAILink client operation. They are named CLC_xxx such as CLC_Init, CLC_DoProcess, ... For their usage see following sections Initialization and Runtime.
Local data functions : these functions manipulate local data structure like messages, values ... Information about these function can be found in:
CopperLan functions : these functions generally operate on CHAI objects and require communication with the host (Computer or VNM Chip). These functions can only be called in the CopperLan context (see Runtime for more information). If ENABLE_RUNTIMECHECK is defined in the customization file, a call to one of these functions will fail and return the CLC_ErrorCode_General_CannotCallFromSystem code.

Initialization

The CHAILink Client Initialization process consist in:

A static phase. The customization of the CHAILink Client itself by modifying the CLC_Customization.h file (see CHAI Link client customization).
At runtime. The call to the CLC_Init function. This call is very important as it defines:
- All callbacks for the application, notifications and asynchronous returns; (See CLC_Callbacks structure for more details).
- The transport interface. This interface provided by the transport, enables the CHAILink Client to perform its IO duties. Transport drivers can be found in various samples, especially for the CopperDuino board (UART and USB). For more information about CopperDuino please contact us. For more information about Transport, see CHAILink Client Transport.
- The Keep Alive activation. The keep-alive feature is important in a release build in order to keep Client and Server synchronized, but it can be problematic while debugging a client application.

Example;

    CLC_Callbacks cb;
    // Prepare the callback definition structure
    cb.Application.pfnCHAILinkErrorCB = App_CHAILinkErrorCB;
    cb.Application.pfnCHAILinkConnectionStateChangedCB = App_CHAILinkConnectionStateChangedCB;
    cb.Application.pfnCPDoProcess= App_CPDoProcess;
    cb.Application.pfnSystemDoProcess = App_SystemDoProcess;
    cb.Application.pErrorCBParam = NULL;
    cb.Application.pConnectionStateChangedParam = NULL;
    cb.Application.pCPDoProcessParam = NULL;
    cb.Application.pSystemDoProcessParam = NULL;
#if defined(ARH_ENABLED) || defined(FORCE_ALL_CALLBACKS)
    cb.pARHCallbackList = &g_ARHCallbacks;
#endif
    cb.pNHCallbackList = &g_NHCallbacks;
    return CLC_Init(
        // Callbacks settings
        &cb, 
        // Transport settings
        pTransportInterface,
        // TRUE if keep alive between CLC and CLS is active
        TRUE);

Runtime

The CHAILink Client is designed to work in cooperative mode in a single threaded environment. It processes three tasks:

The system task. The entry point for this task is defined in CLC_Callbacks (pfnSystemDoProcess in CLC_Callbacks::Application). In this task, the application has to process IO (driver, backgroud processing, ...) but cannot use CopperLan functions.
The CopperLan task. The entry point for this task is defined in CLC_Callbacks (pfnCPDoProcess in CLC_Callbacks::Application). In this task, the application has to do CopperLan duties (send messages, start explorations, ...). This task runs in CopperLan context and can call all CopperLan functions.
The notification task. This task runs in CopperLan context and can call all CopperLan functions. its callbacks are:
- The connection state changed call back (pfnCHAILinkConnectionStateChangedCB in CLC_Callbacks::Application).
- All notification callbacks (CLC_Callbacks::pNHCallbackList).
- All asynchronous returns (CLC_Callbacks::pARHCallbackList).

The CHAILink Client can work in two modes:

It uses its own scheduler. After calling CHAILink initialization, the application call CLC_StartScheduler. This function should never return; it distributes processing to the three tasks.
The application uses its scheduler. In this mode, the application is responsible for calling regularly the CLC_DoProcess function. This function allocates processing time to the CopperLan task and the notification task. In both modes, when a CopperLan function is called in the CopperLan context, the system task (pfnSystemDoProcess in CLC_Callbacks::Application) is continuously called while the CHAILink Client is waiting for the response.

Note: The Error callback (pfnCHAILinkErrorCB in CLC_Callbacks::Application) notifies application of a low-level error. The context in this notification is not defined.

Using CLC_StartScheduler

1. Application initializes the CHAILink Client (CLC_Init)
2. Application starts the CHAILink Client scheduler (CLC_StartScheduler)
3. The CopperLan Task is called.
4. The CopperLan Task calls CopperLan functions.
5. The CopperLan function calls the system task while waiting for the response. Step 3 to 5 can occur several times.
6. The notification task are processed as necessary.
7. The notification task calls CopperLan functions.
8. The CopperLan function calls the system task while waiting for the response. Step 6 to 8 can occur several times.
9. The Scheduler calls the system task and returns to step 3.

Using CLC_DoProcess

1. Application initializes the CHAILink Client (CLC_Init)
2. The application in its main loop calls CLC_DoProcess.
3. The CopperLan Task is called.
4. The CopperLan Task calls CopperLan functions.
5. The CopperLan function calls the system task while waiting for the response. Step 3 to 5 can occur several times.
6. The notification task are processed as necessary.
7. The notification task calls CopperLan functions.
8. The CopperLan function calls the system task while waiting for the response. Step 6 to 8 can occur several times.
9. The CLC_DoProcess function returns.
10. The application calls the system task to process IO and returns to step 2.