Docs

You are here:
Sending and receiving messages

The rcm:Message class encapsulates a single message in the RCM protocol.

Apart from the payload, each message has the following properties:

  • source address (short or UID)
  • destination address (short, UID, group or broadcast)
  • source endpoint (see Endpoints)
  • destination endpoint (see Endpoints)
  • radius (maximum number of network hops the message can travel)
  • ack mode (message requires acknowledgment or not)

In addition, received messages also carry information about:

  • link quality indicator (LQI)
  • received signal strength indicator (RSSI)

Preparing and sending outgoing messages.

The default rcm::Message constructor provides a single, general-purpose, uninitialized message.

The rcm:Message class provides three methods of initializing messages in order to prepare them to be sent. These methods differ depending on the type of destination address used:

Once the message is ready it can be sent via a rcm::Endpoint using rcm::Endpoint::sendMessage method.

The following example illustrates all three methods of sending messages:

#include "rcmpp.h"
int rcmpp_message_sending_example(const char* portName)
{
int result = 0;
try {
// construct the connection object
rcm::Connection rcm(portName);
// set UID
rcm.setUID(0x0123456789abcdee);
// configure networking
rcm.configureNode(RCM_DEVICE_TYPE_ROUTER, 0x1122334455667788, RCM_ADDRESSING_SCHEME_STATIC, 1);
// register endpoint 1
rcm::Endpoint& ep1 = rcm.registerEndpoint(1);
// start networking
if (rcm.startNetworking()) {
// create a message object
// prepare the message to send using short destination addressing mode
// dstAddr = 0 : destination address in short form (16 bit) - 0 is the address of the coordinator
// dstEndpoint = 1 : destination endpoint
// data = "Hello! (shortAddr)" : data to send
// dataSize = 18 : size of data to send in number of bytes
// reqAck = true : the message should be acknowledged
msg.initOutgoingUsingShortAddr(0, 1, "Hello! (shortAddr)", 18, true);
// send the message through endpoint 1
if (false == ep1.sendMessage(msg)) {
// unable to send message
result = 1;
}
// some delay
OS_Sleep(1000);
// prepare the message to send using UID destination addressing mode
// dstUID = 0x0x0123456789abcdef : destination UID, should be the UID of the coordinator
// dstEndpoint = 1 : destination endpoint
// data = "Hello! (uid)" : data to send
// dataSize = 12 : size of data to send in number of bytes
// reqAck = true : the message should be acknowledged
msg.initOutgoingUsingUID(0x0123456789abcdef, 1, "Hello! (uid)", 12, true);
// send the message through endpoint 1
if (false == ep1.sendMessage(msg)) {
// unable to send message
result = 2;
}
// some delay
OS_Sleep(1000);
// prepare the message to send using broadcast
// dstEndpoint = 1 : destination endpoint
// data = "Hello! (broadcast)" : data to send
// dataSize = 18 : size of data to send in number of bytes
msg.initOutgoingUsingBroadcast(1, "Hello! (broadcast)", 18);
// send the message through endpoint 1
if (false == ep1.sendMessage(msg)) {
// unable to send message
result = 3;
}
// some delay
OS_Sleep(1000);
// leave the network
rcm.stopNetworking();
}
}
catch(rcm::exception &e) {
result = 100;
}
catch(std::exception &e) {
result = 101;
}
catch (...) {
result = 102;
}
return result;
}

Receiving messages.

There are basically two methods of receiving messages:

  • polling the endpoint
  • installing a message filter in the endpoint

The basic method is polling the rcm::Endpoint object for new messages using rcm::Endpoint::getPendingMessage method. In addition, the rcm::Endpoint::getPendingMessagesCount returns the number of messages awaiting in the reception queue.

The following example illustrates the endpoint polling:

#include "rcmpp.h"
int rcmpp_message_receiving_example(const char* portName)
{
int result = 0;
try {
// construct the connection object
rcm::Connection rcm(portName);
// set UID
rcm.setUID(0x0123456789abcdef);
// configure networking
rcm.configureNode(RCM_DEVICE_TYPE_COORDINATOR, 0x1122334455667788, RCM_ADDRESSING_SCHEME_STATIC, 0);
// register endpoint 1
rcm::Endpoint& ep1 = rcm.registerEndpoint(1);
// start networking
if (rcm.startNetworking()) {
do {
// wait for message for 10 seconds
msg = ep1.getPendingMessage(10000);
// if no message is received, we quit the loop
} while (msg);
// leave the network
rcm.stopNetworking();
}
}
catch(rcm::exception &e) {
result = 100;
}
catch(std::exception &e) {
result = 101;
}
catch (...) {
result = 102;
}
return result;
}

Another method is installing message filter. See Message filters for details.

Both of these methods can also be combined. All messages that do not get filtered will be stored in the endpoint reception queue and can be received using endpoint polling. Note however, that combining two approaches may affect code clarity.

Go to Top