# TMX Insight™ Service Platform 2.6 User Guide

# 1 Preface

This guide is primarily intended to give a comprehensive understanding of the TMX Insight™ Service Platform. The Platform represents the TMX Insight™ Service Platform in this document.

# 2 Overview

The Platform has the capability of analyzing some telemetry data and presenting more helpful information. Once the Platform receives the device data, both the historical data and statistics data are available to view. Please refer to 9.8 Viewing device details in TMX Access™ Service Platform User Guide for further information. In current release, the Platform provides Dashboards for customized data visualization, Flows and Functions for data configuration, Buckets for data storage. In Flows, Actions with policies are also provided for better data monitoring and safety purposes.

Based on a user's requirements, each deployment can have various components and features. Throughout those components, the Platform provides the following features:

• Buckets
• Dashboards
• Flows
• Functions
• APIs

# 3 Browser Compatibility

# 3.1 Supported Browsers

The Platform currently only supports Chrome and Firefox.

# 4 Supported Devices

# 4.1 Device Models

IoT Gateway is responsible for device communication via TCP or TLS. Different protocols are supported and used for the communication with each unique device model. The IoT Gateway currently supports the following ThingsMatrix approved devices:

Version	Model	Description
1.x	TMA01	Logistics Tracker (2G, LTE)
	TMA11	Detachable Sensor Hub for TMA01
	TMX06	Tracker (2G)
	TMX07	Tracker (LTE Cat-M)
	TMM01	Certified 3rd party devices
2.x	TMX08	Collector Tracker (Cat-M)
	TMF01	Fibocom IoT Modules (NL668, MT910, etc)
	TMY01	Tracker (2G, Cat-M)
	TMY02	Tracker (2G, Cat-M, NB)
	TMX09	Tracker (2G, Cat-M, NB)
	TMY07	Tracker (2G, Cat-M, NB)
	TMY09	Tracker (2G, Cat-M, NB)
	TMY03	Tracker (2G, Cat-M, NB)
	TMY05	Tracker (2G, Cat-M, NB)
	TMX01	Tracker (2G LTE Cat-M)
	TMX02	Tracker (2G LTE Cat-M)
	TMX03	Tracker (2G)
	TMX04	Tracker (2G LTE Cat-M)
	TMX05	Tracker (2G)
	Custom	3rd party devices applying MQTT protocol

# 5 Get Started

Please make sure you have already registered a TMX Account and also subscribed the TMX Insight™ service. Please refer to Console 2.6 User Guide for further information.

# 6 Home

Once you sign in successfully, it enters the TMX Insight™ homepage where some report statistics charts describe data activities as follows:

• Flow Hits

  It gives a pie chart of status and model distribution of all flow executions.

• API Calls

  It counts the number of API calls for a certain period of time (today or last 7/30 days).

• Bucket Data Usage

  It counts the amount of bucket data usage for a certain period of time (today or last 7/30 days).

# 7 Buckets

Bucket applies storage strategy on data store, and it unifies the data format for easier process.

# 7.1 Adding new buckets

Click the + Add Bucket button and an Add Bucket window will pop up.

Fill in the form and then click the Add button to add a new bucket. For "Retention" field, you can define the time range of data collection. For example, if a retention of 60 days is selected, the bucket will store the data generated for 60 days.

# 7.2 Editing buckets

Select the bucket you want to edit and then click the Edit button, an Edit Bucket window will pop up.

After the edition, click the Submit button to save the changes. Please note: The "Retention" field cannot be modified.

# 7.3 Adding new bucket fields

Select a bucket, then enter the Bucket Field tab. A preset bucket field time is provided to represent the time that data is sampled. Click the Add button to add a new bucket field. You can enter field identifier, field title, type of field value, unit of field value, min value of field value if required, max value of field value if required, and a description of the field. If you want to add more than a bucket field, click the Add button to add more fields. All the added fields will be listed in the bucket field list below.

# 7.4 Deleting bucket fields

Click the Delete button to delete a specific bucket field. Please note: Bucket fields in use and preset bucket fields cannot be deleted.

# 7.5 Viewing buckets

There are several tabs shown as below:

• Bucket Field

  It is for bucket data field management.

  

• Dashboards

  It shows all the charts configured in Dashboard and set to be enabled in TMX Access™ - Settings for the selected bucket. Please refer to 8 Dashboards and 14 Settings in TMX Access™ Service Platform 2.6 User Guide for further information.

  

