# TMX Access™ Service Platform 2.6 User Guide

# 1 Preface

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

# 2 Overview

The Platform enables IoT solutions with its modular approach in design and deployment, consisting of these main components: IoT Gateway (IOTGW), Device Management Platform (DMP). 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.

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

  • Certificates
  • Models
  • Devices
  • Commands
  • Reports
  • Events
  • APIs

# 3 Browser Compatibility

# 3.1 Supported Browsers

The Platform currently only supports Chrome and Firefox.

# 4 Supported Devices

# 4.1 Device Models

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

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

# 5 Get Started

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

# 6 Home

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

image-20210325193006215

  • Devices

    It gives a pie chart of status and model distribution of all imported devices.

  • Active Device Trend

    It shows the trend of active devices for last 7/30/90 days.

  • Events

    It counts the number of triggered events (including event codes and alarm codes) for last 30 days.

  • Commands

    It gives a pie chart of status and model distribution of all created commands.

  • Top 10

    It shows the top 10 ranking (positive or reverse) of reported data for a certain period of time (today, yesterday or last 7 days).

  • Reports

    It is a bar chart that displays the quantity of reported data for a certain period of time (today or last 7/30/90 days).

# 7 Certificates

Certificates is used to uniformly manage the TLS certificates required by each network component. The Platform supports certificates in .pem format. You can configure the certificate and the server trust store to establish a secure connection between the devices and the Platform. Please click here to download your server certificate.

image-20210325193051073

# 7.1 Adding new CA certificates

By entering CA Certificates tab and then clicking the + Add Certificate button, an Add CA Certificate window will pop up.

image-20210325193828021

You can view the field description by hovering the mouse over its corresponding Information icon.

image-20210326143545575

  • For "Registration Code" field, you can copy the value to generate verification certificate.

  • For "CA Certificate" field, you can upload a private CA certificate.

  • For "Verification Certificate" field, you can upload a verification certificate created using the private key corresponding to this CA certificate to prove that you own it.

    • Verification certificate supports files in the .pem format only.

    • We will introduce the steps in creating a verification certificate by using OpenSSL as an example:

      1. Generate a key pair of the private key's verification certificate. The command to generate a key pair is as follows:

        openssl genrsa -out verificationCert.key 2048
        
      2. Use the value of "Registration Code" field above to create a Certificate Signing Request (CSR).

        The command to create a CSR is as follows:

         openssl req -new -key verificationCert.key -out verificationCert.csr
        

        Copy the value of "Registration Code" field above and paste it as the value of "Common Name" field below.

        ……
        Common Name (e.g. server FQDN or YOUR name) []: yourRegistrationCode****
        ……
        
      3. Use the CSR signed by the private key of the CA certificate to create a verification certificate.

        The command to generate a verification certificate is as follows:

        openssl x509 -req -in verificationCert.csr -CA yourCA.cer -CAkey yourPrivateKey.key -CAcreateserial -out verificationCert.crt -days 300 -sha512
        

# 7.2 Viewing CA certificates

You can filter the CA certificates by specifying CA certificate name and description, or selecting CA certificate status.

image-20210325193334211

# 7.3 Downloading CA certificates

Select a specific CA certificate and then click the Download button to download the CA certificate.

image-20210325193416737

# 7.4 Deleting CA certificates

Select a specific CA certificate and then click the Delete button to delete the CA certificate. Please note: The CA certificates associated with device certificates cannot be deleted.

image-20210325193442770

# 7.5 Adding new device certificates

By entering Device certificates tab and then clicking the + Add Certificate button, an Add Device Certificate window will pop up.

image-20210325193722727

You can view the field description by hovering the mouse over its corresponding Information icon.

image-20210325194053225

  • For "Device Certificate" field, you can upload a device certificate.
  • For "CA Certificate" field, you can select an existed CA certificate to associate with.

# 7.6 Viewing device certificates

You can filter the device certificates by specifying device certificate name, device certificate serial number, associated CA certificate name and device certificate description, or selecting device certificate status.

image-20210325194209702

# 7.7 Downloading device certificates

Select a specific device certificate and then click the Download button to download the device certificate.

image-20210325194232932

# 7.8 Deleting device certificates

Select a specific device certificate and then click the Delete button to delete the device certificate. Please note: A device certificate can only be deleted when it isn’t applied by any groups or devices.

