Data Route

Data routes provide a simple and compact way for developers to access MetaWear’s advanced features such as logging, data processing, and on-board event handling. The routing API has been improved upon from MetaWear API v2 and has also been refactored to accommodate lambda expressions.

Creating Routes

Routes are created by calling the addRouteAsync function of the DataProducer you want to interact with. The addRouteAsync function accepts a RouteBuilder countaining the collection of RouteComponent calls that define how data flows from a producer to different endpoints.

public void createRouteExample(DataProducer producer) {
    producer.addRouteAsync(new RouteBuilder() {
        @Override
        public void configure(RouteComponent source) {
            // define route here with RouteComponent objects
        }
    });
}

All route objects have a unique numerical value associated with them. You can retrieve routes anytime using this numerical ID with the lookupRoute method.

Handling Data

Data created by the data producers is represented by the Data interface, encapsulating key attributes such as the time the data was created (or receieved) and the value of the data sample. Data objects are consumed by Subscribers attached to the route via the stream or log component.

When accessing the data value, you need to specify what type the value should be casted to. Valid class types passed to the value method differ depending on the data producer; a ClassCastException is thrown if an invalid class type is used. Developers can use the types method to get a list of valid class types that can be used with the value function of the particular Data object.

public static void logDataTypes(Data data) {
    Log.i("MainActivity", "Class types; " + Arrays.toString(data.types()));
}

Stream

Creating a live data stream to your Android device is handled with the stream component. The data from the most recent producer will be sent live to the Subscriber.

public void streamData(DataProducer producer) {
    producer.addRouteAsync(new RouteBuilder() {
        @Override
        public void configure(RouteComponent source) {
            source.stream(new Subscriber() {
                @Override
                public void apply(Data data, Object... env) {
                    Log.i("MainActivity", data.toString());
                }
            });
        }
    });
}

Log

Alternatively, you may want to record data to the on-board flash memory and retrieve it at a later time. Constructing a logging route follows the same steps as a streaming route except you use the log component.

public void logData(DataProducer producer) {
    producer.addRouteAsync(new RouteBuilder() {
        @Override
        public void configure(RouteComponent source) {
            source.log(new Subscriber() {
                @Override
                public void apply(Data data, Object... env) {
                    Log.i("MainActivity", data.toString());
                }
            });
        }
    });
}

Note that this only creates a route to handle logged data; you still need to tell the logger when to start/stop logging data and when to download the recorded data. More information on controlling the logger is provided in the Logging section.

Reaction

A reaction is a collection of MetaWear commands programmed onto the board that is executed when the source producer has created new data. Developers can use this feature to have the board react to new data without needing maintain an active connection to the board.

The MetaWear commands you want programmed onto the board are contained in an Action object which is passed into the react component.

// Turn on the led everytime new data is available from the producer
public void addReaction(DataProducer producer, final Led led) {
    producer.addRouteAsync(new RouteBuilder() {
        @Override
        public void configure(RouteComponent source) {
            source.react(new RouteComponent.Action() {
                @Override
                public void execute(DataToken token) {
                    led.editPattern(Led.Color.BLUE, Led.PatternPreset.SOLID);
                    led.play();
                }
            });
        }
    });
}

Split

Splitters break down combined data into its individual components i.e. the xyz values in acceleration data. When you add the split component, you can refer to each data component with the index component. Note that you must call index immediately after calling split.

public void splitAccData(AccelerationDataProducer acceleration) {
    // stream z-axis data from accelerometer
    acceleration.addRouteAsync(new RouteBuilder() {
        @Override
        public void configure(RouteComponent source) {
            source.split().index(2).stream(new Subscriber() {
                @Override
                public void apply(Data data, Object... env) {
                    Log.i("MainActivity", "Z-axis: " + data.value(Float.class));
                }
            });
        }
    });
}

Multicast

The multicast component creates branches in the route where the same data can be pass to different route components. Starting a new branch is expressed with the to component and you can specify as many branches as you need provided the firmware has enough resources to allocate the additional route components. Keep in mind that you must call to immediately after calling multicast.

