Understanding the Component Auto-Generated .cpp and .hpp

[jake14000]

Hello,

As I learn F Prime, I am finding it hard to grasp what is going on in the auto-generated .cpp and .hpp files after we fprime-util generate and fprime-util impl. More specifically, as I read through the SystemReference deployment as an example vs the auto-generated template files, I do not understand what these auto-generated functions are doing.

For example (in Arduino), I know that

void setup() { pinMode(LED, OUTPUT); }

Is the setup function that defines the LED pin to output, and that

void loop() { digitalWrite(LED_BUILTIN, HIGH); delay(1000); digitalWrite(LED_BUILTIN, LOW); delay(1000); }

Is a function that infinitely loops a power command with a delay within it.

Is there anywhere I can reference that goes into this level of depth for me to grasp? Any help would be appreciated.

[LeStarch]

I'll suggest we break down the I2C example a bit and see if this answers your question. If not please reply back for more help.

To start with, we have two effective functions when dealing with hardware:

1. Decide what to write to hardware. In your above code: set LED HIGH/LOW.
2. Decide how to write it. Send a digital HIGH/LOW via digitalWrite.

Some hardware communication is more complicated. For example, it might us an I2C bus. This is how our IMU works. It sends out a message using I2C to communicate with the I2C IMU chip. We break the same functionality into two pieces as stated above.

