Fast Data Pipe Setter Methods

Description

The Fast-Data-Setter methods are intended for a successive update of the data visualization properties of the LaRoomy Api. With a successive output a live value display can be achieved. Currently methods for the BarGraph and the LineGraph are provided. When designing a firmware which is using this feature it is important to understand the transmission scheme of the LaRoomy transmission protocol system. The successive output should only be activated when the respective Complex-Property page is opened to display the data. To figure out when this is the case the callback methods regarding the navigation of the app can be used (onComplexPropertyPageInvoked, onBackNavigation) or the ID of the current visible property page can be checked with the getCurrentOpenedPropertyPageID method of the LaRoomy Api. Additionally the connection state should be monitored to stop method calls if the device is getting disconnected.

API Reference

This a list of all available setter methods.

barGraphFastDataPipeSetSingleBarValue

  		
void barGraphFastDataPipeSetSingleBarValue(cID barGraphID, unsigned int barIndex, float barValue);

Use this method to change the value of a single bar in a BarGraph-Property.

Arguments:

barGraphID - The ID of the BarGraph whose data should be set.

barIndex - The index of the bar in the BarGraph.

barValue - The new value of the bar.

Example:
  		
#define  MY_BARGRAPH_ID  1

// timer params
long mTimer = 0;
long mTimeOut = 100;

void setup()
{
    /* other setup */
    
   // create a BarGraph
    BarGraph barGraph;
    barGraph.barGraphID = MY_BARGRAPH_ID;
    barGraph.barGraphDescription = "My BarGraph";
    barGraph.imageID = LaRoomyImages::BAR_GRAPH_162;

    // define an initial state with 3 bars
    barGraph.barGraphState.fixedMaximumValue = 100.0f;
    barGraph.barGraphState.addBar(
        BarData("Bar 1", 20.0f)
    );
    barGraph.barGraphState.addBar(
        BarData("Bar 2", 88.7f)
    );
    barGraph.barGraphState.addBar(
        BarData("Bar 3", 57.1f)
    );

    // add the BarGraph
    LaRoomyApi.addDeviceProperty(barGraph);
    
    /* other setup */
    
    // init timer reference
    mTimer = millis();    
}

void loop()
{
    // put your main code here, to run repeatedly:

    LaRoomyApi.onLoop();
    
    // invoke in a 100ms interval, but only transmit if the respective property page is opened
    if ((millis() > (unsigned long)(mTimeOut + mTimer)) 
            && (LaRoomyApi.getCurrentOpenedPropertyPageID() == MY_BARGRAPH_ID))
    {
        // update timer reference
        mTimer = millis();

        /* collect the bar data, e.g. measured adc values*/
        unsigned int barOneValue = .. ;

        // update the second bar 'Bar 2'
        LaRoomyApi.barGraphFastDataPipeSetSingleBarValue(MY_BARGRAPH_ID, 1, (float)barOneValue);
    }
    
    /* other code */
    
}

barGraphFastDataPipeSetAllBarValues

  		
void barGraphFastDataPipeSetAllBarValues(cID barGraphID, itemCollection<BarData>& bData);

Use this method to change the whole bar data in a BarGraph-Property.

Arguments:

barGraphID - The ID of the BarGraph whose data should be set.

bData - A compatible collection of BarData class objects. Compatible means if the BarGraph has 3 bars, the collection must provide 3 elements of bar-data, one for each bar.

Example:
  		
#define  MY_BARGRAPH_ID  1

// timer params
long mTimer = 0;
long mTimeOut = 100;

void setup()
{
    /* other setup */
    
   // create a BarGraph
    BarGraph barGraph;
    barGraph.barGraphID = MY_BARGRAPH_ID;
    barGraph.barGraphDescription = "My BarGraph";
    barGraph.imageID = LaRoomyImages::BAR_GRAPH_162;

    // define an initial state with 3 bars
    barGraph.barGraphState.fixedMaximumValue = 100.0f;
    barGraph.barGraphState.addBar(
        BarData("Bar 1", 20.0f)
    );
    barGraph.barGraphState.addBar(
        BarData("Bar 2", 88.7f)
    );
    barGraph.barGraphState.addBar(
        BarData("Bar 3", 57.1f)
    );

    // add the BarGraph
    LaRoomyApi.addDeviceProperty(barGraph);
    
    /* other setup */
    
    // init timer reference
    mTimer = millis();    
}

