The Tetra Internet of Things (IoT) Agent allows sensors and instruments with no network connectivity options to be connected to the Tetra Scientific Data and AI Cloud. Connectivity is provided by using both additional hardware (the Tetra IoT Agent Box) and the Tetra IoT Layer, which provides dedicated cloud resources.

TetraScience provides the additional hardware to your organization prior to Tetra Data Platform (TDP) deployment. A user with Administrator permissions must configure both the TDP and the Tetra IoT Agent Boxes to have the correct user organization and driver information before the Agent can upload data to the Tetra Scientific Data and AI Cloud.

To set up the Tetra IoT Agent Box, see Tetra IoT Box Local Setup and Configuration.

📘

NOTE

You will see the supported instruments when you set up a data source for the IoT integration. For sensors or instruments that are not displayed in the drop-down, please consult with TetraScience about instrument compatibility.

Create a New Tetra IoT Agent

To configure a new Tetra IoT Agent, do the following:

1. Sign in to the TDP as a user with Administrator permissions. Then, in the left navigation menu, choose Data Sources.
2. Choose IoT. The IoT Agents page appears.
3. Select the + Create New Agent button. The Create IoT Agent dialog appears.
4. Enter the following information:
   • For Agent Name, enter a name for the Agent. Make sure that the name includes only letters, numbers, spaces, and the following symbols: +,-,/, ., or _. Names must be less than 256 characters.
   • (Optional) For Agent Description, enter a brief description of the Agent. Consider adding information about how the Agent is going to be used.
   • For Device Vendor, select the name of the vendor who made the device that the IoT Agent device is attached to.
   • For Device Model, select the model of the device that the IoT Agent device is connected to.
   • For Device Drive, enter select the device driver that you want to use.
   • For Driver Version, enter the device driver version.
   • For Device Name, enter a name for the device. Make sure that the name includes only letters, numbers, spaces, and the following symbols: +,-,/, ., or _.
   • (Optional) For Device Description, enter a brief description of the device that you're connecting.
5. If needed, configure attributes for the data source. All files uploaded from this data source will automatically inherit the attributes as file attributes. For more information, see Manage and Apply Attributes.
6. Choose Create. The IoT Agent page appears and displays the Agent that you just created.

Sync the Tetra IoT Agent to the Tetra IoT Agent Box

A newly created agent will not be paired to any Tetra IoT Agent Box. To establish a link, you must sync the agent to a box. An IoT Agent can be synced to a box once only. After the Agent is synced to a box, it will be permanently associated with that box and its serial number.

To sync a Tetra IoT Agent to a box, do the following:

1. Make sure the IoT box is configured so that its external ID matches the Agent's ID that you want to sync it with. For instructions, see Tetra IoT Agent Local Setup and Configuration.
2. Sign in to the TDP as a user with Administrator permissions. Then, in the left navigation menu, choose Data Sources.
3. Choose IoT. The IoT Agents page appears.
4. Find the Agent that you want to sync. Then, on the right of that Agent's row, select the Sync IoT Agent icon.

