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 Service Platform 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
Data Bucket applies storage strategy on data store, and it unifies the data format for easier process. It is an object to combine Channel and Policy features. Together with data Transformer, it provides a better way to define data Flow.
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 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 shows bucket data fields.
Dashboards
It shows all the charts configured in Dashboard feature and set to be enabled in 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 bucket data exported in
Excel
orCSV
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 section, 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 left, 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:
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.
Please note: Edition of the configuration here will not be saved. It is only for quick chart configuration.
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 section, 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 section, 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:
Select a type of Data Source, for example,
Device Telemetry Data
.Enter the Serial Number of the specific device. For convenience, you can enter at least three characters to perform fuzzy search.
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, users 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, users 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 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 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, TMX07 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 all 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.
There is a Function Library on the left side and a Function in Transformer List on the right side. By clicking the Right 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 Data - Function 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 functions and then click the Left button. You can also search for functions in the searching bar. Click the Up/Down button to modify the order for executing the functions. After modifying the transformer, click the Save button to save the settings. For more information about function, please refer to 10.4 Function section. 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 applied by current flow. Please note: No action is applied 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.
Add necessary conditions, for example as follows:
Event: Generate event records to event list, including event codes and alarm codes. Please refer to 12 Events in TMX Access™ Service Platform 2.6 User Guide for further information.
Enter a name and add a description for the event, then click the Save button to save all 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.
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 "On". 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 "Off". 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 Save 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 all 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.