// Convert value to Kelvin and Farenheit for all temperature data
public void createMulticast(Temperature.Sensor tempSensor) {
    tempSensor.addRouteAsync(new RouteBuilder() {
        @Override
        public void configure(RouteComponent source) {
            source.multicast()
                .to().stream(new Subscriber() {
                    @Override
                    public void apply(Data data, Object... env) {
                        Log.i("MainActivity", "Celsius = " + data.value(Float.class));
                    }
                }).to().map(Function2.MULTIPLY, 18)
                    .map(Function2.DIVIDE, 10)
                    .map(Function2.ADD, 32)
                    .stream(new Subscriber() {
                        @Override
                        public void apply(Data data, Object... env) {
                            Log.i("MainActivity", "Fahrenheit = " + data.value(Float.class));
                        }
                    })
                .to().map(Function2.ADD, 273.15).stream(new Subscriber() {
                    @Override
                    public void apply(Data data, Object... env) {
                        Log.i("MainActivity", "Kelvin = " + data.value(Float.class));
                    }
                });
        }
    });
}

Data Processing

One of the neat features of the MetaWear firmware is the abiliy to manipulate data on-board before passing it to the user. Processors can be chained together to combine multiple operations in one route. Note that data processors can have stream and log components attached to them as well.

Data processors are identified by a globally unique name using the name component. This name is used to identify the processor in the Data Processor module or to construct feedback loops with the comparator or mapper.

Account

The accounter processor adds additional information to the BTLE packet to reconstruct the data’s timestamp, typically used with streaming raw accelerometer, gyro, and magnetometer data. This processor is designed specifically for streaming, do not use with the logger.

public void accountAccData(AccelerationDataProducer acceleration) {
    acceleration.addRouteAsync(new RouteBuilder() {
        @Override
        public void configure(RouteComponent source) {
            source.account().stream(new Subscriber() {
                @Override
                public void apply(Data data, Object... env) {
                    Log.i("MainActivity", "realtime: " + data.formattedTimestamp());
                }
            });
        }
    });
}

If there is not enough space to append timestamp data, i.e. sensor fusion outputs, a sample count can instead be added to the packet. The count value is accessed via the extra function.

import com.mbientlab.metawear.builder.RouteComponent.AccountType;

public async void accountData(IAsyncDataProducer producer) {
    acceleration.addRouteAsync(new RouteBuilder() {
        @Override
        public void configure(RouteComponent source) {
            source.account(AccountType.COUNT).stream(new Subscriber() {
                @Override
                public void apply(Data data, Object... env) {
                    Log.i("MainActivity", "sample: " + data.extra(Long.class));
                }
            });
        }
    });
}

Accumulate

An accumlator tallies a running sum of all data that passes through. The running sum can be reset to 0 or set to a specific value using an AccumulatorEditor.

public void accumAbsRef(Gpio.Pin pin) {
    pin.analogAbsRef().addRouteAsync(new RouteBuilder() {
        @Override
        public void configure(RouteComponent source) {
            // sum the values from gpio abs reference voltage
            source.accumulate();
        }
    });
}

Average

This component is renamed to lowpass in SDK v3.1.

Buffer

Buffers store the most recent input in its internal state which can accessed using the state method from the Data Processor module. As there is no output from the buffer processor, you cannot chain additional route components after the buffer.

public void bufferTempData(Temperature.Sensor tempSensor) {
    tempSensor.addRouteAsync(new RouteBuilder() {
        @Override
        public void configure(RouteComponent source) {
            // store temp data in buffer named "temp_buffer"
            // read buffer state with DataProcessor module
            source.buffer().name("temp_buffer");
        }
    });
}

Count

Add a count component to tally the number of data samples received. The output from this processor is the current running count. Use a CounterEditor to reset the count or set it to a specific value.

public void countData(DataProducer producer) {
    producer.addRouteAsync(new RouteBuilder() {
        @Override
        public void configure(RouteComponent source) {
            // Count number of data samples produced
            source.count();
        }
    });
}

Delay

The delay component stalls further route activity until it has collected N samples.

public void delayData(DataProducer producer) {
    producer.addRouteAsync(new RouteBuilder() {
        @Override
        public void configure(RouteComponent source) {
            // Collect 16 data samples before letting it pass
            source.split().index(2).delay((byte) 16);
        }
    });
}

Filter

