Docs

You are here:
Performance testing

Built-in performance test utilities

The RCM 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 connection need to be opened (RCM_Open) and run (RCM_Run). 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_StartContinuousTX function, 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.

Example

The following example illustrates the usage of output power test:

#include "rcm.h"
// Structure holding information about the connection
static RCMConnection rcm;
// Declare a structure named frameBuffer, that will fit infinite SCOM packets
static SCOM_DECLARE_FRAME_BUFFER_USING_HEAP(frameBufferInHeap);
// Declare a structure named messageBufferInHeap that can fit unlimited number of RCM messages
static RCM_DECLARE_MESSAGE_BUFFER_USING_HEAP(messageBufferInHeap);
// Declare a structure named epMessageBufferInHeap that can fit unlimited number of RCM messages - for endpoint filtering
static RCM_DECLARE_MESSAGE_BUFFER_USING_HEAP(epMessageBufferInHeap);
int rcm_output_power_test_example(IODevice iodevice)
{
int result = 0;
RCMMessage* receivedMessage;
OSTime startTime;
// get current time
startTime = OS_GetSystemTime();
// try to open the connection using specified IODevice
if (RCM_RESULT_OK == RCM_Open(&rcm, iodevice, &frameBufferInHeap, &messageBufferInHeap, OS_GetSystemTime)) {
// connection opened, run it
if (RCM_RESULT_OK == RCM_Run(&rcm)) {
// threads run successfully
// configure the RCM module
RCM_SetUID(&rcm, 0x0123456789abcdef);
// establish the network
if (RCM_RESULT_OK == RCM_StartNetworking(&rcm)) {
// network established successfully
// enable output power test on antenna 0, with pseudo-random bit sequence
// in the loop, check only the state of connection
while (0 == result) {
// 1s delay
OS_Sleep(1000);
// check connection
while (RCM_RESULT_OK != RCM_GetConnectionState(&rcm)) {
// connection broke down (hardware error?)
// exit with error code
result = 2;
}
// check timeout
if (OS_GetSystemTime() - startTime > 5000) {
// timeout
break;
}
}
}
// stop the RCM threads
RCM_Stop(&rcm);
} else {
// error
result = 2;
}
// finally close the connection
RCM_Close(&rcm);
} else {
// error
result = 1;
}
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_StartPERTest function starts the PER test and causes the router to send packets to the coordinator. The RCM_WaitForPERTestEnd function can block the calling thread, until the test is finished . The RCM_GetPERTestResultFromRemoteNode function can be used by the router to retrieve PER test results from the coordinator. In addition, the RCM_SetPERTestCallback function allows to register a callback function, that will be called every time the PER test progress information is reported from the radio module. It can be used to monitor the progress of the test.

Example

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

#include "rcm.h"
// Structure holding information about the connection
static RCMConnection rcm;
// Declare a structure named frameBuffer, that will fit infinite SCOM packets
static SCOM_DECLARE_FRAME_BUFFER_USING_HEAP(frameBufferInHeap);
// Declare a structure named messageBufferInHeap that can fit unlimited number of RCM messages
static RCM_DECLARE_MESSAGE_BUFFER_USING_HEAP(messageBufferInHeap);
// Declare a structure named epMessageBufferInHeap that can fit unlimited number of RCM messages - for endpoint filtering
static RCM_DECLARE_MESSAGE_BUFFER_USING_HEAP(epMessageBufferInHeap);
// This function will be called whenever new PER test progress data will be received
static void rcm_per_test_callback(struct RCMConnection* rcmon, RCMPERTestResult* result)
{
// 'result' points to the structure containing the current PER test progress information
}
int rcm_per_test_router_example(IODevice iodevice)
{
int result = 0;
uint32_t testId;
RCMPERTestResult testResult;
// try to open the connection using specified IODevice
if (RCM_RESULT_OK == RCM_Open(&rcm, iodevice, &frameBufferInHeap, &messageBufferInHeap, OS_GetSystemTime)) {
// connection opened, run it
if (RCM_RESULT_OK == RCM_Run(&rcm)) {
// threads run successfully
// configure the RCM module
RCM_SetUID(&rcm, 0x0123456789abcdee);
// establish the network
if (RCM_RESULT_OK == RCM_StartNetworking(&rcm)) {
// network established successfully
// Set up a callback that will be called whenever new PER test progress information will be received
RCM_SetPERTestCallback(&rcm, rcm_per_test_callback);
// Run PER test
if (RCM_RESULT_OK == RCM_StartPERTest(&rcm, 0, 1000, 0, &testId)) {
// Wait for PER test end
if (RCM_RESULT_OK == RCM_WaitForPERTestEnd(&rcm, testId, &testResult, 30000)) {
// Once the test is done, request results from remote node
if (RCM_RESULT_OK == RCM_GetPERTestResultFromRemoteNode(&rcm, 0, testId, &testResult, 10000)) {
}
}
}
}
// stop the RCM threads
RCM_Stop(&rcm);
} else {
// error
result = 2;
}
// finally close the connection
RCM_Close(&rcm);
} else {
// error
result = 1;
}
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_SetPERTestCallback function, which the same as in the case of the router allows to register a callback function, 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 "rcm.h"
// Structure holding information about the connection
static RCMConnection rcm;
// Declare a structure named frameBuffer, that will fit infinite SCOM packets
static SCOM_DECLARE_FRAME_BUFFER_USING_HEAP(frameBufferInHeap);
// Declare a structure named messageBufferInHeap that can fit unlimited number of RCM messages
static RCM_DECLARE_MESSAGE_BUFFER_USING_HEAP(messageBufferInHeap);
// Declare a structure named epMessageBufferInHeap that can fit unlimited number of RCM messages - for endpoint filtering
static RCM_DECLARE_MESSAGE_BUFFER_USING_HEAP(epMessageBufferInHeap);
// This function will be called whenever new PER test results will be received
static void rcm_per_test_callback(struct RCMConnection* rcmon, RCMPERTestResult* result)
{
// 'result' points to the structure containing the current PER test results
}
int rcm_per_test_coordinator_example(IODevice iodevice)
{
int result = 0;
OSTime startTime;
// get current time
startTime = OS_GetSystemTime();
// try to open the connection using specified IODevice
if (RCM_RESULT_OK == RCM_Open(&rcm, iodevice, &frameBufferInHeap, &messageBufferInHeap, OS_GetSystemTime)) {
// connection opened, run it
if (RCM_RESULT_OK == RCM_Run(&rcm)) {
// threads run successfully
// configure the RCM module
RCM_SetUID(&rcm, 0x0123456789abcdef);
// establish the network
if (RCM_RESULT_OK == RCM_StartNetworking(&rcm)) {
// network established successfully
// Set up a callback that will be called whenever new PER test results will be received
RCM_SetPERTestCallback(&rcm, rcm_per_test_callback);
// in the loop, check only the state of connection
while (0 == result) {
// 1s delay
OS_Sleep(1000);
// check connection
while (RCM_RESULT_OK != RCM_GetConnectionState(&rcm)) {
// connection broke down (hardware error?)
// exit with error code
result = 2;
}
// check timeout
if (OS_GetSystemTime() - startTime > 20000) {
// timeout
break;
}
}
}
// stop the RCM threads
RCM_Stop(&rcm);
} else {
// error
result = 2;
}
// finally close the connection
RCM_Close(&rcm);
} else {
// error
result = 1;
}
return result;
}
Go to Top