# TMX Insight™ Service Platform 2.0 User Guide

# Service Platform Overview

ThingsMatrix Service Platform enables IoT solutions with its modular approach in design and deployment. ThingsMatrix Service Platform consists of four main components: IoT Gateways (IOTGW), Device Management Platform (DMP), Connectivity Management Platform (TMX Connect™) and Control Management Centre (CMC). Each component can also be deployed independently based on the service requirements.

IOTGW handles device communication and interprets protocols and data.

DMP handles device and session management, data collection, storage, and reporting.

TMX Connect™ integrates with mobile operator networks and provides overall SIM management functionality, e.g. SIM status management, session management and usage reporting.

CMC is a core component which provides user management and centralized control functionality via a web UI interface. It also provides an API service which contains all business logics.

Based on a customer's requirements, each deployment can have various components and functions. Throughout those components, the whole system provides the following services:

  • User Management Service
  • Assets Management Service
  • Data Management Service
  • Connectivity Management Service

# Browser Compatibility

# Supported Browsers


The ThingsMatrix service platform currently only supports Chrome and Firefox.

# Supported Devices

# 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. ThingsMatrix IoT Gateway currently supports the following ThingsMatrix certified devices:

Version Protocol Model Description
1.x proprietary TMA01 Logistics Tracker (2G, LTE)
proprietary TMA11 Detachable Sensor Hub for TMA01
proprietary TMX06 Tracker (2G)
proprietary TMX07 Tracker (LTE Cat-M)
MQTT TMM01 Certified 3rd party devices
2.x proprietary TMX08 Collector Tracker (Cat-M)
proprietary TMF01 Fibocom IoT Modules (NL668, MT910, etc)
proprietary TMX09 Tracker (2G)
proprietary TMY01 Collector Tracker (Cat-M)
proprietary TMYO2 Collector Tracker (Cat-M)

# Device Data Fields


IoT Gateway parses data fields from device communication protocol and forms a JSON format data payload. Data fields supported by different device models are listed in table as below:

Name Description TMA01 TMA11 TMX06 TMX07 TMX08 TMF01 TMM01 TMX09 TMY01 TMY02
time Timestamp
lat Latitude
lng Longitude
gps GPS String
sn Serial Number
iccid SIM ICCID
imsi SIM IMSI
nmSn Network Module Serial Number
imei Device IMEI
deviceMcu Device CPU Usage (%)
deviceRam Device Memory Usage (%)
nmMcu Network Module CPU Usage (%)
nmRam Network Module Memory Usage (%)
cellId Cell Id
mcc Country Code
mnc Network Code
lac Area Code
singalStrength Cell Signal Strength
speed Speed (km/h)
altitude Altitude (m)
battery Battery (%)
voltage Battery Voltage (V)
ipAddress IP Address
net Mobile Network Type
firmware Device Firmware Version
ssn Sensor Hub Serial Number
temperature Temperature (C)
humidity Humidity (RH)
acceleration Acceleration
door Door Open (0: open/1: close)
gpsSpeed GPS Speed
direction Direction (0-359)
distance Ultrasonic Sensor (mm)
distance_1 Ultrasonic Sensor 1 (mm)
current Current Sensor (A)

# Control Management Center

# Functions Description


Control Management Center provides a user interface for enterprise users. Its main functions include user management and permission control, integration management as well as API services.

Within the Management Control Center user interface, the features are grouped into following four categories:

  • User Management Service
  • Connectivity Management Service
  • Assets Management Service
  • Data Management Service

# Main User Interface


Main User Interface has three main core sections: Navigation, Top Menu and Function Section:

Each service will be described in a separated chapter.

# User Management Service

ThingsMatrix Service Platform provides user management functionality for each company separately, which allows an administrator to create its own organizational structure and manage users through the organization menu. Based on all user information, the platform uses role-based access control function for all static configuration and applies user access control functionality in order to share device telemetry data for each individual.

# Role-Based Access Control


