ThingsMatrix Service Platform 2.4 User Guide

1 Preface

This guide is primarily intended to give the user administrator a comprehensive understanding of the ThingsMatrix Service Platform. The Platform represents the ThingsMatrix Service Platform.

2 Overview

The Platform enables IoT solutions with its modular approach in design and deployment. The Platform consists of four main components: IoT Gateway (IOTGW), Device Management Platform (DMP), Connectivity Management Platform (CMP) and Control Management Center (CMC). Each component can also be deployed independently based on the service requirements.

IOTGW handles device communication and interprets protocol and data.

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

CMP integrates with mobile operator networks and provides overall SIM management features such as SIM status management, session management and usage reporting.

CMC is a core component which provides user management and centralized control features via a web UI interface. It also provides API services which contain all necessary business logic.

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

  • Organization Management Service
  • Connectivity Management Service
  • Asset Management Service
  • Data Management Service
  • API Services

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)
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)
TMY10 Tracker (2G, Cat-M, NB)
TMX09-M Tracker (Cat-M, NB)

5 Get Started

Every new user who wants to utilize the Platform, needs to provide 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 in the Platform. Meanwhile, an email with the login URL, username and password will be sent to the email address of the main contact person. The user then can log in to the Platform with the given information.

6 Sign In

Click the login URL to go to the login portal, then enter username and password.

Once the user has logged in successfully, the Home page displays features in the navigation bar and the device location map as shown below:

7 Organization Management Service

7.1 Feature Description

The Platform provides an Organization Management feature for each company separately, which allows a user 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 for all static configuration and applies user access control in order to share device telemetry data for each individual.

The Organization Management service consists of four parts:

  • All Users
  • Department
  • Team
  • Role management

7.2 All Users

For user management, user access control is applied. By default, a normal user can only view the Device List, but is not allowed to view device data. The privilege of viewing device telemetry data is controlled within each device group. Only the user who has been authorized can access data via the GUI or API. A company administrator automatically has the access to all data.

By clicking the All Users tab, the User List and Pending User List are shown as below. If can’t access to the All Users part, please make sure the organization management service is purchased and valid for the user administrator account. In the section of User List, the user administrator has the privilege to add and delete users, as well as view and modify the information of all level of user roles. In the Pending User List section, the user administrator can invite new users, view the user information of those who are applying for access to the Platform, and perform operations on them.

The Platform provides three methods to add a user:

  1. The user administrator can enter all user information and add the user directly. Temporary password is shared via email. Please refer to 7.2.1 Adding new users section below.
  2. The user administrator can invite the user via an email address, and the user can then accept the invitation and complete the registration with an invitation code. Please refer to 7.2.3 Inviting new users section below.
  3. The user can enter a valid email address to complete the sign up process via a web page. The process will generate an invitation code and send it to the user's email address. Please refer to 7.2.5 New user registration section below.

After a user completes the registration process, the user can log into the Platform with his username and password. The user administrator can change the user role later. Every user can modify the password via account center and the user administrator can reset a user's password from the User List. A user can also generate an API token in account center if he needs to get access to the API of the Platform.

7.2.1 Adding new users

By clicking the + button in the User List section, an Add User window will pop up, and the user administrator can then add a new user account.

To assign specific device group access to the new user, select the device groups in the "Device group permissions (Own)" field. It means that the new user can view all device data of the selected device groups: "tmy01_90m" and "tmy02_30m", for example as below. After filling in the form, click the Submit button to add a new user.

7.2.2 Managing users

By choosing one of the users and clicking the Actions button, a list of available actions will be displayed. The user administrator can then click the Modify button to modify the information of an added user. The Enable/Disable button can help the user administrator manage the user accounts by activating or deactivating them. By clicking the Reset Password button, the user administrator can reset the password of users. The Delete button can help the user administrator delete users.

  • Modifying users

    Click the Modify button, an Edit User window will pop up as below, and the user administrator can modify the user information.

    If the "Device group permissions (Inherited)" field is not empty, it means that the user is permitted by his own department to access the device data of the specific device groups: "tmx03_10m" and "tmx09_2h", for example as below. To modify this field, please refer to 7.3.1 Adding new sub-departments and 7.3.2 Modifying sub-departments sections. After the modification of the user, click the Submit button to apply the changes.

  • Disabling users

    Disabled users cannot log into the Platform or use API services. By selecting a user and clicking the Disable button, the user account will be disabled. An example is outlined below:

  • Enabling users

    Enabled users can log into the Platform and have access to API services. By selecting the user and clicking the Enable button, the user account will be enabled as outlined below:

  • Reset Password

    By clicking the Reset Password button, the password of the selected user will be reset. An email will be sent to the selected user's email address, together with the new password for him to use during login.

  • Deleting users

    Please note: The user needs to be removed from his own department if he has before he can be deleted. Also, the user needs to be disabled using instructions provided previously. After the user has been disabled, please click the Delete button, and the selected user account will be deleted from the Platform.

7.2.3 Inviting new users

By clicking the + button in the Pending User List, an Invite User window will pop up. The user administrator can enter the email address of the user that he wants to invite. After clicking the Invite button, a verification email will be sent to the email address. The user can then register on the Platform following instructions found within the verification email.

7.2.4 Pending user operations

The user administrator can view invited users' registration status, reinvite and delete pending users.

7.2.5 New user registration

The user can enter a valid email address to complete the sign up process via the portal registration page. The valid email address should match one of the names in the company email domain list. Click the Sign Up > button to go to the registration page.

Enter the user‘s valid email address, and then click the Sign Up button.

Fill in the registration form, and click the Sign Up button.