1. Imu manager decides what to write: on off messages, read data messages, etc.
2. LinuxI2cDriver decide how to send the message to I2C (e.g. call write(i2c device, message)

We might do the same thing with your GPIO example above, creating an LED manager and a Pin driver. The reason we do this is to separate out the functionality. One controls what it manages, and the other controls the underlying hardware. The I2C driver may be reused for any other I2C sensor without needing to remove IMU specific items.

This brings us to the Application / Manager / Driver pattern. Applications component perform the top-level application of your software: blink an LED, detect tilt of a board, etc. These application components delegate functionality to managers to handle the specific hardware portions: e.g. "turn on LED", "turn off LED", "read IMU" etc. These managers delegate messaging and bus instructions to the driver: "send read message", "toggle pin", etc. As an application grows beyond a simple loop (above) it is much easier to design and validate functionality when it is broken up. Imagine reading an I2C, detecting a tilt, sending the "he we tilted" to ground, each with its management, messages, etc in a single program loop. It would work but is so hard to debug, verify, etc because it would be all co-located.

See: Application Manager Driver Pattern

[LeStarch]

... and finally to the update helper function:

void Imu ::updateAccel() {
    U8 data[IMU_MAX_DATA_SIZE_BYTES];
    Fw::Buffer buffer(data, sizeof data);

    // Read a block of registers from the IMU at the accelerometer's address
    Drv::I2cStatus status = this->readRegisterBlock(IMU_RAW_ACCEL_ADDR, buffer);

    // Check a successful read of 6 bytes before processing data
    if ((status == Drv::I2cStatus::I2C_OK) && (buffer.getSize() == 6) && (buffer.getData() != nullptr)) {
        Gnc::Vector vector = deserializeVector(buffer, accelScaleFactor);
        this->tlmWrite_accelerometer(vector);
    } else {
        this->log_WARNING_HI_TelemetryError(status);
    }
}

Here we setup a Fw::Buffer to store our read. It wraps 6 bytes of data (6 being the value of IMU_MAX_DATA_SIZE_BYTES). That 6 bytes is filled by the readRegisterBlock helper which we just analyzed and which calls the write_out and read_out driver ports.

That would be enough to get telemetry, and we could send it down directly.....however, we wanted to process the telemetry into nice units and report an error if we failed. That is the remaining lines of the function: if "good" convert to nicely formatted data, else log a WARNING_HI event called "telemetry error".

In the final section we'll look at the data formatting code.

[LeStarch]

The data we read back is of the form of 3xI16 values in big-endian form in order x, y, z. How did we know this? It is in the data sheet. Starting at the start register we see:

1. X higher-order byte
2. X low-order byte
3. Y higher-order byte
4. Y low-order byte
5. Z higher-order byte
6. Z low-order byte

This is also how we knew to read 6 bytes...

We want to convert that data to a nice 3-elemet vector in floating point format. We also want to scale the data to be engineering units (degrees per second or something). This is what the deserializeVector helper does.

Gnc::Vector Imu ::deserializeVector(Fw::Buffer& buffer, F32 scaleFactor) {
    Gnc::Vector vector;
    I16 value;
    FW_ASSERT(buffer.getSize() >= 6, buffer.getSize());
    FW_ASSERT(buffer.getData() != nullptr);
    // Data is big-endian as is fprime internal storage so we can use the built-in buffer deserialization
    Fw::SerializeBufferBase& deserializeHelper = buffer.getSerializeRepr();
    deserializeHelper.setBuffLen(buffer.getSize()); // Inform the helper what size we have available
    FW_ASSERT(deserializeHelper.deserialize(value) == Fw::FW_SERIALIZE_OK);
    vector[0] = static_cast<F32>(value) / scaleFactor;

    FW_ASSERT(deserializeHelper.deserialize(value) == Fw::FW_SERIALIZE_OK);
    vector[1] = static_cast<F32>(value) / scaleFactor;

    FW_ASSERT(deserializeHelper.deserialize(value) == Fw::FW_SERIALIZE_OK);
    vector[2] = static_cast<F32>(value) / scaleFactor;
    return vector;
}

First we assert that there is enough data to work. The caller should ensure this, but we double check. Next Fw::Buffer provides a helper component that will allow us to easily deserialize data stored in the Fw::Buffer data as long as it is in big-endian format. That is stored in the deserializeHelper variable and is of type Fw::SerializeBufferBase.

Then we deserialize into an I16 called value 3 times, assert it worked, and the do the scale-factor multiplication. Each step is stored in an element of the vector.

[LeStarch]

Now you may be wondering why we have so many helpers running around. This is for 2 reasons:

1. Reusability: we can reuse the same code to do the gyro update with different parameters.
2. Verifiability: it is much easier to prove a function correct through review or unit-test if it does one small thing.

Does the setupReadRegister work? It does one thing: write the upcoming read's address. Yes, it absolutely does the correct thing.
Does the readRegisterBlock work? It does one less-small-thing: setup read (known to work as above), checks result, and then reads. Yes, it also works.

If the code were co-mingled, you'd be unable to reuse it and it would be quite difficult to verify that it works or fix it if it doesn't. Here we can verify small easily understood pieces, and use composition to construct larger functions. This desire extrapolates to application and component breakdown too.

[LeStarch]

@jake14000 I hope this analysis helps, and I encourage more questions!

[jake14000]

@jake14000 I hope this analysis helps, and I encourage more questions!

Thank you so much Mr. Starch! My team has been digging into this all week, thank you for taking the time to write this out for us. If we have any more questions, we will continue to ask them.

[capsulecorplab]

The data we read back is of the form of 3xI16 values in big-endian form in order x, y, z. How did we know this? It is in the data sheet. Starting at the start register we see:

1. X higher-order byte

2. X low-order byte

3. Y higher-order byte

4. Y low-order byte

5. Z higher-order byte

6. Z low-order byte

This is also how we knew to read 6 bytes...

We want to convert that data to a nice 3-elemet vector in floating point format. We also want to scale the data to be engineering units (degrees per second or something). This is what the deserializeVector helper does.

Gnc::Vector Imu ::deserializeVector(Fw::Buffer& buffer, F32 scaleFactor) {
    Gnc::Vector vector;
    I16 value;
    FW_ASSERT(buffer.getSize() >= 6, buffer.getSize());
    FW_ASSERT(buffer.getData() != nullptr);
    // Data is big-endian as is fprime internal storage so we can use the built-in buffer deserialization
    Fw::SerializeBufferBase& deserializeHelper = buffer.getSerializeRepr();
    deserializeHelper.setBuffLen(buffer.getSize()); // Inform the helper what size we have available
    FW_ASSERT(deserializeHelper.deserialize(value) == Fw::FW_SERIALIZE_OK);
    vector[0] = static_cast<F32>(value) / scaleFactor;

    FW_ASSERT(deserializeHelper.deserialize(value) == Fw::FW_SERIALIZE_OK);
    vector[1] = static_cast<F32>(value) / scaleFactor;

    FW_ASSERT(deserializeHelper.deserialize(value) == Fw::FW_SERIALIZE_OK);
    vector[2] = static_cast<F32>(value) / scaleFactor;
    return vector;
}

First we assert that there is enough data to work. The caller should ensure this, but we double check. Next Fw::Buffer provides a helper component that will allow us to easily deserialize data stored in the Fw::Buffer data as long as it is in big-endian format. That is stored in the deserializeHelper variable and is of type Fw::SerializeBufferBase.

Then we deserialize into an I16 called value 3 times, assert it worked, and the do the scale-factor multiplication. Each step is stored in an element of the vector.

Hi @LeStarch I'm having trouble finding where in the data sheet it says that the data is in big-endian format. Page 50 of https://invensense.tdk.com/wp-content/uploads/2017/11/RM-MPU-9250A-00-v1.6.pdf seem to suggest the data is stored in little-endian format.

[LeStarch]

We were specifically using this data sheet for the 6050 the IMU we've used in the class: http://cdn.sparkfun.com/datasheets/Sensors/Accelerometers/RM-MPU-6000A.pdf

Here the low-order registers store the high-order bytes for each of the data signals.

[capsulecorplab]

Thanks @LeStarch, would there happen to be a helper function for reading and de-serializing little-endian data from an I2C register? My colleagues and I are attempting to interpret the BME680 register map and implement a BME680 Component as an extension to the fprime-baremetal-reference mdrs-community/fprime-baremetal-reference#1