Across the platform, there are two default user roles setup internally.Default role cannot be modified.

  • Company Admin
  • Normal User

Company Admin has the privilege to manage all objects and configuration within his own company, such as add and delete devices. Normal user is allowed to view devices list, etc.

At the same time, company administrators have the privilege to configure roles. According to business needs, administrators can add roles, give them operational privileges, and assign them to the appropriate users.

# User Access Control


By default, normal user can only view devices and sensors lists, but is not allowed to view device data. The privilege of viewing device telemetry data is controlled under each device group. Only the user who has been permitted can access that data via GUI or API. Company Admin automatically has the access to all data.

# Company Registration and Deployment


Every new customer who wants to utilize the ThingsMatrix service platform, needs to provide the following information in order to initiate company registration and deployment:

  • Company Name
  • Unique Name Or Code (Used in domain URL)
  • Main Contact Email Address (Unique)
  • Email Domain (Multiple, by default it uses the email domain from main contact)
  • Selected Services

Once the request has been received by ThingsMatrix and a service contract is signed, ThingsMatrix is responsible for creating a new company on the platform. Meanwhile, the login URL will be sent together with an invitation email to the email address of the main contact person.

# User Registration


During the process of company platform creation, the first invitation is sent to the main contact with an administrator privilege. All users must provide username, firstname, lastname, email address, and contact details to sign up on the platform before they can access the information.

ThingsMatrix service platform provides three methods to add a user:

  1. Administrator can complete all user information and add the user directly. Temporary password is shared via email.
  2. Administrator can invite the user via email address, user can accept the invitation and complete the registration with an invitation code.
  3. User can use valid email address to complete sign up process via web page. The process will generate an invitation code and send it to user email address.

After a normal user completes the registration process, that user can then login into the platform with username and password. Administrator can change the user role later. Every user can modify the password via account center, administrator can reset a user's password from the user list. Every user can also generate an API Key in account center.

# Common Operations


Once a company setup is done, every company has a unique URL to access the platform. User needs username and password to login into the platform.

User can use email address to initiate registration process. This email address must be valid and the email domain has to match the configuration of the company.

After a user receives an invitation email, he can then complete the registration process by providing the invitation code.

Administrator can browse the organization page. He can add a user into the user list.

Administrator can also invite a new user via email if he does not have all the information from the user.

# Assets Management Service

# Function Description


This service is responsible for the overall management of devices and sensors. Device is an equipment which has an MCU, Network Module, GPS and build-in sensors. Sensor hub is a standalone equipment connecting to multiple sensors. It can be attached to a device, but it cannot communicate to the platform independently. Sensor hub has its own serial number. Assets Management Tab provides a list of functions for the operator to manage all devices and corresponding configuration. Under this tab there are three submenus: Device Management, Device List, and Sensor List. User can view the information of each device model, devices and sensors. Administrator can perform operations for device group and model configuration template, manage devices and sensors.

Device Management includes all configuration of Device Model and Device Group. Device List is a list of main equipment. Administrator can perform operations and execute query functions on those pages.

# Common Workflow


Each device model has its unique configuration file, which is used to define the basic settings, firmware version and ruleset of the device. Operator must specify Template Name and Device Model when clicking the new template button in order to add a configuration template.

Add/Modify Configuration Template

During Device registration and authentication, device configuration file will be passed to IoT Gateway and downloaded onto the devices. By default, a device group could have an empty configuration template. It means system and device will use its default configuration settings.

Device Group is a logical component which includes a group of devices with the same model. User can manage some common properties of devices.

Add/Modify Device Group

Group Name, Device Model Name, and Description are mandatory fields in order to add device group.

If the operator wants to modify the configuration template of device and sensor, it must be done on device group level. Administrator needs to go into the Device Management menu, select the correct device group which contains expected devices or sensors, and then click Modify. In the configuration of device group, administrator can choose different configuration templates from the dropdown menu. If template is changed, a manual reset of device or sensor need to be perform, the change need be applied on all devices or sensors in this group. If the administrator cannot see the template from the dropdown menu, then a template can be added the corresponding device model.