The user has registered successfully on the Platform. Enter username and password, and click the Login button to log in.

7.3 Department Organization

To organize department structure, click the Department tab. The user administrator can create separate sub-departments to assign different data access to users. Once the first level sub-department is created, the user administrator can add, modify and delete sub-departments if needed.

7.3.1 Adding new sub-departments

To create a sub-department, the user administrator needs to select the parent department, then click the Action button, and click the Add Sub-department button.

An Add Sub-department window will pop up, please enter a name for the department. To assign specific device group access to the new department, select the device groups in the "Device group permissions (Own)" field. It means that all the users of this department can view all device data of the selected device groups: "tmx08_30m" and "tmy01_12h", for example as below. After filling in the form, click the Submit button to add a new sub-department.

7.3.2 Modifying sub-departments

By selecting one of the departments and clicking the Action button and the Modify button, a Modify Sub-department window will pop up for the user administrator to modify the sub-department.

If the "Device group permissions (Inherited)" field is not empty, it means that all of the users who belong to this department are permitted to access the device data of the specific device group: "tmy01_12h", for example as below. Please note: The device group permissions are inherited from its sub-departments. To modify this field, you need to modify the sub-departments of this department. After the modification, click the Submit button to apply the changes.

7.3.3 Deleting sub-departments

The user administrator can simply select one of the departments and then click the Delete button to delete it. The sub-department will be deleted and the department information of the account will also be removed. Please note: If you do so, it will also delete all the sub-departments below it. However, it will not remove the members' accounts linked to it.

7.4 Team Definition

For flexibility, the user administrator can define teams for users from different departments and assign different data access to them.

7.4.1 Adding new teams

Click the + button, an Add Team window will pop up for the user administrator to add a new team by entering a team name and define a team member list.

To assign specific device group access to the new team, select the device groups in the "Device group permissions (Own)" field. It means that all the members of this team can view all device data of the selected device groups: "tmx02_15m", "tmx04_periodic" and "tmx04_storage", for example as below. After finishing the form, click the Save button to create a new team.

7.4.2 Modifying teams

If the user administrator wants to modify the team, he can select the team and then click the Modify button to edit the team's name, assign different device group permissions and rearrange the team members.

After the modification, Click the Save button to save the changes.

7.4.3 Deleting teams

The user administrator can delete a team as well as remove the members from the team by clicking the Delete button. Please note: This operation will not remove the members' accounts within the team from the company.

7.5 Role Management

The Platform applies role-based access control to manage user roles. There are two default user roles setup internally, which cannot be modified or deleted:

  • Company Admin
  • Normal User

By default, Company Admin has the privilege to manage all objects and configuration within his own company, such as add or delete devices. Normal user can only view the Device List, but is not allowed to view device data. The privilege of viewing device telemetry data is controlled within each device group. Only an authorized user can access that data via the GUI or API. Company Admin automatically has the access to all data.

The user administrator can authorize different roles for different levels of access.

7.5.1 Adding new roles

Click the + New button, the user administrator can create a new role by filling in the Add Role form.

7.5.2 Managing roles

Select one of the user roles and click the Actions button, it will show the list of different actions the user administrator can do.

  • Modifying roles

    The user administrator can modify roles by clicking the Modify button. A Modify Role window will pop up, and the user administrator can rename the role and modify owned permissions of it.

    After the modification, Click the Submit button to save the changes.

  • Deleting roles

    Select a user role first, and then click the Delete button to delete a user role. Please note: The user administrator needs to make sure that there is no associated user of the role, or he will not be able to delete it.

8 Connectivity Management Service

8.1 Feature Description

Connectivity Management Service is used to manage SIM cards distributed from mobile network operators. The Platform supports two types of SIM cards:

  1. User-supplied SIM cards
  2. ThingsMatrix-supplied SIM cards

For user-supplied SIM cards, Connectivity Management Service is responsible for SIM card inventory management. For ThingsMatrix-supplied SIM cards, the Platform is integrated with the MNO's service API in order to retrieve SIM card information and real time session status. Based on the MNO's SIM usage report, Connectivity Management Service is capable of providing a summary report on SIM card usage in the View of SIM card data. Please note: In the current release, ThingsMatrix only supports AT&T and ARM SIM card types.

8.2 ThingsMatrix-supplied SIM cards

The user administrator can view SIM card historical and statistics data as well as export the SIM card list in Excel and CSV formats.

8.2.1 Viewing SIM card usage summary

By clicking the View button in the Data column, the corresponding SIM card usage data will be displayed. You can check historical data and statistics data by selecting the start date and end date.

8.2.2 Exporting SIM card list

By clicking the Export button, an Export window will pop up. Choose a format and click the Export button to export SIM card list.

8.3 User-supplied SIM cards

The user administrator can view SIM card historical and statistics data, as well as import new SIM cards and export the SIM card list in Excel and CSV formats.

8.3.1 Adding new SIM cards

Click the + New button and a New SIM Connectivity window will pop up.

Fill in the form and click the Submit button to add a new SIM card.

8.3.2 Importing new SIM cards

By clicking the Import button, an Import window will pop up. By choosing CSV or Excel format, a corresponding template will ask to be downloaded.

After downloading the template, the user administrator can then fill in the form. Click the Browser button to select the file.

Click the Import button to upload the file and import the SIM cards into SIM card list.

8.3.3 Exporting SIM card list

By clicking the Export button, an Export window will pop up. The user administrator can then can choose to get the SIM card list exported in Excel or CSV format.

9 Asset Management Service

9.1 Feature Description