image-20210325194302021

# 8 Models

Model is a set of device products which possess same features with similar configurations and can execute same commands. After you purchase default model devices, the corresponding default models will be pre-configured by ThingsMatrix in Models. You can purchase more desired default model devices from the Console or by contacting ThingsMatrix Sales Team. Please refer to Console 2.6 User Guide for further information. Additionally, to support MQTT devices, the Platform provides custom models for you to create and customize.

image-20210325194536259

Let's take the default model TMX08 as an example. Select the TMX08 model within the dropdown box.

image-20210325194612455

The basic information of the model is shown in the middle part.

image-20210325194657419

  • Schemas

    Each proprietary protocol model has its own data schemas, which can be used to store and display telemetry data. Initially it only contains system schemas which cannot be deleted, while custom model has no system schema. Additionally, you can extend schemas if desired. Please note: The data of created extended schemas will be collected only if they have been configured and calculated in Flow. Please refer to 9.3 Configuring flow components in TMX Insight™ Service Platform 2.6 User Guide for further information.

    image-20210325194843082

  • Topics (Only for custom models applying MQTT protocol)

    To connect the Platform, an MQTT device needs to provide its client ID as its serial number and configure the corresponding broker URL, for example, <company_name>.gw.thingsmatrix.io. Each custom model has several topics for communication between MQTT devices and the Platform. Topics must be used for the device to report data or receive configurations and commands. There are some pre-configured topics as shown below:

    image-20210325195543613

    Devices can report data to the Platform by publishing data to the Report and Event topics. Meanwhile, devices can receive data from the Platform by subscribing data from the Config and Command topics. Please note: In current release, the Platform accepts data reported by MQTT devices in JSON format.

    • Report

      • Topic Pattern: ${model_id}/${sn}/report
      • Sample topic: M001234/801046012345678/report
      • Data Tag: Report

      A device will report real-time data based on its configuration. Assume that the device reports temperature as the real-time data, to receive and store its temperature data, an extended schema needs to be created on the Platform first, for example, temperature as the schema identifier. Please refer to 8.4 Adding new extended schemas for further information on adding an extended schema, . After the temperature schema is created, data reported by MQTT device as follows will be recorded in Reports.

      {
          "temperature": 27.5
      }
      
      • Event

        • Topic Pattern: ${model_id}/${sn}/event
          • Sample Topic: M001234/801046012345678/event
        • Data Tag: None

        To separate event-related data from report data, the Event topic is recommended. let's assume that the device reports door status as its event-related data. When the door status turns from 0 to 1, the door is opened; While the door status turns from 1 to 0, the door is closed. To receive its door status data, an extended schema needs to be created on the Platform first, for example, door_status as the schema identifier. , Please refer to 8.4 Adding new extended schemas for further information on adding an extended schema. In order to trigger an event, you need to add a flow, configure to filter the topic and then create an Event action. Please refer to 9.3 Configuring flow components in TMX Insight™ Service Platform 2.6 User Guide for further information. When the door is opened, the following data will be published to the Event topic by the device, and the Platform will trigger an door open event, which will be then recorded in Events.

        {
            "door_status": 1
        }
        
  • Groups

    It is a logical component for you to manage the common properties of a set of devices of the same model. The Dashboard part shows all the charts configured in TMX Insight™ - Dashboards and set to be enabled in Settings. Please refer to 14 Settings and 8 Dashboards in TMX Insight™ Service Platform 2.6 User Guide for further information.

    image-20210325200405141

  • Config Templates

    Each model has its unique configuration file, which is used to define the basic settings, firmware version, and ruleset of the devices of the model. During device registration and authentication, the configuration file will be passed to the IoT Gateway and downloaded onto the devices. By default, a group could have an empty configuration template, which means the devices will work with its default configuration settings. Please note: If a device is moved to a group without a config template, the Platform will issue the default configuration to the device. After applying a specific config template, all the devices within the group will apply the new configuration settings. If the config template is changed, the new configuration is proactively issued to the online devices and then applied. For offline devices, the new configuration will be issued and applied the next time the offline devices are connected to the Platform. For parameter configuration, please refer to the Parameter Table in the corresponding ThingsMatrix Device Manual for further information.

    image-20210325200600497

# 8.1 Adding new custom models

You can add new custom models to apply MQTT devices. Click the + Add Model button on the top right side, an Add Model window will pop up.

