Docs

You are here:
Performance testing

The RCM C++ library provides functions for performance testing featuring:

  • output power test
  • packet error rate (PER) measurement

Output power test.

The output power test is provided to easily measure the amount of power the radio module is configured to deliver.

In order to enable output power test, the device needs to be configured as a network coordinator and it needs to join (in this case - establish) the network. Once this is done, the application code can call rcm::Connection::startContinuousTX method, which causes the module to continuously output a radio signal.

BEWARE: Enabling continuous radio signal can jam other radio devices in range. This mode must be used with caution and only for evaluation purposes.

The following example illustrates the usage of output power test:

#include "rcmpp.h"
#include <iostream>
using namespace std;
int rcmpp_output_power_test_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);
// start networking
if (rcm.startNetworking()) {
// enable continuous TX output
rcm.startContinuousTX(PSEUDO_RANDOM_BIT_SEQUENCE, 0);
// 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;
}

Packet error rate (PER) measurement.

The packet error rate measurement is useful for characterizing a single radio link. Two devices are required to conduct a PER measurement. One device is configured as a network coordinator, the other one as a router. Once the router joins the network established by the coordinator, the PER test can start. During the test, the router sends a number of packets to the coordinator. When this is done, the router can request the PER test results from the coordinator. Each test is identified by a 32-bit unique identifier, that is chosen randomly.

During the PER test, a router is the source of packets. it thus needs to be configured to start the test. The rcm::Connection::startPERTest method starts the PER test and causes the router to send packets to the coordinator. The rcm::Connection::waitForPERTestEnd method can block the calling thread, until the test is finished . The rcm::Connection::getPERTestResultFromRemoteNode method can be used by the router to retrieve PER test results from the coordinator. In addition, the rcm::Connection::setPERTestHandler method allows to register an user-defined object, that will handle every incoming PER test progress information, that is reported from the radio module. It can be used to monitor the progress of the test.

The following example illustrates the usage of PER test on the router:

#include "rcmpp.h"
#include <iostream>
using namespace std;
// This class implements the PER test results handler
class PERHandler : public rcm::PERTestHandler
{
public:
void onTestProgress(rcm::Connection& connection, const RCMPERTestResult& result) {
cout << "Got PER results:" << endl;
cout << " testId = " << result.ID << endl;
cout << " currentPacket = " << result.currentPacket << endl;
cout << " successPackets = " << result.successPackets << endl;
cout << " totalPackets = " << result.totalPackets << endl;
if (result.currentPacket == result.totalPackets) {
cout << "FINAL PER = " << result.successPackets << "/" << result.totalPackets << endl;
}
}
};
int rcmpp_per_test_router_example(const char* portName)
{
int result = 0;
PERHandler perHandler;
unsigned int testId;
RCMPERTestResult testResult;
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);
// start networking
if (rcm.startNetworking()) {
// set up PER test results handler
rcm.setPERTestHandler(&perHandler);
// start PER test with 1000 packets against the coordinator (shortAddr = 0)
testId = rcm.startPERTest(0, 1000, 0);
// Wait for PER test end
if (rcm.waitForPERTestEnd(testId, 30000, testResult)) {
// Once the test is done, request results from remote node
if (rcm.getPERTestResultFromRemoteNode(0, testId, 10000, testResult)) {
// all OK!
} else {
// failed to get PER test results from remote node
result = 3;
}
} else {
// failed to finish PER test
result = 2;
}
// leave the network
rcm.stopNetworking();
} else {
// failed to join the network
result = 1;
}
}
catch(rcm::exception &e) {
result = 100;
}
catch(std::exception &e) {
result = 101;
}
catch (...) {
result = 102;
}
return result;
}

In case of the coordinator, which is a PER test receiver, no additional configuration or setup is necessary for the PER test to run. One optional thing is the use of rcm::Connection::setPERTestHandler, which the same as in the case of the router allows to register a handler that will be called every time the PER test progress information is reported from the radio module.

The following example illustrates the usage of PER test on the coordinator:

#include "rcmpp.h"
#include <iostream>
using namespace std;
// This class implements the PER test results handler
class PERHandler : public rcm::PERTestHandler
{
public:
void onTestProgress(rcm::Connection& connection, const RCMPERTestResult& result) {
cout << "Got PER results:" << endl;
cout << " testId = " << result.ID << endl;
cout << " currentPacket = " << result.currentPacket << endl;
cout << " successPackets = " << result.successPackets << endl;
cout << " totalPackets = " << result.totalPackets << endl;
if (result.currentPacket == result.totalPackets) {
cout << "FINAL PER = " << result.successPackets << "/" << result.totalPackets << endl;
}
}
};
int rcmpp_per_test_coordinator_example(const char* portName)
{
int result = 0;
PERHandler perHandler;
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);
// start networking
if (rcm.startNetworking()) {
// set up PER test results handler
rcm.setPERTestHandler(&perHandler);
// some delay
OS_Sleep(10000);
// leave the network
rcm.stopNetworking();
}
}
catch(rcm::exception &e) {
result = 100;
}
catch(std::exception &e) {
result = 101;
}
catch (...) {
result = 102;
}
return result;
}
Go to Top