Table of Contents
The connection structure
The first thing when working with the RCM library is to initialize and open a connection with an RCM radio module. The connection is represented by RCMConnection structure which encapsulates all the data related to the connection. A single RCMConnection is a central point of all the library API.
The connection structure is usually defined by the user. Each instance represents a single RCM radio module (usually there is only one in the system).
Once we have the connection structure, we can start using the RCM library API.
Opening the connection
The very first thing we want to do is to open the connection. We do that through a call to RCM_Open, however there are several concepts we need to grasp before we do that. Most of them have to do with the underlying libraries that are designed with portability in mind. Let's list and briefly discuss them:
The IODevice object
Internally, the RCM library relies on HALFRED(tm) hardware abstraction layer, which, among others, introduces a concept of IODevices - abstraction of peripherals that can read and write data (I/O). One example of such device will be a serial communication port through which we communicate with a RCM radio module. The HALFRED library port provides these objects or means of constructing them. We're going to need one in order to communicate with a RCM radio module. For the purpose of this tutorial let's assume that the port we're going to use is called USART1.
SCOM frame buffer
The RCM library relies on SCOM communication protocol when it comes to delivering and receiving information to and from a RCM radio module. The underlying SCOM library implementation is designed in a portable way, which among other implies that it should be adaptable to a range of hardware platforms, including small 8-bit microcontrollers. On such platforms it is often strongly encouraged NOT to use any dynamic memory allocation. Thus, by default the SCOM library requires the user to define a memory pool of a chosen size, called SCOM frame buffer, that the SCOM library can use to queue incoming and outgoing SCOM packets. The SCOM library also delivers a convenient macro for doing so called SCOM_DECLARE_FRAME_BUFFER, that we can use to construct a frame buffer. Here's an example:
It is worth to note, that on platforms that do not have stringent heap memory usage barriers, we can use different macro, called SCOM_DECLARE_FRAME_BUFFER_USING_HEAP, and declare frame buffer without upper limits (other than heap memory availability) on the number of frames it can fit:
In order to open a RCMConnection we are going to need such frame buffer. Let's assume that it is the one from the first example called frameBuffer
RCM message buffer
The RCM library follows the same principles as SCOM implementation. As the library handles RCM messages it also needs space to hold them. This space will be called message buffer, and the user is expected to provide one of it's choosen size. Again, we have a convenient macro to do so called RCM_DECLARE_MESSAGE_BUFFER:
Similar to SCOM, we have the RCM_DECLARE_MESSAGE_BUFFER_USING_HEAP macro to declare frame buffer without upper limits on the number of messages it can fit (other that heap memory availability):
For further purposes we will use the first approach - our message buffer will be called messageBuffer.
Clock provider
The RCM library as well as the underling SCOM protocol implementation deals with real-time communication. Thus we need to deliver the information about time in a most portable manner. To do so, the RCM library expects the user to deliver a function, that will return current time in ms. We will call that function clockProvider.
Finally we can construct a working code:
Note, that in the above example the RCM_Close function is used to close a previously opened connection and free all resources taken for that purpose.
Running the connection
Opening the connection does not make it operational yet. Due to library design choices related to portability, the RCM library expects the user to periodically run two functions:
- RCM_CommunicationProc which is the main communication engine
- RCM_FilterProc which runs SCOM frame filters, that the RCM library relies on
Both of these functions should be called periodically, with a rate acceptable to maintain a short response capability - around 10-50ms is a good approximation. Usually the functions can be called in a main loop or inside an operatin system thread.
The RCM library can make full use of an operating system. On target platforms covered by HALFRED operating system abstraction layer this is done automatically. On such platforms the user can simply call RCM_Run to start all threads necessary to run the connection. A complementary RCM_Stop is used to stop these threads
- usually prior to closing the connection.
At any given time the user can poll the connection state using RCM_GetConnectionState function.
The following example shows a typical pattern when working on an operating system supported by HALFRED abstraction layer:
Generated on Fri Aug 31 2018 09:37:14 for RCM API Library by
