Skip to main content

Siemens Tutorial

Tutorial to transform Siemens UDT to JSON

This tutorial has been tested against the Siemens Simatic 1507 PLC version 2.7.0, being programmed and controlled with TIA Portal version 16.

Requirements:

  • Ensure the FairCom server is installed and running.

  • Confirm server access by running the FairCom API Explorer. The typical URL is https://localhost:8443/ .

Siemens UDT to JSON transform tutorials

tutorialsJSONUDT to JSONtransformtransform method

Obtain and convert the UDT schema

  1. Export the schema that pertains to the user-defined data type that will be serialized and sent to FairCom Edge using your Siemens development environment TIA Portal.

    1. Navigate to PLC data types.

    2. Right-click the desired data type.

    3. Select Generate source from blocks/including all dependent blocks to save the .UDT file to disk.

    4. Copy the .UDT file to the machine that you are performing your FairCom development on.

    5. Observe the .UDT file contents.

      Example 1. .UDT file contents

      TYPE "Machine_Status"

      TITLE = Realtime status of stamper 1

      VERSION : 0.1

      STRUCT 

       XPos : Real;

        YPos : Real;

        StatusCode : Int;

        Info : String[54];

        CycleID : Array[1.."Cycle_ID_Array_Length"] of Char;

      END_STRUCT;

      END_TYPE



  2. Make a note of the root TYPE name — for example, "Machine_Status" in Example 1, “.UDT file contents”, you will need this root TYPE name to Create the Siemens UDT-to-JSON transform.

    Note

    If your UDT has multiple nested data structures, use the root TYPE name of the parent structure that nests all other structures. Often it is the last structure listed in the .UDT file. 

  3. Prepare the UDT for insertion into JSON, using the following conversions so that the .UDT file can be passed to FairCom Edge inside a JSON document.

    • Replace any array-length variables with their actual integer values.

      Example 2. Replace array-length variables with actual integer values
      CycleID : Array[1.."Cycle_ID_Array_Length"] of Char;

      to

      CycleID : Array[1..30] of Char;


    • Replace double-quotes/quotation marks with single quotes/apostrophes.

    • Replace End-Of-Line control chars (\r\n in Windows) with the following 2-character string:  \n

    Example 3. Conversion

    The listed conversions in Step 3 convert the .UDT file contents in Example 1, “.UDT file contents” to:

    TYPE 'Machine_Status'\nTITLE = Realtime status of stamper 1\nVERSION : 0.1\nSTRUCT\n  XPos : Real;\n  YPos : Real;\n  StatusCode : Int;\n  Info : String[54];\n  CycleID : Array[1..30] of Char;\nEND_STRUCT;\nEND_TYPE\n


Configure your Siemens PLC to publish to the FairCom Edge broker

The project running in your PLC must be configured to connect to the FairCom Edge MQTT broker and publish MQTT messages to that broker which contains a serialized version of your UDT data.  How that is done depends on the PLC model and the development language and environment used to program it.

  1. Navigate to and open the FairCom Edge services.json file in the <faircom>\config folder.

  2. Locate the "listeners" array in the services.json file and determine which one of the following objects matches how your PLC connects to the MQTT broker.

    • "serviceName": "mqtt1883"

    • "serviceName": "mqtts8883"

    • "serviceName": "mqttws9001"

    • "serviceName": "mqttwss9002"

  3. Ensure that the "enabled" property is set to true for the relevant block.

  4. Observe the MQTT topic that the messages are being published to and how often they are being published.

Verify that the UDT-to-JSON transform service is enabled

  1. Open services.json from the <faircom>\config folder in a text editor.

  2. Locate the "transformServices" object and ensure the "enabled" property is set to true.

    "transformServices": [
    {
        "serviceName": "siemensUdt2Json",
        "serviceLibrary": "siemensudtservice.dll",
        "enabled": true
    }
]

    Note

    The "serviceLibrary" property value will differ depending on your operating system.

  3. Save any changes.

  4. Restart the server for the changes to take effect.

