arobenko
commented
6 years ago Hi Dennis, Thanks for the warm words about my library. I'm happy when other developers find my work useful. Recently I saw someone online describing my library as "building a house out of matches". It may be true, but these "matches" allow implementation of various crazy / complex protocols with multiple levels of customization with little effort (once you get hold of how to use the library of course).
You did a great job in understanding how to use the library and what needs to be done. I'd say both of your approaches are feasible and more or less equal in complexity in terms of implementation effort and runtime speed performance. As for the final binary code size, I'm not sure, testing is needed. Unless you are implementing something bare-metal, it shouldn't bother you much.
Let's start with the "variant" approach. Note, that COMMS library is handles all the "length" fields as containing the remaining bytes after the length field itself (not including the latter). In your case we just need to add "4" when serializing the value of the field. The same goes for the "Length" field in the main message frame. As the result, your length field should be defined as:
using LengthField =
comms::field::IntValue<
MyFieldBase,
uint16_t,
comms::option::NumValueSerOffset<4>
>;The ParameterIDField looks good, but I'd use ValidNumValue option instead of ValidNumValueRange to avoid repetition of the parameter
template <int Num>
using ParameterIDField =
comms::field::IntValue<
MyFieldBase,
ParamId,
comms::option::DefaultNumValue<Num>,
comms::option::ValidNumValue<Num>,
comms::option::FailOnInvalid<>
>;Now, the COMMS library allows you to implement your own read/refresh functionality to any field as long as you use HasCustomRead and HasCustomRefresh options to notify other components that these functions are not default.
template <int Num, typename T>
class Parameter " public
comms::field::Bundle<
MyFieldBase,
std::tuple<
ParameterIDField<Num>,
LengthField,
T
>,
comms::option::HasCustomRead,
comms::option::HasCustomRefresh
>
{
using Base = ...; // Repeated Base class definition, my be required for certain compilers
public:
// Provide convenience access functions to bundle members
COMMS_FIELD_MEMBERS_ACCESS(id, length, val);
// Custom read function
template <typename TIter>
comms::ErrorStatus read(TIter& iter, std::size_t len)
{
auto es = Base::template readUntil<FieldIdx_val>(iter, len); // read id and value
if (es != comms::ErrorStatus::Success) { return es; }
auto consumedLength = Base::template lengthUntil<FieldIdx_val>();
auto remainingLength = len - consumedLength;
auto expectedLength = field_length().value();
if (expectedLength < remainingLength) { /* report error, data is malformed */}
es = Base::template readFrom<FieldIdx_val>(iter, remainingLength);
if (es != comms::ErrorStatus::Success) { reutrn es; }
// consume remaining bytes as protection against malformed data
assert(field_value().length() <= remainingLength); // debug code verifying correction
auto lengthToConsume = remainingLength = field_val().length();
std::advance(iter, lengthToConsume);
return comms::ErrorStatus::Success;
}
// Custom refresh function (to bring field to a consistent state before writing)
bool refresh()
{
auto expectedLength = field_val().length();
auto recordedLength = field_length().value();
if (recordedLength == expectedLength) { return false; } // state not changed
field_length().value() = expectedLength;
return true; // state changed
}
};The empty value parameter I'd define using comms::field::NoValue:
template <int Num>
using EmptyParameter = Parameter<Num, comms::field::NoValue<MyFieldBase>>;Then your definition of the variant becomes:
class Message1Variant : public
comms::field::Variant<
MyFieldBase,
std::tuple<
Parameter<Message1ParameterIDs::X, UInt16Field>,
Parameter<Message1ParameterIDs::Y, UInt16Field>,
EmptyParameter<Message1ParameterIDs::Button>
>
>;
{
using Base = ... // redefinition of the base class, my be required by some compilers
public:
// Provide convenience access functions
COMMS_VARIANT_MEMBERS_ACCESS(X, Y, Button);
};Now you define your message contents as list of variants
struct Message1Fields
{
using PropertiesList =
comms::field::ArrayList<MyFieldBase, Message1Variant>;
using All = std::tuple<PropertiesList>;
};
template <typename TBase>
class Message1
: public comms::MessageBase<TBase,
comms::option::StaticNumIdImpl<MsgId_Message1>,
comms::option::FieldsImpl<Message1Fields::All>,
comms::option::MsgType<Message1<TBase>>,
comms::option::HasName>
{
public:
COMMS_MSG_FIELDS_ACCESS(list); // there is only one "list" field.
};The access to the parameters in the handling function or before sending may be performed like this:
auto& listField = msg1.field_list(); // access to the list field
auto& variantsVec = listField.value(); // access to the vector containing the variant fields
for (auto& varField : variantsVec) { // access to each variant field
... // process each field here
}How to process each variant contents is up to you to decide. Please open documentation of comms::field::Variant and read through available functions. One of the approaches is to define your parameter handling class and use "currentFieldExec()" member function for dispatch
struct MyHandler
{
template <std::size_t TIdx, typename TField>
void operator()(TField& field)
{
... // TField is one of the types in the tuple of the variant ("Parameter")
... // switch on ID and store the value somewhere to process later
}
}Another way to implement handler is provide "operator()" for every possible parameter
struct MyHandler
{
template <std::size_t TIdx>
void operator()(Parameter<Message1ParameterIDs::X, UInt16Field>& f)
{
auto xValue = f.field_val().value();
... // Store value of X somewhere
}
template <std::size_t TIdx>
void operator()(Parameter<Message1ParameterIDs::Y, UInt16Field>& f)
{
auto yValue = f.field_val().value();
... // Store value of Y somewhere
}
template <std::size_t TIdx>
void operator()(EmptyParameter<Message1ParameterIDs::Button>& field)
{
... // Store indication that button has been pressed
}
}I'd have some kind of State struct containing values for for all the possible parameters wrapped in boost::optional or std::optional to have an indication whether it was actually received. The MyHandler object in its handling operators may update the state object. Then the message handling may proceed in analyzing the received values.
If you want to send such a message you need to prepare it properly:
Message1<MyMessageInterface> msg1;
auto& listField = msg1.field_list(); // access to the list field
auto& variantsVec = listField.value(); // access to the vector containing the variant fields
variantsVec.resize(3); // Prepare 3 parameters
auto& xParam = variantsVec[0].initField_X();
xParam.field_val().value() = ... // X value
auto& yParam = variantsVec[1].initField_Y();
yParam.field_val().value() = ... // Y value
auto& buttonParam = variantsVec[2].initField_Button();
msg1.doRefresh(); // Required to assign appropriate values to all the "length" fields in the bundles
... // Send the messageThe second approach as treating every parameter as second message may also work. I'll try write a second message explaining it later today.
ftab
Thanks for such a great system, I've been looking at it for quite a while and I felt really inspired once I started catching on 😄 I'm trying to implement a protocol which defines its basic stack like so:
I think I have the basic protocol stack layer properly built to handle this (SyncPrefix -> MsgId -> Size -> Payload) but then the parameter value can be any one of several data types. The primitive ones I think I've got down pat (basic ints, a string, etc). But parameters can come/go in any order and be any one of those data types or a group of them (i.e. the bottom right section of that table repeated all over again for the Value field). I've created Bundle fields for each specific pairing of param/length/data type, but I don't think there is a provision for a bundled field to have its own length, unlike ArrayList (if I understood ArrayList correctly). I saw Variant fields, but unless I'm wrong, for each message with, say, 3 parameters is going to look like this:
My other thought was just run the entire message payload layer through another protocol stack definition (MsgId -> Size -> Payload) and so on and so forth for any subgroups of parameters within, but 1) that'd be several new protocol stacks for each message I think?, 2) I don't see an example of how to do that, 3) not sure where to even begin to try to wrap my head around fitting that in (parameter dispatch?) during message dispatch
am I trying too hard to look for something to avoid boilerplate code in every message? The example I wrote above already looks pretty hefty just for a single message, and I've got...oh, about 100 messages to implement 😬
Thoughts?