• Bucket Data

  It shows all the data configured and stored in the bucket. You can filter data by specifying device serial number and selecting time range.

  

  You can export bucket data by clicking the Export button on the right side. An Export window will pop up, and you can choose to get the data exported in Excel or CSV format.

  

# 7.6 Deleting buckets

Select the bucket you want to delete and then click the Delete button to delete the bucket. Please note: A bucket in use cannot be deleted.

# 8 Dashboards

The Platform provides data visualization and autonomous configuration of visual data through the dashboard to help users monitor and analyze data. In the Dashboard, you can configure charts based on actual needs to monitor real-time data or historical data change tracks for individual devices. You can also configure statistical charts to count the total number of devices in the company and their status distribution. When configuring the charts, you can also configure the time period for the chart display and select refresh interval in order to define its frequency.

# 8.1 Adding new dashboards

Before you can add a new chart, you need to add a new dashboard. By clicking the + Add Dashboard button on the top right, an Add Dashboard window will pop up. Enter the name and then click the Add button to add a new dashboard.

# 8.2 Viewing dashboards

Simply click the dashboard card to view the dashboard detail.

There are several quick configurations can be set in the dashboard as shown below:

Please note: Edition of the configuration here will not be saved. It is only for quick chart configuration.

• General:

  • Time Range:

    Select time range of data collection.

  • Refresh Interval:

    Set chart refresh frequency.

• Variable:

  • Group Name Bar:

    Quickly generate charts for a specific group. After configured a new group, all charts in the dashboard will be configured by the specific group, no matter which group they were configured by before.

  • Serial Number Bar:

    Quickly generate charts for a specific serial number (you can enter at least 3 characters to select the desire one). After configured a new serial number, all charts in the dashboard will be configured by the specific serial number, no matter which serial numbers they were configured by before.

  • Bucket Name Bar:

    Quickly generate charts for a specific Bucket. After configured a new bucket, all charts in the dashboard will be configured by the specific Bucket, no matter which Bucket they were configured by before.

  • Field Identifier Bar:

    Quickly generate charts for a specific field. After configured a new field, all charts in the dashboard will be configured by the specific field, no matter which fields they were configured by before.

The platform also provides Full Screen view for the specific dashboard. Simply click the ... button and then click the Full Screen button to enter the Full Screen view.

An example is shown as follows:

# 8.3 Editing dashboards

By clicking the Settings button, you can enter the dashboard settings page. In this page, you can rename the dashboard and also determine which quick configurations to be displayed in dashboard detail page.

For "Hide Field" in General, if it is on, the quick configurations section will not display in the dashboard detail page.

For "Group", "Serial Number", "Bucket" and "Field" in Variables, Query type means user can perform fuzzy search and all the options cannot be customized, while Custom type means you can customize the options. If Text box type is selected, it allows users to enter arbitrary values. A default value for it can be pre-configured here.

After finishing the configuration, click the < button to go back to dashboard detail page.

Then click the Save Dashboard button to save the changes.

# 8.4 Adding new panels

In the dashboard detail page, by clicking the Add Panel button, all supported panel types will be displayed, including the Graph, Gauge, Table, Pie, Stat and Map panel.

Let's take the Graph panel as an example. Click the Graph button and an empty graph is created.

# 8.5 Editing panels

Click the ... button on the top right of the panel and then click the Edit button to enter the panel detail page.

There are several tabs shown as below:

• Data

  Data source configuration.

  

  To configure a specific data source, please follow these steps:

  1. Select a type of Data Source, for example, Device Telemetry Data.

  2. Enter the Serial Number of the specific device. For convenience, you can enter at least three characters to perform fuzzy search.

  3. Select a desired Data Field, such as Signal Strength.

     

  Click the + Add Data button to add more data sources.

  

  By clicking the Copy button, a copy of the specific data source is generated for you to edit.

  

  Also, you can click the Hide button to hide a specific data source. Please note: The hidden data will neither display in panel detail page nor panel view page.

  

  To delete a data source, click the Delete button. Please note: If there is only a data source, it cannot be deleted.

  

• Visualization

  Visual configuration of chart. Data Show, Axes and Legend can be customized in this tab.

  

• General

  General Settings, including Panel Name, Data Range and Refresh Interval.

  