image-20210325200639103

Fill in the form to add a new custom model. You can also upload a device image of which size is smaller than 500 KB.

image-20210325200746638

# 8.2 Editing custom models

Select a custom model and then click the Edit button, an Edit Model window will pop up. Let's take the SampleModel model as an example.

image-20210325201008131

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

image-20210325201136226

# 8.3 Deleting custom models

Click the Delete button to delete the custom model. Please note: you need to remove all devices of the model first before you can delete it.

image-20210325201154861

# 8.4 Adding new extended schemas

Select one of the models and enter Schemas tab, let's take the SampleModel01 model as an example. Then by clicking the + Add Schema button on the left side, an Adding Schema form will be displayed on the right side.

image-20210325201249593

You can view the field description by hovering the mouse over its corresponding Information icon. Fill in the form and then click the Add button on the right side to add a new extended schema. Please note: The unit can be customized if desired.

image-20210325201330281

For "Configuration" field:

  • Storable

    • If checked, the schema value will be stored and can be viewed in Reports.
    • If unchecked, the data will be processed in passthrough mechanism, that is, the schema value will not be stored on the Platform and there will be no corresponding data in Reports.
  • Enable

    • If checked, the schema will be displayed on the Platform and can be accessed via APIs.
    • If unchecked, the schema will not be displayed on the Platform and cannot be accessed via APIs.

If the user would like to add a boolean type schema, its value description can be setup for better understanding.

image-20210325201445273

After saving the schema, it will be displayed in the Latest Received Report of Last Report tab in Devices for the SampleModel01 model as shown below:

image-20210325201736181

*Please note: The data of extended schemas will be generated only if they have been configured and computed in Flows in TMX Insight™ Service. If more than an extended schema is desired, follow the instructions above to add more extended schemas.

# 8.5 Viewing schemas

There are some operations to help users view schemas.

  • Search

    You can enter identifier or title to search for a specific device schema.

    image-20210325201908413

  • Sort

    You can sort the schemas by dragging the Drag button, which takes effect to the schema order in Devices - Last Report, the field order in Devices - Reports and Reports.

    image-20210325202119643

# 8.6 Editing schemas

Click the specific schema card which you are desired to edit. After the edition, click the Save button to save the changes. Please note: "Identifier" and "Type" fields cannot be modified.

image-20210325202155486

# 8.7 Enabling schemas

The data of enabled schemas can be viewed on the Platform and accessed via APIs. Click the specific schema card, check the Enable checkbox and then click the Save button, the disabled schema will be enabled. The Eye icon will turn on after the operation.

image-20210325202215577

# 8.8 Disabling schemas

The data of disabled schemas cannot be viewed on the Platform or accessed via APIs. The export report files will exclude the related data. Click the specific schema card, uncheck the Enable checkbox and then click the Save button, the enabled schema will be disabled. The Eye icon will turn off after the operation.

image-20210325202227545

# 8.9 Storing schemas

The data of storable schemas will be stored on the Platform. Click the specific schema card, check the Store in database checkbox and then click the Save button, the non-storable schema will be storable. The Storage icon will turn on after the operation.

image-20210325202242350

# 8.10 Unstoring schemas

The data of non-storable schemas will not be stored on the Platform. Click the specific schema card, uncheck the Store in database checkbox and then click the Save button, the storable schema will be non-storable. The Storage icon will turn off after the operation.

image-20210325202309329

# 8.11 Deleting extended schemas

Click the specific schema card, then click the Delete button to delete an extended schema. Please Note: System schemas cannot be removed. Users can delete extended schemas in use and all of the removed schemas will be marked as "invalid" schemas in TMX Insight™ service.

image-20210325202457625

# 8.12 Adding new custom topics

Select one of the MQTT protocol models and enter Topics tab, let's take the SampleModel model for example. Then by clicking the + Add Topic button on the left side, an Adding Topic form will be displayed on the right side. A field description will be displayed when hovering the mouse over the Information icon of each field. Fill in the form and then click the Add button on the right side to create a new custom topic. Please note: The data will be allowed to be viewed in Reports on the Platform only if it is published by the devices to a topic of which data tag is Report. For a topic with None data tag, the data published by the devices will not be stored on the Platform.

image-20210325203202462

# 8.13 Editing custom topics

