Getting Started
###############

This guide walks through setting up a Siemens PLC project using the SDK.

Getting the SDK
***************
The SDK is packaged as a downloadable .zip archive found on `help.graco.com <https://help.graco.com>`_. The latest version (as of writing) is GracoPd2kInt_Siemens_SDK_v\ |version|\ .zip.

Using the example project as a template
***************************************
The SDK comes with a Siemens example project providing some basic functionality right out of the box. Using this project as a starting point is a good way to get to a working system quickly.

The example project can be found in the GracoPd2kInt_Example directory; the project file is GracoPd2kInt_Example.ap17. Since this is a V17 project, make sure you have the correct version of TIA Portal installed on your PC.

Configure the PLC
=================

The example project comes pre-loaded with a 1211C CPU program:

.. image:: ../assets/project-tree-cpus.png

This can be downloaded directly to a matching physical PLC, or changed to a different model by right-clicking on the CPU and selecting "change device".

All of the FBs, FCs, and UDTs are included in the program under a "GracoPd2kInt" group folder:

.. image:: ../assets/project-tree-blocks.png

Configure the PD2K
==================

In the network view of the example project, a default PD2K device is connected to the PLC:

.. image:: ../assets/network-view.png

Make sure to set the Profinet settings to match the actual device - these are in Device view -> General -> PROFINET interface -> Ethernet addresses:

.. image:: ../assets/pd2k-pn-settings.png

Once the network configuration is setup to match your real device network, the project can be downloaded to your physical PLC.

Project Structure
=================
The Main (OB1) block is the entrypoint for this project. This block simply calls an instance of the Pd2kExample FB:

.. image:: ../assets/example_main.png

All of the logic for this example is wrapped in this FB. Open the FB definition to see its code:

.. image:: ../assets/example_fb.png

The FB is quite simple - it calls a few other FBs/FCs included with the SDK. Each block handles one particular task; for example, the StatusToUDT FC reads data from the PD2K and copies it into a UDT for more convenient lookup. The PumpControl and GunControl blocks provide an interface for controlling the system, e.g. writing mode commands via boolean variables. You can read the network comments for more information.

The example FB uses an instance datablock named "Pd2kExample_DB1". Typically, you do not need to touch this, as all of the relevant data is passed through parameters.

At the root of the project, there is a datablock named "Globals". This block contains everything you as the user can access for controlling the PD2K:

.. image:: ../assets/global-vars.png

Each of these variables correspond to parameters for the Pd2kExample FB called in Main.

The PD2K_STATUS variable contains all of the status data arranged in a convenient UDT form. This tends to be much easier compared to working with the `I` process data directly. For more info, see :ref:`StatusToUDT`.

The PD2K_PUMP_CTRL variable provides access to the system mode commands and setpoints. Similarly, the PD2K_GUN_CTRL variable provides access to the gun-related commands and setpoints. For more info, see :ref:`PumpControl` and :ref:`GunControl`.

The PD2K_ALM_CODE and PD2K_ALM_DT variables are the most recent alarm code and datetime values, respectively. These are updated through the :ref:`ReadAlarmInfo` FB.

Finally, the PD2K_TARGET variable is the :ref:`TypeTarget` instance used to point to the actual PD2K device defined in the project network configuration. see :ref:`using-typetarget`;

Note that no PLC tags are being used with this example. Because of how the project is structured, you can simply access everything you need through the Globals datablock instead (but you can always add your own tags if you wish).

Running the PD2K
================
Once you have downloaded the example project to a PLC, you can start running the PD2K using the provided code.

While online with the PLC, open the Global DB. Expand the PD2K_TARGET variable. Confirm that the ``simulate`` variable is set to FALSE and the ``pnDeviceNum`` matches that of the PD2K device (default is 1):

.. image:: ../assets/globals_target_expanded.png

Expand the PD2K_STATUS variable. Assuming the PD2K is currently in "pump off" mode, you should see a "1" for the system mode along with the "pumpOff" system mode flag set to TRUE:

.. image:: ../assets/globals-pump-off.png

Next, expand the PD2K_PUMP_CTRL variable. Right-click the powerOnCmd member and select "modify operand":

.. image:: ../assets/globals-powerOnCmd.png

Set the modify value to 1 (i.e. TRUE) and click OK:

.. image:: ../assets/modify-pumpOnCmd.png

The :ref:`PumpControl` FB sees this boolean and pulses the system mode command to "power on" (note the FB also clears the powerOnCmd boolean). If there are no alarms present, the pumps should power on, followed by the system mode status showing "standby":

.. image:: ../assets/globals-standby.png

You should now be able to set any of the other controls found in PD2K_PUMP_CTRL and PD2K_GUN_CTRL and control the system. For example, write a desired flow rate value to PD2K_PUMP_CTRL.mixCtrlSP, then set recipeChangeCmd to TRUE to perform a recipe change.


Where to go from here
=====================
Now that you have explored the example project, you should have a better understanding of how to use the SDK in your own larger applications. For example:

* The variables provided in the Globals DB can be connected to an HMI for touchscreen control of the system.
* You can use the Globals DB variables within your own custom application sequence. For example, the PLC can monitor the pot life time of the current recipe and automatically trigger a purge when neccessary.
* Because of the modular design of the FBs/FCs, you can expand your program to control multiple PD2K systems from the same PLC. Simply create a :ref:`TypeTarget` variable for each instance, assign that instance's profinet device number, and pass that into your function calls.

For more information about all the available program blocks, see the :ref:`api-doc`.

Adding the SDK to an existing project
*************************************
Besides using the example project, the contents of the SDK can be pulled into an existing TIA Portal project as well. The recommended way is using the provided global library named "GracoPd2kInt_Library". This contains all of the FBs/FCs/UDTs from the example project, each of which can be added to an existing TIA Portal project.

Using the global library
========================

With a TIA Portal project open, select the Libraries pane and click the "open global library" button:

.. image:: ../assets/open-global-library.png

Select the GracoPd2kInt_Library.al17 file in the file navigator and click Open. The blocks can be found in this library under the "Master copies" folder:

.. image:: ../assets/library-blocks.png

Drag any of the program blocks into the project to use them. Note that the blocks must be dropped into their given folders, e.g. FBs/FCs must go in Program blocks, UDTs must go in PLC data types. Once copied over, these blocks can be used in the program.

.. note::

  The blocks in the global library are stored as "master copies", meaning they are not directly linked to the copies in the PLC program. Any changes made in the PLC will not affect the global library (and vice-versa).

  "Library types", on the other-hand, provide a link between the the global library and the blocks in the PLC. However, we do not utilize this feature in the SDK because it conflicts with the Siemens Version Control Interface (VCI), and SDK development is done using that tool instead.