Summary

We will walk through how to set up this type of device in the Samsara Cloud. You will map data inputs according to the protocol the third party device is communicating through.

Create Third Party Device

NOTE: This device type requires the use of the Samsara 4-Port Serial Cable Adapter (USB to 4x RS232 Converter, SKU = CBL-IG-CS), and will not function with the built-in serial adapter, or any other serial hardware device. Contact your Samsara Account Executive for more information.

To map your third party registers in the Cloud, go to Settings > Third Party Devices > + Configure New Device. Fill out the details in the box below and hit Create.

  • Name: Give your device a name that is unique and descriptive

  • Gateway: Select the IG connected to the device you’re bringing data in from

  • Type: Serial

  • Baud Rate, Data Bits, and Stop Bits: These parameters dictate how a packet of information is formatted. Typically baud rate is 9600, with 8 data bits, no parity, and 1 stop bit.

  • Protocol: Select the appropriate serial protocol, RS-232 or RS-485.

  • Port: The port number of the 4-port USB->Serial cable that the interactive serial device is connected to.

  • Please consult your Device instructions for the parameters appropriate for your device.

Create Registers

Add Registers In Bulk

You can use the bulk data setup tool to configure many registers, pins, or tags AND create and map to data inputs or outputs automatically. Read this article for an in depth guide on how to use the bulk data setup tool: Add Third Party Device Registers with the Bulk Edit Tool , or follow along below to see more details on how to configure registers one at a time according to the device type.

Add Registers One at a Time

After specifying the protocol by creating the Device, you now will map the data inputs on the device within your cloud dashboard. These data inputs are called “Registers”.

  • To start, go to Settings > 3rd Party Devices > select the 3rd party device you would like to map > + Configure New Register

  • Once selecting +Configure New Register you will see the screen below

  • Name: Give the register a unique name for later reference.

  • Command: If the connected device requires that a command be sent to trigger a response, enter it here. If no command is required, simply leave this blank by entering a space.

  • Response Regex: A regular expression to parse the response data into ‘Matches’. See regex101.com or  https://www.rexegg.com/regex-quickstart.html for information on regular expressions.

  • Regex Match Index: This will determine which ‘Match’ to select data from. The index begins at 0. This means if you want the first match to be selected, enter 0. 

  • Regex Submatch Index: This will determine which submatch within the Match Index to be selected.

Examples

For full explanation and documentation on regular expressions and how to parse, please visit regex101.com and the Regex Cheat Sheet.

Example 1

The response RegEx will search the response for keywords or patterns. In this first example, we search for the word “first”. Since this is the only instance it will be the first and only match and submatch.

  • Response RegEx = (first)

  • Match Index = 0

  • Submatch Index = 0

Note: Regex101.com uses ‘1’ for the first match, Samsara uses ‘0’. 

Example 2

 Here we are searching for ‘This is’. Notice there are 2 Matched Index’s and 2 Submatched Index’s. This is how we can drill down to grab individual instances.

Please note: the above examples search for words. For the Samsara System, you may search for words but any selected values must be numbers to be ingested into the Samsara System.

Example 3

Here we want to parse out all the values from a string of data returned from the command: 

102419 183102 23.048 8.69 20.04 19.49 8.65 65.76 13.61 0.00 -103.75 0.00 101.38 0.00 14.70 0.04
CODE

Using information from regex101.com & Regex Cheat Sheet we created the following Regex: (\S+)\s?

  • 1st Capturing Group (\S+)

    • \S+ matches any non-whitespace character (equal to [^\r\n\t\f\v ])

    • + Quantifier — Matches between one and unlimited times, as many times as possible, giving back as needed (greedy)

  • \s? matches any whitespace character (equal to [\r\n\t\f\v ])

    • ? Quantifier — Matches between zero and one times, as many times as possible, giving back as needed


Result

  • Match 0

    • Submatch 0 

      • Samsara brings in= 102419

  • Match  1

    • Submatch 0

      • Samsara brings in= 183102