Click the specific topic card which you are desired to edit. After the edition, click the Save button to save the changes. Please note: System topics cannot be edited. And once the changes have been confirmed, all data published by the devices to the former topic will not be reached. So please remember to switch the devices to valid topics.

image-20210325203255884

# 8.14 Deleting custom topics

Click the specific topic card, then click the Delete button to delete a custom topic. Please Note: System topics cannot be removed. Users can delete custom topics in use and all data published by the devices to these removed topics will not be reached. So please remember to switch the devices to valid topics.

image-20210325203313552

# 8.15 Adding new groups

Select one of the models and enter Groups tab, let's take the TMX08 model for example. Then by clicking the + Add Group button on the left side, an Adding Group form will be displayed on the right side.

image-20210325203432240

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

  • For "Template" field, you can choose to assign a specific configuration for the new group or not. Please refer to Parameter Table in the corresponding device's ThingsMatrix Device Manual for further information.

    image-20210325203523837

  • For "Certificate" field, you can select desired certificate of authentication for safety purpose (Only for specific models applying MQTT protocol). Please refer to 7 Certificates for further information.

    image-20210325203610475

# 8.16 Editing groups

Click the specific group card which you are desired to edit. After the edition, click the Save button to save the changes.

image-20210325203743756

# 8.17 Deleting groups

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

image-20210325203759793

# 8.18 Adding new config templates

Select a device model, and click the + button in the Config Template list. An Add Config Template window will pop up.

image-20210325204009165

  • Default Model

    Each device model has its own configuration parameter settings. Please refer to the Parameter Table 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", "Periodic Mode Settings", "Storage Mode Settings", "Motion Static Mode Settings", "Schedule Mode Settings", "Master Server Settings", "Firmware". 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 Add button to add a new config template.

    image-20210325204119670

  • Custom Model

    You can add a new config template by uploading a configuration file in JSON format. Enter the name and necessary description and then click the Save button to add a new config template.

    image-20210325204237105

# 8.19 Editing config templates

Select a specific config template and then click the Edit button, an Edit Config Template window will pop up.

image-20210325204526929

  • Default Model

    After changing the parameter values, click the Submit button to save all the changes. If the config 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.

    image-20210325204401266

  • Custom Model

    You can edit the config template by uploading a new configuration file in JSON format. After the edition, click the Submit button to save all the changes.

    image-20210325204458098

# 8.20 Copying config templates

By selecting a specific template and then clicking the Copy button, a Copy Config Template window will pop up.

  • Default Model

    The new generated config template is exactly the same as the one you have chosen. Enter a new name and description for the new config template, then click the Copy button to create a config template. You can also edit the settings during the creation to apply some changes on the new configuration.

    image-20210325204545692

    image-20210325204618402

  • Custom Model

    The config template is exactly the same as the one you have chosen. Enter a new name and description for the new configuration, then click the Copy button to create a config template. You can also create a new template by uploading a new configuration file in JSON format.

    image-20210325204641617

# 8.21 Deleting config templates

Select a specific config template and then click the Delete button to delete the template. Please note: A config template can only be deleted when it isn’t applied by any groups.

  • Default Model

    image-20210325204924140

  • Custom Model

    image-20210325204853213

# 9 Devices