This service is responsible for the overall management of devices and sensors. A device is a piece of equipment which has an MCU, Network Module, GPS and built-in sensors. A sensor hub is a standalone piece of equipment which connects to multiple sensors. It can be attached to a device, but it cannot communicate to the Platform independently. A sensor hub has its own serial number. Asset Management Tab provides a list of features for the authorized users to manage all devices and corresponding configurations. The Asset management service has five parts:

  • Device Management
  • Device List
  • Report
  • Event
  • Alarm

9.2 Device Management

In the Device Management section, the device models are pre-configured by ThingsMatrix, thus users can not add or delete the device models here. User administrator can purchase more desired device models from ThingsMatrix official website or by contacting ThingsMatrix.

Let's take device model TMX08 as an example. Select model TMX08.

  • Data Schema

Each model has its own data schemas. Initially it only contains default schemas. Default schemas cannot be deleted. User administrator can add customized schemas if desired. Please note: The data of customized fields will be generated only if they have been configured and calculated in Flow feature. For more information, please refer to 10.3.3 Configuring flow components section.

  • Group

Device Group is a logical component which includes a group of devices of the same model. Authorized users can manage some common properties of devices. It contains following tabs as shown below:

  1. Basic Info

    It shows the basic information of the selected device group.

  2. Device

    It shows all the devices which belong to the selected device group.

  3. Dashboard

    It shows all the charts configured in Dashboard feature and set to be enabled in Settings for the selected device group. For more information, please refer to 10.2 Dashboard section and 12 Settings section. If dashboard display is enabled, you can view device group data.

  • Configuration Template

Each device model has its unique configuration file, which is used to define the basic settings, firmware version, and ruleset of the device. During device registration and authentication, the device configuration file will be passed to the IoT Gateway and downloaded onto the devices. By default, a device group could have an empty configuration template. It means the device will use its default configuration settings. After applying a configuration template, the device will use the new configuration settings. If the template is changed, the new configuration is proactively issued to the online devices and applied. For offline devices, the new configuration will be issued and applied the next time the offline devices are connected to the Platform. The change would be applied to all devices in this group. For parameter configuration, please refer to the Parameter Table section in the corresponding device's ThingsMatrix Device Manual for further information.

9.2.1 Adding new schemas

Click the Add button on the right side, a new empty schema row will be displayed in the form below.

Fill in the row and click the OK button to create a new schema.

Please note: The data of customized fields will be generated only if they have been configured and calculated in Flow feature. After saving the schema, it will be displayed in the Extra Data section of the Status tab in the Device List for device model TMX08 as shown below:

If more than a device schema is desired, follow the instructions above to add more device schemas.

9.2.2 Viewing Schemas

There are some operations to help users view device schemas.

  • Search

    You can enter field name, title, or description to search for a specific device schema.

  • Filter

    You can specify the type to filter device schemas.

    You can also specify the category to filter device schemas.

  • Refresh

    Click the Refresh button to refresh the device schema list.

  • View Disabled Schema

    Click the Show Optional button to view device disabled schemas. Disabled schemas will not be displayed in any other sections on the Platform side and cannot be accessed via APIs.

9.2.3 Modifying Schemas

Click the Modify button, it will enter the modification state. Please note: "Field Name" and "Type" fields cannot be modified. After the modification, click the OK button to save the changes.

9.2.4 Enabling Schemas

Enabled schemas will be displayed on the Platform side and can be accessed via APIs. By clicking the Enable button, the schema will be enabled.

9.2.5 Disabling Schemas

Disabled schemas will not be displayed on the Platform side and cannot be accessed via APIs. By clicking the Disable button, the schema will be disabled.

9.2.6 Deleting Schemas

Click the Delete button to delete the schema. Please Note: Default fields cannot be modified or removed. For customized fields, they can't be deleted if they are in use, such as being configured in one of the flows.

9.2.7 Adding new groups

Select device model TMX08, enter Group tab, and click the + button, a New Group window will pop up.

Fill in the form and click the Save button to create a new group.

  • For "Config Template" field, the user administrator can assign a specific configuration for the new group. Please refer to Parameter Table section in the corresponding device's ThingsMatrix Device Manual for further information.
  • For "Policy" field, the user administrator can set a Platform Policy for a device in order to activate special functions which would bring added value to the user. This is an optional field. For Platform Policy, please refer to 10.6.2 Platform Policy section to get more information.
  • For "Push Notification" field, the user administrator can specify the URL to push notifications.
  • For "Notification" field, the user administrator can select desired category of reported data to push to the URL configured above.

9.2.8 Modifying groups

Click the Modify button, a Modify Group window will pop up.

After modifying the group, click the Save button to save all the changes to the group.

9.2.9 Deleting groups

Click the Delete button to delete the group. Please note: you need to empty the group first before you can delete it, that is, remove all the devices within the group.

9.2.10 Adding new Templates

Select a device model, and click the + button in the Configuration Template list. A New Configuration window will pop up.

Each device model has its own configuration parameter settings. Please refer to the Parameter Table section in the corresponding device's ThingsMatrix Device Manual for further information.

Let's take device model TMY07 as an example. Its own configuration consists of the following categories: "Working Mode Option", "Generic Settings", "Periodic Mode Settings", "Flight Mode Settings", "Always Mode Settings", "Motion Mode Settings", "Threshold Settings", "Firmware", "Device Area" and "Net Settings". Within each parameter category, hovering your mouse over one of the parameters, an explanation will be displayed. Each parameter has a default value, users can modify the value based on requirements. A description can also be added if needed. After the configuration, click the Save button to create a new configuration template.

9.2.11 Modifying templates

