The Robox BCC/31 communication protocol library for Cpp: BCC/31 module

Introduction

Description

This is the Robox's BCC/31 communication protocol library implementation for Cpp.
This library allows custom client software developped with Cpp to connect to Robox's remote controls.
You can get remote module device informations, handle all kinds of Variable running on that, and perform all the common allowed operations (read , write, force, release) according to the variable type.

How to use the library

In order to use the library, your client has to be build upon C++11 or successive.
Make sure to include all the requested include files distributed with the library and link the library modules to your project.
Before digging into the library specific usage, let's expose some general tips:

• As general rules, all the library's API traps most common exception, returning a Globals::Results error code as accurate as possibile.
• The error codes may be decoded into strings with specific helper functions ( Globals::DecodeResult ).
• It's best practise that the methods and properties exposed by a specific instance of a Client object are invoked from a single thread, so for multithread operations it’s better to use a different Client for each single thread.
  Concurrent invokation of methods of the same Client instance from different threads is protected and will fail, but invoking methods (even one a time) by alternating the calling thread may have unexpected behaviors .
  Concurrent access of properties from different threads may have unexpected behaviors in the Client itself (they aren't thread safe).
  If you need to use the same Client object from different thread, you do it at your own risk and you must ensure with your logic (for example locking the thread) that just a thread at time invokes methods and properties of the Client object.
• The library makes use of namespaces, so it's advice to declared the used one in your files, e.g.

  using namespace RLibCpp;
  using namespace RLibCpp::Bcc;

That said, let's see che basic step to start using the library

Getting a Connection

The basic object requested to communicate with a device is the Connection object.
The Connection object needs just few settings to be ready for use. For convenience it's advice to connect to some Connection signal to get rid of the most significative Connection status changes notifications.
Here is an example for the TcpIpConnection object, probably the most used one.

// Create the object
TcpIpConnection con;
 
// Set the Vtx path
String vtxPath = "../etc/vtx";
con.setVtxPath(vtxPath);
 
// Set the address with default device port
con.setServerIp("192.168.0.180");
 
// Set the schedule type
con.setScheduleType(ThreadHelper::scheduleTypeFast);
 
// Connect to most significative signals
con.started.connect(onConnStarted);
con.stopped.connect(onConnStopped);
// or if event handler are non static member function of class (e.g. MyClass *obj)
// con.started.connect(obj, &MyClass::onConnStarted);
// con.stopped.connect(obj, &MyClass::onConnStopped);
 
// Start the connection
if (con.start() != Globals::resSuccess)
{
    cout << "!!!!!! Failed to start connection\n";
    return;
}

The Connection object per se doesn't expose any usefull method , so we need a Client object to perform the most significative operations.

Getting a Client

To get a Client for a Connection just invoke the proper method ( Connection::getClient )

Client *client;
if (con.getClient(client) != Globals::resSuccess)
{
    cout << "!!!!!! Failed to get the client\n";
    return;
}

Now you can use the Client object from just a single thread a time.
When done with the object, it's best practice to expliciatlly release it (Connection::releaseClient) elsewhere it will survive for all the the Connection object lifespan.

if (con.releaseClient(client) != Globals::resSuccess)
{
    cout << "!!!!!! Failed to release the client\n";
    return;
}

Note that you cannot neither create nor delete a Client object directly, everything has to be handled by the associated Connection object.

Getting a Variabile

Once we have a valid Client object (see Getting a Client) we can use it to read a Variable (Client.readVariable) The Variable object may be created in different ways:

1. You can get standard variable using the method specific for that variable type
   e.g.

   Variable var= Variable::fromVR32(1000, 10);

2. If you need to access other types of variable (e.g. local task variable, predefined variables etc) or simply you prefer to specify the variable definition, you can get specify the variable name with proper syntax
   e.g.

   Variable var1= Variable::fromName("R 1000, 10");
   Variable var2= Variable::fromName("tam");

The Variable may be further customized to use Safe modes (ClientStruct::ReadVariableData::setSafe) or coherent values (ClientStruct::ReadVariableData::setCoherentValues) : see section Using safe operations and Using coherent values for further details.

Reading a Variable

To read a Variable you'll have to get a ClientStruct::ReadVariableData object, assign the ClientStruct::ReadVariableData::var() property as seen in Getting a Variabile and call the Client::readVariable(ClientStruct::ReadVariableData&) method

ClientStruct::ReadVariableData data(Variable::fromVR32(1000, 10));
if (client->readVariable(data) != Globals::resSuccess)
{
    cout << "!!!!!! Failed to read variable\n";
    return;
}

Now you can use the values read:

for (size_t valIdx = 0; valIdx < data.values().size(); valIdx++)
{
    switch (data.values()[valIdx].type())
    {
    case Variable::Data::dtDouble:
    case Variable::Data::dtSingle:
        cout << data.values()[valIdx].getDouble() << " ";
        break;
    case Variable::Data::dtString:
        cout << data.values()[valIdx].getString() << " ";
        break;
    default:
        cout << data.values()[valIdx].getU32() << " ";
        break;
    }
}

Writing a Variable

To write a Variable you'll have to get a ClientStruct::WriteVariableData object, assign the ClientStruct::WriteVariableData::var() property as seen in Getting a Variabile and add the values to write

ClientStruct::WriteVariableData data(Variable::fromVR32(1000, 10));
for (int32_t idx = 0; idx < 10; idx++)
{
    data.values().pushBack(Variable::Data::fromU32(idx));
}

... and write the values to the device with the proper method ( see Client::writeVariable(ClientStruct::WriteVariableData&) ) ...

if (client->writeVariable(data) != Globals::resSuccess)
{
    cout << "!!!!!! Failed to write variable\n";
}

Getting a Monitor

To get a Monitor for a Connection just invoke the proper method ( Connection::getMonitor )

Monitor *mon;
if (con.getMonitor(mon) != Globals::resSuccess)
{
    cout << "!!!!!! Failed to get the monitor\n";
    return;
}

Now you can use the Monitor object from just a single thread a time.
When done with the object, it's best practice to expliciatlly release it (Connection::releaseMonitor) elsewhere it will survive for all the the Connection object lifespan.

if (con.releaseMonitor(mon) != Globals::resSuccess)
{
    cout << "!!!!!! Failed to release the monitor\n";
    return;
}

Note that you cannot neither create nor delete a Monitor object directly, everything has to be handled by the associated Connection object.

Using the Monitor

Once we got a Monitor object (see Getting a Monitor) we need some basic settings before to use it, such as the requested data frequency , the autorestart flag:

// Setup the monitor
mon->setAutoRestart(true);
mon->setDataFrequency(100);

It's best practice to use the emitted signals to get rid of the Monitor status and to read data

mon.dataChanged.connect(onMonDataChanged);
mon.restarted.connect(onMonRestarted);
mon.started.connect(onMonRonMonStartedestarted);
mon.stopped.connect(onMonStopped);
mon.error.connect(onMonError);
// or if event handler are non static member function of class (e.g. MyClass *obj)
// mon.dataChanged.connect(obj, &MyClass::onMonDataChanged);
// mon.restarted.connect(obj, &MyClass::onMonRestarted);
// mon.started.connect(obj, &MyClass::onMonStarted);
// mon.stopped.connect(obj, &MyClass::onMonStopped);
// mon.error.connect(obj, &MyClass::onMonError);

The Monitor may be further customized to use coherent values (Monitor::setCoherentValues) : see section Using coherent values for further details.
Once the Monitor was properly setupped , we have to add it the variables be read ( see Getting a Variabile).
Unless you need to use Monitor::coherentValues, you can add as many variables as needed (with arbitrary repetition count) to the single Monitor. Instead, if you setted the Monitor::coherentValues flag, then you have to distribute the variable into as many distinct monitors as needed to accomplish the BCC 31 monitor specification data size.
The limit to the number of variables and their repetition, is the maximum number of bcc monitor that the device can allows to be created.

mon->add(Variable::fromVRR(2000, 10));
mon->add(Variable::fromVR32(1000, 10));

When done, you have to Monitor::start the Monitor ...

if (mon->start() != Globals::resSuccess)
{
    cout << "!!!!!! Failed to start the monitor\n";
    return;
}

... and wait for Monitor::dataChanged events

void onMonDataChanged(uint64_t senderId, uint32_t changeId)
{
    RLibCpp::Bcc::MonitorStruct::ReadData readData;
    if( mon->read(readData)!= Globals::resSuccess)
    {
        cout << "!!!!!! Failed to read the monitor\n";
        return;
    }
    cout << "Monitor data changed: " << readData.changeId() << "\n";
    for (size_t valIdx = 0; valIdx < readData.values().size(); valIdx++)
    {
        Variable::Data::PtrVector *list = readData.values()[valIdx];
        for (size_t itemIdx = 0; itemIdx < list->size(); itemIdx++)
        {
            Variable::Data *data= (*list)[itemIdx];
            switch (data->type())
            {
            case Variable::Data::dtDouble:
            case Variable::Data::dtSingle:
                cout << data->getDouble() << " ";
                break;
            case Variable::Data::dtString:
                cout << data->getString() << " ";
                break;
            default:
                cout << data->getU32() << " ";
                break;
            }
        }
    }
}

Make sure to process data as fast as possible, according to the setted data frequency and the capabilities of the device running your application.
Alternatively, if you don't want to use signals, you can pool the Monitor::changeId for variations and read data directly

uint32_t lastChangeId= 0;
 
void readMonData(Monitor *mon)
{
    uint32_t changeId= mon->changeid();
    if( lastChangeId == changeId)
        return;
    lastChangeId= changeId;
    MonitorStruct::ReadData readData;
    if( mon->read(readData)!= Globals::resSuccess)
    {
        cout << "!!!!!! Failed to read the monitor\n";
        return;
    }
    cout << "Monitor data changed: " << readData.changeId() << "\n";
    for (size_t valIdx = 0; valIdx < readData.values().size(); valIdx++)
    {
        Variable::Data::PtrVector *list = readData.values()[valIdx];
        for (size_t itemIdx = 0; itemIdx < list->size(); itemIdx++)
        {
            Variable::Data *data= (*list)[itemIdx];
            switch (data->type())
            {
            case Variable::Data::dtDouble:
            case Variable::Data::dtSingle:
                cout << data->getDouble() << " ";
                break;
            case Variable::Data::dtString:
                cout << data->getString() << " ";
                break;
            default:
                cout << data->getU32() << " ";
                break;
            }
        }
    }
}

Getting an Oscilloscope

To get an Oscilloscope for a Connection just invoke the proper method ( Connection::getOscilloscope )

Oscilloscope *osc;
if (con.getOscilloscope(osc) != Globals::resSuccess)
{
    cout << "!!!!!! Failed to get the oscilloscope\n";
    return;
}

Now you can use the Oscilloscope object from just a single thread a time.
When done with the object, it's best practice to expliciatlly release it (Connection::releaseOscilloscope) elsewhere it will survive for all the the Connection object lifespan.

if (con.releaseOscilloscope(osc) != Globals::resSuccess)
{
    cout << "!!!!!! Failed to release the oscilloscope\n";
    return;
}

Note that you cannot neither create nor delete an Oscilloscope object directly, everything has to be handled by the associated Connection object.

Using the Oscilloscope

Once we got an Oscilloscope object (see Getting an Oscilloscope) we need some basic settings before to use it, such as the requested data and event frequency , the autorestart flag:

// Setup the oscilloscope
osc->setAutoRestart(true);
osc->setDataFrequency(500);
osc->setEventFrequency(200);

It's best practice to use the emitted signals to get rid of the Oscilloscope status and to read data

osc->dataChanged.connect(onOscDataChanged);
osc->restarted.connect(onOscRestarted);
osc->started.connect(onOscStarted);
osc->stopped.connect(onOscStopped);
osc->error.connect(onOscError);
osc->dataOverflowed.connect(onOscDataOverflowed);
// or if event handler are non static member function of class (e.g. MyClass *obj)
// osc->dataChanged.connect(obj, &MyClass::onOscDataChanged);
// osc->restarted.connect(obj, &MyClass::onOscRestarted);
// osc->started.connect(obj, &MyClass::onOscStarted);
// osc->stopped.connect(obj, &MyClass::onOscStopped);
// osc->error.connect(obj, &MyClass::onOscError);
// osc->dataOverflowed.connect(obj, &MyClass::onOscDataOverflowed);

Once the Oscilloscope was properly setupped , we have to add it the variables be read ( see Getting a Variabile).
You have to distribute the variable into as many distinct oscilloscopes as needed to accomplish the BCC 31 oscilloscope specification data size

osc->add(Variable::fromName("RR 2000"));
osc->add(Variable::fromVR32(var, 1000));

When done, you have to Oscilloscope::start the Oscilloscope ...

if (osc->start() != Globals::resSuccess)
{
    cout << "!!!!!! Failed to start the oscilloscope\n";
    return;
}

... and wait for Oscilloscope::dataChanged events

void onOscDataChanged(uint64_t, uint32_t)
{
    RLibCpp::Bcc::OscilloscopeStruct::ReadData oscData;
    if (osc->read(oscData) != Globals::resSuccess)
    {
        cout << "!!!!!! Failed to read the oscilloscope\n";
        return;
    }
    // Show the last returned value 
    RLibCpp::Bcc::OscilloscopeStruct::DataSample *sample = oscData.samples()[oscData.samples().size() - 1];
    if (oscData.samples().size() == 0)
        return;
    RLibCpp::Bcc::OscilloscopeStruct::DataSample *sample = oscData.samples()[oscData.samples().size() - 1];
    FloatVector &values = sample->values();
    for (size_t valIdx = 0; valIdx < values.size(); valIdx++)
    {
        cout << StringHelper::fromSingle(values[valIdx]) << " ";
    }
    cout << " @ " << StringHelper::fromDouble(sample->time()) << endl;
}

Make sure to process data as fast as possible, according to the setted data frequency and the capabilities of the device running your application.
Alternatively, if you don't want to use signals, you can pool the Oscilloscope::changeId for variations and read data directly

uint32_t lastChangeId= 0;
 
void readOscData(Oscilloscope *osc)
{
    uint32_t changeId = osc->changeId();
    if (lastChangeId == changeId)
        return;
    lastChangeId = changeId;
    OscilloscopeStruct::ReadData oscData;
    if (osc->read(oscData) != Globals::resSuccess)
    {
        cout << "!!!!!! Failed to read the oscilloscope\n";
        return;
    }
    cout << "Oscilloscope data changed: " << oscData.changeId() << "\n";
    // Show the last returned value 
    RLibCpp::Bcc::OscilloscopeStruct::DataSample *sample = oscData.samples()[oscData.samples().size() - 1];
    if (oscData.samples().size() == 0)
        return;
    RLibCpp::Bcc::OscilloscopeStruct::DataSample *sample = oscData.samples()[oscData.samples().size() - 1];
    FloatVector &values = sample->values();
    for (size_t valIdx = 0; valIdx < values.size(); valIdx++)
    {
        cout << StringHelper::fromSingle(values[valIdx]) << " ";
    }
    cout << " @ " << StringHelper::fromDouble(sample->time()) << endl;
}

If this is the case, make sure to read data at proper rate to avoid the Oscilloscope data overflow.

Using safe operations

The use of safe operation (see RLibCpp::Bcc::ClientStruct::SafeModes) grants you that the variable operation will be synched with the remote device, i.e. ensures that the device's varset identifier matches the library stored varset identifier. If the the stored varset identifier doesn't match the device one, then the library will transparently try to synch and performs the operation again.
Not all the variables operations supports safe operations. Here is the list:

• RLibCpp::Bcc::ClientStruct::ReadVariableData::setSafe(RLibCpp::Bcc::ClientStruct::SafeModes value)
• RLibCpp::Bcc::ClientStruct::WriteVariableData::setSafe(RLibCpp::Bcc::ClientStruct::SafeModes value)
• RLibCpp::Bcc::ClientStruct::ForceVariableData::setSafe(RLibCpp::Bcc::ClientStruct::SafeModes value)
• RLibCpp::Bcc::ClientStruct::ReleaseVariableData::setSafe(RLibCpp::Bcc::ClientStruct::SafeModes value)
• RLibCpp::Bcc::ClientStruct::ReleaseAllVariablesData::setSafe(RLibCpp::Bcc::ClientStruct::SafeModes value)

When setting the property you have some choices to choose :

• RLibCpp::Bcc::ClientStruct::safeModeIfSupported
• RLibCpp::Bcc::ClientStruct::safeModeAlways
• RLibCpp::Bcc::ClientStruct::safeModeNever

The suggested and preferred mode is RLibCpp::Bcc::ClientStruct::safeModeIfSupported unless you are concerned with perfomance and want to skip any extra comunication with the device or are accessing variables that don't rely on the device varset identifier (e.g. accessing standard register such as V32, NvR32). If that's the case then you may want to set the RLibCpp::Bcc::ClientStruct::safeModeNever mode

Using coherent values

The use of coherent values in operations grants you that the data packet handled is atomic i.e. performed with same operation.
If coherent value flag is resetted than the library may transparently split the operation to the device in multiple one , and variable modification may occur during successive device operations.
If coherent value flag is resetted than you are free to add as many variable as needed to the operation data, or few variable but with large repetition count (e.g. 300 Nv32 register). The library will take care of splitting (if necessary) the single user operation into as many device operations as needed to accomlish with the BCC 31 protocol specification
Otherwise if coherent value flag is setted than the responsability to fit the BCC 31 protocol specification is up to you.
Not all the variables operations have coherent values. Here is the list:

• RLibCpp::Bcc::ClientStruct::ReadVariableData::setCoherentValues(bool value)
• RLibCpp::Bcc::ClientStruct::WriteVariableData::setCoherentValues(bool value)
• RLibCpp::Bcc::Monitor::setCoherentValues(bool value)

Using the cache

The library provides a Connection's Variable cache storage.
You can save Variable definitions into the cache and the retrive them when needed.

QString varName= "RR 1000, 10";
uint32_t cacheId = con.findInVarsCache(varName);
if( cacheId == 0)
{
    // Variable not present into the cache: add it
    cacheId = con.addToVarsCache(varName);
    if (cacheId == 0)
    {
        cout << "!!!!!! Failed to add variable to cache\n";
        return;
    }
}
Variable cachedVar= Variable::fromCache(cacheId);

If you need the same Variable definition to be used for multiple purpose and you need to keep them in cache as different entries , then you can add an extra tag to Variable cache definition

QString varName= "RR 1000, 10";
uint32_t cacheId = con.findInVarsCache(varName, "MON");
if( cacheId == 0)
{
    // Variable not present into the cache: add it
    cacheId = con.addToVarsCache(varName, "MON");
    if (cacheId == 0)
    {
        cout << "!!!!!! Failed to add variable to cache\n";
        return;
    }
}
Variable cachedVar= Variable::fromCache(cacheId);