To display device information, geographical location and data in different ways, the Platform provides the following two views (it enters the List view by default):

  • List view: Please click the List button to enter the List view.

    You can get detailed device information and also the data collected by the device. We have statistics for the data reported to the Platform, so you can have a better understanding of the data trends. A page with all added device information will show up as below:

    image-20210326102303825

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

    • Serial number: Each device has one unique serial number for identification purposes.
    • Alias: Device alias.
    • Model: Device model name.
    • PID: Device Product ID, which is used to represent the devices with same main components.
    • Group: Device group name in which the device belongs.
    • Status: Different working status of the device are as follows:
      • When a device is just imported from ThingsMatrix and hasn't connected to the Platform yet, it will show as Inactive.
      • 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
      • When a device's owner company is changed (it doesn't belong to your company at the moment), it will show as Suspended.
      • When a device is in tracking mode, it will show as Tracking.
    • 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 that the latest location data reported by the device is LBS location data; while if the satellite icon is on, it means that the latest location data reported by the device is GPS location data. However, If the icon is in grey with an X mark, it means that the Platform doesn't received any valid location data.
    • The fourth icon looks like a warning. If the warning icon is on, the device is sending events of alarm code to the Platform.

    Besides basic information, there are reported data in the list. Almost all the headers here are configured by device schemas. Please Note: Disabled schemas and their values will not be displayed. When a device reports new data to the Platform, the latest data in the list will refresh automatically, including status, state and enabled schema values. If the device doesn't report new data, the corresponding latest data in the list will still remain. Please refer to 9.8 Viewing device details for further information.

  • Map view: Please click the Map button to enter the Map view.

    Geographical location of devices is displayed more clearly with brief device information and latest data. A page with the location of all connected devices will show up as follow:

    image-20210325205506210

    For better searching and filtering experience, the Platform provides the following two modes (it enters the Filter mode by default):

    • Filter mode: Please click the Filter button to enter the Filter mode.

      You can filter the devices by selecting a model name, a group name or status.

      image-20210325205708099

      By configuring a data field, the corresponding data will display in the list and also above the location points of devices. If the corresponding data has not been generated yet, it will display as "--".

      image-20210325205759552

      As mentioned above, a device list is on the right side to show more detailed device information for each device in the visible area, including alias, serial number, model name, PID, group name, locating type, detailed address and corresponding device data if configured. Please click the serial number of the device to go to its detail page to view more information.

      image-20210325205824972

      You can easily reset or restart a specific device if available by clicking the Reset button or Restart button.

      image-20210325205914193

    • Search mode: Please click the Magnifier button to enter the Search mode.

      image-20210325205927536

      You can enter at least three digits of serial number so as to select the desired serial number. Then click the Search button to locate the specific device.

      image-20210325210026016

      For convenience, you can also set a targeting point on the map. So that it will display the map with the targeting point as the center every time after entering the Map view. Simply right click the place where you would like to set as the targeting point on the map, and click the Targeting point setting button, the specific place will be set as the targeting point.

      image-20210325210102112

      Right click the existed targeting point to delete it, or right click another place to set another new targeting point.

      image-20210325210159186

      The statistics and location of devices will refresh if new location data is reported to the Platform.

# 9.1 Adding new custom model devices

Before you can add a new custom model device, you need to create a group first. Please refer to 8.15 Adding new groups above for further information. Please note: Only custom model devices can be added manually through this way. All purchased default model devices will be imported into their default model groups by ThingsMatrix automatically. for example, all purchased TMX08 model devices will be imported into the TMX08_DG group.

After a custom model group is created, go to Devices and click the + Add Device button on the top right. An Add Device window will pop up.

image-20210326103127996

Fill in the form and click the Add button to add a new device. For "SIM ICCID" field, you can choose to provide or not provide relevant information because the Platform will automatically collect this information. If the Allow for connection after it has changed checkbox is checked, the Platform is allowed to do additional updates after the SIM 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 custom attributes to the device.

image-20210326103431983

You can see the newly added device.

image-20210326103513234

# 9.2 Importing new custom model devices

The Platform provides device import feature. Click the Import button and an Import window will pop up. Please note: Only new custom model devices can be imported. Import up to 5000 devices at a time.

image-20210326103642682

By choosing CSV or Excel format and click the Download button, a corresponding device information import template will ask to be downloaded (If you have downloaded the import template already, you may skip this step).

image-20210326103753209

After downloading the device information import template, you 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 group name to which the device belongs. A 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-40 characters, special symbols only include "_" and "-".
    • SimICCID: Must be 20 digits.
    • SimAutoUpdate: "0" means non-automatic update, "1" means automatic. By default it is 1, and leaving it empty is also regarded as the same.
    • Description: No more than 256 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 SimICCID Description Tags Attribute.Address
    861901268000009 tmx07_0009 tmx07_20m TMX07 Device 1 San Antonio, Atlanta 9442 North Capital of Texas Hwy
    801046031113285 tmx08_3285 tmx08_2h TMX08 Device 2 San Antonio, Atlanta 9445 North Capital of Texas Hwy
    801046031097369 tmx08_7369 tmx08_1h TMX08 Device 3 San Antonio, Atlanta 9442 North Capital of Texas Hwy

Then click the Upload File 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. The import will be terminated, and it does no impact on device list.

# 9.3 Exporting devices

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

image-20210326103959746

# 9.4 Editing devices