Click the Modify button, a Modify Configuration window will pop up.

After changing the parameter values, click the Save button to apply the new changes. If the template has already been applied to some groups, once the template is changed, the new configuration is proactively issued to the online devices in those groups and applied. For the offline devices within those groups, the new configuration will be issued and applied the next time the offline devices are connected to the Platform. The changes would be applied to all devices in those groups.

9.2.12 Copying templates

By clicking the Copy button, a New Configuration window will pop up. The configuration template is exactly the same as the one the user chose. Enter a new name and description for the new configuration, then click the Save button to create a template. You can also modify the settings during creation to make some changes on the new configuration.

9.2.13 Deleting templates

Click the Delete button to delete the template. Please note: A template can only be deleted when it isn’t applied by any groups.

9.2.14 Adding new devices

After a device model group is created and the necessary configuration template is applied, a new device is prepared to be added.

Select a device group, for example "tmx08_demo", enter the Device tab, then click the + button on the right side. If there isn't any device in the group yet, you can also click the add device button in the middle.

A New Device window will pop up. Fill in the form and click the Submit button to add a new device. Please note: The fields with * are required, while the others are optional. For "SIM ICCID" field, users can choose to provide or not provide relevant information because the Platform will automatically collect this information. If the Auto Update checkbox is checked, the Platform is allowed to do additional updates after the information is initially populated, such as replacing the SIM card. If not, the Platform will reject the connection to the device if you replace the SIM card after the information is initially populated. You can also assign a specific alias, add tags and create customized attributes to the device.

You can see the newly added device. The next step is to insert the SIM card into your device if required and turn the power on. Please refer to the Installation Instructions section in the corresponding device's ThingsMatrix Device Manual for further information on physical installation.

The device will then automatically connect to the Platform. Click the Refresh button or refresh the page to read the device's latest status. The device has been added successfully.

To get full details of how to add a ThingsMatrix approved device, please refer to ThingsMatrix Service Platform Quick Start Guide.

9.2.15 Modifying devices

Select a device and then click the Modify button, a Modify Device window will pop up.

After modifying the device, click the Submit button to save all the changes to the device.

9.2.16 Deleting devices

Select a device, then click the Delete button to delete the device. Please note: You need to disable the device before you can delete it.

9.2.17 Actions on devices

Select the device(s), by clicking the Actions button, the authorized users can perform actions on them, such as enabling, disabling, restarting and resetting. Some device models support additional actions such as snapshotting, tracking, etc. However, if an action item is in gray color, the corresponding command is not supported at the moment temporarily. Please note: You can select more than one device and click the Batch Actions button to do similar tasks. For more information, please refer to 9.3.6 Actions on devices section.

9.2.18 Viewing device details

The device details is only available for authorized users. When the authorized users select one of the added devices, the second half of the page will display more details. For more information, please refer to 9.3.7 Viewing device details section.

9.3 Device List

In the Device List section, authorized users can get detailed device information and also the data collected by the device. We have statistics for the data reported to the Platform, so the users can have a better understanding of the data trends.

When a user clicks the Device List, a window with all added device information will show up as below:

From the list, we can find following device basic information:

  • Serial number: Each device will have one unique Serial Number for identification purposes.
  • Model: Device model name.
  • Alias: Device alias.
  • Group: Device group name in which the device belongs.
  • Status: Different working statuses of the device are as follows:
    • When a device has connected to the Platform, it will show as "Online".
    • When a device enters sleep mode, it will show as "Standby".
    • When a device is not working for a period of time (according to the user administrator’s timer settings), it will show as "Offline".
    • When a device is disabled by the users, it will show as "Disabled".
  • State: We have 4 states to indicate the device properties:
    • The first icon looks like a battery. If it is on, it displays the battery status of the device; while if it is off, it means the Platform does not received any battery data.
    • The second icon looks like a plug. If it is on, it means the device is connecting to external power; while if it is off, it means the Platform does not received any data of external power.
    • The third icon looks like a cell tower or a satellite, which represents the positioning features. If the cell tower icon is on, it means the device is sending LBS location data; while if the satellite icon is on, it means the device is sending GPS location data.
    • The fourth icon looks like a warning. If the warning icon is on, the device is sending alarms to the Platform.

9.3.1 Adding new devices

Before you can add a new device, you need to create a group first. Please refer to 9.2.7 Adding new groups section above to get further information. To get full details of how to add a ThingsMatrix approved device, please refer to ThingsMatrix Service Platform Quick Start Guide.

After a group is created, go to Asset - Device List section and click the + button on the top right. A New Device window will pop up.

Fill in the form and click the Submit button to add a new device. Please note: The fields with * are required, while the others are optional. For "SIM ICCID" field, users can choose to provide or not provide relevant information because the Platform will automatically collect this information. If the Auto Update checkbox is checked, the Platform is allowed to do additional updates after the information is initially populated, such as replacing the SIM card. If not, the Platform will reject the connection to the device if you replace the SIM card after the information is initially populated. You can also assign a specific alias, add tags and create customized attributes to the device.

The next step is to insert the SIM card into your device and turn the power on. The device will then automatically connect to the Platform. When the device's status shows as "Online", it means the device successfully connected to the Platform. Please refer to the Installation Instructions section in the corresponding device's ThingsMatrix Device Manual for further information on physical installation.

9.3.2 Importing new devices

The Platform provides device import feature. Click the Import button and an Import window will pop up.

By choosing CSV or Excel format, a corresponding device information import template will ask to be downloaded.

After downloading the device information import template, the user administrator can fill in the form.

