ThingsMatrix Service Platform 2.3 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)

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 main page displays features and the device detail 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 permitted can access data via the GUI or API. A company administrator automatically has the access to all data.

Clicking the All Users bar, it enters the window 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 edit 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 then 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 a 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 + New button, an Add User window will pop up, and the user administrator can then add any user level accounts into the User list.

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 edit 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 edit the user information.

  • 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, a Reset Password warning will pop up. After clicking the OK 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

    If the user administrator wants to delete a user, he needs to disable that selected user first using instructions provided previously. After the user has been disabled, then click the Delete button, and a Delete User warning will pop up. After clicking the OK button, the selected user account will be deleted from the Platform.

7.2.3 Inviting new users

By clicking the + Invite button, 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 add new users, as well as 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 departmental architecture, click the Department bar. The user administrator can create a separate department if the data has different authentication for each team. Once the first level sub-department is created, the user administrator can rename or delete the sub-department if needed. He can also create more sub-departments if desired.

7.3.1 Adding new sub-departments

The user administrator can create a sub-department by clicking the Add Sub-department button. An Add Sub-department window will pop up, and then the user administrator can enter a name for it to create a new one.

7.3.2 Renaming sub-departments

If the user administrator want to rename a sub-department, he can click the Rename button. A Rename window will pop up for the user administrator to enter a new name for the sub-department.

7.3.3 Deleting sub-departments

The user administrator can delete sub-departments. To do that, simply click the Delete Department button, and a Delete Confirmation window will pop up. Click the Delete button to delete a sub-department. The department will be deleted and the department information of the account will also be removed. Please note that 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.

7.4.1 Adding new teams

Click the + New button, the user administrator can add a new team by entering a team name and define a user list.

7.4.2 Modifying teams

If the user administrator wants to modify the team, he can click the Modify button to edit the team's name and rearrange the team members.

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:

  • Company Admin
  • Normal User

Company Admin has the privilege to manage all objects and configuration within his own company, such as add or delete devices. Normal user is allowed to view devices and sensors list. By default, normal user can only view device lists, but is not allowed to view device data. The privilege of viewing device telemetry data is controlled within each device group. Only a permitted 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 form will pop up, and the user administrator can rename the role and edit owned permissions of it.

  • Deleting roles

    Select a user role first, and then click the Delete button to delete a user role. Please note that 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 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 Viewing SIM card usage summary

Please refer to 8.2.1 View SIM card usage summary section above.

8.3.2 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.3 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.4 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 two parts:

  • Device Management
  • Device List

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.

  • 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, a manual reset of devices or sensors would need to be performed. The change would be applied to all devices or sensors in this group. For parameter configuration, please refer to the Parameter Table section in the corresponding device's Product User Manual for further information.

  • 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.

9.2.1 Adding new groups

Select a device model, and click the + New Group 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, the user administrator can assign a specific configuration for the new group. Please refer to Parameter Table section in the corresponding device's Product User Manual for further information.
  • For Policy, the user administrator can set a device Policy in order to activate special functions which would bring added value to the user. This is an optimal field. The Policy settings can be done in Data Management Service - Policy section.
  • For Channel, the user administrator can put any data that he wants to see in the white list, and put any data that he does not care to see in the black list in order to control data consumption. This is also an optional field. Please note that the channel settings can be done in Data Management Service - Channel section.
  • For Share Data, you can select specific users to share data. They will have access to view all data in this group. User administrators and users who already have all privileges will automatically have access to view all data.

9.2.2 Editing groups

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

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

9.2.3 Deleting groups

Click the Delete button, a Delete Group Warning will pop up. Then click the OK button to delete the group. Please note: you need to empty the group first before you can delete a device group.

9.2.4 Adding new Templates

Select a device model, and click the + New 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 Product User Manual for further information.

Let's take device model TMY07 as an example. Its configuration consists of the following categories: "refresh_timer", "work_settings", "firmware", "net_settings" and "device_area". 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.

9.2.5 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 a group, the latest configuration will not take effect until the devices in the group connect to the Platform next time.

9.2.6 Copying templates

By clicking the Save As... 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 edit the settings during creation to make some changes on the new configuration.

9.2.7 Deleting templates

Click the Delete button and a Delete Template Warning will pop up.

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

9.2.8 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, then click the + button on the right.

A New Device window will pop up, fill in the form, and click the Submit button to add a new device.