Select a device, click the Action button and then click the Edit button, an Edit Device window will pop up. Please note: Suspended devices cannot be modified.

image-20210326104124715

After editing the device, click the Submit button to save the changes to the device.

image-20210326104201663

# 9.5 Batch editing device information

The Platform provides two ways to edit devices in batch as follows:

  • By selection (For small batch of no more than 100 devices and with only minor changes on device information):

    To have larger selection, the page size need to be configured. Then you can select these specific devices in one page, click the Action button and then click the Edit button, a Batch Edit Device Info window will pop up.

    image-20210326104250217

    After the edition, click the Submit button to save the changes to the selected devices. Please note: The Modify checkbox need to be checked to apply the corresponding changes.

    image-20210326104414546

  • Via file (For larger batch of more than 100 devices or with major changes on device information):

    Simply click the Batch Edit Device Info button and a Batch Edit Device Info window will pop up. Please note: Only added devices can be edited. Batch edit up to 5000 devices at a time.

    image-20210326105205500

    By choosing CSV or Excel format and click the Download button, a corresponding device information edition template will ask to be downloaded (If you have downloaded the edition template already, you may skip this step).

    image-20210326105226693

    After downloading the device information edition template, you 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 group name to which the device belongs. A 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-40 characters, special symbols only include "_" and "-".
      • SimICCID: Must be 20 digits.
      • SimAutoUpdate: "0" means non-automatic update, "1" means automatic. By default it is 1, and leaving it empty is also regarded as the same.
      • Description: No more than 256 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 SimICCID Description Tags Attribute.Address
      861901268000009 tmx07_0009 tmx07_20m TMX07 Device 1 San Antonio, Atlanta 9442 North Capital of Texas Hwy
      801046031113285 tmx08_3285 tmx08_2h TMX08 Device 2 San Antonio, Atlanta 9445 North Capital of Texas Hwy
      801046031097369 tmx08_7369 tmx08_1h TMX08 Device 3 San Antonio, Atlanta 9442 North Capital of Texas Hwy

    Then click the Upload File button to select the file, and click the Import button to upload the file to batch edit device information. if some errors occurred during the edition, the error details will be displayed in the Import Log section. The edition will be terminated, and it does no impact on device list.

# 9.6 Deleting devices

Select a device and then click the Delete button to delete a device. Please note: Only disabled, inactive and suspended devices can be deleted. If you happened to delete a default model device but would like it back, please contact ThingsMatrix as soon as possible. For custom model device, it can be added back manually by authorized users following the instructions of 9.1 Adding new custom model devices.

image-20210326105623863

# 9.7 Issuing commands to devices

Select the device(s), by clicking the Command button, you can issue commands to them, such as enabling, disabling, restarting and resetting. Some device models support additional commands such as snapshotting, tracking, etc. However, if a command item is in gray color, the corresponding command is not supported at the moment temporarily.

Below are the following commands that can be executed:

  • The Enable/Disable button can help you activate or deactivate devices as needed (In current release, Disable command is temporarily unavailable).
  • The Restart button allows you to restart the online device remotely.
  • The Reset button can help you reset devices.
  • The Snapshot button can be used to snapshot a device, that is, make the device report its real-time location information with sensor data immediately.
  • The Track button allows you to track devices for a certain period of time.

image-20210326105818886

Please note: You can select more than one device and click the Command button to issue commands to devices in batch.

image-20210326105909686

Commands can also be issued in device detail page. Click the Command button and select a desired command to issue.

image-20210326110114999

Currently, the Platform supports following commands:

  • Disabling devices (In current release, Disable command is temporarily unavailable)

    Disabled devices cannot connect to the Platform. Click the Disable button, and the selected device will be disabled.

  • Enabling devices

    Only enabled devices can connect to the Platform. Click the Enable button, and the selected device will be enabled.

  • Restarting devices

    You can restart the online devices by clicking the Restart button.

  • Resetting devices

    Devices can be reset, and its configuration will be restored to factory settings. Please click the Reset button to reset the device.

  • Snapshotting devices

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

  • Tracking devices

    Click the Track 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, you would like to track a device in one hour and require the device to report location information every ten seconds.

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

    When tracking the device, you can still issue commands shown as below, such as restarting, resetting, snapshotting and stopping tracking 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 Tracking command at 15:00:10, setting the interval to be 10 seconds and the expiration to be 150 seconds. Then the Tracking command takes effect and the device will report data every 10 seconds in next 150 seconds. After that, the device will shutdown the Tracking command 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 Tracking command had been performed.