void loop()
{
    // put your main code here, to run repeatedly:

    LaRoomyApi.onLoop();
    
    // invoke in a 100ms interval, but only transmit if the respective property page is opened
    if ((millis() > (unsigned long)(mTimeOut + mTimer)) 
            && (LaRoomyApi.getCurrentOpenedPropertyPageID() == MY_BARGRAPH_ID))
    {
        // update timer reference
        mTimer = millis();

        /* collect the bar data, e.g. measured adc values*/
        unsigned int barOneValue = .. ;
        unsigned int barTwoValue = .. ;
        unsigned int barThreeValue = .. ;

        // create a compatible collection with 3 elements for each bar and and set the bar data
        itemCollection<BarData> bCollection;
        
        bCollection.AddItem(
            BarData((float)barOneValue)
        );
        bCollection.AddItem(
            BarData((float)barTwoValue)
        );
        bCollection.AddItem(
            BarData((float)barThreeValue)
        );

        // use the fast data setter to update the bargraph
        LaRoomyApi.barGraphFastDataPipeSetAllBarValues(MY_BARGRAPH_ID, bCollection);
    }
    
    /* other code */
    
}

lineGraphFastDataPipeResetDataPoints

  		
void lineGraphFastDataPipeResetDataPoints(cID lineGraphID, LineGraphDataPoints& lData);

Use this method to replace the whole data in a LineGraph-Property.

Arguments:

lineGraphID - The ID of the LineGraph whose data should be reset.

lData - A LineGraphDataPoints class object containing the new line data.

Example:
  		
#define  MY_LINEGRAPH_ID  2

// timer params
long mTimer = 0;
long mTimeOut = 200;

void setup()
{
    /* other setup */
    
    // create a lineGraph
    LineGraph lineGraph;
    lineGraph.imageID = LaRoomyImages::LINE_GRAPH_163;
    lineGraph.lineGraphDescription = "My LineGraph";
    lineGraph.lineGraphID = MY_LINEGRAPH_ID;

    // configure the grid
    lineGraph.lineGraphState.drawAxisValues = true;
    lineGraph.lineGraphState.drawGridLines = true;
    lineGraph.lineGraphState.xMinValue = 0;
    lineGraph.lineGraphState.xMaxValue = 100;
    lineGraph.lineGraphState.yMinValue = 0;
    lineGraph.lineGraphState.yMaxValue = 4100;
    lineGraph.lineGraphState.xIntersection = 10;
    lineGraph.lineGraphState.yIntersection = 500;

    // add the LineGraph to the Api
    LaRoomyApi.addDeviceProperty(lineGraph);
    
    /* other setup */
    
    // init timer reference
    mTimer = millis();    
}

void loop()
{
    // put your main code here, to run repeatedly:

    LaRoomyApi.onLoop();
    
    // invoke in a 200ms interval, but only transmit if the respective property page is opened
    if ((millis() > (unsigned long)(mTimeOut + mTimer)) 
            && (LaRoomyApi.getCurrentOpenedPropertyPageID() == MY_LINEGRAPH_ID))
    {
        // update timer reference
        mTimer = millis();

        // collect the data for the LineGraph
        LineGraphDataPoints dataPoints;

        for(uint8_t i = 0; i < 101; i++)
        {
            POINT pt;

            pt.x = i;
            pt.y = analogRead(14);

            dataPoints.addPoint(pt);
        }

        // set the LineGraph data
        LaRoomyApi.lineGraphFastDataPipeResetDataPoints(MY_LINEGRAPH_ID, dataPoints);
    }
    
    /* other code */
    
}

lineGraphFastDataPipeAddDataPoints

  		
void lineGraphFastDataPipeAddDataPoints(cID lineGraphID, LineGraphDataPoints& lData);
  	
  		
void lineGraphFastDataPipeAddDataPoints(cID lineGraphID, LineGraphDataPoints& lData, float shifter, LineGraphGridShiftDirection dir);

This method can be used to add data-points to the existing line data in a LineGraph-Property. An overloaded method is provided to additionally shift the grid of the LineGraph in a defined direction.

Arguments:

lineGraphID - The ID of the LineGraph to which the data should be added.

lData - A LineGraphDataPoints class object containing the line data to add.

shifter - The distance to shift the grid.

dir - The direction in which to shift the grid. Type: LineGraphGridShiftDirection

Example:
  		
#define  MY_LINEGRAPH_ID  2

// timer params
long mTimer = 0;
long mTimeOut = 50;

// counter
unsigned int counter = 0;

void setup()
{
    /* other setup */
    
    // create a lineGraph
    LineGraph lineGraph;
    lineGraph.imageID = LaRoomyImages::LINE_GRAPH_163;
    lineGraph.lineGraphDescription = "My LineGraph";
    lineGraph.lineGraphID = MY_LINEGRAPH_ID;

    // configure the grid
    lineGraph.lineGraphState.drawAxisValues = true;
    lineGraph.lineGraphState.drawGridLines = true;
    lineGraph.lineGraphState.xMinValue = 0;
    lineGraph.lineGraphState.xMaxValue = 100;
    lineGraph.lineGraphState.yMinValue = 0;
    lineGraph.lineGraphState.yMaxValue = 4100;
    lineGraph.lineGraphState.xIntersection = 10;
    lineGraph.lineGraphState.yIntersection = 500;

    // add the LineGraph to the Api
    LaRoomyApi.addDeviceProperty(lineGraph);
    
    /* other setup */
    
    // init timer reference
    mTimer = millis();    
}