Validate that the PLC is publishing MQTT messages to the broker

  1. Ensure changes made to the PLC project are uploaded to the PLC.

  2. Set the PLC to RUN mode.

  3. Validate that the PLC is connected and publishing messages to the FairCom EdgeMQTT broker:

    1. Open the FairCom MQ Explorer (https://localhost:8443//MQExplorer/index.html).

    2. Select MQTT Management from the Control menu button (ControlMenu.png).

    3. Click Subscribe (SubscribeManageSubscriptionbutton.png) to open the Manage Subscriptions window.

    4. Select the MQTT topic that the PLC is publishing to from the Topic dropdown menu.

    5. Click + Subscribe (SubscribePlusButton.png).

    6. Close the Manage Subscriptions window.

    7. Observe your messages, displayed under Incoming Messages each time the PLC publishes a message to that topic.

      Note

      The format of the messages is binary.

    8. If the topic is not visible or the messages are not arriving in the topic:

      1. Check for error messages in the CTSTATUS.FCS file in the FairCom Edge data folder.

      2. Perform any necessary debugging on the PLC side.

Create the Siemens UDT-to-JSON transform

  1. Open the FairCom MQ Explorer (https://localhost:8443//MQExplorer/index.html).

  2. Select API Explorer from the Control menu (ControlMenu.png).

  3. Replace the JSON in the API Request editor with the following JSON:

    • Update the "schema" property value with the converted UDT schema noted in Conversion.

    • Update the "rootTypeName" property value with the root type name noted from the .UDT file contents.

    {
    "api": "hub",
    "apiVersion": "1.0",
    "action": "createTransform",
    "params": {
        "transformName": "PLCData_transform",
        "transformActions": [
            {
                "transformService": "siemensUdt2Json",
                "transformStepMethod": "siemensUdtPayloadToJson",
                "inputFields": [
                    "source_payload"
                ],
                "outputFields": [
                    "aValidFieldName"
                ],
                "transformParams": {
                    "schema": "ReplaceWithConvertedUdtSchema",
                    "rootTypeName": "ReplaceWithRootName",
                    "udtDebugTracing": true
                }
            }
        ]
    },
    "authToken": "replaceWithAuthTokenFromCreateSession"
}

  4. Click Apply defaults to JSON request (Apply.PNG) to replace the "authToken" value with the valid one from your session.

  5. Click Send request (Runbutton.png) to issue the JSON-based request.

  6. Observe the response and ensure the action completed successfully.

    Note

    "errorCode" with a value of 0 indicates success. "errorCode" with a non-zero value indicates a failure. See Errors and contact FairCom for more information about an error.

Configure the MQTT topic to use the newly created transform

  1. Select MQ API from the Select API dropdown menu.

  2. Select "configureTopic" from the JSON Actions dropdown menu.

  3. Replace the JSON in the API Request editor with the following JSON:

    {
    "api": "mq",
    "apiVersion": "1.0",
    "action": "configureTopic",
    "params": {
        "topic": "ReplaceWithTopicName",
        "transformName": "PlcData_transform",
        "outputPayloadField": "aValidFieldName"
    },
    "authToken": "replaceWithAuthTokenFromCreateSession"
}

  4. Update the "topic" property value with the name of the MQTT topic that the PLC is publishing to.

  5. Click Apply defaults to JSON request (Apply.PNG) to replace the "authToken" value with the valid one from your session.

  6. Click Send request (Runbutton.png) to issue the JSON-based request.

  7. Observe the response and ensure the action completed successfully.

    Note

    "errorCode" with a value of 0 indicates success. "errorCode" with a non-zero value indicates a failure. See Errors and contact FairCom for more information about an error.

Validate that MQTT messages are being changed to JSON

  1. Open the FairCom MQ Explorer (https://localhost:8443//MQExplorer/index.html).

  2. Select MQ Explorer from the Control menu button (ControlMenu.png).

  3. Observe your messages, displayed under Incoming Messages each time the PLC publishes a message to that topic.