# 9.8 Viewing device details

By selecting one of the added devices in the list, the second half of the page will display more details:

  • Last Report
  • Statistics
  • Reports
  • Dashboards
  • Events
  • Operation Log

image-20210326110416963

Click the Full Screen button on the right side, it will enter the device detail page.

image-20210326110452152

  1. Last Report

    A device's serial number, alias, model name, group name, certificate name (Only for custom models applying MQTT protocol), description, SIM ICCID, SKU, tags and attributes are shown in the Information section. You can view the device's latest reported data in the Latest Received Report section together with the geographical location of the device in the Location section. Please note: The order of the schemas in the Latest Received Report section can be managed in Models - Schemas. The latest data will refresh if new data is reported by the devices.

    image-20210326110505250

  2. Statistics

    You can view the chart of device's detailed historical data and the chart of statistics data by configured time range, schema title and granularity. A path map is also provided to show device's route records in the Path section. By selecting a desired schema title, for example "Signal Strength", its historical data will display on the map. you can switch between All, LBS and GPS to filter data reported in different locating mode. The Historical Data chart will refresh if new data is reported by the device.

    image-20210326110551655

  3. Reports

    You can view the device's report records. Click the Export button to export filtered report records. Please note: The order of the fields can be managed in Models - Schemas.

    image-20210326110649043

  4. Dashboards

    You can view all the charts configured in TMX Insight™ - Dashboards and set to be enabled in Settings for the selected device. Please refer to 8 Dashboards in TMX Insight™ Service Platform 2.6 User Guide and 14 Settings for further information.

    image-20210326111019697

  5. Events

    You can view the device's event records. For better understanding, the Platform provides two views (it enters the Table view by default):

    • Table view: Please click the Table View button to enter the Table view.

      You can configure the time range, event name(s) (including event codes & alarm codes), level and status to filter event records.

      image-20210326111033267

    • Chart view: Please click the Chart View button to enter the Chart view.

      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. You can also configure the time range, event name(s) (including event codes & alarm codes), level and status to obtain a more specific event chart.

      image-20210326111044350

  6. Operation Log

    You can view the device's operation log, which records the operations made by the users or the system. To filter the operation(s), you can configure the time range, field name, description, operation type and operator.

    image-20210326111107071

# 9.9 Editing device list headers

In the List view, Click the Edit Headers button and an Edit Headers window will pop up.

image-20210326111121113

You can select preferred headers to be displayed or hidden. Move the fields into Displayed Header List or Hidden Header List section by clicking the Left/Right button.

image-20210326120015917

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

image-20210326120100091

After you finished the edition, click the Submit button to apply the changes.

# 10 Commands

The platform provides a command center for device command management. You can view command records as shown below:

image-20210325210752516

# 10.1 Adding new commands

Click the + Add Command button on the top right side, an Add Command window will pop up.

image-20210325210826881

There are three steps need to be done totally to add a new command:

  • First Step: Command and Device

    Please enter a command alias, write a description and select devices which are required to execute the command. You can search a device by entering at least one digit of its serial number. A filter of model name, group name and status is also provided to select specific devices.

    image-20210325210901762

    If a selected device needs to be excluded, click the Delete button on the right side of the device to remove it from the selected device list.

    image-20210325210917791

    By clicking the Clear All button, all of the selected devices will be removed from the selected device list.

    image-20210325210937457

    After filling in the form in the first step, click the Next button to go to the second step.

  • Second Step: Configuration

    There is a selected device list for you to assure device selection. After the confirmation, you can select one of the common supported command types to illustrate which type of command is desired to execute. Only one type of command can be chosen. Hover the mouse on the Information icon on the top right of the command type button to read its description. Let's select the restart type of command for example as shown below:

    image-20210325211018736

    After finishing the selection, click the Next button to go to the third step.

  • Third Step: Parameter and Strategy

    Fill in the form and click the Add button to add a new command. For Execute Strategy, you can choose multiple status, signal strength range and battery condition to determine which devices are required to execute the command. The command can be set to be executed immediately or on schedule by selecting a fixed time. For Retry Strategy, timeout, retry times and retry interval can be configured. Please note: The value of Timeout means the total execution timeout, that is, if the command exceeds timeout, the command will be marked as Failed. All retries are processed within the duration of timeout.

    image-20210325211110303