Device management is the primary function of the ThingsMatrix Service Platform. After a customer receives devices, a user can add a device into their repository by providing some basic information, such as Serial Number. During this process, the administrator can also provider the ICCID of the SIM card, the IMEI identify of the device or the Serial Number of the sensor. An Administrator can also leave those items as blank. It means the device will automatically collect and fill in this information once device connected onto the platform. There are auto update options to indicate whether the platform is allowed to perform any additional updates after the information is initally populated. If the platform detects these fields have changed on the Device but the platform is not allowed to auto update, then the platform will then reject the connection from the device. In addition, administrators can add a description, tags, and attributes onto a device.

Add/Modify a Device

Each TMX Certified device has a unique serial number but the length could be variable, e.g. TMA01 661890000000001

# Import/Export Device or Sensor


The TMX platform provides bulk import device functionality. Supports tables in both Excel and CSV formats. The form fill specification is as follows:

Example

SerialNumber Group Model Description Sim ICCID SensorSN Tags Attribute.Adress
861901268000009 TMX07_G2 TMX07 60s 89860437111890028017 661808008000092 San Antonio,Atlanta San Antonio,Atlanta
801046031116490 tmx08_0708 TMX08 Good 898607b2111730537722 661808008000093 302 San Antonio,Atlanta
801046031094416 tmx08_0708 TMX08 Good device 89011703278173974331 661808008000094 301

Completion Instructions

<1>SerialNumber, Group, Model are required fields, others are optional fields;

<2>SerialNumber: Unique identifier of the Device/Sensor;

<3>Group: The group to which the device belongs. Group must exist in the system first, and has a corresponding relationship with the model; if it is not in the system, please add it to the system first;

<4>Model: Model of the device;

<5>SimICCID: Must be 20 digits;

<6>SensorSN: Must be 8-16 bit characters, including digits 0-9 and leters A-Z;

<7>SimAutoUpdate: 0 means non-automatic update, 1 means automatic with new. Default is automatic with new, empty means default;

<8>SensorAutoUpdate: 0 means non-automatic update, 1 means automatic with new. Default is automatic with new, empty means default;

<9>Description: The number of words must be 0-200;

<10>Tags: Must be 1-50 characters, including digits 0-9, letters a-z and A-Z, characters "-", ".", "_", "@", "$" and blank space. The number of tags for a device does not exceed 20 tags and tags are separated by “,”;

<11>Attribute: The attribute is filled in by the header, such as "attribute:xx", which means adding an attribute whose name is xx. Must be 1-50 characters, including the numbers 0-9, the letters a-z and A-Z, the characters "-", ".", "_", "@", "$" and blank space.

# View Device Data


On the device list, when user clicks to select a single device, device telemetry data is displayed at the bottom of the page.The status tab displays the latest reported data from device. User can also view the alarms and events for each device.

Administrators can customize device labels or parameters and set them as headers.

In terms of the privilege of data view, it can be setup inside the configuration of a group. The administrator can choose to share the data with certain users. Once it is configured, the user who has the permission can access the telemetry data via GUI or API.

# Data Management Service

# Function Description


ThingsMatrix Service Platform has the capability of analyzing some telemetry data and presenting some helpful information to user. Once the customer enables data storage, the historical data and statistics data are available to view.

Meantime, the platform provides Policy and Channel functionality for further data monitoring and data safety purposes;it also provides Dashboard and Transformer for custom data visualization and custom data configuration.

# History and Statistics Data


On the data page of each device or sensor, there is a history tab to view historical data and statistics data.

# Data Dashboard


