C-CPP_SerialDriver_UserGuide

Overview

The Coronis SDK - SerialDriver API allows connecting your modem through a serial driver low level protocol.
Only the Coronis rs232Driver implementation is available in the current version.

The Serial Driver API offer service to manage the dataflow on the serial port and ensures to the upper layer that provided data are correct and correspond to those sent by the RF Modem:
open, close, send, receive, etc.

A more detailed information about RS232Driver implementation can be obtained from Serial Driver developer guide [RS232Driver_DevelopperGuide]

Getting started

1. Create user C project

First, you have to create a new C project into eclipse environment. Please read [How to create a C project in CDT eclipse] tutorial.

2. Import SerialDriver implementation

In this tutorial, we will use the Coronis RS232Driver implementation of SerialDriver API.

1. Get the last Coronis RS232Driver delivery package
2. Copy the RS232driver library to the root of the user project
   • csrs232driver.dll for Windows platform
   • libcsrs232driver.so for Linux platform
3. Copy the csrs232driver.properties file to the root of your project
4. Include header files of SerialDriver API
   • First solution (recommended), Import in user workspace, the com_coronis_sdk_serialdriver_api folder as an eclipse project.
   • Second solution, copy all the header files of SerialDriver API into a subfolder include of your project.
   • In both cases, user has to add the SerialDriver API folder into its C/C++ Build project properties->Include path compilation option.
5. Include the SerialFrame definition that must be used for Coronis RS232Driver implementation:
   • First solution (recommended), Import in user workspace, the com_coronis_sdk_domain folder as an eclipse project.
   • Second solution, copy serial_driver_types.h of Coronis domain into a subfolder include of your project.
   • In both cases, user has to add the serial_driver_types.h parent folder into its C/C++ Build project properties->Include path compilation option
   • Refer [SerialDriver Serial frame] for more information about the coronis serial frame definition
6. Include Generic constants header file of Domain module.
   • add the generic_constants.h parent folder into C/C++ Build project properties->Include path compilation option.
   • this file includes usefull constants definition like OK, NULL...

3. Load SerialDriver implementation

To use a serial driver implementation in accordance with the API, user must use specific mechanism of "library and function loading" to be able to call the API services from the library that implements the API.

• Let's have first a quick look to the SerialDriver loading mechanism, that is implemented into domain module:

  • The principle is to create a Serial driver loader structure which will contains a pointer to each function of the i_serial_driver_service.h method. With this structure, the user will be able to call each service of SerialDriver API.
  • This structure named SerialDriverLoader, is defined into header file com_coronis_sdk_domain/include/loader_serial_driver.h
  • 2 methods load_serial_driver and free_serial_driver are declared into file com_coronis_sdk_domain/src/external/loader_serial_driver.c, to allow the user to initialize or free the structure
  • The load method use native method for loading library and functions and make the link between the structure and the implemented services of the SerialDriver implementated library.
  • Extracted source that concerns the SerialDriver loading mechanism are available here [SerialDriver loading mechanism sources]

• To use this mechanism, user has 2 possibilities:

  • Get a copy of loader_serial_driver.h & loader_serial_driver.c source files of domain module into its project.
  • Make a local link to the domain folder which include the loader_serial_driver.c and exclude other file from project compilation.
  • In both case user has to add the loader_serial_driver.h parent folder into C/C++ Build project properties->Include path compilation option.

4. Send frame (main program)

In this tutorial, we suppose that user has connected a Waveport radio modem on Port COM4.
We will send the frame 0x5005, which correspond to the local service request READ_RADIO_ADDRESS. So we must receive spontaneously after the sending, a frame which begins with 0x51

1. Here are usual step that must be done before be able to send the frame:

   • Load RS232Driver library
   • Create a RS232Driver instance
   • Configure the instance
     • port ID setting
     • initialization (default configuration values)
   • Register a listener to receive spontaneous frame
   • Open the connection

2. Send the frame

3. At the end, following steps must be done before quit the program:

   • Close the current connection
   • Destroy the RS232Driver instance
   • Unload RS232Driver library.

5. Activate the Coronis Domain logger (optional)

Coronis Domain module offers a logging feature, that is used by the rs232driver implementation to give internal process information. To activate it, user has to follow these steps:

1. Copy the Domain library (Coronis RS232Driver delivery package) to the root of the user project
   • csdomain.dll for Windows platform
   • libcsdomain.so for Linux platform
2. Copy the cslogger.properties file to the root of your project
   • Edit the logger properties if needed (log level, destination file)

Resources

Source of main program can be found here : [C Serial Driver tutorial sources]

This example is available as an eclipse project (com_coronis_sdk_serialdriver_rs232driver_example.zip) inside the Coronis RS232Driver delivery package.

Going further

To have more details information about Serial Driver API, refer the documentation C SerialDriver API