Docs

You are here:
RCM Hub API for field devices

Using the RCM Hub API for field devices

Functions that constitute the API for field devices

All the functions that form the RCM Hub field device API begin with RCMHUB_FD_ prefix.

Required header file

In order to use the RCM Hub API for field devices 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.

Connecting to the network

The connection descriptor

You start by defining a structure (RCMHUBFieldDeviceConnection), that will hold all the information about the RCMHUB field device connection. The structure needs to be initialized using the RCMHUB_FD_Init function.

#include "rcm_hub.h"
// define the RCM Hub field device descriptor
void myFieldDeviceApp(void) {
// initialize the descriptor
RCMHUB_FD_Init(&myFieldDevice);
// TODO... (read on)
}

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

Establishing connection to the RCM network

To connect to the RCM network as a field device your device need to be in wireless range of a gateway or a router. Your device needs to know four things:

  • what is 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
  • what is the device role

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.

The last thing is to decide if your device will act as a router or as an end-device (see RCMHUBFieldDeviceRole).

To connect to the network call the RCMHUB_FD_Connect 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, the network name is "demo-net" and we are developing an end-device.

#include "rcm_hub.h"
// define the RCM Hub field device descriptor
void myFieldDeviceApp(void) {
// initialize the descriptor
RCMHUB_FD_Init(&myFieldDevice);
// try to connect to the network
if (RCMHUB_FD_Connect(&myFieldDevice, USART1, RCM_PHY_20KBPS, "demo-net", ENDDEVICE) {
// connection established
// TODO... (read on)
// disconnect
RCMHUB_FD_Disconnect(&myFieldDevice);
}
}

Ending the connection to the RCM network

Once you're done networking you should call the RCMHUB_FD_Disconnect function. This closes the wireless connection.

What happens if I don't disconnect?

It won't harm the network. Other devices will notice that your field device stopped collaborating. The RCMHUB_FD_Disconnect function is only required to disable your RCM module locally.

Sending sensor data to the gateway

In order to send data to the gateway you need to register your sensors, collect their values and schedule the transmission.

Registering sensors

The RCMHUB_FD_RegisterSensor function registers a sensor. Each sensor registered in the RCM Hub library has:

  • a name (string)
  • a unit (string)
  • a value type (integer or float)

Here's an exemplary call:

SensorID tempSendorID = RCMHUB_FD_RegisterSensor(&myFieldDevice, "temperature", "C", RCMHUB_FLOAT);
SensorID humSendorID = RCMHUB_FD_RegisterSensor(&myFieldDevice, "humidity", "%", RCMHUB_INT);

The value returned is the ID of the registered sensor.

Collecting sensor values

Once the sensors are registered, we can build a data set using RCMHUB_FD_AppendSensorValueInt and RCMHUB_FD_AppendSensorValueFloat functions:

SensorID tempSendorID = RCMHUB_FD_RegisterSensor(&myFieldDevice, "temperature", "C", RCMHUB_FLOAT);
SensorID humiditySendorID = RCMHUB_FD_RegisterSensor(&myFieldDevice, "humidity", "%", RCMHUB_INT);
RCMHUB_FD_AppendSensorValueFloat(&myFieldDevice, tempSendorID, 20.5);
RCMHUB_FD_AppendSensorValueInt(&myFieldDevice, humiditySendorID, 45);

Sending collected sensor values

Once your data set is ready, it can be sent using the RCMHUB_FD_SendSensorValues function. This call does two things:

  • it prepares one or more packets (RCM messages) to store the whole dataset
  • it wakes up the radio module (if necessary) and schedules sending of these packets
  • it clears the dataset so you can build one up again

A complete working example

So here is a complete working example of a function/thread that connects to the network, and periodically sends out 2 sensor values:

int fieldDeviceThread(void* param) {
// define the RCM Hub field device descriptor
// Initialize the descriptor
RCMHUB_FD_Init(&myFieldDevice);
// Connect to the network
if(true == RCMHUB_FD_Connect(&myFieldDevice, BSP_GetIODeviceForRCM(), RCM_PHY_20KBPS, settings->networkName, settings->role)) {
// Register sensors
SensorID tempSensorID = RCMHUB_FD_RegisterSensor(&myFieldDevice, "temp", "C", RCMHUB_FLOAT);
SensorID humiditySensorID = RCMHUB_FD_RegisterSensor(&myFieldDevice, "humidity", "%", RCMHUB_INTEGER);
// Check if both sensors are registered successfully
if (tempSensorID != 0 && humiditySensorID != 0) {
// Main loop
while(true) {
// Check if we are still in the network
if(RCMHUB_FD_IsConnected(&myFieldDevice)) {
// Prepare data to send
RCMHUB_FD_AppendSensorValueFloat(&myFieldDevice, tempSensorID, 20.5));
RCMHUB_FD_AppendSensorValueInt(&myFieldDevice, humiditySensorID, 45));
// Send data
}
// Sleep for the given interval (if OS tick is every 1ms this gives one minute)
OS_Sleep(60*1000);
} // while
}
RCMHUB_FD_Disconnect(&myFieldDevice);
}
return 0;
}
Go to Top