============
Adding Nodes
============

The OPC UA address space consists of a set of nodes interconnected by various
types of references. There are two main categories of references: hierarchical
and non-hierarchical.

Hierarchical references are used to construct a tree structure of nodes, which
is commonly visible in different UI clients.

Non-hierarchical references have a special significance and are used to describe
the relationships between nodes. For instance, the HasTypeDefinition reference
type is used to define a type with a predefined set of fields.

Node attributes
---------------

Every node in OPC UA can be one of the following classes:

* Variable
* VariableType
* Object
* ObjectType
* Method
* View
* DataType
* ReferenceType

Each node has a set of attributes that describe it. The full list of attributes
is detailed in the `OPC-UA specification <https://reference.opcfoundation.org/Core/Part3/v105/docs/5>`__.

Folder and Variable nodes
-------------------------

The most basic nodes in the address space are Folder and Variable nodes. Folder
nodes are used to organize the address space into a tree structure, while Variable
nodes are used to store data values.

The SDK provides helper functions to simplify the process of adding Folder and
Variable nodes to the address space:

.. function:: ua.newFolderParams(parentNodeId, nodeName, requestedNodeId)

  Function creates a table with parameters for adding a new folder node.

.. function:: ua.newVariableParams(parentNodeId, nodeName, defaultValue, requestedNodeId)

  Function creates a table with parameters for adding a new variable node.


:parentNodeId: ( :ref:`node_id_type` ) Parent node identifier.

:nodeName: (string) The internal name for the node. This name is used in the
  TranslateBrowsePathsToNodeIdsservice to resolve NodeId by the path from
  some nodes.

:defaultValue: (:ref:`data_value_type`) The default value for the variable.

:requestedNodeId: ( :ref:`node_id_type` ) NodeID for the new node. The identifier
  will be automatically assigned by the server if NodeId equals ua.NodeId.Null.


Adding nodes example
---------------------

A Variable in OPC-UA is a node in the address space with a set of predefined
attributes:

  .. literalinclude:: examples/server/server_add_nodes.lua
      :language: lua
      :lines: 11-44

  `Full source <_static/server/server_add_nodes.lua>`__

New node common attributes
--------------------------

To add new object into address space you need to pass a table with the following
parameters:

  **ParentNodeId** ( :ref:`node_id_type` )
    Parent node identifier.

  **ReferenceTypeId** (:ref:`node_id_type`)
    Parent's reference type identifier.

  **RequestedNewNodeId** (:ref:`node_id_type`)
    NodeID for the new node. The identifier will be automatically assigned by
    the server if NodeId equals ua.NodeId.Null.

  **BrowseName** (:ref:`qualified_name_type`)
    The internal non-localizable name for the node. This name is used in the
    TranslateBrowsePathsToNodeIdsservice to resolve NodeId by the path from
    some nodes.

  **NodeClass** (uint8)
    Node equal to ua.NodeClass.Object,

  **TypeDefinition** (:ref:`node_id_type`)
    Node ID of the object type definition. According this will be created an
    underlining node hierarcy.

  **NodeAttributes** (:ref:`extension_object_type`)
    An Extension object table with attributes specific to the object node.
    The follwing sections describes the full set of attributes for different
    node classes.

.. _object_node_attributes:

Object NodeAttributes
---------------------

**TypeId** (:ref:`node_id_type`)
  Node ID of Object attributes "i=354"

**Body** (:ref:`extension_object_type`)
  A body of extension object attrubutes:

  **SpecifiedAttributes** = ua.ObjectAttributesMask

  **DisplayName** (:ref:`localized_text_type`)
    Clients use this attribute if they want to show the name of the node to the user. Can be localized.

  **Description** (:ref:`localized_text_type`)
    The optional description attribute explains the purpose of the node using localized text.

  **WriteMask** (UInt32)
    Bit mask. Makes it possible for a client to write the Attributes of the Node.

  **UserWriteMask** (UInt32)
    Bit mask. Makes it possible for a client to write the Attributes of the Node.

  **EventNotifier** (Byte)
    Event notifier.

Object NodeAttributes example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: lua

  local folderParams = { -- #1
    ParentNodeId = ObjectsFolder,
    ReferenceTypeId = Organizes,
    RequestedNewNodeId = "i=1000",
    BrowseName = {Name="TestFolder", ns=0},
    NodeClass = ua.NodeClass.Object,
    TypeDefinition = FolderType,
    NodeAttributes = {
      TypeId = "i=354",
      Body = {
        SpecifiedAttributes = ua.ObjectAttributesMask,
        DisplayName = {Text="DisplayName"},
        Description = {Text="Description"},
        WriteMask = 0,
        UserWriteMask = 0,
        EventNotifier = 0,
      }
    }
  }