Filter processors remove data that do not satisfy a given condition and are added to a route using the filter component.

Comparator

The comparison filter removes data from the route whose value does not satisfy the comparison operation. All 6 comparison operations (eq, neq, lt, lte, gt, gte) are supported.

import com.mbientlab.metawear.builder.filter.Comparison;

public void compareTempData(Temperature.Sensor tempSensor) {
    tempSensor.addRouteAsync(new RouteBuilder() {
        @Override
        public void configure(RouteComponent source) {
            // removes temperature data that is not greater than 21C
            // from the route
            source.filter(Comparison.GT, 21f);
        }
    });
}

As of firmware v1.2.3, the comparator has been updated to compare against multiple values. The variant filter component accepts an extra ComparisonOutput enum which provides other information about the multi-value comparison.

Output Descripion
Absolute Input value is returned when the comparison is satisfied, behavior of old comparator
Reference The reference value that satisified the comparison is outputted
Zone Outputs the index (0 to n-1) of the reference value that satisfied the comparison, n if none are valid
Pass / Fail 0 if the comparison fails, 1 if it passed
import com.mbientlab.metawear.builder.filter.ComparisonOutput;

public void multiCompareTempData(Temperature.Sensor tempSensor) {
    tempSensor.addRouteAsync(new RouteBuilder() {
        @Override
        public void configure(RouteComponent source) {
            // Create 3 ranges: T < 0C [0], 0C < T < 21f [1], and 21C < T < 31C [2]
            // return which range the input resides in
            source.filter(Comparison.LT, ComparisonOutput.ZONE, 0f, 21f, 38f);
        }
    });
}

Keep in mind that if you are using zone or pass/fail type comparisons, the comparison will be treated like a Map component instead. You will need to chain an additional absolute or reference type comparison to restore the original filter behavior.

public void zoneCompareFilter(Temperature.Sensor tempSensor) {
    tempSensor.addRouteAsync(new RouteBuilder() {
        @Override
        public void configure(RouteComponent source) {
            source.filter(Comparison.LT, ComparisonOutput.ZONE, 0f, 21f, 38f)
                    // do not let (zone == 3) values through i.e. prior zone comparison failed
                    .filter(Comparison.NEQ, ComparisonOutput.ABSOLUTE, 3);
        }
    });
}

Differential

Differential filters compute the distance between the current data value and a reference value, and only lets the data through if the distance is greater than a set threshold. When data that satisfies this criteria is found, the reference point will be updated to the last allowed value.

This filter also has three output modes that provide different information about the input data:

Output Description
Absolute Input passed through as is
Differential Difference between current and reference
Binary 1 if current < reference, -1 if current > reference
import com.mbientlab.metawear.builder.filter.DifferentialOutput;

public void adcDifferentialFilter(Gpio.Pin pin) {
    pin.analogAdc().addRouteAsync(new RouteBuilder() {
        @Override
        public void configure(RouteComponent source) {
            // Remove ADC data that is not at least 128 steps
            // from the reference point
            // Output the difference between the reference and input values
            source.filter(DifferentialOutput.DIFFERENCE, 128);
        }
    });
}

Threshold

The threshold filter only allows data through whose value crosses a boundary value, whether rising above the boundary or falling below it. It also has an alternate output mode that reports which direction the boundary was crossed.

Output Transformation
Absolute Input passed through untouched
Binary 1 if value rose above, -1 if it fell below

To prevent oscillations around the boundary from sending multiple data samples through, a hysteresis value can be set so that the threshold filter will only allow values that cross the boundary and lay outside the range [boundary - hysteresis, boundary + hysteresis].

public void thsAccXAxis(AccelerationDataProducer acceleration) {
    acceleration.addRouteAsync(new RouteBuilder() {
        @Override
        public void configure(RouteComponent source) {
            // let x-axis acceleration data through if it crosses the 1g boundary
            // with +/- 0.0001g of hysteresis i.e.
            // must be below 0.999g and above 1.0001g
            source.split().index(0).filter(ThresholdOutput.BINARY, 1f, 0.001f);
        }
    });
}

Find

The find component scans the data to see if it satisfies a pattern. Currently, the only available pattern is a pulse which is defined as a minimum number of consecutive data points that rises above then falls below a threshold. Both the threshold and minimum sample size can be later modified using a PulseEditor.

