Working with Factory Data

Data in Tier0 unified namespace can be altered and managed through MQTT and APIs with authorization.

MQTT

MQTT clients can connect to the UNS broker with credentials generated on Tier0.

Note

You can use MQTT clients such as MQTTX, MQTT Explorer, and Node-RED to connect to the broker and publish/subscribe messages.

Generating MQTT Credentials

On the Edge tab in Tier0, create a new credential and make a note of it.

Exceptions on Tier0 Edge version

The Tier0 Edge version does not require credentials for external connections.

Connecting MQTT Clients

Tip

• The UNS broker can be connected through both TCP and WSS with the following address:
  • mqtt://host:1883
  • mqtts://host:8883
  • ws://host:8083/mqtt
  • wss://host:8084/mqtt
• TCP without TLS is used as an example in the following connections.

MQTTX

1. Install and open MQTTX.
2. Add a connection with the information of the UNS broker and the generated credentials.

   {
     "Host": "mqtt.tier0.dev",
     "Port": 1883,
     "Client ID": "<generated client ID>",
     "Username": "<generated username>",
     "Password": "<generated password>"
   }

MQTT Explorer

1. Install and open MQTT Explorer.
2. Add a new connection with the UNS broker information and the generated credentials.

   {
     "Protocol": "mqtt://",
     "Host": "mqtt.tier0.dev",
     "Port": 1883,
     "Username": "<generated username>",
     "Password": "<generated password>"
   }

3. Change the client ID to the credential ID in ADVANCED before connecting.

Node-RED

• Use Event Flow - Data processing module in Tier0 based on Node-RED.

  1. Create an Event Flow in Flows, and start it with an mqtt in node.
  2. Select the UNS broker as Server (same name as the flow) and set Topic to a UNS model in the node.

• Use Independent Node-RED Instance

  1. Install and open the Node-RED instance.
  2. Add a server in the mqtt in node with the following information.

  {
    {/* under Connection */}
    "Server": "mqtt://mqtt.tier0.dev",
    "Port": 1883,
    "Client ID": "<generated clientId>",
    {/* under Security */}
    "Username": "<generated username>",
    "Password": "<generated password>"
  }

Testing Connections

1. Make sure the client status is normal.
2. Copy a UNS model topic and publish a message to it through the client.

API

Use the REST API to operate on UNS data.

How to use the API

The OpenAPI base path is /openapi/v1, For example https://your-workspace.tier0.app/openapi/v1, and pass your API key in the x-api-key header.

Getting API Key

API keys are from Settings > API Keys. Depend on different account type, allowed key types are different.

• Service Key: Can only be created by Admin and Owner.
• Personal Key: Can be created by anyone, and the permission scope is the same as that of the account.

Key permisson vs Account permission

Account permission trumps key permission. When the key permission is set to Full Access, data unavailable to the account still cannot be accessed with this key.

Examples