These are fields in the template:

  • SerialNumber, Group, Model are required fields:

    • SerialNumber: Unique identifier of the Device.
    • Group: The device group name to which the device belongs. Group must exist in the system first, and has a corresponding relationship with the model. If it is not, please add it to the system first.
    • Model: Model name of the device.
  • The remaining fields are optional:

    • Alias: Must be 1-30 characters, including the numbers 0-9, the letters a-z and A-Z, Chinese characters, the characters "_" and "-".
    • SimICCID: Must be 20 digits.
    • SensorSN: Sensor Serial Number. Must be 8-16 bit characters, including the numbers 0-9 and the letters A-Z.
    • SimAutoUpdate: 0 means non-automatic update, 1 means automatic with new. Default is automatic with new, empty means default.
    • SensorAutoUpdate: 0 means non-automatic update, 1 means automatic with new. Default is automatic with new, empty means default.
    • Description: Must be 1-200 characters.
    • Tags: Must be 1-50 characters, including the numbers 0-9, the letters a-z and A-Z, the characters "-", ".", "_", "@", "$" and blank space. The number of tags for a device does not exceed 20 tags and tags are separated by ",".
    • 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.
  • Example:

    SerialNumber Alias Group Model Description Sim ICCID Tags Attribute.Address
    861901268000009 tmx07_20m TMX07 Device 1 89860437111890028017 San Antonio, Atlanta 9442 North Capital of Texas Hwy
    801046031113285 tmx08_favorite tmx08_2h TMX08 Device 2 89860782111730537722 San Antonio, Atlanta 9445 North Capital of Texas Hwy
    801046031097369 tmx08_1h TMX08 Device 3 89011703278173974331 San Antonio, Atlanta 9442 North Capital of Texas Hwy

Please determine whether to check the checkbox "When the same Serial Number exists, the current content is overwritten" or not first. Then click the Browser button to select the file, and click the Import button to upload the file to import the devices. if some errors occurred during the import, the error details will be displayed in the Import Log section.

9.3.3 Exporting devices

The user administrator can export devices by clicking the Export button on the top right. An Export window will pop up, then the user administrator can choose to get the Device List exported in Excel or CSV format.

9.3.4 Modifying devices

Select a device and then click the Modify button, a Modify Device window will pop up.

After modifying the device, click the Submit button to save all the changes to the device.

9.3.5 Deleting devices

Click the Delete button to delete a device. Please note: You need to disable the device before you can delete it.

9.3.6 Actions on devices

Select the device(s), by clicking the Actions button, the authorized users can perform actions on them, such as enabling, disabling, restarting and resetting. Some device models support additional actions such as snapshotting, tracking, etc. However, if an action item is in gray color, the corresponding command is not supported at the moment temporarily.

Below are the following actions that can be performed:

  • The Enable/Disable button can help the authorized users activate or deactivate devices as needed.
  • The Restart button allows the authorized users to restart the online device remotely.
  • The Reset button can help the authorized users reset devices.
  • The Snapshot button can be used to snapshot a device's location information.
  • The Track Now button allows the authorized users to track devices for a period of time.

Please note: You can select more than one device and click the Batch Actions button to do similar tasks following the instructions below.

  • Disabling devices

    Disabled devices cannot connect to the Platform. Click the Disable button, and the selected device will be disabled, for example as below:

  • Enabling devices

    Only enabled devices can connect to the Platform. Click the Enable button, and the selected device will be enabled, for example as below:

  • Restarting devices

    The user administrator can restart the online devices by clicking the Restart button.

  • Resetting devices

    Devices can be reset by the user administrator. Please click the Reset button to reset the device.

  • Snapshotting devices

    Click the Snapshot button, then click the OK button to snapshot a device. Please note: Snapshotting will not affect any working timers of a device.

  • Tracking devices

    Click the Track Now button and a Tracking Setting window will pop up.

    Fill in the Interval and Expiration fields and then click the OK button to track a device. For example, an authorized user would like to track a device in one hour and require the device to report location information every ten seconds. The configuration is shown as below:

    If the device is still online, the device will turn the status from "Online" into "Tracking". The tracking configuration is displayed when hovering over the clock icon.

    When tracking the device, user can still perform actions shown as below, such as restarting, resetting, snapshotting, stopping tracking, disabling the device:

    Please note: Tracking will not affect any working timers of a device, however, it will make an effect on the device working time, that is, make the device work longer. For example, the device is set to wake up every hour to report data. Let's say it is at 15:00:00 that the device will wake up, and it will turn into sleep state after 30 seconds. An authorized user performs a Track Now action at 15:00:10, setting the interval to be 10 seconds and the expiration to be 150 seconds. Then the Track Now action takes effect and the device will report data every 10 seconds in next 150 seconds. After that, the device will shutdown the Track Now action and remain working for 20 seconds due to its working timer - normally, it is supposed to be online for 30 seconds totally every hour. And the report interval will keep the same as it was before the Track Now action performed.

9.3.7 Viewing device details

The device details is only available for authorized users. When the authorized users select one of the added devices, the second half of the page will display more details:

  • Information
  • Status
  • Statistics
  • Report
  • Path
  • Dashboard
  • Event
  • Alarm
  1. Information A device's alias, description, SIM card ICCID, tags and attributes are shown to all users.

  2. Status Authorized users can view the device's details such as basic information, basic data, network information, extra data and the location in the map.

  3. Statistics Authorized users can view the device's detailed data statistics by configured time range, data variable and granularity.

  4. Report

    Authorized users can view the device's report records.

  5. Path Authorized users can view the device's route records.

  6. Dashboard

    Authorized users can view all the charts configured in Dashboard feature and set to be enabled in Settings for the selected device group. For more information, please refer to 10.2 Dashboard section and 12 Settings section.

    For better convenience, authorized users can select different devices, and the charts will be quickly configured by new devices and updated.

    You can also select a specific field to view the data. In this way, authorized users can perform value comparison of different fields between devices.

  7. Event Authorized users can view the device's event records. By clicking the Chart View button on the right side, the chart view of the device's event records will be displayed.

    The scroll bar on the top can help you specify the time range. Click the Table View button on the right side to go back to the table view.

  8. Alarm Authorized users can view the device's alarm records.