# 10.2 Favoriting commands

By clicking the Favorite button, the specific command will be favorited, that is, it will be displayed on the top of the command list. You can find a specific command more easily by favoriting it.

image-20210325211226805

# 10.3 Canceling favorite commands

By clicking the Cancel Favorite button, the specific command will be removed from the favorites.

image-20210325211153649

# 10.4 Viewing commands

You can search commands by entering device serial number, device alias or command alias. You can also filter the commands by selecting a specific time, the result will show a command list where the specific time is between the start time and the end time of the commands. The platform also provides a command status filter. Check the Favorite icon, the result will show the favorite command list.

image-20210325211321760

Select a specific command, its detail is shown in the bottom section as shown below:

image-20210325211348702

Enter the Device tab to view detailed device command execution results.

image-20210325211422912

# 10.5 Copying commands

Click the Copy button, a Copy Command window will pop up. Following the instructions in 10.1 Adding new commands to copy the command, Before submitting, you can perform edition based on requirements to add a desired command.

image-20210325211458351

# 10.6 Retrying commands

Select a command and then click the Retry button to retry the execution of the specific command.

image-20210325211512002

To retry a specific device command, you can also select a command, enter the Device tab, select the desired device and then click the Retry button.

image-20210325211531663

# 10.7 Canceling commands

Select a command and then click the Cancel button to cancel the execution of the specific command.

image-20210325211546594

To cancel a specific device command, you can also select a command, enter the Device tab, select the desired device and then click the Cancel button.

image-20210325211600991

# 10.8 Exporting commands

Select a command, enter the Device tab, and then click the Export button to export specific device command records.

image-20210325211622544

An Export window will pop up, and you can choose to get the command records exported in Excel or CSV format.

# 11 Reports

It displays detailed report records received from the devices.

image-20210325212243554

# 11.1 Viewing report records

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

image-20210325212314032

All the report records of the devices whose model is TMX08 will be displayed. You can filter the records by specifying device serial number, selecting time range and device group. Please note: The order of the fields can be managed in Models - Schemas.

image-20210325212353520

# 11.2 Exporting report records

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

image-20210325212407072

# 12 Events

It displays detailed event records received from the devices.

image-20210325212630851

# 12.1 Viewing event records

All the event records of the devices will be displayed. For better understanding, the Platform provides two views (it enters the Table view by default):

  • Table view: Please click the Table View button to enter the Table view.

    image-20210325212823567

    You can configure the serial number, time range, model name, group name, event name(s) (including event codes & alarm codes), level and status to filter event records.

    image-20210325212804270

  • Chart view: Please click the Chart View button to enter the Chart view.

    image-20210325212851504

    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. You can configure the serial number, time range, model name, group name, event name(s) (including event codes & alarm codes), level and status to obtain a more specific event chart.

    image-20210325212901548

# 12.2 Exporting event records

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

image-20210325212922910

# 13 API Services

The Platform provides north bound API services to external users and systems. Please refer to TMX Access™ Service Platform 2.6 API Guide for detailed technical information. Please refer to Console 2.6 User Guide - 10 API Applications for further information on API access control.

# 14 Settings

Map display type can be selected by clicking the Edit button via the settings. You can also enable/disable dashboard display. You can select specific dashboard to display in Devices, Models or Buckets in ThingsMatrix Insight™ service. Then click the Save button to save the changes.

image-20210325213525489

image-20210325213359856

By clicking the dashboard name, you can go to the dashboard detail page.

image-20210325213428899

Click the Restore Default button to return to the initial state.

image-20210325213505087

The company admin 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.

  • Company admin
  1. Personal TMX Settings

    image-20210325213708705

  2. Company TMX Settings

    image-20210325213734821

  • Other users

    Personal TMX Settings only

    image-20210325214148495

# 15 Operation Log

You can view log of operations performed by company members.

image-20210325214510483

You can search operations by selecting target type, operation type, operator. You can also filter the operations by configuring a specific time range and entering target object, field name or description.

image-20210325214716607

# 16 Notification Board

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

image-20210325214947134

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

image-20210325215005838

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

Click the Confirm button to confirm the notice.

image-20210326120700549

Last updated: 5/17/2021, 3:26:04 PM