After finishing all the settings, please click the < button to go back to dashboard detail page, and then click the Save Dashboard button to save all the changes.

The panel size can be adjusted by dragging its border to give a more comfortable visual experience.

Also, the panel can be relocated by dragging it. Hover the mouse over its blank space, when the cursor turns into a dragging icon, you can rearrange the position of the panels.

# 8.6 Viewing panels

By clicking the ... button on the top right of the panel and then clicking the View button, it enters panel view page.

In dashboard detail page, you can click the ... button on the top right of the specific panel and then clicking the Refresh button to refresh the data immediately.

# 8.7 Importing panels

Click the ... button on the top right of the panel and then click the Import button to import panels.

Click the Browser button to upload a JSON file, then click the Import button to import panels.

# 8.8 Exporting panels

Click the ... button on the top right of the panel and then click the Export button to export panels.

# 8.9 Deleting panels

Click the ... button on the top right of the panel and then click the Delete button to delete the panel.

# 8.10 Copying dashboards

In the dashboard card page, click the ... button on the top right of the dashboard card and then click the Copy button to copy the dashboard.

# 8.11 Deleting dashboards

Click the ... button on the top right of the dashboard card and then click the Delete button to delete the dashboard. Please note: The dashboard can only be deleted when it is not configured in ThingsMatrix Access™ - Settings.

# 9 Flows

The Platform provides a browser-based editor that makes it easy to create computational flows to obtain desired data based on reported data by devices. Flows are independent between different models.

# 9.1 Adding new flows

Select a model, TMX08 for example, click the + Add Flow button and a new Flow block will appear. Enter the name of the flow and then click the Save button to add a new flow.

# 9.2 Renaming flows

By Clicking the ... button and Edit button, you can rename the flow.

# 9.3 Configuring flow components

There are several components which can be configured in a flow as shown below:

Click the flow block to enter flow detail page.

• Filter: Select input data.

  You can select specific groups and topics (Only for custom models applying MQTT protocol) to make the data as the input of the flow. Please note: All device data will go through the flows by default.

  

  After the configurations, click the Save button to save the changes.

• Transformer: Configure functions used by the flow.

  You can select specific functions to be applied by current flow. Please note: No function is applied by the flows by default.

  

  The Function library is on the left side and the Function in Transformer list is on the right side. By clicking the Select button, you can select functions from the library to be used in the Transformer. Please note: If you want to use your own functions, you need to configure them in Functions before you can select them from the library. If not, there are some preset functions in the library for you to use. To remove functions from the transformer, select the function and then click the delete button. By clicking the Remove All button, all selected functions are removed from the list. You can also search for functions in the searching bar. Hover the mouse over the selected function, when the cursor turns into a dragging icon, you can edit the order for executing the functions. After editing the transformer, click the Save button to save the settings. Please refer to 10 Functions for further information. An example of applying the Ultrasonic Temperature Compensator function and then the temp_minus function is shown as below:

  

• Action: Determine the actions on data computed by flow.

  You can select specific actions to be triggered by current flow. Please note: No action is triggered by the flows by default.

  By clicking the + Add Action button, an empty action form will appear. Select an action type and enter a name for it. Click the + Add Condition button to configure trigger conditions if desired. Select Match Any or Match All to configure condition determination. You can choose to trigger the action immediately, or only if the duration is greater than a certain period of time, or the consecutive time is greater than a specific value.

  

  Platform provides several action types for example as follows:

  • Event: Generate event records to TMX Access™ - Events, including event codes and alarm codes. Please refer to 12 Events in TMX Access™ Service Platform 2.6 User Guide for further information.

    The Platform provides three trigger types for event generation:

    • Every time when condition(s) match

      Trigger an event every time if the current data matches the above condition(s).

      Enter a event code, for example low_temperature_event, select a level and add a description for the event.

    • Only first time in a row of condition(s) match

      Trigger only an event for the first time in a row of data matching the above condition(s).

      Enter a event code, for example high_humidity_event, select a level and add a description for the event.

    • Condition match status has changes

      Trigger an on event if the data didn't match the above condition(s) or no data reported last time, but it matches this time. Also, trigger an off event if the data matched the above condition(s) last time, but it doesn't match this time.

      Enter an alarm code, for example low_battery_alarm, select levels and add different descriptions for both the on event and off event.

    Click the Save button to save the changes.

    

  • Bucket: Store processed data in specific bucket. Please refer to 7 Buckets for further information.

    Click the + Add Data button to add a configuration into the bucket field and flow result mapping list. An example of a bucket field of temperature which has already been added in the bucket is shown as below:

    

    Then click the Save button to save all the changes.

  • SMS: Send an SMS message to a specific phone number.

    Enter a phone number and add a description for the SMS message, then click the Save button to save all the changes. The targeted user will receive an SMS message with a URL to login on to the Platform to read the content if the data matches the condition(s).

    

  • URL: Push processed data to a specific URL.

    Enter a URL, then click the Save button to save all the changes.

    

  • Email: Send processed data to specific email address(es).

    Enter an valid email address, then click the Save button to save all the changes. Please note: Press the Enter key to apply an email address. The email will be sent to the applied email address(es) only. If in red, it has been regarded as an invalid email address.

    

  • Command: Issue control commands to the devices in Filter.

    Select a command type, then click the Save button to save all the changes. Please note: If parameters are required, please fill in the parameters.

    