9.3.8 Customizing Device List columns

Click the Modify Column button and a Column Edit window will pop up.

You can select preferred columns to be shown or hidden. Move the fields into Show Column section or Hide Column section by clicking the Left/Right button.

You can also customize the orders of the columns by selecting a column and clicking the Up/Down button.

After you finished the customization, click the Save button to apply.

9.4 Report

In the Report section, authorized users can get detailed report records.

9.4.1 Viewing report records

Let's take device model TMY03 as an example. Select model TMY03.

All the report records of the devices whose model is TMY03 will be displayed. Authorized users can filter the records by specifying device serial number, selecting time range and device group.

9.4.2 Exporting report records

Authorized users can export report records by clicking the Export button on the top right. An Export window will pop up, and you can choose to get the report records exported in Excel or CSV format.

9.5 Event

In the Event section, authorized users can get detailed event records.

9.5.1 Viewing event records

All the event records will be displayed. Authorized users can filter the records by specifying device serial number and event category, and by selecting time range, device model, device group and event codes. By clicking the Chart View button on the right side, the chart view of the event records will be displayed.

The scroll bar on the top can help you specify the time range. Click the Table View button on the right side to go back to the table view.

9.5.2 Exporting event records

Authorized users can export event records by clicking the Export button on the top right. An Export window will pop up, and you can choose to get the event records exported in Excel or CSV format.

9.6 Alarm

In the Alarm section, authorized users can get detailed alarm records.

9.6.1 Viewing alarm records

All the alarm records will be displayed. Authorized users can filter the records by specifying device serial number and alarm category, and by selecting time range, device model, device group, severity, alarm codes, origin and status.

9.6.2 Exporting alarm records

Authorized users can export alarm records by clicking the Export button on the top right. An Export window will pop up, and you can choose to get the alarm records exported in Excel or CSV format.

10 Data Management Service

10.1 Feature Description

The Platform has the capability of analyzing some telemetry data and presenting some helpful information to authorized users. Once the user administrator enables data storage, both the historical data and statistics data are available to view. Please refer to 9.3.7 Viewing device details for further information. In the current release, the Platform provides Dashboard feature for customized data visualization, Flow and Function features for data configuration, Bucket feature for data storage. It also provides Policy feature for further data monitoring and safety purposes.

10.2 Dashboard

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, 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 configuring the charts, users can also configure the time period for the chart display and select refresh interval in order to define its frequency.

10.2.1 Adding new dashboards

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

10.2.2 Viewing dashboards

Simply click the dashboard card or the Detail button to view the dashboard detail.

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

  • Time range

    Select time range of data collection.

  • Refresh interval

    Set chart refresh frequency.

  • Serial Number bar

    Quickly generate charts for a specific serial number. 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. However, the configuration will not be saved.

  • Field 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: Modification of the configuration here will not be saved. It is only for quick chart configuration.

10.2.3 Modifying dashboards

By clicking the Edit button, user administrator can enter the modification state. You can also click the Configuration button in the middle if the dashboard is empty as show below:

The user administrator can modify the dashboard theme, time range of data collection, and refresh interval. For example:

  • Theme: Theme 1
  • Time Range: Recent 1 month
  • Refresh Interval: 30m (refresh the charts every 30 minutes, 0s for no refresh)

Then click the Save button to apply the configuration of the dashboard.

10.2.4 Inserting new charts

During the modification of the dashboard, click the + Insert button, all supported chart and panel types will be displayed, including line chart, line area chart, bar chart, pie chart, circle chart, number panel, map panel, table panel, and gauge panel.

Let's take the line chart as an example. Click the Line Chart button and an empty line chart is created.

10.2.5 Modifying charts

Click the Settings button on the top right of the chart and a Chart Configuration window will pop up.

You can rename the chart, customize the theme, time range of data collection and refresh interval. You can also do boundary settings to show the boundaries in the chart if desired. Please note: All fields with * are required. After the modification, Click the Submit button on the bottom right to apply the configuration.

After saving the configuration, the chart will display data as follows:

10.2.6 Viewing charts

After modification, click the Save button to save the dashboard.

The chart is now successfully displayed on the dashboard.

You can click the Sync Chart Data button on the top right of the chart to refresh the data immediately.

You can also click the Hide Legend button to hide the legend of the chart.

10.2.7 Quickly configuring charts

We provides a quick chart configuration in the dashboard. By entering a specific serial number in the serial number configuration bar and clicking the Magnifier button, the chart will be quickly configured by the new serial number and show the data of the device of the serial number and the same field. Furthermore, if you also enter a specific field in the field configuration bar, the chart will be quickly configured by the new serial number and the new field, thus show the data of the device with the serial number and the new field.

For example, "LineChartDemo" shows the data of the device which is a TMX08 device and with serial number of "801046037957640" and the field of "distance".

  1. If we enter a new serial number in the configuration bar, e.g. "801046037944531" which is another TMX08 device, then click the Magnifier button, the chart will be quickly configured and updated.

  2. If we also enter a new field in the configuration bar, e.g. "battery", then click the Magnifier button, the chart will be quickly configured and updated. Please note: You need to enter the name of the schema field, not the title. For example, please enter "battery" for "Battery."

