tutorial_server_object.c 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334
  1. /* This work is licensed under a Creative Commons CCZero 1.0 Universal License.
  2. * See http://creativecommons.org/publicdomain/zero/1.0/ for more information. */
  3. /**
  4. * Working with Objects and Object Types
  5. * -------------------------------------
  6. *
  7. * Using objects to structure information models
  8. * ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  9. * Assume a situation where we want to model a set of pumps and their runtime
  10. * state in an OPC UA information model. Of course, all pump representations
  11. * should follow the same basic structure, For example, we might have graphical
  12. * representation of pumps in a SCADA visualisation that shall be resuable for
  13. * all pumps.
  14. *
  15. * Following the object-oriented programming paradigm, every pump is represented
  16. * by an object with the following layout:
  17. *
  18. * .. graphviz::
  19. *
  20. * digraph tree {
  21. *
  22. * fixedsize=true;
  23. * node [width=2, height=0, shape=box, fillcolor="#E5E5E5", concentrate=true]
  24. *
  25. * node_root [label=< <I>ObjectNode</I><BR/>Pump >]
  26. *
  27. * { rank=same
  28. * point_1 [shape=point]
  29. * node_1 [label=< <I>VariableNode</I><BR/>ManufacturerName >] }
  30. * node_root -> point_1 [arrowhead=none]
  31. * point_1 -> node_1 [label="hasComponent"]
  32. *
  33. * { rank=same
  34. * point_2 [shape=point]
  35. * node_2 [label=< <I>VariableNode</I><BR/>ModelName >] }
  36. * point_1 -> point_2 [arrowhead=none]
  37. * point_2 -> node_2 [label="hasComponent"]
  38. *
  39. * { rank=same
  40. * point_4 [shape=point]
  41. * node_4 [label=< <I>VariableNode</I><BR/>Status >] }
  42. * point_2 -> point_4 [arrowhead=none]
  43. * point_4 -> node_4 [label="hasComponent"]
  44. *
  45. * { rank=same
  46. * point_5 [shape=point]
  47. * node_5 [label=< <I>VariableNode</I><BR/>MotorRPM >] }
  48. * point_4 -> point_5 [arrowhead=none]
  49. * point_5 -> node_5 [label="hasComponent"]
  50. *
  51. * }
  52. *
  53. * The following code manually defines a pump and its member variables. We omit
  54. * setting constraints on the variable values as this is not the focus of this
  55. * tutorial and was already covered. */
  56. #include "open62541.h"
  57. #include <signal.h>
  58. static void
  59. manuallyDefinePump(UA_Server *server) {
  60. UA_NodeId pumpId; /* get the nodeid assigned by the server */
  61. UA_ObjectAttributes oAttr = UA_ObjectAttributes_default;
  62. oAttr.displayName = UA_LOCALIZEDTEXT("en-US", "Pump (Manual)");
  63. UA_Server_addObjectNode(server, UA_NODEID_NULL,
  64. UA_NODEID_NUMERIC(0, UA_NS0ID_OBJECTSFOLDER),
  65. UA_NODEID_NUMERIC(0, UA_NS0ID_ORGANIZES),
  66. UA_QUALIFIEDNAME(1, "Pump (Manual)"), UA_NODEID_NUMERIC(0, UA_NS0ID_BASEOBJECTTYPE),
  67. oAttr, NULL, &pumpId);
  68. UA_VariableAttributes mnAttr = UA_VariableAttributes_default;
  69. UA_String manufacturerName = UA_STRING("Pump King Ltd.");
  70. UA_Variant_setScalar(&mnAttr.value, &manufacturerName, &UA_TYPES[UA_TYPES_STRING]);
  71. mnAttr.displayName = UA_LOCALIZEDTEXT("en-US", "ManufacturerName");
  72. UA_Server_addVariableNode(server, UA_NODEID_NULL, pumpId,
  73. UA_NODEID_NUMERIC(0, UA_NS0ID_HASCOMPONENT),
  74. UA_QUALIFIEDNAME(1, "ManufacturerName"),
  75. UA_NODEID_NUMERIC(0, UA_NS0ID_BASEDATAVARIABLETYPE), mnAttr, NULL, NULL);
  76. UA_VariableAttributes modelAttr = UA_VariableAttributes_default;
  77. UA_String modelName = UA_STRING("Mega Pump 3000");
  78. UA_Variant_setScalar(&modelAttr.value, &modelName, &UA_TYPES[UA_TYPES_STRING]);
  79. modelAttr.displayName = UA_LOCALIZEDTEXT("en-US", "ModelName");
  80. UA_Server_addVariableNode(server, UA_NODEID_NULL, pumpId,
  81. UA_NODEID_NUMERIC(0, UA_NS0ID_HASCOMPONENT),
  82. UA_QUALIFIEDNAME(1, "ModelName"),
  83. UA_NODEID_NUMERIC(0, UA_NS0ID_BASEDATAVARIABLETYPE), modelAttr, NULL, NULL);
  84. UA_VariableAttributes statusAttr = UA_VariableAttributes_default;
  85. UA_Boolean status = true;
  86. UA_Variant_setScalar(&statusAttr.value, &status, &UA_TYPES[UA_TYPES_BOOLEAN]);
  87. statusAttr.displayName = UA_LOCALIZEDTEXT("en-US", "Status");
  88. UA_Server_addVariableNode(server, UA_NODEID_NULL, pumpId,
  89. UA_NODEID_NUMERIC(0, UA_NS0ID_HASCOMPONENT),
  90. UA_QUALIFIEDNAME(1, "Status"),
  91. UA_NODEID_NUMERIC(0, UA_NS0ID_BASEDATAVARIABLETYPE), statusAttr, NULL, NULL);
  92. UA_VariableAttributes rpmAttr = UA_VariableAttributes_default;
  93. UA_Double rpm = 50.0;
  94. UA_Variant_setScalar(&rpmAttr.value, &rpm, &UA_TYPES[UA_TYPES_DOUBLE]);
  95. rpmAttr.displayName = UA_LOCALIZEDTEXT("en-US", "MotorRPM");
  96. UA_Server_addVariableNode(server, UA_NODEID_NULL, pumpId,
  97. UA_NODEID_NUMERIC(0, UA_NS0ID_HASCOMPONENT),
  98. UA_QUALIFIEDNAME(1, "MotorRPMs"),
  99. UA_NODEID_NUMERIC(0, UA_NS0ID_BASEDATAVARIABLETYPE), rpmAttr, NULL, NULL);
  100. }
  101. /**
  102. * Object types, type hierarchies and instantiation
  103. * ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  104. * Building up each object manually requires us to write a lot of code.
  105. * Furthermore, there is no way for clients to detect that an object represents
  106. * a pump. (We might use naming conventions or similar to detect pumps. But
  107. * that's not exactly a clean solution.) Furthermore, we might have more devices
  108. * than just pumps. And we require all devices to share some common structure.
  109. * The solution is to define ObjectTypes in a hierarchy with inheritance
  110. * relations.
  111. *
  112. * .. graphviz::
  113. *
  114. * digraph tree {
  115. *
  116. * fixedsize=true;
  117. * node [width=2, height=0, shape=box, fillcolor="#E5E5E5", concentrate=true]
  118. *
  119. * node_root [label=< <I>ObjectTypeNode</I><BR/>Device >]
  120. *
  121. * { rank=same
  122. * point_1 [shape=point]
  123. * node_1 [label=< <I>VariableNode</I><BR/>ManufacturerName<BR/>(mandatory) >] }
  124. * node_root -> point_1 [arrowhead=none]
  125. * point_1 -> node_1 [label="hasComponent"]
  126. *
  127. * { rank=same
  128. * point_2 [shape=point]
  129. * node_2 [label=< <I>VariableNode</I><BR/>ModelName >] }
  130. * point_1 -> point_2 [arrowhead=none]
  131. * point_2 -> node_2 [label="hasComponent"]
  132. *
  133. * { rank=same
  134. * point_3 [shape=point]
  135. * node_3 [label=< <I>ObjectTypeNode</I><BR/>Pump >] }
  136. * point_2 -> point_3 [arrowhead=none]
  137. * point_3 -> node_3 [label="hasSubtype"]
  138. *
  139. * { rank=same
  140. * point_4 [shape=point]
  141. * node_4 [label=< <I>VariableNode</I><BR/>Status<BR/>(mandatory) >] }
  142. * node_3 -> point_4 [arrowhead=none]
  143. * point_4 -> node_4 [label="hasComponent"]
  144. *
  145. * { rank=same
  146. * point_5 [shape=point]
  147. * node_5 [label=< <I>VariableNode</I><BR/>MotorRPM >] }
  148. * point_4 -> point_5 [arrowhead=none]
  149. * point_5 -> node_5 [label="hasComponent"]
  150. *
  151. * }
  152. *
  153. * Children that are marked mandatory are automatically instantiated together
  154. * with the parent object. This is indicated by a `hasModellingRule` reference
  155. * to an object that representes the `mandatory` modelling rule. */
  156. /* predefined identifier for later use */
  157. UA_NodeId pumpTypeId = {1, UA_NODEIDTYPE_NUMERIC, {1001}};
  158. static void
  159. defineObjectTypes(UA_Server *server) {
  160. /* Define the object type for "Device" */
  161. UA_NodeId deviceTypeId; /* get the nodeid assigned by the server */
  162. UA_ObjectTypeAttributes dtAttr = UA_ObjectTypeAttributes_default;
  163. dtAttr.displayName = UA_LOCALIZEDTEXT("en-US", "DeviceType");
  164. UA_Server_addObjectTypeNode(server, UA_NODEID_NULL,
  165. UA_NODEID_NUMERIC(0, UA_NS0ID_BASEOBJECTTYPE),
  166. UA_NODEID_NUMERIC(0, UA_NS0ID_HASSUBTYPE),
  167. UA_QUALIFIEDNAME(1, "DeviceType"), dtAttr,
  168. NULL, &deviceTypeId);
  169. UA_VariableAttributes mnAttr = UA_VariableAttributes_default;
  170. mnAttr.displayName = UA_LOCALIZEDTEXT("en-US", "ManufacturerName");
  171. UA_NodeId manufacturerNameId;
  172. UA_Server_addVariableNode(server, UA_NODEID_NULL, deviceTypeId,
  173. UA_NODEID_NUMERIC(0, UA_NS0ID_HASCOMPONENT),
  174. UA_QUALIFIEDNAME(1, "ManufacturerName"),
  175. UA_NODEID_NUMERIC(0, UA_NS0ID_BASEDATAVARIABLETYPE), mnAttr, NULL, &manufacturerNameId);
  176. /* Make the manufacturer name mandatory */
  177. UA_Server_addReference(server, manufacturerNameId,
  178. UA_NODEID_NUMERIC(0, UA_NS0ID_HASMODELLINGRULE),
  179. UA_EXPANDEDNODEID_NUMERIC(0, UA_NS0ID_MODELLINGRULE_MANDATORY), true);
  180. UA_VariableAttributes modelAttr = UA_VariableAttributes_default;
  181. modelAttr.displayName = UA_LOCALIZEDTEXT("en-US", "ModelName");
  182. UA_Server_addVariableNode(server, UA_NODEID_NULL, deviceTypeId,
  183. UA_NODEID_NUMERIC(0, UA_NS0ID_HASCOMPONENT),
  184. UA_QUALIFIEDNAME(1, "ModelName"),
  185. UA_NODEID_NUMERIC(0, UA_NS0ID_BASEDATAVARIABLETYPE), modelAttr, NULL, NULL);
  186. /* Define the object type for "Pump" */
  187. UA_ObjectTypeAttributes ptAttr = UA_ObjectTypeAttributes_default;
  188. ptAttr.displayName = UA_LOCALIZEDTEXT("en-US", "PumpType");
  189. UA_Server_addObjectTypeNode(server, pumpTypeId,
  190. deviceTypeId, UA_NODEID_NUMERIC(0, UA_NS0ID_HASSUBTYPE),
  191. UA_QUALIFIEDNAME(1, "PumpType"), ptAttr,
  192. NULL, NULL);
  193. UA_VariableAttributes statusAttr = UA_VariableAttributes_default;
  194. statusAttr.displayName = UA_LOCALIZEDTEXT("en-US", "Status");
  195. statusAttr.valueRank = -1;
  196. UA_NodeId statusId;
  197. UA_Server_addVariableNode(server, UA_NODEID_NULL, pumpTypeId,
  198. UA_NODEID_NUMERIC(0, UA_NS0ID_HASCOMPONENT),
  199. UA_QUALIFIEDNAME(1, "Status"),
  200. UA_NODEID_NUMERIC(0, UA_NS0ID_BASEDATAVARIABLETYPE), statusAttr, NULL, &statusId);
  201. /* Make the status variable mandatory */
  202. UA_Server_addReference(server, statusId,
  203. UA_NODEID_NUMERIC(0, UA_NS0ID_HASMODELLINGRULE),
  204. UA_EXPANDEDNODEID_NUMERIC(0, UA_NS0ID_MODELLINGRULE_MANDATORY), true);
  205. UA_VariableAttributes rpmAttr = UA_VariableAttributes_default;
  206. rpmAttr.displayName = UA_LOCALIZEDTEXT("en-US", "MotorRPM");
  207. rpmAttr.valueRank = -1;
  208. UA_Server_addVariableNode(server, UA_NODEID_NULL, pumpTypeId,
  209. UA_NODEID_NUMERIC(0, UA_NS0ID_HASCOMPONENT),
  210. UA_QUALIFIEDNAME(1, "MotorRPMs"),
  211. UA_NODEID_NUMERIC(0, UA_NS0ID_BASEDATAVARIABLETYPE), rpmAttr, NULL, NULL);
  212. }
  213. /**
  214. * Now we add the derived ObjectType for the pump that inherits from the device
  215. * object type. The resulting object contains all mandatory child variables.
  216. * These are simply copied over from the object type. The object has a reference
  217. * of type ``hasTypeDefinition`` to the object type, so that clients can detect
  218. * the type-instance relation at runtime.
  219. */
  220. static void
  221. addPumpObjectInstance(UA_Server *server, char *name) {
  222. UA_ObjectAttributes oAttr = UA_ObjectAttributes_default;
  223. oAttr.displayName = UA_LOCALIZEDTEXT("en-US", name);
  224. UA_Server_addObjectNode(server, UA_NODEID_NULL,
  225. UA_NODEID_NUMERIC(0, UA_NS0ID_OBJECTSFOLDER),
  226. UA_NODEID_NUMERIC(0, UA_NS0ID_ORGANIZES),
  227. UA_QUALIFIEDNAME(1, name),
  228. pumpTypeId, /* this refers to the object type
  229. identifier */
  230. oAttr, NULL, NULL);
  231. }
  232. /**
  233. * Often times, we want to run a constructor function on a new object. This is
  234. * especially useful when an object is instantiated at runtime (with the
  235. * AddNodes service) and the integration with an underlying process canot be
  236. * manually defined. In the following constructor example, we simply set the
  237. * pump status to on.
  238. */
  239. static UA_StatusCode
  240. pumpTypeConstructor(UA_Server *server,
  241. const UA_NodeId *sessionId, void *sessionContext,
  242. const UA_NodeId *typeId, void *typeContext,
  243. const UA_NodeId *nodeId, void **nodeContext) {
  244. UA_LOG_INFO(UA_Log_Stdout, UA_LOGCATEGORY_USERLAND, "New pump created");
  245. /* Find the NodeId of the status child variable */
  246. UA_RelativePathElement rpe;
  247. UA_RelativePathElement_init(&rpe);
  248. rpe.referenceTypeId = UA_NODEID_NUMERIC(0, UA_NS0ID_HASCOMPONENT);
  249. rpe.isInverse = false;
  250. rpe.includeSubtypes = false;
  251. rpe.targetName = UA_QUALIFIEDNAME(1, "Status");
  252. UA_BrowsePath bp;
  253. UA_BrowsePath_init(&bp);
  254. bp.startingNode = *nodeId;
  255. bp.relativePath.elementsSize = 1;
  256. bp.relativePath.elements = &rpe;
  257. UA_BrowsePathResult bpr =
  258. UA_Server_translateBrowsePathToNodeIds(server, &bp);
  259. if(bpr.statusCode != UA_STATUSCODE_GOOD ||
  260. bpr.targetsSize < 1)
  261. return bpr.statusCode;
  262. /* Set the status value */
  263. UA_Boolean status = true;
  264. UA_Variant value;
  265. UA_Variant_setScalar(&value, &status, &UA_TYPES[UA_TYPES_BOOLEAN]);
  266. UA_Server_writeValue(server, bpr.targets[0].targetId.nodeId, value);
  267. UA_BrowsePathResult_deleteMembers(&bpr);
  268. /* At this point we could replace the node context .. */
  269. return UA_STATUSCODE_GOOD;
  270. }
  271. static void
  272. addPumpTypeConstructor(UA_Server *server) {
  273. UA_NodeTypeLifecycle lifecycle;
  274. lifecycle.constructor = pumpTypeConstructor;
  275. lifecycle.destructor = NULL;
  276. UA_Server_setNodeTypeLifecycle(server, pumpTypeId, lifecycle);
  277. }
  278. /** It follows the main server code, making use of the above definitions. */
  279. UA_Boolean running = true;
  280. static void stopHandler(int sign) {
  281. UA_LOG_INFO(UA_Log_Stdout, UA_LOGCATEGORY_SERVER, "received ctrl-c");
  282. running = false;
  283. }
  284. int main(void) {
  285. signal(SIGINT, stopHandler);
  286. signal(SIGTERM, stopHandler);
  287. UA_ServerConfig *config = UA_ServerConfig_new_default();
  288. UA_Server *server = UA_Server_new(config);
  289. manuallyDefinePump(server);
  290. defineObjectTypes(server);
  291. addPumpObjectInstance(server, "pump2");
  292. addPumpObjectInstance(server, "pump3");
  293. addPumpTypeConstructor(server);
  294. addPumpObjectInstance(server, "pump4");
  295. addPumpObjectInstance(server, "pump5");
  296. UA_StatusCode retval = UA_Server_run(server, &running);
  297. UA_Server_delete(server);
  298. UA_ServerConfig_delete(config);
  299. return (int)retval;
  300. }