This processor also has 4 output modes that provide different contextual information about the pulse.

Output Description
Width Number of samples that made up the pulse
Area Summation of all the data in the pulse
Peak Highest value in the pulse
On Detect Return 0x1 as soon as pulse is detected
public void findAdcPulse(Gpio.Pin pin) {
    pin.analogAdc().addRouteAsync(new RouteBuilder() {
        @Override
        public void configure(RouteComponent source) {
            // find a pulse that has a minimum of 16 samples
            // rise above then fall below  512
            // Output the max value of the pulse
            source.find(PulseOutput.PEAK, 512, (short) 16);
        }
    });
}

High Pass

High pass filters compute the difference of the current value from a running average of the previous N samples. Output from this processor is delayed until the first N samples have been received. Use the AverageEditor to reset the running average.

public void hpfAccData(AccelerationDataProducer acceleration) {
    acceleration.addRouteAsync(new RouteBuilder() {
        @Override
        public void configure(RouteComponent source) {
            // delay stream by 4 samples, 5th sample and on are high pass filtered
            source.highpass((byte) 4).stream(new Subscriber() {
                @Override
                public void apply(Data data, Object... env) {
                    Log.i("MainActivity", "hpf acc = " + data.value(Acceleration.class));
                }
            });
        }
    });
}

Low Pass

Low pass filters compute a running average of the current and previous N samples. Output from this processor is delayed until the first N samples have been received. Use the AverageEditor to reset the running average.

public void averageAdc(Gpio.Pin pin) {
    pin.analogAdc().addRouteAsync(new RouteBuilder() {
    @Override
        public void configure(RouteComponent source) {
            // compute running average over 4 ADC values
            source.average((byte) 4);
        }
    });
}

Limit

Limiters control the amount of data that flows through the route. Add them to a route using the limit component.

Passthrough

The passthrough limiter functions as a user controlled gate using the value parameter to determine when to let data pass. There are three types of passthrough limiters:

Type Description
All Allows all data to pass
Conditional Only allow data through if value > 0
Count Only allow a fixed number of samples through

Both the value and type parameters can be modified using a PassthroughEditor.

public void dataPassthrough(DataProducer producer) {
    producer.addRouteAsync(new RouteBuilder() {
        @Override
        public void configure(RouteComponent source) {
            // Only allow 16 data samples through
            // Use DataProcessor module to reset the count when all 16 values pass
            source.limit(Passthrough.COUNT, (short) 16).name("acc_passthrough");
        }
    });
}

Time

Time limiters reduce the frequency at which data flows through the route. They are typically used to stream data at frequencies not natively supported by the sensor, or combined with a data processing chain to only stream processed data at certain intervals.

public void limitData(DataProducer producer) {
    producer.addRouteAsync(new RouteBuilder() {
        @Override
        public void configure(RouteComponent source) {
            // Reduce data rate to 10Hz
            source.limit(100);
        }
    });
}

Map

A mapper applies a function to the data letting developers modify the value of each data sample. All basic arithemtic is supported along with some bit shifting, sqrt, vector magnitude and rms.

public void mapAccData(AccelerationDataProducer acceleration) {
    acceleration.addRouteAsync(new RouteBuilder() {
        @Override
        public void configure(RouteComponent source) {
            // Apply the RMS function to all acceleration data
            source.map(Function1.RMS)
        }
    });
}

Packer

The packer processor combines multiple data samples into 1 BLE packet to increase the data throughput. You can pack between 4 to 8 samples per packet depending on the data size.

Note that if you use the packer processor with raw motion data instead of using their packed data producer variants, you will only be able to combine 2 data samples into a packet instead of 3 samples however, you can chain an accounter processor to associate a timestamp with the packed data.

public void packData(DataProducer producer) {
    producer.addRouteAsync(new RouteBuilder() {
        @Override
        public void configure(RouteComponent source) {
            // Combine 4 data samples into 1 BLE packet
            source.limit((byte) 4).stream(new Subscriber() {
                int count = 0;
                @Override
                public void apply(Data data, Object... env) {
                    Log.i("MainActivity", "Samples: " + count);
                    count++;
                }
            });
        }
    });
}