Please note: The quick chart configuration can also be applied in the Dashboard tab of Asset - Device Management, Asset - Device List and Data - Bucket if enabled via Settings.

10.2.8 Deleting charts

During the modification of the dashboard, click the Close button and the chart is deleted.

10.2.9 Copying dashboards

In the dashboard card page, click the Action button and then click the Copy button, a new copy of the original dashboard will be created.

10.2.10 Deleting dashboards

Click the Action button and then click the Delete button to delete the dashboard. Please note: The dashboard can only be deleted when it is not configured in the Settings section.

10.3 Flow

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.

10.3.1 Adding new flows

Click the + Add button and a New Flow window will pop up. Enter the name of the flow and then click the Submit button to create a new flow.

10.3.2 Renaming flows

By hovering the mouse over the Modify button and clicking the Rename button, you can rename the flow.

10.3.3 Configuring flow components

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

  • Filter: Select input data.

    By clicking the Filter button, an Edit Filter window will pop up.

    To select the data that you desire to make as the input of the flow, simply select the device models and groups. Please note: If none of the models or groups are selected, that is, the filter is empty, all data will be used as the input of the flow. Then click the Submit button to save the filter.

  • Transformer: Configure functions used by the flow.

    By clicking the Transformer button, a Modify Transformer window will pop up.

    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 Submit 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:

  • Bucket Data: Store data into bucket.

    By clicking the Bucket Data button, an Edit Bucket Data window will pop up. Please note: You need to create a bucket before you can configure bucket data here. For more information about Bucket, please refer to 10.5 Bucket section.

    Form details are as follows:

    • Flow Result: The result computed by the flow.
    • Bucket: The corresponding bucket name that you desire to store in.
    • Field Name: The corresponding field name that you desire to bind to.

    Click the Add button and the OK button to add a flow result into the bucket data flow result list. An example of a bucket field of "temp_minus" which has already been added in the bucket is shown as below:

    If there is more than a flow result, follow the instructions above to add more flow results. After you finish adding all the flow results, click the Submit button to save the configuration.

  • Device Schema: Store data into device schema.

    By clicking the Device Schema button, an Edit Device Schema window will pop up. Please note: You don't need to create new device schemas if only default schemas are required. However, you must create a device schema before you can configure a customized device schema here. For more information about Device Schema, please refer to 9.2 Device Management section.

    Form details are as follows:

    • Flow Result: The result computed by the flow.
    • Model: The corresponding device model.
    • Device Schema: The corresponding device schema that you desire to bind to.

    Click the Add button and the OK button to add a flow result into the device schema flow result list. An example of a customized field of "temp_minus" which has already been added in the device schema is shown as below:

    If there is more than a flow result, follow the instructions above to add more flow results. After you finish adding all the flow results, click the Submit button to save the configuration.

10.3.4 Inserting flows

Hover the mouse on the Modify button and click the Insert(Up)/Insert(Down) button, and then you can insert a new flow in the front or at the back. A New Flow window will pop up. After entering the name of the flow and clicking the Submit button, a new flow is inserted.

10.3.5 Opening flows

When a flow is open, it will compute every time when there is input data. To open a flow, simply click the Open button. Please note: An open flow cannot be modified.

You can also perform batch opening for all the flows by clicking the Open All button.

10.3.6 Closing flows

When a flow is closed, it will stop computation. To close an open flow, simply click the Close button. Please note: If you want to modify a flow, you need to close it first.

You can also perform batch closing for all the flows by clicking the Close All button.

10.3.7 Importing flows

Hover the mouse on the Modify button and click the Import(Up)/Import(Down) button, and then you can import new flows in front or at the back. An Import Flow window will pop up.

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

10.3.8 Exporting flows

Hover the mouse on the Modify button and click the Export button, a JSON file with current flow's information will ask for being downloaded.

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.

10.3.9 Replacing all flows

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

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

10.3.10 Deleting flows

Hover the mouse on the Modify button and click the Delete button to delete the flow. Please note: Only closed flows can be deleted.

10.4 Function

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. And the number is displayed on the top right side. For example as below, only "Ultrasonic Temperature Compensator", "GPS shifting" and "temp_minus" these three functions are in use.

10.4.1 Adding new functions

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

Authorized users can enter a title for the function, write a description and perform some coding tasks. There are instructions on the right side to help authorized users write the code. Please note: You do not need to write a return statement. The programming language is JavaScript inside the coding section. Please note: 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 Submit button to create a new function. An example for temperature compensation is shown as below:

10.4.2 Viewing functions

Simply click the function card or the Detail button to view the function detail.

10.4.3 Modifying functions

Click the Action button and then click the Edit button, an Edit Function window will pop up.

After the modification, click the Submit button to save the changes. Please note: Functions in use cannot be modified.

10.4.4 Copying functions

Click the Action button and then click the Copy button, a Copy Function window will pop up. Before clicking the Submit button to copy the function, you can perform modification on it based on requirements.

10.4.5 Deleting functions

Click the Action button and then click the Delete button to delete the function. Please note: Functions in use cannot be deleted.

10.5 Bucket

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.

10.5.1 Adding new buckets

Click the + button and a New Bucket window will pop up.

Fill in the form and then click the Submit button to create 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.
  • For "Share Data" field, you can select specific users to share data. They will have access to view all data in this bucket. User administrators and users who already have all privileges will automatically have access to view all data.

10.5.2 Modifying buckets