• Debug: Display debug messages.

  For the Debug switch, if it is on, the debug messages for most recent data flow will display.

  

  Click the Refresh button to refresh the log.

# 9.4 Inserting flows

Click the ... button and then click the Insert Flow button to insert a new flow. After entering the name of the flow and clicking the Save button, a new flow is inserted below.

# 9.5 Running flows

When a flow is running, it will compute every time when there is input data. To run a flow, simply switch the Flow switch to Run. Please note: A running flow cannot be edited. However, the Debug switch is still valid.

You can also perform batch running for all the flows by clicking the Run All button.

# 9.6 Stopping flows

When a flow is stopped, it will stop computation. To stop a flow, simply switch the Flow switch to Stop. Please note: If you want to edit a flow, you need to stop it first.

You can also perform batch stopping for all the flows by clicking the Stop All button.

# 9.7 Importing flows

Click the ... button and then click the Import button, an Import Flow window will pop up.

Select Import Above to import all the flows in the front of current flow or Import Below to import all the flows at the back of current flow.

Click the Upload File button to select a JSON file, then click the Import button to import flows.

# 9.8 Exporting flows

Click the ... button and then click the Export button to export the selected flow.

You can also perform batch export for all the flows by clicking the Export All button, a JSON file with all flows' information will ask for being downloaded.

# 9.9 Replacing all flows

To import new flows and replace all original flows, simply click the Replace All button. An Replace All window will pop up.

Click the Upload File button to select a JSON file, then click the Import button to replace all flows.

# 9.10 Deleting flows

Click the ... button and then click the Delete button to delete the flow. Please note: Only stopped flows can be deleted.

# 10 Functions

A function is used for computing data as a component of a flow. There are some preset functions in the library shown as below:

A function is in use only when it is configured by a running flow.

# 10.1 Adding new functions

Click the + Add Function button, an Add Function window will pop up.

You can enter a title for the function, write a description and perform some coding tasks. Instructions are on the right side and a syntax parser is provided to help you write the code. The programming language is JavaScript inside the coding section. Please note: You do not need to write a return statement. The unit of timestamp is millisecond (13 digits), and the valid time string format is "yyyy-MM-dd HH:mm:ss.SSS". After finishing the form, click the Add button to add a new function. An example for temperature compensation is shown as below:

# 10.2 Editing functions

Simply click the function card or the Detail button to edit the function.

After the edition, click the Save button to save the changes. Please note: Functions in use and preset functions cannot be edited.

# 10.3 Copying functions

Click the Copy button, a Copy Function window will pop up. Before clicking the Copy button to copy the function, you can perform edition on it based on requirements.

# 10.4 Deleting functions

Click the Delete button to delete the function. Please note: Functions in use and preset functions cannot be deleted.

# 11 API Services

The Platform provides north bound API services to external users and systems. For detailed technical information, please refer to ThingsMatrix Service Platform API Guide.

# 12 Notification Board

The Platform provides Notification Board to display notifications and messages, such as system upgrade schedule and over limit/frequency alert of SMS, URL and email usage. If there is a red dot next to the Ring button on the top right side, several new notifications have been received.

By clicking the Ring button, a Notification Board will pop up. It will display all notifications and messages. You can filter notifications by selecting a desired notification type.

Click the unread notification for detailed content. Please note: The notice with a red dot means that it hasn't been read yet.

Click the Confirm button to confirm the notice.