manuals/developer-guide/src/main/asciidoc/ocpplugin/ocp-developer-guide.adoc

   1 == OCP Plugin Developer Guide
   2 This document is intended for both OCP (ORI [Open Radio Interface] C&M [Control and Management]
   3 Protocol) agent developers and OpenDaylight service/application developers.
   4 It describes essential information needed to implement an OCP agent that is capable of interoperating
   5 with the OCP plugin running in OpenDaylight, including the OCP connection establishment and
   6 state machines used on both ends of the connection. It also provides a detailed description of the
   7 northbound/southbound APIs that the OCP plugin exposes to allow automation and programmability.
   8
   9 === Overview
  10 OCP is an ETSI standard protocol for control and management of Remote Radio Head (RRH)
  11 equipment. The OCP Project addresses the need for a southbound plugin that allows
  12 applications and controller services to interact with RRHs using OCP. The OCP southbound
  13 plugin will allow applications acting as a Radio Equipment Control (REC) to interact
  14 with RRHs that support an OCP agent.
  15
  16 .OCP southbound plugin
  17 image::ocpplugin/ocp-sb-plugin.jpg[OCP southbound plugin,width=500]
  18
  19 === Architecture
  20 OCP is a vendor-neutral standard communications interface defined to enable control and management
  21 between RE and REC of an ORI architecture. The OCP Plugin supports the implementation of the OCP
  22 specification; it is based on the Model Driven Service Abstraction Layer (MD-SAL) architecture.
  23
  24 The OCP Plugin project consists of three main components: OCP southbound plugin, OCP protocol library
  25 and OCP service. For details on each of them, refer to the OCP Plugin User Guide.
  26
  27 .Overall architecture
  28 image::ocpplugin/plugin-design.jpg[Overall architecture,width=500]
  29
  30 === Connection Establishment
  31 The OCP layer is transported over a TCP/IP connection established between the RE and the REC.
  32 OCP provides the following functions:
  33
  34 * Control & Management of the RE by the REC
  35 * Transport of AISG/3GPP Iuant Layer 7 messages and alarms between REC and RE
  36
  37 ==== Hello Message
  38 Hello message is used by the OCP agent during connection setup. It is used for version negotiation.
  39 When the connection is established, the OCP agent immediately sends a Hello message with the version
  40 field set to highest OCP version supported by itself, along with the verdor ID and serial number of
  41 the radio head it is running on.
  42
  43 The combinaiton of the verdor ID and serial number will be used by the OCP plugin to uniquely identify
  44 a managed radio head. When not receiving reply from the OCP plugin, the OCP agent can resend Hello
  45 message with pre-defined Hello timeout (THLO) and Hello resend times (NHLO).
  46
  47 According to ORI spec, the default value of TCP Link Monitoring Timer (TTLM) is 50 seconds. The RE shall
  48 trigger an OCP layer restart while TTLM expires in RE or the RE detects a TCP link failure. So we may
  49 define NHLO * THLO = 50 seconds (e.g. NHLO = 10, THLO = 5 seconds).
  50
  51 By nature the Hello message is a new type of indication, and it contains supported OCP version, vendor
  52 ID and serial number as shown below.
  53
  54 .Hello message
  55 ----
  56 <?xml version="1.0" encoding="UTF-8"?>
  57 <msg xmlns="http://uri.etsi.org/ori/002-2/v4.1.1">
  58   <header>
  59     <msgType>IND</msgType>
  60     <msgUID>0</msgUID>
  61   </header>
  62   <body>
  63     <helloInd>
  64       <version>4.1.1</version>
  65       <vendorId>XYZ</vendorId>
  66       <serialNumber>ABC123</serialNumber>
  67     </helloInd>
  68   </body>
  69 </msg>
  70 ----
  71
  72 ==== Ack Message
  73 Hello from the OCP agent will always make the OCP plugin respond with ACK. In case everything is OK,
  74 it will be ACK(OK). In case something is wrong, it will be ACK(FAIL).
  75
  76 If the OCP agent receives ACK(OK), it goes to Established state. If the OCP agent receives ACK(FAIL),
  77 it goes to Maintenance state. The failure code and reason of ACK(FAIL) are defined as below:
  78
  79 * FAIL_OCP_VERSION (OCP version not supported)
  80 * FAIL_NO_MORE_CAPACITY (OCP plugin cannot control any more radio heads)
  81
  82 The result inside Ack message indicates OK or FAIL with different reasons.
  83
  84 .Ack message
  85 ----
  86 <?xml version="1.0" encoding="UTF-8"?>
  87 <msg xmlns="http://uri.etsi.org/ori/002-2/v4.1.1">
  88   <header>
  89     <msgType>ACK</msgType>
  90     <msgUID>0</msgUID>
  91   </header>
  92   <body>
  93     <helloAck>
  94       <result>FAIL_OCP_VERSION</result>
  95     </helloAck>
  96   </body>
  97 </msg>
  98 ----
  99
 100 ==== State Machines
 101 The following figures illustrate the Finite State Machine (FSM) of the OCP agent and OCP plugin
 102 for new connection procedure.
 103
 104 .OCP agent state machine
 105 image::ocpplugin/ocpagent-state-machine.jpg[OCP agent state machine,width=500]
 106
 107 .OCP plugin state machine
 108 image::ocpplugin/ocpplugin-state-machine.jpg[OCP plugin state machine,width=500]
 109
 110 === Northbound APIs
 111 There are ten exposed northbound APIs: health-check, set-time, re-reset, get-param,
 112 modify-param, create-obj, delete-obj, get-state, modify-state and get-fault
 113
 114 ==== health-check
 115 The Health Check procedure allows the application to verify that the OCP layer is functioning
 116 correctly at the RE.
 117
 118 Default URL: http://localhost:8181/restconf/operations/ocp-service:health-check-nb
 119
 120 ===== POST Input
 121
 122 [options="header",cols="2,1,2,2,1"]
 123 |=======
 124 |Field Name | Type | Description | Example | Required?
 125 | nodeId | String | Inventory node reference for OCP radio head | ocp:MTI-101-200 | Yes
 126 | tcpLinkMonTimeout | unsignedShort | TCP Link Monitoring Timeout (unit: seconds) | 50 | Yes
 127 |=======
 128
 129 .Example
 130 ----
 131 {
 132     "health-check-nb": {
 133         "input": {
 134             "nodeId": "ocp:MTI-101-200",
 135             "tcpLinkMonTimeout": "50"
 136         }
 137     }
 138 }
 139 ----
 140
 141 ===== POST Output
 142
 143 [options="header",cols="1,1,2"]
 144 |=======
 145 |Field Name | Type | Description
 146 | result | String, enumerated | Common default result codes
 147 |=======
 148
 149 .Example
 150 ----
 151 {
 152     "output": {
 153         "result": "SUCCESS"
 154     }
 155 }
 156 ----
 157
 158 ==== set-time
 159 The Set Time procedure allows the application to set/update the absolute time reference that
 160 shall be used by the RE.
 161
 162 Default URL: http://localhost:8181/restconf/operations/ocp-service:set-time-nb
 163
 164 ===== POST Input
 165
 166 [options="header",cols="1,1,2,2,1"]
 167 |=======
 168 |Field Name | Type | Description | Example | Required?
 169 | nodeId | String | Inventory node reference for OCP radio head | ocp:MTI-101-200 | Yes
 170 | newTime | dateTime | New datetime setting for radio head | 2016-04-26T10:23:00-05:00 | Yes
 171 |=======
 172
 173 .Example
 174 ----
 175 {
 176     "set-time-nb": {
 177         "input": {
 178             "nodeId": "ocp:MTI-101-200",
 179             "newTime": "2016-04-26T10:23:00-05:00"
 180         }
 181     }
 182 }
 183 ----
 184
 185 ===== POST Output
 186
 187 [options="header",cols="1,1,2"]
 188 |=======
 189 |Field Name | Type | Description
 190 | result | String, enumerated | Common default result codes + FAIL_INVALID_TIMEDATA
 191 |=======
 192
 193 .Example
 194 ----
 195 {
 196     "output": {
 197         "result": "SUCCESS"
 198     }
 199 }
 200 ----
 201
 202 ==== re-reset
 203 The RE Reset procedure allows the application to reset a specific RE.
 204
 205 Default URL: http://localhost:8181/restconf/operations/ocp-service:re-reset-nb
 206
 207 ===== POST Input
 208
 209 [options="header",cols="1,1,2,2,1"]
 210 |=======
 211 |Field Name | Type | Description | Example | Required?
 212 | nodeId | String | Inventory node reference for OCP radio head | ocp:MTI-101-200 | Yes
 213 |=======
 214
 215 .Example
 216 ----
 217 {
 218     "re-reset-nb": {
 219         "input": {
 220             "nodeId": "ocp:MTI-101-200"
 221         }
 222     }
 223 }
 224 ----
 225
 226 ===== POST Output
 227
 228 [options="header",cols="1,1,2"]
 229 |=======
 230 |Field Name | Type | Description
 231 | result | String, enumerated | Common default result codes
 232 |=======
 233
 234 .Example
 235 ----
 236 {
 237     "output": {
 238         "result": "SUCCESS"
 239     }
 240 }
 241 ----
 242
 243 ==== get-param
 244 The Object Parameter Reporting procedure allows the application to retrieve the following information:
 245
 246 . the defined object types and instances within the Resource Model of the RE
 247 . the values of the parameters of the objects
 248
 249 Default URL: http://localhost:8181/restconf/operations/ocp-service:get-param-nb
 250
 251 ===== POST Input
 252
 253 [options="header",cols="1,1,2,2,1"]
 254 |=======
 255 |Field Name | Type | Description | Example | Required?
 256 | nodeId | String | Inventory node reference for OCP radio head | ocp:MTI-101-200 | Yes
 257 | objId | String | Object ID | RxSigPath_5G:1 | Yes
 258 | paramName | String | Parameter name | dataLink | Yes
 259 |=======
 260
 261 .Example
 262 ----
 263 {
 264     "get-param-nb": {
 265         "input": {
 266             "nodeId": "ocp:MTI-101-200",
 267             "objId": "RxSigPath_5G:1",
 268             "paramName": "dataLink"
 269         }
 270     }
 271 }
 272 ----
 273
 274 ===== POST Output
 275
 276 [options="header",cols="1,1,2"]
 277 |=======
 278 |Field Name | Type | Description
 279 | id | String | Object ID
 280 | name | String | Object parameter name
 281 | value | String | Object parameter value
 282 | result | String, enumerated | Common default result codes + "FAIL_UNKNOWN_OBJECT", "FAIL_UNKNOWN_PARAM"
 283 |=======
 284
 285 .Example
 286 ----
 287 {
 288     "output": {
 289         "obj": [
 290             {
 291                 "id": "RxSigPath_5G:1",
 292                 "param": [
 293                     {
 294                         "name": "dataLink",
 295                         "value": "dataLink:1"
 296                     }
 297                 ]
 298             }
 299         ],
 300         "result": "SUCCESS"
 301     }
 302 }
 303 ----
 304
 305 ==== modify-param
 306 The Object Parameter Modification procedure allows the application to configure the values of the
 307 parameters of the objects identified by the Resource Model.
 308
 309 Default URL: http://localhost:8181/restconf/operations/ocp-service:modify-param-nb
 310
 311 ===== POST Input
 312
 313 [options="header",cols="1,1,2,2,1"]
 314 |=======
 315 |Field Name | Type | Description | Example | Required?
 316 | nodeId | String | Inventory node reference for OCP radio head | ocp:MTI-101-200 | Yes
 317 | objId | String | Object ID | RxSigPath_5G:1 | Yes
 318 | name | String | Object parameter name | dataLink | Yes
 319 | value | String | Object parameter value | dataLink:1 | Yes
 320 |=======
 321
 322 .Example
 323 ----
 324 {
 325     "modify-param-nb": {
 326         "input": {
 327             "nodeId": "ocp:MTI-101-200",
 328             "objId": "RxSigPath_5G:1",
 329             "param": [
 330                 {
 331                     "name": "dataLink",
 332                     "value": "dataLink:1"
 333                 }
 334             ]
 335         }
 336     }
 337 }
 338 ----
 339
 340 ===== POST Output
 341
 342 [options="header",cols="1,1,2"]
 343 |=======
 344 |Field Name | Type | Description
 345 | objId | String | Object ID
 346 | globResult | String, enumerated | Common default result codes + "FAIL_UNKNOWN_OBJECT", "FAIL_PARAMETER_FAIL",
 347   "FAIL_NOSUCH_RESOURCE"
 348 | name | String | Object parameter name
 349 | result | String, enumerated | "SUCCESS", "FAIL_UNKNOWN_PARAM", "FAIL_PARAM_READONLY", "FAIL_PARAM_LOCKREQUIRED",
 350   "FAIL_VALUE_OUTOF_RANGE", "FAIL_VALUE_TYPE_ERROR"
 351 |=======
 352
 353 .Example
 354 ----
 355 {
 356     "output": {
 357         "objId": "RxSigPath_5G:1",
 358         "globResult": "SUCCESS",
 359         "param": [
 360             {
 361                 "name": "dataLink",
 362                 "result": "SUCCESS"
 363             }
 364         ]
 365     }
 366 }
 367 ----
 368
 369 ==== create-obj
 370 The Object Creation procedure allows the application to create and initialize a new instance
 371 of the given object type on the RE.
 372
 373 Default URL: http://localhost:8181/restconf/operations/ocp-service:create-obj-nb
 374
 375 ===== POST Input
 376
 377 [options="header",cols="1,1,2,2,1"]
 378 |=======
 379 |Field Name | Type | Description | Example | Required?
 380 | nodeId | String | Inventory node reference for OCP radio head | ocp:MTI-101-200 | Yes
 381 | objType | String | Object type | RxSigPath_5G | Yes
 382 | name | String | Object parameter name | dataLink | No
 383 | value | String | Object parameter value | dataLink:1 | No
 384 |=======
 385
 386 .Example
 387 ----
 388 {
 389     "create-obj-nb": {
 390         "input": {
 391             "nodeId": "ocp:MTI-101-200",
 392             "objType": "RxSigPath_5G",
 393             "param": [
 394                 {
 395                     "name": "dataLink",
 396                     "value": "dataLink:1"
 397                 }
 398             ]
 399         }
 400     }
 401 }
 402 ----
 403
 404 ===== POST Output
 405
 406 [options="header",cols="1,1,2"]
 407 |=======
 408 |Field Name | Type | Description
 409 | objId | String | Object ID
 410 | globResult | String, enumerated | Common default result codes + "FAIL_UNKNOWN_OBJTYPE", "FAIL_STATIC_OBJTYPE",
 411   "FAIL_UNKNOWN_OBJECT", "FAIL_CHILD_NOTALLOWED", "FAIL_OUTOF_RESOURCES" "FAIL_PARAMETER_FAIL", "FAIL_NOSUCH_RESOURCE"
 412 | name | String | Object parameter name
 413 | result | String, enumerated | "SUCCESS", "FAIL_UNKNOWN_PARAM", "FAIL_PARAM_READONLY", "FAIL_PARAM_LOCKREQUIRED",
 414   "FAIL_VALUE_OUTOF_RANGE", "FAIL_VALUE_TYPE_ERROR"
 415 |=======
 416
 417 .Example
 418 ----
 419 {
 420     "output": {
 421         "objId": "RxSigPath_5G:0",
 422         "globResult": "SUCCESS",
 423         "param": [
 424             {
 425                 "name": "dataLink",
 426                 "result": "SUCCESS"
 427             }
 428         ]
 429     }
 430 }
 431 ----
 432
 433 ==== delete-obj
 434 The Object Deletion procedure allows the application to delete a given object instance and
 435 recursively its entire child objects on the RE.
 436
 437 Default URL: http://localhost:8181/restconf/operations/ocp-service:delete-obj-nb
 438
 439 ===== POST Input
 440
 441 [options="header",cols="1,1,2,2,1"]
 442 |=======
 443 |Field Name | Type | Description | Example | Required?
 444 | nodeId | String | Inventory node reference for OCP radio head | ocp:MTI-101-200 | Yes
 445 | objId | String | Object ID | RxSigPath_5G:1 | Yes
 446 |=======
 447
 448 .Example
 449 ----
 450 {
 451     "delete-obj-nb": {
 452         "input": {
 453             "nodeId": "ocp:MTI-101-200",
 454             "obj-id": "RxSigPath_5G:0"
 455         }
 456     }
 457 }
 458 ----
 459
 460 ===== POST Output
 461
 462 [options="header",cols="1,1,2"]
 463 |=======
 464 |Field Name | Type | Description
 465 | result | String, enumerated | Common default result codes + "FAIL_UNKNOWN_OBJECT",
 466   "FAIL_STATIC_OBJTYPE", "FAIL_LOCKREQUIRED"
 467 |=======
 468
 469 .Example
 470 ----
 471 {
 472     "output": {
 473         "result": "SUCCESS"
 474     }
 475 }
 476 ----
 477
 478 ==== get-state
 479 The Object State Reporting procedure allows the application to acquire the current state
 480 (for the requested state type) of one or more objects of the RE resource model, and
 481 additionally configure event-triggered reporting of the detected state changes for all
 482 state types of the indicated objects.
 483
 484 Default URL: http://localhost:8181/restconf/operations/ocp-service:get-state-nb
 485
 486 ===== POST Input
 487
 488 [options="header",cols="2,1,2,2,1"]
 489 |=======
 490 |Field Name | Type | Description | Example | Required?
 491 | nodeId | String | Inventory node reference for OCP radio head | ocp:MTI-101-200 | Yes
 492 | objId | String | Object ID | RxSigPath_5G:1 | Yes
 493 | stateType | String, enumerated | Valid values: "AST", "FST", "ALL" | ALL | Yes
 494 | eventDrivenReporting | Boolean | Event-triggered reporting of state change | true | Yes
 495 |=======
 496
 497 .Example
 498 ----
 499 {
 500     "get-state-nb": {
 501         "input": {
 502             "nodeId": "ocp:MTI-101-200",
 503             "objId": "antPort:0",
 504             "stateType": "ALL",
 505             "eventDrivenReporting": "true"
 506         }
 507     }
 508 }
 509 ----
 510
 511 ===== POST Output
 512
 513 [options="header",cols="1,1,2"]
 514 |=======
 515 |Field Name | Type | Description
 516 | id | String | Object ID
 517 | type | String, enumerated | State type. Valid values: "AST", "FST
 518 | value | String, enumerated | State value. Valid values: For state type = "AST": "LOCKED", "UNLOCKED".
 519   For state type = "FST": "PRE_OPERATIONAL", "OPERATIONAL", "DEGRADED", "FAILED", "NOT_OPERATIONAL", "DISABLED"
 520 | result | String, enumerated | Common default result codes + "FAIL_UNKNOWN_OBJECT", "FAIL_UNKNOWN_STATETYPE",
 521   "FAIL_VALUE_OUTOF_RANGE"
 522 |=======
 523
 524 .Example
 525 ----
 526 {
 527     "output": {
 528         "obj": [
 529             {
 530                 "id": "antPort:0",
 531                 "state": [
 532                     {
 533                         "type": "FST",
 534                         "value": "DISABLED"
 535                     },
 536                     {
 537                         "type": "AST",
 538                         "value": "LOCKED"
 539                     }
 540                 ]
 541             }
 542         ],
 543         "result": "SUCCESS"
 544     }
 545 }
 546 ----
 547
 548 ==== modify-state
 549 The Object State Modification procedure allows the application to trigger a change in the
 550 state of an object of the RE Resource Model.
 551
 552 Default URL: http://localhost:8181/restconf/operations/ocp-service:modify-state-nb
 553
 554 ===== POST Input
 555
 556 [options="header",cols="1,1,2,2,1"]
 557 |=======
 558 |Field Name | Type | Description | Example | Required?
 559 | nodeId | String | Inventory node reference for OCP radio head | ocp:MTI-101-200 | Yes
 560 | objId | String | Object ID | RxSigPath_5G:1 | Yes
 561 | stateType | String, enumerated | Valid values: "AST", "FST", "ALL" | AST | Yes
 562 | stateValue | String, enumerated | Valid values: For state type = "AST": "LOCKED", "UNLOCKED".
 563   For state type = "FST": "PRE_OPERATIONAL", "OPERATIONAL", "DEGRADED", "FAILED", "NOT_OPERATIONAL", "DISABLED" | LOCKED | Yes
 564 |=======
 565
 566 .Example
 567 ----
 568 {
 569     "modify-state-nb": {
 570         "input": {
 571             "nodeId": "ocp:MTI-101-200",
 572             "objId": "RxSigPath_5G:1",
 573             "stateType": "AST",
 574             "stateValue": "LOCKED"
 575         }
 576     }
 577 }
 578 ----
 579
 580 ===== POST Output
 581
 582 [options="header",cols="1,1,2"]
 583 |=======
 584 |Field Name | Type | Description
 585 | objId | String | Object ID
 586 | stateType | String, enumerated | State type. Valid values: "AST", "FST
 587 | stateValue | String, enumerated | State value. Valid values: For state type = "AST": "LOCKED", "UNLOCKED".
 588   For state type = "FST": "PRE_OPERATIONAL", "OPERATIONAL", "DEGRADED", "FAILED", "NOT_OPERATIONAL", "DISABLED"
 589 | result | String, enumerated | Common default result codes + "FAIL_UNKNOWN_OBJECT", "FAIL_UNKNOWN_STATETYPE",
 590 "FAIL_UNKNOWN_STATEVALUE", "FAIL_STATE_READONLY", "FAIL_RESOURCE_UNAVAILABLE", "FAIL_RESOURCE_INUSE",
 591 "FAIL_PARENT_CHILD_CONFLICT", "FAIL_PRECONDITION_NOTMET
 592 |=======
 593
 594 .Example
 595 ----
 596 {
 597     "output": {
 598         "objId": "RxSigPath_5G:1",
 599         "stateType": "AST",
 600         "stateValue": "LOCKED",
 601         "result": "SUCCESS",
 602     }
 603 }
 604 ----
 605
 606 ==== get-fault
 607 The Fault Reporting procedure allows the application to acquire information about all current
 608 active faults associated with a primary object, as well as configure the RE to report when the
 609 fault status changes for any of faults associated with the indicated primary object.
 610
 611 Default URL: http://localhost:8181/restconf/operations/ocp-service:get-fault-nb
 612
 613 ===== POST Input
 614
 615 [options="header",cols="1,1,2,2,1"]
 616 |=======
 617 |Field Name | Type | Description | Example | Required?
 618 | nodeId | String | Inventory node reference for OCP radio head | ocp:MTI-101-200 | Yes
 619 | objId | String | Object ID | RE:0 | Yes
 620 | eventDrivenReporting | Boolean | Event-triggered reporting of fault | true | Yes
 621 |=======
 622
 623 .Example
 624 ----
 625 {
 626     "get-fault-nb": {
 627         "input": {
 628             "nodeId": "ocp:MTI-101-200",
 629             "objId": "RE:0",
 630             "eventDrivenReporting": "true"
 631         }
 632     }
 633 }
 634 ----
 635
 636 ===== POST Output
 637
 638 [options="header",cols="1,1,2"]
 639 |=======
 640 |Field Name | Type | Description
 641 | result | String, enumerated | Common default result codes + "FAIL_UNKNOWN_OBJECT", "FAIL_VALUE_OUTOF_RANGE"
 642 | id (obj) | String | Object ID
 643 | id (fault) | String | Fault ID
 644 | severity | String | Fault severity
 645 | timestamp | dateTime | Time stamp
 646 | descr | String | Text description
 647 | affectedObj | String | Affected object
 648 |=======
 649
 650 .Example
 651 ----
 652 {
 653     "output": {
 654         "result": "SUCCESS",
 655         "obj": [
 656             {
 657                 "id": "RE:0",
 658                 "fault": [
 659                     {
 660                         "id": "FAULT_OVERTEMP",
 661                         "severity": "DEGRADED",
 662                         "timestamp": "2012-02-12T16:35:00",
 663                         "descr": "PA temp too high; Pout reduced",
 664                         "affectedObj": [
 665                             "TxSigPath_EUTRA:0",
 666                             "TxSigPath_EUTRA:1"
 667                         ]
 668                     },
 669                     {
 670                         "id": "FAULT_VSWR_OUTOF_RANGE",
 671                         "severity": "WARNING",
 672                         "timestamp": "2012-02-12T16:01:05",
 673                     }
 674                 ]
 675             }
 676         ],
 677     }
 678 }
 679 ----
 680
 681 NOTE:
 682 The northbound APIs described above wrap the southbound APIs to make them accessible to external applications
 683 via RESTCONF, as well as take care of synchronizing the RE resource model between radio heads and the controller's
 684 datastore. See applications/ocp-service/src/main/yang/ocp-resourcemodel.yang for the yang representation of the RE
 685 resource model.
 686
 687 === Java Interfaces (Southbound APIs)
 688 The southbound APIs provide concrete implementation of the following OCP elementary functions:  health-check,
 689 set-time, re-reset, get-param, modify-param, create-obj, delete-obj, get-state, modify-state and get-fault.
 690 Any OpenDaylight services/applications (of course, including OCP service) wanting to speak OCP to radio heads will
 691 need to use them.
 692
 693 ==== SalDeviceMgmtService
 694 Interface SalDeviceMgmtService defines three methods corresponding to health-check, set-time and re-reset.
 695
 696 .SalDeviceMgmtService.java
 697 ----
 698 package org.opendaylight.yang.gen.v1.urn.opendaylight.ocp.device.mgmt.rev150811;
 699
 700 public interface SalDeviceMgmtService
 701     extends
 702     RpcService
 703 {
 704
 705     Future<RpcResult<HealthCheckOutput>> healthCheck(HealthCheckInput input);
 706
 707     Future<RpcResult<SetTimeOutput>> setTime(SetTimeInput input);
 708
 709     Future<RpcResult<ReResetOutput>> reReset(ReResetInput input);
 710
 711 }
 712 ----
 713
 714 ==== SalConfigMgmtService
 715 Interface SalConfigMgmtService defines two methods corresponding to get-param and modify-param.
 716
 717 .SalConfigMgmtService.java
 718 ----
 719 package org.opendaylight.yang.gen.v1.urn.opendaylight.ocp.config.mgmt.rev150811;
 720
 721 public interface SalConfigMgmtService
 722     extends
 723     RpcService
 724 {
 725
 726     Future<RpcResult<GetParamOutput>> getParam(GetParamInput input);
 727
 728     Future<RpcResult<ModifyParamOutput>> modifyParam(ModifyParamInput input);
 729
 730 }
 731 ----
 732
 733 ==== SalObjectLifecycleService
 734 Interface SalObjectLifecycleService defines two methods corresponding to create-obj and delete-obj.
 735
 736 .SalObjectLifecycleService.java
 737 ----
 738 package org.opendaylight.yang.gen.v1.urn.opendaylight.ocp.object.lifecycle.rev150811;
 739
 740 public interface SalObjectLifecycleService
 741     extends
 742     RpcService
 743 {
 744
 745     Future<RpcResult<CreateObjOutput>> createObj(CreateObjInput input);
 746
 747     Future<RpcResult<DeleteObjOutput>> deleteObj(DeleteObjInput input);
 748
 749 }
 750 ----
 751
 752 ==== SalObjectStateMgmtService
 753 Interface SalObjectStateMgmtService defines two methods corresponding to get-state and modify-state.
 754
 755 .SalObjectStateMgmtService.java
 756 ----
 757 package org.opendaylight.yang.gen.v1.urn.opendaylight.ocp.object.state.mgmt.rev150811;
 758
 759 public interface SalObjectStateMgmtService
 760     extends
 761     RpcService
 762 {
 763
 764     Future<RpcResult<GetStateOutput>> getState(GetStateInput input);
 765
 766     Future<RpcResult<ModifyStateOutput>> modifyState(ModifyStateInput input);
 767
 768 }
 769 ----
 770
 771 ==== SalFaultMgmtService
 772 Interface SalFaultMgmtService defines only one method corresponding to get-fault.
 773
 774 .SalFaultMgmtService.java
 775 ----
 776 package org.opendaylight.yang.gen.v1.urn.opendaylight.ocp.fault.mgmt.rev150811;
 777
 778 public interface SalFaultMgmtService
 779     extends
 780     RpcService
 781 {
 782
 783     Future<RpcResult<GetFaultOutput>> getFault(GetFaultInput input);
 784
 785 }
 786 ----
 787
 788 === Notifications
 789 In addition to indication messages, the OCP southbound plugin will translate specific events
 790 (e.g., connect, disconnect) coming up from the OCP protocol library into MD-SAL Notification
 791 objects and then publish them to the MD-SAL. Also, the OCP service will notify the completion
 792 of certain operation via Notification as well.
 793
 794 ==== SalDeviceMgmtListener
 795 An onDeviceConnected Notification will be published to the MD-SAL as soon as a
 796 radio head is connected to the controller, and when that radio head is disconnected
 797 the OCP southbound plugin will publish an onDeviceDisconnected Notification in response
 798 to the disconnect event propagated from the OCP protocol library.
 799
 800 .SalDeviceMgmtListener.java
 801 ----
 802 package org.opendaylight.yang.gen.v1.urn.opendaylight.ocp.device.mgmt.rev150811;
 803
 804 public interface SalDeviceMgmtListener
 805     extends
 806     NotificationListener
 807 {
 808
 809     void onDeviceConnected(DeviceConnected notification);
 810
 811     void onDeviceDisconnected(DeviceDisconnected notification);
 812
 813 }
 814 ----
 815
 816 ==== OcpServiceListener
 817 The OCP service will publish an onAlignmentCompleted Notification to the MD-SAL once
 818 it has completed the OCP alignment procedure with the radio head.
 819
 820 .OcpServiceListener.java
 821 ----
 822 package org.opendaylight.yang.gen.v1.urn.opendaylight.params.xml.ns.yang.ocp.applications.ocp.service.rev150811;
 823
 824 public interface OcpServiceListener
 825     extends
 826     NotificationListener
 827 {
 828
 829     void onAlignmentCompleted(AlignmentCompleted notification);
 830
 831 }
 832 ----
 833
 834 ==== SalObjectStateMgmtListener
 835 When receiving a state change indication message, the OCP southbound plugin will propagate
 836 the indication message to upper layer services/applications by publishing a corresponding
 837 onStateChangeInd Notification to the MD-SAL.
 838
 839 .SalObjectStateMgmtListener.java
 840 ----
 841 package org.opendaylight.yang.gen.v1.urn.opendaylight.ocp.object.state.mgmt.rev150811;
 842
 843 public interface SalObjectStateMgmtListener
 844     extends
 845     NotificationListener
 846 {
 847
 848     void onStateChangeInd(StateChangeInd notification);
 849
 850 }
 851 ----
 852
 853 ==== SalFaultMgmtListener
 854 When receiving a fault indication message, the OCP southbound plugin will propagate
 855 the indication message to upper layer services/applications by publishing a corresponding
 856 onFaultInd Notification to the MD-SAL.
 857
 858 .SalFaultMgmtListener.java
 859 ----
 860 package org.opendaylight.yang.gen.v1.urn.opendaylight.ocp.fault.mgmt.rev150811;
 861
 862 public interface SalFaultMgmtListener
 863     extends
 864     NotificationListener
 865 {
 866
 867     void onFaultInd(FaultInd notification);
 868
 869 }
 870 ----