Click the group and you can see the newly added 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. Click the Refresh button or refresh the page to read the device's latest status. The device has been added successfully as shown below:

9.2.9 Managing devices

Select the device(s), by clicking the Actions button, the authorized users can modify, enable/disable, restart, reset and delete them. For more information, please refer to 9.3.4 Managing devices 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 information:

  • Serial number : Each device will have one unique Serial Number for identification purposes.

  • Model: Device model name.

  • Group: Group 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:

  • First icon looks like a battery, which represents the battery status of the device.

  • Second icon looks like a plug, which means the battery is currently being charged - if the device supports a rechargeable battery.

  • 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.

  • Fourth icon looks like a warning. If the warning icon is on, the device is sending alarms to the Platform.

  • SIM ICCID: It shows the SIM card ICCID information inside the device.

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.1 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 Assets - 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" and "Sensor Serial Number" fields, 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 or the sensor after the information is initially populated. You can also add tags and 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 Product User 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 template will ask to be downloaded.

After downloading the 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/Sensor.
    • 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, please add it to the system first.
    • Model: Model of the device.
  • The remaining fields are optional:

    • SimICCID: Must be 20 digits.
    • SensorSN: Sensor Serial Number. Must be 8-16 bit characters, including digits 0-9 and 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: The number of characters must be no more than 200.
    • 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 ",".
    • 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 Group Model Description Sim ICCID SensorSN Tags Attribute.Address
    861901268000009 TMX07_GM TMX07 60s 89860437111890028017 661808008000092 San Antonio, Atlanta 9442 North Capital of Texas Hwy
    801046031116490 tmx08_1123 TMX08 70s 89860782111730537722 661808008000093 San Antonio, Atlanta 9445 North Capital of Texas Hwy
    801046031094416 tmx08_1125 TMX08 50s 89011703278173974331 661808008000094 San Antonio, Atlanta 9442 North Capital of Texas Hwy

Click the Browser button to select the file. Then click the Import button to upload the file and import the devices.

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 Managing devices

Choose one of the devices and click the Actions button, it will show the list of different actions the user administrator can do. However, if an action item is in gray color, it is not supported by the device model.

Below are the following actions that can be performed:

  • The Modify button can be used to edit device information.
  • 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 device remotely.
  • The Reset button can help the authorized users reset devices.
  • The Delete button can be used to remove devices from the device list.

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

  • Modifying devices

    Click the Modify button, an Edit Device window will pop up as below, and the user administrator can do basic device information editing. Once the edits are complete, then click the Submit button to apply those changes.

  • Disabling devices

    Click the Disable button, and then click the OK button. The selected device will be disabled, for example as below:

  • Enabling devices

    Click the Enable button, and then click the OK button. The selected device will be enabled, for example as below:

  • Restarting devices

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

  • Resetting devices

    Devices can be reset by the user administrator. Please click the Reset button and then click the OK button.

  • Deleting devices

    Please note: You need to disable the device before you can delete it. Click the Delete button, then click the OK button to remove a device from the list.

9.3.5 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
  • Path
  • Event
  • Alarm
  1. Information A device's description, SIM card ICCID, sensor Serial Number, tags and attributes are shown to all users.

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

  3. Statistics Authorized users can get detailed data statistics by configured time range, data variable and granularity.

  4. Path Authorized users can find the device route records.

  5. Event Authorized users can find the device behavior records.

  6. Alarm Authorized users can find all the device alarm records.

9.3.6 Customizing device list columns

Select a specific device and then click the Edit Column button - 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.

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.5 Viewing device details for further information. In the current release, the Platform provides Dashboard and Transformer features for customized data visualization and configuration. It also provides Policy and Channel features 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. Click the + button on the top right.

10.2.2 Editing dashboards

Click the Down button on the right side of the dashboard name, then click the Edit button.

The user administrator can edit the dashboard name, theme, time period of chart display, and refresh interval. For example:

  • name: Demo
  • theme: Theme 1
  • time period: 2019-08-17 16:31:47 - 2019-11-15 16:31:47
  • refresh interval: 30min (refresh the chart every 30 minutes, 0s for no refresh)

Then click the Down button and click the Save button to apply the configuration.

10.2.3 Inserting new charts

When editing 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 a line chart is created.

10.2.4 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 and refresh interval, do boundary settings and select a data source. 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.5 Viewing charts

