Summary

Formulas are a feature of Data Inputs that allow users to interpret and calculate the values that will be represented on dashboards and reports. This guide will show a few examples of common formulas and includes a table of acceptable operators and a list of other formulas available.

Data Inputs with Formulas Overview

Data Input Formula Requirements

  • Data Inputs referencing Gateway Channel or Mapped Registers (PLC) or Data Input sources*

  • Full-Admin or equivalent access on cloud.samsara.com

Note: Formulas are currently only accessible on the following Sources: Third Party Pin (PLC Mapped Registers), Gateway Channel and Data Inputs (see screenshot below). You can reference another Data Input as a Source which will allow you to add formulas to Samsara Sensor data or even multiple Data Inputs.

Operators and Modifiers

Below are some example modifiers that can be used in the formula bar:

Symbol

Modification

Example // x = 2

+ -

Addition

x+1 // Returns 3

  • / ** %

Multiplication

x**3 // Returns 8

>> << | &

Bitwise shifts, masks

See Bit Masking example in Custom Formula article: Create Custom Formula Data Inputs

Create Formula Inputs from Third Party Pin Inputs

  • Create Third Party Pin Inputs: Third Party Pin Data Inputs and Outputs

  • Now, you can create formula inputs based on these PLC Mapped Register Inputs

  • Use cases for formula inputs:

    • Your 3rd party device reports data in a raw form and needs to be scaled to engineering units. Use the Min/Max scaling or the custom formula to scale the data to the correct units. Ex: 0-65535 for a 16 bit register scaled to 0-100%

    • Your 3rd party device reports a boolean value or a multi-state integer value representing different states. Use the Map to Range values section to add numerical ranges and associated strings. Ex: Hand/Off/Auto for 0/1/2

Example of Creating Data Input Formulas for Inputs with Source =Third Party Pin

Create Formula Inputs from Gateway Channel Inputs

  • Create Gateway Inputs: Gateway Channel Inputs for Digital and Analog IO

  • Now, you can create formula inputs based on these Gateway Channel Inputs

  • Use case for formula inputs:

    • Your analog input records data as a raw voltage or current signal and needs to be scaled to engineering units. Use the Min/Max scaling or the custom formula to scale the data to the correct units.

      • Example: 4-20mA/0-10V to 0-60Hz

Example of Creating Data Input Formulas for Inputs with Source = Gateway Channel

Create Formula Data Inputs

In this section, we will go through how to create all the different types of formula inputs with Source = Data Inputs. Navigate to this article here:

Data Input Formula Source Type Options

  1. Predefined - Choose from a set of provided calculations

    1. Steps to create & examples outlined below

  2. Map Ranges to Values - Set data input ranges that map to your own custom values

    1. Steps to create & examples outlined below

  3. Moving Window Function - Calculate the rolling avg, max, or min value of an input reported over a time duration

    1. Steps to create & examples outlined below

  4. Aggregate - Calculate child asset values of the same Data Group within an assigned parent asset

    1. Create Aggregate Data Inputs

  5. Custom Values - Set your own formula

    1. Create Custom Formula Data Inputs

Create Predefined Data Inputs

Some predefined formulas are available to quickly set up formulas. Presets include but are not limited to Min, Max, Average, Totalize and more.

 You also can select a Time Window with which you would like this preset formula to reference.

Example of Predefined Data Inputs

  1. Average - The below data input with calculate a 15-minute average of the selected data input and report that value once per time window

  2. Totalize - The below data input will totalize the selected data input each hour. This is useful when you have a data input coming in as a rate (Gallons per minute, tons per hour) and you want to get a total amount of gallons or tons for the selected time window

Create Map Ranges to Values Data Inputs

If you want to apply text to different numeric states of data input, you can use the Map Ranges to values formula type. This allows you to specify number ranges and assign them names to display as text on dashboards and alerts.

Example of Map Ranges to Values Inputs

  1. The below map ranges to values data input will assign -1 and off when Chaparral Pump 1 Mode is -infinity to -1, 1 and on when >-1 to 1, and 2 and auto when >1 to infinity. This lets the user display On/Off/Auto on the dashboard.

Create Moving Window Function Data Inputs

Moving window functions let you create a rolling average that will smooth out data by plotting continuous averages, in one minute increments.  For example, you may want to calculate an average for the last 15 minutes, every minute. You can set this up by selecting the moving window function within a data input, selecting average, and setting the window size you’d like to use.

Example of Moving Window Function Data Inputs

  1. In the moving window function example below, unlike a predefined average function that evaluates once every 15minutes, the moving average function will continuously calculate a 15minute average and report that value to the newly created data input. This is useful to clean up data that may be noisy or data that bounces around a lot to make the dashboard trends look nicer.

Duplicate Data Input Formulas

With assets that have similar IO, it is useful to be able to duplicate calculations and data inputs across multiple assets. This saves a lot of time during setup and lets you do your work in bulk. Utilizing data groups, assets, and asset labels, some data inputs can be duplicated across any number of assets.

Duplicating data inputs works by pointing the input that is being duplicated to a subset of assets or an asset label. Samsara then uses the data group(s) of the data input(s) that are being used inside of the calculated data input, searches the target assets for data inputs with those data groups, and then creates a new data input in each of the target assets that is a copy of the original using the new data inputs.

Example

Asset 1 has two data inputs Flow 1 Raw Data with data group Raw Data and Average Flow with data group Average Flow. Assets 2, Asset 3, and Asset 4 all have data inputs with the data group Raw Data: Flow 2 Raw Data, Flow 3 Raw Data, Flow 4 Raw Data.

To duplicate Average Flow to these remaining three assets, do the following:

  1. Check that all data inputs are organized into their respective assets

  2. Check that all data inputs that will be in the newly created calculated share the same data group

  3. Optional: apply labels to assets to bulk select them when duplicating

  4. Navigate to the asset configuration page and open the asset where the calculated data input lives. Select the three dots to the right of the input that will be calculated and hit Duplicate:

  5. Select the assets that the new data input will be created in. Assets can be selected via label or individually:

  6. Hit Preview. Samsara will check to make sure the target assets have existing data groups that match the one(s) used in the data input that is being duplicated. If the group isn’t preset, it will flag the assets where there is no group. If a data input is duplicated to an asset that has no matching group, the data input will be duplicated as is and will not dynamically assign a new data input into the calculation.

  7. Hit Duplicate to duplicate data inputs into the target assets.