void loop()
{
    // put your main code here, to run repeatedly:

    LaRoomyApi.onLoop();
    
    // invoke in a 50ms interval, but only transmit if the respective property page is opened
    if ((millis() > (unsigned long)(mTimeOut + mTimer)) 
            && (LaRoomyApi.getCurrentOpenedPropertyPageID() == MY_LINEGRAPH_ID))
    {
        // update timer reference
        mTimer = millis();
        
        // create point data class
        LineGraphDataPoints points;

        // add 3 points to the class
        for(uint8_t i = 0; i < 3; i++)
        {
            POINT pt;
            pt.x = counter + i;
            pt.y = analogRead(14);
        }

        if(counter >= 75)
        {
            /*
                If the counter is higher than 75 points, the grid is shifted in x direction to the left
                this holds the measure point inside of the valid view area
            */
            LaRoomyApi.lineGraphFastDataPipeAddDataPoints(MY_LINEGRAPH_ID, points, 3.0f, LineGraphGridShiftDirection::LGS_SHIFT_X_AXIS_PLUS);
        }
        else
        {
            // no shift: add normal
            LaRoomyApi.lineGraphFastDataPipeAddDataPoints(MY_BARGRAPH_ID, points);
        }

        counter+=3;
    }
    
    /* other code */
    
}

lineGraphFastDataPipeAddPoint

  		
void lineGraphFastDataPipeAddPoint(cID lineGraphID, LPPOINT pPoint);
  	
  		
void lineGraphFastDataPipeAddPoint(cID lineGraphID, LPPOINT pPoint, float shifter, LineGraphGridShiftDirection dir);

This method can be used to add one single data-point to the existing line data in a LineGraph-Property. An overloaded method is provided to additionally shift the grid of the LineGraph in a defined direction.

Arguments:

lineGraphID - The ID of the LineGraph to which the point should be added.

pPoint - A pointer to a POINT struct containing the data for the point.

shifter - The distance to shift the grid.

dir - The direction in which to shift the grid. Type: LineGraphGridShiftDirection

Example:
  		
#define  MY_LINEGRAPH_ID  2

// timer params
long mTimer = 0;
long mTimeOut = 50;

// counter
unsigned int counter = 0;

void setup()
{
    /* other setup */
    
    // create a lineGraph
    LineGraph lineGraph;
    lineGraph.imageID = LaRoomyImages::LINE_GRAPH_163;
    lineGraph.lineGraphDescription = "My LineGraph";
    lineGraph.lineGraphID = MY_LINEGRAPH_ID;

    // configure the grid
    lineGraph.lineGraphState.drawAxisValues = true;
    lineGraph.lineGraphState.drawGridLines = true;
    lineGraph.lineGraphState.xMinValue = 0;
    lineGraph.lineGraphState.xMaxValue = 100;
    lineGraph.lineGraphState.yMinValue = 0;
    lineGraph.lineGraphState.yMaxValue = 4100;
    lineGraph.lineGraphState.xIntersection = 10;
    lineGraph.lineGraphState.yIntersection = 500;

    // add the LineGraph to the Api
    LaRoomyApi.addDeviceProperty(lineGraph);
    
    /* other setup */
    
    // init timer reference
    mTimer = millis();    
}

void loop()
{
    // put your main code here, to run repeatedly:

    LaRoomyApi.onLoop();
    
    // invoke in a 50ms interval, but only transmit if the respective property page is opened
    if ((millis() > (unsigned long)(mTimeOut + mTimer)) 
            && (LaRoomyApi.getCurrentOpenedPropertyPageID() == MY_LINEGRAPH_ID))
    {
        // update timer reference
        mTimer = millis();
        
        // create a point (x-pos = current counter / y-pos = adc measure result)
        POINT pt;
        pt.x = counter;
        pt.y = analogRead(14);

        if(counter >= 75)
        {
            /*
                If the counter is higher than 75 points, the grid is shifted in x direction to the left
                this holds the measure point inside of the valid view area
            */
            LaRoomyApi.lineGraphFastDataPipeAddPoint(MY_LINEGRAPH_ID, &pt, 1.0f, LineGraphGridShiftDirection::LGS_SHIFT_X_AXIS_PLUS);
        }
        else
        {
            // no shift: add normal
            LaRoomyApi.lineGraphFastDataPipeAddPoint(MY_BARGRAPH_ID, &pt);
        }

        counter++;
    }
    
    /* other code */
    
}