tutorial_server_object.c 14 KB

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