TMX platform provides data visualization and autonomous configuration of visual data through the dashboard.To help users monitor and analyze data information. In the Dashboard panel, users can configure charts based on actual needs to monitor real-time data or historical data change tracks for individual devices. Users can also configure statistical charts to count the total number of devices in the company and their status distribution. When the user configures the chart, you can configure the time period for the chart display or select Auto Refresh to define the data content of the chart.

Dashboard currently offers configurable chart types including line charts, histograms, pie charts, dashboards, etc., Users can choose to display data according to their needs.

# Data Transformer


TMX Platform provides a browser-based editor that makes it easy to create computational flows from the Transformer panel to get the data you want.

The user adds a Transformer node in the Transformer panel, and fills in and edits the JavaScript function inside the Transformer. Flows can be then deployed to the runtime in the JavaScript function if it is created correctly.

# Coding Reference

Transformer code is using Javascript. You can retrieve input from device static configuration, device attribute metadata, and dynamic data.

For example:

device.sn, device.group

device.attributes.zipcode

payload.distance , payload.temperature

You don't need write a return statement. All output parameters are defined as global variables and need match output list definition. Any miscalculation or exception may cause empty output.

Code Example, the output is temperature_f:

var temperature_f = payload.temperature

if (device.attributes.country === 'US') {

  temperature_f = payload.temperature * 9 / 5 + 32;

}

# Output

Output data is new data generated by the Transformer flow.The newly generated output data can be seen in the ExtraData panel in the DeviceList page.

# Original field

The default data when the device is shipped from the factory.

# Output field

Output data is new data generated by the Transformer flow.

# Data Policy


In its current release, the Platform supports two types of policies, Device Policy and Platform Policy. Device policy is part of Device configuration. Please note that not every device supports device policy. If a policy is violated, the device will generate device alarms via communication protocol. On the other hand, the platform policy is implemented on the Data Engine of the platform. When device data violates platform policy configuration, alarm is triggered on platform side directly. These two types of policies have different configuration and work independently.

In the Device Group configuration, the operator can select Policies from the available lists, and activate them. Within one device group, multiple policies can be enabled at the same time. They work independently.

In current release, the policy performs data validation on the platform side. The platform supports two types of policy. One is called Basic Type in order to monitor the data threshold values, and the other is called Geofencing which is to monitor geolocation of a device. Geofencing policy supports a circle fence which is defined by a center point and radius. An alarm will be triggered when the device is crossing the border of the fence. It is recommended to be used only when many devices are very close within the same location. Basic type policy is used to monitor high and low thresholds of a data value.

# Data Channel


In the current release, data Channel is a logic component which controls the data sharing. An administrator can define a whitelist and blacklist of data fields based on the device model. Data channel is configured within the device group. Each device group can have multiple data channels to serve different purposes and filter different data fields. Through data channel, a user can query data from the device group with proper data fields. If the user wants to access the raw data, it can be achieved via device or group level.

# Connectivity Management Service

# Function Description


Connectivity Management Service is used to manage SIM cards distributed from mobile network operators. The platform supports two types of SIM card. One is the SIM card supplied by customer. The other could be SIM cards purchased via ThingsMatrix.

For SIM cards supplied by customer, SIM Management Service is responsible for SIM inventory management. For SIM cards supplied by ThingsMatrix, the service platform is integrated with the MNO's service API in order to retrieve SIM information and real time session status. Based on the MNO's SIM Usage report, SIM Management Service is capable of providing a summary SIM usage report on the Company main dashboard. Note: In the current release, ThingsMatrix is only supporting AT&T SIM types.

# Common Operations


Import SIM

In order to import a SIM card onto the platform, the Administrator needs to collect the SIM's ICCID and IMSI.

# Settings

# Function Description


User can select the appropriate language, time zone, data statistics unit, and map display type in the settings. You can also return to the initial state by clicking the Restore Default button. Administrators can preset a common company settings template for use across the company.

# API Services

Management Center provides north bound API service to external users and systems. For detailed technical information, please refer to the ThingsMatrix Service Platform API Document.

Last updated: 4/30/2021, 9:52:12 AM