Select the bucket you want to modify, click the Action button and then click the Modify button. An Edit Bucket window will pop up.

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

10.5.3 Adding new bucket fields

Select a bucket, then enter the Bucket Field tab. Click the Add button and the OK button to add a new bucket field. You can enter field name, field title, type of field value, unit of field value, max value of field value if required, min value of field value if required and a description of the field. If you want to create more than a field, click the + Add button to add more fields. All the added fields will be listed in the field list below.

10.5.4 Viewing buckets

There are several tabs shown as below:

  • Bucket Field

    It shows bucket data schemas.

  • Dashboard

    It shows all the charts configured in Dashboard feature and set to be enabled in Settings for the selected bucket. For more information, please refer to 10.2 Dashboard section and 12 Settings section.

  • Bucket Data

    It shows all the data configured and stored in the bucket.

10.5.5 Deleting buckets

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

10.6 Policy

In the current release, the Platform supports two types of policies:

  • Device Policy
  • Platform Policy

10.6.1 Device Policy

Device Policy is part of the device configuration. If a Policy is violated, the device will trigger alarms via communication protocol. However, not every device supports device Policy.

In Asset - Device Management, the authorized users can select available device policies from the Configuration Template List, and then activate them. They can also create new device policies if necessary.

Let's take TMX08 as an example. In its configuration template, sensor_policy and device_area belong to device policy. In sensor_policy, there are two types of device alarms: temperature alarm and distance alarm. In device_area, there is a geo fencing alarm. When the device violates the device Policy, the device itself will trigger corresponding alarm(s) to the Platform and notify the authorized users.

10.6.2 Platform Policy

Platform Policy is implemented on the data engine of the Platform. When device data violates Platform Policy configuration, alarms are triggered on the Platform side directly. These two types of policies, device policy and platform policy, have different configurations but work independently.

In the current release, the Policy performs data validation on the Platform side. The Platform supports two types of policies. One is called basic type, which is to monitor the data threshold values. And the other one is called geo fencing, which is to monitor the geographic location of the device. Geo fencing Policy supports a circle fence which is defined by a center point and radius. An alarm will be triggered when the device crosses the border of the fence. It is recommended to be used only when many devices are very close within the same location.

Within one device group, multiple policies can be enabled at the same time but work independently.

10.6.3 Add new basic type platform policies

  1. Click the + New button, and a Create New Policy window will pop up. Select the device model which the user administrator would like to set the Policy to, and then click the Next button.

  2. Enter the Policy's name and select the configuration type, then click the Next button.

  3. Select the Data field you would like to configure, (for example Temperature). Users can configure the temperature range per their requirements. Then click the Next button.

  4. Add any description which helps other users understand, then click the Submit button.

  5. A new Platform Policy has been created. Users can see it in the Data - Policy section.

  6. Go back to the Asset - Device Management section, and select one of the existing group (or create a new group). Click the Modify button and a Modify Group window will pop up. Authorized users can select the newly created policy and click the Save button to make the policy take effect.

10.6.4 Add new geo fencing platform policies

  1. Click the + New button and a Create New Policy window will pop up. Select the device model which the user administrator would like to set the Policy to, then click the Next button.

  2. Enter the Policy's name and select the configuration type, then click the Next button.

  3. Enter latitude, longitude and radius of the geo fencing. The user administrator can operate the map and modify the circle in it to define the location of the geo fencing. The edge of the circle can be dragged to change the size, and the center point can be dragged to move the circle. Then click the Next button.

  4. Add any description which helps other users understand and then click the Submit button.

  5. A new Platform Policy has been created. Users can see it in the Data - Policy section.

  6. Go back to the Asset - Device Management section, and select one of the existing group (or create a new group). Click the Modify button and a Modify Group window will pop up. Authorized users can select the newly created policy and click the Save button to make the policy take effect.

10.6.5 Modifying policies

Select the policy, Click the Actions button and then click the Modify button, an Edit Policy window will pop up.

After the modification, click the Submit button to apply the changes to the policy.

10.6.6 Deleting policies

Select the policy you want to delete, click the Actions button and then click the Delete button to delete the policy. Please note: A policy can only be deleted when it isn’t applied by any groups.

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 Settings

Users can select the appropriate language, time zone, data statistics unit, and map display type via the settings. You can also enable/disable dashboard display in Dashboard settings. You can select specific dashboard to display in Asset - Device List, Asset - Device Management or Data - Bucket section. For example as shown below, we select dashboard of "Demo1" to display in the Dashboard tab of Asset - Device List, dashboard of "Demo2" to display in the Dashboard tab of Asset - Device Management, dashboard of "Demo3" to display in the Dashboard tab of Data - Bucket. Click the Restore default button to return to the initial state. The user administrator can pre-set a common company settings template for other users in the company. If needed, other users can have their own personal general settings.

  • User Administrators
  1. General settings

  1. Company settings

  • Other Users

General settings only

13 Operation Log

User administrator can view log of operations performed by company members. Hover the mouse over the avatar icon on the top right side, Then click the Operation Log button to view the log.

14 Notification Board

The Platform provides Notification Board to display notifications and messages, for example, service upgrade plan. Check the Ring button on top right, you can see there is a number next to it, which shows the number of unread messages. There are three unread messages for example as shown below:

By clicking the Ring button, a Notification Board will pop up. It will display all notifications and messages. Click the Read button to set the notice read. Please note: The notice with a red dot means that it hasn't been read yet, while the notice with a white dot means that it has been read already.

Click the Confirm button to confirm the notice.

Last updated: 3/26/2021, 9:27:55 AM