If the sync fails, this usually means either that the Tetra IoT Agent Box has failed to establish a connection to the TDP, or that the external ID doesn't match the expected Agent. Both of these possibilities can be checked in the box's [local configuration]((https://developers.tetrascience.com/docs/setting-up-and-configuring-the-tetra-iot-agent).

Move a Tetra IoT Box Between Agents

Although an Agent can only ever be paired to one box, it is possible for multiple Tetra IoT Agents to link to the same box. However, only one Agent can be active at a time.

The main use case for this is to allow a box to be switched between different TDP organizations. For example, you might have a development org that you want to use for validating the integration, with the intention of moving it over to a production org once ready. The box can be transferred to a second Agent if the second Agent has never been synced to a box, or if the second Agent has already been synced to the same box in the past.

🚧

IMPORTANT

Although multiple agents can be synced to a single box, only one of these Agents is allowed to be active at a time.

To transfer a Tetra IoT Agent Box between Agents, do the following:

1. If there is currently an active Agent using the box, disable that Agent. To verify this, use the text box in the upper right of the IoT Agents page. Then, search the list of current Agents by using the serial number of the Tetra IoT Agent Box.
2. Set the external ID of the box to match the Agent that you want associated with the box..
3. Sync the Tetra IoT Agent to the box.
   - or -
   (If the Agent you are transferring to has already been synced to the box before) If the Agent already has an assigned serial number that matches the box, then from the right side of the page, select More > Enable Agent.

Viewing Existing Tetra IoT Agents

To view your organization's Tetra IoT Agents, do the following:

1. Sign in to the TDP as a user with Administrator permissions. Then, in the left navigation menu, choose Data Sources.

2. Choose IoT. The IoT Agents page appears.

   

The IoT Agent page displays the following information:

• IoT Agent Summary statistics, including the number of Agent configurations available and how many IoT Agents are online, offline, or disabled.
• Status filters that allow you to view all of the IoT Agents or only those that are online, offline, or disabled.
• A search bar that allows you to search for an agent by either name or serial number.
• A list of IoT Agents set up in your organization's TDP.

View a Detailed Summary of an IoT Agent Device Configuration

On the IoT Agents page, clicking a row corresponding to a single Agent will expand and show the following information:

• Customer device name
• Instrument device vendor and type
• Device model, driver, and driver version
• MAC address
• Agent and Device descriptions
• Labels, metadata, and tags (if any)

Activate and Deactivate IoT Agent Devices

To activate or deactivate Tetra IoT Agents, do the following:

1. Sign in to the TDP as a user with Administrator permissions. Then, in the left navigation menu, choose Data Sources.
2. Choose IoT. The IoT Agents page appears.
3. Select the name of the IoT agent that you want to activate or deactivate. A dialog appears.
4. On the upper right of the dialog, select the More drop-down menu. Then, choose one of the following:
   • To activate the device, select Enable Agent.
   • To deactivate the device, select Disable Agent.

View the IoT Agent Device's Configuration File

In addition to the local configuration of the Tetra IoT Agent Box to establish communication with the TDP, the box also requires configuration specific to the actual instrument it will be attached to. Based on the chosen vendor, device, and driver chosen during Agent creation, the TDP will generate the appropriate configuration to send to the box.

• On the IoT Agents page, select the name of the IoT Agent you want to see the configuration for. Then, select the View IoT Agent Configuration button that appears on the right side of the screen.
• Alternatively, select the name of the IoT Agent that you want to see the configuration for. Then, select the edit icon to view the Edit IoT Agent screen. Scroll to the bottom of the screen and select the View Config File link.

Using Custom Configuration Files

In some cases, the generated configuration file may not be accurate for your device. For example, if the TDP has an incorrect default port for serial communication with the instrument, you may need to correct that. By clicking More > Custom Config, you can provide an XML configuration file to be applied instead of the standard, templated version.

🚧

IMPORTANT

The configuration file controls key aspects of the Tetra IoT Agent Box's communication with the TDP. Always begin custom configuration by copying the generated configuration file as a base, and modify only what you need to.

The most likely use case for custom configuration is if you are using a Tetra Hub as a proxy for the box, as discussed in Tetra IoT Box Local Setup and Configuration.

Setting Proxy Information in Custom Configuration

When using a Tetra Hub proxy, the default templated XML configuration that the TDP sends to the box will overwrite these settings. This can be worked around by using a custom XML configuration file and doing the following:

1. From the IoT Agents page in the TDP, select the Agent that you're working with and view the configuration file. Copy the contents.
2. On the same Agent, click More > Custom Config.
3. Paste the contents from the original file.
4. Search for the line beginning <driver n="T.IDrv.Task:libkmqtt". Find the config field . The value of this field will be a string, with several values separated by semicolons (;). The first and third entries in the string will correspond to the hostname of the IoT cloud server used in your deployment (for example, iot.tetrascience-dev.com).
5. Replace that hostname with the address or hostname of your Tetra Hub proxy.
6. Choose Confirm.

Edit a Tetra IoT Agent's Configuration

To edit an IoT Agent's configuration, do the following:

1. On the IoT Agents page, select the name of the IoT Agent that you want to edit. Then, select the edit icon on the right side of the page. The Edit IoT Agent page appears.
2. Edit the configuration information as needed.
3. Choose Save.