Click the Down button and then 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.6 Deleting charts

When editing the dashboard, click the Close button and the chart is deleted.

10.2.7 Viewing dashboards

Let's create more charts following the instructions in 10.2.3 Inserting new Charts section above. After saving all the charts, they will be displayed on the dashboard. All the charts and diagrams can be resized and their locations can be rearranged based on requirements.

10.2.8 Copying dashboards

Click the Down button and then click the Copy button, a new copy of the original dashboard is be created.

Click the new dashboard so that you can view or edit the dashboard.

10.2.9 Deleting dashboards

Click the Down button and then click the Delete button, a Delete Dashboard warning will pop up. Click the OK button to delete the dashboard.

10.3 Transformer

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

10.3.1 Adding new transformers

First, you need to select a specific device model for which you want to create a transformer. Let's take device model TMX08 as an example.

Right click the Begin button, which stands for a transformer start node, click the New Transformer button.

A New Transformer window will pop up for authorized users to enter a name for the transformer and do some coding tasks. There are instructions on the right side to help users write the code. Please note that you do not need to write a return statement. The programming language is JavaScript inside the coding section.

After the coding is finished, click the Submit button to add the transformer.

Output fields are created by users, and users can customize output field names. And output data is generated by the Transformer flow. The newly generated output data can be seen in the ExtraData section of the device's information. Please refer to 9.3.5 Viewing device details to get more information.

Right click the transformer node which has just been created, then click the Output button, an Output Editor window will pop up.

Click the + New button to create a new output field.

You can define more than one output in the transformer. Fill in the form to define all of the output, then click the Submit button to save the changes. Flows can be then deployed to the runtime in the JavaScript function if it is created correctly.

You can add a few more new transformers if desired. Different flows can be created based on your requirements.

10.3.2 Modifying transformers

Right click the transformer node that you want to edit, then click the Coding button, and an Edit Transformer window will pop up. You can rename the transformer or edit the codes. Then click the Submit button to apply the changes.

In addition, right click the transformer node that you want to edit, then click the Output button, and an Output Editor window will pop up. You can then edit the output. Click the Submit button to apply the changes.

10.3.3 Deleting transformers

Right click the transformer node that you want to delete, then click the Delete button, and a Delete Transformer Confirmation window will pop up.

Click the Delete button to delete the selected transformer.

10.4 Policy

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

  • Device Policy
  • Platform Policy

10.4.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 Assets - 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.4.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 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.4.3 Create a basic type Platform Policy

  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 Policy section.

  6. Go back to the Assets - Device Management section, and select one of the existing group (or create a new group). Click the Edit button and a Modify Group window will pop up. Authorized users can find the Policy-Optional item by scrolling down. Then they can select the newly created Policy and click the Save button to make the Policy take effect.

10.4.4 Create a geo fencing Platform Policy

  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 Policy section.

  6. Go back to the Assets - Device Management section, and select one of the existing groups (or create a new group). Click the Edit button and a Modify Group window will pop up. Authorized users can find the Policy-Optional item by scrolling down. Then they can select the newly created Policy and click the Save button to make the Policy take effect.

10.5 Channel

In the current release, Channel is a logic component which controls data sharing. The user administrator can define a white list and black list of data fields based on the device model. Channel is configured within the device group. Each device group can have multiple data Channels to serve various purposes and filter different data fields. Through data Channel, authorized users can query data from the device group with proper data fields. If the users want to access the raw data, it can be achieved via the device or group level.

10.5.1 Create a Channel

  1. Click the + New button and a Create New Channel window will pop up. The authorized users then can select the device model, and click the Next button.

  2. Enter the name of the Channel and click the Next button.

  3. Move the data fields to the proper list based on the requirements. Whitelist data can be accessed via APIs. Blacklist data will be blocked, as users cannot access that specified data via APIs.

    Please note that it does not mean that the Platform will not show the Blacklist data. The Channel is just used to block Blacklist data when relevant APIs are called to query it.

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

  5. A new Channel has been created. Users can see it in the Channel section.

  6. Go back to Assets - Device Management section, and select one of the existing groups (or create a new group). Click the Edit button and a Modify Group window will pop up. Authorized users can find the Channel-Optional item by scrolling down. Then they can select the newly created Channel and click the Save button to make the Channel take effect.

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 return to the initial state by clicking the Restore default button. 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

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