Docs

You are here:
RCM Hub API for gateway

Using the RCM Hub API for gateway

Functions that constitute the API for field devices

All the functions that form the RCM Hub gateway API begin with RCMHUB_GW_ prefix.

Required header file

In order to use the RCM Hub API for gateway you must include the "rcm_hub.h" header file

#include "rcm_hub.h"

This includes all the necessary components to work with the RCM Hub APIs.

Starting a network

The connection descriptor

You start by defining a structure (RCMHUBGatewayConnection), that will hold all the information about the RCMHUB gateway connection. The structure needs to be initialized using the RCMHUB_GW_Init function. This call allocates all the necessary resources for the gateway code so don't forget to call the RCMHUB_GW_Deinit when you're done with the work to clean everything up

#include "rcm_hub.h"
// define the RCM Hub gateway descriptor
void myGatewayApp(void) {
// initialize the descriptor
RCMHUB_GW_Init(&myGateway);
// TODO... (read on)
// deinitialize everything and free all resources
RCMHUB_GW_Deinit(&myGateway);
}

Once this is done, you're ready to start up the wireless network.

Establishing new RCM network

In order to start up new network your device needs to know three things:

  • what will be the PHY used by the network (there are two options: see RCMPHY)
  • what is the network name
  • on what physical interface is the RCM module connected

The PHY and network name must be set to the same values across all communicating devices. This is usually done during device commissioning or at production.

You also need to know, what is the physical interface that your host device uses to connect to the RCM module. It usually is an UART/USART port or a serial/tty port. The IODevice interface that will be used should be provided by the HALFRED port for your hardware platform.

To establish a new network call the RCMHUB_GW_StartNetwork function. In the following example we will assume, that the RCM module is connected using USART1 port, the PHY used is 20 kbps DSSS-BPSK and the network name is "demo-net".

#include "rcm_hub.h"
// define the RCM Hub gateway descriptor
void myGatewayApp(void) {
// initialize the descriptor
RCMHUB_GW_Init(&myGateway);
// start the network
if (RCMHUB_GW_StartNetwork(&myGateway, USART1, RCM_PHY_20KBPS, "demo-net") {
// network established
// TODO... (read on)
// stop networking
RCMHUB_GW_StopNetwork(&myGateway);
}
// deinitialize everything and free all resources
RCMHUB_GW_Deinit(&myGateway);
}

To stop the network and disconnect the gateway use the RCMHUB_GW_StopNetwork function.

Interacting with the field devices

Once the network is started, the field devices can join it and send their data to the gateway. The gateway recognizes the field devices and identifies them by a unique ID number called UID. Each field device can also register a set of sensors, each of them identified by a number called SensorID. All this information is stored within the RCM Hub structures in gateway and is accessible through the following functions:

The RCMHUB_GW_GetFieldDeviceCount function returns the number of field devices registered in the gateway.

To get information about each of these field devices you can use the RCMHUB_GW_GetFieldDeviceByIndex function. To get information about a specific device identified by a UID you can use the RCMHUB_GW_GetFieldDeviceByUID. Both of these functions return pointer to a field device descriptor structure (RCMHUBFieldDeviceDescriptor).

To get to the description of registered sensors in each of the field devices you can use the RCMHUB_GW_GetSensor function.

Callbacks

The RCM Hub provides gives a way to incoming data as soon as it arrives through callbacks.

The RCMHUB_GW_SetCallbackOnSensorRegistration function allows to register a callback, that will be called when a new sensor is registered for a field device.

The RCMHUB_GW_SetCallbackOnSensorDataReceived function allows to register a callback, that will be called when a new sensor data arrives.

Go to Top