• /uns/create

  Create UNS path or topic. Use namespace to define the node tree.

  JavaScript

  const BASE_URL = process.env.TIER0_BASE_URL;
  const API_KEY = process.env.TIER0_API_KEY;
  
  const response = await fetch(`${BASE_URL}/uns/create`, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'x-api-key': API_KEY,
    },
    body: JSON.stringify({
      namespace: [
        {
          name: 'DemoFactory',
          type: 'PATH',
          children: [
            {
              name: 'Site_01',
              type: 'PATH',
              children: [
                {
                  name: 'Production',
                  type: 'PATH',
                  children: [
                    {
                      name: 'Produced_Qty',
                      type: 'TOPIC',
                      topicType: 'METRIC',
                      displayName: 'Produced Quantity',
                      description: 'Produced quantity from the production line.',
                      enableHistory: true,
                      fields: [
                        { name: 'value', type: 'DOUBLE', unit: 'pcs' },
                      ],
                    },
                  ],
                },
              ],
            },
          ],
        },
      ],
    }),
  });
  
  const result = await response.json();
  console.log(result.data.results);

  Python

  import os
  import requests
  
  base_url = os.environ["TIER0_BASE_URL"]
  api_key = os.environ["TIER0_API_KEY"]
  
  response = requests.post(
      f"{base_url}/uns/create",
      headers={"x-api-key": api_key},
      json={
          "namespace": [
              {
                  "name": "DemoFactory",
                  "type": "PATH",
                  "children": [
                      {
                          "name": "Site_01",
                          "type": "PATH",
                          "children": [
                              {
                                  "name": "Production",
                                  "type": "PATH",
                                  "children": [
                                      {
                                          "name": "Produced_Qty",
                                          "type": "TOPIC",
                                          "topicType": "METRIC",
                                          "displayName": "Produced Quantity",
                                          "description": "Produced quantity from the production line.",
                                          "enableHistory": True,
                                          "fields": [
                                              {"name": "value", "type": "DOUBLE", "unit": "pcs"},
                                          ],
                                      },
                                  ],
                              },
                          ],
                      },
                  ],
              },
          ],
      },
      timeout=30,
  )
  response.raise_for_status()
  
  result = response.json()
  print(result["data"]["results"])

  cURL

  curl -X POST "$TIER0_BASE_URL/uns/create" \
    -H "content-type: application/json" \
    -H "x-api-key: $TIER0_API_KEY" \
    -d '{
      "namespace": [
        {
          "name": "DemoFactory",
          "type": "PATH",
          "children": [
            {
              "name": "Site_01",
              "type": "PATH",
              "children": [
                {
                  "name": "Production",
                  "type": "PATH",
                  "children": [
                    {
                      "name": "Produced_Qty",
                      "type": "TOPIC",
                      "topicType": "METRIC",
                      "displayName": "Produced Quantity",
                      "description": "Produced quantity from the production line.",
                      "enableHistory": true,
                      "fields": [
                        { "name": "value", "type": "DOUBLE", "unit": "pcs" }
                      ]
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }'

• /uns/read

  Read the latest value and metadata for one or more UNS topics.

  JavaScript

  const BASE_URL = process.env.TIER0_BASE_URL;
  const API_KEY = process.env.TIER0_API_KEY;
  
  const response = await fetch(`${BASE_URL}/uns/read`, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'x-api-key': API_KEY,
    },
    body: JSON.stringify({
      topics: [
        'DemoFactory/Site_01/Production/Produced_Qty',
      ],
      include_leaf_value: true,
      include_metadata: true,
    }),
  });
  
  const result = await response.json();
  console.log(result.data.results);

  Python

  import os
  import requests
  
  base_url = os.environ["TIER0_BASE_URL"]
  api_key = os.environ["TIER0_API_KEY"]
  
  response = requests.post(
      f"{base_url}/uns/read",
      headers={"x-api-key": api_key},
      json={
          "topics": [
              "DemoFactory/Site_01/Production/Produced_Qty",
          ],
          "include_leaf_value": True,
          "include_metadata": True,
      },
      timeout=30,
  )
  response.raise_for_status()
  
  result = response.json()
  print(result["data"]["results"])

  cURL

  curl -X POST "$TIER0_BASE_URL/uns/read" \
    -H "content-type: application/json" \
    -H "x-api-key: $TIER0_API_KEY" \
    -d '{
      "topics": [
        "DemoFactory/Site_01/Production/Produced_Qty"
      ],
      "include_leaf_value": true,
      "include_metadata": true
    }'

• /uns/update

  Update a UNS node by path. Use updateMask to specify which fields should change.

  JavaScript

  const BASE_URL = process.env.TIER0_BASE_URL;
  const API_KEY = process.env.TIER0_API_KEY;
  
  const response = await fetch(`${BASE_URL}/uns/update`, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'x-api-key': API_KEY,
    },
    body: JSON.stringify({
      path: 'DemoFactory/Site_01/Production/Produced_Qty',
      displayName: 'Produced Quantity',
      description: 'Updated production output quantity.',
      updateMask: ['displayName', 'description'],
    }),
  });
  
  const result = await response.json();
  console.log(result.data);

  Python

  import os
  import requests
  
  base_url = os.environ["TIER0_BASE_URL"]
  api_key = os.environ["TIER0_API_KEY"]
  
  response = requests.post(
      f"{base_url}/uns/update",
      headers={"x-api-key": api_key},
      json={
          "path": "DemoFactory/Site_01/Production/Produced_Qty",
          "displayName": "Produced Quantity",
          "description": "Updated production output quantity.",
          "updateMask": ["displayName", "description"],
      },
      timeout=30,
  )
  response.raise_for_status()
  
  result = response.json()
  print(result["data"])

  cURL

  curl -X POST "$TIER0_BASE_URL/uns/update" \
    -H "content-type: application/json" \
    -H "x-api-key: $TIER0_API_KEY" \
    -d '{
      "path": "DemoFactory/Site_01/Production/Produced_Qty",
      "displayName": "Produced Quantity",
      "description": "Updated production output quantity.",
      "updateMask": ["displayName", "description"]
    }'

• /uns/delete

  Delete one or more UNS models. Use hard_delete: false to move models to the recycle bin.

  JavaScript

  const BASE_URL = process.env.TIER0_BASE_URL;
  const API_KEY = process.env.TIER0_API_KEY;
  
  const response = await fetch(`${BASE_URL}/uns/delete`, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'x-api-key': API_KEY,
    },
    body: JSON.stringify({
      topics: [
        'DemoFactory/Site_01/Production/Produced_Qty',
      ],
      hard_delete: false,
    }),
  });
  
  const result = await response.json();
  console.log(result.data);

  Python

  import os
  import requests
  
  base_url = os.environ["TIER0_BASE_URL"]
  api_key = os.environ["TIER0_API_KEY"]
  
  response = requests.post(
      f"{base_url}/uns/delete",
      headers={"x-api-key": api_key},
      json={
          "topics": [
              "DemoFactory/Site_01/Production/Produced_Qty",
          ],
          "hard_delete": False,
      },
      timeout=30,
  )
  response.raise_for_status()
  
  result = response.json()
  print(result["data"])

  cURL

  curl -X POST "$TIER0_BASE_URL/uns/delete" \
    -H "content-type: application/json" \
    -H "x-api-key: $TIER0_API_KEY" \
    -d '{
      "topics": [
        "DemoFactory/Site_01/Production/Produced_Qty"
      ],
      "hard_delete": false
    }'

API reference

• Tier0 OpenAPI Reference

Next

• Build Apps on UNS — Build industrial applications with UNS data.
• Analyze UNS Data — Analyze UNS data with Marimo Notebook and Python.